session-orchestrator 5.3.0 → 5.5.0

package/scripts/fleet-checkin.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * fleet-checkin.mjs — write this session's fleet check-in (#1462, PRD !53 § 3.2).
+ *
+ * Thin CLI over `scripts/lib/fleet-protocol.mjs`, called by session-start
+ * Phase 7.6 and the operations-contract peer preflight BEFORE the first writing
+ * action of a session.
+ *
+ * Usage:
+ *   echo '<check-in JSON>' | node scripts/fleet-checkin.mjs
+ *
+ * Reads one JSON object from stdin, stamps `zeit` (always overwritten), validates
+ * it with `validateCheckin()`, and writes it atomically (tmp file + rename in
+ * the target directory, mode 0600) to `<navigatorDir>/checkin/<session>.json`.
+ * Then reads the navigator lease and emits `orchestrator.fleet.checkin` with the
+ * payload `{ session, repo, modus, kandidaten, navigator_state }` — no paths, no
+ * quota, no `auftrag_ref`.
+ *
+ * stdout: one JSON line
+ * `{ ok, path, navigator_state, navigator_adresse, fallback_due_at, event }`.
+ * `navigator_adresse` is the active lease's `adresse` exactly as
+ * `readNavigatorLease()` validated it (a ListAgents peer name), else `null` — no
+ * active lease, no address in it, or one the validator refused. It is the only
+ * value the caller may address a hint to; an unvalidated string never reaches it.
+ * `fallback_due_at` is `fallbackDueAt(zeit, navigator_state)`: when the
+ * Standard-Auflagen apply if no `auflagen/` file has appeared by then. It is
+ * stdout only — the check-in FILE schema, which the navigator reads, is unchanged.
+ *
+ * Exit codes:
+ *   0 — check-in written (an event failure only WARNs; `event: false` on stdout)
+ *   1 — write error
+ *   2 — invalid input (not JSON, not an object, or validation errors; no file)
+ */
+
+import { randomBytes } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { emitEvent } from './lib/events.mjs';
+import {
+  checkinPath,
+  fallbackDueAt,
+  navigatorDir,
+  readNavigatorLease,
+  utcSecondsTimestamp,
+  validateCheckin,
+} from './lib/fleet-protocol.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+
+const PREFIX = 'fleet-checkin:';
+
+/** @returns {Promise<string>} */
+async function readStdin() {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+/**
+ * Create `<navigatorDir>/checkin/` (0700) and write `record` atomically to
+ * `target` (0600). Refuses a `checkin/` that is not a real directory, so a
+ * planted symlink cannot redirect the chmod or the write.
+ * @param {string} target
+ * @param {object} record
+ */
+async function writeCheckinFile(target, record) {
+  const checkinDir = path.dirname(target);
+  await fs.mkdir(navigatorDir(), { recursive: true, mode: 0o700 });
+  await fs.mkdir(checkinDir, { recursive: true, mode: 0o700 });
+  const st = await fs.lstat(checkinDir);
+  if (!st.isDirectory()) throw new Error(`${checkinDir} is not a directory`);
+  // mkdir's mode does not apply to a directory that already existed.
+  await fs.chmod(checkinDir, 0o700);
+
+  const tmp = path.join(checkinDir, `.${path.basename(target)}.${randomBytes(6).toString('hex')}.tmp`);
+  try {
+    // `wx`: never follow or reuse a pre-existing path at the tmp name.
+    await fs.writeFile(tmp, JSON.stringify(record, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+    // The creation mode is filtered through the umask; pin it explicitly.
+    await fs.chmod(tmp, 0o600);
+    await fs.rename(tmp, target);
+  } catch (err) {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+/** @returns {Promise<number>} exit code */
+async function main() {
+  let input;
+  try {
+    input = JSON.parse(await readStdin());
+  } catch {
+    process.stderr.write(`${PREFIX} stdin is not valid JSON\n`);
+    return 2;
+  }
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    process.stderr.write(`${PREFIX} stdin must be a JSON object\n`);
+    return 2;
+  }
+
+  const record = { ...input, zeit: utcSecondsTimestamp() };
+  const errors = validateCheckin(record);
+  if (errors.length > 0) {
+    for (const e of errors) process.stderr.write(`${PREFIX} ${e}\n`);
+    return 2;
+  }
+
+  const target = checkinPath(record.session);
+  try {
+    await writeCheckinFile(target, record);
+  } catch (err) {
+    process.stderr.write(`${PREFIX} write failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    return 1;
+  }
+
+  const navigator = await readNavigatorLease();
+  const navigatorState = navigator.state;
+  // readNavigatorLease() returns a lease only when it passed validation, its
+  // `adresse` included (an invalid one makes the whole lease `unreadable`).
+  const navigatorAdresse =
+    navigator.state === 'active' && typeof navigator.lease.adresse === 'string' ? navigator.lease.adresse : null;
+
+  let event = true;
+  try {
+    const repoRoot = (process.env.CLAUDE_PROJECT_DIR || '').trim() || process.cwd();
+    await emitEvent(
+      'orchestrator.fleet.checkin',
+      {
+        session: record.session,
+        repo: record.repo,
+        modus: record.modus,
+        kandidaten: record.kandidaten,
+        navigator_state: navigatorState,
+      },
+      { repoRoot },
+    );
+  } catch (err) {
+    event = false;
+    process.stderr.write(
+      `${PREFIX} WARN: check-in written but event emission failed: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
+
+  // Report the path with `~` for the home prefix: stdout lands in transcripts.
+  const home = os.homedir();
+  const shownPath = target.startsWith(`${home}${path.sep}`) ? `~${target.slice(home.length)}` : target;
+  process.stdout.write(
+    JSON.stringify({
+      ok: true,
+      path: shownPath,
+      navigator_state: navigatorState,
+      navigator_adresse: navigatorAdresse,
+      fallback_due_at: fallbackDueAt(record.zeit, navigatorState),
+      event,
+    }) + '\n',
+  );
+  return 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  main().then(
+    (code) => { process.exitCode = code; },
+    (err) => {
+      process.stderr.write(`${PREFIX} ${err instanceof Error ? err.message : String(err)}\n`);
+      process.exitCode = 1;
+    },
+  );
+}

package/scripts/lib/agent-frontmatter.mjs

@@ -21,11 +21,11 @@ const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 
 // Aliases per https://code.claude.com/docs/en/sub-agents § model resolution.
 // Full model IDs (claude-{opus|sonnet|haiku|fable}-N[-N][-YYYYMMDD], e.g.
-// "claude-opus-4-7", "claude-sonnet-5", "claude-fable-5-20260101") also
+// "claude-opus-5-5", "claude-sonnet-5", "claude-fable-5-20260101") also
 // accepted via MODEL_ID_RE. `fable` is a valid upstream model family
 // alongside opus/sonnet/haiku (#768) — the trailing numeric group is
 // optional so both the two-part ("claude-sonnet-5") and three-part
-// ("claude-opus-4-7") ID shapes validate.
+// ("claude-opus-5-5") ID shapes validate.
 // Exported so persona-panel modules (catalog-loader.mjs, persona-gate-wave.mjs) can
 // validate against the SSOT instead of re-declaring (W4 architect MED-1, 2026-05-19).
 export const ALLOWED_MODEL_ALIASES = new Set(['inherit', 'sonnet', 'opus', 'haiku', 'fable']);
@@ -187,7 +187,7 @@ export function validateAgentFrontmatter(frontmatter) {
     errors.push({
       path: 'model',
       rule: 'enum',
-      message: `model must be one of ${[...ALLOWED_MODEL_ALIASES].map((m) => JSON.stringify(m)).join('|')} or a full model ID like "claude-opus-4-7" or "claude-sonnet-5" (got ${JSON.stringify(model)})`,
+      message: `model must be one of ${[...ALLOWED_MODEL_ALIASES].map((m) => JSON.stringify(m)).join('|')} or a full model ID like "claude-opus-5-5" or "claude-sonnet-5" (got ${JSON.stringify(model)})`,
     });
   }
 

package/scripts/lib/auto-dream.mjs

@@ -1,10 +1,11 @@
 /**
- * auto-dream.mjs — Auto-Dream Post-Session Hook helper (issue #502, PRD F2.2).
+ * auto-dream.mjs — Memory-maintenance signals and proposal I/O (issue #502).
  *
- * Provides the decision + I/O surface used by session-end Phase 3.6.5 and by
- * /memory-cleanup --dry-run / --apply-pending. Decides whether the post-session
- * dream should fire, writes the proposed diff to `.orchestrator/pending-dream.md`
- * atomically, and applies it in a follow-up session.
+ * Provides the due signal used by session-start's maintenance-due probe and
+ * the I/O used by /memory-cleanup --dry-run / --apply-pending. The former
+ * session-end Phase 3.6.5 nudge was retired in #1288. The manual skill writes
+ * `.orchestrator/pending-dream.md` atomically and applies a reviewed proposal;
+ * the maintenance probe does not generate proposals or dispatch a cleanup.
  *
  * Decision inputs (PRD F2.2 acceptance criteria):
  *   - memory-cleanup-threshold (default 5) — sessions since last cleanup
@@ -118,7 +119,7 @@ export async function readDreamSignals({ repoRoot, memoryDir }) {
 // ---------------------------------------------------------------------------
 
 /**
- * Decide whether session-end Phase 3.6.5 should dispatch /memory-cleanup --dry-run.
+ * Decide whether session-start should report that memory cleanup is due.
  *
  * Rules (PRD F2.2):
  *   - threshold === 0 → never trigger (kill-switch).

package/scripts/lib/autopilot/flags.mjs

@@ -20,7 +20,12 @@ export const FLAG_BOUNDS = Object.freeze({
   maxSessions: { min: 1, max: 50, default: 5 },
   maxHours: { min: 0.5, max: 24.0, default: 4.0 },
   confidenceThreshold: { min: 0.0, max: 1.0, default: 0.85 },
-  maxTokens: { min: 0, max: 10_000_000, default: 500_000 },
+  // Default 0 = token-budget switch OFF until calibrated (HR-101): the budget
+  // counts subagent OUTPUT tokens only, and one measured deep session's
+  // subagents alone produced 450 499 — a 500 000 default stopped autopilot after
+  // about one deep session. Revisit once sessions.jsonl carries enough
+  // total_token_output values to pick a threshold that fires rarely.
+  maxTokens: { min: 0, max: 10_000_000, default: 0 },
 });
 
 /** Default peer Claude-process count above which `resource-overload` fires when verdict is critical. */

package/scripts/lib/autopilot/loop.mjs

@@ -38,6 +38,7 @@ function clampNumber(value, { min, max, fallback }) {
  * @property {string|null} kill_switch @property {string|null} kill_switch_detail @property {string[]} sessions
  * @property {string|null} host_class @property {string|null} resource_verdict_at_start
  * @property {boolean} fallback_to_manual @property {boolean} dry_run @property {number} total_tokens_used
+ * @property {number} tokens_unknown_sessions — #1487 Pkt 4: iterations whose own record carried no token figure; > 0 makes total_tokens_used a lower bound
  * @property {string|null} worktree_path @property {string|null} parent_run_id @property {number} stall_recovery_count
  * @property {number|null} blocked_by_issue — Phase D (#341): issue number this loop was waiting on (OPEN-4 commit-deps); null when not blocked
  * @property {boolean} aborted_by_cohort — Phase D (#341): set by cohort-abort policy (OPEN-5); mutated by W3 P5 orchestration-glue, not by runLoop itself
@@ -131,11 +132,19 @@ export async function runLoop(opts = {}) {
     confidence_threshold: confidenceThreshold,
     // Persisted for the same reason as the three above (HR-105): a switch whose
     // input is never recorded cannot be falsified afterwards. `0` = disabled.
-    // CEILING: reaching a NON-zero value here does not make TOKEN_BUDGET_EXCEEDED
-    // live under the headless driver — `readTailSession()` in scripts/autopilot.mjs
-    // returns no `usage`, and sessions.jsonl carries no token field to build one
-    // from, so `total_tokens_used` stays 0. Revisit when a session record gains
-    // token counts.
+    // Live path (#1436): scripts/emit-session.mjs merges the subagents.jsonl
+    // rollup (`total_token_output`, `total_tokens`) into each session record,
+    // scripts/autopilot.mjs selects the unique canonical record whose
+    // raw_session_id equals the child's --session-id UUID and projects its
+    // totals as `usage`; the accumulator sums them into `total_tokens_used`.
+    // Zero or multiple matches throw → FAILED_WAVE, never foreign token usage.
+    // CEILING: an own record without token totals adds 0 — the budget
+    // undercounts, it never over-fires. Such sessions are counted in
+    // `tokens_unknown_sessions` (#1487 Pkt 4), and the switch still fires on the
+    // known lower bound: every fire stays correct, none is lost. Failing closed on
+    // an unknown session instead would stop an armed run on every
+    // coordinator-direct session (no subagents → no rollup totals); revisit if
+    // the session record ever carries the coordinator's own usage.
     max_tokens: opts.maxTokens ?? 0,
     iterations_completed: 0,
     kill_switch: null,
@@ -146,6 +155,9 @@ export async function runLoop(opts = {}) {
     fallback_to_manual: false,
     dry_run: dryRun,
     total_tokens_used: 0,
+    // #1487 Pkt 4 — completed iterations whose own record carried no token
+    // figure; non-zero means `total_tokens_used` is a lower bound.
+    tokens_unknown_sessions: 0,
     // ADR-364 additive fields — forward-compat; callers may omit, defaults are null/0.
     worktree_path: opts.worktreePath ?? null,
     parent_run_id: opts.parentRunId ?? null,
@@ -271,14 +283,21 @@ export async function runLoop(opts = {}) {
     }
     state.iterations_completed += 1;
 
-    // Accumulate output tokens; stays 0 when sessionRunner omits `usage` (forward-compat).
-    if (sessionResult && typeof sessionResult.usage === 'object' && sessionResult.usage !== null) {
-      const outTokens = Number(
-        sessionResult.usage.output_tokens ?? sessionResult.usage.total_tokens
-      );
-      if (Number.isFinite(outTokens) && outTokens > 0) {
-        cumulativeTokens += outTokens;
-      }
+    // Accumulate own-record output tokens (total_tokens fallback). An unassignable
+    // child record already threw → FAILED_WAVE above. An own record carrying
+    // neither figure has UNKNOWN usage, not 0 (#1487 Pkt 4): it adds nothing, so
+    // `total_tokens_used` is a lower bound, and it is counted in
+    // `tokens_unknown_sessions` so the record says how much the sum cannot see.
+    const usage = sessionResult?.usage;
+    const rawTokens = usage !== null && typeof usage === 'object'
+      ? (usage.output_tokens ?? usage.total_tokens)
+      : undefined;
+    // `Number(null)` is 0 — a null figure is a missing one, never a measured 0.
+    const outTokens = rawTokens === null || rawTokens === undefined ? NaN : Number(rawTokens);
+    if (Number.isFinite(outTokens) && outTokens >= 0) {
+      cumulativeTokens += outTokens;
+    } else {
+      state.tokens_unknown_sessions += 1;
     }
     state.total_tokens_used = cumulativeTokens;
 

package/scripts/lib/autopilot/stall-sampler.mjs

@@ -8,7 +8,8 @@
  *      `hooks/on-stop.mjs` refreshes it at every turn-end and
  *      `hooks/post-tool-batch-wave-signal.mjs` at every tool batch.
  *   2. `autopilot.jsonl` mtime — the legacy marker, used only when no lock path
- *      is supplied or the lock is absent/corrupt/timestamp-less.
+ *      is supplied or the lock is absent/corrupt/heartbeat-less (`started_at`
+ *      is never a stand-in — it does not advance during a run).
  *
  * The header of this module used to claim `autopilot.jsonl` carries "one record
  * per session". It does not: `telemetry.mjs` writes ONE record per /autopilot
@@ -74,11 +75,13 @@ function readHeartbeatMs(sessionLockPath) {
     return null;
   }
   if (typeof lock !== 'object' || lock === null) return null;
-  // Same precedence `session-lock.mjs` uses on read: a v1 lock has no
-  // `last_heartbeat`, and its `started_at` is the best available stand-in.
-  const raw = typeof lock.last_heartbeat === 'string' && lock.last_heartbeat.length > 0
-    ? lock.last_heartbeat
-    : lock.started_at;
+  // `last_heartbeat` only — no `started_at` stand-in, matching `isLockLive()`
+  // since the #595 sunset (2026-10-02). `started_at` never advances during a
+  // run, so a lock without a heartbeat would read as a stall once 600 s passed
+  // (or as fresh within 30 s of its genesis) — a measurement the lock never
+  // made. No heartbeat → `null` → the mtime marker, exactly as for a lock
+  // with no timestamp at all.
+  const raw = lock.last_heartbeat;
   if (typeof raw !== 'string' || raw.length === 0) return null;
   const ms = Date.parse(raw);
   return Number.isFinite(ms) ? ms : null;
@@ -95,9 +98,10 @@ function readHeartbeatMs(sessionLockPath) {
  * @param {string} [opts.autopilotJsonlPath] — path to autopilot.jsonl (default
  *   '.orchestrator/metrics/autopilot.jsonl').
  * @param {string} [opts.sessionLockPath] — path to `session.lock`. When supplied
- *   and readable, its `last_heartbeat` (falling back to `started_at`, the schema
- *   v1 normalisation `session-lock.mjs` applies on read) REPLACES the mtime
- *   marker. Omitted → mtime only, which is what every pre-existing caller gets.
+ *   and readable, its `last_heartbeat` REPLACES the mtime marker. A lock
+ *   without a parsable `last_heartbeat` contributes nothing (no `started_at`
+ *   fallback, as in `session-lock.mjs` `isLockLive()`) and the mtime marker is
+ *   used. Omitted → mtime only, which is what every pre-existing caller gets.
  * @param {number} [opts.stallTimeoutSeconds] — kill-switch threshold (default
  *   600). NOT range-clamped here; caller is responsible for bounds.
  * @param {() => number} [opts.nowMs] — wall-clock supplier (default Date.now).

package/scripts/lib/baseline-archetypes.mjs

@@ -19,10 +19,11 @@ const BASENAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*\.md$/;
 const unique = (items) => [...new Set(items)].sort();
 const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
 
+/** `message` must never interpolate a baseline root or any other host path. */
 export class BaselineContractError extends Error {
-  constructor(reason) { super(`Baseline archetype lookup failed (${reason}).`); this.name = 'BaselineContractError'; this.reason = reason; }
+  constructor(reason, message = `Baseline archetype lookup failed (${reason}).`) { super(message); this.name = 'BaselineContractError'; this.reason = reason; }
 }
-function fail(reason = 'invalid-contract') { throw new BaselineContractError(reason); }
+function fail(reason = 'invalid-contract', message) { throw new BaselineContractError(reason, message); }
 function check(condition) { if (!condition) fail(); }
 function shape(value, required, optional = []) {
   check(object(value) && required.every((key) => Object.hasOwn(value, key)) && Object.keys(value).every((key) => [...required, ...optional].includes(key)));
@@ -122,24 +123,38 @@ process.stdout.write(JSON.stringify(resolveConfiguredBaselinePath(JSON.parse(rea
   return realpathSync(root);
 }
 
-/** Resolve a canonical relative source and reject symlinks at every component. */
-export function baselineSourcePath(root, source, directory = false) {
+/** Resolve a canonical relative source and reject symlinks at every component.
+ * Only an ENOENT thrown by the per-component `lstatSync` itself maps to
+ * `missingReason`; every other failure is `unsafe-source`. Existence is never
+ * probed with a link-following call (existsSync/statSync/accessSync/realpathSync):
+ * a dangling symlink would then read as "missing" instead of `unsafe-source`.
+ */
+export function baselineSourcePath(root, source, directory = false, { missingReason = 'unsafe-source' } = {}) {
   relative(source);
+  // Resolved first: a vanished root is unsafe, never a missing source.
+  let realRoot;
+  try { realRoot = realpathSync(root); } catch { fail('unsafe-source'); }
   let current = root;
-  try {
-    for (const component of source.split('/')) {
-      current = path.join(current, component);
-      if (lstatSync(current).isSymbolicLink()) fail('unsafe-source');
-    }
-    const stat = lstatSync(current);
-    if (directory ? !stat.isDirectory() : !stat.isFile()) fail('unsafe-source');
-    if (!realpathSync(current).startsWith(`${realpathSync(root)}${path.sep}`)) fail('unsafe-source');
-    return current;
-  } catch { fail('unsafe-source'); }
+  let stat;
+  for (const component of source.split('/')) {
+    current = path.join(current, component);
+    try { stat = lstatSync(current); } catch (error) { fail(error?.code === 'ENOENT' ? missingReason : 'unsafe-source'); }
+    if (stat.isSymbolicLink()) fail('unsafe-source');
+  }
+  if (directory ? !stat.isDirectory() : !stat.isFile()) fail('unsafe-source');
+  let real;
+  try { real = realpathSync(current); } catch { fail('unsafe-source'); }
+  if (!real.startsWith(`${realRoot}${path.sep}`)) fail('unsafe-source');
+  return current;
 }
 
+const PRODUCER = 'scripts/archetype-manifest.mjs';
 function projection(root, args, { timeoutMs = 5000, maxBuffer = MAX_BYTES } = {}) {
-  const script = baselineSourcePath(root, 'scripts/archetype-manifest.mjs');
+  let script;
+  try { script = baselineSourcePath(root, PRODUCER, false, { missingReason: 'producer-missing' }); } catch (error) {
+    if (error?.reason !== 'producer-missing') throw error;
+    fail('producer-missing', `Baseline archetype lookup failed (producer-missing): the configured baseline has no ${PRODUCER} exporter — see docs/baseline.md § How bootstrap finds it.`);
+  }
   const result = spawnSync(process.execPath, [script, ...args], {
     cwd: root, encoding: 'utf8', timeout: Math.min(timeoutMs, 5000), maxBuffer: Math.min(maxBuffer, MAX_BYTES),
     shell: false, killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'pipe'],
@@ -195,7 +210,8 @@ export async function loadBaselineArchetypes(options = {}) {
     let manifest;
     try { manifest = validateBaselineContract(JSON.parse(projection(root, ['export'], options))); }
     catch (error) { if (error instanceof BaselineContractError) throw error; fail(); }
-    for (const item of manifest.archetypes) baselineSourcePath(root, item.templatePath, true);
+    // An absent declared source is an incomplete baseline, not a security refusal (#1447 3a).
+    for (const item of manifest.archetypes) baselineSourcePath(root, item.templatePath, true, { missingReason: 'invalid-contract' });
     const facts = collectFacts(repoRoot);
     const ordered = [...manifest.archetypes].sort((a, b) => a.order - b.order);
     const archetypes = ordered.map(({ id, order, runtimes, packageManagers, ui, api, deploy }) => ({ id, order, runtimes, packageManagers, ui, api, deploy }));
@@ -220,7 +236,7 @@ export async function loadBaselineArchetypes(options = {}) {
       if (!ruleTargets.includes(name) || seen.has(name)) fail('invalid-rule-projection');
       seen.add(name);
       if (owned.includes(name)) continue;
-      baselineSourcePath(root, source);
+      baselineSourcePath(root, source, false, { missingReason: 'invalid-rule-projection' });
       baselineRules.push({ source, target: `.claude/rules/${name}` });
     }
     if (ruleTargets.some((name) => !seen.has(name))) fail('invalid-rule-projection');
@@ -230,7 +246,9 @@ export async function loadBaselineArchetypes(options = {}) {
       pluginRuleTargets: ruleTargets.filter((name) => owned.includes(name)), baselineRules,
     } };
   } catch (error) {
-    return { status: 'error', reason: error instanceof BaselineContractError ? error.reason : 'lookup-failed', archetypes: [], selected: null };
+    // Only a BaselineContractError message is path-free by construction; others stay opaque.
+    const contract = error instanceof BaselineContractError;
+    return { status: 'error', reason: contract ? error.reason : 'lookup-failed', ...(contract && { message: error.message }), archetypes: [], selected: null };
   }
 }
 
@@ -290,11 +308,12 @@ function applyCopies(plan) {
   return { status: 'applied', created, preserved };
 }
 function applyFailure(error) {
-  return { status: 'error', reason: error instanceof BaselineContractError ? error.reason : 'apply-failed', created: [], preserved: [] };
+  const contract = error instanceof BaselineContractError;
+  return { status: 'error', reason: contract ? error.reason : 'apply-failed', ...(contract && { message: error.message }), created: [], preserved: [] };
 }
 async function selectedContext(options) {
   const result = await loadBaselineArchetypes(options);
-  if (result.status !== 'private' || !result.selected) fail(result.reason);
+  if (result.status !== 'private' || !result.selected) fail(result.reason, result.message);
   const root = await resolveBaselineLocation(options);
   if (!root) fail('baseline-unavailable');
   return { root, selected: result.selected };
@@ -340,7 +359,7 @@ export async function scaffoldBaselineArchetype(options = {}) {
     const { repoRoot = process.cwd(), projectName } = options;
     if (typeof projectName !== 'string' || !ID.test(projectName)) fail('invalid-project-name');
     const { root, selected } = await selectedContext(options);
-    const template = baselineSourcePath(root, selected.templatePath, true);
+    const template = baselineSourcePath(root, selected.templatePath, true, { missingReason: 'invalid-contract' });
     sourceFiles(template);
     const shared = baselineSourcePath(root, 'templates/shared', true);
     sourceFiles(shared);
@@ -401,7 +420,7 @@ export async function syncBootstrapRules(options = {}) {
     // ordinary plugin rules, just as its minimal scaffold does.
     const contract = options.minimal ? { status: 'public', selected: null }
       : await loadBaselineArchetypes({ ...options, repoRoot, pluginRoot, archetype });
-    if (contract.status === 'error') fail(contract.reason);
+    if (contract.status === 'error') fail(contract.reason, contract.message);
     if (contract.status === 'private' && !contract.selected && !hasUnselectedFastLock(repoRoot)) fail(contract.reason);
     const before = new Set();
     for (const name of pluginRuleTargets(pluginRoot)) {

package/scripts/lib/blocked-commands-policy.mjs

@@ -198,6 +198,46 @@ export function mergePolicies(floor, overlay) {
   return { rules: merged, warnings };
 }
 
+// ---------------------------------------------------------------------------
+// Wave-manifest projection
+// ---------------------------------------------------------------------------
+
+/**
+ * The patterns a wave manifest's `blockedCommands` may carry (#1509): the
+ * `pattern` of every `severity: 'block'` rule that has NO `type`.
+ *
+ * A TYPED rule's `pattern` is not a command pattern. `redirect-truncate` rules
+ * carry `pattern: ">"` and `path-delete` rules a free-text label; both are
+ * decided by their TARGET, type-aware, in hooks/pre-bash-destructive-guard.mjs.
+ * `hooks/enforce-commands.mjs` reads every `blockedCommands` entry as a command
+ * pattern, so the flattened `">"` denied interpreter payloads such as
+ * `bash -c "echo hi > /tmp/x"` (measured 2026-10-03 @ 8292050e). An untyped
+ * rule is the one class whose pattern means the same thing to both hooks.
+ *
+ * An UNKNOWN `type` is excluded as well: its pattern's meaning is unknown, and
+ * the destructive guard still evaluates the rule on every Bash call, so leaving
+ * it out of the manifest drops no protection — admitting it repeats #1509 for
+ * the next rule type.
+ *
+ * Total: a non-array `rules` (e.g. `loadEffectivePolicy()`'s `null`) yields `[]`.
+ *
+ * @param {unknown} rules - the `rules` of {@link loadEffectivePolicy}
+ * @returns {string[]}
+ */
+export function blockedCommandPatterns(rules) {
+  if (!Array.isArray(rules)) return [];
+  return rules
+    .filter(
+      (r) =>
+        r !== null &&
+        typeof r === 'object' &&
+        r.severity === 'block' &&
+        (r.type ?? null) === null &&
+        typeof r.pattern === 'string',
+    )
+    .map((r) => r.pattern);
+}
+
 // ---------------------------------------------------------------------------
 // Load (with per-path mtime cache)
 // ---------------------------------------------------------------------------

package/scripts/lib/common.mjs

@@ -54,6 +54,47 @@ export function expandTilde(p) {
   return p;
 }
 
+/**
+ * Replace the current user's home directory with `~` wherever it occurs in
+ * `text` — the inverse of {@link expandTilde}, for free text as well as a bare
+ * path: an `err.message` from `node:fs` (`ENOENT: …, open '/Users/bob/v/x.md'`),
+ * git stderr, a resolved vault dir. Every occurrence is replaced.
+ *
+ * Log lines of the vault writers and the session-end shell land in CI logs and
+ * session transcripts, where the home dir is an owner-privacy leak (#1490,
+ * `.claude/rules/security.md` § Owner-Privacy).
+ *
+ * Boundary-aware on both sides. On the right the home dir must end at a path
+ * separator, the end of the text, whitespace, a quote/bracket/list delimiter
+ * (`'"\`)]},;:`) or a sentence-final `.`, so `/Users/bob` never rewrites
+ * `/Users/bobby/x` or `/Users/bob.old`. On the left it must not continue a
+ * path segment, so `/data/Users/bob` stays. A home dir that is empty, the
+ * filesystem root or a bare drive root is a no-op — collapsing it would
+ * rewrite every absolute path. Non-strings pass through unchanged.
+ *
+ * @param {string} text
+ * @param {string} [home] — defaults to `os.homedir()`; an unresolvable home
+ *   leaves `text` unchanged (a log redactor must never turn an error path into
+ *   a crash)
+ * @returns {string}
+ */
+export function redactHomeDir(text, home) {
+  if (typeof text !== 'string' || text.length === 0) return text;
+  let h = home;
+  if (h === undefined) {
+    try {
+      h = os.homedir();
+    } catch {
+      return text;
+    }
+  }
+  h = String(h ?? '').replace(/[/\\]+$/, '');
+  if (h.length === 0 || /^[a-z]:$/i.test(h)) return text;
+  const escaped = h.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`(?<![\\w.~-])${escaped}(?=$|[/\\\\\\s'"\`)\\]},;:]|\\.(?:$|\\s))`, 'g');
+  return text.replace(re, '~');
+}
+
 // ---------------------------------------------------------------------------
 // Timestamp helpers
 // ---------------------------------------------------------------------------