session-orchestrator 5.11.0 → 5.13.0

package/scripts/session-commit-files.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * session-commit-files.mjs — which files did one session commit, in which of
+ * its own work trees (#1659).
+ *
+ * Read-only CLI over scripts/lib/session-work-trees.mjs: the session's
+ * `(tree, start_ref)` pairs come from the `orchestrator.session.work_tree`
+ * events in the default events ledger, and every tree is diffed INSIDE ITSELF
+ * against its own start ref (`git -C <tree> diff --name-only <ref>..HEAD`).
+ * Never a diff across two trees, never a write.
+ *
+ * Usage:
+ *   node scripts/session-commit-files.mjs [--session-id <raw-id>] [--json]
+ *
+ * Exit codes: 0 success (also with zero trees), 2 usage error (unknown flag,
+ * missing session id). Deviates from cli-design.md's `1` for input errors by
+ * coordinator contract (#1659); documented in `--help`.
+ */
+
+import { parseArgs } from 'node:util';
+
+import { isMainModule } from './lib/is-main-module.mjs';
+import { readSessionWorkTrees, sessionCommitFiles } from './lib/session-work-trees.mjs';
+
+const USAGE = `Usage: node scripts/session-commit-files.mjs [--session-id <raw-id>] [--json]
+
+List the files one session committed, per own work tree (#1659).
+
+Reads the session's (tree, start_ref) pairs from the
+orchestrator.session.work_tree events of the default events ledger and runs
+'git -C <tree> diff --name-only <start_ref>..HEAD' inside each tree only.
+Read-only: writes nothing.
+
+Options:
+  --session-id <id>  raw session id (default: $CLAUDE_CODE_SESSION_ID)
+  --json             print { trees, perTree, skipped, union, malformed, invalid,
+                     complete[, error] } as JSON (complete: null = no ledger found)
+  -h, --help         show this help
+
+Default output (stdout): one line per tree '<tree>\\t<start_ref>\\t<n> files',
+a blank line, then the union of files, one per line. Skipped trees and notes
+go to stderr.
+
+Exit codes:
+  0  success (also when the session recorded no trees)
+  2  usage error (unknown option, no session id)
+
+Example:
+  node scripts/session-commit-files.mjs --session-id "$CLAUDE_CODE_SESSION_ID" --json`;
+
+/**
+ * Run the CLI.
+ *
+ * @param {string[]} argv — arguments after the script path.
+ * @param {{ env?: NodeJS.ProcessEnv,
+ *           stdout?: (s: string) => void, stderr?: (s: string) => void }} [io]
+ * @returns {number} exit code
+ */
+export function main(argv, {
+  env = process.env,
+  stdout = (s) => process.stdout.write(s),
+  stderr = (s) => process.stderr.write(s),
+} = {}) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: {
+        'session-id': { type: 'string' },
+        json: { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (err) {
+    stderr(`session-commit-files: ${err.message}\n${USAGE}\n`);
+    return 2;
+  }
+  if (values.help) {
+    stdout(`${USAGE}\n`);
+    return 0;
+  }
+
+  // Process-local identity only — never a repo-global file (#1659).
+  const sessionId = (values['session-id'] ?? env.CLAUDE_CODE_SESSION_ID ?? '').trim();
+  if (sessionId === '') {
+    stderr('session-commit-files: no session id (pass --session-id or set CLAUDE_CODE_SESSION_ID)\n');
+    return 2;
+  }
+
+  const read = readSessionWorkTrees({ sessionId });
+  const files = sessionCommitFiles({ trees: read.trees });
+
+  // Notes go to stderr in BOTH modes, so `--json` never hides that the
+  // answer is partial or that no ledger exists (#1659).
+  if (read.error) stderr(`session-commit-files: ledger read failed: ${read.error}\n`);
+  if (read.complete === null && !read.error) stderr('session-commit-files: no events ledger found\n');
+  if (read.malformed > 0) stderr(`session-commit-files: ${read.malformed} unreadable ledger line(s)\n`);
+  if (read.invalid > 0) {
+    stderr(`session-commit-files: ignored ${read.invalid} own work_tree event(s) without a valid tree/start_ref\n`);
+  }
+  for (const s of files.skipped) {
+    stderr(`session-commit-files: skipped ${s.tree} (${s.start_ref}): ${s.reason}\n`);
+  }
+
+  if (values.json) {
+    stdout(`${JSON.stringify({
+      trees: read.trees,
+      perTree: files.perTree,
+      skipped: files.skipped,
+      union: files.union,
+      malformed: read.malformed,
+      invalid: read.invalid,
+      complete: read.complete,
+      ...(read.error ? { error: read.error } : {}),
+    }, null, 2)}\n`);
+    return 0;
+  }
+
+  if (read.trees.length === 0) {
+    if (read.complete !== null) stderr(`session-commit-files: no work trees recorded for session ${sessionId}\n`);
+    return 0;
+  }
+  if (files.perTree.length === 0) return 0; // every tree skipped — reported on stderr above
+  const lines = files.perTree.map((t) => `${t.tree}\t${t.start_ref}\t${t.files.length} files`);
+  stdout(`${lines.join('\n')}\n\n${files.union.map((f) => `${f}\n`).join('')}`);
+  return 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/scripts/site-numbers.mjs

@@ -110,9 +110,10 @@ import { join, resolve, relative, sep } from 'node:path';
 import { execFileSync } from 'node:child_process';
 
 import { writeStdoutLineSync, writeJsonAtomicSync } from './lib/io.mjs';
-import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
+import { isMeasuredSession, readCanonicalSessions } from './lib/sessions-canonical.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 import { slashCommandNames } from './lib/user-invocable-skills.mjs';
+import { resolveEventsLedgerRoot } from './lib/platform.mjs';
 
 /** Machine-readable schema tag for the --json envelope. */
 export const SCHEMA = 'site-numbers/1';
@@ -393,6 +394,30 @@ export function isDirty(root) {
   }
 }
 
+/** Metrics counted from a gitignored ledger — the ones `--write` must never republish from the snapshot. */
+const LEDGER_METRICS = Object.freeze(['sessions', 'learnings']);
+
+/**
+ * Path of a gitignored metrics ledger. A linked worktree carries none of its own,
+ * so it reads its main checkout's copy (#1555) — the same mapping
+ * `scripts/resolve-session-invocation.mjs` applies to sessions.jsonl. Returns the
+ * root's own path when neither exists, so an absent ledger still reads as `null`
+ * downstream and the snapshot fallback stays reachable for a fresh clone.
+ *
+ * @param {string} root
+ * @param {string} name  e.g. `sessions.jsonl`
+ * @returns {string}
+ */
+function ledgerFile(root, name) {
+  // ledger-root: this tree's own copy first, on purpose; the shared one is the fallback below
+  const own = join(root, '.orchestrator', 'metrics', name);
+  if (existsSync(own)) return own;
+  const main = resolveEventsLedgerRoot(root);
+  // ledger-root: the shared copy in the main checkout, read on purpose beside the own one
+  const shared = join(main, '.orchestrator', 'metrics', name);
+  return main !== resolve(root) && existsSync(shared) ? shared : own;
+}
+
 // ---------------------------------------------------------------------------
 // The metric table — the part that must never be re-derived by hand
 // ---------------------------------------------------------------------------
@@ -472,9 +497,9 @@ export const METRIC_DEFS = Object.freeze([
     // Measured on THIS repo's own ledger @ 2ccea0f2: raw line count 289 vs
     // canonical (deduped) count 278 — an over-count of 11 records, which is the
     // bug's magnitude this migration removes.
-    source: 'grep -c . .orchestrator/metrics/sessions.jsonl   (then deduped per session_id — see readCanonicalSessions, #1186)',
+    source: 'grep -c . .orchestrator/metrics/sessions.jsonl   (then deduped per session_id — see readCanonicalSessions, #1186; synthetic backfill stubs excluded — isMeasuredSession, audit E1)',
     compute: (root) => {
-      const file = join(root, '.orchestrator', 'metrics', 'sessions.jsonl');
+      const file = ledgerFile(root, 'sessions.jsonl');
       // Same absent/non-file guard as countJsonlEntries, kept explicit here
       // because readCanonicalSessions returns [] (not null) on a missing ledger
       // — collapsing that into fmtCount(0) would silently defeat the
@@ -487,7 +512,9 @@ export const METRIC_DEFS = Object.freeze([
       // identified for dedup. Measured @ 2ccea0f2 on this repo's own ledger:
       // 0 such rows (raw 289 lines == 289 identified), so the drop is inert
       // here; it only matters for a future malformed/legacy row.
-      return fmtCount(readCanonicalSessions({ filePath: file }).length);
+      // Audit E1: count MEASURED sessions only — synthetic backfill stubs are
+      // records of a start, not sessions (`isMeasuredSession`).
+      return fmtCount(readCanonicalSessions({ filePath: file }).filter(isMeasuredSession).length);
     },
   },
   {
@@ -497,7 +524,7 @@ export const METRIC_DEFS = Object.freeze([
     snapshotFallback: true,
     source: 'grep -c . .orchestrator/metrics/learnings.jsonl',
     compute: (root) => {
-      const r = countJsonlEntries(join(root, '.orchestrator', 'metrics', 'learnings.jsonl'));
+      const r = countJsonlEntries(ledgerFile(root, 'learnings.jsonl'));
       return r === null ? null : fmtCount(r.entries);
     },
   },
@@ -743,7 +770,7 @@ export function collect(root, ctx = {}) {
     ['sessions', 'sessions.jsonl'],
     ['learnings', 'learnings.jsonl'],
   ]) {
-    const r = countJsonlEntries(join(root, '.orchestrator', 'metrics', file));
+    const r = countJsonlEntries(ledgerFile(root, file));
     if (r && r.malformed > 0) {
       // #1186: the two ledgers now disagree on what a malformed line DOES to
       // the published count. `learnings` is still the raw countJsonlEntries
@@ -759,7 +786,7 @@ export function collect(root, ctx = {}) {
     }
   }
 
-  return { values, missing, warnings, fromSnapshot };
+  return { values, missing, warnings, fromSnapshot, localFallbacks };
 }
 
 // ---------------------------------------------------------------------------
@@ -1307,7 +1334,7 @@ export function main(argv = process.argv.slice(2), env = {}) {
     return 2;
   }
 
-  const { values, missing, warnings, fromSnapshot } = collect(root, { usage: env.usage });
+  const { values, missing, warnings, fromSnapshot, localFallbacks } = collect(root, { usage: env.usage });
   if (missing.length > 0) {
     stderr(
       `Error: could not measure ${missing.join(', ')} under ${root} — ` +
@@ -1315,6 +1342,22 @@ export function main(argv = process.argv.slice(2), env = {}) {
     );
     return 2;
   }
+  // #1555: a --write of the SERVED site publishes what it measured. A ledger
+  // metric answered by the snapshot is the previous release's number, not a
+  // measurement (5.11.0 and 5.12.0 both republished 475 sessions / 220
+  // learnings from a release worktree), so it is refused. Only the real site/
+  // is guarded; a --write --site <fixture> run publishes nothing. counted-sha
+  // keeps its snapshot answer — the tested no-.git contract below.
+  const writesServedSite = args.write && resolve(siteDir) === resolve(join(root, 'site'));
+  const staleLedgers = localFallbacks.filter((id) => LEDGER_METRICS.includes(id));
+  if (writesServedSite && staleLedgers.length > 0) {
+    stderr(
+      `Error: ${staleLedgers.join(', ')} not measurable under ${root} — the gitignored ledgers are absent ` +
+        `here and in the main checkout; refusing to republish the old ${CENSUS_FILE.join('/')} values. ` +
+        'Run --write from a checkout that has them.',
+    );
+    return 2;
+  }
   for (const w of warnings) stderr(`WARN: ${w}`);
 
   const dirty = isDirty(root);
@@ -1489,7 +1532,7 @@ export function main(argv = process.argv.slice(2), env = {}) {
   // release preflight's clean-tree check. A fixture run is a read of the repo,
   // never a write to it.
   let censusWritten = false;
-  const writesCensus = args.write && resolve(siteDir) === resolve(join(root, 'site'));
+  const writesCensus = writesServedSite;
   if (writesCensus && ok) {
     const res = writeCensusSnapshot(root, values);
     if (res.ok) {

package/scripts/snapshot-probe.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * snapshot-probe.mjs — run validate-plugin and the test suite on the curated public
+ * snapshot tree, materialized outside the repo without a remote (#1712).
+ * Library: scripts/lib/snapshot-probe.mjs.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+
+import { isMainModule } from './lib/is-main-module.mjs';
+import { KNOWN_STEPS, SnapshotProbeSystemError, runSnapshotProbe } from './lib/snapshot-probe.mjs';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+export const HELP = `Usage: node scripts/snapshot-probe.mjs [options]
+
+Builds the curated public GitHub snapshot of a source commit (the tree minus the paths in
+.orchestrator/policy/public-export.json — the same helper the export uses), materializes it
+under $TMPDIR as a one-commit git repo WITHOUT any remote, and runs the steps there. Catches
+tests and validators that depend on a file the public export drops.
+
+Options:
+  --source <rev>     source commit (default HEAD)
+  --steps <list>     comma-separated steps, from: ${KNOWN_STEPS.join(', ')} (default: both)
+  --host <alias>     run the 'test' step on an offload host instead: one 'remote-gate' step
+                     (the pre-push router's full gate against the snapshot commit, no gate
+                     telemetry); validate-plugin still runs locally
+  --local            run the 'test' step (full suite) on this host instead
+                     The 'test' step needs exactly one of --host or --local.
+  --keep             keep the materialized snapshot directory (printed as dir)
+  --no-receipt       do not write .orchestrator/tmp/snapshot-probe/<tree>.json
+  --json             print one JSON object instead of the human summary (remote gate
+                     output goes to stderr)
+  --version          print the plugin version
+  -h, --help         show this help
+
+Exit codes:
+  0  every step passed
+  1  usage error
+  2  system error: git, tar or mkdtemp failure, or the remote gate did not run the suite
+     to completion (host unknown or not ready, fallback, gate-timeout, a timed-out check,
+     no test result) — no receipt is written
+  3  the probe ran and the snapshot is red (a step failed or timed out)
+
+A receipt is written only when a suite step ran ('test' or 'remote-gate'); a
+--steps validate-plugin run prints its result and leaves any existing receipt untouched.
+The release preflight accepts only receipts whose steps include a passing suite step:
+'test' (--local) or 'remote-gate' (--host).
+
+Examples:
+  node scripts/snapshot-probe.mjs --steps validate-plugin
+  node scripts/snapshot-probe.mjs --host m5 --json
+  node scripts/snapshot-probe.mjs --local --json
+`;
+
+/**
+ * Parse argv into probe options.
+ * @param {string[]} argv
+ * @returns {{ ok: true, opts: object } | { ok: false, error: string } | { ok: true, help: true } | { ok: true, version: true }}
+ */
+export function parseCli(argv) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      strict: true,
+      allowPositionals: false,
+      options: {
+        source: { type: 'string', default: 'HEAD' },
+        steps: { type: 'string' },
+        local: { type: 'boolean', default: false },
+        host: { type: 'string' },
+        keep: { type: 'boolean', default: false },
+        'no-receipt': { type: 'boolean', default: false },
+        json: { type: 'boolean', default: false },
+        version: { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+    }));
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+  if (values.help) return { ok: true, help: true };
+  if (values.version) return { ok: true, version: true };
+  const steps = values.steps === undefined ? [...KNOWN_STEPS] : values.steps.split(',').map((s) => s.trim()).filter(Boolean);
+  if (steps.length === 0) return { ok: false, error: '--steps is empty' };
+  const unknown = steps.filter((s) => !KNOWN_STEPS.includes(s));
+  if (unknown.length > 0) return { ok: false, error: `unknown step(s): ${unknown.join(', ')} (known: ${KNOWN_STEPS.join(', ')})` };
+  if (values.local && values.host !== undefined) return { ok: false, error: '--host and --local are mutually exclusive' };
+  if (values.host !== undefined && !/^[A-Za-z0-9._-]+$/.test(values.host)) return { ok: false, error: `invalid --host alias '${values.host}'` };
+  // Host rule: full suites belong on a remote host; the local host only with --local.
+  if (steps.includes('test') && !values.local && values.host === undefined) {
+    return { ok: false, error: "the 'test' step runs the full suite — pass --host <alias> or --local, or use --steps validate-plugin" };
+  }
+  return {
+    ok: true,
+    opts: { source: values.source, steps, keep: values.keep, writeReceipt: !values['no-receipt'], json: values.json, ...(values.host !== undefined ? { host: values.host } : {}) },
+  };
+}
+
+function humanSummary(r) {
+  const lines = [
+    `snapshot probe ${r.ok ? 'GREEN' : 'RED'} — source ${r.sourceSha.slice(0, 12)}, tree ${r.snapshotTree.slice(0, 12)} (route ${r.route})`,
+    `files: ${r.counts.source} source, ${r.counts.excluded} excluded, ${r.counts.exported} exported`,
+  ];
+  for (const s of r.steps) {
+    lines.push(`  ${s.name}: ${s.status} (exit ${s.exitCode}, ${Math.round(s.durationMs / 1000)}s)`);
+    if (s.reason) lines.push(`    ${s.reason}`);
+    if (s.failedFiles) for (const f of s.failedFiles) lines.push(`    FAIL ${f}`);
+    if (s.tail) lines.push(...s.tail.split('\n').map((l) => `    | ${l}`));
+  }
+  if (r.dir) lines.push(`kept: ${r.dir}`);
+  return lines.join('\n');
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ repoRoot?: string, probe?: typeof runSnapshotProbe }} [deps]
+ * @returns {Promise<number>} exit code
+ */
+export async function main(argv, { repoRoot = REPO_ROOT, probe = runSnapshotProbe } = {}) {
+  const parsed = parseCli(argv);
+  if (!parsed.ok) {
+    process.stderr.write(`snapshot-probe: ${parsed.error}\n\n${HELP}`);
+    return 1;
+  }
+  if (parsed.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (parsed.version) {
+    process.stdout.write(`${JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8')).version}\n`);
+    return 0;
+  }
+  const { json, ...opts } = parsed.opts;
+  let result;
+  try {
+    result = await probe({ repoRoot, ...opts });
+  } catch (err) {
+    const message = err instanceof SnapshotProbeSystemError ? err.message : `unexpected failure: ${err?.message ?? err}`;
+    if (json) process.stdout.write(`${JSON.stringify({ ok: false, error: message })}\n`);
+    process.stderr.write(`snapshot-probe: ${message}\n`);
+    return 2;
+  }
+  process.stdout.write(json ? `${JSON.stringify(result)}\n` : `${humanSummary(result)}\n`);
+  return result.ok ? 0 : 3;
+}
+
+if (isMainModule(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+  });
+}

package/scripts/so-hud.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFile } from 'node:child_process';
+import { promisify, parseArgs } from 'node:util';
+import { measure } from './lib/so-hud/runtime.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+import { parseSessionId } from './lib/session-id.mjs';
+const exec = promisify(execFile);
+const SO_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+export async function main(argv, deps = {}) {
+  const output = deps.output ?? (s => process.stdout.write(s));
+  const error = deps.error ?? (s => process.stderr.write(s));
+  let values;
+  try {
+    ({ values } = parseArgs({ args: argv, options: { json: { type: 'boolean' }, 'repo-root': { type: 'string' }, 'session-id': { type: 'string' }, 'register-root': { type: 'boolean' }, help: { type: 'boolean' } }, allowPositionals: false }));
+    if (values.help) {
+      output('so-hud --json [--repo-root <path>] [--session-id <raw-uuid>] [--register-root]\nRead-only HUD JSON v1. --register-root registers this SO installation (0600).\nDefault repo: git toplevel of cwd. --session-id: the session whose agents are counted, read beside its own session.lock (#1730); without it the id comes from CLAUDE_SESSION_ID/SO_SESSION_ID and agents are read in the repo.\nExit 0: measured; 2: invocation/registration error; 6: repository unavailable.\n');
+      return 0;
+    }
+    if (!values.json && !values['register-root']) throw new Error('--json required');
+    if (values['session-id'] !== undefined && parseSessionId(values['session-id'])?.format !== 'uuid') throw new Error('bad --session-id');
+  } catch (e) {
+    error(e?.message === 'bad --session-id' ? 'so-hud: --session-id braucht eine Roh-UUID; siehe --help\n' : 'so-hud: --json erforderlich; siehe --help\n');
+    return 2;
+  }
+  if (values['register-root']) {
+    try {
+      const dir = path.join(deps.home ?? os.homedir(), '.config/session-orchestrator/hud');
+      await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+      await fs.chmod(dir, 0o700);
+      const target = path.join(dir, 'so-root');
+      const temp = `${target}.${process.pid}.tmp`;
+      try { await fs.writeFile(temp, `${SO_ROOT}\n`, { mode: 0o600, flag: 'wx' }); await fs.rename(temp, target); }
+      finally { await fs.unlink(temp).catch(() => {}); }
+    } catch { error('so-hud: Registrierung fehlgeschlagen\n'); return 2; }
+    if (!values.json) return 0;
+  }
+  let root;
+  try {
+    // A session started in a subdirectory measures its working copy: the git toplevel. Not a repo → the given
+    // directory itself (never fail the measurement).
+    const given = values['repo-root'] ? path.resolve(values['repo-root']) : null;
+    const top = await (deps.exec ?? exec)('git', [...(given ? ['-C', given] : []), 'rev-parse', '--show-toplevel'], { timeout: 700 })
+      .then(r => r.stdout.trim(), () => '');
+    if (!top && !given) throw new Error('missing');
+    root = await fs.realpath(top || given);
+    // git answers in physical spelling, but the session writes file paths in the spelling it was given, and the
+    // collision guard compares those as strings: keep the caller's spelling of the toplevel where it is derivable.
+    // Peers are compared physically in collect.mjs. The caller's spelling is used only when it resolves to the
+    // physical toplevel: a symlinked last path part (<d>/elsewhere/scripts → <d>/repo/scripts) would otherwise
+    // map to <d>/elsewhere, which is not the repository.
+    if (given) {
+      const sub = path.relative(root, await fs.realpath(given));
+      let candidate = null;
+      if (sub === '') candidate = given;
+      else if (sub !== '..' && !sub.startsWith(`..${path.sep}`) && given.endsWith(`${path.sep}${sub}`)) candidate = given.slice(0, -sub.length - 1);
+      if (candidate !== null && await fs.realpath(candidate).catch(() => null) === root) root = candidate;
+    }
+    if (!(await fs.stat(root)).isDirectory()) throw new Error('missing');
+  } catch { error('so-hud: Repo nicht ermittelbar\n'); return 6; }
+  try { output(`${JSON.stringify(await (deps.measure ?? measure)(root, { sessionId: values['session-id'] ?? null }))}\n`); return 0; }
+  catch { error('so-hud: Messung fehlgeschlagen\n'); return 6; }
+}
+if (isMainModule(import.meta.url)) process.exitCode = await main(process.argv.slice(2));

package/scripts/state-md-idle-reset.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/** session-start Phase 1.5 Idle Reset (#1560): rewrite a completed STATE.md to idle, under the STATE.md lock. */
+import { readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { resetStateMdToIdleOnDisk } from './lib/state-md/idle-reset.mjs';
+
+const HELP = `Usage: node scripts/state-md-idle-reset.mjs [--repo-root <dir>] [--json]
+
+Reset the repo's STATE.md to idle when its status is completed (session-start
+Phase 1.5, Idle Reset rules 1-7): status idle, current-wave 0, Wave History
+demoted into Previous Session, Deviations emptied, scope-baseline-* keys
+deleted. The five recommendation keys stay in the frontmatter so the Phase 7.5
+Mode-Selector can read them. Any other status is a no-op; reasons:
+status-not-completed, unparseable, missing (no or empty STATE.md),
+foreign-state-md (only another platform's foreign STATE.md exists, #1618).
+
+  --repo-root <dir>  Repository root holding the state dir (default: cwd)
+  --json             Emit {"changed", "reason", "path"} instead of one line
+  --help             Show this help
+  --version          Show the plugin version
+
+Example: node scripts/state-md-idle-reset.mjs --json
+Exit codes: 0 reset or no-op, 1 bad CLI arguments,
+            2 I/O error, --repo-root not a directory, or a write the
+              STATE.md guards refused
+`;
+
+/** Reasons under which writeStateMd refused a wanted write. */
+const REFUSED = new Set(['size-ceiling', 'frontmatter-unsafe']);
+
+let options;
+try {
+  options = parseArgs({
+    options: {
+      'repo-root': { type: 'string' },
+      json: { type: 'boolean' },
+      help: { type: 'boolean' },
+      version: { type: 'boolean' },
+    },
+    allowPositionals: false,
+  }).values;
+} catch (error) {
+  process.stderr.write(`state-md-idle-reset: ${error.message}\n`);
+  process.exit(1);
+}
+
+if (options.help) {
+  process.stdout.write(HELP);
+} else if (options.version) {
+  process.stdout.write(
+    `${JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version}\n`,
+  );
+} else {
+  const repoRoot = resolve(options['repo-root'] ?? process.cwd());
+  // The STATE.md lock would otherwise create <repoRoot>/.orchestrator/ for a
+  // root that does not exist and report a harmless-looking `missing`.
+  let rootStat;
+  try {
+    rootStat = statSync(repoRoot, { throwIfNoEntry: false });
+  } catch {
+    rootStat = undefined; // EACCES / ELOOP: an I/O error, exit 2 below
+  }
+  if (!rootStat?.isDirectory()) {
+    process.stderr.write(`state-md-idle-reset: --repo-root is not a directory: ${repoRoot}\n`);
+    process.exit(2);
+  }
+  let result;
+  try {
+    result = await resetStateMdToIdleOnDisk(repoRoot);
+  } catch (error) {
+    process.stderr.write(`state-md-idle-reset: ${error.message}\n`);
+    process.exit(2);
+  }
+  const reason = result.reason ?? null;
+  process.stdout.write(
+    options.json
+      ? `${JSON.stringify({ changed: result.changed, reason, path: result.path })}\n`
+      : `${result.changed ? 'reset to idle' : `unchanged (${reason})`}: ${result.path}\n`,
+  );
+  if (REFUSED.has(reason)) process.exit(2);
+}