session-orchestrator 5.1.0 → 5.2.0

package/scripts/relocate-vault-corpus.mjs

@@ -40,7 +40,6 @@
 
 import { promises as fs, existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
 import path from 'node:path';
 import {
   loadVaultRelocationRules,
@@ -55,6 +54,7 @@ import {
 } from './lib/vault-relocation-rules.mjs';
 import { buildBackfillIndex, parseSessionId } from './lib/vault-repo-backfill.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -1158,8 +1158,7 @@ async function main() {
 // Entry guard (run only when invoked directly)
 // ---------------------------------------------------------------------------
 
-const invokedDirectly =
-  process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+const invokedDirectly =isMainModule(import.meta.url);
 
 if (invokedDirectly) {
   main().catch((err) => {

package/scripts/repair-invalid-sessions.mjs

@@ -37,10 +37,10 @@
 import fs from 'node:fs';
 import { parseArgs } from 'node:util';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 import { repairLedger, CANONICAL_LEDGER_REL } from './lib/session-record-repair.mjs';
 import { getProjectDir } from './lib/platform.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const USAGE =
   'Usage: node scripts/repair-invalid-sessions.mjs [--dry-run|--apply] [--json]\n' +
@@ -200,7 +200,7 @@ async function main() {
   process.exit(summary.ok === false ? 3 : 0);
 }
 
-const isDirectRun = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+const isDirectRun =isMainModule(import.meta.url);
 if (isDirectRun) {
   main().catch((err) => {
     process.stderr.write(`repair-invalid-sessions: unexpected error: ${err?.stack ?? err}\n`);

package/scripts/session-shape.mjs

@@ -42,10 +42,10 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
-import { fileURLToPath } from 'node:url';
 import { resolveInstructionFile } from './lib/common.mjs';
 import { parseSessionConfig } from './lib/config.mjs';
 import { resolveAndRecordSessionShape } from './lib/session-shape.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const USAGE = [
   'Usage: node scripts/session-shape.mjs --repo-root <path> --session-type <housekeeping|feature|deep>',
@@ -258,7 +258,7 @@ async function main() {
 }
 
 // Entrypoint guard — importing this file must not run it (check-unwired-features S3).
-if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+if (isMainModule(import.meta.url)) {
   main().catch((err) => {
     process.stderr.write(`session-shape: unexpected error: ${err?.stack ?? err}\n`);
     process.exit(EXIT_CONFIG_IO);

package/scripts/site-numbers.mjs

@@ -101,10 +101,11 @@
 import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join, resolve, relative } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
 
 import { writeStdoutLineSync, writeJsonAtomicSync } from './lib/io.mjs';
 import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+import { slashCommandNames } from './lib/user-invocable-skills.mjs';
 
 /** Machine-readable schema tag for the --json envelope. */
 export const SCHEMA = 'site-numbers/1';
@@ -169,11 +170,37 @@ export function countSkills(root) {
   return n;
 }
 
-/** `ls commands/*.md | wc -l` — same basis as checker.mjs `command-count`. */
+/**
+ * The product's "slash commands" number: `commands/*.md` ∪ skills carrying an
+ * EXPLICIT `user-invocable: true`, deduplicated by name.
+ *
+ * NOT `ls commands/*.md | wc -l` any more, and the change is not cosmetic. After
+ * the 2026-09-16 fold (#1370) `commands/` holds two files — `session` and
+ * `templates-ack`, the only two names a skill cannot carry — while 26 operator-
+ * facing slash commands exist. A command file only ever resolved because a
+ * same-named skill existed, and the twin additionally listed the entry twice in
+ * the `/` picker; the skill frontmatter flag is what makes a slash command a
+ * slash command now. Counting the directory would have reported 2.
+ *
+ * Dedup by name is load-bearing: a name present on BOTH sides is the picker-
+ * duplicate defect (`tests/commands/headless-bare-command-availability.test.mjs`
+ * fails on it), so it must count once here rather than inflate the tile.
+ *
+ * null (→ the tile renders as unmeasured) only when NEITHER `commands/` nor
+ * `skills/` exists — i.e. this is not a plugin tree at all. A tree with one of
+ * the two counts what it has; a missing `commands/` is now the NORMAL state, not
+ * a missing measurement.
+ *
+ * NO divergence from `skills/claude-md-drift-check/checker.mjs` `command-count`:
+ * that checker unions the same user-invocable skills (`checker.mjs:435-446`,
+ * measured 2026-09-17), and both routes reach the same verdict through the same
+ * SSOT — `isUserInvocableValue` in `scripts/lib/user-invocable-skills.mjs`. The
+ * checker stays GENERIC over consumer repos only in the sense that a repo
+ * without `skills/` sees the union collapse to the directory count on its own.
+ */
 export function countCommands(root) {
-  const dir = join(root, 'commands');
-  if (!isDir(dir)) return null;
-  return readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith('.')).length;
+  if (!isDir(join(root, 'commands')) && !isDir(join(root, 'skills'))) return null;
+  return slashCommandNames(root).length;
 }
 
 /**
@@ -400,7 +427,8 @@ export const METRIC_DEFS = Object.freeze([
   {
     id: 'commands',
     provenance: false,
-    source: 'ls commands/*.md | wc -l',
+    source:
+      'ls commands/*.md | wc -l  +  grep -l "^user-invocable: true" skills/*/SKILL.md | wc -l   (union by name — see countCommands)',
     compute: (root) => fmtCount(countCommands(root)),
   },
   {
@@ -1398,11 +1426,7 @@ export function main(argv = process.argv.slice(2), env = {}) {
   return exitCode;
 }
 
-const isMain =
-  typeof process !== 'undefined' &&
-  process.argv[1] !== null &&
-  process.argv[1] !== undefined &&
-  resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+const isMain =isMainModule(import.meta.url);
 
 if (isMain) {
   const argv = process.argv.slice(2);

package/scripts/sweep-expired-rules.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/**
+ * sweep-expired-rules.mjs — CLI for the generated-rule expiry sweep (#1377).
+ *
+ * The sibling of `scripts/sweep-expired-learnings.mjs`, one corpus over:
+ * that one moves expired LEARNINGS out of `learnings.jsonl`, this one removes
+ * expired ENTRIES from the consolidated `.claude/rules/*.md` files that were
+ * generated from them. `scripts/lib/rule-loader.mjs` already refuses to inject
+ * an expired generated rule; nothing until now removed one from disk.
+ *
+ * All planning and writing logic lives in
+ * `scripts/lib/reconcile/rule-expiry-sweep.mjs`
+ * (`planRuleExpirySweep` / `applyRuleExpirySweep`). This file is argv parsing,
+ * output formatting, the event emit, and exit codes — nothing else.
+ *
+ * SAFETY: `--dry-run` is the DEFAULT and writes nothing. `--apply` is the only
+ * write path, and it rewrites or deletes TRACKED files under `.claude/rules/`.
+ *
+ * Usage:
+ *   node scripts/sweep-expired-rules.mjs [--dry-run|--apply] [--json]
+ *     [--grace-days N] [--now ISO] [--repo-root PATH] [--learnings PATH]
+ *
+ * Exit codes (the same contract as the learnings sweep CLI, deliberately —
+ * two sibling commands with inverted codes is a trap for the operator who
+ * learns one of them):
+ *   0  Success, including the no-op when nothing is expired
+ *   1  Usage/invocation error (bad flag or value)
+ *   2  Sweep error (an I/O or validation failure inside the lib, or any
+ *      per-file error on the `--apply` path)
+ */
+
+import { emitEvent } from './lib/events.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+import {
+  RULE_EXPIRY_SWEEP_EVENT,
+  applyRuleExpirySweep,
+  planRuleExpirySweep,
+} from './lib/reconcile/rule-expiry-sweep.mjs';
+
+const DEFAULT_GRACE_DAYS = 0;
+
+function printHelp() {
+  process.stdout.write(
+    `Usage: node scripts/sweep-expired-rules.mjs [--dry-run|--apply] [--json] [--grace-days N] [--now ISO] [--repo-root PATH] [--learnings PATH]
+
+Removes EXPIRED entries from the consolidated machine-generated rule files in
+.claude/rules/. An expired entry's prose block is deleted; its "## Provenance"
+pair is KEPT as a "markers only" bullet, because /reconcile dedupes on those
+markers and dropping one re-proposes the learning. A file is deleted only when
+every substantive entry expired, and every provenance key is stamped terminal
+before the unlink.
+
+Options:
+  --dry-run         Preview the plan; write nothing (DEFAULT)
+  --apply           Perform the rewrites/deletes and emit the ledger event
+  --json            Emit a single machine-parseable JSON summary line
+  --grace-days N    Days past expiry before an entry is swept (default: ${DEFAULT_GRACE_DAYS})
+  --now ISO         Injected clock (testing / what-if planning)
+  --repo-root PATH  Repo root (default: process.cwd())
+  --learnings PATH  Learnings store, repo-relative (default: the metrics store)
+
+Exit codes:  0 success  1 usage/invocation error  2 sweep error
+`,
+  );
+}
+
+/** Exit 1 with a diagnostic on stderr (usage/invocation errors). */
+function usageError(message) {
+  process.stderr.write(`sweep-expired-rules: ${message}\n`);
+  process.exit(1);
+}
+
+export function parseArgs(argv) {
+  const args = {
+    dryRun: true,
+    json: false,
+    graceDays: DEFAULT_GRACE_DAYS,
+    now: null,
+    repoRoot: process.cwd(),
+    learnings: null,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--apply') args.dryRun = false;
+    else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--json') args.json = true;
+    else if (a === '--grace-days') {
+      const raw = argv[++i];
+      const v = Number(raw);
+      if (!Number.isFinite(v) || v < 0) {
+        usageError(`--grace-days requires a non-negative number, got: ${raw}`);
+      }
+      args.graceDays = v;
+    } else if (a === '--now') {
+      const raw = argv[++i];
+      if (typeof raw !== 'string' || !Number.isFinite(Date.parse(raw))) {
+        usageError(`--now requires an ISO timestamp, got: ${raw}`);
+      }
+      args.now = raw;
+    } else if (a === '--repo-root') {
+      const raw = argv[++i];
+      if (typeof raw !== 'string' || raw.length === 0) usageError('--repo-root requires a path');
+      args.repoRoot = raw;
+    } else if (a === '--learnings') {
+      const raw = argv[++i];
+      if (typeof raw !== 'string' || raw.length === 0) usageError('--learnings requires a path');
+      args.learnings = raw;
+    } else if (a === '--help' || a === '-h') {
+      printHelp();
+      process.exit(0);
+    } else {
+      usageError(`unknown argument: ${a}`);
+    }
+  }
+  return args;
+}
+
+/** Roll the plan up into the summary both output modes render. */
+function summarize(plan, args, applied) {
+  const counts = { rewrite: 0, delete: 0, keep: 0 };
+  for (const p of plan.plans) counts[p.action] = (counts[p.action] ?? 0) + 1;
+  return {
+    dry_run: args.dryRun,
+    grace_days: args.graceDays,
+    files_scanned: plan.plans.length,
+    rewrites: counts.rewrite,
+    deletes: counts.delete,
+    keeps: counts.keep,
+    expired_entries: plan.plans.reduce((n, p) => n + p.expiredPairIds.length, 0),
+    unresolved_pairs: plan.plans.reduce((n, p) => n + p.unresolvedPairIds.length, 0),
+    malformed_lines: plan.malformedLines,
+    rules_dir_readable: plan.ok,
+    skipped: plan.skipped,
+    plans: plan.plans.map(({ nextContent: _nextContent, ...rest }) => rest),
+    ...(applied ? { applied } : {}),
+  };
+}
+
+async function main(argv) {
+  const args = parseArgs(argv);
+
+  let plan;
+  try {
+    plan = await planRuleExpirySweep({
+      repoRoot: args.repoRoot,
+      now: args.now ?? undefined,
+      graceDays: args.graceDays,
+      learningsPath: args.learnings ?? undefined,
+    });
+  } catch (err) {
+    process.stderr.write(`sweep-expired-rules: planning failed: ${err?.message ?? err}\n`);
+    process.exit(2);
+  }
+
+  let applied = null;
+  if (!args.dryRun) {
+    applied = applyRuleExpirySweep(plan, { repoRoot: args.repoRoot, now: args.now ?? undefined });
+  }
+
+  const summary = summarize(plan, args, applied);
+
+  if (args.json) process.stdout.write(`${JSON.stringify(summary)}\n`);
+  else {
+    process.stdout.write(
+      `sweep-expired-rules: ${args.dryRun ? 'dry-run' : 'applied'} — ` +
+        `${summary.files_scanned} generated rule file(s), ${summary.rewrites} rewrite(s), ` +
+        `${summary.deletes} delete(s), ${summary.expired_entries} expired entr(ies), ` +
+        `${summary.unresolved_pairs} unresolved pair(s), ${summary.skipped.length} skipped, ` +
+        `${summary.malformed_lines} malformed learnings line(s)\n`,
+    );
+    for (const s of plan.skipped) process.stdout.write(`  skipped ${s.file}: ${s.reason}\n`);
+    for (const p of plan.plans) {
+      if (p.advisory) process.stdout.write(`  advisory ${p.file}: ${p.advisory}\n`);
+    }
+  }
+
+  if (applied) {
+    for (const e of applied.errors) {
+      process.stderr.write(`sweep-expired-rules: ${e.file}: ${e.error}\n`);
+    }
+    // Emitted on apply ONLY, and AFTER the writes: a record's presence is proof
+    // that `.claude/rules/` was actually changed, never that a preview ran.
+    // Wrapped because `emitEvent` THROWS `EventValidationError` — a telemetry
+    // failure must not turn a completed sweep into a non-zero exit.
+    try {
+      await emitEvent(
+        RULE_EXPIRY_SWEEP_EVENT,
+        {
+          rewritten: applied.rewritten.length,
+          deleted: applied.deleted.length,
+          stamped: applied.stamped,
+          write_errors: applied.errors.length,
+          expired_entries: summary.expired_entries,
+          files_scanned: summary.files_scanned,
+          source: 'sweep-expired-rules-cli',
+        },
+        { repoRoot: args.repoRoot },
+      );
+    } catch (err) {
+      process.stderr.write(`sweep-expired-rules: event emit failed: ${err?.message ?? err}\n`);
+    }
+    if (applied.errors.length > 0) process.exit(2);
+  }
+
+  if (!plan.ok) {
+    process.stderr.write(
+      'sweep-expired-rules: .claude/rules/ exists but could not be enumerated — ' +
+        'the plan above is INCOMPLETE, not clean.\n',
+    );
+    process.exit(2);
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  await main(process.argv.slice(2));
+}

package/scripts/validate-plugin.mjs

@@ -424,6 +424,15 @@ if (runCheck('check-unicode-safety.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-dead-bridge.mjs') !== 0) checkFailed = 1;
 
+// BLOCKING (#1371): a hand-written `process.argv[1] === import.meta.url` entry
+// guard is false under any symlinked invocation, so main() never runs and the
+// process still exits 0 — the caller reads silence as success. This can block
+// honestly because the backlog was drained to zero in the same change: the check
+// is not red on arrival for work nobody intends to do (contrast the WARN-only
+// censuses below, each of which had a standing backlog when it landed).
+process.stdout.write('\n');
+if (runCheck('check-entry-guard.mjs') !== 0) checkFailed = 1;
+
 // FAIL-capable, unlike the WARN-only censuses below: R2+R4 were measured at
 // 1 hit / 1 TP / 0 FP each against the full test corpus, so this check cannot be
 // red on arrival for anything but a real instance of the class. The alternatives

package/scripts/vault-consolidate.mjs

@@ -84,7 +84,6 @@
 
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import { die, utcTimestamp, expandTilde } from './lib/common.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
@@ -96,6 +95,7 @@ import {
   stageBackup,
   compressAndCleanupBackup,
 } from './lib/vault-consolidate-fs.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const DEFAULT_SOURCE = '~/Projects/vault';
 const DEFAULT_CANONICAL = '~/Projects/Bernhard/vault';
@@ -580,7 +580,7 @@ async function main() {
 // `process.argv[1]` is undefined when the module is loaded via `node -e
 // "import(...)"` (no script path in argv), so guard against it before calling
 // pathToFileURL — otherwise the import itself throws ERR_INVALID_ARG_TYPE.
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isMainModule(import.meta.url)) {
   main().catch((e) => {
     console.error(e);
     process.exit(1);

package/scripts/vault-mirror.mjs

@@ -53,7 +53,6 @@ import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import { createReadStream } from 'node:fs';
-import { pathToFileURL } from 'node:url';
 
 import { processLearning, processSession, getMaskerStats } from './lib/vault-mirror/process.mjs';
 import { emitMirrorEvent, emitMirrorRunEvent } from './lib/vault-mirror/telemetry.mjs';
@@ -64,6 +63,7 @@ import { resolveRepoNamespace } from './lib/vault-mirror/namespace.mjs';
 import { resolveCanonicalSuffixes } from './lib/named-vault-resolver.mjs';
 import { loadOwnerConfig } from './lib/owner-yaml.mjs';
 import { canonicalizeSessions } from './lib/sessions-canonical.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 // ── Canonical-vault helpers (#600 D2 / #607 D2) ────────────────────────────────
 // These are module-level (above the CLI bootstrap) so the module is import-safe
@@ -166,8 +166,7 @@ export function _normalizeRemote(url) {
 // (`node vault-mirror.mjs ...`). When imported from a unit test, argv belongs to
 // the test runner — parsing it would spuriously process.exit. The exported
 // helpers above are unaffected by this guard.
-const _isDirectInvocation =
-  Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
+const _isDirectInvocation =isMainModule(import.meta.url);
 
 if (_isDirectInvocation) {
   let parsedFlags;

package/scripts/wave-scope-binding.mjs

@@ -37,10 +37,9 @@
  */
 
 import { parseArgs } from 'node:util';
-import { resolve as resolvePath } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { attributionForRecord, emitEvent } from './lib/events.mjs';
 import { MANIFEST_SESSION_KEYS } from './lib/session-identity/own-session.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const HELP = `Usage: node scripts/wave-scope-binding.mjs [--merge] [--wave N] [--role R] [--repo-root DIR]
 
@@ -210,6 +209,6 @@ function readStdin() {
 
 // `import.meta.main` is not available on every supported Node — compare argv[1]
 // instead, so importing this module from a test never runs the CLI.
-if (process.argv[1] && fileURLToPath(import.meta.url) === resolvePath(process.argv[1])) {
+if (isMainModule(import.meta.url)) {
   await main(process.argv.slice(2));
 }

package/skills/_shared/bootstrap-gate.md

@@ -102,7 +102,7 @@ source: projects-baseline | plugin-template | claude-init
 
 A repo that has already been bootstrapped passes the gate on every subsequent invocation with zero overhead. The gate check reads three files and performs two grep operations — negligible cost.
 
-`/bootstrap --retroactive` exists for repos that predate the gate (have `CLAUDE.md` + Session Config but no `bootstrap.lock`). It writes the lock without re-scaffolding. Documented in `commands/bootstrap.md`.
+`/bootstrap --retroactive` exists for repos that predate the gate (have `CLAUDE.md` + Session Config but no `bootstrap.lock`). It writes the lock without re-scaffolding. Documented in `skills/bootstrap/SKILL.md`.
 
 ## Auto-Skill Dispatch (opt-in, default: off)
 

package/skills/_shared/monitor-patterns.md

@@ -23,7 +23,7 @@ coverage check.
 
 ## Pattern 1 — GitLab pipeline + GitHub mirror sync (post-push)
 
-**When.** After `git push origin main` from `commands/close.md` Phase 6.
+**When.** After `git push origin main` from `skills/close/SKILL.md` Phase 6.
 Watches the GitLab pipeline through to a terminal status, then prints
 the GitHub mirror's main-branch SHA so the operator can confirm parity.
 

package/skills/_shared/research-evidence.md

@@ -0,0 +1,53 @@
+# Research Evidence Contract
+
+Use this contract when research informs a plan, audit, recommendation, or
+research-agent handoff. Scale it to the decision: a trivial local lookup may be
+one sentence; a comparison with several sources needs one record per material
+claim. It does not require external research when repository evidence is enough.
+
+## Record
+
+For each finding that changes the recommendation, retain:
+
+- **Source:** stable reference plus source revision or publication/update date.
+  For repository evidence, prefer `SHA:path:line`; for changing external facts,
+  include the observation date.
+- **Basis:** label the finding `observed` for a measurement or source-code
+  inspection (name which), `documented` for a source's claim, or `inference`
+  when it follows from other evidence. A test found in source is not an
+  executed test. Never present one class as another. Counts, percentages and
+  distributions additionally require PSA-006's executed-command transcript
+  (`.claude/rules/parallel-sessions.md` § PSA-006) — command, file scope,
+  result, measurement time.
+- **Local equivalent:** name the existing repository feature, dependency, rule,
+  or workflow that already covers the need; use `none found` only after a search
+  proportionate to the task.
+- **Disposition:** `adopt`, `adapt`, `experiment`, `reject`, or
+  `already stronger`, with one short reason. `Adopt` still means implement
+  through the current repository's conventions; it does not authorize copying,
+  installing, publishing, or another external mutation.
+- **Next check:** state one falsifiable next step when uncertainty remains: what
+  result would confirm or overturn the disposition.
+
+Keep quoted text minimal. Record limitations that materially constrain the
+claim. A source revision proves which artifact was inspected; it does not prove
+that its documented behavior works.
+
+## Private sources
+
+Treat private/internal sources as evidence for an authorized private audience
+only. Follow [Private capability context](private-capability-context.md) for
+lookup and retention. Do not copy private identities, paths, excerpts, or
+derived implementation details into a public plan or handoff. Re-establish a
+public claim from an authorized public source, or omit it. Source access never
+expands the task's implementation or external-action authority.
+
+## Compact example
+
+```text
+Source: vendor guide, rev 3.2, observed 2026-09-15
+Basis: documented — retries use exponential backoff; runtime behavior untested
+Local equivalent: src/retry.mjs already provides capped linear retries
+Disposition: experiment — compare failure recovery before changing the default
+Next check: 100 replayed failures; reject if success rate does not improve
+```

package/skills/_shared/state-ownership.md

@@ -18,6 +18,7 @@ total-waves: <N>
 # Optional fields (schema-version 1, additive for backward-compat):
 updated: <ISO 8601 UTC>      # last write timestamp, touched by any writer
 session: <session-label>     # attribution/history label; normally semantic since #573, legacy UUID-v4 remains readable; never a lock/registry ownership key
+session-id: <raw id>         # the RAW/native harness session id from session.lock (#1368); omit when absent; never a lock/registry ownership key
 session-start-ref: <sha>     # git ref at session start
 ---
 ```
@@ -25,6 +26,8 @@ session-start-ref: <sha>     # git ref at session start
 ### Required vs. optional fields
 
 - `schema-version`, `session-type`, `branch`, `issues`, `started_at`, `status`, `current-wave`, `total-waves` — **required** in every session-owned STATE.md.
+- `session-id` — **optional**, additive under `schema-version: 1` (#1368). The RAW/native harness session id, taken from `.orchestrator/session.lock` via `resolveSessionIds()` (`scripts/lib/state-md.mjs`). Writers OMIT the key when the lock yields none; readers MUST tolerate its absence. It exists so `/close`'s #429 pre-check can join STATE.md to sessions.jsonl on a NATIVE identity (`findRecordedSession`'s UUID fast path) instead of falling through to the semantic label. Like `session`, it grants no lock or registry ownership.
+- `started_at` is SOURCED from the same lock (`resolveSessionStartedAt()`), never from the writer's clock — see `skills/wave-executor/references/wave-executor-state-init.md` § Pre-Wave 1b for the template and the 48-minute drift that motivated it (#1368). On the READ side `started_at` is a CORROBORATING signal, never an identity key: `findRecordedSession()` (`scripts/lib/session-close-backfill.mjs`) joins STATE.md to `sessions.jsonl` on the native `session-id` FIRST and never consults `started_at` on that path — only the legacy-LABEL path compares the two timestamps, and it tolerates up to `STARTED_AT_DRIFT_TOLERANCE_MS` = **6 h** of drift (`session-close-backfill.mjs:559`, the single definition) before vetoing a label match: wider than any plausible write-lag (the 48 minutes above), narrower than the day the label's own date component already distinguishes.
 - `updated`, `session`, `session-start-ref` — **optional**. Added by #184. STATE.md files without these fields remain valid and should be treated as `updated: null` / `session: null`. Writers SHOULD populate these fields but readers MUST tolerate their absence. `session` is an attribution/history label, normally `<branch>-<YYYY-MM-DD>-<mode>-<n>` since #573 (Epic #568 Parallel-Aware Sessions P2.2); pre-#573 files may contain a UUID-v4 — both formats are read via `parseSessionId()` from `scripts/lib/session-id.mjs` per PRD §3 P2 row 3 (backward-compat). Neither form grants lock or registry ownership.
 
 The `session-type: none` + `status: idle` combination is used only for bootstrap-scaffolded placeholder files (no active session).

package/skills/autopilot/SKILL.md

@@ -9,12 +9,47 @@ description: >
   record per loop run. Phase C scaffold (issue #277); implementation lives in
   scripts/lib/autopilot.mjs (Phase C-1 follow-up).
 user-invocable: true
+argument-hint: "[--headless] [--verbose] [--max-sessions=N] [--max-hours=H] [--confidence-threshold=0.X] [--dry-run]"
 tags: [phase-c, autopilot, autonomous, loop]
 model: sonnet
 ---
 
 # Autopilot Skill
 
+## Invocation
+
+The user invokes `/autopilot` with arguments: **$ARGUMENTS**. This is autonomous
+session-orchestration mode — a top-level invocation only, never from inside a running
+session.
+
+Parse `$ARGUMENTS` before anything else. Unrecognized flags are ignored; out-of-range
+values silently clamp to bounds. Use `parseFlags` from `scripts/lib/autopilot.mjs` for
+canonical parsing — never re-implement clamping inline. The loop flags
+(`--max-sessions`, `--max-hours`, `--confidence-threshold`, `--dry-run`) and their
+defaults/bounds are tabled once in § Command Surface below. Two further flags belong to
+the invocation surface only:
+
+| Flag | Default | Meaning |
+|------|---------|---------|
+| `--headless` | `false` | Run via the standalone driver `scripts/autopilot.mjs`, which spawns `claude -p '/session <mode>'` as a child process per iteration. Required for unattended walk-away mode. Without it, `/autopilot` runs the in-process driver inside the current chat session (see § Production Wiring). |
+| `--verbose` | `false` | Verbose driver output. |
+
+### Headless (`claude -p`)
+
+Headless requirements:
+
+- Anthropic API key configured for `claude -p` (Claude Code CLI auth).
+- `scripts/autopilot.mjs` reads `sessions.jsonl` tail after each child exit to construct
+  the `sessionRunner` return shape — the spawned session must complete cleanly and append
+  its record (session-end Phase 3.7 handles this).
+- `AUTOPILOT_RUN_ID` env var is propagated to the child so session-end stamps it onto the
+  per-iteration `sessions.jsonl` record.
+
+Do NOT re-implement loop logic inline — this skill and `scripts/lib/autopilot.mjs` are
+authoritative. Kill-switches are enforced by `scripts/lib/autopilot.mjs`, not inline by
+Claude. The runtime writes ONE record to `.orchestrator/metrics/autopilot.jsonl` per
+invocation via atomic tmp+rename; no other code path appends to that file.
+
 ## Phase 0.5: Parallel-Aware Preamble
 
 > Skip silently when `persistence: false` in Session Config.
@@ -177,7 +212,8 @@ Phase C-1 ships `runLoop` as a pure controller. Phase C-1.c ships `buildLiveSign
 the canonical signals-assembly helper. This section documents the **in-process driver
 protocol** (Option B from #301): how Claude — running as the coordinator in a chat
 session — drives `runLoop` between manual `/session` invocations. The headless wrapper
-(Option A, `scripts/autopilot.mjs` CLI spawning `claude -p`) is reserved for Phase C-5.
+(Option A, `scripts/autopilot.mjs` CLI spawning `claude -p`) is selected with `--headless`
+— see § Invocation.
 
 ### Dependency-Injection Contract
 
@@ -187,8 +223,8 @@ session — drives `runLoop` between manual `/session` invocations. The headless
 |---|---|---|
 | `modeSelector` | `() => Promise<{mode, confidence, rationale?}>` | wraps `selectMode(await buildLiveSignals())` |
 | `sessionRunner` | `({mode, autopilotRunId}) => Promise<{session_id, agent_summary?, effectiveness?}>` | wraps a `/session <mode>` invocation; reads `sessions.jsonl` tail to construct return value |
-| `resourceEvaluator` | `() => {verdict}` | wraps `evaluate(await probe(), thresholds)` from `resource-probe.mjs` |
-| `peerCounter` | `() => number` | reads `claude_processes_count` from a fresh `probe()` snapshot |
+| `resourceEvaluator` | `() => {verdict}` | calls `evaluate(cachedProbeSnapshot, thresholds)` from `resource-probe.mjs` over a snapshot `peerCounter` refreshed on the prior iteration — never calls `probe()` itself, which is what keeps it synchronous |
+| `peerCounter` | `() => Promise<number>` | returns `peers.length` from `detectPeers({ sessionId, freshnessMin: 15 })` (a SESSION count, not a process count — see `host-resources.md` HR-103) while refreshing the cached `probe()` snapshot `resourceEvaluator` reads |
 
 `abortSignal` is optional (Ctrl+C / Esc → `user-abort` kill-switch).
 
@@ -256,6 +292,25 @@ The in-process driver has Claude (the coordinator) call `/session <mode>` betwee
 - **Con:** not truly autonomous — Claude must stay in the chat. Doesn't deliver
   walk-away UX. That's Phase C-5's job.
 
+### Headless Driver Wiring (Option A — `scripts/autopilot.mjs`)
+
+The standalone headless driver invoked via `--headless` (see § Invocation) wires all
+four required `runLoop` dependencies (`modeSelector`, `sessionRunner`,
+`resourceEvaluator`, `peerCounter`) plus the optional `abortSignal` to production
+sources — distinct from, and more concrete than, the in-process skeleton above:
+
+- `sessionRunner` — spawns `claude -p '/session <mode>'` as a child process; after it
+  exits cleanly, reads the `sessions.jsonl` tail to construct the return shape
+  `{session_id, agent_summary?, effectiveness?}` (`scripts/autopilot.mjs` `sessionRunner`).
+- `resourceEvaluator` — calls `evaluate(cachedProbeSnapshot, thresholds)` from
+  `scripts/lib/resource-probe.mjs`, reading a snapshot refreshed by `peerCounter` on the
+  prior iteration so the function itself stays synchronous, per the `runLoop` contract
+  (`scripts/autopilot.mjs` `resourceEvaluator`).
+- `peerCounter` — calls `detectPeers({ sessionId: autopilotRunId, freshnessMin: 15 })` from
+  `scripts/lib/session-registry.mjs` AND refreshes the cached `probe()` snapshot in the
+  same call, returning `peers.length` (`scripts/autopilot.mjs` `makePeerCounter`).
+- `abortSignal` — an `AbortController` aborted on the process's `SIGINT` handler.
+
 ### `autopilot_run_id` Propagation
 
 When `runLoop` invokes `sessionRunner({mode, autopilotRunId})`, the per-iteration
@@ -387,7 +442,6 @@ Single-story `/autopilot` takes no Session Config block. Multi-story
 - PRD: "Autopilot Loop" (#277; archived in the private Meta-Vault)
 - Implementation (Phase C-1 + C-1.b): `scripts/lib/autopilot.mjs` — exports `runLoop`, `parseFlags`, `writeAutopilotJsonl`, `KILL_SWITCHES`, `FLAG_BOUNDS`, `SCHEMA_VERSION`, `DEFAULT_PEER_ABORT_THRESHOLD`, `DEFAULT_JSONL_PATH`, `DEFAULT_CARRYOVER_THRESHOLD`
 - Tests (Phase C-1 + C-1.b): `tests/lib/autopilot.test.mjs`
-- Command file: `commands/autopilot.md`
 - Mode-Selector contract: `skills/mode-selector/SKILL.md`
 - Resource probe: `scripts/lib/resource-probe.mjs`
 - Session registry: `scripts/lib/session-registry.mjs`