agentflow-proof 1.2.0__tar.gz → 1.2.1__tar.gz

{agentflow_proof-1.2.0 → agentflow_proof-1.2.1}/CHANGELOG.md

@@ -7,6 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.1] - 2026-11-02
+
+Agentflow 1.2.1 fixes three cases where `next-action` sent an agent the wrong
+way. It no longer asks a step to record a file again when the file already has
+a matching receipt from another step or attempt (#97). It guides an edit made
+after a step completed to `amend-step` instead of a `finish-run` that always
+fails (#73). It reports a ledger change only when a fresh read of the ledgers
+shows one, so a deterministic bug no longer looks like a race (#94). No state,
+recovery action, artifact schema, schema-version constant,
+`docs/cli-contract.json` value or exit-code change.
+
+### Fixed
+
+- `next-action` no longer asks a step to record a changed file that already has
+  a matching receipt. A file in the step's scope counts as recorded when its
+  latest file receipt, from any step or attempt, matches the file as it is now
+  (a deleted file needs a deleted receipt), the check `verify-run` makes. It
+  used to require a receipt from the open attempt itself. When two steps
+  listed the same file, following it copied the first step's hunks into a new
+  receipt and made the second step the file's latest owner in the proof, and
+  an amendment had to record again files its step had already recorded. A
+  file the open attempt recorded and then edited again is now
+  `file_receipts_missing`; `next-action` used to send it to `finish-step`, and
+  `finish-run` then failed. Enforced hunk attribution also requires the
+  current hunks to be recorded, even when the content hash still matches
+  after a staged rename or file type change. Working-tree inspection errors
+  return blocking `state_invalid` diagnostics instead of a traceback. No
+  state, recovery action, schema or exit-code change. (#97)
+- `next-action` guides an edit made after a step completed to `amend-step`
+  instead of a `finish-run` that always fails. When every changed file with no
+  matching receipt is in exactly one step's effective scope and drift reports
+  no out-of-scope or blocked file, it reports `step_amendment_needed` with
+  `amend-step <step> --reason 'record post-completion edit to <path>'`. The
+  `amend` action is `automatic: false` while any changed file lacks a matching
+  receipt, for timeout, failed and strict amendments too, because receipts
+  cannot show who made the edit. Otherwise `drift_failing` and `run_unverified`
+  name each path and the step that could record it. `drift_failing` now lists
+  blocked files and unmapped hunks (path, header and fingerprint) as well as
+  out-of-scope files, and its reason names the categories present; it used to
+  say "changes fall outside plan scope" with no diagnostics for an unmapped
+  hunk. `record-file-change`, `run` and `verify-step` on a completed step with
+  no open attempt say to open one with `amend-step` instead of `claim-step`. A
+  git or file error while inspecting changed files reports `state_invalid`. No
+  state, recovery action, schema or exit-code change. (#73)
+- `next-action` reports "execution ledgers changed during next-action; run it
+  again" only when the ledgers really changed. When a check after the
+  validated snapshot raises, `next-action` reads the step, command, file
+  receipt and verification ledgers again. It reports `state_invalid` only if
+  they differ from the snapshot or cannot be read; otherwise the original
+  error propagates with its traceback. It used to report any `AttributeError`,
+  `KeyError`, `TypeError`, `OSError` or `ValueError` raised while choosing the
+  action as a ledger change, on the claim path too, so a deterministic bug
+  looked like a race and the rerun it asked for gave the same answer every
+  time. (#94)
+
 ## [1.2.0] - 2026-10-29
 
 Agentflow 1.2.0 shows why a run is stuck. `next-step --explain` reports why
@@ -347,7 +402,8 @@ repository, so this heading is intentionally unlinked._
 
 - Existing v0.2 proof artifacts remain valid when no execution contract exists.
 
-[Unreleased]: https://github.com/kstruzzieri/agentflow/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/kstruzzieri/agentflow/compare/v1.2.1...HEAD
+[1.2.1]: https://github.com/kstruzzieri/agentflow/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/kstruzzieri/agentflow/compare/v1.1.1...v1.2.0
 [1.1.1]: https://github.com/kstruzzieri/agentflow/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/kstruzzieri/agentflow/compare/v1.0.0...v1.1.0

{agentflow_proof-1.2.0/src/agentflow_proof.egg-info → agentflow_proof-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentflow-proof
-Version: 1.2.0
+Version: 1.2.1
 Summary: A model-agnostic workflow runner for drift-resistant agentic development.
 Author: Agentflow contributors
 License-Expression: MIT

{agentflow_proof-1.2.0 → agentflow_proof-1.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentflow-proof"
-version = "1.2.0"
+version = "1.2.1"
 description = "A model-agnostic workflow runner for drift-resistant agentic development."
 readme = "README.md"
 requires-python = ">=3.11"

{agentflow_proof-1.2.0 → agentflow_proof-1.2.1}/src/agentflow/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "1.2.0"
+__version__ = "1.2.1"

{agentflow_proof-1.2.0 → agentflow_proof-1.2.1}/src/agentflow/cli.py

@@ -47,6 +47,7 @@ from .execution_coverage import verify_run, verify_step
 from .events import filter_events_since, project_events, valid_since
 from .capabilities import append_capability_receipt, build_capability_receipt
 from .handoff import export_handoff, lint_handoff_text
+from .hunks import format_unmapped_hunk
 from . import porcelain
 from .locks import file_lock
 from .packs import (
@@ -639,11 +640,7 @@ def command_audit_drift(args: argparse.Namespace) -> int:
         hunk_lines = []
         for entry in report["unmapped_hunks"]:
             if isinstance(entry, dict):
-                hunk_lines.append(
-                    f"- {entry['path']} @@ -{entry['old_start']},{entry['old_count']} "
-                    f"+{entry['new_start']},{entry['new_count']} @@ "
-                    f"{entry['hash'][:12]} ({entry['reason']})"
-                )
+                hunk_lines.append(f"- {format_unmapped_hunk(entry)}")
             else:
                 hunk_lines.append(f"- {entry}")
         print_lines([_terminal_safe(line) for line in hunk_lines])

{agentflow_proof-1.2.0 → agentflow_proof-1.2.1}/src/agentflow/execution.py

@@ -604,6 +604,9 @@ def resolve_attempt(root: Path, step_id: str, attempt_id: Optional[str]) -> str:
         return open_attempts[0]
     if len(open_attempts) > 1:
         raise ValueError(f"multiple open attempts for {step_id}; pass --attempt")
+    if state["steps"].get(step_id, {}).get("completed"):
+        # #73: claim-step refuses a completed step, so point at the command that works.
+        raise ValueError(f"step {step_id} has completed work and no open attempt; open one with amend-step")
     raise ValueError(f"{step_id} has no open attempt; run claim-step first")
 
 

{agentflow_proof-1.2.0 → agentflow_proof-1.2.1}/src/agentflow/execution_coverage.py

@@ -21,7 +21,7 @@ from .execution import (
     receipt_timed_out,
     resolve_attempt,
 )
-from .git import changed_file_records
+from .git import changed_file_records, is_git_repo
 from .hunks import effective_hunk_policy, unmapped_hunks
 from .receipts import (
     command_receipts,
@@ -381,7 +381,7 @@ def _ignored(path: str, prefixes: List[str]) -> bool:
     return any(path.startswith(prefix) for prefix in prefixes)
 
 
-def _latest_file_receipts_by_path(root: Path) -> Dict[str, Dict[str, Any]]:
+def latest_file_receipts_by_path(root: Path) -> Dict[str, Dict[str, Any]]:
     latest: Dict[str, Dict[str, Any]] = {}
     for receipt in file_receipts(root):
         path = receipt.get("path")
@@ -390,11 +390,30 @@ def _latest_file_receipts_by_path(root: Path) -> Dict[str, Dict[str, Any]]:
     return latest
 
 
+def receipt_matches_worktree(root: Path, record: Dict[str, str], receipt: Dict[str, Any]) -> bool:
+    """True when receipt records record's changed path as it is now.
+
+    verify-run and next-action (#97) share this check.
+    """
+    if record["change_kind"] == "deleted":
+        return receipt.get("change_kind") == "deleted"
+    return receipt.get("after_sha256") == sha256_path(root / record["path"])
+
+
 def _reconcile_changed_files(
     root: Path,
     plan: Dict[str, Any],
     require_file_receipts: bool = True,
 ) -> List[Dict[str, str]]:
+    return [finding for _path, finding in _changed_file_pairs(root, plan, require_file_receipts)]
+
+
+def _changed_file_pairs(
+    root: Path,
+    plan: Dict[str, Any],
+    require_file_receipts: bool = True,
+) -> List[Tuple[str, Dict[str, str]]]:
+    """(path, finding) for each changed file verify-run flags (#73 needs the path)."""
     contract: Dict[str, Any] = {}
     contract_path = root / ".agent/execution.contract.json"
     if contract_path.exists():
@@ -405,8 +424,8 @@ def _reconcile_changed_files(
         if contract is None:
             contract = {}
     ignore = contract.get("concurrency", {}).get("reconcile_ignore", [".agent/", ".git/"])
-    latest = _latest_file_receipts_by_path(root)
-    findings: List[Dict[str, str]] = []
+    latest = latest_file_receipts_by_path(root)
+    findings: List[Tuple[str, Dict[str, str]]] = []
     for record in changed_file_records(root):
         path = record["path"]
         if _ignored(path, ignore):
@@ -415,25 +434,19 @@ def _reconcile_changed_files(
         if receipt is None:
             if not require_file_receipts:
                 continue
-            findings.append(
-                {
-                    "severity": "error",
-                    "message": f"changed file is not mapped to a step receipt: {path}",
-                }
-            )
+            findings.append((path, {
+                "severity": "error",
+                "message": f"changed file is not mapped to a step receipt: {path}",
+            }))
             continue
-        if record["change_kind"] == "deleted":
-            if receipt.get("change_kind") != "deleted":
-                findings.append(
-                    {"severity": "error", "message": f"deleted file lacks deleted receipt: {path}"}
-                )
+        if receipt_matches_worktree(root, record, receipt):
             continue
-        expected_hash = receipt.get("after_sha256")
-        actual_hash = sha256_path(root / path)
-        if expected_hash != actual_hash:
-            findings.append(
-                {"severity": "error", "message": f"out-of-band edit after latest file receipt: {path}"}
-            )
+        message = (
+            f"deleted file lacks deleted receipt: {path}"
+            if record["change_kind"] == "deleted"
+            else f"out-of-band edit after latest file receipt: {path}"
+        )
+        findings.append((path, {"severity": "error", "message": message}))
     if effective_hunk_policy(root) == "enforce":
         # Scope-filter candidates the same way audit_drift does, so verify-run
         # and audit-drift cannot diverge on which paths are hunk-checked.
@@ -447,16 +460,14 @@ def _reconcile_changed_files(
             and not matches_path(record["path"], blocked)
         ]
         for entry in unmapped_hunks(root, candidates):
-            findings.append(
-                {
-                    "severity": "error",
-                    "message": (
-                        f"unmapped hunk in {entry['path']} "
-                        f"(@@ -{entry['old_start']},{entry['old_count']} "
-                        f"+{entry['new_start']},{entry['new_count']} @@): no matching file receipt"
-                    ),
-                }
-            )
+            findings.append((entry["path"], {
+                "severity": "error",
+                "message": (
+                    f"unmapped hunk in {entry['path']} "
+                    f"(@@ -{entry['old_start']},{entry['old_count']} "
+                    f"+{entry['new_start']},{entry['new_count']} @@): no matching file receipt"
+                ),
+            }))
     return findings
 
 
@@ -672,15 +683,25 @@ def _timeout_receipt_findings(
 
 
 def replacement_needs(
-    root: Path, plan: Dict[str, Any], strict: bool = False
+    root: Path,
+    plan: Dict[str, Any],
+    strict: bool = False,
+    edits: Optional[Dict[str, Any]] = None,
 ) -> List[Dict[str, Any]]:
     """Plan-order completed steps that need a replacement attempt, with causes.
 
     Mirrors the verify_run errors a replacement attempt would clear: a
     recoverable timed-out receipt, a failed latest attempt, and (effective
     strict) a latest attempt that is not completed. attempt_id/status are the
-    step's latest non-lease ledger event.
+    step's latest non-lease ledger event. #73: when post_completion_edits
+    offers them, each unreceipted change is a post_completion_edit cause on
+    its one candidate step, after that step's other causes.
     """
+    edit_causes: Dict[str, List[Dict[str, Any]]] = {}
+    if edits and edits.get("offered"):
+        for pair in edits["pairs"]:
+            [owner] = edits["candidates"][pair["path"]]
+            edit_causes.setdefault(owner, []).append({"cause": "post_completion_edit", **pair})
     effective_strict = strict or bool(_proof_policy(root).get("strict_by_default"))
     state = read_step_state(root)
     latest: Dict[str, Dict[str, Any]] = {}
@@ -716,6 +737,7 @@ def replacement_needs(
             causes.append({"cause": "failed_attempt"})
         if effective_strict and status != "completed":
             causes.append({"cause": "strict_incomplete"})
+        causes.extend(edit_causes.get(step_id, []))
         if causes:
             needs.append({
                 "step_id": step_id,
@@ -726,6 +748,64 @@ def replacement_needs(
     return needs
 
 
+def _requires_file_receipts(root: Path, strict: bool) -> bool:
+    policy = _proof_policy(root)
+    return (
+        strict
+        or bool(policy.get("strict_by_default"))
+        or bool(policy.get("require_file_receipts_for_changed_files", True))
+    )
+
+
+def post_completion_edits(
+    root: Path, plan: Dict[str, Any], strict: bool = False
+) -> Dict[str, Any]:
+    """#73: changed files verify-run flags, and whether one step can absorb them.
+
+    For the selector's terminal branch only (no open attempt, nothing
+    eligible). Read-only. A path's candidates are the plan steps whose
+    effective scope holds it, the check record-file-change applies; that
+    permits recording, it does not prove who edited. offered is True only
+    when every path has exactly one candidate, drift has no out-of-scope or
+    blocked file, and nothing makes the run permanently unprovable. Git and
+    file errors propagate: the caller fails closed.
+    """
+    edits: Dict[str, Any] = {
+        "pairs": [], "candidates": {}, "drift": None,
+        "permanent": False, "scope_violation": False, "offered": False,
+    }
+    if not is_git_repo(root):
+        return edits
+    pairs = _changed_file_pairs(root, plan, _requires_file_receipts(root, strict))
+    if not pairs:
+        return edits
+    step_ids = [
+        step["id"] for step in plan.get("steps", [])
+        if isinstance(step, dict) and isinstance(step.get("id"), str)
+    ]
+    edits["pairs"] = [{"path": path, "message": finding["message"]} for path, finding in pairs]
+    for path, _finding in pairs:
+        if path not in edits["candidates"]:
+            edits["candidates"][path] = [
+                step_id for step_id in step_ids if path_in_effective_scope(plan, step_id, path)
+            ]
+    edits["permanent"] = bool(_terminal_attempt_violations(root)) or any(
+        receipt_state == "unrecoverable"
+        for _receipt, receipt_state, _by in timeout_receipt_states(root, plan)
+    )
+    if edits["permanent"]:
+        return edits
+    drift = audit_drift(root, plan)
+    edits["drift"] = drift
+    edits["scope_violation"] = bool(
+        drift.get("out_of_scope_files") or drift.get("blocked_files_changed")
+    )
+    edits["offered"] = not edits["scope_violation"] and all(
+        len(candidates) == 1 for candidates in edits["candidates"].values()
+    )
+    return edits
+
+
 def _unresolved_finding_refs(root: Path) -> List[Dict[str, str]]:
     """Flag amendment finding refs whose review run is not recorded.
 
@@ -792,9 +872,7 @@ def verify_run(
     result: Dict[str, Any] = {"status": "passed", "errors": [], "warnings": []}
     policy = _proof_policy(root)
     effective_strict = strict or bool(policy.get("strict_by_default"))
-    require_file_receipts = effective_strict or bool(
-        policy.get("require_file_receipts_for_changed_files", True)
-    )
+    require_file_receipts = _requires_file_receipts(root, strict)
     for error in validate_plan(plan):
         result["errors"].append({"severity": "error", "message": error})
     drift = audit_drift(root, plan)

{agentflow_proof-1.2.0 → agentflow_proof-1.2.1}/src/agentflow/hunks.py

@@ -243,3 +243,12 @@ def unmapped_hunks(root: Path, records: List[Dict[str, Any]]) -> List[Dict[str,
                     }
                 )
     return out
+
+
+def format_unmapped_hunk(entry: Dict[str, Any]) -> str:
+    """One unmapped_hunks entry as audit-drift prints it (#73: shared with next-action)."""
+    return (
+        f"{entry['path']} @@ -{entry['old_start']},{entry['old_count']} "
+        f"+{entry['new_start']},{entry['new_count']} @@ "
+        f"{entry['hash'][:12]} ({entry['reason']})"
+    )

{agentflow_proof-1.2.0 → agentflow_proof-1.2.1}/src/agentflow/porcelain.py

@@ -38,12 +38,16 @@ from .execution import (
     validate_execution_contract,
 )
 from .execution_coverage import (
+    latest_file_receipts_by_path,
+    post_completion_edits,
+    receipt_matches_worktree,
     replacement_needs,
     timeout_receipt_states,
     verify_run,
     verify_step,
 )
 from .git import changed_file_records
+from .hunks import effective_hunk_policy, format_unmapped_hunk, unmapped_hunks
 from .proof import verify_proof
 from .receipts import command_receipts, file_receipts, sha256_path
 from .validation import audit_drift, path_in_effective_scope, validate_plan
@@ -165,7 +169,8 @@ class _Selection:
     recorded_blockers is set (possibly []) only on the clean returns after the
     step-runs ledger has been validated; None keeps the recorded_blockers key
     absent from next-action. ledgers is the validated snapshot they came from,
-    set on the same returns.
+    set on the same returns. edits is the #73 post_completion_edits result,
+    filled with needs, so projection and rendering share one inspection.
     """
 
     kind: Optional[str]
@@ -177,6 +182,7 @@ class _Selection:
     unrecoverable: List[Dict[str, Any]] = field(default_factory=list)
     recorded_blockers: Optional[List[Dict[str, Any]]] = None
     ledgers: Optional[Dict[str, List[Dict[str, Any]]]] = None
+    edits: Dict[str, Any] = field(default_factory=dict)
 
 
 def _timeout_close(
@@ -661,8 +667,14 @@ def _project_recovery_actions(
                 else "claim requires an agent identity"
             )
         amend_allowed = amend and bool(agent_id)
+        # #73: an amendment records the working tree as the step's work, so
+        # with any unreceipted change someone must say whose it is first.
+        manual = amend and bool(selection.edits.get("pairs"))
         amend_reason = (
-            f"step {step_id} has completed work and needs a replacement attempt"
+            "changed files have no matching file receipt; an operator must attribute "
+            "them with amend-step"
+            if amend_allowed and manual
+            else f"step {step_id} has completed work and needs a replacement attempt"
             if amend_allowed
             else "amend requires an agent identity"
             if amend
@@ -680,7 +692,7 @@ def _project_recovery_actions(
                 automatic=False, break_glass=True,
             ),
             _recovery_action("block", False, "no open attempt"),
-            _recovery_action("amend", amend_allowed, amend_reason),
+            _recovery_action("amend", amend_allowed, amend_reason, automatic=not manual),
         ]
 
     owner = attempt.get("agent_id")
@@ -806,14 +818,26 @@ def _resumability(
             else:
                 # Nothing eligible: replace the first completed step that needs
                 # it, unless an unrecoverable timeout makes the run unprovable.
+                # #73: an unreceipted change is one more cause. Its inspection
+                # reads the working tree, so a git or file error fails closed.
+                try:
+                    edits = post_completion_edits(root, plan, strict=strict)
+                except (RuntimeError, OSError) as exc:
+                    return _diagnose(
+                        projection,
+                        "execution_state_invalid",
+                        f"cannot inspect changed files: {exc}",
+                        "working tree",
+                    ), _Selection(None)
                 selection = _Selection(
                     None,
-                    needs=replacement_needs(root, plan, strict=strict),
+                    needs=replacement_needs(root, plan, strict=strict, edits=edits),
                     unrecoverable=[
                         receipt
                         for receipt, receipt_state, _ in timeout_receipt_states(root, plan)
                         if receipt_state == "unrecoverable"
                     ],
+                    edits=edits,
                 )
                 if selection.needs and not selection.unrecoverable:
                     need = selection.needs[0]
@@ -1029,15 +1053,11 @@ def explain_next_step(root: Path) -> Dict[str, Any]:
     return {"step": None, "reason_code": code, "diagnostics": diagnostics}
 
 
-def _scoped_unrecorded_paths(root: Path, plan: Dict[str, Any], step_id: str,
-                             attempt_id: str) -> List[str]:
-    """Scoped changed files with no file receipt for this open attempt."""
-    recorded = {
-        r.get("path")
-        for r in file_receipts(root)
-        if r.get("step_id") == step_id and r.get("attempt_id") == attempt_id
-    }
+def _scoped_unrecorded_paths(root: Path, plan: Dict[str, Any], step_id: str) -> List[str]:
+    """Scoped files without matching receipt content or enforced hunk coverage."""
+    latest = latest_file_receipts_by_path(root)
     missing: List[str] = []
+    scoped_records: List[Dict[str, str]] = []
     for record in changed_file_records(root):
         path = record.get("path")
         if not isinstance(path, str):
@@ -1046,8 +1066,12 @@ def _scoped_unrecorded_paths(root: Path, plan: Dict[str, Any], step_id: str,
             continue
         if not path_in_effective_scope(plan, step_id, path):
             continue
-        if path not in recorded:
+        scoped_records.append(record)
+        receipt = latest.get(path)
+        if receipt is None or not receipt_matches_worktree(root, record, receipt):
             missing.append(path)
+    if effective_hunk_policy(root) == "enforce":
+        missing.extend(entry["path"] for entry in unmapped_hunks(root, scoped_records))
     return sorted(set(missing))
 
 
@@ -1103,6 +1127,53 @@ def _latest_run_verification(root: Path) -> Optional[Dict[str, Any]]:
     return latest
 
 
+def _unreceipted_hints(edits: Dict[str, Any]) -> List[str]:
+    """#73: which step could record each unreceipted change no step was offered.
+
+    Nothing when the edits were offered (the cause lines say it) or the run is
+    permanently unprovable. A blocked or out-of-scope change is never presented
+    as something an amendment can accept.
+    """
+    if not edits.get("pairs") or edits.get("offered") or edits.get("permanent"):
+        return []
+    prefix = (
+        "after the out-of-scope and blocked changes are resolved, "
+        if edits.get("scope_violation") else ""
+    )
+    hints = []
+    for path, candidates in edits["candidates"].items():
+        if len(candidates) == 1:
+            hints.append(f"{prefix}{path} is in step {candidates[0]}'s scope; "
+                         f"amend-step {candidates[0]} can record it")
+        elif candidates:
+            hints.append(f"{path} is in the scope of steps {', '.join(candidates)}; "
+                         "amend the step that made the edit and record it there")
+        else:
+            hints.append(f"{path} is in no step's scope; no amendment can record it")
+    return hints
+
+
+def _drift_reason(root: Path, drift: Dict[str, Any]) -> str:
+    """#73: name every failing drift category, not only out-of-scope files."""
+    parts = []
+    if drift.get("out_of_scope_files"):
+        parts.append("changes fall outside plan scope")
+    if drift.get("blocked_files_changed"):
+        parts.append("blocked files changed")
+    # Under observe, unmapped hunks are listed but do not fail drift.
+    if drift.get("unmapped_hunks") and effective_hunk_policy(root) == "enforce":
+        parts.append("changed hunks are not covered by file receipts")
+    return "; ".join(parts) or "changes fall outside plan scope"
+
+
+def _unmapped_hunk_lines(drift: Dict[str, Any]) -> List[str]:
+    return [
+        f"unmapped hunk: {format_unmapped_hunk(entry)}"
+        for entry in drift.get("unmapped_hunks", [])
+        if isinstance(entry, dict)
+    ]
+
+
 def _replacement_cause(
     step_id: str,
     need: Dict[str, Any],
@@ -1118,6 +1189,8 @@ def _replacement_cause(
         )
     if cause["cause"] == "failed_attempt":
         return f"replace failed attempt {need['attempt_id']}", f"{step_id} has failed attempt"
+    if cause["cause"] == "post_completion_edit":
+        return f"record post-completion edit to {cause['path']}", cause["message"]
     return (
         f"replace {need['status']} attempt {need['attempt_id']} (strict)",
         f"{step_id} is not completed",
@@ -1196,7 +1269,14 @@ def next_action(
         changed = selection.kind != "claim" and _projection_ledgers(root) != selection.ledgers
     except (AttributeError, KeyError, OSError, TypeError, ValueError):
         # A downstream reader can fail before the final comparison is reached.
-        changed = True
+        # #94: blame the ledgers only if a fresh read differs or fails;
+        # otherwise the error is Agentflow's own and a rerun cannot clear it.
+        try:
+            changed = _projection_ledgers(root) != selection.ledgers
+        except (OSError, ValueError):
+            changed = True
+        if not changed:
+            raise
     if changed:
         return _invalid_action(_diagnose(
             projection,
@@ -1237,7 +1317,9 @@ def _selected_action(
                 command=_cmd(args, user_placeholder=not agent_id), args=args, step_id=step_id,
                 diagnostics=[
                     *(line for _text, line in texts),
+                    *_unmapped_hunk_lines(selection.edits.get("drift") or {}),
                     *(f"also needs a replacement attempt: {other['step_id']}" for other in others),
+                    *_unreceipted_hints(selection.edits),
                 ],
             ),
             projection,
@@ -1251,13 +1333,19 @@ def _selected_action(
             for receipt in selection.unrecoverable
         ]
         finish_args = ["finish-run", *strict_args]
-        drift = audit_drift(root, plan)
+        hints = _unreceipted_hints(selection.edits)
+        drift = selection.edits.get("drift") or audit_drift(root, plan)
         if drift.get("status") == "fail":
             return _attach(
-                Action("drift_failing", "changes fall outside plan scope",
+                Action("drift_failing", _drift_reason(root, drift),
                        command=_cmd(finish_args), args=finish_args,
-                       diagnostics=[*(f"out of scope: {p}" for p in
-                                      drift.get("out_of_scope_files", [])), *stranded]),
+                       diagnostics=[
+                           *(f"out of scope: {p}" for p in drift.get("out_of_scope_files", [])),
+                           *(f"blocked: {p}" for p in drift.get("blocked_files_changed", [])),
+                           *_unmapped_hunk_lines(drift),
+                           *hints,
+                           *stranded,
+                       ]),
                 projection,
             )
         run_result = verify_run(root, plan, strict=strict, record=False)
@@ -1271,7 +1359,7 @@ def _selected_action(
             strict and bool(run_warnings)
         )
         if run_record is None or run_failed:
-            diagnostics = [*(f["message"] for f in run_findings), *stranded]
+            diagnostics = [*(f["message"] for f in run_findings), *hints, *stranded]
             if run_record is None:
                 diagnostics.insert(0, "run verification has not been recorded")
             return _attach(
@@ -1346,7 +1434,16 @@ def _selected_action(
             ),
             projection,
         )
-    unrecorded = _scoped_unrecorded_paths(root, plan, step_id, attempt_id)
+    try:
+        unrecorded = _scoped_unrecorded_paths(root, plan, step_id)
+    except (RuntimeError, OSError) as exc:
+        # A concurrent ledger change must supersede this working-tree diagnostic.
+        return _invalid_action(_diagnose(
+            {**projection, "diagnostics": []},
+            "execution_state_invalid",
+            f"cannot inspect changed files: {exc}",
+            "working tree",
+        ))
     if unrecorded:
         args = ["record-file-change", "--step", step_id, "--path", unrecorded[0], *agent_args]
         return _attach_inflight(

{agentflow_proof-1.2.0 → agentflow_proof-1.2.1/src/agentflow_proof.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentflow-proof
-Version: 1.2.0
+Version: 1.2.1
 Summary: A model-agnostic workflow runner for drift-resistant agentic development.
 Author: Agentflow contributors
 License-Expression: MIT