fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

f.write_str(&self.msg)

}

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

f.write_str(&self.msg)

}

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

f.write_str(&self.msg)

}

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

f.write_str(&self.msg)

}

pub msg: String,

/// Plan operation name (e.g. `"doc.update"`, `"doc.delete_where"`).

pub suggested_op: &'static str,

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

f.write_str(&self.msg)

}

err.chain().any(|cause| {

cause.downcast_ref::<InvalidInputError>().is_some()

|| cause.downcast_ref::<InvalidInputHintError>().is_some()

})

err.chain().find_map(|cause| {

cause

.downcast_ref::<InvalidInputHintError>()

.map(|e| e.suggested_op)

})

err.chain().any(|cause| {

cause

.downcast_ref::<std::io::Error>()

.is_some_and(|e| e.kind() == std::io::ErrorKind::NotFound)

})

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

f.write_str(&self.msg)

}

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

f.write_str(&self.msg)

}

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

f.write_str(&self.msg)

}

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

f.write_str(&self.msg)

}

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

f.write_str(&self.msg)

}

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

f.write_str(&self.msg)

}

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

f.write_str(&self.msg)

}

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

f.write_str(&self.msg)

}

pub msg: String,

/// Backup session created for the write that preceded format failure.

pub backup_session: Option<String>,

/// Paths already written before format failed (#1795). Agents need this

/// without re-reading disk or parsing English `error` text.

pub written_files: Vec<String>,

/// Format failure without a known backup session.

#[must_use]

pub fn new(msg: impl Into<String>) -> Self {

Self {

msg: msg.into(),

backup_session: None,

written_files: Vec::new(),

}

}

/// Attach a backup session (files already on disk; agent can `undo`).

#[must_use]

pub fn with_backup_session(mut self, session: Option<String>) -> Self {

self.backup_session = session.filter(|s| !s.is_empty());

self

}

/// Paths that were committed before the format hook failed.

#[must_use]

pub fn with_written_files(mut self, files: Vec<String>) -> Self {

self.written_files = files;

self

}

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

match &self.backup_session {

Some(ts) => write!(

f,

"{} (backup session {ts}; run `patchloom undo` to restore)",

self.msg

),

None => f.write_str(&self.msg),

}

}

err.chain().find_map(|cause| {

cause

.downcast_ref::<FormatFailedError>()

.and_then(|f| f.backup_session.as_deref())

})

err.chain()

.find_map(|cause| {

cause

.downcast_ref::<FormatFailedError>()

.map(|f| f.written_files.clone())

})

.unwrap_or_default()

/// Finalized backup session id (same shape as [`FormatFailedError::backup_session`]).

pub session: String,

/// `true` when `restore_session` succeeded after the mutation failure.

pub restored: bool,

/// Present when restore failed; human-readable restore error.

pub restore_err: Option<String>,

/// Display of the original mutation error (kept for diagnostics).

pub mutation_msg: String,

/// Build a restored-session error (undo still available).

#[must_use]

pub fn restored(session: impl Into<String>, mutation_msg: impl Into<String>) -> Self {

Self {

session: session.into(),

restored: true,

restore_err: None,

mutation_msg: mutation_msg.into(),

}

}

/// Build a restore-failed error (disk may still be half-applied).

#[must_use]

pub fn restore_failed(

session: impl Into<String>,

restore_err: impl Into<String>,

mutation_msg: impl Into<String>,

) -> Self {

Self {

session: session.into(),

restored: false,

restore_err: Some(restore_err.into()),

mutation_msg: mutation_msg.into(),

}

}

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

match (self.restored, &self.restore_err) {

(true, _) => write!(

f,

"mutation failed after backup finalize; restored session {} (undo still available): {}",

self.session, self.mutation_msg

),

(false, Some(re)) => write!(

f,

"mutation failed after backup finalize; restore of session {} also failed: {re}: {}",

self.session, self.mutation_msg

),

(false, None) => write!(

f,

"mutation failed after backup finalize; restore of session {} also failed: {}",

self.session, self.mutation_msg

),

}

}

err.chain().find_map(|cause| {

cause

.downcast_ref::<MutationAfterBackupError>()

.map(|e| e.session.as_str())

})

err.chain().any(|cause| {

cause

.downcast_ref::<std::io::Error>()

.is_some_and(|e| e.kind() == std::io::ErrorKind::IsADirectory)

})

let top = err.to_string();

let mut complete = true;

for cause in err.chain().skip(1) {

let c = cause.to_string();

if !c.is_empty() && !top.contains(&c) {

complete = false;

break;

}

}

if complete { top } else { format!("{err:#}") }

let (kind, code) = match classify_typed_error(err) {

Some((k, c)) => (Some(k), c),

None => (None, FAILURE),

};

let mut output = serde_json::json!({

"ok": false,

"error": agent_error_message(err)

});

if let Some(k) = kind {

output["error_kind"] = serde_json::Value::String(k.to_string());

}

// Predicate/wildcard write-nav fail-closed (#2133): machine-stable op hint.

if let Some(op) = suggested_op_from_error(err) {

output["suggested_op"] = serde_json::Value::String(op.to_string());

}

// FormatFailed and MutationAfterBackup (#2127 residual CLI JSON parity).

if let Some(bs) = backup_session_from_error(err) {

output["backup_session"] = serde_json::Value::String(bs.to_string());

}

let written = format_failed_written_files(err);

// Write landed only when format_failed lists paths or carries a session.

// MutationAfterBackup also has a session, but that is persist-fail after

// backup (Windows readonly / sharing lock): disk is original or restored,

// so a session id must not imply applied:true.

let write_landed = !written.is_empty() || format_failed_backup_session(err).is_some();

if write_landed {

// Canonical with other mutators (#1831 / #1788): agents branch on

// `applied`. Keep `write_applied` as a deprecated alias for one release.

output["applied"] = serde_json::Value::Bool(true);

output["write_applied"] = serde_json::Value::Bool(true);

if !written.is_empty() {

output["files_changed"] = serde_json::Value::Number(written.len().into());

output["files"] = serde_json::Value::Array(

written

.into_iter()

.map(|path| serde_json::json!({ "path": path }))

.collect(),

);

}

} else if kind.is_some_and(error_kind_implies_not_applied)

|| matches!(kind, Some("format_failed"))

{

// Pre-write failures never mutate disk (#1835): agents branch on

// `applied` alone. Also cover not_found / already_exists / parse_error

// (CLI emit_error_json_kind parity). format_failed with no write

// evidence is applied:false.

output["applied"] = serde_json::Value::Bool(false);

}

(output, code)

matches!(

kind,

"no_matches"

| "ambiguous"

| "invalid_input"

| "binary"

| "invalid_encoding"

| "guard_rejected"

| "not_found"

| "already_exists"

| "type_error"

| "conflicts"

| "parse_error"

| "parse_timeout"

| "changes_detected"

| "fuzzy_span_suspicious"

| "stale"

| "rollback"

| "rollback_failed"

)

if is_stale(err) {

Some(("stale", FAILURE))

} else if is_no_match(err) {

Some(("no_matches", NO_MATCHES))

} else if is_ambiguous(err) {

Some(("ambiguous", AMBIGUOUS))

} else if is_binary(err) {

Some(("binary", FAILURE))

} else if is_invalid_encoding(err) {

Some(("invalid_encoding", FAILURE))

} else if is_invalid_input(err) {

Some(("invalid_input", FAILURE))

} else if is_io_not_found(err) {

Some(("not_found", FAILURE))

} else if is_io_is_a_directory(err) {

// Path exists but is a directory (or non-file). Not not_found: agents

// must not retry as create; use invalid_input like API file ops.

Some(("invalid_input", FAILURE))

} else if is_already_exists(err) {

Some(("already_exists", FAILURE))

} else if is_type_error(err) {

Some(("type_error", FAILURE))

} else if is_conflicts(err) {

Some(("conflicts", CONFLICTS))

} else if is_parse_timeout(err) {

Some(("parse_timeout", PARSE_ERROR))

} else if is_parse_error(err) {

Some(("parse_error", PARSE_ERROR))

} else if is_changes_detected(err) {

Some(("changes_detected", CHANGES_DETECTED))

} else if is_format_failed(err) {

Some(("format_failed", FAILURE))

} else if let Some(m) = err

.chain()

.find_map(|c| c.downcast_ref::<MutationAfterBackupError>())

{

// Persist failed after backup finalize. `restored` means disk is

// back to the pre-write bytes (exit 7). `restore_failed` means

// undo did not complete (exit 1). Neither is a successful apply.

if m.restored {

Some(("rollback", ROLLBACK))

} else {

Some(("rollback_failed", FAILURE))

}

} else if let Some(edit) = err

.chain()

.find_map(|c| c.downcast_ref::<crate::fallback::EditError>())

{

// Library/engine PathGuard and other EditError-only kinds (#1935).

// Keep exit-typed arms above so already_exists / type_error stay distinct

// when both layers appear in a chain. EditErrorKind now peels the same

// honesty kinds for library hosts (#1947 / #1963).

use crate::fallback::EditErrorKind;

match edit.kind {

EditErrorKind::GuardRejected => Some(("guard_rejected", FAILURE)),

EditErrorKind::NoMatch => Some(("no_matches", NO_MATCHES)),

EditErrorKind::AmbiguousTarget => Some(("ambiguous", AMBIGUOUS)),

EditErrorKind::InvalidInput => Some(("invalid_input", FAILURE)),

EditErrorKind::Binary => Some(("binary", FAILURE)),

EditErrorKind::InvalidEncoding => Some(("invalid_encoding", FAILURE)),

EditErrorKind::FuzzySpanSuspicious => Some(("fuzzy_span_suspicious", FAILURE)),

EditErrorKind::TypeError => Some(("type_error", FAILURE)),

EditErrorKind::AlreadyExists => Some(("already_exists", FAILURE)),

EditErrorKind::NotFound => Some(("not_found", FAILURE)),

EditErrorKind::Conflicts => Some(("conflicts", CONFLICTS)),

EditErrorKind::ChangesDetected => Some(("changes_detected", CHANGES_DETECTED)),

EditErrorKind::ParseError => Some(("parse_error", PARSE_ERROR)),

EditErrorKind::ParseTimeout => Some(("parse_timeout", PARSE_ERROR)),

EditErrorKind::FormatFailed => Some(("format_failed", FAILURE)),

EditErrorKind::SyntaxInvalid

| EditErrorKind::ConflictingEdit

| EditErrorKind::OperationFailed => Some(("operation_failed", OPERATION_FAILED)),

}

} else {

None

}

use super::*;

#[test]

fn classify_typed_error_maps_format_failed() {

let err: anyhow::Error = FormatFailedError::new("format command failed").into();

let wrapped = err.context("files were written but formatting failed");

assert_eq!(

classify_typed_error(&wrapped),

Some(("format_failed", FAILURE))

);

}

#[test]

fn structured_error_payload_includes_suggested_op_from_hint() {

let err: anyhow::Error = InvalidInputHintError {

msg: "selector uses wildcard/predicate".into(),

suggested_op: "doc.update",

}

.into();

let wrapped = err.context("operation 1 (doc.set) failed");

assert!(is_invalid_input(&wrapped));

assert_eq!(suggested_op_from_error(&wrapped), Some("doc.update"));

assert_eq!(

classify_typed_error(&wrapped),

Some(("invalid_input", FAILURE))

);

let (payload, code) = structured_error_payload(&wrapped);

assert_eq!(code, FAILURE);

assert_eq!(payload["error_kind"], "invalid_input");

assert_eq!(payload["suggested_op"], "doc.update");

assert_eq!(payload["applied"], false);

assert_eq!(payload["ok"], false);

}

#[test]

fn plain_invalid_input_has_no_suggested_op() {

let err: anyhow::Error = InvalidInputError {

msg: "empty selector".into(),

}

.into();

assert_eq!(suggested_op_from_error(&err), None);

let (payload, _) = structured_error_payload(&err);

assert!(

payload.get("suggested_op").is_none(),

"plain invalid_input must not invent suggested_op: {payload}"

);

}

#[test]

fn backup_session_from_error_peels_format_failed() {

let err: anyhow::Error = FormatFailedError::new("format command failed (false)")

.with_backup_session(Some("99_0".into()))

.into();

assert_eq!(backup_session_from_error(&err), Some("99_0"));

assert_eq!(format_failed_backup_session(&err), Some("99_0"));

}

#[test]

fn backup_session_from_error_peels_mutation_after_backup() {

// Root via Into (not .context): anyhow context layers are not downcastable.

let err: anyhow::Error = MutationAfterBackupError::restored("42_1", "disk full").into();

assert_eq!(backup_session_from_error(&err), Some("42_1"));

assert_eq!(mutation_after_backup_session(&err), Some("42_1"));

let msg = err.to_string();

assert!(

msg.contains("restored session 42_1"),

"Display stays human-readable: {msg}"

);

assert!(

msg.contains("disk full"),

"mutation detail must remain visible: {msg}"

);

}

#[test]

fn backup_session_from_error_peels_restore_failed() {

let err: anyhow::Error =

MutationAfterBackupError::restore_failed("7_0", "permission denied", "write failed")

.into();

assert_eq!(backup_session_from_error(&err), Some("7_0"));

let msg = err.to_string();

assert!(

msg.contains("restore of session 7_0"),

"Display keeps restore-failed wording: {msg}"

);

assert!(msg.contains("write failed"), "mutation detail: {msg}");

}

#[test]

fn backup_session_from_error_none_for_plain_no_match_and_guard() {

let no_match: anyhow::Error = NoMatchError {

msg: "no matches for old".into(),

}

.into();

assert_eq!(backup_session_from_error(&no_match), None);

let guard: anyhow::Error = crate::fallback::EditError::new(

crate::fallback::EditErrorKind::GuardRejected,

"path outside workspace",

)

.into();

assert_eq!(backup_session_from_error(&guard), None);

let plain = anyhow::anyhow!("something went wrong");

assert_eq!(backup_session_from_error(&plain), None);

}

#[test]

fn backup_session_from_error_prefers_format_failed_when_both_in_chain() {

// FormatFailed is the primary post-write path; prefer it if both appear.

let fmt: anyhow::Error = FormatFailedError::new("fmt")

.with_backup_session(Some("fmt_sess".into()))

.into();

// Simulate outer wrap that still peels FormatFailed via chain.

let wrapped = fmt.context("post-write hooks failed");

assert_eq!(backup_session_from_error(&wrapped), Some("fmt_sess"));

}

#[test]

fn backup_session_from_error_peels_mutation_under_outer_context() {

// Root typed error + outer Display context (CLI remappers often wrap).