session-orchestrator 4.1.0 → 5.0.0

package/scripts/lib/reconcile/writer.mjs

@@ -11,6 +11,9 @@
  * Responsibilities:
  *  - Acquire a per-write file lock (`.orchestrator/rules.lock`) to serialise
  *    concurrent writers — mirrors PSA-005 (withStateMdLock) pattern.
+ *  - Before any write: project the instruction budget after the batch and
+ *    refuse the WHOLE batch (nothing written, nothing stamped) when it would
+ *    breach a ceiling — see `budgetPreflight`.
  *  - For each approved proposal: path-safety guard → STRUCTURAL content gate
  *    (#1015, see {@link frontmatterRefusalReason}) → mkdirSync → atomic
  *    tmp+rename write → stamp the idempotency sidecar terminal via
@@ -54,8 +57,20 @@
  * @module reconcile/writer
  */
 
-import { mkdirSync, writeFileSync, renameSync, appendFileSync, realpathSync, statSync } from 'node:fs';
+import {
+  mkdirSync,
+  mkdtempSync,
+  writeFileSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  appendFileSync,
+  realpathSync,
+  rmSync,
+  statSync,
+} from 'node:fs';
 import { randomBytes } from 'node:crypto';
+import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import { withFileLock } from '../file-lock.mjs';
@@ -490,6 +505,228 @@ function isOperatorRejection(item) {
   return typeof item.content === 'string' && item.content.length > 0;
 }
 
+// ---------------------------------------------------------------------------
+// Instruction-budget pre-flight (#1316 follow-up)
+// ---------------------------------------------------------------------------
+
+/** Refusal reason returned when the projected corpus would breach a ceiling. */
+export const BUDGET_REFUSAL_REASON = 'instruction-budget-exceeded';
+
+const BUDGET_HINT =
+  'absorb the approved rule(s) into an existing thematic file under .claude/rules/ ' +
+  '(N provenance pairs in ONE file, globs:/paths: mirrored — docs/rule-authoring.md § Consolidated rules) ' +
+  'and re-run; never raise the ceiling';
+
+/**
+ * @typedef {Object} BudgetRefusal
+ * @property {string} reason    - always {@link BUDGET_REFUSAL_REASON}.
+ * @property {'path-scoped-bytes'|'generated-bytes'|'always-on-bytes'|'directives'} axis
+ * @property {number} current   - the axis value before the write.
+ * @property {number} projected - the axis value after the write.
+ * @property {number} ceiling   - the ceiling the projection breaches.
+ * @property {string} hint
+ */
+
+/**
+ * Project the instruction budget AFTER the pending repo-local writes and refuse
+ * the whole batch if the projection would breach a ceiling.
+ *
+ * WHY A PROJECTION AND NOT WRITE-THEN-ROLLBACK: a rollback has to undo rule
+ * files AND sidecar stamps, and a half-failed rollback is worse than the breach.
+ * Refusing before the first byte lands keeps the failure clean.
+ *
+ * HOW: the guard's own `computeInstructionBudget` runs twice — on the live rules
+ * directory, and on a throwaway overlay (a copy of that directory with the
+ * pending contents written over it). Re-running the guard's code rather than
+ * re-deriving its byte count means the projection cannot disagree with the
+ * verdict: same frontmatter stripping, same `globs:`/provenance predicates,
+ * all four axes, and an update of an existing file lands as its delta by
+ * construction. Ceilings follow `checkInstructionBudget`'s precedence
+ * (Session Config `instruction-budget.*` > module default), and
+ * `enabled: false` / `mode: off` skips the pre-flight — the operator opted out
+ * of the guard.
+ *
+ * REFUSE ONLY WHAT THIS WRITE WORSENS: an axis blocks the batch only when it is
+ * over in the projection AND the write grows it. A corpus that is already over
+ * therefore still accepts a shrinking consolidation — the remedy must never be
+ * blocked by the breach it repairs — and an unrelated pre-existing breach (say,
+ * the hand-authored always-on directive count) does not freeze reconcile.
+ *
+ * CEILING (BV-004): this is a projection of THIS batch against the corpus as it
+ * stands inside the rules lock. It does not cover rule edits made by hand or by
+ * any writer that does not take `.orchestrator/rules.lock`, and it projects
+ * with the Session Config ceilings while `tests/rules/receiving-review.test.mjs`
+ * asserts against the module defaults — so a repo that RAISES its ceiling in
+ * config can pass here and still go red there; that live test stays the second
+ * safety net. It also fails OPEN (one `errors[]` warning, then the write
+ * proceeds) when the guard cannot load or the overlay cannot be built,
+ * because blocking every reconcile write on a broken measurement is the larger
+ * harm. Revisit if a second writer of `.claude/rules/` appears, or if a repo
+ * ever carries a config ceiling above the module default.
+ *
+ * @param {Object} ctx
+ * @param {WriterApprovedItem[]} ctx.approvedItems
+ * @param {PreparedTarget|undefined} ctx.prep - the prepared `repo-local` target.
+ * @param {{repoRoot?: string, baselineRoot?: string}} ctx.roots
+ * @param {string} ctx.repoRoot
+ * @param {string[]} ctx.errors - receives fail-open warnings.
+ * @returns {Promise<BudgetRefusal|null>} null ⇒ proceed with the writes.
+ */
+async function budgetPreflight({ approvedItems, prep, roots, repoRoot, errors }) {
+  if (!prep || !prep.ok) return null;
+
+  // Only what the write loop below would actually put on disk counts: the same
+  // content-type check, structural gate and destination resolution. Errors from
+  // this dry resolution go to a throwaway sink — the write loop reports them.
+  /** @type {Array<{rel: string, content: string}>} */
+  const pending = [];
+  for (const item of approvedItems) {
+    if (!item || typeof item.content !== 'string') continue;
+    if (frontmatterRefusalReason(item.content) !== null) continue;
+    const dest = resolveDest(item, 'repo-local', prep, roots, []);
+    if (dest === null) continue;
+    pending.push({ rel: path.relative(prep.dir, dest), content: item.content });
+  }
+  if (pending.length === 0) return null;
+
+  let overlay = null;
+  try {
+    // Dynamic import keeps the guard out of this module's static graph.
+    const guard = await import('../instruction-budget-guard.mjs');
+    const cfg = guard.loadInstructionBudgetConfig(repoRoot);
+    if (!cfg.enabled || cfg.mode === 'off') return null;
+    // computeInstructionBudget falls back to its module default for any
+    // non-number, so an absent optional key needs no special case here.
+    const ceilings = {
+      ceiling: cfg.ceiling,
+      byteCeiling: cfg['byte-ceiling'],
+      generatedByteCeiling: cfg['generated-byte-ceiling'],
+      pathScopedByteCeiling: cfg['path-scoped-byte-ceiling'],
+    };
+
+    const current = guard.computeInstructionBudget({ repoRoot, rulesDir: prep.dir, ...ceilings });
+
+    overlay = mkdtempSync(path.join(tmpdir(), 'reconcile-budget-'));
+    // The guard reads the rules directory flat (`readdirSync`, `.md` only).
+    for (const name of readdirSync(prep.dir)) {
+      if (!name.endsWith('.md')) continue;
+      try {
+        writeFileSync(path.join(overlay, name), readFileSync(path.join(prep.dir, name), 'utf8'), 'utf8');
+      } catch {
+        /* unreadable or a directory — the guard skips it too */
+      }
+    }
+    for (const { rel, content } of pending) {
+      const dest = path.join(overlay, rel);
+      mkdirSync(path.dirname(dest), { recursive: true });
+      writeFileSync(dest, content, 'utf8');
+    }
+
+    const projected = guard.computeInstructionBudget({ repoRoot, rulesDir: overlay, ...ceilings });
+
+    const axes = [
+      ['path-scoped-bytes', current.bySurface.pathScoped.bytes, projected.bySurface.pathScoped.bytes, projected.pathScopedByteCeiling, projected.overPathScopedBudget],
+      ['generated-bytes', current.bySurface.generated.bytes, projected.bySurface.generated.bytes, projected.generatedByteCeiling, projected.overGeneratedBudget],
+      ['always-on-bytes', current.totalBytes, projected.totalBytes, projected.byteCeiling, projected.overByteBudget],
+      ['directives', current.totalDirectives, projected.totalDirectives, projected.ceiling, projected.overDirectiveBudget],
+    ];
+    for (const [axis, cur, proj, ceiling, over] of axes) {
+      if (over && proj > cur) {
+        return { reason: BUDGET_REFUSAL_REASON, axis, current: cur, projected: proj, ceiling, hint: BUDGET_HINT };
+      }
+    }
+    return null;
+  } catch (err) {
+    const msg = err && err.message ? err.message : String(err);
+    errors.push(`instruction-budget pre-flight could not run (${msg}) — writes proceed unchecked (fail-open)`);
+    return null;
+  } finally {
+    if (overlay !== null) {
+      try {
+        rmSync(overlay, { recursive: true, force: true });
+      } catch {
+        /* a leftover tmp dir is harmless */
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Telemetry (#1307)
+// ---------------------------------------------------------------------------
+
+/**
+ * Ledger name of the rule-write event (issue #1307).
+ *
+ * WHY A SECOND EVENT AND NOT A FIELD ON `orchestrator.reconcile.completed`:
+ * that event is emitted by the `runReconcile` wrapper — BEFORE the operator
+ * approval AUQ and before this module runs at all. A `dry_run: false` record
+ * therefore proves only that the engine ran and merged the candidate store; an
+ * operator who declined every proposal emits a byte-identical record to one who
+ * approved five. The emitter has to sit where the thing it proves happens, and
+ * that is here: after the write pass, in the one module that writes rule files.
+ *
+ * Emitting is NOT writing — the #693 FA2/FA3 brandmauer is untouched. This
+ * module remains the only writer of `.claude/rules/`, and every write it makes
+ * is still an operator-approved item handed in via `approved`.
+ */
+export const RULES_WRITTEN_EVENT = 'orchestrator.reconcile.rules_written';
+
+/**
+ * Record ONE rule-write pass in the repo's event ledger — best-effort.
+ *
+ * ZERO-WRITE IS EMITTED, DELIBERATELY. The alternative (emit only on a
+ * successful write) makes the maintenance loop unable to separate three
+ * materially different outcomes that would all produce NO record: the operator
+ * declined every proposal, every write was REFUSED by a guard (path-safety,
+ * the #1015 content gate, a missing baseline root), and the writer was never
+ * reached at all. `.claude/rules/host-resources.md` § HR-105 is explicit that a
+ * rule whose firing you cannot falsify is not a rule, and the sibling event's
+ * own docs row states the same convention in one line: *"`dry_run` is the
+ * discriminator, not the event's absence"*. So the discriminator here is a
+ * FIELD — `rules_written` against `approved_proposals` — never the absence of a
+ * record. The one case that emits nothing is the caller's true no-op (neither
+ * an approved nor a rejected item), which returns before the lock is taken.
+ *
+ * NEVER THROWS, and never propagates: `emitEvent` throws `EventValidationError`
+ * on a malformed record, and `writeApprovedRules`'s never-throws contract is
+ * older and more load-bearing than this telemetry. A failed emit degrades to a
+ * stderr WARN and the write result is returned unchanged.
+ *
+ * @param {WriteApprovedRulesResult} result
+ * @param {{repoRoot?: string, targets: string[], approvedCount: number}} ctx
+ * @returns {Promise<void>}
+ */
+async function emitRulesWritten(result, ctx) {
+  const { repoRoot } = ctx;
+  // Same refusal as `emitReconcileCompleted` (#1119): with no repoRoot the
+  // ambient `SO_PROJECT_DIR` would receive synthetic records on every test run.
+  if (typeof repoRoot !== 'string' || repoRoot.trim() === '') return;
+
+  /** @type {Record<string, unknown>} */
+  const payload = {
+    rules_written: result.written,
+    approved_proposals: ctx.approvedCount,
+    rejected_archived: result.archived,
+    write_errors: result.errors.length,
+  };
+  // Allowlisted to the CLOSED {@link TARGET_DIRS} key set before entering the
+  // ledger — `targets` originates in operator-authored Session Config and is
+  // unbounded there, so an unknown value is untrusted text, never a
+  // measurement. Same treatment as `buildReconcilePayload`'s `targets`.
+  const known = Object.keys(TARGET_DIRS);
+  const targets = ctx.targets.filter((t) => known.includes(t));
+  if (targets.length > 0) payload.targets = targets;
+
+  try {
+    const { emitEvent } = await import('../events.mjs');
+    await emitEvent(RULES_WRITTEN_EVENT, payload, { repoRoot });
+  } catch (err) {
+    const msg = err && err.message ? err.message : String(err);
+    process.stderr.write(`reconcile-writer: ${RULES_WRITTEN_EVENT} emit failed (non-fatal): ${msg}\n`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -532,6 +769,12 @@ function isOperatorRejection(item) {
  * @property {number}   written   - number of rule files successfully written.
  * @property {number}   archived  - number of rejected records appended to the log.
  * @property {string[]} errors    - per-item error strings (never fatal).
+ *
+ * On an instruction-budget refusal (see `budgetPreflight`) the same object also
+ * carries `ok: false` plus every {@link BudgetRefusal} field, `written` and
+ * `archived` are 0, and `errors[]` holds one line naming the axis and the hint —
+ * so a caller that only surfaces `errors[]` still shows the refusal. The success
+ * shape carries no `ok` key.
  */
 
 /**
@@ -618,6 +861,24 @@ export async function writeApprovedRules({
         }
       }
 
+      // Instruction-budget pre-flight — before the first write, inside the
+      // lock so no concurrent reconcile writer moves the corpus between the
+      // projection and the write. A refusal writes NOTHING: no rule file, no
+      // rejected-log line, no sidecar stamp (approved or rejected).
+      const budgetRefusal = await budgetPreflight({
+        approvedItems,
+        prep: prepared.get('repo-local'),
+        roots,
+        repoRoot,
+        errors,
+      });
+      if (budgetRefusal !== null) {
+        errors.push(
+          `${budgetRefusal.reason}: ${budgetRefusal.axis} would go ${budgetRefusal.current} → ${budgetRefusal.projected} (ceiling ${budgetRefusal.ceiling}) — nothing written, no candidate marked processed; ${budgetRefusal.hint}`,
+        );
+        return { written: 0, archived: 0, errors, ok: false, ...budgetRefusal };
+      }
+
       // ── Step 1: write approved rule files ──────────────────────────────────
       for (const item of approvedItems) {
         // Item-level guards run ONCE, before any target loop: content is a
@@ -765,15 +1026,21 @@ export async function writeApprovedRules({
     { timeoutMs: 10000 },
   );
 
-  // If lock acquisition failed, return a zeroed result with the lock error.
-  if (lockResult.ok === false) {
-    return {
-      written: 0,
-      archived: 0,
-      errors: [`lock-${lockResult.reason ?? 'unknown'}`],
-    };
-  }
+  // One emit for BOTH return points (#1307). A lock-acquisition failure is a
+  // zero-write pass like any other and is recorded as one — its `write_errors: 1`
+  // plus a non-zero `approved_proposals` is exactly the shape an operator needs
+  // to see, and an emit placed on the success path alone would drop it silently.
+  const result =
+    lockResult.ok === false
+      ? { written: 0, archived: 0, errors: [`lock-${lockResult.reason ?? 'unknown'}`] }
+      : // Unwrap the result returned from inside the lock body.
+        lockResult.value;
+
+  await emitRulesWritten(result, {
+    repoRoot,
+    targets: effectiveTargets,
+    approvedCount: approvedItems.length,
+  });
 
-  // Unwrap the result returned from inside the lock body.
-  return lockResult.value;
+  return result;
 }

package/scripts/lib/resource-probe/evaluate.mjs

@@ -61,6 +61,14 @@
  * of starts is a broken instrument to be re-aimed, not a policy to obey.
  */
 
+// `session-shape.mjs` is the ONE exported `agents-per-wave` resolver; this
+// module used to carry a private third copy. Import-graph note (this file is
+// hook-reachable via `hooks/_lib/hook-import-set.json`): `session-shape.mjs`
+// statically imports only `session-schema/constants.mjs`, a pure-data leaf, and
+// defers `events.mjs` to a lazy `await import()` — so nothing runs at module
+// load here that did not run before.
+import { resolveAgentCap } from '../session-shape.mjs';
+
 // ---------------------------------------------------------------------------
 // Verdict precedence helper
 // ---------------------------------------------------------------------------
@@ -252,29 +260,19 @@ function concurrencySignal(snapshot, concWarn) {
 }
 
 /**
- * Resolve an `agentsPerWave` option value into a plain numeric cap, or `null`
- * when no cap should apply. Mirrors `resolveApwCap()` in
- * `../wave-resource-gate.mjs` — kept as a local pure helper here rather than
- * a cross-module import since both sites are ≤10 lines and evolve
- * independently per their own gate's options shape.
+ * The session type this module resolves `agents-per-wave` FOR: none.
  *
- * `evaluate()` has no session-mode input in scope, so the object shape
- * resolves to `cap.default` — the documented HR-003 convention writes the
- * override as `<default> (mode: <higher-ceiling>)`, i.e. `default` is the
- * MORE restrictive of the pair, so this can only under-apply a looser
- * mode-specific ceiling, never let a heavy repo exceed its base cap.
+ * `evaluate()` has no session-mode input in scope, so it deliberately asks
+ * `resolveAgentCap` for no type and takes the `.default` fallback. The HR-003
+ * convention writes the override as `<default> (mode: <higher-ceiling>)`, i.e.
+ * `default` is the MORE restrictive of the pair — under-applying a looser
+ * mode-specific ceiling is safe, while passing a guessed `'deep'` here would
+ * silently RAISE a heavy repo's ceiling to the deep override on a loaded host.
+ * Naming the absence is what keeps that from being written by accident.
  *
- * @param {number|{default: number, [mode: string]: number}|*} cap
- * @returns {number|null}
+ * @type {undefined}
  */
-function resolveAgentsPerWaveCap(cap) {
-  if (typeof cap === 'number') return Number.isFinite(cap) ? cap : null;
-  if (cap !== null && typeof cap === 'object' && !Array.isArray(cap)) {
-    const def = cap.default;
-    return typeof def === 'number' && Number.isFinite(def) ? def : null;
-  }
-  return null;
-}
+const MODE_BLIND_SESSION_TYPE = undefined;
 
 /**
  * Evaluate a snapshot against `resource-thresholds` (from Session Config #166)
@@ -423,7 +421,7 @@ export function evaluate(snapshot, thresholds, options = {}) {
   // the live-probe signals already computed.
   // ---------------------------------------------------------------------------
   const { heavyRepo, agentsPerWave } = options;
-  const resolvedApwCap = resolveAgentsPerWaveCap(agentsPerWave);
+  const resolvedApwCap = resolveAgentCap(agentsPerWave, MODE_BLIND_SESSION_TYPE);
   if (heavyRepo === true && resolvedApwCap !== null) {
     cap = cap === null ? resolvedApwCap : Math.min(cap, resolvedApwCap);
   }

package/scripts/lib/rules-sync.mjs

@@ -121,7 +121,7 @@ function listManifestCategories(indexContent) {
  * @param {string|null} explicitArchetype
  * @returns {{archetype: string|null, known: boolean}}
  */
-function resolveArchetype(repoRoot, explicitArchetype) {
+export function resolveArchetype(repoRoot, explicitArchetype) {
   if (explicitArchetype) {
     return { archetype: explicitArchetype.trim().toLowerCase(), known: true };
   }
@@ -194,6 +194,12 @@ function escapeRegex(s) {
  * at least one concrete bullet entry. This keeps `/bootstrap --sync-rules`
  * ready for future opt-in categories without requiring CLI changes.
  *
+ * `requiredBasenames` optionally adds explicitly required manifest entries,
+ * regardless of category or archetype scope. The caller supplies this data;
+ * this synchronous writer performs no external lookup. Every requested name
+ * must resolve uniquely in the full manifest before ANY file is written.
+ * Source validation, provenance, local overrides and dry-run still apply.
+ *
  * Vendoring sanitizer (issue #1098): every source file that reaches the write
  * decision is additionally scanned by `scanVendoringLeaks()`, and its findings
  * are collected into the additive `sanitizer[]` array. This runs in
@@ -214,7 +220,8 @@ function escapeRegex(s) {
  *   dryRun?: boolean,
  *   validate?: boolean,
  *   requireProvenance?: boolean,
- *   archetype?: string|null
+ *   archetype?: string|null,
+ *   requiredBasenames?: string[]|null
  * }} opts
  * @returns {{
  *   written: string[],
@@ -233,6 +240,7 @@ export function syncRules({
   validate = true,
   requireProvenance = true,
   archetype = null,
+  requiredBasenames = null,
 } = {}) {
   const written = [];
   const skipped = [];
@@ -268,13 +276,35 @@ export function syncRules({
     ? categories
     : listManifestCategories(indexContent);
   const entries = parseIndex(indexContent, selectedCategories);
+  const fullManifest = parseIndex(indexContent, listManifestCategories(indexContent));
+  const required = new Set();
+  if (requiredBasenames !== null) {
+    if (!Array.isArray(requiredBasenames)) {
+      errors.push({ file: '_index.md', reason: 'requiredBasenames must be an array of unique manifest basenames' });
+    } else {
+      for (const name of requiredBasenames) {
+        if (typeof name !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.-]*\.md$/.test(name) || required.has(name)) {
+          errors.push({ file: '_index.md', reason: 'invalid or duplicate required basename' });
+          continue;
+        }
+        required.add(name);
+        const matching = fullManifest.filter((entry) => basename(entry.relPath) === name);
+        if (matching.length !== 1) {
+          errors.push({ file: name, reason: 'required basename must resolve uniquely in _index.md' });
+        } else if (!entries.some((entry) => entry.relPath === matching[0].relPath)) {
+          entries.push(matching[0]);
+        }
+      }
+    }
+    if (errors.length > 0) return { written, skipped, preserved, errors, warnings, sanitizer };
+  }
 
   // Resolvability for the See-Also sanitizer is judged against the FULL
   // manifest, not `selectedCategories`: an archetype-scoped rule is a
   // legitimate citation target in every repo whose archetype matches, so
   // narrowing this to the current selection would report false leaks.
   const manifestBasenames = new Set(
-    parseIndex(indexContent, listManifestCategories(indexContent)).map((e) => basename(e.relPath)),
+    fullManifest.map((e) => basename(e.relPath)),
   );
 
   if (entries.length === 0) {
@@ -297,7 +327,7 @@ export function syncRules({
 
     // Archetype filter (issue #722 Epic A Wave 3) — evaluated before any
     // file IO, so a skip never triggers a spurious "source file not found".
-    if (archetypes !== null) {
+    if (archetypes !== null && !required.has(basename(relPath))) {
       if (!resolvedArchetype.known) {
         skipped.push({ file: relPath, reason: 'archetype-unknown' });
         continue;