session-orchestrator 5.11.0 → 5.13.0

package/scripts/fleet-checkin.mjs

@@ -15,6 +15,10 @@
  * Then reads the navigator lease and emits `orchestrator.fleet.checkin` with the
  * payload `{ session, repo, modus, kandidaten, navigator_state }` — no paths, no
  * quota, no `auftrag_ref`.
+ * Without fleet integration, valid input exits 0 with `skipped: "no-fleet"` and no directory, file or event.
+ * That holds for `plattform: "kopflos"` too: the record cannot prove a coordinator started the run,
+ * and a write would create the navigator directory, which then flips every later solo session to
+ * fleet. A headless run without fleet integration applies the Standard-Auflagen instead (#1559 review).
  *
  * stdout: one JSON line
  * `{ ok, path, navigator_state, navigator_adresse, fallback_due_at, event }`.
@@ -29,7 +33,7 @@
  * Exit codes:
  *   0 — check-in written (an event failure only WARNs; `event: false` on stdout)
  *   1 — write error
- *   2 — invalid input (not JSON, not an object, or validation errors; no file)
+ *   2 — invalid input or semantic session ID occupied by another repo (no write/event)
  */
 
 import { randomBytes } from 'node:crypto';
@@ -39,6 +43,7 @@ import path from 'node:path';
 import { emitEvent } from './lib/events.mjs';
 import {
   checkinPath,
+  fleetIntegrationEnabled,
   fallbackDueAt,
   navigatorDir,
   readNavigatorLease,
@@ -46,6 +51,7 @@ import {
   validateCheckin,
 } from './lib/fleet-protocol.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
+import { openNoFollow } from './lib/no-follow-open.mjs';
 
 const PREFIX = 'fleet-checkin:';
 
@@ -63,8 +69,14 @@ async function readStdin() {
  * planted symlink cannot redirect the chmod or the write.
  * @param {string} target
  * @param {object} record
+ * @param {object} [options]
+ * @param {typeof openNoFollow} [options.open] opener for the ownership read.
+ *   Injectable only so tests can reach the fail-closed `ERR_FILE_CHANGED`
+ *   branch, which `openNoFollow` never takes on POSIX; production passes nothing.
+ * @returns {Promise<boolean>} false when another repo already owns the target,
+ *   or the target changed during the ownership check
  */
-async function writeCheckinFile(target, record) {
+export async function writeCheckinFile(target, record, { open = openNoFollow } = {}) {
   const checkinDir = path.dirname(target);
   await fs.mkdir(navigatorDir(), { recursive: true, mode: 0o700 });
   await fs.mkdir(checkinDir, { recursive: true, mode: 0o700 });
@@ -79,7 +91,52 @@ async function writeCheckinFile(target, record) {
     await fs.writeFile(tmp, JSON.stringify(record, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
     // The creation mode is filtered through the umask; pin it explicitly.
     await fs.chmod(tmp, 0o600);
+    let existing;
+    try {
+      // Never follow a symlink at the target and never block on a FIFO; the
+      // helper also covers platforms without O_NOFOLLOW (win32, #1744).
+      const handle = await open(target);
+      try {
+        const stat = await handle.stat();
+        const limit = 64 * 1024;
+        // Check-ins are small: non-files and larger targets are unreadable for
+        // this guard and fail-open. Bound reads even if the file grows after stat.
+        if (stat.isFile() && stat.size <= limit) {
+          const buffer = Buffer.alloc(limit);
+          let length = 0;
+          while (length < limit) {
+            const { bytesRead } = await handle.read(buffer, length, limit - length, length);
+            if (bytesRead === 0) break;
+            length += bytesRead;
+          }
+          if ((await handle.stat()).size <= limit) {
+            existing = JSON.parse(buffer.subarray(0, length).toString('utf8'));
+          }
+        }
+      } finally {
+        await handle.close();
+      }
+    } catch (err) {
+      // A target swapped during the check may hide a foreign check-in: fail closed.
+      if (err?.code === 'ERR_FILE_CHANGED') {
+        await fs.rm(tmp, { force: true });
+        process.stderr.write(`${PREFIX} check-in target ${path.basename(target)} changed during the safety check; refusing to overwrite\n`);
+        return false;
+      }
+      // Fail-open otherwise: a missing (first write), symlinked, non-regular,
+      // unreadable or invalid-JSON target gives the navigator no readable
+      // check-in to preserve. `rename` replaces a symlink itself, never follows it.
+    }
+    if (typeof existing?.repo === 'string' && existing.repo !== record.repo) {
+      await fs.rm(tmp, { force: true });
+      process.stderr.write(`${PREFIX} semantic session ID ${record.session} is already occupied by another repo: ${JSON.stringify(existing.repo)}\n`);
+      return false;
+    }
+    // BV-004 ceiling: protects an already-visible foreign check-in, not concurrent
+    // writers between read and rename; revisit with atomic coordination when a
+    // simultaneous cross-repo collision is observed.
     await fs.rename(tmp, target);
+    return true;
   } catch (err) {
     await fs.rm(tmp, { force: true }).catch(() => {});
     throw err;
@@ -107,9 +164,22 @@ async function main() {
     return 2;
   }
 
+  if (!fleetIntegrationEnabled()) {
+    process.stdout.write(JSON.stringify({
+      ok: true,
+      skipped: 'no-fleet',
+      path: null,
+      navigator_state: 'none',
+      navigator_adresse: null,
+      fallback_due_at: null,
+      event: false,
+    }) + '\n');
+    return 0;
+  }
+
   const target = checkinPath(record.session);
   try {
-    await writeCheckinFile(target, record);
+    if (!await writeCheckinFile(target, record)) return 2;
   } catch (err) {
     process.stderr.write(`${PREFIX} write failed: ${err instanceof Error ? err.message : String(err)}\n`);
     return 1;

package/scripts/gc-stale-worktrees.mjs

@@ -27,6 +27,7 @@ import path from 'node:path';
 
 import { validateWorkspacePath } from './lib/worktree/lifecycle.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
+import { resolveEventsLedgerRoot } from './lib/platform.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -79,7 +80,11 @@ export function isPidAlive(pid) {
  */
 function loadRecentSessionRefs(repoRoot) {
   const refs = new Set();
-  const sessionsPath = path.join(repoRoot, SESSIONS_JSONL);
+  // #1592: the repo's ONE ledger (main checkout from a linked worktree, which
+  // has none since #1584) — reading the worktree's would drop every "kept"
+  // reference and let GC remove a worktree a recent session still names.
+  // The worktree-meta dir stays per checkout: it is tmp state, not the ledger.
+  const sessionsPath = path.join(resolveEventsLedgerRoot(repoRoot), SESSIONS_JSONL);
 
   let raw;
   try {

package/scripts/github-export.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * github-export.mjs — build the curated public GitHub snapshot (`mirror: curated`, #1631).
+ *
+ * Usage:
+ *   node scripts/github-export.mjs [--source <rev>] [--dry-run]
+ *   node scripts/github-export.mjs --verify <export sha> --source <source sha>
+ *   node scripts/github-export.mjs --plain-guard --mirror-key <github|unset>
+ *
+ * The parent is ALWAYS the public GitHub main: `refs/remotes/github/main`, required to
+ * equal `git ls-remote github refs/heads/main` (one read-only network call). There is
+ * deliberately no parent override, and refs/heads/github-export is only the output slot.
+ *
+ * Writes ONE snapshot commit to refs/heads/github-export (see scripts/lib/github-export.mjs);
+ * session-end then pushes it to github main (skills/session-end/SKILL.md § 4.4).
+ *
+ * Exit codes:
+ *   0  snapshot created (stdout: new sha) — or, with --dry-run, stats printed
+ *   3  nothing to publish: the curated tree equals github main's (stdout: that sha;
+ *      refs/heads/github-export is not touched)
+ *   1  refused, one-line reason on stderr (replace refs or grafts present, github main
+ *      not verifiable or tracking ref stale, source not descended from the published
+ *      snapshot's source, excluded path survived, leakage scan failed, a public file
+ *      still cites an excluded path, push URL differs from fetch URL, compare-and-swap
+ *      lost) — or a usage error
+ *
+ * --verify re-checks an already built snapshot BY SHA right before session-end pushes
+ * that sha: graph integrity, push URL == fetch URL, github main verified via ls-remote,
+ * exactly one commit on it with `Source-Commit: <source>`, no excluded path in its tree.
+ * Exit 0 ok, 1 refused. stdout stays empty in every mode except the sha lines above.
+ *
+ * --plain-guard answers whether a PLAIN push of source history (`git push github HEAD`)
+ * is allowed: refused (exit 1, reason on stderr) when HEAD or origin's main carries
+ * .orchestrator/policy/public-export.json, i.e. the repo has adopted the curated export
+ * even if this checkout's Session Config predates `mirror: curated` (#1645), and — without
+ * an `origin` remote to consult — unless `--mirror-key github` (explicit `mirror: github`).
+ * Exit 0 allowed.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+import { buildGithubExport, createGitRunner, plainPushGuard, verifyExportCommit } from './lib/github-export.mjs';
+
+function usage(msg) {
+  if (msg) console.error(`github-export: ${msg}`);
+  console.error('Usage: node scripts/github-export.mjs [--source <rev>] [--dry-run] | --verify <sha> --source <sha> | --plain-guard --mirror-key <github|unset>');
+  process.exit(1);
+}
+
+const opts = { source: 'HEAD', dryRun: false };
+let verifySha = null;
+let plainGuard = false;
+let mirrorKey = null;
+const args = process.argv.slice(2);
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === '--dry-run') opts.dryRun = true;
+  else if (a === '--plain-guard') plainGuard = true;
+  else if (a === '--mirror-key') {
+    mirrorKey = args[++i];
+    if (mirrorKey !== 'github' && mirrorKey !== 'unset') usage('--mirror-key must be github or unset');
+  }
+  else if (a === '--source' || a === '--verify') {
+    const v = args[++i];
+    if (!v || v.startsWith('--')) usage(`${a} requires a value`);
+    if (a === '--source') opts.source = v;
+    else verifySha = v;
+  } else if (a === '--help' || a === '-h') usage();
+  else usage(`unknown argument '${a}'`);
+}
+
+const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+if (top.status !== 0) {
+  console.error('github-export: refused — not inside a git work tree');
+  process.exit(1);
+}
+
+const git = createGitRunner(top.stdout.trim());
+
+if (plainGuard) {
+  if (args.length !== 3 || mirrorKey === null) usage('--plain-guard takes exactly --mirror-key <github|unset>');
+  const verdict = plainPushGuard({ git, explicitGithub: mirrorKey === 'github' });
+  if (!verdict.ok) {
+    console.error(`github-export: plain push refused — ${verdict.reason}`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+if (verifySha !== null) {
+  if (opts.dryRun) usage('--verify does not combine with --dry-run');
+  const verdict = verifyExportCommit({ git, sha: verifySha, source: opts.source });
+  if (!verdict.ok) {
+    console.error(`github-export: verify refused — ${verdict.reason}`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+const result = buildGithubExport({ git, ...opts });
+
+if (result.stats) {
+  const s = result.stats;
+  console.error(
+    `github-export: source files ${s.sourceFiles}, excluded ${s.excludedFiles}, snapshot files ${s.snapshotFiles}, changed vs parent ${s.changedVsParent}`,
+  );
+}
+for (const line of result.findings ?? []) console.error(line);
+for (const line of result.warnings ?? []) console.error(`github-export: WARN — ${line} (a real export would refuse)`);
+
+switch (result.status) {
+  case 'created':
+    console.log(result.sha);
+    process.exit(0);
+    break;
+  case 'unchanged':
+    console.log(result.sha);
+    console.error('github-export: nothing to publish — snapshot tree equals github main, no new commit');
+    process.exit(3);
+    break;
+  case 'dry-run':
+    console.error(`github-export: dry-run — ${result.stats?.unchanged ? 'tree unchanged' : 'snapshot built and scanned'}, refs/heads/github-export not updated`);
+    process.exit(0);
+    break;
+  default:
+    console.error(`github-export: refused — ${result.reason}`);
+    process.exit(1);
+}

package/scripts/github-protection-audit.mjs

@@ -9,7 +9,9 @@
  * the DEPLOYING path is the SAME as the REVIEWING path. This repo's GitHub
  * mirror breaks that: `origin` (GitLab) is reviewed via MR, `github` is
  * pushed directly by `skills/session-end/SKILL.md`'s mirror-push block
- * (`git push github HEAD`, no MR, no review) — and since a Vercel Git
+ * (`git push github HEAD`, or with `mirror: curated` (#1631) one verified
+ * snapshot `git push github <sha>:refs/heads/main`, published only through
+ * /close; no MR, no review either way) — and since a Vercel Git
  * integration deploys on every push to that mirror's `main`, a compromised
  * mirror token or an admin bypass IS a deploy with zero review. See
  * `docs/github-mirror-protection.md` for the full runbook.

package/scripts/handover-queue-check.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * handover-queue-check.mjs — every open point of a fleet handover carries a
+ * queue mark before the session reports "Bereit zum Schließen." (#1639).
+ *
+ * Callers: `skills/_shared/fleet-protocol.md` § Übergabe und Zug-Manifest
+ * Schritt 1a (the waiting turn that writes the file) and session-end § 4.5
+ * (re-check at `/close`). Parsing lives in `lib/handover-queue-marks.mjs`.
+ *
+ * Usage:
+ *   node scripts/handover-queue-check.mjs (--file <path> | --fleet-dir <dir> --since <iso>)
+ *        [--name <name>] [--apply --repo <repo> [--navigator-cli <path>]] [--json]
+ *
+ *   --file           the handover or train manifest to check
+ *   --fleet-dir/--since  newest of uebergabe-<name>.md, uebergabe-<name>-*.md,
+ *                    <name>-zug-*.md in <dir> modified at or after <iso> or
+ *                    epoch ms (the session's start, e.g. `startedAt` of its
+ *                    ~/.claude/sessions entry): session names repeat across days, so an
+ *                    older file of the same name is a predecessor's (#1639 F1)
+ *   --name           the session name; queue titles read `<name>: <point>`
+ *                    (required with --fleet-dir and with --apply)
+ *   --apply          file each unmarked point via `owner-queue add --json`
+ *                    and write `queue:#<id>` into the file; points under an
+ *                    owner/decision heading are reported, never filed. Only
+ *                    for an own file (the --fleet-dir name pattern for
+ *                    --name); a foreign file is refused untouched (#1647).
+ *                    Check mode without --apply reads any file.
+ *   --repo           owner-queue repo name (required with --apply)
+ *   --navigator-cli  coordinator CLI: a `.js` path runs under node, anything
+ *                    else as a binary; default `navigator` from PATH
+ *
+ * Exit: 0 every open point marked (or no fleet integration: nothing to do) ·
+ *       3 unmarked points remain (listed on stdout) · 2 usage error ·
+ *       4 --apply on a file that is not the session's own — foreign name, a
+ *         symlink, or older than --since (nothing filed or written).
+ */
+
+import { spawnSync } from 'node:child_process';
+import { lstatSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { fleetIntegrationEnabled } from './lib/fleet-protocol.mjs';
+import { findOpenPoints, insertMarks, kindFor, refFor, unmarkedPoints } from './lib/handover-queue-marks.mjs';
+
+const EXIT_OK = 0;
+const EXIT_USAGE = 2;
+const EXIT_UNMARKED = 3;
+const EXIT_FOREIGN = 4;
+
+function parseArgs(argv) {
+  const out = { apply: false, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--apply') out.apply = true;
+    else if (a === '--json') out.json = true;
+    else if (['--file', '--name', '--fleet-dir', '--since', '--repo', '--navigator-cli'].includes(a)) {
+      const v = argv[++i];
+      if (v === undefined || v.startsWith('--')) throw new Error(`${a} needs a value`);
+      out[a.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = v;
+    } else throw new Error(`unknown argument: ${a}`);
+  }
+  if (!out.file && !(out.name && out.fleetDir && out.since)) {
+    throw new Error('need --file, or --fleet-dir with --name and --since');
+  }
+  if (out.since !== undefined) {
+    // ISO date, or epoch ms as the session registry's `startedAt` carries it.
+    out.sinceMs = /^\d+$/.test(out.since) ? Number(out.since) : Date.parse(out.since);
+    if (Number.isNaN(out.sinceMs)) throw new Error(`--since is not a date: ${out.since}`);
+  }
+  if (out.apply && !out.repo) throw new Error('--apply needs --repo');
+  if (out.apply && !out.name) throw new Error('--apply needs --name');
+  return out;
+}
+
+/**
+ * True when basename `f` is a handover or train file of session `name`:
+ * `uebergabe-<name>.md`, `uebergabe-<name>-*.md` or `<name>-zug-*.md`. The
+ * hyphen after `<name>` keeps `uebergabe-foo2-*.md` out of `foo`'s files.
+ */
+function isOwnHandover(f, name) {
+  return (
+    f.endsWith('.md') &&
+    (f === `uebergabe-${name}.md` || f.startsWith(`uebergabe-${name}-`) || f.startsWith(`${name}-zug-`))
+  );
+}
+
+/** Newest handover/train file of `name` in `dir` modified at/after `sinceMs`, or null. */
+function newestHandover(dir, name, sinceMs) {
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const own = names.filter((f) => isOwnHandover(f, name));
+  const withTime = own.map((f) => ({ f, t: statSync(join(dir, f)).mtimeMs })).filter((x) => x.t >= sinceMs);
+  withTime.sort((a, b) => b.t - a.t);
+  return withTime.length ? join(dir, withTime[0].f) : null;
+}
+
+/** `owner-queue add --json` → queue id (exit 0: new, exit 4: existing), or an error string. */
+function fileQueueItem(cli, { repo, kind, title, ref }) {
+  const args = ['--json', 'owner-queue', 'add', '--repo', repo, '--kind', kind, '--waits-on', 'lead', '--title', title];
+  if (ref) args.push('--ref', ref);
+  const [cmd, argv] = cli.endsWith('.js') ? [process.execPath, [cli, ...args]] : [cli, args];
+  const r = spawnSync(cmd, argv, { encoding: 'utf8', timeout: 30_000 });
+  if (r.error) return { error: r.error.code ?? r.error.message };
+  let parsed;
+  try {
+    parsed = JSON.parse((r.stdout || '').trim().split('\n').pop() || 'null');
+  } catch {
+    parsed = null;
+  }
+  if (r.status === 0 && Number.isInteger(parsed?.id)) return { id: parsed.id };
+  if (r.status === 4 && Number.isInteger(parsed?.ids?.[0])) return { id: parsed.ids[0] };
+  return { error: `owner-queue add exit ${r.status}` };
+}
+
+function main() {
+  let opts;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`handover-queue-check: ${err.message}\n`);
+    return EXIT_USAGE;
+  }
+  const say = (obj, text) => process.stdout.write(opts.json ? `${JSON.stringify(obj)}\n` : `${text}\n`);
+
+  if (!fleetIntegrationEnabled()) {
+    say({ fleet: false, unmarked: 0 }, 'handover-queue-check: keine Flottenintegration — nichts zu prüfen');
+    return EXIT_OK;
+  }
+  const file = opts.file ?? newestHandover(opts.fleetDir, opts.name, opts.sinceMs);
+  if (!file) {
+    say({ fleet: true, file: null, unmarked: 0 }, 'handover-queue-check: keine Übergabe-Datei gefunden');
+    return EXIT_OK;
+  }
+  // --apply writes into the file and files queue items titled with --name:
+  // only the session's own file qualifies (#1647: a fleet-wide loop over
+  // --file marked 17 foreign handovers).
+  // The name alone is not enough: a symlink named like an own file writes
+  // through to its target, and session names repeat across days, so with
+  // --since an older file of the same name is a predecessor's (#1639 F1).
+  if (opts.apply) {
+    let st = null;
+    try {
+      st = lstatSync(file);
+    } catch {
+      // unreadable: the read below reports it
+    }
+    const reason = !isOwnHandover(basename(file), opts.name)
+      ? 'fremde Datei'
+      : st?.isSymbolicLink()
+        ? 'Symlink'
+        : st && opts.sinceMs !== undefined && st.mtimeMs < opts.sinceMs
+          ? 'Datei älter als --since (Vorgänger gleichen Namens)'
+          : null;
+    if (reason) {
+      process.stderr.write(`handover-queue-check: ${reason}: ${basename(file)} — --apply nur für die eigene Übergabe von ${opts.name}\n`);
+      return EXIT_FOREIGN;
+    }
+  }
+  let content;
+  try {
+    content = readFileSync(file, 'utf8');
+  } catch (err) {
+    process.stderr.write(`handover-queue-check: ${file} unlesbar (${err.code ?? err.message})\n`);
+    return EXIT_USAGE;
+  }
+
+  let open = unmarkedPoints(findOpenPoints(content));
+  const filed = [];
+  const failed = [];
+  if (opts.apply && open.length > 0) {
+    const cli = opts.navigatorCli ?? 'navigator';
+    const ids = new Map();
+    for (const p of open) {
+      const kind = kindFor(p);
+      if (kind === null) {
+        failed.push({ line: p.line + 1, error: 'Owner-Entscheid: mit --options/--class selbst anlegen' });
+        continue;
+      }
+      // The CLI shortens titles over 200 code units itself (cleanly, with a
+      // WARN); slicing here could split a surrogate pair.
+      const title = `${opts.name}: ${p.text}`;
+      const r = fileQueueItem(cli, { repo: opts.repo, kind, title, ref: refFor(p, opts.repo) });
+      if (r.id !== undefined) {
+        ids.set(p.line, r.id);
+        filed.push({ line: p.line + 1, id: r.id });
+      } else {
+        failed.push({ line: p.line + 1, error: r.error });
+      }
+    }
+    if (ids.size > 0) {
+      content = insertMarks(content, ids);
+      writeFileSync(file, content);
+    }
+    open = open.filter((p) => !ids.has(p.line));
+  }
+
+  const unmarked = open.map((p) => ({ line: p.line + 1, section: p.section, text: p.text }));
+  const lines = [`handover-queue-check: ${basename(file)} — ${unmarked.length} Punkt(e) ohne Queue-ID`];
+  for (const f of filed) lines.push(`  angelegt: Zeile ${f.line} → queue:#${f.id}`);
+  for (const u of unmarked) lines.push(`  offen: Zeile ${u.line} [${u.section}] ${u.text}`);
+  for (const f of failed) lines.push(`  Anlegen gescheitert: Zeile ${f.line} (${f.error})`);
+  say({ fleet: true, file, unmarked: unmarked.length, filed, failed, points: unmarked }, lines.join('\n'));
+  return unmarked.length > 0 ? EXIT_UNMARKED : EXIT_OK;
+}
+
+process.exitCode = main();

package/scripts/harness-audit.mjs

@@ -15,7 +15,7 @@
  */
 
 import { existsSync, readFileSync, mkdirSync, appendFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { execFileSync } from 'node:child_process';
 
 import {
@@ -29,6 +29,7 @@ import {
   runCategory8,
   runCategory9,
 } from './lib/harness-audit/categories.mjs';
+import { resolveLedgerPath } from './lib/ledger-path.mjs';
 
 const RUBRIC_VERSION = '2026-06';
 
@@ -193,11 +194,12 @@ function writeSummary(categories, summary) {
 // ---------------------------------------------------------------------------
 
 function appendAuditRecord(root, record) {
-  const metricsDir = join(root, '.orchestrator/metrics');
+  // #1722: main checkout's copy when root is a linked worktree that gitignores it.
+  const ledger = resolveLedgerPath('.orchestrator/metrics/audit.jsonl', root);
   try {
-    mkdirSync(metricsDir, { recursive: true });
+    mkdirSync(dirname(ledger), { recursive: true });
     const line = JSON.stringify(record) + '\n';
-    appendFileSync(join(metricsDir, 'audit.jsonl'), line, 'utf8');
+    appendFileSync(ledger, line, 'utf8');
   } catch (err) {
     process.stderr.write(`harness-audit: Failed to append audit.jsonl: ${err.message}\n`);
   }

package/scripts/lib/agent-frontmatter.mjs

@@ -31,6 +31,35 @@ const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 export const ALLOWED_MODEL_ALIASES = new Set(['inherit', 'sonnet', 'opus', 'haiku', 'fable']);
 export const MODEL_ID_RE = /^claude-(opus|sonnet|haiku|fable)-\d+(-\d+)?(-\d{8})?$/;
 
+// Reasoning effort per https://code.claude.com/docs/en/sub-agents (#1614).
+// REQUIRED whenever `model` is not `inherit`: the per-model default differs
+// (Sonnet 5.5 defaults to `high`, Opus 5.5 to `medium`), so a pinned model
+// without an explicit effort silently thinks longer than the role needs.
+// With `model: inherit` the agent follows the session, effort included.
+export const ALLOWED_EFFORTS = new Set(['low', 'medium', 'high', 'xhigh', 'max']);
+
+/**
+ * The effort rule shared by this validator and check-agents.mjs (#1614).
+ *
+ * @param {unknown} model - the frontmatter `model` value
+ * @param {unknown} effort - the frontmatter `effort` value (undefined when absent)
+ * @returns {{ rule: 'required'|'enum', message: string } | null} null when valid
+ */
+export function checkAgentEffort(model, effort) {
+  const effortList = [...ALLOWED_EFFORTS].join('|');
+  if (effort === undefined || effort === null || effort === '') {
+    if (model === undefined || model === '' || model === 'inherit') return null;
+    return {
+      rule: 'required',
+      message: `effort is required when model is not inherit (got model ${JSON.stringify(model)}); set effort: ${effortList}`,
+    };
+  }
+  if (!ALLOWED_EFFORTS.has(/** @type {string} */ (effort))) {
+    return { rule: 'enum', message: `effort must be one of ${effortList} (got ${JSON.stringify(effort)})` };
+  }
+  return null;
+}
+
 // Canonical Anthropic palette (red|blue|green|yellow|purple|orange|pink|cyan)
 // plus magenta from plugin-dev SKILL.md for backward-compat.
 const ALLOWED_COLORS = new Set(['blue', 'cyan', 'green', 'yellow', 'magenta', 'red', 'purple', 'orange', 'pink']);
@@ -129,8 +158,14 @@ export function parseAgentFrontmatter(contents) {
 /**
  * Validates a parsed frontmatter object against CLAUDE.md Agent Authoring Rules.
  *
+ * `warnings` is present only when non-empty and never flips `ok`. A missing
+ * `effort` on a pinned model is a warning here, because this validator also
+ * reads consumer `.claude/agents` (discovery probe); the plugin's own agents
+ * fail on it in check-agents.mjs. A set but invalid `effort` stays an error.
+ *
  * @param {Record<string,string>|null|undefined} frontmatter
- * @returns {{ ok: true }|{ ok: false, errors: Array<{path: string, rule: string, message: string}> }}
+ * @returns {{ ok: true, warnings?: Array<{path: string, rule: string, message: string}> }
+ *          |{ ok: false, errors: Array<{path: string, rule: string, message: string}>, warnings?: Array<{path: string, rule: string, message: string}> }}
  */
 export function validateAgentFrontmatter(frontmatter) {
   if (frontmatter === null || frontmatter === undefined || typeof frontmatter !== 'object') {
@@ -141,6 +176,7 @@ export function validateAgentFrontmatter(frontmatter) {
   }
 
   const errors = /** @type {Array<{path: string, rule: string, message: string}>} */ ([]);
+  const warnings = /** @type {Array<{path: string, rule: string, message: string}>} */ ([]);
 
   // --- name ---
   const name = frontmatter['name'];
@@ -171,7 +207,7 @@ export function validateAgentFrontmatter(frontmatter) {
       path: 'description',
       rule: 'no-block-scalar',
       message:
-        'description must be an inline single-line string, not a YAML block scalar (> or |). Put <example> blocks inline.',
+        'description must be an inline single-line string, not a YAML block scalar (> or |). Keep it to the routing sentence; put <example> blocks in a body `## Examples` section.',
     });
   }
 
@@ -191,6 +227,20 @@ export function validateAgentFrontmatter(frontmatter) {
     });
   }
 
+  // --- effort (#1614): missing on a pinned model = warning, invalid value = error ---
+  const effortError = checkAgentEffort(model, frontmatter['effort']);
+  if (effortError) (effortError.rule === 'required' ? warnings : errors).push({ path: 'effort', ...effortError });
+
+  // --- omitClaudeMd (optional boolean, #1616) ---
+  const omit = frontmatter['omitClaudeMd'];
+  if (omit !== undefined && omit !== 'true' && omit !== 'false' && omit !== true && omit !== false) {
+    errors.push({
+      path: 'omitClaudeMd',
+      rule: 'boolean',
+      message: `omitClaudeMd must be true or false (got ${JSON.stringify(omit)})`,
+    });
+  }
+
   // --- color ---
   const color = frontmatter['color'];
   if (color === undefined || color === '') {
@@ -244,7 +294,8 @@ export function validateAgentFrontmatter(frontmatter) {
     }
   }
 
-  return errors.length > 0 ? { ok: false, errors } : { ok: true };
+  const warn = warnings.length > 0 ? { warnings } : {};
+  return errors.length > 0 ? { ok: false, errors, ...warn } : { ok: true, ...warn };
 }
 
 /**
@@ -253,8 +304,8 @@ export function validateAgentFrontmatter(frontmatter) {
  * Never throws. Returns a result object with the file path attached.
  *
  * @param {string} filePath - absolute or relative path to the agent .md file
- * @returns {{ ok: true, file: string }
- *          |{ ok: false, file: string, errors: Array<{path: string, rule: string, message: string}> }}
+ * @returns {{ ok: true, file: string, warnings?: Array<{path: string, rule: string, message: string}> }
+ *          |{ ok: false, file: string, errors: Array<{path: string, rule: string, message: string}>, warnings?: Array<{path: string, rule: string, message: string}> }}
  */
 export function validateAgentFile(filePath) {
   let contents;
@@ -280,9 +331,5 @@ export function validateAgentFile(filePath) {
   }
 
   const validation = validateAgentFrontmatter(parsed.frontmatter);
-  if (!validation.ok) {
-    return { ok: false, file: filePath, errors: validation.errors };
-  }
-
-  return { ok: true, file: filePath };
+  return { ...validation, file: filePath };
 }