@arbiterforge/ca-pi 0.18.4 → 0.19.0

package/plugins/ca-pi/hooks/_contextwriterlib.py

@@ -0,0 +1,114 @@
+"""Prepare explicit whole-document context previews from bounded source evidence.
+
+This convenience layer writes nothing. The native writer owns validation,
+preview retention, compare-and-swap, paired writes and recovery. Content hashes
+record what was inspected; they never attest a semantic review or user approval.
+"""
+from __future__ import annotations
+
+import datetime
+import hashlib
+import json
+import os
+from pathlib import Path
+import stat
+
+import _artifactlib
+import _contextsnapshotlib
+
+
+def _read_file(path: Path, limit: int) -> bytes:
+    try:
+        fd = _artifactlib._open_pinned_regular(path)
+        try:
+            info = os.fstat(fd)
+            if not stat.S_ISREG(info.st_mode) or info.st_size > limit:
+                raise _artifactlib.ArtifactError("INVALID_CONTEXT_REQUEST", "context input is not a bounded regular file")
+            raw = os.read(fd, limit + 1)
+        finally:
+            os.close(fd)
+        if len(raw) > limit or len(raw) != info.st_size:
+            raise _artifactlib.ArtifactError("INVALID_CONTEXT_REQUEST", "context input is oversized or changed during acquisition")
+        return raw
+    except OSError as exc:
+        raise _artifactlib.ArtifactError("INVALID_CONTEXT_REQUEST", "context input is unavailable or unsafe") from exc
+
+
+def prepare_document_preview(root: str | Path, document_id: str,
+                             draft_file: str | Path, source_paths: list[str]) -> dict:
+    """Select the entire named document and preserve exact current identities."""
+    root = _artifactlib._trusted_directory(root, "UNSAFE_ROOT")
+    target = _artifactlib._CONTEXT_TARGETS.get(document_id)
+    if target is None or not source_paths or len(source_paths) > 64:
+        raise _artifactlib.ArtifactError("INVALID_CONTEXT_REQUEST", "select one context document and 1-64 source paths")
+    provenance_path = f".codearbiter/.provenance/{document_id}.json"
+    if any(path in {target, provenance_path} for path in source_paths):
+        raise _artifactlib.ArtifactError("INVALID_CONTEXT_REQUEST", "context cannot use its own output as source evidence")
+    draft = Path(draft_file)
+    if not draft.is_absolute():
+        draft = root / draft
+    raw = _read_file(draft, 128 * 1024)
+    try:
+        markdown = raw.decode("utf-8", "strict")
+    except UnicodeError as exc:
+        raise _artifactlib.ArtifactError("INVALID_CONTEXT_REQUEST", "context draft must be UTF-8") from exc
+    evidence = []
+    for path in sorted(set(source_paths)):
+        try:
+            acquired = _contextsnapshotlib.digest_file(root, path)
+        except _contextsnapshotlib.DigestError as exc:
+            raise _artifactlib.ArtifactError("INVALID_CONTEXT_SOURCE", str(exc)) from exc
+        evidence.append({"kind": "content", **{key: acquired[key] for key in
+                                              ("path", "digest_method", "digest")}})
+    existing = _read_file(root / target, 128 * 1024) if os.path.lexists(root / target) else None
+    prior = _read_file(root / provenance_path, 1 << 20) if os.path.lexists(root / provenance_path) else None
+    mode = "create" if existing is None else "adopt"
+    if prior is not None:
+        try:
+            record = _artifactlib._decode(prior, max_bytes=1 << 20)
+        except _artifactlib.ArtifactError as exc:
+            raise _artifactlib.ArtifactError("INVALID_CONTEXT_REQUEST", "preserve malformed existing provenance for review") from exc
+        if not isinstance(record, dict) or record.get("doc") != document_id or record.get("schema") not in (1, 2):
+            raise _artifactlib.ArtifactError("INVALID_CONTEXT_REQUEST", "preserve unsupported existing provenance for review")
+        if existing is None:
+            raise _artifactlib.ArtifactError("INVALID_CONTEXT_REQUEST", "existing provenance has no document; inspect recovery before creating")
+        if record["schema"] == 2:
+            mode = "update"
+    digest = lambda value: hashlib.sha256(value).hexdigest() if value is not None else None
+    request = {
+        "mode": mode, "document_id": document_id, "target_path": target,
+        "typed": {"format": "codearbiter.repository-context/0.1.0", "document_id": document_id,
+                  "entries": [{"id": "FIELD-DOCUMENT", "kind": "document", "markdown": markdown,
+                               "evidence_refs": ["CLAIM-DOCUMENT"]}]},
+        "selections": [{"entry_id": "FIELD-DOCUMENT", "anchor": "document"}],
+        "expected_document_sha256": digest(existing), "expected_provenance_sha256": digest(prior),
+        "proposed_provenance": {
+            "schema": 2, "doc": document_id, "created": datetime.date.today().isoformat(),
+            "document": {"path": target, "digest_method": "sha256-raw", "digest": digest(raw)},
+            "fields": [{"id": "FIELD-DOCUMENT", "owner_ref": "document", "claims": [{
+                "id": "CLAIM-DOCUMENT", "semantic_review": {"state": "unreviewed", "reference": None},
+                "evidence": evidence, "effective_authority_refs": [],
+            }]}],
+        },
+    }
+    identity = hashlib.sha256(json.dumps(request, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()).hexdigest()
+    request["operation_id"] = "context-refresh-" + identity[:32]
+    return request
+
+
+def prepare_finalization_preview(root: str | Path) -> dict:
+    """Bind initialization to the exact required outputs without changing them."""
+    root = _artifactlib._trusted_directory(root, "UNSAFE_ROOT")
+    expected = {}
+    for path in sorted(_artifactlib._CONTEXT_FINALIZE_PATHS):
+        try:
+            expected[path] = _contextsnapshotlib.digest_file(root, path)["digest"]
+        except _contextsnapshotlib.DigestError as exc:
+            raise _artifactlib.ArtifactError(
+                "INVALID_CONTEXT_FINALIZATION", f"required output unavailable or unsafe: {path} ({exc})") from exc
+    identity = hashlib.sha256(json.dumps(expected, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+    return {
+        "operation_id": "context-finalize-" + identity[:32], "mode": "finalize",
+        "document_id": "CONTEXT", "target_path": ".codearbiter/CONTEXT.md",
+        "expected": expected,
+    }

package/plugins/ca-pi/hooks/_host.py

@@ -11,7 +11,7 @@ import hostapi  # noqa: E402
 class PiHost(hostapi.Host):
     name = "pi"
     adapter_name = "@arbiterforge/ca-pi"
-    adapter_version = "0.18.4"
+    adapter_version = "0.19.0"
     update_target = "ca-pi"
     update_tag_prefix = "ca-pi-v"
     update_command = "pi update npm:@arbiterforge/ca-pi"

package/plugins/ca-pi/hooks/_prerequisitelib.py

@@ -847,6 +847,31 @@ def cancel_user_prerequisite(
         }
 
 
+def retire_unanswered_user_prerequisite(
+    root: str | Path, artifact_id: str, prerequisite_id: str, *, reason: str,
+) -> dict[str, Any]:
+    """Retire only an ARMED question, never an observed user decision.
+
+    Reuse the existing bounded pending reader, per-plan transition lock,
+    and the proven ARMED-only cancellation. CONFIRMED or CAPTURED must
+    follow their existing exact recovery paths; no receipt is synthesized.
+    """
+    if (not isinstance(reason, str) or not reason.strip()
+            or len(reason.encode("utf-8")) > 2048
+            or not isinstance(artifact_id, str) or ID_RE.fullmatch(artifact_id) is None
+            or not isinstance(prerequisite_id, str) or ID_RE.fullmatch(prerequisite_id) is None):
+        raise PrerequisiteError("INVALID_RETIREMENT", "retirement requires valid IDs and a bounded nonblank reason")
+    cancelled = cancel_user_prerequisite(root, artifact_id, prerequisite_id)
+    if cancelled.get("cancelled") is not True:
+        raise PrerequisiteError("INVALID_RETIREMENT", "the unanswered prerequisite was not cancelled")
+    return {
+        "artifact_id": artifact_id, "prerequisite_id": prerequisite_id,
+        "disposition": "unanswered_prompt_superseded", "reason": reason.strip(),
+        "authority_granted": False, "mutation_attempted": False,
+    }
+
+
+
 def supersede_user_prerequisite(
     root: str | Path,
     client: Any,
@@ -976,12 +1001,22 @@ def main(argv: list[str] | None = None) -> int:
     supersede.add_argument("--root", required=True)
     supersede.add_argument("--artifact-id", required=True)
     supersede.add_argument("--prerequisite-id", required=True)
+    retire = sub.add_parser("retire")
+    retire.add_argument("--root", required=True)
+    retire.add_argument("--artifact-id", required=True)
+    retire.add_argument("--prerequisite-id", required=True)
+    retire.add_argument("--reason", required=True)
     args = parser.parse_args(argv)
     if args.command == "cancel":
         print(json.dumps(cancel_user_prerequisite(
             args.root, args.artifact_id, args.prerequisite_id
         )))
         return 0
+    if args.command == "retire":
+        print(json.dumps(retire_unanswered_user_prerequisite(
+            args.root, args.artifact_id, args.prerequisite_id, reason=args.reason,
+        )))
+        return 0
     client = _artifactlib.ArtifactClient(
         args.root, _artifactlib.helper_installation(__file__)
     )

package/plugins/ca-pi/hooks/_provenancelib.py

@@ -650,7 +650,7 @@ def assess_context_provenance(provenance_dir, expected_docs, snapshot,
     """
     result = {"coverage": "incomplete", "identity": "unknown",
               "semantic": "unverified", "verified_fresh": False,
-              "documents": {}, "first_input": {}}
+              "documents": {}, "first_input": {}, "snapshot_current": {}}
     if (not isinstance(provenance_dir, (str, os.PathLike)) or
             type(expected_docs) not in (list, tuple) or
             not expected_docs):
@@ -725,6 +725,8 @@ def assess_context_provenance(provenance_dir, expected_docs, snapshot,
         except Exception:
             return result
         probes = {doc: probe for doc in eligible}
+        result["snapshot_current"] = {
+            doc: probe["source_current"] and probe["targets_current"] for doc in eligible}
         if not probe["source_current"] or not probe["targets_current"]:
             if store_complete and len(eligible) == len(expected_docs):
                 result["coverage"] = "complete"
@@ -732,6 +734,9 @@ def assess_context_provenance(provenance_dir, expected_docs, snapshot,
             for doc in eligible:
                 result["documents"][doc] = "v2_stale"
             return result
+    result["snapshot_current"] = {
+        doc: probe.get("source_current") is True and probe.get("targets_current") is True
+        for doc, probe in probes.items()}
     try:
         files = snapshot["source"]["files"]
         membership = snapshot["source"]["membership"]
@@ -1111,6 +1116,107 @@ def rebaseline(provenance, current_hashes):
 # ---------------------------------------------------------------------------
 
 
+def v2_heal_worklist(staged_paths, provenance, snapshot, assessment):
+    """Select changed v2 claims intersecting staged sources; never authorize writes.
+
+    Use the existing assessor's dependency probe and snapshot. Unknown evidence
+    suspends automatic maintenance for that document, not the commit. Selected
+    claims still need content review and the native paired writer with CAS;
+    replacing their digests through the legacy rebaseline path is unsupported.
+    """
+    result = {"claims": [], "unknown": [], "authorizes_write": False}
+    if (type(staged_paths) not in (list, tuple) or
+            any(not _v2_path(path) for path in staged_paths) or
+            type(provenance) is not dict or type(assessment) is not dict):
+        result["unknown"].append({"document_id": None, "reason": "invalid_inputs"})
+        return result
+    paths = list(dict.fromkeys(staged_paths))
+    if not paths:
+        return result
+    try:
+        from _contextsnapshotlib import _membership_match
+
+        files, members = snapshot["source"]["files"], snapshot["source"]["membership"]
+        targets = snapshot["targets"]
+        states, probes = assessment["documents"], assessment["snapshot_current"]
+        if (any(type(value) is not dict for value in (files, targets, states, probes)) or
+                type(members) is not list):
+            raise ValueError
+        membership = {}
+        for member in members:
+            key = (member["predicate"], tuple(member["scope_paths"]))
+            if key in membership:
+                raise ValueError
+            membership[key] = member
+    except (KeyError, TypeError, ValueError):
+        result["unknown"].append({"document_id": None, "reason": "invalid_snapshot_or_assessment"})
+        return result
+
+    def intersects(evidence, path):
+        if evidence["kind"] == "content":
+            return path == evidence["path"]
+        if not any(scope == "." or path == scope or path.startswith(scope + "/")
+                   for scope in evidence["scope_paths"]):
+            return False
+        predicate = evidence["predicate"]
+        parents = path.split("/")[:-1]
+        return (_membership_match(predicate, path, False) or
+                any(_membership_match(predicate, parent, True) for parent in parents))
+
+    for doc in sorted(set(provenance) | set(states)):
+        record = provenance.get(doc)
+        if (type(record) is dict and record.get("schema") == SCHEMA_VERSION and
+                valid_provenance_record(record)):
+            continue
+        if (not valid_provenance_record(record) or record.get("schema") != V2_SCHEMA_VERSION or
+                record.get("doc") != doc):
+            result["unknown"].append({"document_id": doc, "reason": "record_unknown"})
+            continue
+        candidates = []
+        for field in record["fields"]:
+            for claim in field["claims"]:
+                affected = [path for path in paths
+                            if any(intersects(item, path) for item in claim["evidence"])]
+                if affected:
+                    candidates.append((field, claim, affected))
+        if not candidates:
+            continue
+        if states.get(doc) not in ("v2_current", "v2_stale") or probes.get(doc) is not True:
+            result["unknown"].append({"document_id": doc, "reason": "snapshot_not_current"})
+            continue
+        document = record["document"]
+        target = targets.get(document["path"])
+        if (type(target) is not dict or target.get("status") != "file" or
+                any(target.get(key) != document[key] for key in ("digest_method", "digest"))):
+            result["unknown"].append({"document_id": doc, "reason": "document_preimage_changed_or_unknown"})
+            continue
+        selected, unknown = [], []
+        for field, claim, affected in candidates:
+            changed = []
+            for evidence in claim["evidence"]:
+                current = (files.get(evidence["path"]) if evidence["kind"] == "content" else
+                           membership.get((evidence["predicate"], tuple(evidence["scope_paths"]))))
+                if (type(current) is not dict or
+                        current.get("status", "file") != (
+                            "file" if evidence["kind"] == "content" else "complete") or
+                        current.get("digest_method") != evidence["digest_method"] or
+                        not _sha256(current.get("digest"))):
+                    unknown.append({"document_id": doc, "field_id": field["id"],
+                                    "claim_id": claim["id"], "paths": affected,
+                                    "reason": "evidence_unknown"})
+                    break
+                if current["digest"] != evidence["digest"]:
+                    changed.extend(path for path in affected if intersects(evidence, path))
+            if changed:
+                selected.append({"document_id": doc, "field_id": field["id"],
+                                 "claim_id": claim["id"],
+                                 "paths": [path for path in affected if path in changed]})
+        result["unknown"].extend(unknown)
+        if not unknown:
+            result["claims"].extend(selected)
+    return result
+
+
 def heal_worklist(staged_paths, provenance, current_hashes):
     """Return staged paths that are drift_trigger:true entries with diverged/absent hashes.
 

package/plugins/ca-pi/hooks/_readinjectlib.py

@@ -1128,13 +1128,14 @@ def build_index(root):
         extra = []
         client = ArtifactClient(root, helper_installation(__file__))
         for entry in client.index("spec"):
-            authority = entry["authority"]
-            if authority["authority_verified"] and entry.get("governs"):
+            state = entry["authority"].get("state")
+            if state in ("draft", "ready", "approved") and entry.get("governs"):
                 extra.append({
                     "spec": entry["artifact_id"],
                     "path": entry["path"],
                     "globs": entry["governs"],
                     "artifact_html": True,
+                    "governance_state": state,
                     "revision": entry.get("revision"),
                     "model_sha256": entry.get("model_sha256"),
                     "normative_sha256": entry.get("normative_sha256"),
@@ -1165,22 +1166,35 @@ def spec_pointers(rel, index):
     if not isinstance(index, list):
         return _artifact_legacy_spec_pointers(rel, index)
     warnings = [item for item in index if isinstance(item, dict) and item.get("artifact_diagnostic")]
-    normal = [item for item in index if not isinstance(item, dict) or not item.get("artifact_diagnostic")]
+    normal = [item for item in index if not isinstance(item, dict) or
+              not item.get("artifact_html") and not item.get("artifact_diagnostic")]
     result = _artifact_legacy_spec_pointers(rel, normal)
+    for item in index:
+        if (not isinstance(item, dict) or not item.get("artifact_html") or
+                item.get("governance_state") not in ("draft", "ready", "approved")):
+            continue
+        if isinstance(rel, str) and any(fnmatch.fnmatch(rel, glob) for glob in item.get("globs", [])):
+            result.append({"tier": "specs", "text": (
+                "spec {} ({}) — advisory context for this file; read {}. "
+                "This pointer grants no approval or execution authority."
+            ).format(item["spec"], item["governance_state"], item["path"])})
     if warnings:
         warning = warnings[0]
         code = warning["artifact_diagnostic"]
         if warning.get("artifact_diagnostic_kind") == "capability":
             text = (
                 "HTML artifact capability unavailable (" + code + "). Repair or reinstall "
-                "the pinned artifact payload. Source inspection and unrelated legacy Markdown "
-                "may continue; HTML planning/execution must stop until resolved."
+                "the pinned artifact payload. Stop only operations that require this capability. "
+                "Independent authorized work may continue. "
+                "Do not bypass the error with raw artifact writes."
             )
         else:
             text = (
                 "HTML specification is invalid or unreadable (" + code + "). Inspect the "
-                "engine diagnostic and repair-preview before any repair. Source inspection may "
-                "continue; HTML planning/execution must stop until resolved."
+                "engine diagnostic and repair-preview before repairing the affected artifact. "
+                "Stop only operations that depend on the affected artifact. "
+                "Independent authorized work may continue. "
+                "Do not bypass the error with raw artifact writes."
             )
         result.append({"tier": "artifact-diagnostic", "text": text})
     return result

package/plugins/ca-pi/hooks/_reconciliationlib.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 from contextlib import contextmanager
 import hashlib
+from itertools import islice
 import json
 import os
 from pathlib import Path
@@ -237,6 +238,107 @@ def _load_attempt(root: Path, pending: dict[str, Any]) -> dict[str, Any] | None:
     return value["request"]
 
 
+def _history_records(root: Path, relative: Path):
+    """Read a bounded immutable history directory without following links."""
+    try:
+        directory = _artifactauthoritylib._safe_directory(root, relative, create=False)
+    except FileNotFoundError:
+        return
+    except (OSError, _artifactauthoritylib.AuthorityError) as exc:
+        raise ReconciliationError(f"reconciliation {relative.name} storage is unavailable or unsafe") from exc
+    try:
+        entries = list(islice(directory.iterdir(), 513))
+        if len(entries) > 512:
+            raise ReconciliationError(f"too many historical {relative.name} to inspect reconciliation safely")
+        for entry in entries:
+            if not _approvallib.SHA256_RE.fullmatch(entry.stem) or entry.suffix != ".json":
+                raise ReconciliationError(f"{relative.name} storage contains an unrecognized entry; inspect before retiring")
+            info = entry.lstat()
+            if (not stat.S_ISREG(info.st_mode) or getattr(info, "st_file_attributes", 0) & 0x400
+                    or info.st_size > 65536):
+                raise ReconciliationError(f"reconciliation {relative.name} is not bounded regular data")
+            fd = _artifactlib._open_pinned_regular(entry)
+            with os.fdopen(fd, "rb") as stream:
+                opened = os.fstat(stream.fileno())
+                if (not stat.S_ISREG(opened.st_mode) or opened.st_size > 65536
+                        or (info.st_dev, info.st_ino) != (opened.st_dev, opened.st_ino)):
+                    raise ReconciliationError(f"reconciliation {relative.name} changed while opening")
+                raw = stream.read(65537)
+            if len(raw) > 65536:
+                raise ReconciliationError(f"reconciliation {relative.name} exceeds its bound")
+            record = _artifactlib._decode(raw)
+            if not isinstance(record, dict) or _digest(_canonical(record)) != entry.stem:
+                raise ReconciliationError(f"stored {relative.name} changed; preserve the pending reconciliation")
+            yield relative / entry.name, record
+    except (OSError, ValueError, _artifactlib.ArtifactError) as exc:
+        raise ReconciliationError(f"reconciliation {relative.name} storage is unreadable or unsafe") from exc
+
+
+def _reply_observation_matches(observed: dict[str, Any], pending: dict[str, Any]) -> bool:
+    return (observed.get("format") == _artifactauthoritylib.OBSERVATION_FORMAT
+            and observed.get("kind") == "reconciliation"
+            and observed.get("producer_profile") == "host-user-prompt/0.1.0"
+            and observed.get("subject") == {
+                "artifact_id": pending["artifact_id"], "record_id": pending["target_id"],
+                "normative_sha256": pending["identity"].get("normative_sha256"),
+            }
+            and isinstance(observed.get("producer_result"), dict)
+            and observed["producer_result"].get("prompt_sha256") == pending["prompt_sha256"])
+
+
+def _published_reply_observed(root: Path, pending: dict[str, Any]) -> bool:
+    """A captured reply is not unanswered even if its attempt was not saved."""
+    return any(_reply_observation_matches(record, pending)
+               for _, record in _history_records(root, _artifactauthoritylib.OBSERVATION_DIR))
+
+
+def _recover_captured_request(root: Path, client: Any, pending: dict[str, Any]) -> dict[str, Any]:
+    """Recover only the original immutable user event; never manufacture one."""
+    try:
+        binding = _artifactpromptlib.binding(root, "reconciliation", pending["artifact_id"])
+    except _artifactpromptlib.PromptRouteError as exc:
+        raise ReconciliationError("captured reconciliation route is unavailable or unsafe") from exc
+    if binding != _digest(_canonical(pending)):
+        raise ReconciliationError("pending reconciliation changed after arming")
+    observations = {
+        path.as_posix(): record
+        for path, record in _history_records(root, _artifactauthoritylib.OBSERVATION_DIR)
+        if _reply_observation_matches(record, pending)
+    }
+    if not observations:
+        raise ReconciliationError("no in-flight reconciliation or observed reply to recover")
+    payload = {"input_sha256": pending["input_sha256"], "assessment": pending["assessment"]}
+    if pending["operation"] == "task-reconcile":
+        payload.update(task_sha256=_artifactauthoritylib._engine_digest(pending["record"]),
+                       target_state=pending["target_state"])
+    sources = []
+    for path, event in _history_records(root, SOURCE_DIR):
+        reference = event.get("observation_ref")
+        observed = observations.get(reference) if isinstance(reference, str) else None
+        if (observed is not None
+                and event.get("format") == _artifactauthoritylib.EVENT_FORMAT
+                and event.get("kind") == "reconciliation"
+                and event.get("authority_kind") == "user_workflow"
+                and event.get("verdict") == "reconciled"
+                and event.get("subject") == observed["subject"]
+                and event.get("observation_sha256") == Path(event["observation_ref"]).stem
+                and event.get("payload") == payload
+                and isinstance(event.get("source_text"), str)
+                and _digest(event["source_text"].encode("utf-8")) == pending["prompt_sha256"]):
+            sources.append({"source_ref": path.as_posix(), "source_sha256": path.stem})
+    if len(sources) != 1:
+        raise ReconciliationError("captured reconciliation source is missing or ambiguous; preserve pending state")
+    # The native reader validates the original source/observation/context and
+    # reuses its content-addressed receipt. No host event or source is created.
+    captured = client.call("capture-observation", sources[0])
+    receipt = captured.get("receipt") if isinstance(captured, dict) else None
+    if not isinstance(receipt, str) or not receipt.startswith(".codearbiter/.artifacts/receipts/"):
+        raise ReconciliationError("capture returned no valid reconciliation receipt")
+    request = _mutation_request(pending, receipt)
+    _write_attempt(root, pending, request)
+    return request
+
+
 def _current(client: Any, artifact_id: str, target_id: str) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
     identity = client.call("identity", {"artifact_id": artifact_id})
     snapshot = client.call("snapshot", {"artifact_id": artifact_id})
@@ -386,6 +488,8 @@ def _cancel_reconciliation_unlocked(root: Path, artifact_id: str, prompt: str) -
         raise ReconciliationError("cancellation prompt does not match the armed request")
     if _load_attempt(root, pending) is not None:
         raise ReconciliationError("in-flight reconciliation must be retried or recovered, not cancelled")
+    if _published_reply_observed(root, pending):
+        raise ReconciliationError("observed user reconciliation must be retried or recovered, not cancelled")
     try:
         binding = _artifactpromptlib.binding(root, "reconciliation", artifact_id)
     except _artifactpromptlib.PromptRouteError as exc:
@@ -397,6 +501,65 @@ def _cancel_reconciliation_unlocked(root: Path, artifact_id: str, prompt: str) -
     return {"artifact_id": artifact_id, "cancelled": True}
 
 
+def supersede_unanswered_reconciliation(
+    root: str | Path, artifact_id: str, *, reason: str,
+) -> dict[str, Any]:
+    """Retire an unanswered legacy prompt without a user approval code.
+
+    This only discards an unanswered armed question. A published reply or a
+    durable execution attempt must remain available for retry/recovery: never
+    turn uncertain work into an uncommitted result by deleting its marker.
+    Real task BLOCKED state, original receipts and actual user decisions are
+    not changed by this call.
+    """
+    if (
+        not isinstance(reason, str) or not reason.strip()
+        or len(reason.encode("utf-8")) > 2048
+        or not isinstance(artifact_id, str) or ID_RE.fullmatch(artifact_id) is None
+    ):
+        raise ReconciliationError("a valid artifact and bounded nonblank supersession reason are required")
+    # Match existing reconciliation entrypoints: macOS /var may resolve through
+    # the system /private/var alias. Inspect the canonical path with the shared
+    # trusted-directory validator rather than rejecting that platform alias.
+    # This still rejects an unsafe final directory, unreadable path or reparse
+    # point, and all pending/attempt/route checks remain unchanged.
+    requested = Path(root).absolute()
+    try:
+        info = requested.lstat()
+    except OSError as exc:
+        raise ReconciliationError("reconciliation root is unavailable or unsafe") from exc
+    # Allow macOS's *parent* /var -> /private/var alias after canonicalization,
+    # but never accept a symlink or Windows reparse point as the selected repo
+    # itself. This is stricter than the older legacy arm/cancel entrypoints.
+    if stat.S_ISLNK(info.st_mode) or getattr(info, "st_file_attributes", 0) & 0x400:
+        raise ReconciliationError("reconciliation root cannot be a linked or reparse directory")
+    root = _artifactlib._trusted_directory(requested.resolve(strict=True), "UNSAFE_ROOT")
+    with _reconciliation_lock(root, artifact_id):
+        pending = _load(root, artifact_id)
+        if _load_attempt(root, pending) is not None:
+            raise ReconciliationError("in-flight reconciliation must be retried or recovered, not superseded")
+        if _published_reply_observed(root, pending):
+            raise ReconciliationError("observed user reconciliation must be retried or recovered, not superseded")
+        try:
+            binding = _artifactpromptlib.binding(root, "reconciliation", artifact_id)
+        except _artifactpromptlib.PromptRouteError as exc:
+            raise ReconciliationError("reconciliation route is unavailable or unsafe; inspect before retiring") from exc
+        if binding != _digest(_canonical(pending)):
+            raise ReconciliationError("pending reconciliation and registered prompt binding differ")
+        # The validated marker represents an unanswered question; no captured
+        # reply or attempt exists. This does not certify a decision or change state.
+        # Receipt, observation and source history remain in their owning stores.
+        _pending_path(root, artifact_id).unlink()
+        _artifactpromptlib.unregister(root, "reconciliation", artifact_id)
+        return {
+            "artifact_id": artifact_id, "target_id": pending["target_id"],
+            "original_operation": pending["operation"],
+            "superseded": True, "disposition": "unanswered_prompt_superseded",
+            "reason": reason.strip(), "mutation_attempted": False,
+            "authority_granted": False,
+        }
+
+
 def cancel_orphaned_reconciliation(root: str | Path, artifact_id: str) -> dict[str, Any]:
     """Recover a complete pending marker stranded before route registration."""
     root = Path(root).resolve(strict=True)
@@ -404,6 +567,8 @@ def cancel_orphaned_reconciliation(root: str | Path, artifact_id: str) -> dict[s
         pending = _load(root, artifact_id)
         if _load_attempt(root, pending) is not None:
             raise ReconciliationError("in-flight reconciliation must be retried or recovered, not cancelled")
+        if _published_reply_observed(root, pending):
+            raise ReconciliationError("observed user reconciliation must be retried or recovered, not cancelled")
         try:
             binding = _artifactpromptlib.binding(root, "reconciliation", artifact_id)
         except _artifactpromptlib.PromptRouteError as exc:
@@ -420,13 +585,13 @@ def cancel_orphaned_reconciliation(root: str | Path, artifact_id: str) -> dict[s
 
 
 def recover_reconciliation(root: str | Path, client: Any, artifact_id: str) -> dict[str, Any]:
-    """Replay a durable attempt; clear it only after a proven commit or non-commit."""
+    """Recover a captured reply/attempt; clear only a proven commit or non-commit."""
     root = Path(root).resolve(strict=True)
     with _reconciliation_lock(root, artifact_id):
         pending = _load(root, artifact_id)
         request = _load_attempt(root, pending)
         if request is None:
-            raise ReconciliationError("no in-flight reconciliation to recover")
+            request = _recover_captured_request(root, client, pending)
         try:
             result = client.call(pending["operation"], request)
             transaction = result.get("transaction") if isinstance(result, dict) else None

package/plugins/ca-pi/hooks/_releaselib.py

@@ -2834,12 +2834,12 @@ def _targets_error_exit_code(exc):
            skill's "Targets" section and must never be mistaken for
            "safe to back-fill".
 
-    Exit code 2 is deliberately NOT reused for either state here: it already
-    means "bad CLI invocation" or "unrecognised target name" elsewhere in
-    this dispatcher, neither of which is a statement about the declared
-    file's own state -- collapsing them together is exactly how the
-    original defect made "absent" and "exists but broken" indistinguishable
-    from the CLI."""
+    Exit code 2 is deliberately NOT reused for either declared-file state.
+    This module's dispatcher uses 2 for bad CLI invocation or an unrecognised
+    target name; releasehash.py instead reserves 2 for "never confirmed"
+    and uses 64/65 for usage/unknown-target errors. Neither caller may
+    collapse its own exit-2 meaning into the distinction between an absent
+    declared file and an existing but broken one."""
     return 3 if isinstance(exc, AbsentBlockError) else 4