fix(journal): unify empty-team dedup posture via session-dir marker fallback (#1169) (#1171)

* feat(journal): session-dir marker fallback for empty-team snapshot dedup

Empty-team frames previously fail-opened past the shared content-hash
dedup marker (degenerate guard returns no target), making every eligible
snapshot emit unconditional. Anchor the fallback marker root at the
session dir — resolvable by construction whenever the journal is — so
dedup resolvability equals journal resolvability. Two-root scheme:
healthy-team markers do not move (default root_dir=None is byte-identical).

- agent_handoff_marker: keyword-only root_dir plumbing; guard/pin flow
  stays single-copy; falsy or non-absolute root fails open as before
- task_metadata_snapshot: _snapshot_marker_root policy helper consumed by
  both hard-bound wrappers (claim/rollback root symmetry by construction)
- pact_context: docstring note on the effective deferral target
- verification tests: fallback claim/suppress, two-root regression pin,
  defer-before-claim, degenerate root fail-open

* test(journal): bidirectional certification for empty-team session-dir dedup fallback

Seam-level cert suite (19 tests) coexisting with the substrate-surface
verification file — one assertion per behavior across the two files:

- close direction: per-write emit through the real gate path on an
  empty-team lead frame (delta-only payload pinned), symlink fault
  fails open with a recovery control leg, changed payload supersedes
- open direction: identical repeat suppressed to one event, cross-seam
  dedup on the shared namespace, compensating unclaim under both
  append-failure shapes (claim/rollback root parity)
- both-modes standing gate: lead emits+claims under the session root;
  in-process and tmux teammate frames stay fail-closed, keyed on
  structural signals only
- guard-order pin: non-str team_name with degenerate task_id fails
  open instead of raising

Non-vacuity proven by source-only revert (21 fail / 4 pass, passes are
the unchanged-behavior pins) plus a predicate-force-open probe for the
fail-closed matrix rows. Full suite: 11004 passed, 0 failed, 0 errors.

* chore: bump plugin version to 4.6.4

* fix(journal): materialize fallback marker base at 0o700

The fallback claim's mkdir gave only the namespace leaf 0o700; a
not-yet-materialized session dir was created as a mkdir parent at
umask default, diverging from every other session-dir creator. Pre-
create the base branch-locally (after the falsy/non-absolute guard,
before the marker-dir join); OSError refuses to a fail-open emit,
matching the shared flow's failure posture. exist_ok never chmods a
pre-existing base — pinned under explicit umask control alongside a
red-first mode pin.

* test(journal): pin healing-transition cost at exactly one duplicate

Team empty-to-healed with identical content: the healed emit appends
(never suppresses the canonical event) and claims under the team root
while the session-root marker population stays disjoint on disk; a
further healed identical emit is suppressed, bounding the transition
at one duplicate. Falsifier verified: an always-session-root neuter
flips the never-suppression assertion.

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.3",
+      "version": "4.6.4",
       "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.3/       # Plugin version
+│               └── 4.6.4/       # Plugin version
 │                   ├── agents/
 │                   ├── commands/
 │                   ├── skills/

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

@@ -1,6 +1,6 @@
 {
   "name": "PACT",
-  "version": "4.6.3",
+  "version": "4.6.4",
   "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.3
+> **Version**: 4.6.4
 
 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/hooks/shared/agent_handoff_marker.py

@@ -157,6 +157,7 @@ def _resolve_marker_target(
     occupant: str,
     *,
     namespace: str = _DEFAULT_MARKER_NAMESPACE,
+    root_dir: "str | Path | None" = None,
 ) -> "tuple[int | None, str | None]":
     """
     Sanitize + validate + pin the marker directory; return the open directory
@@ -169,6 +170,16 @@ def _resolve_marker_target(
     sites is the #877/#878 parallel-path-rot class — a single derivation makes
     alignment structural rather than a convention two sites must each remember.
 
+    root_dir (keyword-only, default None) is a caller-owned root override:
+    when provided, team_name is IGNORED (the caller owns root policy) and the
+    marker dir becomes {root_dir}/{namespace} with root_dir itself as the
+    containment base. A falsy or non-absolute root_dir is treated as "no
+    valid target" (same fail-open signal as a degenerate team). The default
+    None keeps the team-scoped derivation byte-identical to the pre-override
+    behavior. Only the (marker_dir, containment base) selection branches —
+    the guard/pin flow below is single-copy for both roots, so the override
+    cannot diverge from the team path's symlink/TOCTOU/dir_fd hazards.
+
     Returns (dir_fd, filename) on success — the caller MUST os.close(dir_fd).
     Returns (None, None) on any degenerate-key / symlink / containment /
     resolution failure; the caller fail-opens (already_emitted → emit;
@@ -179,42 +190,67 @@ def _resolve_marker_target(
     to the fd, cannot be redirected through a symlinked directory swapped in
     after this resolution.
     """
-    # Centralized normalization (SSOT): case-fold + sanitize team_name HERE so
-    # every caller derives a BYTE-IDENTICAL marker dir regardless of what it
-    # passed in — b1 (agent_handoff_emitter) pre-lowercases for its
-    # read_task_json path, b2 (task_lifecycle_gate) does not; folding .lower()
-    # in here makes the two structurally identical and closes the dormant
-    # case-drift (the #887 divergence shape one level up). Idempotent w.r.t.
-    # b1's external .lower(). The normalized value flows into BOTH _marker_dir()
-    # and the TOCTOU team_base below, keeping the containment check consistent.
-    team_name = sanitize_path_component(team_name.lower())
     task_id = sanitize_path_component(task_id)
     occupant = sanitize_path_component(occupant)
 
     # Degenerate post-sanitization values collapse the marker path onto an
-    # existing directory:
-    #   _marker_dir(".")  → .../teams/./.agent_handoff_emitted
-    #   _marker_dir("..") → .../teams/../.agent_handoff_emitted
-    # For the filename, the composite key f"{task_id}-{occupant}" no longer
-    # collapses on a degenerate task_id alone ("." → ".-<hash>", a normal
-    # file) — but the task_id guard is retained for defense + behavioral
-    # parity with the pre-occupant key, and a missing occupant (only possible
-    # if a caller bypasses occupant_hash()) is treated as "no valid key".
-    # In every degenerate case: signal "no valid target" so the caller
-    # fail-opens (already_emitted emits rather than suppresses; unclaim no-ops).
-    if (
-        not team_name
-        or team_name in (".", "..")
-        or not task_id
-        or task_id in (".", "..")
-        or not occupant
-    ):
+    # existing directory (see the team guard below for the dir-collapse
+    # shape). For the filename, the composite key f"{task_id}-{occupant}" no
+    # longer collapses on a degenerate task_id alone ("." → ".-<hash>", a
+    # normal file) — but the task_id guard is retained for defense +
+    # behavioral parity with the pre-occupant key, and a missing occupant
+    # (only possible if a caller bypasses occupant_hash()) is treated as "no
+    # valid key". These key guards apply under EITHER root. In every
+    # degenerate case: signal "no valid target" so the caller fail-opens
+    # (already_emitted emits rather than suppresses; unclaim no-ops).
+    if not task_id or task_id in (".", "..") or not occupant:
         return None, None
 
-    marker_dir = _marker_dir(team_name, namespace=namespace)
+    if root_dir is None:
+        # Centralized normalization (SSOT): case-fold + sanitize team_name
+        # HERE so every caller derives a BYTE-IDENTICAL marker dir regardless
+        # of what it passed in — b1 (agent_handoff_emitter) pre-lowercases
+        # for its read_task_json path, b2 (task_lifecycle_gate) does not;
+        # folding .lower() in here makes the two structurally identical and
+        # closes the dormant case-drift (the #887 divergence shape one level
+        # up). Idempotent w.r.t. b1's external .lower(). The normalized value
+        # flows into BOTH _marker_dir() and the TOCTOU containment base,
+        # keeping the containment check consistent.
+        #
+        # Degenerate team values collapse the marker path onto an existing
+        # directory:
+        #   _marker_dir(".")  → .../teams/./.agent_handoff_emitted
+        #   _marker_dir("..") → .../teams/../.agent_handoff_emitted
+        team_name = sanitize_path_component(team_name.lower())
+        if not team_name or team_name in (".", ".."):
+            return None, None
+        marker_dir = _marker_dir(team_name, namespace=namespace)
+        base = get_claude_config_dir() / "teams" / team_name
+    else:
+        # Caller-owned root: team_name is ignored (root policy lives with
+        # the caller). A falsy or relative root cannot anchor a containment
+        # check → no valid target, fail-open.
+        if not root_dir or not Path(root_dir).is_absolute():
+            return None, None
+        base = Path(root_dir)
+        # Pre-create the base itself at 0o700 when absent: the shared mkdir
+        # below applies mode= to the FINAL component (the namespace dir)
+        # only, so parents it creates get umask-default permissions — a
+        # claim that materializes a missing base (e.g. a session dir the
+        # journal writer has not created yet) would otherwise leave it
+        # looser than every other creator, which mkdirs the base as its own
+        # 0o700 leaf. exist_ok keeps an already-present base's mode
+        # untouched; on failure, refuse the target (fail-open emit),
+        # consistent with the shared mkdir's OSError posture below.
+        try:
+            base.mkdir(parents=True, exist_ok=True, mode=0o700)
+        except OSError:
+            return None, None
+        marker_dir = base / namespace
+
     # Symlink-containment pre-check: if marker_dir already exists as a
     # symlink, refuse to use it (a pre-planted symlink could redirect marker
-    # creation outside the team directory). Fail-open emit rather than risk
+    # creation outside the containment base). Fail-open emit rather than risk
     # writing to an attacker-controlled location.
     if marker_dir.is_symlink():
         return None, None
@@ -226,19 +262,18 @@ def _resolve_marker_target(
 
     # TOCTOU containment re-check (closes the window between the is_symlink()
     # pre-check above and this mkdir): a symlink race could swap marker_dir
-    # to a directory OUTSIDE the team base between the two operations, and
-    # mkdir(exist_ok=True) silently follows an existing symlink. Re-resolve
-    # both paths and verify marker_dir is still contained within the team
-    # base. commonpath (not str.startswith — defeats the /teams/foo vs
+    # to a directory OUTSIDE the containment base between the two operations,
+    # and mkdir(exist_ok=True) silently follows an existing symlink.
+    # Re-resolve both paths and verify marker_dir is still contained within
+    # the base. commonpath (not str.startswith — defeats the /teams/foo vs
     # /teams/foobar prefix-collision) is the robust containment test; chosen
     # over Path.is_relative_to because pyproject pins requires-python >=3.7
     # and is_relative_to is 3.9+. On breach OR any resolution error: fail-open
     # emit (return None) WITHOUT writing a marker at the escaped path —
     # consistent with the is_symlink() pre-check's fail-open posture.
-    team_base = get_claude_config_dir() / "teams" / team_name
     try:
         real_marker = os.path.realpath(marker_dir)
-        real_base = os.path.realpath(team_base)
+        real_base = os.path.realpath(base)
         if os.path.commonpath([real_marker, real_base]) != real_base:
             return None, None
     except (OSError, ValueError):
@@ -273,10 +308,15 @@ def already_emitted(
     occupant: str,
     *,
     namespace: str = _DEFAULT_MARKER_NAMESPACE,
+    root_dir: "str | Path | None" = None,
 ) -> bool:
     """
     Test-and-set the per-(team, task_id, occupant) marker.
 
+    root_dir is a caller-policy root override (see _resolve_marker_target),
+    resolved through the same SSOT as unclaim() so the claim and the rollback
+    can never diverge.
+
     Returns True iff a prior fire for the same key already created the marker
     (caller should suppress the journal write). Returns False on fresh fires —
     the marker is created as a side-effect of this call, making the
@@ -308,7 +348,7 @@ def already_emitted(
     process claimed but whose journal write then failed) — see unclaim().
     """
     dir_fd, filename = _resolve_marker_target(
-        team_name, task_id, occupant, namespace=namespace
+        team_name, task_id, occupant, namespace=namespace, root_dir=root_dir
     )
     if dir_fd is None:
         # Degenerate key / symlink-guarded / unresolvable → fail-open emit.
@@ -337,6 +377,7 @@ def unclaim(
     occupant: str,
     *,
     namespace: str = _DEFAULT_MARKER_NAMESPACE,
+    root_dir: "str | Path | None" = None,
 ) -> None:
     """
     Compensating rollback (#901, R1) — remove the marker THIS process just
@@ -346,6 +387,10 @@ def unclaim(
     suppresses every later fire for the key forever (the silent-permanent-loss
     residual the writability gate only narrowed, not closed).
 
+    root_dir is a caller-policy root override (see _resolve_marker_target),
+    resolved through the same SSOT as already_emitted() so the rollback can
+    never target a root that diverges from the claim.
+
     Caller contract: invoke ONLY when this process OWNS the marker — i.e.
     already_emitted() returned False on THIS fire (a fresh O_EXCL create).
     Calling it after a True (prior-fire-owns) result could remove a marker a
@@ -363,7 +408,7 @@ def unclaim(
     marker) — strictly no worse than not having the rollback. Never raises.
     """
     dir_fd, filename = _resolve_marker_target(
-        team_name, task_id, occupant, namespace=namespace
+        team_name, task_id, occupant, namespace=namespace, root_dir=root_dir
     )
     if dir_fd is None:
         return

pact-plugin/hooks/shared/pact_context.py

@@ -954,7 +954,11 @@ def is_canonical_journal_frame(input_data: dict) -> bool:
     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,
+    canonical emit. On an empty-team frame the teammate-completion seams
+    starve by construction (no team namespace to read task state from),
+    so the effective deferral target is the lead-completion seam, whose
+    snapshot substrate dedups under the session-dir marker root when the
+    team is empty. 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.
     """

pact-plugin/hooks/shared/task_metadata_snapshot.py

@@ -28,9 +28,12 @@
 Supersession: multiple snapshots per task are legal — a changed payload
 after completion re-emits under a new content key; an unchanged payload
 never re-emits (the content-keyed O_EXCL marker dedups across all seams).
-Readers take latest-ts within the (task_id, occupant) group; the occupant
-field is the task-id-reuse discriminator (platform reuses task ids across
-arcs within one team).
+The content-key marker claims under the team root, or under the session-dir
+root when team_name is empty (dedup-resolvable ⇔ journal-resolvable — both
+derive from the same session context, so an emit that can reach the journal
+can always claim its dedup marker). Readers take latest-ts within the
+(task_id, occupant) group; the occupant field is the task-id-reuse
+discriminator (platform reuses task ids across arcs within one team).
 
 Size-bounding invariant: key EXISTENCE is never silently lost — worst case
 a key survives name-only in the payload's top-level "_dropped_keys" list.
@@ -52,6 +55,7 @@
     sanitize_path_component,
     unclaim,
 )
+from .pact_context import get_session_dir
 from .session_journal import append_event, get_journal_path, make_event
 
 # Keys never mirrored: only entries with equivalent-or-better journal
@@ -110,6 +114,23 @@
 # other. Module constant, never input-derived.
 SNAPSHOT_MARKER_NAMESPACE: str = ".task_metadata_snapshot_emitted"
 
+
+def _snapshot_marker_root(team_name: str) -> str | None:
+    """Marker-root policy for the snapshot family (the ONE place it lives).
+
+    Non-empty team -> None (default team-scoped root, path-identical to
+    the pre-fallback behavior). Empty team -> the session directory, so
+    dedup resolvability is equal-by-construction to journal resolvability
+    (get_journal_path derives from the same get_session_dir); the
+    "empty team + resolvable journal" fail-open gap cannot reopen. An
+    unresolvable session dir returns "" — the resolver treats a falsy
+    root as no-valid-target and fail-opens, which the emit path never
+    reaches (its writability precondition already returned).
+    """
+    if team_name:
+        return None
+    return get_session_dir()
+
 # Marker-dict key set used to recognize truncation markers this module
 # itself produced (stage-2 candidate filtering + stage-3 head emptying).
 _MARKER_KEYS = frozenset({"_truncated", "original_bytes", "head"})
@@ -341,21 +362,33 @@ def snapshot_already_emitted(
     marker functions: a forgotten namespace arg would claim in one dir and
     no-op-unclaim against the other, leaving a poisoned marker; the wrapper
     makes that impossible by construction.
+
+    The marker root is likewise hard-bound: it comes from
+    _snapshot_marker_root, the family's single root-policy site, so the
+    claim and the rollback derive the same root by construction.
     """
     return already_emitted(
-        team_name, task_id, content_key, namespace=SNAPSHOT_MARKER_NAMESPACE
+        team_name,
+        task_id,
+        content_key,
+        namespace=SNAPSHOT_MARKER_NAMESPACE,
+        root_dir=_snapshot_marker_root(team_name),
     )
 
 
 def snapshot_unclaim(team_name: str, task_id: str, content_key: str) -> None:
     """Compensating rollback for a claim whose journal write failed.
 
     Hard-bound twin of snapshot_already_emitted — same namespace constant,
-    same resolver SSOT underneath, so the claim and the rollback can never
-    reference divergent paths.
+    same root policy (_snapshot_marker_root), same resolver SSOT underneath,
+    so the claim and the rollback can never reference divergent paths.
     """
     unclaim(
-        team_name, task_id, content_key, namespace=SNAPSHOT_MARKER_NAMESPACE
+        team_name,
+        task_id,
+        content_key,
+        namespace=SNAPSHOT_MARKER_NAMESPACE,
+        root_dir=_snapshot_marker_root(team_name),
     )