session-orchestrator 3.17.0 → 3.20.0

package/scripts/check-doc-consistency.sh

@@ -86,7 +86,16 @@ strip_fences "$CLAUDE" > "$CLAUDE_NOFENCE"
 # ---------------------------------------------------------------------------
 # Check 3: live `## Session Config` present in CLAUDE.md
 # ---------------------------------------------------------------------------
-if ! grep -qE '^## Session Config[[:space:]]*$' "$CLAUDE"; then
+# The pattern is EXACT, mirroring isSessionConfigHeading() in
+# scripts/lib/config/section-extractor.mjs (the SSOT) — CR tolerated for CRLF
+# checkouts, nothing else. Shell cannot import the JS predicate, so the
+# alignment is by hand and this comment names the authority. It was
+# `[[:space:]]*$` until #968, which accepted `## Session Config␠` — a heading
+# the runtime parser rejects. That made this check, whose entire purpose is to
+# report whether the runtime can find the block, answer "present" for the one
+# state it exists to catch.
+CR=$(printf '\r')
+if ! grep -qE "^## Session Config${CR}?\$" "$CLAUDE"; then
   emit "$CLAUDE:1" "live-config-missing" "## Session Config heading not found (skills/_shared/config-reading.md depends on it)"
 fi
 
@@ -94,6 +103,13 @@ fi
 # Check 1: H2 parity (CLAUDE.md → README.md)
 # Canonical runtime-only headings live in CLAUDE.md exclusively and are exempt.
 # ---------------------------------------------------------------------------
+# NOT tightened to the SSOT (#968), deliberately. This is a README↔CLAUDE H2
+# PARITY-exemption list, not a comparator against "can the runtime read the
+# Session Config block" — four of its five entries have no SSOT at all, and a
+# heading it wrongly exempts costs a missing parity warning, never a silent
+# config fallback. Check 3 above is the site that answers the runtime question,
+# and that one is exact. Tightening only the `Session Config` alternative would
+# make section-extractor.mjs the authority for a fact it does not govern.
 EXEMPT_HEADINGS_RE='^## (Structure|Destructive-Command Guard|Agent Authoring Rules|Current State|Session Config)[[:space:]]*$'
 
 # Extract README H2 set (one per line, normalized — heading text without the leading `## `)

package/scripts/emit-session.mjs

@@ -27,6 +27,7 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { appendJsonl } from './lib/common.mjs';
+import { serializeSessionLineChecked } from './lib/session-schema/serializer.mjs';
 import {
   validateSession,
   ValidationError,
@@ -35,45 +36,7 @@ import {
   aliasLegacyEndedAt,
 } from './lib/session-schema.mjs';
 
-/**
- * Serialize `validated` to a single JSONL line and prove it round-trips:
- * the line MUST be JSON-parseable AND the parsed-back object MUST still pass
- * `validateSession`. This is the pre-write self-validation seam (#662) that
- * mirrors the `appendLearning` guard — it catches non-serializable values
- * (`undefined`, `NaN`, `Infinity`, `BigInt`, circular refs) that
- * `JSON.stringify` silently drops or that produce a line which won't parse
- * back to the same schema-valid shape.
- *
- * Throws ValidationError (consumed by the caller as a validation failure,
- * exit 1). Does not write — the caller appends only after this returns.
- *
- * @param {object} validated — already validated session entry
- * @returns {string} the verified JSONL line (newline-terminated)
- * @throws {ValidationError} when the serialized line does not round-trip
- */
-export function serializeSessionLineChecked(validated) {
-  let line;
-  try {
-    line = JSON.stringify(validated);
-  } catch (err) {
-    throw new ValidationError(`session is not JSON-serializable: ${err.message}`);
-  }
-  if (typeof line !== 'string' || line.length === 0) {
-    throw new ValidationError('session serialized to an empty line');
-  }
-  let reparsed;
-  try {
-    reparsed = JSON.parse(line);
-  } catch (err) {
-    throw new ValidationError(
-      `serialized session line does not parse back as JSON: ${err.message}`
-    );
-  }
-  // Re-validate the round-tripped shape — catches required fields that were
-  // present as `undefined`/`NaN` before stringify but vanished after.
-  validateSession(reparsed);
-  return line + '\n';
-}
+export { serializeSessionLineChecked };
 
 function parseArgs(argv) {
   const args = { file: '.orchestrator/metrics/sessions.jsonl', entry: null };
@@ -167,7 +130,7 @@ async function main() {
   // sessions.jsonl and only surface on the NEXT session's read. Treated as a
   // validation failure (exit 1); file is left untouched.
   try {
-    serializeSessionLineChecked(validated);
+    serializeSessionLineChecked(repaired);
   } catch (err) {
     if (err instanceof ValidationError) {
       process.stderr.write(

package/scripts/eval-session.mjs

@@ -10,6 +10,36 @@
  *   - Data → stdout, diagnostics → stderr.
  *   - Exit codes: 0 success/match · 1 user-error/drift · 2 system error.
  *
+ * ## Append failures are NOT exit 0 (GitLab #969)
+ *
+ * `appendEvalRecord` is a never-throw sink: it returns
+ * `{ ok:false, reason:'validation'|'fs-error' }` instead of raising. This CLI
+ * used to log that WARN and still `process.exit(0)` — the caller saw success
+ * while the journal had no record, one surface reporting a fact the other did
+ * not carry. A failed append now exits non-zero, split by reason:
+ *
+ *   - `fs-error`  → EXIT_SYSTEM (2). The filesystem refused the append
+ *     (permissions, ENOTDIR, full disk) — "system error" per cli-design.md.
+ *   - `validation` → EXIT_USER (1). Reachable from the invocation: `--handle ""`
+ *     survives the `?? null` default as an empty string and trips the
+ *     "handle must be a non-empty string or null" rule in eval/schema.mjs.
+ *     Malformed metrics input reaches the same path, and cli-design.md maps
+ *     "bad args, invalid file" to 1. This matches the rest of this file, where
+ *     every input-derived failure is EXIT_USER and only engine crashes are
+ *     EXIT_SYSTEM. (An engine-internal invariant breach also lands here — a
+ *     mild under-classification, accepted so the reachable case stays honest.)
+ *
+ * Both branches emit the `--json` / human payload to stdout BEFORE exiting, and
+ * do so via `writeStdoutLineSync` rather than a queued write: `process.stdout`
+ * is asynchronous on a pipe on macOS, so `process.exit()` discards whatever is
+ * still in libuv's queue past the 65 536-byte kernel buffer. Losing the record
+ * alongside the error is the exact fail-open shape #906 fixed in the hook layer.
+ * Real records measure ≤ 5 210 bytes today, but `evidence` strings are
+ * engine-generated free text, so the bound is empirical, not structural.
+ *
+ * Session-end Phase 3.7d remains advisory and MUST NOT gate on this exit code —
+ * it catches a non-zero exit and logs a WARN (skills/session-end/SKILL.md).
+ *
  * Usage:
  *   eval-session.mjs [--session <id>] [--json] [--no-write]
  *                    [--metrics-dir <path>] [--rubric <path>]
@@ -29,6 +59,7 @@ import { fileURLToPath } from 'node:url';
 
 import { evaluateSession, diffDimensions, DEFAULT_RUBRIC_PATH, RUBRIC_VERSION } from './lib/eval/engine.mjs';
 import { appendEvalRecord, readEvalRecords } from './lib/eval/sink.mjs';
+import { writeStdoutLineSync } from './lib/io.mjs';
 import { VALID_MODEL_SOURCES } from './lib/eval/schema.mjs';
 import { SessionResolutionError } from './lib/eval/session-resolve.mjs';
 
@@ -69,8 +100,9 @@ OPTIONS
 
 EXIT CODES
   0  success / verify match
-  1  user error (session not found, unknown run-id) / verify drift
-  2  system error
+  1  user error (session not found, unknown run-id, record failed validation)
+     / verify drift
+  2  system error (could not append the record to the eval journal)
 `;
 
 function fail(exitCode, message) {
@@ -144,18 +176,27 @@ function runEvaluate(values) {
   const { record, summary } = result;
 
   let writeResult = null;
+  let appendFailureReason = null;
   if (!values['no-write']) {
     writeResult = appendEvalRecord(record, { path: path.join(metricsDir, 'eval.jsonl') });
     if (!writeResult.ok) {
-      // never-throw sink already emitted a stderr WARN; surface it as a soft note.
+      // The never-throw sink already emitted its own stderr WARN; add the
+      // CLI-level line, then carry the reason to the exit code below.
       process.stderr.write(`[eval-session] append failed (${writeResult.reason}): ${writeResult.error}\n`);
+      appendFailureReason = writeResult.reason;
     }
   }
 
+  // stdout FIRST, synchronously — the caller must not lose the payload along
+  // with the error (see the append-failure note in the module docblock).
   if (values.json) {
-    process.stdout.write(`${JSON.stringify(record)}\n`);
+    writeStdoutLineSync(JSON.stringify(record));
   } else {
-    process.stdout.write(`${renderHuman(record, summary, writeResult)}\n`);
+    writeStdoutLineSync(renderHuman(record, summary, writeResult));
+  }
+
+  if (appendFailureReason !== null) {
+    process.exit(appendFailureReason === 'validation' ? EXIT_USER : EXIT_SYSTEM);
   }
   process.exit(EXIT_OK);
 }
@@ -195,15 +236,15 @@ function runVerify(runId, values) {
 
   if (diffs.length === 0) {
     if (values.json) {
-      process.stdout.write(`${JSON.stringify({ run_id: runId, match: true, dimensions: fresh.dimensions.length })}\n`);
+      writeStdoutLineSync(JSON.stringify({ run_id: runId, match: true, dimensions: fresh.dimensions.length }));
     } else {
-      process.stdout.write(`MATCH: ${runId} re-evaluates identically across ${fresh.dimensions.length} dimension(s).\n`);
+      writeStdoutLineSync(`MATCH: ${runId} re-evaluates identically across ${fresh.dimensions.length} dimension(s).`);
     }
     process.exit(EXIT_OK);
   }
 
   if (values.json) {
-    process.stdout.write(`${JSON.stringify({ run_id: runId, match: false, diffs })}\n`);
+    writeStdoutLineSync(JSON.stringify({ run_id: runId, match: false, diffs }));
   } else {
     const out = [`DRIFT: ${runId} re-evaluation differs from the stored record:`];
     for (const d of diffs) {
@@ -213,7 +254,7 @@ function runVerify(runId, values) {
         out.push(`  ${d.id}.${d.field}: stored=${JSON.stringify(d.stored)} fresh=${JSON.stringify(d.fresh)}`);
       }
     }
-    process.stdout.write(`${out.join('\n')}\n`);
+    writeStdoutLineSync(out.join('\n'));
   }
   process.exit(EXIT_USER);
 }

package/scripts/fleet-instruction-scan.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * fleet-instruction-scan.mjs — always-on instruction load across every repo on the host.
+ *
+ * `scripts/measure-context-overhead.sh` measures one directory precisely but
+ * costs an API call per measurement. This scans the whole fleet for free by
+ * counting bytes and classifying them the way `scripts/lib/rule-loader.mjs`
+ * does: a rule file is always-on unless its frontmatter carries `globs:` or
+ * `paths:` (issue #795), and it reaches wave agents unless it is tagged
+ * `tier: coordinator-only` (issue #692).
+ *
+ * Token estimates use the ratio measured 2026-07-30 on claude-opus-5[1m]:
+ * 108589 always-on bytes in this repo produced roughly 67396 context tokens,
+ * i.e. about 1 token per 1.6 bytes. Treat the estimate as an order of
+ * magnitude and confirm a specific repo with measure-context-overhead.sh.
+ *
+ * Usage:
+ *   node scripts/fleet-instruction-scan.mjs
+ *   node scripts/fleet-instruction-scan.mjs ~/Projects/intern ~/Projects/extern
+ *   node scripts/fleet-instruction-scan.mjs --json
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+
+const BYTES_PER_TOKEN = 1.6;
+
+const argv = process.argv.slice(2);
+const asJson = argv.includes('--json');
+const roots = argv.filter((a) => !a.startsWith('--'));
+const ROOTS = roots.length
+  ? roots
+  : [
+      join(homedir(), 'Projects', 'extern'),
+      join(homedir(), 'Projects', 'intern'),
+      join(homedir(), 'Projects', 'Ventures'),
+      join(homedir(), 'Projects', 'Bernhard'),
+    ];
+
+/** Classify one rule file the way rule-loader.mjs does. */
+function classify(path) {
+  const body = readFileSync(path, 'utf8');
+  const fmMatch = body.match(/^---\n([\s\S]*?)\n---/);
+  const fm = fmMatch ? fmMatch[1] : '';
+  const tierMatch = fm.match(/^tier:\s*(\S+)/m);
+  return {
+    scoped: /^(globs|paths):/m.test(fm),
+    tier: tierMatch ? tierMatch[1] : 'always',
+    bytes: Buffer.byteLength(body),
+  };
+}
+
+function scanRepo(dir) {
+  let alwaysBytes = 0;
+  let waveBytes = 0;
+  let files = 0;
+  let scopedFiles = 0;
+  const rulesDir = join(dir, '.claude', 'rules');
+  if (existsSync(rulesDir)) {
+    for (const f of readdirSync(rulesDir).filter((n) => n.endsWith('.md'))) {
+      const c = classify(join(rulesDir, f));
+      files++;
+      if (c.scoped) {
+        scopedFiles++;
+        continue;
+      }
+      alwaysBytes += c.bytes;
+      if (c.tier !== 'coordinator-only') waveBytes += c.bytes;
+    }
+  }
+  const instructionFile = ['CLAUDE.md', 'AGENTS.md'].map((f) => join(dir, f)).find(existsSync);
+  const cmBytes = instructionFile ? statSync(instructionFile).size : 0;
+  return { files, scopedFiles, alwaysBytes, waveBytes, cmBytes, total: alwaysBytes + cmBytes };
+}
+
+const rows = [];
+for (const root of ROOTS) {
+  if (!existsSync(root)) continue;
+  for (const name of readdirSync(root)) {
+    const dir = join(root, name);
+    try {
+      if (!statSync(dir).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    if (!existsSync(join(dir, '.git'))) continue;
+    rows.push({ repo: `${basename(root)}/${name}`, ...scanRepo(dir) });
+  }
+}
+rows.sort((a, b) => b.total - a.total);
+
+if (asJson) {
+  console.log(JSON.stringify({ bytesPerToken: BYTES_PER_TOKEN, repos: rows }, null, 2));
+  process.exit(0);
+}
+
+const pad = (s, n) => String(s).padStart(n);
+console.log(
+  'REPO'.padEnd(36),
+  pad('RULES', 6),
+  pad('SCOPED', 7),
+  pad('ALWAYS_B', 9),
+  pad('WAVE_B', 8),
+  pad('INSTR_B', 8),
+  pad('EST_TOK', 8),
+);
+for (const r of rows) {
+  console.log(
+    r.repo.padEnd(36),
+    pad(r.files, 6),
+    pad(r.scopedFiles, 7),
+    pad(r.alwaysBytes, 9),
+    pad(r.waveBytes, 8),
+    pad(r.cmBytes, 8),
+    pad(Math.round(r.total / BYTES_PER_TOKEN), 8),
+  );
+}
+
+const totalFiles = rows.reduce((a, r) => a + r.files, 0);
+const totalScoped = rows.reduce((a, r) => a + r.scopedFiles, 0);
+const median = (xs) => {
+  const s = [...xs].sort((a, b) => a - b);
+  return s.length ? s[Math.floor(s.length / 2)] : 0;
+};
+const withRules = rows.filter((r) => r.files > 0);
+
+console.log(`\nrepos scanned            : ${rows.length} (${withRules.length} with rule files)`);
+console.log(`rule files               : ${totalFiles}  (${totalScoped} glob/path-scoped, ${totalFiles - totalScoped} always-on)`);
+console.log(`median always-on bytes   : ${median(withRules.map((r) => r.alwaysBytes))}`);
+console.log(`median est. tokens/session: ${Math.round(median(withRules.map((r) => r.total)) / BYTES_PER_TOKEN)}`);
+
+// A value shared by many repos means a vendored rule set: trimming it at the
+// source propagates everywhere, which is the cheapest lever in the fleet.
+const byBytes = new Map();
+for (const r of withRules) byBytes.set(r.alwaysBytes, (byBytes.get(r.alwaysBytes) || 0) + 1);
+const shared = [...byBytes.entries()].filter(([, n]) => n > 1).sort((a, b) => b[1] - a[1]);
+if (shared.length) {
+  console.log('\nidentical always-on totals (vendored rule sets — trim once, propagate widely):');
+  for (const [bytes, n] of shared.slice(0, 5)) console.log(`  ${bytes} B  in ${n} repos`);
+}

package/scripts/lib/autopilot/mr-draft.mjs

@@ -13,6 +13,8 @@
 import { execFile as execFileCb } from 'node:child_process';
 import { promisify } from 'node:util';
 
+import { resolveRepoSpec } from '../vcs-repo-spec.mjs';
+
 const realExecFile = promisify(execFileCb);
 
 // ---------------------------------------------------------------------------
@@ -112,13 +114,22 @@ export function validateMrInputs(title, description) {
  * @param {'glab'|'gh'} opts.vcs
  * @param {string} opts.branchName
  * @param {Function} [opts.execFile] - defaults to promisified execFile from node:child_process
+ * @param {string} [opts.repoRoot] - defaults to process.cwd()
+ * @param {(opts: { repoRoot: string, vcs: 'gitlab'|'github' }) => string | undefined} [opts.resolveRepoSpecFn]
+ *   Injectable seam for the `-R`/`--repo` host-pinning resolution (#872) —
+ *   defaults to the real `resolveRepoSpec` (shells out to `git remote
+ *   get-url`); tests inject a stub instead of shelling out.
  * @returns {Promise<{hasMR: boolean, mrIid: number|null, mrUrl: string|null}>}
  */
 export async function checkExistingMR(opts) {
-  const { vcs, branchName } = opts;
+  const { vcs, branchName, repoRoot = process.cwd() } = opts;
   const execFile = typeof opts.execFile === 'function' ? opts.execFile : realExecFile;
+  const resolveRepoSpecFn =
+    typeof opts.resolveRepoSpecFn === 'function' ? opts.resolveRepoSpecFn : resolveRepoSpec;
 
   if (vcs === 'glab') {
+    // Resolve the -R/--repo host-pinning spec ONCE for this call (#872).
+    const spec = resolveRepoSpecFn({ repoRoot, vcs: 'gitlab' });
     const args = [
       'mr',
       'list',
@@ -129,6 +140,7 @@ export async function checkExistingMR(opts) {
       '--output',
       'json',
     ];
+    if (spec) args.push('-R', spec);
     const { stdout } = await execFile('glab', args, { shell: false, timeout: 5_000 });
     let mrs;
     try {
@@ -148,7 +160,10 @@ export async function checkExistingMR(opts) {
   }
 
   if (vcs === 'gh') {
+    // Resolve the -R/--repo host-pinning spec ONCE for this call (#872).
+    const spec = resolveRepoSpecFn({ repoRoot, vcs: 'github' });
     const args = ['pr', 'list', '--head', branchName, '--state', 'open', '--json', 'number,url'];
+    if (spec) args.push('-R', spec);
     const { stdout } = await execFile('gh', args, { shell: false, timeout: 5_000 });
     let prs;
     try {
@@ -391,6 +406,11 @@ export function buildMrBody(ctx) {
  * @param {object} [opts]
  * @param {Function} [opts.execFile]
  * @param {(level: string, msg: string) => void} [opts.log]
+ * @param {string} [opts.repoRoot] - defaults to process.cwd()
+ * @param {(opts: { repoRoot: string, vcs: 'gitlab'|'github' }) => string | undefined} [opts.resolveRepoSpecFn]
+ *   Injectable seam for the `-R`/`--repo` host-pinning resolution (#872) —
+ *   defaults to the real `resolveRepoSpec` (shells out to `git remote
+ *   get-url`); tests inject a stub instead of shelling out.
  * @returns {Promise<{created: boolean, deferred?: boolean, existing?: boolean, mrUrl?: string|null, error?: string}>}
  */
 export async function maybeCreateDraftMR(loop, opts = {}) {
@@ -399,6 +419,9 @@ export async function maybeCreateDraftMR(loop, opts = {}) {
       ? opts.log
       : (_level, _msg) => {}; // no-op default
   const execFile = typeof opts.execFile === 'function' ? opts.execFile : realExecFile;
+  const repoRoot = typeof opts.repoRoot === 'string' ? opts.repoRoot : process.cwd();
+  const resolveRepoSpecFn =
+    typeof opts.resolveRepoSpecFn === 'function' ? opts.resolveRepoSpecFn : resolveRepoSpec;
 
   const { draftMrPolicy, vcs, issueIid, issueTitle, branchName, parentRunId, worktreePath } = loop;
 
@@ -442,6 +465,11 @@ export async function maybeCreateDraftMR(loop, opts = {}) {
       worktreePath,
     });
 
+    // Resolve the -R/--repo host-pinning spec ONCE (#872); reuse the same
+    // resolved value for both the collision check and the create call below
+    // (mirrors #839's spiral-carryover.mjs / issue-close-strip-labels.mjs idiom).
+    const spec = resolveRepoSpecFn({ repoRoot, vcs });
+
     // Collision check — skip if MR already exists
     let existingCheck;
     try {
@@ -449,6 +477,7 @@ export async function maybeCreateDraftMR(loop, opts = {}) {
         vcs: vcsBin, // 'glab' or 'gh'
         branchName,
         execFile,
+        resolveRepoSpecFn: () => spec,
       });
     } catch (err) {
       log('error', `mr-draft: collision check failed — ${err.message}`);
@@ -491,6 +520,7 @@ export async function maybeCreateDraftMR(loop, opts = {}) {
         branchName,
       ];
     }
+    if (spec) createArgs.push('-R', spec);
 
     // Execute MR/PR creation
     try {

package/scripts/lib/autopilot/worktree-pipeline.mjs

@@ -32,7 +32,8 @@ import fs, { realpathSync } from 'node:fs';
 import { runLoop } from './loop.mjs';
 import { maybeCreateDraftMR } from './mr-draft.mjs';
 import { validateWorkspacePath } from '../worktree/lifecycle.mjs';
-import { acquire, release } from '../session-lock.mjs';
+import { acquire, release, buildLockOwnerProof } from '../session-lock.mjs';
+import { emitEvent } from '../events.mjs';
 import { main as gcMain } from '../../gc-stale-worktrees.mjs';
 import { SEMANTIC_ID_RE } from '../session-id.mjs';
 
@@ -65,6 +66,9 @@ import { SEMANTIC_ID_RE } from '../session-id.mjs';
  * @property {string|null} killSwitch
  * @property {string|null} killSwitchDetail
  * @property {number} iterationsCompleted
+ * @property {boolean} fallbackToManual  - Mirrors loop.mjs's `fallback_to_manual` (#905): true
+ *   when the inner loop broke out with no mode recommendation instead of doing real work.
+ *   The caller (autopilot-multi.mjs) MUST NOT treat a true value as a completed loop.
  * @property {number} spiralRecoveryCount
  * @property {string|null} commitDependency
  * @property {boolean} abortedByCohort
@@ -128,6 +132,42 @@ function repoBasename(repoRoot) {
   return path.basename(repoRoot);
 }
 
+/**
+ * Render a worktree path for an event record: repo-relative, never absolute.
+ *
+ * `events.jsonl` records get quoted into issues and MR descriptions, and this
+ * repo mirrors to a PUBLIC GitHub remote — so an absolute worktree path ships
+ * the operator's home directory (`/Users/<name>/…`) into a public artefact
+ * (#957 finding 3). The forensic value of the field is "WHICH worktree", which
+ * the repo-relative form carries in full.
+ *
+ * Escaping the repo root is expected, not an error: the default worktree root
+ * is `~/.so-worktrees`, so the normal output is a `../…` chain. That form is
+ * still host-agnostic — `path.relative` strips the COMMON PREFIX, which is
+ * exactly where `/Users/<name>` lives.
+ *
+ * Pure string math: no `realpathSync`, no fs access, cannot throw. This runs on
+ * the teardown path where the worktree may already have been removed.
+ *
+ * Residual, deliberately not defended against: a repo root OUTSIDE the home
+ * directory combined with a worktree root INSIDE it (e.g. `/srv/repo` +
+ * `~/.so-worktrees`) shares no prefix, so the `../` chain descends back through
+ * `Users/<name>/`. That configuration is not reachable from this module's
+ * defaults and a heuristic scrub would be less predictable than the plain
+ * relative path.
+ *
+ * @param {string} repoRoot      absolute path to the primary repo
+ * @param {string|null|undefined} worktreePath absolute worktree path, if known
+ * @returns {string|null} repo-relative path, or null when either input is unusable
+ */
+export function relativeWorktreePath(repoRoot, worktreePath) {
+  if (typeof worktreePath !== 'string' || worktreePath.length === 0) return null;
+  // Without a usable base there is no way to strip the host prefix. Report
+  // "unknown" rather than fall back to the absolute path this exists to avoid.
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) return null;
+  return path.relative(repoRoot, worktreePath);
+}
+
 // ---------------------------------------------------------------------------
 // setupWorktree
 // ---------------------------------------------------------------------------
@@ -230,6 +270,9 @@ export async function setupWorktree(context, opts = {}) {
  *  - If `result.killSwitch` is `'stall-timeout'`: leave the worktree intact
  *    for retry. Only release the lock.
  *  - Otherwise: call `opts.gcOnExit` to clean up, then release the lock.
+ *  - The lock-release outcome is evaluated and emitted as an
+ *    `orchestrator.session.lock.released` / `…release_failed` breadcrumb
+ *    (`caller: 'worktree-pipeline'`) into the PARENT repo's events stream (#952).
  *  - Errors during teardown are swallowed (logged to stderr). Never re-throws.
  *
  * @param {StoryContext} context
@@ -267,13 +310,69 @@ export async function teardownWorktree(context, result, opts = {}) {
 
   // Always attempt to release the per-worktree lock.
   if (result._lockSessionId) {
+    /** @type {{ ok: boolean, deleted?: boolean, reason?: string, verified?: boolean }|null} */
+    let releaseResult = null;
     try {
-      release({ sessionId: result._lockSessionId, repoRoot: result.worktreePath });
+      // #987 defense-in-depth: pass the in-memory genesis proof (captured by
+      // runStoryPipeline right after acquire — same process, no file I/O)
+      // so the delete is double-gated at the fs layer. Spread-guarded:
+      // release()'s proof gate triggers on `proof !== undefined`, so a
+      // null/absent proof MUST be omitted entirely or EVERY release would
+      // be refused with 'proof-mismatch'.
+      releaseResult = release({
+        sessionId: result._lockSessionId,
+        repoRoot: result.worktreePath,
+        ...(result._lockOwnerProof ? { proof: result._lockOwnerProof } : {}),
+      });
     } catch (lockErr) {
       console.error(
         `worktree-pipeline: lock release error for issue #${context.issueIid}: ${lockErr?.message ?? String(lockErr)}`,
       );
     }
+
+    // #952 (A) — observability breadcrumb for the SECOND release() call-site.
+    // Before this, the call above was fire-and-forget: its structured result was
+    // discarded entirely, so a per-worktree lock that failed to release — or
+    // that had already vanished — left NO trace anywhere. That is the blind
+    // spot behind the "#914 lock disappears in the start chain" class for
+    // worktree-isolated runs.
+    //
+    // Emitted at the CALL-SITE, never inside release(): session-lock.mjs
+    // deliberately carries no dependency on events.mjs, and release() is
+    // synchronous while emitEvent() is async. `caller` keeps this path
+    // distinguishable from hooks/on-session-end.mjs in the single stream.
+    //
+    // Destination is PINNED to the parent repo (`repoRoot` via the #941
+    // `opts.repoRoot` interface — same pattern as scripts/lib/lock-reaper.mjs)
+    // rather than the ambient SO_PROJECT_DIR: this pipeline deliberately runs
+    // across worktrees with an explicit repoRoot (#219 CWD-drift), and the
+    // worktree itself may already have been removed by the gc step above, so
+    // its own `.orchestrator/` is not a valid destination.
+    const benignAlreadyGone = releaseResult?.ok === true && releaseResult.reason === 'no-lock';
+    const releaseFailed = releaseResult === null
+      || (!benignAlreadyGone && (releaseResult.ok !== true || releaseResult.deleted !== true));
+    try {
+      if (releaseFailed) {
+        await emitEvent('orchestrator.session.lock.release_failed', {
+          session_id: result._lockSessionId,
+          reason: releaseResult === null
+            ? 'threw'
+            : (releaseResult.reason ?? (releaseResult.ok === true ? 'not-deleted' : 'fs-error')),
+          caller: 'worktree-pipeline',
+          worktree_path: relativeWorktreePath(repoRoot, result.worktreePath),
+          issue_iid: context.issueIid,
+        }, { repoRoot });
+      } else {
+        await emitEvent('orchestrator.session.lock.released', {
+          session_id: result._lockSessionId,
+          caller: 'worktree-pipeline',
+          outcome: benignAlreadyGone ? 'already-gone' : 'deleted',
+          verified: releaseResult.verified === true,
+          worktree_path: relativeWorktreePath(repoRoot, result.worktreePath),
+          issue_iid: context.issueIid,
+        }, { repoRoot });
+      }
+    } catch { /* observability is best-effort — teardown must never throw */ }
   }
 }
 
@@ -393,6 +492,7 @@ export async function runStoryPipeline(context, opts = {}) {
       kill_switch: 'failed-wave',
       kill_switch_detail: err?.message ?? String(err),
       iterations_completed: 0,
+      fallback_to_manual: false,
       stall_recovery_count: 0,
     };
   }
@@ -409,11 +509,18 @@ export async function runStoryPipeline(context, opts = {}) {
     killSwitch: loopState.kill_switch ?? null,
     killSwitchDetail: loopState.kill_switch_detail ?? null,
     iterationsCompleted: loopState.iterations_completed ?? 0,
+    fallbackToManual: loopState.fallback_to_manual === true,
     spiralRecoveryCount: loopState.stall_recovery_count ?? 0,
     commitDependency: null,
     abortedByCohort: loopState.kill_switch === 'peer-abort',
     // Internal: used by teardownWorktree to release the lock.
     _lockSessionId: lockSessionId,
+    // Internal (#987): in-memory genesis proof for the proof-gated release in
+    // teardownWorktree. Same process as the acquire above, so no file I/O is
+    // needed — buildLockOwnerProof() returns null on a partial/absent lock
+    // (e.g. a DI test stub without a full lock body), and teardown's
+    // spread-guard then falls back to the session_id-only release.
+    _lockOwnerProof: buildLockOwnerProof(lockResult.lock),
   };
 
   await teardownWorktree(context, result, { gcOnExit });
@@ -423,11 +530,12 @@ export async function runStoryPipeline(context, opts = {}) {
     throw loopError;
   }
 
-  // Strip internal field before returning to caller.
-  const { _lockSessionId: _removed, ...publicResult } = result;
+  // Strip internal fields before returning to caller.
+  const { _lockSessionId: _removed, _lockOwnerProof: _removedProof, ...publicResult } = result;
 
-  // Suppress unused-variable lint warning — _removed is intentionally discarded.
+  // Suppress unused-variable lint warning — both are intentionally discarded.
   void _removed;
+  void _removedProof;
 
   return publicResult;
 }