@tech-leads-club/harness-toolkit 0.10.5 → 0.11.0

package/src/core/handoff/handoff.types.ts

@@ -15,7 +15,6 @@ export type HandoffShared = {
 
 export type HandoffProviderSlice = {
   updated_at: string;
-  session_key?: string;
   session_narrative?: string;
   completed?: string[];
   last_ship_claim_at?: string;
@@ -46,12 +45,13 @@ export type HandoffProviderSlice = {
   machine_state?: Record<string, unknown>;
 };
 
-export const HANDOFF_SCHEMA = "harness.handoff.v2" as const;
+export const HANDOFF_SCHEMA = "harness.handoff.v3" as const;
 
+/** The project-wide facts every session shares — no turn-scoped continuity here (moved to per-session files,
+ * [/decisions/ad-122.md](/decisions/ad-122.md)). */
 export type HandoffFile = {
   schema: typeof HANDOFF_SCHEMA;
   shared: HandoffShared;
-  by_provider: Record<string, HandoffProviderSlice>;
 };
 
 export type ForeignSlice = {
@@ -68,7 +68,6 @@ export function defaultHandoffFile(mode: OperatorMode = "solo"): HandoffFile {
   return {
     schema: HANDOFF_SCHEMA,
     shared: { mode, updated_at: new Date().toISOString() },
-    by_provider: {},
   };
 }
 
@@ -78,10 +77,44 @@ export function isHandoffFile(value: unknown): value is HandoffFile {
   }
   const candidate = value as Partial<HandoffFile>;
   return (
-    candidate.schema === HANDOFF_SCHEMA &&
-    typeof candidate.shared === "object" &&
-    candidate.shared !== null &&
-    typeof candidate.by_provider === "object" &&
-    candidate.by_provider !== null
+    candidate.schema === HANDOFF_SCHEMA && typeof candidate.shared === "object" && candidate.shared !== null
+  );
+}
+
+export const HANDOFF_SESSION_SCHEMA = "harness.handoff-session.v1" as const;
+
+/** which session last wrote this continuity file, and when — liveness itself is decided elsewhere, against
+ * presence's own heartbeat, not against anything stored here ([/decisions/ad-122.md](/decisions/ad-122.md)). */
+type HandoffSessionOwner = {
+  session_key: string;
+  provider: string;
+  updated_at: string;
+};
+
+export type HandoffSessionFile = {
+  schema: typeof HANDOFF_SESSION_SCHEMA;
+  owner: HandoffSessionOwner;
+  slice: HandoffProviderSlice;
+};
+
+export function isHandoffSessionFile(value: unknown): value is HandoffSessionFile {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value as Partial<HandoffSessionFile>;
+  if (candidate.schema !== HANDOFF_SESSION_SCHEMA) {
+    return false;
+  }
+  const owner = candidate.owner;
+  if (typeof owner !== "object" || owner === null) {
+    return false;
+  }
+  const o = owner as Partial<HandoffSessionOwner>;
+  return (
+    typeof o.session_key === "string" &&
+    typeof o.provider === "string" &&
+    typeof o.updated_at === "string" &&
+    typeof candidate.slice === "object" &&
+    candidate.slice !== null
   );
 }

package/src/core/policy/policy.defaults.ts

@@ -90,6 +90,9 @@ export const DEFAULTS: Policy = {
     stallDetection: false,
     stallRepeatThreshold: 3,
   },
+  secrets: {
+    redactOutput: true,
+  },
   intelligence: {
     gapFeedback: true,
     failureClassification: true,

package/src/core/policy/policy.loader.ts

@@ -37,6 +37,7 @@ function deepMerge(base: Policy, patch: PartialPolicy): Policy {
     untrustedContent: { ...base.untrustedContent, ...patch.untrustedContent },
     planGate: { ...base.planGate, ...patch.planGate },
     shell: { ...base.shell, ...patch.shell },
+    secrets: { ...base.secrets, ...patch.secrets },
     intelligence: {
       ...base.intelligence,
       ...patch.intelligence,

package/src/core/policy/policy.types.ts

@@ -122,6 +122,9 @@ export type Policy = {
     stallDetection: boolean;
     stallRepeatThreshold: number;
   };
+  secrets: {
+    redactOutput: boolean;
+  };
   intelligence: {
     gapFeedback: boolean;
     failureClassification: boolean;
@@ -148,6 +151,7 @@ export type PartialPolicy = Partial<Policy> & {
   planGate?: Partial<Policy["planGate"]>;
   rules?: Partial<Policy["rules"]>;
   shell?: Partial<Policy["shell"]>;
+  secrets?: Partial<Policy["secrets"]>;
   intelligence?: Partial<Policy["intelligence"]> & {
     lessons?: Partial<LessonsPolicyConfig>;
   };

package/src/core/presence/presence.service.ts

@@ -8,7 +8,17 @@ import {
 } from "./presence.store.ts";
 import type { PresenceRecord } from "./presence.types.ts";
 
-const STALE_MS = 10 * 60 * 1000;
+/** how long a file-edit claim (`checkCollision`'s `recent_files`) survives without a fresh touch — unrelated
+ * to whether the session's own conversation is still open, see `CONVERSATION_STALE_MS`. */
+const CLAIM_STALE_MS = 10 * 60 * 1000;
+
+/** why longer than the claim window: a conversation can sit quiet — reading long output, thinking — for well
+ * past ten minutes without being over, and both `isSessionLive` and `sweepStale` must agree on that same
+ * question so a record is never physically deleted while a reader would still call it live
+ * ([/decisions/ad-122.md](/decisions/ad-122.md)), matching this codebase's own precedent for the same class of
+ * stale-but-alive tolerance (`GATE_LOCK_STALE_MS`, `src/core/gate/gate.lock.ts`). */
+const CONVERSATION_STALE_MS = 30 * 60 * 1000;
+
 const RECENT_FILES_MAX = 20;
 
 export function register(
@@ -29,20 +39,29 @@ export function register(
   return record;
 }
 
+/**
+ * why self-healing: `sweepStale` deletes a record once it looks quiet, but quiet is not the same fact as over —
+ * a session whose next event arrives after that deletion is not a new session, and treating its own heartbeat
+ * as a no-op would leave it misdiagnosed as a dead predecessor by every other reader, permanently, since nothing
+ * else ever re-creates the file. This event is itself proof the conversation is still going, so it is always
+ * enough to (re)establish presence, register() or not ([/decisions/ad-122.md](/decisions/ad-122.md)).
+ */
 export function heartbeat(
   root: string,
   args: { provider: string; session: string; file?: string; now?: Date },
-): PresenceRecord | null {
+): PresenceRecord {
   const existing = readPresenceRecord(root, args.provider, args.session);
-  if (!existing) {
-    return null;
-  }
+  const now = (args.now ?? new Date()).toISOString();
   const recent_files = args.file
-    ? [...existing.recent_files.filter((f) => f !== args.file), args.file].slice(-RECENT_FILES_MAX)
-    : existing.recent_files;
+    ? [...(existing?.recent_files.filter((f) => f !== args.file) ?? []), args.file].slice(-RECENT_FILES_MAX)
+    : (existing?.recent_files ?? []);
   const next: PresenceRecord = {
-    ...existing,
-    heartbeat_at: (args.now ?? new Date()).toISOString(),
+    provider: args.provider,
+    session: args.session,
+    pid: process.pid,
+    branch: existing?.branch ?? "unknown",
+    started_at: existing?.started_at ?? now,
+    heartbeat_at: now,
     recent_files,
   };
   writePresenceRecord(root, next);
@@ -54,8 +73,8 @@ function heartbeatAgeMs(record: PresenceRecord, now: number): number {
   return Number.isNaN(at) ? Number.POSITIVE_INFINITY : now - at;
 }
 
-function isStale(record: PresenceRecord, now: number): boolean {
-  return heartbeatAgeMs(record, now) >= STALE_MS;
+function isStale(record: PresenceRecord, now: number, staleMs: number): boolean {
+  return heartbeatAgeMs(record, now) >= staleMs;
 }
 
 function elapsedLabel(record: PresenceRecord, now: number): string {
@@ -74,7 +93,7 @@ export function checkCollision(
     if (presenceSessionKey(record.provider, record.session) === ownSessionKey) {
       continue;
     }
-    if (isStale(record, nowMs)) {
+    if (isStale(record, nowMs, CLAIM_STALE_MS)) {
       continue;
     }
     if (!record.recent_files.includes(file)) {
@@ -104,7 +123,7 @@ export function checkCollision(
 export function sweepStale(root: string, now: Date = new Date()): number {
   let swept = 0;
   for (const record of listPresenceRecords(root)) {
-    if (isStale(record, now.getTime())) {
+    if (isStale(record, now.getTime(), CONVERSATION_STALE_MS)) {
       deletePresenceRecord(root, record.provider, record.session);
       swept += 1;
     }
@@ -116,4 +135,31 @@ export function release(root: string, provider: string, session: string): void {
   deletePresenceRecord(root, provider, session);
 }
 
+/**
+ * why the session key, not the raw session id: every caller outside this module already carries the prefixed
+ * form (`${provider}-${id}`) — every inbound mapper produces it that way — and asking each one to also derive
+ * the bare id is the duplication a shared helper exists to remove.
+ */
+function sessionIdFromSessionKey(provider: string, sessionKey: string): string {
+  const prefix = `${provider}-`;
+  return sessionKey.startsWith(prefix) ? sessionKey.slice(prefix.length) : sessionKey;
+}
+
+/**
+ * why heartbeat and not a process check: this harness's hook processes are one-shot — every entrypoint calls
+ * `process.exit` at the end of the single event it handled ([/decisions/ad-122.md](/decisions/ad-122.md)) — so
+ * no pid outlives the event that recorded it, and a pid-liveness check answers "dead" for every session,
+ * including one still very much in conversation. A heartbeat refreshed on every recognized event, regardless of
+ * which process handled it, is the one signal that survives the process boundary.
+ */
+export function isSessionLive(
+  root: string,
+  provider: string,
+  sessionKey: string,
+  now: Date = new Date(),
+): boolean {
+  const record = readPresenceRecord(root, provider, sessionIdFromSessionKey(provider, sessionKey));
+  return record !== null && !isStale(record, now.getTime(), CONVERSATION_STALE_MS);
+}
+
 export { listPresenceRecords, presenceSessionKey, readPresenceRecord };

package/src/core/secret-scan/secret-scan.service.ts

@@ -0,0 +1,96 @@
+export type SecretMatch = {
+  start: number;
+  end: number;
+  kind: string;
+};
+
+// invariant: shaped like the real thing, never the real thing — a signature fixture that could pass for a working
+// credential in its own test file would be the exact leak this module exists to catch.
+export const SIGNATURES: Record<string, RegExp> = {
+  "aws-access-key": /\bAKIA[0-9A-Z]{16}\b/g,
+  "github-token": /\bgh[pousr]_[A-Za-z0-9]{36}\b/g,
+  "slack-token": /\bxox[baprs]-[0-9A-Za-z-]{10,72}\b/g,
+  "stripe-key": /\bsk_(?:live|test)_[A-Za-z0-9]{24,}\b/g,
+  "pem-private-key": /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  jwt: /\beyJ[A-Za-z0-9_-]*\.eyJ[A-Za-z0-9_-]*\.[A-Za-z0-9_-]+\b/g,
+};
+
+// why: a run of the base64/hex/token alphabet, long enough to be worth an entropy check at all. Excluding `-` keeps
+// a dash-separated UUID out of this pattern entirely — each of its five segments is shorter than the minimum length
+// below, so it never reaches the entropy test in the first place.
+const ENTROPY_TOKEN_PATTERN = /[A-Za-z0-9+/_=]{20,}/g;
+
+/**
+ * why these numbers: measured against this module's own fixtures (see `__test__`) — a 40-character git commit SHA
+ * scores ~3.8 bits/char (hex alphabet), a hand-picked high-diversity secret-shaped string scores 5.0. 4.5 sits
+ * between them, so a hex-alphabet identifier stays out of the false-positive path while a genuinely high-diversity
+ * token still crosses it. The 20-character floor keeps a short common token from crossing it by chance alone.
+ */
+export const ENTROPY_THRESHOLD = 4.5;
+export const ENTROPY_MIN_LENGTH = 20;
+
+export function shannonEntropy(text: string): number {
+  if (text.length === 0) {
+    return 0;
+  }
+  const counts = new Map<string, number>();
+  for (const ch of text) {
+    counts.set(ch, (counts.get(ch) ?? 0) + 1);
+  }
+  let entropy = 0;
+  for (const count of counts.values()) {
+    const p = count / text.length;
+    entropy -= p * Math.log2(p);
+  }
+  return entropy;
+}
+
+function signatureMatches(text: string): SecretMatch[] {
+  const matches: SecretMatch[] = [];
+  for (const [kind, pattern] of Object.entries(SIGNATURES)) {
+    const regex = new RegExp(pattern.source, pattern.flags);
+    for (const match of text.matchAll(regex)) {
+      if (match.index === undefined) {
+        continue;
+      }
+      matches.push({ start: match.index, end: match.index + match[0].length, kind });
+    }
+  }
+  return matches;
+}
+
+function overlaps(a: { start: number; end: number }, b: { start: number; end: number }): boolean {
+  return a.start < b.end && b.start < a.end;
+}
+
+// why: a signature match (an AWS key, a JWT segment) is already high-entropy by construction, so scanning it
+// again here would report the same secret as two separate spans — checked against `existing` before this runs.
+function entropyMatches(text: string, existing: readonly SecretMatch[]): SecretMatch[] {
+  const matches: SecretMatch[] = [];
+  for (const match of text.matchAll(ENTROPY_TOKEN_PATTERN)) {
+    if (match.index === undefined) {
+      continue;
+    }
+    const span = { start: match.index, end: match.index + match[0].length };
+    if (existing.some((existingMatch) => overlaps(span, existingMatch))) {
+      continue;
+    }
+    if (span.end - span.start < ENTROPY_MIN_LENGTH) {
+      continue;
+    }
+    if (shannonEntropy(match[0]) > ENTROPY_THRESHOLD) {
+      matches.push({ ...span, kind: "entropy" });
+    }
+  }
+  return matches;
+}
+
+// invariant: pure — no I/O, no network call, no subprocess. Every input is a string already in memory.
+export function scanForSecrets(text: string | undefined): SecretMatch[] {
+  if (!text) {
+    return [];
+  }
+  const signature = signatureMatches(text);
+  const entropy = entropyMatches(text, signature);
+  return [...signature, ...entropy].sort((a, b) => a.start - b.start);
+}

package/src/core/secret-scan/secret-scan.store.ts

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { projectStateDir } from "../../platform/paths.ts";
+
+// invariant: keyed by a hash of the matched text, never the raw value — this file is the only durable
+// record of a redaction, so it must not become a second copy of the secret it exists to hide.
+type SecretRedactionStore = {
+  [sessionKey: string]: {
+    [textHash: string]: string;
+  };
+};
+
+function storePath(root: string): string {
+  return join(projectStateDir(root), "secret-redaction.json");
+}
+
+function readStore(root: string): SecretRedactionStore {
+  const path = storePath(root);
+  if (!existsSync(path)) {
+    return {};
+  }
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as SecretRedactionStore;
+  } catch {
+    return {};
+  }
+}
+
+function writeStore(root: string, store: SecretRedactionStore): void {
+  try {
+    mkdirSync(projectStateDir(root), { recursive: true });
+    writeFileSync(storePath(root), `${JSON.stringify(store, null, 2)}\n`, "utf8");
+  } catch {}
+}
+
+function hashOf(matchedText: string): string {
+  return createHash("sha256").update(matchedText).digest("hex").slice(0, 8);
+}
+
+// invariant: the same matchedText within the same session always resolves to the same placeholder, keyed by a
+// hash rather than the raw value.
+export function placeholderFor(root: string, sessionKey: string, matchedText: string, kind: string): string {
+  const store = readStore(root);
+  const session = store[sessionKey] ?? {};
+  const hash = hashOf(matchedText);
+  const existing = session[hash];
+  if (existing !== undefined) {
+    return existing;
+  }
+  const placeholder = `[REDACTED:${kind}:${hash}]`;
+  session[hash] = placeholder;
+  store[sessionKey] = session;
+  writeStore(root, store);
+  return placeholder;
+}

package/src/entrypoints/prompt-submit.ts

@@ -16,7 +16,7 @@ export const promptSubmitHandler: Handler = async (event: HarnessEvent, ctx: Han
   // whole untouched file read as "added this turn" ([/decisions/ad-117.md](/decisions/ad-117.md)).
   const sha = await currentGitSha(shaScopeRoot(event));
   if (sha) {
-    await coreFacade.handoff.patchHandoff(event.projectDir, event.provider, {
+    await coreFacade.handoff.patchHandoff(event.projectDir, event.provider, event.sessionKey, {
       slice: { turn_base_sha: sha },
     });
   }

package/src/entrypoints/response-after.ts

@@ -13,7 +13,7 @@ export const responseAfterHandler: Handler = async (
     const plan = coreFacade.plan.detectPlan(text);
     const deviations = coreFacade.plan.detectDeviations(text);
     if (plan) {
-      await coreFacade.handoff.patchHandoff(event.projectDir, event.provider, {
+      await coreFacade.handoff.patchHandoff(event.projectDir, event.provider, event.sessionKey, {
         slice: {
           plan_paths: plan.paths,
           plan_at: ctx.now.toISOString(),
@@ -25,11 +25,11 @@ export const responseAfterHandler: Handler = async (
     if (deviations.length > 0) {
       // why: a deviation can be justified in a later message than the one that declared the plan, so they
       // accumulate for the plan's window instead of replacing what was already accepted.
-      const handoff = coreFacade.handoff.readHandoff(event.projectDir, event.provider);
+      const handoff = coreFacade.handoff.readHandoff(event.projectDir, event.provider, event.sessionKey);
       const known = handoff.plan_deviations ?? [];
       const fresh = deviations.filter((deviation) => !known.some((seen) => seen.path === deviation.path));
       if (fresh.length > 0) {
-        await coreFacade.handoff.patchHandoff(event.projectDir, event.provider, {
+        await coreFacade.handoff.patchHandoff(event.projectDir, event.provider, event.sessionKey, {
           slice: { plan_deviations: [...known, ...fresh] },
         });
       }
@@ -38,7 +38,7 @@ export const responseAfterHandler: Handler = async (
 
   const claim = coreFacade.ship.detectShipClaim(text);
   if (claim) {
-    await coreFacade.handoff.patchHandoff(event.projectDir, event.provider, {
+    await coreFacade.handoff.patchHandoff(event.projectDir, event.provider, event.sessionKey, {
       slice: {
         last_ship_claim_at: ctx.now.toISOString(),
         last_ship_claim_snippet: claim.snippet,

package/src/entrypoints/run.ts

@@ -18,6 +18,7 @@ export type HandlerContext = {
   capabilities: ProviderCapabilities;
   provider: ProviderPort;
   now: Date;
+  protectedPaths: string[];
 };
 
 export type Handler = (event: HarnessEvent, ctx: HandlerContext) => Decision | Promise<Decision>;
@@ -180,7 +181,8 @@ export async function runHandler(handler: Handler, io: RunIo = {}): Promise<RunO
       ...(claimsFile(event) ? { file: event.filePath } : {}),
       now,
     });
-    const context: HandlerContext = { policy, capabilities, provider, now };
+    const protectedPaths = providerRegistry.flatMap((p) => p.wiringTargets());
+    const context: HandlerContext = { policy, capabilities, provider, now, protectedPaths };
     const decision = await handler(event, context);
     const degraded = degrade(decision, event, capabilities, {
       contextBudgetChars: CONTEXT_BUDGET_CHARS,

package/src/entrypoints/session-end.ts

@@ -12,7 +12,7 @@ export const sessionEndHandler: Handler = async (
   const root = event.projectDir;
   const session = sessionIdFromKey(event);
 
-  await coreFacade.handoff.patchHandoff(root, event.provider, {
+  await coreFacade.handoff.patchHandoff(root, event.provider, event.sessionKey, {
     slice: {
       next_action: "Session ended. Run `tlc harness handoff` before resuming.",
     },

package/src/entrypoints/session-start.ts

@@ -43,7 +43,9 @@ export const sessionStartHandler: Handler = async (
     branch: branch ?? "unknown",
   });
 
-  await coreFacade.handoff.patchHandoff(root, event.provider, {
+  coreFacade.handoff.pruneDeadHandoffSessions(root);
+
+  await coreFacade.handoff.patchHandoff(root, event.provider, event.sessionKey, {
     shared: {
       mode: policy.mode,
       project_name: policy.projectName,
@@ -51,7 +53,6 @@ export const sessionStartHandler: Handler = async (
       git_sha: sha ?? undefined,
     },
     slice: {
-      session_key: event.sessionKey,
       // why: names the command, not the file. The path is on the policy surface, so an instruction pointing at it
       // asked for something the floor then refused ([/decisions/ad-047.md](/decisions/ad-047.md)).
       next_action: "Run `tlc harness handoff` if resuming; otherwise start from the user request.",
@@ -63,10 +64,10 @@ export const sessionStartHandler: Handler = async (
    * did not make is text placed in front of every later turn. Withholding is the answer, not refusing the turn
    * ([/decisions/ad-078.md](/decisions/ad-078.md)).
    */
-  const handoffSeal = coreFacade.handoff.handoffInjectable(root);
+  const handoffSeal = coreFacade.handoff.handoffInjectable(root, event.sessionKey);
   const lessonSeal = coreFacade.lesson.projectLessonsInjectable(root);
   const handoff = handoffSeal.ok
-    ? coreFacade.handoff.readHandoff(root, event.provider)
+    ? coreFacade.handoff.readHandoff(root, event.provider, event.sessionKey)
     : ({} as ReturnType<typeof coreFacade.handoff.readHandoff>);
   const foreign = handoffSeal.ok ? coreFacade.handoff.readForeignSlices(root, event.provider) : [];
 

package/src/entrypoints/ship-gate.ts

@@ -49,10 +49,10 @@ export async function shipGateVerdict(event: HarnessEvent, ctx: HandlerContext):
   const provider = event.provider;
   const sessionKey = event.sessionKey;
   const session = sessionIdFromKey(event);
-  const scope = await computeTurnScope(root, provider, policy);
+  const scope = await computeTurnScope(root, provider, sessionKey, policy);
   const shaRoot = shaScopeRoot(event);
 
-  const commentHits = await pendingCommentViolations(root, provider, policy);
+  const commentHits = await pendingCommentViolations(root, provider, sessionKey, policy);
   if (commentHits.length > 0) {
     return {
       kind: "deny",

package/src/entrypoints/stop.ts

@@ -179,7 +179,7 @@ async function creditPendingLessons(args: {
     return;
   }
   await coreFacade.lesson.creditLessons(args.root, pending.ids, args.passed ? "helped" : "neutral");
-  await coreFacade.handoff.patchHandoff(args.root, args.provider, {
+  await coreFacade.handoff.patchHandoff(args.root, args.provider, args.sessionKey, {
     slice: { pending_lesson_credit: undefined },
   });
 }
@@ -282,7 +282,7 @@ async function failGate(args: {
     ? "config"
     : coreFacade.turn.classifyGateFailure(args.gate);
   const freshGaps = coreFacade.gate.gapsFromArtifact({ artifact: args.artifact, category });
-  const handoff = coreFacade.handoff.readHandoff(args.root, args.provider);
+  const handoff = coreFacade.handoff.readHandoff(args.root, args.provider, args.sessionKey);
   const gaps = intel.progressiveContext
     ? coreFacade.turn.mergeGaps(handoff.previous_gaps, freshGaps)
     : freshGaps;
@@ -300,7 +300,7 @@ async function failGate(args: {
       })
     : null;
 
-  await coreFacade.handoff.patchHandoff(args.root, args.provider, {
+  await coreFacade.handoff.patchHandoff(args.root, args.provider, args.sessionKey, {
     slice: {
       last_gate_result: "fail",
       last_fingerprint: fingerprint,
@@ -348,7 +348,7 @@ async function failGate(args: {
   // the thing that grades them ([/decisions/ad-039.md](/decisions/ad-039.md)).
   if (selected.usedIds.length > 0) {
     await coreFacade.lesson.markGradeable(args.root, selected.usedIds);
-    await coreFacade.handoff.patchHandoff(args.root, args.provider, {
+    await coreFacade.handoff.patchHandoff(args.root, args.provider, args.sessionKey, {
       slice: {
         pending_lesson_credit: {
           gate: args.gate,
@@ -475,9 +475,9 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
    * risk — a decision taken from planted text. Withholding here means deciding from the file's absence, which is
    * the same answer a first turn gets ([/decisions/ad-080.md](/decisions/ad-080.md)).
    */
-  const stopSeal = coreFacade.handoff.handoffInjectable(root);
+  const stopSeal = coreFacade.handoff.handoffInjectable(root, sessionKey);
   const handoff = stopSeal.ok
-    ? coreFacade.handoff.readHandoff(root, provider)
+    ? coreFacade.handoff.readHandoff(root, provider, sessionKey)
     : ({} as ReturnType<typeof coreFacade.handoff.readHandoff>);
   // hazard: read before the file list, because the list is diffed against it. A turn that commits moves `HEAD`
   // past its own changes, and every gate below then saw an empty diff and skipped — the comment gate in a repo
@@ -506,7 +506,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
   // stop is still visible when the gate it belongs to runs below.
   const pendingCredit = handoff.pending_lesson_credit;
 
-  await coreFacade.handoff.patchHandoff(root, provider, {
+  await coreFacade.handoff.patchHandoff(root, provider, sessionKey, {
     slice: { last_stop_status: status, last_changed_files: changedFiles, last_gate_result: "skipped" },
   });
 
@@ -515,7 +515,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
 
   if (skipVerify || status !== "completed" || cap.capReached) {
     if (cap.capReached) {
-      await coreFacade.handoff.patchHandoff(root, provider, {
+      await coreFacade.handoff.patchHandoff(root, provider, sessionKey, {
         slice: {
           blockers: `Grind cap hit (${maxLoops} stop loops). Fix manually or pause gates.`,
           next_action: "Inspect failures, fix root cause, then continue.",
@@ -543,7 +543,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
     //
     // invariant: this rail records what it saw and never writes a field it reads. `next_action` is not one of
     // them, and the follow-up text carries the instruction anyway.
-    await coreFacade.handoff.patchHandoff(root, provider, {
+    await coreFacade.handoff.patchHandoff(root, provider, sessionKey, {
       slice: {
         last_failure_category: "agent-quality",
         next_action: "Attempt the work, or proceed under a stated assumption.",
@@ -557,7 +557,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
     (typeof event.contextUsagePercent === "number" && event.contextUsagePercent >= 85);
 
   if (intel.budgetContinue && unfinishedWork && budgetPressure) {
-    await coreFacade.handoff.patchHandoff(root, provider, {
+    await coreFacade.handoff.patchHandoff(root, provider, sessionKey, {
       slice: {
         last_failure_category: "budget",
         next_action: coreFacade.turn.suggestionFor("budget", "budget"),
@@ -686,7 +686,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
       turnBase,
     );
     if (hits.length > 0) {
-      await coreFacade.handoff.patchHandoff(root, provider, {
+      await coreFacade.handoff.patchHandoff(root, provider, sessionKey, {
         slice: {
           last_gate_result: "fail",
           blockers: `This turn added ${hits.length} undeclared comment line(s).`,
@@ -721,7 +721,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
         },
       });
       if (outcome.findings.length > 0) {
-        await coreFacade.handoff.patchHandoff(root, provider, {
+        await coreFacade.handoff.patchHandoff(root, provider, sessionKey, {
           slice: {
             last_gate_result: "fail",
             blockers: `This turn changed the dependency graph in ${outcome.findings.length} way(s) that outlive it.`,
@@ -757,7 +757,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
     );
     const hits = coreFacade.duplication.findDuplications(added, scan.index, policy.duplication.minRun);
     if (hits.length > 0) {
-      await coreFacade.handoff.patchHandoff(root, provider, {
+      await coreFacade.handoff.patchHandoff(root, provider, sessionKey, {
         slice: {
           last_gate_result: "fail",
           blockers: `This turn added ${hits.length} run(s) the project already has.`,
@@ -824,7 +824,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
     changedFiles,
   });
   if (planDecision.kind !== "abstain") {
-    await coreFacade.handoff.patchHandoff(root, provider, {
+    await coreFacade.handoff.patchHandoff(root, provider, sessionKey, {
       slice: {
         last_gate_result: "fail",
         last_failure_category: "policy",
@@ -845,7 +845,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
     changedFilesCount: changedFiles.length,
   });
   if (emptyDiffDecision.kind !== "abstain") {
-    await coreFacade.handoff.patchHandoff(root, provider, {
+    await coreFacade.handoff.patchHandoff(root, provider, sessionKey, {
       slice: {
         last_gate_result: "fail",
         blockers: "Structured ship claim with empty diff.",
@@ -875,7 +875,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
     evidenceNotBeforeMs: coreFacade.ship.newestChangeMs(root, changedFiles),
   });
   if (shipEvidenceDecision.kind !== "abstain") {
-    await coreFacade.handoff.patchHandoff(root, provider, {
+    await coreFacade.handoff.patchHandoff(root, provider, sessionKey, {
       slice: {
         last_gate_result: "fail",
         blockers: "HARNESS_SHIP_CLAIM without recent production evidence on runtime changes.",
@@ -922,7 +922,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
   if (stopRules.decision.kind !== "abstain") {
     if (stopRules.decision.kind !== "context") {
       const worst = coreFacade.rules.strictest(stopRules.outcomes);
-      await coreFacade.handoff.patchHandoff(root, provider, {
+      await coreFacade.handoff.patchHandoff(root, provider, sessionKey, {
         slice: {
           last_gate_result: "fail",
           last_failure_category: "policy",
@@ -960,7 +960,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
    * a `why` kind, so `tlc harness why` answers it after the fact.
    */
   const holders = [...new Set(deferred)];
-  await coreFacade.handoff.patchHandoff(root, provider, {
+  await coreFacade.handoff.patchHandoff(root, provider, sessionKey, {
     slice: {
       last_gate_result: holders.length > 0 ? "skipped" : "pass",
       blockers: undefined,