session-orchestrator 5.11.0 → 5.12.0

package/scripts/lib/vault-mirror/utils.mjs

@@ -10,32 +10,43 @@
 import { parseSessionId } from '../session-id.mjs';
 import { digestSha256Short } from '../crypto-digest-utils.mjs';
 
+/** Normalize letters for new note slugs. */
+function normalizeSlugLetters(value) {
+  const german = { ä: 'ae', ö: 'oe', ü: 'ue', ß: 'ss' };
+  return value.normalize('NFC').toLowerCase()
+    .replace(/[äöüß]/g, (letter) => german[letter])
+    .normalize('NFKD').replace(/\p{M}/gu, '');
+}
+
+/** Historical ASCII deletion, frozen for record identity and old note lookup. */
+export function legacySubjectToSlug(subject) {
+  return slugSubject(subject, (value) => value.toLowerCase());
+}
+
 /**
  * Convert a subject string to a kebab slug.
  * - If subject contains slashes, collapse to last path segment.
+ * - Transliterate German letters and decompose accents.
  * - Replace dots and underscores with hyphens.
  * - Strip all non-[a-z0-9-] chars.
  * - Collapse consecutive hyphens.
  * - Trim leading/trailing hyphens.
  */
 export function subjectToSlug(subject) {
-  let s = subject;
+  return slugSubject(subject, normalizeSlugLetters);
+}
 
-  // Collapse slash paths to last segment
+function slugSubject(subject, normalize) {
+  let s = subject;
   if (s.includes('/')) {
     const parts = s.split('/').filter(Boolean);
     s = parts[parts.length - 1];
   }
-
-  // Normalise: lowercase, dots/underscores → hyphens, strip invalid chars
-  s = s
-    .toLowerCase()
+  return normalize(s)
     .replace(/[._]/g, '-')
     .replace(/[^a-z0-9-]/g, '')
     .replace(/-+/g, '-')
     .replace(/^-+|-+$/g, '');
-
-  return s;
 }
 
 const slugRegex = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -80,8 +91,8 @@ export const TAG_MAX_LENGTH = 64;
  * @returns {string}
  */
 export function slugifyTagSegment(input) {
-  const slug = String(input ?? '')
-    .toLowerCase()
+  // Tags are persistent identifiers, so retain historical ASCII deletion.
+  const slug = String(input ?? '').toLowerCase()
     .replace(/[\s._]+/g, '-')
     .replace(/[^a-z0-9-]/g, '')
     .replace(/-+/g, '-')
@@ -123,9 +134,11 @@ export function buildTag(segments) {
  */
 export function slugifyIdSafe(input) {
   // Normalise whitespace to hyphens first (so "My ID" → "my-id" rather than
-  // "myid"), then delegate to subjectToSlug for the rest of the kebab contract.
+  // "myid"), then preserve the historical ASCII kebab contract.
   const normalised = String(input ?? '').replace(/\s+/g, '-');
-  const slug = subjectToSlug(normalised);
+  // Session identity retains historical deletion; transliteration is for new
+  // learning names, never an incidental Session-ID migration.
+  const slug = legacySubjectToSlug(normalised);
   if (!slug) return null;
   // Schema requires min length 2; pad a single-char slug deterministically.
   return slug.length >= 2 ? slug : `${slug}-x`;
@@ -198,7 +211,8 @@ export function resolveSourceSessionLink(source_session, opts = {}) {
   if (!raw || raw === 'unknown') return { isLink: false, target: raw || 'unknown' };
   // Provenance tags like "agent-proposed@wave-1" are never session notes.
   if (/@/.test(raw)) return { isLink: false, target: raw };
-  const slug = subjectToSlug(raw) || raw;
+  // Session targets retain the same historical identity as their note filenames.
+  const slug = legacySubjectToSlug(raw) || raw;
   if (typeof opts.noteExists === 'function') {
     // EXISTENCE-based (authoritative when a predicate is supplied).
     return opts.noteExists(slug) ? { isLink: true, target: slug } : { isLink: false, target: raw };

package/scripts/lib/vault-status/board-writer.mjs

@@ -48,7 +48,7 @@
  * canonical-vault refusal (#1450). Plain Node ESM. No external deps.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
@@ -56,6 +56,7 @@ import { emitEvent, sessionAttribution } from '../events.mjs';
 import { isLockLive, readLock, DEFAULT_TTL_HOURS } from '../session-lock.mjs';
 import { stableHostname } from '../host-identity.mjs';
 import { readRegistry, repoPathHash, isRegistryEntryFresh } from '../session-registry.mjs';
+import { digestSha256 } from '../crypto-digest-utils.mjs';
 import { parseFrontmatter } from '../vault-mirror/utils.mjs';
 import { readConfigFile, parseSessionConfig } from '../config.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
@@ -134,10 +135,29 @@ const CASE_INSENSITIVE_FS = process.platform === 'darwin' || process.platform ==
  * @returns {string|null} `KEY_LENGTH`-char hex prefix, or null for an unusable path.
  */
 export function boardKey(repoRoot) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) return null;
+  try {
+    let resolved = path.resolve(repoRoot);
+    try { resolved = realpathSync.native(resolved); } catch { /* Keep unavailable paths' legacy identity. */ }
+    // Fold AFTER realpath, then hash directly: repoPathHash would restore
+    // on-disk casing and change existing case-folded board keys on macOS.
+    return digestSha256(CASE_INSENSITIVE_FS ? resolved.toLowerCase() : resolved).slice(0, KEY_LENGTH);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pre-#1557 lexical board key, used to migrate rows when alias paths now
+ * resolve to a canonical key. BV-004 revisit/deletion trigger: remove once a
+ * host-wide board audit confirms no rows written before the #1557 canonical-key
+ * rollout remain for 30 consecutive days; age alone does not prove migration.
+ */
+function legacyBoardKey(repoRoot) {
   if (typeof repoRoot !== 'string' || repoRoot.length === 0) return null;
   try {
     const resolved = path.resolve(repoRoot);
-    return repoPathHash(CASE_INSENSITIVE_FS ? resolved.toLowerCase() : resolved).slice(0, KEY_LENGTH);
+    return digestSha256(CASE_INSENSITIVE_FS ? resolved.toLowerCase() : resolved).slice(0, KEY_LENGTH);
   } catch {
     return null;
   }
@@ -435,6 +455,7 @@ export async function collectRows({ repos, now = new Date(), registry, priorStat
     rows.push({
       repo: repoName,
       key,
+      legacyKey: legacyBoardKey(repo.repoRoot), // Internal migration identity; never rendered.
       status,
       session: status === STATUS_FREI ? null : session,
       branch: status === STATUS_FREI ? null : branch,
@@ -1098,8 +1119,8 @@ async function mirrorBoardInner({ repoRoot, repos, explicitStatus, now = new Dat
     // skips `frei` candidates and the TTL pass only rewrites `status`, never
     // removes a row), and the board would grow a permanent duplicate per repo.
     // So a fresh row first claims its hash slot; if that slot is new, it ADOPTS
-    // the legacy name slot for the same folded name — one board write converts
-    // the row, and the migration is complete for that repo.
+    // the legacy name slot for the same folded name and the pre-#1557 lexical
+    // key slot — one board write converts the row for that repo.
     const merged = new Map(staleRederivedRows);
     for (const row of rows) {
       const slot = row.key ? hashSlot(row.key) : nameSlot(row.repo);
@@ -1107,6 +1128,13 @@ async function mirrorBoardInner({ repoRoot, repos, explicitStatus, now = new Dat
         // First keyed write for this repo — take over its legacy row rather than
         // rendering a second one beside it.
         merged.delete(nameSlot(row.repo));
+        if (row.legacyKey && row.legacyKey !== row.key) {
+          // An 8-char key can collide: adopt the legacy-key row only when it
+          // names this repo, never another repo's row that shares the prefix.
+          const legacySlot = hashSlot(row.legacyKey);
+          const legacyRow = merged.get(legacySlot);
+          if (legacyRow && foldKey(legacyRow.repo) === foldKey(row.repo)) merged.delete(legacySlot);
+        }
       }
       merged.set(slot, row);
     }

package/scripts/resolve-session-invocation.mjs

@@ -1,19 +1,67 @@
 #!/usr/bin/env node
 /** Stdin-only boundary for commands/session.md; never executes task context. */
-import { readFileSync } from 'node:fs';
+import { accessSync, constants, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { resolveSessionInvocation } from './lib/session-invocation.mjs';
+import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
+import { isRealSession } from './lib/session-schema/filters.mjs';
+import { resolveEventsLedgerRoot } from './lib/platform.mjs';
 
-const HELP = `Usage: node scripts/resolve-session-invocation.mjs [--json] < arguments.txt
+/**
+ * One ledger: `false` when absent, `undefined` when present but not a readable
+ * file, else whether it holds a real session.
+ *
+ * @param {string} root
+ * @returns {boolean|undefined}
+ */
+function ledgerHasHistory(root) {
+  const file = join(root, '.orchestrator', 'metrics', 'sessions.jsonl');
+  try {
+    if (!statSync(file).isFile()) return undefined;
+    accessSync(file, constants.R_OK);
+  } catch (error) {
+    return error?.code === 'ENOENT' ? false : undefined;
+  }
+  return readCanonicalSessions({ filePath: file }).some(isRealSession);
+}
+
+/**
+ * Whether the repo holds a real session of its own: `true`/`false`, or
+ * `undefined` when that cannot be measured. sessions.jsonl is gitignored, so a
+ * linked worktree also reads its main checkout's ledger (`resolveEventsLedgerRoot`);
+ * one with history in either place has history. A ledger that exists but
+ * cannot be read is "not measured", never "no history".
+ *
+ * @param {string} repoRoot
+ * @returns {boolean|undefined}
+ */
+function measureHistory(repoRoot) {
+  const roots = [...new Set([resolve(repoRoot), resolveEventsLedgerRoot(repoRoot)])];
+  let unmeasured = false;
+  for (const root of roots) {
+    const has = ledgerHasHistory(root);
+    if (has === true) return true;
+    if (has === undefined) unmeasured = true;
+  }
+  return unmeasured ? undefined : false;
+}
+
+const HELP = `Usage: node scripts/resolve-session-invocation.mjs [--json] [--repo-root <dir>] < arguments.txt
 
 Read the complete /session argument text from UTF-8 stdin.
 Resolve the leading housekeeping, feature, deep or ultradeep token; preserve
 the rest as task context. Empty input defaults to deep. An invalid mode emits
 a warning and resolves to deep, as the session command has always specified.
+A bare /session in a repo whose .orchestrator/metrics/sessions.jsonl holds no
+real session adds defaultReason "no-session-history": ask for task and mode
+before starting. A linked git worktree reads its main checkout's ledger; an
+unreadable ledger counts as not measured and adds nothing.
 
-  --json     Emit one JSON object instead of a human-readable summary
-  --help     Show this help
-  --version  Show the plugin version
+  --json             Emit one JSON object instead of a human-readable summary
+  --repo-root <dir>  Project root whose session history is read (default: cwd)
+  --help             Show this help
+  --version          Show the plugin version
 
 Example: node scripts/resolve-session-invocation.mjs --json < arguments.txt
 Write arguments.txt with a file tool; do not interpolate user text into a shell.
@@ -23,7 +71,12 @@ Exit codes: 0 resolved (including fallback), 1 bad CLI arguments, 2 stdin I/O er
 let options;
 try {
   options = parseArgs({
-    options: { json: { type: 'boolean' }, help: { type: 'boolean' }, version: { type: 'boolean' } },
+    options: {
+      json: { type: 'boolean' },
+      'repo-root': { type: 'string' },
+      help: { type: 'boolean' },
+      version: { type: 'boolean' },
+    },
     allowPositionals: false,
   }).values;
 } catch (error) {
@@ -45,7 +98,10 @@ if (options.help) {
     process.stderr.write('session-invocation: could not read UTF-8 stdin\n');
     process.exit(2);
   }
-  const resolved = resolveSessionInvocation(input);
+  // History is read only for a bare /session: an explicit mode never needs it.
+  const hasHistory =
+    input.trim() === '' ? measureHistory(options['repo-root'] || process.cwd()) : undefined;
+  const resolved = resolveSessionInvocation(input, { hasHistory });
   if (resolved.invalidMode !== undefined) {
     process.stderr.write(
       `Invalid session type '${resolved.invalidMode}'. Valid types: housekeeping, feature, deep (alias: ultradeep). Falling back to deep.\n`,
@@ -54,6 +110,6 @@ if (options.help) {
   process.stdout.write(
     options.json
       ? `${JSON.stringify(resolved)}\n`
-      : `Session type: ${resolved.sessionType}${resolved.profile ? ` (profile: ${resolved.profile})` : ''}\nTask context: ${resolved.context}\n`,
+      : `Session type: ${resolved.sessionType}${resolved.profile ? ` (profile: ${resolved.profile})` : ''}${resolved.defaultReason ? ` (default: ${resolved.defaultReason})` : ''}\nTask context: ${resolved.context}\n`,
   );
 }

package/scripts/so-hud.mjs

@@ -0,0 +1,45 @@
+#!/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';
+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' }, 'register-root': { type: 'boolean' }, help: { type: 'boolean' } }, allowPositionals: false }));
+    if (values.help) {
+      output('so-hud --json [--repo-root <path>] [--register-root]\nRead-only HUD JSON v1. --register-root registers this SO installation (0600).\nDefault repo: git toplevel of cwd. Exit 0: measured; 2: invocation/registration error; 6: repository unavailable.\n');
+      return 0;
+    }
+    if (!values.json && !values['register-root']) throw new Error('--json required');
+  } catch { error('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 {
+    root = values['repo-root'] ? path.resolve(values['repo-root']) : (await (deps.exec ?? exec)('git', ['rev-parse', '--show-toplevel'], { timeout: 700 })).stdout.trim();
+    if (!root || !(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))}\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,81 @@
+#!/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).
+
+  --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);
+}

package/scripts/vault-orphans.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * vault-orphans.mjs - CLI for `findVaultOrphans` (#1563, session-end Phase 3.7e).
+ *
+ * Names the untracked files in the Meta-Vault modified since a given instant
+ * (the session's start). Read-only: it never commits, moves or deletes anything
+ * in the vault. See scripts/lib/session-end/vault-orphans.mjs for the design.
+ *
+ * USAGE
+ *   node scripts/vault-orphans.mjs --since <ISO> [--vault-dir <dir>] [--json]
+ *
+ * EXIT CODES
+ *   0  measured (including zero candidates)
+ *   1  bad arguments
+ *   2  could not measure (no vault dir resolvable, not a git repo, git failed)
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { findVaultOrphans } from './lib/session-end/vault-orphans.mjs';
+import { _parseVaultIntegration } from './lib/config/vault-integration.mjs';
+import { loadHostPaths } from './lib/config/host-paths.mjs';
+import { resolveVaultDir } from './lib/config.mjs';
+import { expandTilde } from './lib/common.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+
+const HELP = `vault-orphans.mjs - name untracked vault files written since a session started (#1563)
+
+USAGE
+  node scripts/vault-orphans.mjs --since <ISO> [--vault-dir <dir>] [--json]
+
+DESCRIPTION
+  Runs the read-only \`git -C <vault-dir> ls-files --others --exclude-standard\`
+  and lists every untracked file whose mtime is at or after --since. Files whose
+  frontmatter names one of this plugin's generators (\`_generator:
+  session-orchestrator-...\`) are left out: their writer owns them.
+
+  The results are CANDIDATES: mtime is a hint, not proof that this session
+  wrote the file. Nothing is committed, moved or deleted.
+
+OPTIONS
+  --since <ISO>       Required. ISO 8601 instant with Z or an offset, e.g. the
+                      STATE.md \`started_at\` (2026-10-11T08:00:00.000Z).
+  --vault-dir <dir>   Vault working tree. Default: the host-local resolution
+                      SO_VAULT_DIR > owner.yaml > committed
+                      vault-integration.vault-dir in ./CLAUDE.md or ./AGENTS.md.
+  --json              Print the result object as JSON on stdout.
+  --help              Show this help.
+  --version           Print the plugin version.
+
+EXIT CODES
+  0  measured, including zero candidates
+  1  bad arguments
+  2  could not measure (no vault dir, not a git repo, git failed)
+
+EXAMPLE
+  node scripts/vault-orphans.mjs --since 2026-10-11T08:00:00.000Z --json
+`;
+
+/** ISO 8601 with an explicit zone - a zone-less value would be read as local time. */
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+/**
+ * Resolve the vault dir like the other vault writers: SO_VAULT_DIR > owner.yaml
+ * `vault-dirs:` cwd match > owner.yaml `paths.vault-dir` > committed value.
+ *
+ * @returns {string|null}
+ */
+function resolveDefaultVaultDir() {
+  let content = '';
+  for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+    const p = join(process.cwd(), name);
+    if (existsSync(p)) {
+      try {
+        content = readFileSync(p, 'utf8');
+        break;
+      } catch {
+        /* try the next file */
+      }
+    }
+  }
+  const vi = _parseVaultIntegration(content);
+  const value = resolveVaultDir(vi['vault-dir'], loadHostPaths()).value;
+  return typeof value === 'string' && value.trim() !== '' ? expandTilde(value) : null;
+}
+
+/** @param {{status: 'ok', candidates: Array<{path: string}>, total: number, truncated: boolean, untracked: number}} r */
+function renderHuman(r, since) {
+  const lines = [];
+  if (r.total === 0) {
+    lines.push(`vault-orphans: no untracked vault file modified since ${since} (${r.untracked} untracked in total)`);
+  } else {
+    lines.push(
+      `vault-orphans: ${r.total} untracked vault file(s) modified since ${since} - candidates only, ` +
+        `mtime does not prove this session wrote them (${r.untracked} untracked in total)`,
+    );
+    for (const c of r.candidates) lines.push(`  ${c.path}`);
+    if (r.truncated) lines.push(`  ... showing ${r.candidates.length} of ${r.total}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * CLI entry.
+ *
+ * @param {string[]} [argv]
+ * @param {{stdout: {write: Function}, stderr: {write: Function}}} [io]
+ * @returns {number} exit code
+ */
+export function main(argv = process.argv.slice(2), io = { stdout: process.stdout, stderr: process.stderr }) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: {
+        since: { type: 'string' },
+        'vault-dir': { type: 'string' },
+        json: { type: 'boolean', default: false },
+        help: { type: 'boolean', default: false },
+        version: { type: 'boolean', default: false },
+      },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (err) {
+    io.stderr.write(`vault-orphans: ${err.message}\nRun with --help for usage.\n`);
+    return 1;
+  }
+
+  if (values.help) {
+    io.stdout.write(HELP);
+    return 0;
+  }
+  if (values.version) {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    io.stdout.write(`${pkg.version}\n`);
+    return 0;
+  }
+
+  const since = values.since;
+  const sinceMs = typeof since === 'string' && ISO_RE.test(since) ? Date.parse(since) : NaN;
+  if (!Number.isFinite(sinceMs)) {
+    io.stderr.write('vault-orphans: --since <ISO> is required, e.g. 2026-10-11T08:00:00.000Z\n');
+    return 1;
+  }
+  if (values['vault-dir'] !== undefined && values['vault-dir'].trim() === '') {
+    io.stderr.write('vault-orphans: --vault-dir must not be empty\n');
+    return 1;
+  }
+
+  const vaultDir =
+    values['vault-dir'] !== undefined ? expandTilde(values['vault-dir']) : resolveDefaultVaultDir();
+  const result = findVaultOrphans({ vaultDir, sinceMs });
+
+  if (result.status !== 'ok') {
+    io.stderr.write(
+      `vault-orphans: could not measure (${result.reason}${result.detail ? `: ${result.detail}` : ''})\n`,
+    );
+    if (values.json) io.stdout.write(`${JSON.stringify(result)}\n`);
+    return 2;
+  }
+
+  io.stdout.write(values.json ? `${JSON.stringify(result)}\n` : renderHuman(result, since));
+  return 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = main();
+}

package/skills/_shared/fleet-protocol.md

@@ -75,7 +75,14 @@ die vom Lease-Validator akzeptierte `adresse` einer aktiven Lease, sonst `null`
 Lease, kein Eintrag oder ein abgelehnter Wert — nie ein ungeprüfter String). `fallback_due_at` ist
 der Zeitpunkt, ab dem die Standard-Auflagen (unten) gelten, in der Form von `zeit` (Code:
 `fallbackDueAt()`); er steht nur auf stdout, die Check-in-Datei behält ihr Schema. Exit 0
-geschrieben, 2 ungültige Eingabe (Fehlerliste auf stderr, keine Datei), 1 Schreibfehler.
+geschrieben, 2 ungültige Eingabe (Fehlerliste auf stderr, keine Datei) oder semantische Session-ID
+von einem anderen Repo belegt (eine Zeile auf stderr mit JSON-escaped Repo-Namen, fremde Datei unverändert,
+tmp entfernt, kein Event), 1 Schreibfehler.
+Vor dem `rename` lehnt der Schreiber ein vorhandenes String-`repo` ungleich dem eigenen ab;
+gleiches `repo`, unlesbare Dateien und ungültiges JSON dürfen überschrieben werden.
+Die Prüfung folgt keinen Symlinks, öffnet nichtblockierend und liest nur reguläre Dateien
+bis 64 KiB. Symlinks, andere Dateitypen, größere Dateien oder fehlende sichere Open-Flags
+gelten für diese Prüfung als unlesbar (fail-open zum `rename`).
 
 | Feld | Inhalt |
 |---|---|
@@ -130,9 +137,24 @@ aktiven Navigator ist `fallback_due_at` gleich `zeit`, die Auflagen gelten also
 Lesende Arbeit und Schreiben im eigenen Worktree laufen währenddessen weiter; der Rückfall ist ein
 Dateistand mit Frist, kein Warten auf eine Antwort.
 
+## Verhalten ohne Flotte
+
+Flottenintegration liegt vor, wenn `NAVIGATOR_CONFIG_DIR` gesetzt und nicht leer ist (ausdrückliches
+Opt-in, auch vor dem ersten Anlegen) oder `~/.config/navigator/` als Verzeichnis existiert (Code:
+`fleetIntegrationEnabled()`, #1559). Ein Flottenhost hat das Verzeichnis, weil der Koordinator dort
+die Lease schreibt. Ohne Flottenintegration validiert `fleet-checkin.mjs` die Eingabe wie immer
+(ungültig → Exit 2), schreibt dann aber nichts, legt kein Verzeichnis an, emittiert kein Event und
+meldet `{"ok":true,"skipped":"no-fleet",…}`. Es gelten keine Auflagen, auch keine Standard-Auflagen:
+ohne Flotte gibt es nichts zu koordinieren. Die Navigator-Zeile im Sessionstart-Banner entfällt
+ebenso. Das gilt auch für `plattform: kopflos`: der Datensatz beweist keinen Koordinator, und ein
+Schreiben legte das Verzeichnis an, das danach jede Solo-Session zur Flotte macht. Ein kopfloser
+Lauf ohne Flottenintegration wendet stattdessen die Standard-Auflagen sofort an — er kann niemanden
+fragen. Ein Flotten-Starter, der auf einem frischen Remote-Host startet, setzt deshalb
+`NAVIGATOR_CONFIG_DIR` oder legt das Verzeichnis vorher an.
+
 ## Verhalten ohne Navigator
 
-Lease `none` oder `unreadable`: die Check-in-Datei wird **trotzdem** geschrieben (sie ist der
+Flottenintegration vorhanden, Lease `none` oder `unreadable`: die Check-in-Datei wird **trotzdem** geschrieben (sie ist der
 zählbare Beleg), die Standard-Auflagen gelten sofort, es geht keine Nachricht ab. Kopflose Läufe
 sind per Nachricht nicht erreichbar und nutzen dieselben Dateien: vor jeder Welle `auflagen/` lesen.
 

package/skills/_shared/state-ownership.md

@@ -40,7 +40,7 @@ The `session-type: none` + `status: idle` combination is used only for bootstrap
 | `## Wave History` | Completed wave records | wave-executor (post-wave) |
 | `## Deviations` | Plan adaptation log | wave-executor (step 3) |
 | `## What Not To Retry` | Failed/abandoned approaches not to repeat (#623) | session-end (Phase 1.6) |
-| `## Open Questions` | Unresolved user-facing questions (agent → gate → next session) | wave-executor (inter-wave) + session-end (marks answered) |
+| `## Open Questions` | Unresolved user-facing questions (agent → gate → next session) | wave-executor (inter-wave) + session-end (marks answered; appends one vault-orphan entry at Phase 3.7e, #1563) |
 
 Wave History lines MAY include a `→ issue #NNN` suffix (or `→ existing #NNN` when a duplicate was detected) for SPIRAL/FAILED agents, linking to the auto-created carryover issue (#261). This is optional and backward-compatible; readers that do not recognize the notation can skip it. Session-end Phase 1.6 uses the presence of this suffix to decide whether to retro-file a carryover as a fallback safety net.
 
@@ -139,8 +139,8 @@ growing across sessions is the CCU-009 anti-pattern.
 | Skill | Access | Operations |
 |-------|--------|------------|
 | **wave-executor** | Read + Write (owner) | Creates STATE.md (Pre-Wave 1b), updates after each wave (current-wave, Wave History, Deviations); appends deduped `## Open Questions` at inter-wave checkpoints via `appendOpenQuestionOnDisk` (see `wave-loop.md` § 3e + Post-Wave step 6). |
-| **session-end** | Read + Status-only write | Reads for metrics extraction (Phase 1.7), sets `status: completed` (Phase 3.4). Exception: only fields modified are `status` in frontmatter and marking entries answered in `## Open Questions` via `markOpenQuestionAnsweredOnDisk` (Close Handover-Alignment-Gate). |
-| **session-start** | Read + conditional reset | Reads for continuity checks (Phase 1.5): inspects `status` field to detect crashed/paused sessions. Surfaces `## What Not To Retry` as a forced-read HISTORICAL block (Phase 6.5.1). May reset STATE.md to idle at the boundary between a completed session and a new session — only when prior `status: completed`. The reset clears `current-wave` (→ 0), sets `status: idle`, demotes `## Wave History` into `## Previous Session`, and empties `## Deviations` — but PRESERVES `## What Not To Retry` (cross-session continuity, #623) and `## Open Questions` (Close Handover-Alignment-Gate, PRD 2026-07-07). Never resets on `active` or `paused` (those paths are user-interactive). |
+| **session-end** | Read + Status-only write | Reads for metrics extraction (Phase 1.7), sets `status: completed` (Phase 3.4). Exception: only fields modified are `status` in frontmatter and marking entries answered in `## Open Questions` via `markOpenQuestionAnsweredOnDisk` (Close Handover-Alignment-Gate), plus at most one appended `## Open Questions` entry naming vault-orphan candidates via `appendOpenQuestionOnDisk` (Phase 3.7e, #1563). |
+| **session-start** | Read + conditional reset | Reads for continuity checks (Phase 1.5): inspects `status` field to detect crashed/paused sessions. Surfaces `## What Not To Retry` as a forced-read HISTORICAL block (Phase 6.5.1). May reset STATE.md to idle at the boundary between a completed session and a new session — only when prior `status: completed`, via `scripts/state-md-idle-reset.mjs` (#1560). The reset keeps the five recommendation keys in the frontmatter for the Phase 7.5 Mode-Selector, clears `current-wave` (→ 0), sets `status: idle`, demotes `## Wave History` into `## Previous Session`, and empties `## Deviations` — but PRESERVES `## What Not To Retry` (cross-session continuity, #623) and `## Open Questions` (Close Handover-Alignment-Gate, PRD 2026-07-07). Never resets on `active` or `paused` (those paths are user-interactive). |
 | **evolve** | Read-only | Reads `## Deviations` section for deviation pattern extraction (Step 2.2, pattern 5) |
 
 ### Shared-File Single-Writer Rule (`isolation: none` waves)

package/skills/autopilot/SKILL.md

@@ -249,8 +249,9 @@ import { detectPeers } from '$PLUGIN_ROOT/scripts/lib/session-registry.mjs';
 const flags = parseFlags(process.argv.slice(2));
 
 const modeSelector = async () => {
-  // Each iteration rebuilds signals from current disk state. STATE.md will be
-  // freshly idle-reset by the previous /close, sessions.jsonl will have the
+  // Each iteration rebuilds signals from current disk state. STATE.md will
+  // carry the recommendation the previous /close wrote (the idle reset at the
+  // next session-start keeps those keys, #1560), sessions.jsonl will have the
   // new tail entry, etc. This is the contract: live signals every iteration.
   // `repoRoot` is passed explicitly (#1071) rather than left to the helper's
   // cwd default. Do NOT hand-write a `backlogLimit` here — the window default