feat(journal): per-write mirror for open-task-consumed metadata keys (#1162) (#1168)

* feat(snapshot): per-write mirror substrate constants + canonical-frame predicate

* feat(gate): per-write mirror TaskUpdate leg for open-task targeted keys

* feat(gate): per-write mirror TaskCreate leg

* test(seam): per-write subprocess integration + drain-recovery

* docs(protocols): journal-fallback recovery for drained scope tasks

* docs(hooks): correct stale PreToolUse matcher claim

* test(commands): re-anchor rePACT dispatch-site pin after Phase 0 fallback insertion

* test(seam): adversarial matrix + staleness probe for the per-write mirror

TEST-phase depth for the per-write task_metadata_snapshot path, driven
through the seam (evaluate_lifecycle + the real hook subprocess), with
caps imported from the substrate constants:

- cap-edge payloads (per-value cap/cap+1, whole disk-and-delta overlay
  over the payload cap, 5MB jumbo) — bounded journal lines, marker
  truncation, key existence preserved
- marker-lookalike values: provenance-not-shape end-to-end, incl. the
  hostile non-int original_bytes variant
- hostile task_ids (traversal, control chars, unicode) through the
  sanitized claim path — marker containment, sanitized event ids
- pathological shapes: deep nesting intact, serializer-breaking nesting
  hermetic with no marker poison, None-riddled deltas, non-dict deltas
  (incl. a list carrying a targeted-key token — guard-first shape)
- exit-0 advisory contract: substrate write failure compensates
  (unclaim) and preserves advisories; identical advisories across the
  fire/skip frame boundary
- leadSessionId staleness probe: stale-mismatch downgrades to skip
  (baseline, no marker), stale-equal admit lands in the process's own
  resolvable journal; drained config skips without crash
- completing-TaskUpdate disjointness boundary: targeted delta on a
  completing write yields exactly the completion event
- real-process rows: unchanged-rewrite dedup across process lifetimes,
  stale-config skip, hostile-id containment, oversized stdin frame

* docs(gate): document the intentional team-resolution split at the per-write frame gate

is_canonical_journal_frame resolves its team via the identity-matched
get_team_name() resolver while the per-write emit legs use the persisted
ctx team_name; record at both sites why neither direction may be unified
(topology correctness after resume-divergence vs cross-seam marker-namespace
consistency) and why divergent outcomes stay bounded.

* test(seam): pin teachback_rejection fire-trigger + ruled-key minimum subset

Close the registry's silent-deletion channel with two additive rows:
a teachback_rejection-triggered fire on an open task with an on-disk
teachback_submit sibling asserts the whole-payload overlay mirrors
BOTH (the rejection-cycle catch-up that gives the teammate-written
class its tmux durability; the delta carries only the rejection, so
the row also reds if the key leaves the registry), and a
minimum-subset pin keeps the five ruled keys deletion-protected while
registry extensions stay one-string source diffs.

* chore: bump version to 4.6.3 (PATCH)

* feat(snapshot): target the audit verdict pair in the per-write mirror registry

audit_summary and audit_summary_authored join PER_WRITE_MIRROR_KEYS: both
are consumed by the lead at CODE-phase close while the audited task is
still open, so a status-blind drain destroys them while load-bearing.
Same teammate-written canonical-frame class as teachback_submit.

* test(seam): pin the audit verdict pair in the per-write registry contract

Extend the ruled-key minimum-subset pin to seven keys and add an
audit_summary fire-trigger row: an open-task write of the audit
verdict mirrors the whole overlay immediately. The row uses a lead
frame with no authored-verdict sibling on disk so the gate's
audit_summary_authored preservation machinery stays untangled from
the snapshot-seam assertion; deleting either audit key from the
registry now goes red.

* refactor(claim-gate): re-point _read_lead_session_id to the shared pact_context copy

Delete the inline duplicate; import the SSOT implementation (module-attribute
binding preserves the test patch seam). Relocate the gate-specific stale-config
blast-radius note to the Step-3 call site, and re-orient the LOGIC-PARITY
cross-refs: pact_context is the SSOT, session_registry keeps the one remaining
inline copy forced by its self-contained-leaf invariant.

* test(parity): update drift-guard prose to the SSOT re-point topology

The parity test's docstring still narrated two independent inline
copies; task_claim_gate now binds the shared pact_context
implementation, leaving session_registry as the one inline copy its
leaf invariant forces. Prose only — the behavioral parity contract
and every assertion are unchanged.

Author: michael-wojcik

.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "PACT",
       "source": "./pact-plugin",
       "description": "Orchestration harness that turns Claude Code into a coordinated team of specialist AI agents",
-      "version": "4.6.2",
+      "version": "4.6.3",
       "author": {
         "name": "Synaptic-Labs-AI"
       },

README.md

@@ -605,7 +605,7 @@ When installed as a plugin, PACT lives in your plugin cache:
 │   └── cache/
 │       └── pact-plugin/
 │           └── PACT/
-│               └── 4.6.2/       # Plugin version
+│               └── 4.6.3/       # Plugin version
 │                   ├── agents/
 │                   ├── commands/
 │                   ├── skills/

pact-plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "PACT",
-  "version": "4.6.2",
+  "version": "4.6.3",
   "description": "Orchestration harness that turns Claude Code into a coordinated team of specialist AI agents",
   "author": {
     "name": "Synaptic-Labs-AI",

pact-plugin/README.md

@@ -1,6 +1,6 @@
 # PACT — Orchestration Harness for Claude Code
 
-> **Version**: 4.6.2
+> **Version**: 4.6.3
 
 Turn a single Claude Code session into a managed team of specialist AI agents that prepare, design, build, and test your code systematically.
 

pact-plugin/commands/rePACT.md

@@ -189,6 +189,7 @@ Branch behavior depends on whether rePACT is invoked with a scope contract:
 Before starting, verify:
 1. **Nesting depth**: Read `TaskGet(taskId).metadata.nesting_depth` — if > 1, reject (max depth exceeded). If absent, treat as 0.
 2. **Scope contract**: If this rePACT was dispatched from ATOMIZE, read the scope contract from `TaskGet(taskId).metadata.scope_contract` instead of expecting it inline in the prompt. This ensures scope state survives compaction.
+   - **Journal fallback (covers items 1–2)**: If `TaskGet(taskId)` cannot resolve (task store drained), recover from the session journal instead: run `python3 "{plugin_root}/hooks/shared/session_journal.py" read --session-dir "{session_dir}" --type task_metadata_snapshot` (prints a JSON array), filter to events whose `task_id` matches this task, take the latest-`ts` event, and read `nesting_depth` / `scope_contract` from its `metadata` (honor `_truncated` / `_dropped_keys` markers if present).
 3. **Scope appropriateness**: Is this truly a sub-task of the parent?
 4. **Domain determination**: Single-domain or multi-domain?
 

pact-plugin/hooks/shared/HOOK_STDIN_DISCRIMINATORS.md

@@ -75,9 +75,11 @@ UserPromptSubmit / PostToolUse) but is NOT read on TaskCompleted — that frame
 captured for the #917 emit-path, which gates on `team_name` + journal
 writability rather than this predicate. On PreToolUse, `is_lead` is read via the
 match-all `bootstrap_gate` (matcher `''`, so it fires before every tool —
-including `TaskCreate` / `TaskUpdate`) and the `Edit` / `Write` pin gates; there
-is no `TaskCreate` / `TaskUpdate`-matched PreToolUse hook (that matcher is
-PostToolUse-only — `task_lifecycle_gate`, the row above).
+including `TaskCreate` / `TaskUpdate`), the `Edit` / `Write` pin gates, and the
+`TaskUpdate`-matched `handoff_ordering_gate` (which gates both of its rules on
+`is_lead`). `TaskCreate` has no PreToolUse-matched hook — its only
+task-lifecycle observer is the PostToolUse-matched `task_lifecycle_gate` (the
+row above).
 
 ### UserPromptSubmit has no teammate fire path
 

pact-plugin/hooks/shared/pact_context.py

@@ -906,6 +906,94 @@ def classify_session_role(input_data: dict) -> str:
     return "unknown"
 
 
+def _read_lead_session_id(team_name: str, teams_dir: str | None = None) -> str:
+    """Read the top-level ``leadSessionId`` from
+    ``~/.claude/teams/{team_name}/config.json``.
+
+    LOGIC-PARITY: this is the SSOT copy — ``task_claim_gate`` imports it
+    directly (its former inline copy is consolidated here; the ``teams_dir``
+    test override is part of the shared signature). The ONE remaining inline
+    copy is ``session_registry._read_lead_session_id``, INLINED there by
+    design: that module's self-contained-leaf invariant forbids ``shared.*``
+    imports, so it must not be re-pointed here. Keep the two implementations
+    behaviorally identical — the behavioral-parity drift-guard test compares
+    them on the same logical inputs.
+
+    Fail-safe: returns "" on any of: unsafe team_name, missing/unreadable
+    file, malformed JSON, non-object top-level, or a missing/non-string key.
+    Callers treat "" as "topology unresolvable" and take their own fail-safe
+    branch. Never raises.
+
+    CURRENCY DEPENDENCY (shared with both parity copies): the value is only
+    as current as the platform-maintained team config — a stale
+    ``leadSessionId`` after a session resume can misclassify an in-process
+    frame as tmux (or vice-versa). Consumers must bound that blast radius to
+    coordination-only decisions (see ``is_canonical_journal_frame``).
+    """
+    if not is_safe_path_component(team_name):
+        return ""
+    if teams_dir:
+        config_path = Path(teams_dir) / team_name / "config.json"
+    else:
+        config_path = get_claude_config_dir() / "teams" / team_name / "config.json"
+    try:
+        data = json.loads(config_path.read_text(encoding="utf-8"))
+        lead_session_id = data.get("leadSessionId")
+    except (OSError, json.JSONDecodeError, ValueError, AttributeError, TypeError):
+        return ""
+    return lead_session_id if isinstance(lead_session_id, str) else ""
+
+
+def is_canonical_journal_frame(input_data: dict) -> bool:
+    """True iff THIS process's journal writes land in the canonical
+    (lead-session) journal: the lead frame in either teammateMode, or an
+    in-process teammate frame (session_id == leadSessionId — one process,
+    one session). False for a tmux teammate frame (distinct session_id)
+    and on ANY resolution failure of the topology leg (unreadable team
+    config, missing session_id): skipping defers durability to the
+    completion-time seams — never worse than the shipped baseline — while
+    emitting from a misclassified frame could silo the event AND poison
+    the shared content-hash marker namespace, suppressing a later
+    canonical emit. The is_lead leg is independent of config readability,
+    so lead-written keys keep full both-modes coverage even when the
+    topology leg cannot resolve. Never raises.
+    """
+    try:
+        if is_lead(input_data):
+            return True
+        sid = input_data.get("session_id")
+        if not (isinstance(sid, str) and sid):
+            # Missing/non-string session_id: topology unresolvable — skip
+            # before paying the config read.
+            return False
+        # Team resolution goes through this module's own identity-matched
+        # resolver (fail-closed empty on an unknown team, which routes the
+        # helper to its "" return and this leg to False).
+        #
+        # DELIBERATE SPLIT — do not unify with the callers' team resolution.
+        # The per-write emit legs (task_lifecycle_gate) resolve their
+        # team_name ONCE from the persisted ctx SSOT
+        # (get_pact_context()["team_name"]) and use it for task reads +
+        # marker namespacing, because the dedup namespace must stay
+        # internally CONSISTENT across every seam that shares those markers
+        # (all gate seams use the same persisted value). THIS predicate
+        # instead answers a session-topology question — "does my session_id
+        # match the REAL platform team's leadSessionId?" — which requires
+        # the identity-ALIGNED resolver: after a resume-divergence the
+        # persisted name can point at a config whose leadSessionId is
+        # stale/wrong, flipping the topology answer. Re-pointing the emit
+        # path to the aligned resolver would fragment the marker namespace
+        # against the pre-existing seams (duplicate events); re-pointing
+        # this predicate to the persisted value would mis-answer topology
+        # after divergence. Divergent outcomes are bounded (skip or
+        # duplicate emit — bias-to-preservation, never a lost canonical
+        # emit), which is why the split is safe as well as intentional.
+        lead_session_id = _read_lead_session_id(get_team_name())
+        return bool(lead_session_id) and sid == lead_session_id
+    except Exception:
+        return False
+
+
 def _iter_members(
     team_name: str,
     teams_dir: str | None = None,

pact-plugin/hooks/shared/session_registry.py

@@ -355,9 +355,11 @@ def _read_lead_session_id(team: str) -> str:
 
     Used by ``register()``'s in-process self-guard to compute the runtime
     structural topology signal ``own session_id == leadSessionId`` (in-process)
-    vs ``!=`` (tmux). LOGIC-PARITY with ``task_claim_gate._read_lead_session_id``,
-    INLINED here (not imported) to preserve this module's self-contained-leaf
-    invariant (no ``shared.*`` imports — see module docstring). Reuses the exact
+    vs ``!=`` (tmux). LOGIC-PARITY with the SSOT copy,
+    ``pact_context._read_lead_session_id`` (which ``task_claim_gate`` also
+    imports rather than duplicating), INLINED here (not imported) to preserve
+    this module's self-contained-leaf invariant (no ``shared.*`` imports — see
+    module docstring). Reuses the exact
     ``_is_safe_team_segment`` guard + ``_config_root()`` config-read idiom that
     ``_name_is_team_member`` above already uses, so the read adds no new I/O
     machinery.

pact-plugin/hooks/shared/task_metadata_snapshot.py

@@ -62,6 +62,40 @@
 # exclude set stays minimal by design.
 SNAPSHOT_EXCLUDE: frozenset[str] = frozenset({"handoff"})
 
+# Keys whose WRITE (TaskCreate/TaskUpdate delta) triggers an immediate
+# whole-payload mirror — the open-task-consumed class that a status-blind
+# whole-store drain destroys while load-bearing (mid-arc readers consume
+# these via TaskGet while the task is still open). The fire predicate is
+# targeted-key-in-delta; the payload is always the full overlay (never a
+# projection), so cross-seam content-hash dedup stays coherent with the
+# completion-time seams. Disjoint from SNAPSHOT_EXCLUDE by test-pinned
+# invariant. NOT here: "variety" (already per-write-mirrored at its write
+# point by the dispatch_variety emit); "intentional_wait" (rides along in
+# the overlay; a wait-only write is not load-bearing alone).
+#
+# The audit pair is targeted for the same reasons as teachback_submit:
+# audit_summary (the auditor's live verdict) and audit_summary_authored
+# (the overwrite-protection mirror of the authored verdict) are consumed
+# by the lead at CODE-phase close while the audited task is still OPEN,
+# so a status-blind whole-store drain destroys them exactly while
+# load-bearing (a prior drain lost live audit verdicts mid-arc). Both are
+# teammate-written-class keys (the auditor writes from a teammate frame),
+# so they carry the same canonical-frame tmux asymmetry as
+# teachback_submit: in-process frames mirror per-write; a tmux teammate
+# frame defers to the completion seams. audit_summary_authored rides the
+# overlay whenever audit_summary fires (the gate's own writeback lands
+# before the leg's disk read), but stays targeted in its own right so a
+# direct write of the mirror alone is durability-covered too.
+PER_WRITE_MIRROR_KEYS: frozenset[str] = frozenset({
+    "scope_contract",
+    "nesting_depth",
+    "worktree_path",
+    "teachback_submit",
+    "teachback_rejection",
+    "audit_summary",
+    "audit_summary_authored",
+})
+
 # Size caps on the canonical serialization (see _canonical_bytes). Empirics
 # over the full journal/task-file population found the largest real value at
 # ~10 KB and no journal event ever ≥ 32 KB, so both caps are anomaly paths:

pact-plugin/hooks/task_claim_gate.py

@@ -92,7 +92,6 @@
 import json
 import os
 import sys
-from pathlib import Path
 
 _SUPPRESS_OUTPUT = json.dumps({"suppressOutput": True})
 
@@ -111,6 +110,12 @@
 # catch keeps the exit code clean (0) and the output well-formed.
 try:
     import shared.pact_context as pact_context
+    # SSOT delegation: the shared _read_lead_session_id implementation lives
+    # in shared.pact_context (session_registry keeps the one remaining inline
+    # copy, forced by its self-contained-leaf invariant). The from-import
+    # binds the name as THIS module's attribute, preserving the test seam
+    # that monkeypatches task_claim_gate._read_lead_session_id.
+    from shared.pact_context import _read_lead_session_id
     from shared.session_registry import resolve as registry_resolve
     from shared.task_utils import (
         iter_team_task_jsons,
@@ -200,44 +205,6 @@ def _stdin_team(stdin: dict) -> str:
     return team if isinstance(team, str) else ""
 
 
-def _read_lead_session_id(team_name: str, teams_dir: str | None = None) -> str:
-    """Read the top-level ``leadSessionId`` from
-    ``~/.claude/teams/{team_name}/config.json``.
-
-    Mirrors the guarded-read shape of ``pact_context._iter_members``
-    (try/except → default) — net-new read; no hook reads ``leadSessionId``
-    today. Returns "" on any of: unsafe team_name, missing/unreadable file,
-    malformed JSON, non-object top-level, or a missing/non-string key. An empty
-    return routes the caller to the fail-safe in-process/NO-OP default. Never
-    raises.
-
-    CURRENCY DEPENDENCY (the in-process/tmux topology compare rests on this):
-    in-process safety assumes ``config.leadSessionId`` is CURRENT. A STALE value
-    — e.g. after a session resume where the team config retains a prior session's
-    id — could make the caller's ``session_id == leadSessionId`` compare
-    MISCLASSIFY an in-process frame as tmux (or vice-versa). Blast radius is
-    BOUNDED and benign: the discriminator is coordination-only (all frames are the
-    same OS user; no privilege boundary), and the worst misclassification outcome
-    is a benign ``pending → in_progress`` auto-flip of the teammate's OWN
-    owned-unblocked-pending task (in-process misread as tmux) — the very action
-    the teammate was supposed to take — or a missed nudge (tmux misread as
-    in-process). The ``owner == confident_name`` conjunction still bounds it to
-    the resolved teammate's task; no wrong-teammate flip, no escalation.
-    """
-    if not is_safe_path_component(team_name):
-        return ""
-    if teams_dir:
-        config_path = Path(teams_dir) / team_name / "config.json"
-    else:
-        config_path = get_claude_config_dir() / "teams" / team_name / "config.json"
-    try:
-        data = json.loads(config_path.read_text(encoding="utf-8"))
-        lead_session_id = data.get("leadSessionId")
-    except (OSError, json.JSONDecodeError, ValueError, AttributeError, TypeError):
-        return ""
-    return lead_session_id if isinstance(lead_session_id, str) else ""
-
-
 # ─── claim-candidate predicates ──────────────────────────────────────────────
 
 
@@ -453,6 +420,15 @@ def _evaluate(stdin: dict) -> str | None:
         return None  # cannot locate config → fail-safe NO-OP
 
     # ── Step 3: topology discriminator (the final D3 signal — a config read) ──
+    # CURRENCY (this gate's blast-radius bound; the generic currency note lives
+    # on the shared helper): the compare below assumes config.leadSessionId is
+    # CURRENT. A stale value (e.g. after a session resume) can misclassify an
+    # in-process frame as tmux or vice-versa — bounded and benign HERE: the
+    # worst outcome is a benign pending→in_progress auto-flip of the teammate's
+    # OWN owned-unblocked-pending task (the very action it was supposed to
+    # take) or a missed nudge. The owner == confident_name conjunction bounds
+    # it to the resolved teammate's task; no wrong-teammate flip, no
+    # escalation.
     lead_session_id = _read_lead_session_id(team_name)
     if not lead_session_id:
         # ASYMMETRY (design note): an UNKNOWN topology (config unreadable / no