@event4u/agent-config 14.4.0 → 14.5.0

package/src/scripts/hooks/run_continuation_hook.ts

@@ -51,6 +51,12 @@
  *   checkbox delta)            → allow            (event: halt-stall)
  *   otherwise                  → BLOCK + continue (event: engage)
  *
+ * Every event this concern writes carries `workspace_root`, `git_dir`,
+ * `git_common_dir` and `claim_path` — the two-tree provenance, per
+ * `provenance()` below. Without them the ledger records that an engagement
+ * happened but not that it crossed the tree boundary the fix was about, and
+ * crossing it is the whole claim.
+ *
  * Stall counts CONSECUTIVE ENGAGEMENTS whose open-step count did not move.
  * The upstream stalls on 5-of-5 completed-count readings; AC's checkbox
  * signal is finer-grained (a step in progress usually flips SOMETHING), so
@@ -88,7 +94,8 @@ import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { is_replay_mode } from './state_io.js';
 import { readTranscriptTail } from './turn_end_gate_hook.js';
-import { read_claimed_slug } from '../session_register_hook.js';
+import { resolve_claim } from '../session_register_hook.js';
+import { git_common_dir, git_dir } from '../_lib/git_common_dir.js';
 import {
     deriveSessionKey,
     parseRecord,
@@ -386,6 +393,48 @@ function readState(file: string): RunState | null {
     }
 }
 
+/**
+ * The four fields that make an event's two-tree property checkable by a third
+ * party holding nothing but the ledger line.
+ *
+ * The defect this concern shipped with was a writer and a reader resolving
+ * DIFFERENT trees: `sessions:claim` wrote under `process.cwd()` (the operator's
+ * worktree) while this concern read under `--project-dir` (the parent
+ * checkout), so the claim was never found and no event was written. An empty
+ * ledger looked exactly like a healthy idle run, which is how it survived a
+ * release.
+ *
+ * A reader therefore has to see, from the line alone, which trees were in play
+ * and where the contract was actually read out of. A boolean such as
+ * `worktree_started: true` would be another assertion by the system under
+ * observation rather than a check on it; the falsifiable facts are concrete
+ * (AI council 2026-08-19, 2/2 convergent):
+ *
+ *   `git_dir !== git_common_dir`        → this IS a linked worktree
+ *   `claim_path` under `git_common_dir` → the contract crossed into the shared
+ *                                         root, which is the fix working
+ *
+ * `process.cwd()` is deliberately NOT among them. The dispatcher chdirs into
+ * `--project-dir` before the chain runs, so at concern time cwd equals
+ * `workspace_root` on every shipped path — a field that can never disagree with
+ * another cannot falsify anything, and shipping it as provenance would be the
+ * decorative-evidence shape this whole change exists to remove. Measured while
+ * writing the test that asserted the opposite.
+ *
+ * Absolute paths, deliberately: a relative form is interpreted against whichever
+ * root the reader happens to hold, which is the exact ambiguity being removed.
+ * These are local filesystem paths in gitignored runtime state, never published
+ * — the same posture the session register already takes.
+ */
+export function provenance(workspaceRoot: string, claimPath: string): JsonObject {
+    return {
+        workspace_root: workspaceRoot,
+        git_dir: git_dir(workspaceRoot) ?? '',
+        git_common_dir: git_common_dir(workspaceRoot) ?? '',
+        claim_path: claimPath,
+    };
+}
+
 function appendEvent(workspaceRoot: string, record: JsonObject): void {
     try {
         const file = path.join(workspaceRoot, EVENTS_RELPATH);
@@ -438,8 +487,12 @@ export function main(): number {
         str(envelope['session_id'] as JsonValue | undefined);
 
     // ── contract gate ────────────────────────────────────────────────
-    const slug = read_claimed_slug(workspaceRoot, sessionId || null);
-    if (slug === null) return EXIT_ALLOW;
+    const claim = resolve_claim(workspaceRoot, sessionId || null);
+    if (claim === null) return EXIT_ALLOW;
+    const slug = claim.slug;
+    // The two-root provenance, carried on every event this run emits. See
+    // `provenance()` for why these three and not a boolean.
+    const roots = provenance(workspaceRoot, claim.path);
 
     const roadmapPath = path.join(workspaceRoot, 'agents', 'roadmaps', `${slug}.md`);
     let roadmapText: string;
@@ -491,6 +544,7 @@ export function main(): number {
             roadmap: slug,
             turn: turnOrdinal,
             at: new Date().toISOString(),
+            ...roots,
         });
         return EXIT_ALLOW;
     }
@@ -529,6 +583,7 @@ export function main(): number {
             open: scan.open,
             blocked: scan.blocked,
             at: new Date().toISOString(),
+            ...roots,
         });
         if (action === 'complete') {
             // Only a COMPLETION clears the state, so a later run on the same
@@ -580,6 +635,7 @@ export function main(): number {
         open: scan.open,
         blocked: scan.blocked,
         at: new Date().toISOString(),
+        ...roots,
     });
 
     process.stderr.write(_continuationText(slug, scan, state.iterations));

package/src/scripts/session_register_hook.ts

@@ -237,7 +237,23 @@ function _read_claim_file(file: string): RoadmapClaim | null {
 }
 
 /**
- * The roadmap slug THIS session has claimed, or `null`. Never throws.
+ * A resolved claim plus the file it was actually read from.
+ *
+ * The path is not decoration. The defect this whole surface exists to prevent
+ * was a WRITER and a READER resolving different trees, and the only fact that
+ * falsifies it is the concrete pair of roots — a boolean asserting "worktree
+ * started" is another claim by the system under observation, not a check on it
+ * (AI council 2026-08-19, 2/2, on the run-continuation observation).
+ */
+export interface ResolvedClaim {
+    slug: string;
+    /** Absolute path of the claim file this read came from. */
+    path: string;
+}
+
+/**
+ * The roadmap slug THIS session has claimed, and the file it came from — or
+ * `null`. Never throws.
  *
  * Two reads, in order, and the second one is why a peer's claim can no longer be
  * inherited: the per-session file first, then the legacy per-worktree file —
@@ -246,14 +262,14 @@ function _read_claim_file(file: string): RoadmapClaim | null {
  * that session's claim, and reading it as this session's is exactly the defect
  * that put one archived slug on four live records.
  */
-export function read_claimed_slug(
+export function resolve_claim(
     workspace_root: string,
     // REQUIRED, on the reviewer's point: an optional id means a caller that forgets
     // it silently gets legacy semantics instead of a type error, and there is
     // exactly one call site that matters (`build_record`). `null` stays a legal
     // value — it is the host-exports-nothing case — but it has to be passed.
     session_id: string | null,
-): string | null {
+): ResolvedClaim | null {
     const own = roadmap_claim_rel(session_id);
     if (own !== ROADMAP_CLAIM_REL) {
         // Per-session, shared dir first, then the pre-fix per-tree path. The
@@ -262,16 +278,20 @@ export function read_claimed_slug(
         for (const p of claim_read_paths(workspace_root, session_id)) {
             if (path.basename(p) === path.basename(ROADMAP_CLAIM_REL)) continue;
             const mine = _read_claim_file(p);
-            if (mine !== null) return mine.slug;
+            if (mine !== null) return { slug: mine.slug, path: p };
         }
     }
     // The legacy per-WORKTREE file, in the same two locations. Unchanged in
     // meaning: it is a claim on the checkout, not on a session.
     let legacy: RoadmapClaim | null = null;
+    let legacy_path = '';
     for (const p of claim_read_paths(workspace_root, session_id)) {
         if (path.basename(p) !== path.basename(ROADMAP_CLAIM_REL)) continue;
         legacy = _read_claim_file(p);
-        if (legacy !== null) break;
+        if (legacy !== null) {
+            legacy_path = p;
+            break;
+        }
     }
     if (legacy === null) {
         return null;
@@ -293,7 +313,21 @@ export function read_claimed_slug(
     if (id !== '') {
         return null;
     }
-    return legacy.slug;
+    return { slug: legacy.slug, path: legacy_path };
+}
+
+/**
+ * The roadmap slug THIS session has claimed, or `null`. Never throws.
+ *
+ * Thin projection of `resolve_claim` — kept because every existing caller wants
+ * the slug alone, and widening their return type to carry a path none of them
+ * reads would be a signature change for no consumer.
+ */
+export function read_claimed_slug(
+    workspace_root: string,
+    session_id: string | null,
+): string | null {
+    return resolve_claim(workspace_root, session_id)?.slug ?? null;
 }
 
 /**