@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-core/src/slice/inputs.mjs

@@ -0,0 +1,174 @@
+// slice — input loading.
+//
+// Reads the inputs the slice generator needs:
+//   - profile.md (required) — the operator's full profile (source of truth).
+//   - learned-rules.md (optional) — operational rules from corrections.
+//   - observations dir (optional) — a directory of recent observation .md files.
+//
+// Pure I/O + assembly; no spawning, no API calls. The assembled output is a
+// single string with stable section headers that the prompt's {{INPUTS}}
+// placeholder is replaced with.
+//
+// Observation filtering: we don't trust the caller to have already filtered
+// to "recent". We accept an optional `recentDays` window and keep only files
+// whose mtime is within that window. Files under `_archive/` (any case,
+// any prefix) are skipped — those are post-distillation archives and are
+// not recent signal.
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
+/**
+ * Load all slice inputs and assemble them into a single inputs string ready
+ * to be substituted into the prompt template's {{INPUTS}} placeholder.
+ *
+ * @param {object} opts
+ * @param {string} opts.profilePath       Path to profile.md (required).
+ * @param {string} [opts.learnedRulesPath] Path to learned-rules.md (optional).
+ * @param {string} [opts.observationsDir]  Path to a directory of observation .md files (optional).
+ * @param {number} [opts.recentDays=21]    Window in days for filtering observations by mtime.
+ * @param {() => Date} [opts.now]          Injectable clock for tests.
+ * @returns {Promise<{
+ *   text: string,
+ *   profileBytes: number,
+ *   profileLines: number,
+ *   learnedRulesBytes: number,
+ *   observationsBytes: number,
+ *   observationsCount: number,
+ * }>}
+ */
+export async function loadInputs({
+  profilePath,
+  learnedRulesPath,
+  observationsDir,
+  recentDays = 21,
+  now = () => new Date(),
+} = {}) {
+  if (!profilePath) {
+    const err = new Error('loadInputs: profilePath is required');
+    err.sliceExitCode = 1;
+    throw err;
+  }
+
+  let profile;
+  try {
+    profile = await readFile(profilePath, 'utf8');
+  } catch (err) {
+    const e = new Error(`failed to read profile at ${profilePath}: ${err.message}`);
+    e.sliceExitCode = 2;
+    throw e;
+  }
+  const profileBytes = Buffer.byteLength(profile, 'utf8');
+  const profileLines = profile.split('\n').length;
+
+  let learnedRules = null;
+  let learnedRulesBytes = 0;
+  if (learnedRulesPath) {
+    try {
+      learnedRules = await readFile(learnedRulesPath, 'utf8');
+      learnedRulesBytes = Buffer.byteLength(learnedRules, 'utf8');
+    } catch (err) {
+      const e = new Error(`failed to read learned-rules at ${learnedRulesPath}: ${err.message}`);
+      e.sliceExitCode = 2;
+      throw e;
+    }
+  }
+
+  let observationsText = null;
+  let observationsBytes = 0;
+  let observationsCount = 0;
+  if (observationsDir) {
+    const result = await loadRecentObservations({ dir: observationsDir, recentDays, now });
+    observationsText = result.text;
+    observationsBytes = result.bytes;
+    observationsCount = result.count;
+  }
+
+  // Assemble.
+  const parts = [
+    '## INPUT 1 — OPERATOR PROFILE (authoritative, source of truth)',
+    '',
+    profile.trim(),
+  ];
+  if (learnedRules) {
+    parts.push(
+      '',
+      '## INPUT 2 — LEARNED RULES (operational rules from corrections)',
+      '',
+      learnedRules.trim(),
+    );
+  }
+  if (observationsText) {
+    parts.push(
+      '',
+      `## INPUT 3 — RECENT OBSERVATIONS (raw, last ${recentDays} days, synthesise — do not quote)`,
+      '',
+      observationsText.trim(),
+    );
+  }
+  const text = parts.join('\n') + '\n';
+
+  return {
+    text,
+    profileBytes,
+    profileLines,
+    learnedRulesBytes,
+    observationsBytes,
+    observationsCount,
+  };
+}
+
+/**
+ * Walk an observations directory, keep .md files modified within
+ * `recentDays`, exclude anything under an `_archive`/`_archived` subtree.
+ * Returns a concatenated string with one section per file, prefixed by
+ * the filename for traceability.
+ */
+export async function loadRecentObservations({ dir, recentDays = 21, now = () => new Date() }) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT' || err.code === 'ENOTDIR') {
+      return { text: null, bytes: 0, count: 0 };
+    }
+    throw err;
+  }
+
+  const cutoffMs = now().getTime() - recentDays * 24 * 60 * 60 * 1000;
+  const files = [];
+  for (const e of entries) {
+    if (!e.isFile()) continue;
+    if (!e.name.endsWith('.md')) continue;
+    if (e.name.startsWith('_')) continue; // _archive.md and friends
+    const full = join(dir, e.name);
+    let s;
+    try {
+      s = await stat(full);
+    } catch {
+      continue;
+    }
+    if (s.mtimeMs < cutoffMs) continue;
+    files.push({ path: full, name: e.name, mtime: s.mtimeMs });
+  }
+  // Newest first — for the prompt this helps recency-bias the synthesis.
+  files.sort((a, b) => b.mtime - a.mtime);
+
+  const sections = [];
+  let bytes = 0;
+  for (const f of files) {
+    let content;
+    try {
+      content = await readFile(f.path, 'utf8');
+    } catch {
+      continue;
+    }
+    const section = `### ${basename(f.name)}\n\n${content.trim()}\n`;
+    sections.push(section);
+    bytes += Buffer.byteLength(content, 'utf8');
+  }
+  if (sections.length === 0) {
+    return { text: null, bytes: 0, count: 0 };
+  }
+  return { text: sections.join('\n'), bytes, count: sections.length };
+}

package/dist/engineering-pa-core/src/slice/prompt.mjs

@@ -0,0 +1,94 @@
+// slice — prompt assembly.
+//
+// Loads a prompt template by name (e.g. "dave-boot" → `prompts/dave-boot.md`),
+// substitutes the {{INPUTS}} placeholder with the assembled inputs string,
+// and returns the final prompt text. Pure string + I/O — no Claude calls,
+// no spawning.
+
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Resolve a slice prompt template path.
+ *
+ *  - If `nameOrPath` looks like a path (contains a separator or `.md`), it is
+ *    used as-is (resolved to absolute if relative).
+ *  - Otherwise it is treated as a template name and resolved against the
+ *    bundled `prompts/` directory.
+ *
+ * @param {string} nameOrPath
+ * @returns {string} absolute path
+ */
+export function resolveTemplatePath(nameOrPath) {
+  if (!nameOrPath || typeof nameOrPath !== 'string') {
+    throw new Error('resolveTemplatePath: nameOrPath is required');
+  }
+  if (nameOrPath.endsWith('.md') || nameOrPath.includes('/') || nameOrPath.includes('\\')) {
+    return isAbsolute(nameOrPath) ? nameOrPath : resolve(process.cwd(), nameOrPath);
+  }
+  return resolve(__dirname, 'prompts', `${nameOrPath}.md`);
+}
+
+/**
+ * Load a prompt template and substitute the {{INPUTS}} placeholder.
+ *
+ * @param {object} opts
+ * @param {string} opts.template      Template name or path.
+ * @param {string} opts.inputs        Inputs string to substitute.
+ * @returns {Promise<string>}         Final prompt text.
+ */
+export async function buildSlicePrompt({ template, inputs } = {}) {
+  if (!template) throw new Error('buildSlicePrompt: template is required');
+  if (inputs === undefined || inputs === null) {
+    throw new Error('buildSlicePrompt: inputs is required');
+  }
+  const path = resolveTemplatePath(template);
+  let tpl;
+  try {
+    tpl = await readFile(path, 'utf8');
+  } catch (err) {
+    const e = new Error(`failed to read prompt template at ${path}: ${err.message}`);
+    e.sliceExitCode = 2;
+    throw e;
+  }
+  if (!tpl.includes('{{INPUTS}}')) {
+    const e = new Error(`prompt template at ${path} is missing the {{INPUTS}} placeholder`);
+    e.sliceExitCode = 2;
+    throw e;
+  }
+  return tpl.replace('{{INPUTS}}', inputs);
+}
+
+/**
+ * Argv for the `claude` CLI when running a slice generation.
+ *
+ * v0.1.5: the prompt is no longer passed as a positional CLI argument. On
+ * Linux execve() enforces a per-arg ARG_MAX (typically 128 KB on a single
+ * arg) — a slice prompt that includes observations routinely exceeds this
+ * and surfaces as `spawn E2BIG` (w-2026-05-18-016). We now pipe the prompt
+ * to claude via stdin; argv carries only flags. The runner's `spawn`
+ * supports `{ stdin }` already (see distill/runner.mjs), so the call-site
+ * change in run.mjs is local.
+ *
+ * The `prompt` parameter is accepted but ignored to keep callers that pass
+ * it (and existing tests) working. Callers MUST pass the prompt as
+ * `stdin` to runner.spawn — see run.mjs.
+ *
+ * @param {object} opts
+ * @param {string} opts.sessionName
+ * @param {string} [opts.prompt]   No longer placed in argv. Kept for API
+ *                                 back-compat; pass the prompt to spawn
+ *                                 via `{ stdin: prompt }`.
+ * @returns {string[]}
+ */
+export function claudeArgs({ sessionName }) {
+  return [
+    '--print',
+    '--permission-mode', 'bypassPermissions',
+    '--no-session-persistence',
+    '--name', sessionName,
+  ];
+}

package/dist/engineering-pa-core/src/slice/prompts/dave-boot.md

@@ -0,0 +1,91 @@
+You are operating as a compression assistant. Your job is to produce a compact "boot slice" of the operator's profile — a short markdown document that loads into the PA's context at every session start, in place of the full profile.
+
+The full profile is the source of truth. This slice is a fresh snapshot, regenerated periodically. Stale content in the slice is acceptable for ~24 hours.
+
+## What the slice is for
+
+When the PA boots, it needs to know — in roughly 1–2 KB of context — *who it is working for*. Not every preference, not every historical decision, not every technical opinion. Just enough that:
+
+- It addresses the operator correctly (name, register, tone).
+- It knows the operator's mission framing this year.
+- It knows what's in flight right now (active projects, active relationships).
+- It is aware of the tools and capabilities already built and available.
+- It avoids the highest-cost mistakes (5–10 most load-bearing recent corrections / rules).
+- It can read the rest of the profile or knowledge base when it needs detail.
+
+This is a navigation card, not the territory. **Prefer pointers to canonical sources over baked-in content** that will go stale between regenerations.
+
+## Inputs you have
+
+You are given:
+
+1. **The full operator profile** (`profile.md`) — the source of truth, ~18 KB.
+2. **Recent corrections / load-bearing rules** (optional, `learned-rules.md`) — ~50 KB of operational rules accumulated from corrections.
+3. **Recent observations** (optional) — a concatenated dump of raw observation files filed in the last 2–4 weeks, useful for "what's been on his mind lately" but not authoritative.
+
+Treat the profile as authoritative. Treat learned-rules as second-tier authoritative (they ARE rules). Treat observations as raw signal — synthesise, do not quote.
+
+## Output structure
+
+Produce a markdown document with exactly these seven sections, in this order:
+
+```
+# Operator Boot Slice -- <Operator Name>
+
+_Generated <ISO timestamp>. Refreshed periodically. Source of truth: operator/profile/profile.md._
+
+## Operator basics
+<3-5 bullets: name, what they go by, communication register, tone preferences, sensitivities>
+
+## Mission framing
+<1-2 lines: the north-star / what we're building toward this year>
+
+## Active projects
+<3-6 bullets, one line each: project name -- one-line status>
+
+## Active relationships
+<2-4 bullets, one line each: who -- relationship context>
+
+## Tools at your disposal
+<2-3 lines: a one-line summary of the HQ-built operator-extension tools you have available (look for evidence of these in the inputs — names like wsd-ingest, dispatch, svc, monitoring, scheduled cron tasks, etc.), followed by a pointer line to the canonical list:>
+For the canonical inventory of operator-built tools and scheduled tasks, read `operator/knowledge/systems/operator-tools.md`.
+
+## Load-bearing rules right now
+<5-10 bullets, one line each: most-cited or most-recent operational rules from learned-rules and the profile preferences section. Pick rules whose violation would be most costly>
+
+## Live state — fetch on boot
+For current project and work-item state, run: `pnpm exec desk overview`.
+Do not bake state into this slice — it will be wrong by the time it is read.
+```
+
+The last section is a **fixed instruction**, not generated content. Reproduce it verbatim. The whole point is to send the PA to the live tool for any state question rather than relying on a frozen snapshot.
+
+## Budget
+
+**Soft target: under 2 KB total output.** Aim for ~1.2–1.8 KB. If you can't fit a section in the budget, prefer fewer items over shorter items — better to give 3 sharp project lines than 6 mushy ones. Over-budget is warned but not blocked; under-information is more costly.
+
+## Style
+
+- No emojis (the operator has a strict no-emoji rule for persisted artefacts).
+- No em-dashes — use double-hyphens (`--`) instead.
+- Use the operator's own vocabulary where you can pull it cleanly from the profile.
+- Don't editorialise. State, don't sell.
+- "Operator" not "user". "PA" or the PA's name, not "the assistant".
+
+## What NOT to include
+
+- Technical opinions (the full Technical Opinions section of profile.md).
+- Historical decision patterns.
+- Communication-style examples that aren't load-bearing.
+- Anything the PA can look up at the moment it needs it (this is what the pointers are for).
+- A baked snapshot of project state — the Live-state section's pointer covers that.
+
+The test for "should this be in the slice": *if this is wrong or missing, will the PA make a costly mistake in its first 5 messages?* If yes, include it. If no, leave it out.
+
+## Now produce the slice
+
+The inputs follow below. Read them, then produce the slice. Output ONLY the slice markdown — no preamble, no postscript, no explanation. Your entire response is what gets written to disk.
+
+---
+
+{{INPUTS}}

package/dist/engineering-pa-core/src/slice/run.mjs

@@ -0,0 +1,334 @@
+// slice — orchestrator.
+//
+// Flow:
+//   1. Load inputs (profile + optional learned-rules + optional observations).
+//   2. Build the prompt (template + substituted inputs).
+//   3. Invoke `claude --print` via the shared runner.
+//   4. Validate the response (six required sections, size budget).
+//   5. Write the slice to the configured output path.
+//
+// Output is plain markdown — no front-matter, no JSON envelope. Validation is
+// soft on size (warn over budget, don't fail) and hard on structure (a
+// response missing required headers is a generator failure, not a stale
+// snapshot).
+//
+// Exit codes (§6 tooling standard):
+//   0 ok | 1 usage | 2 prerequisite/operational | 3 claude transport failure
+
+import { mkdir, writeFile, appendFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+import { loadInputs } from './inputs.mjs';
+import { buildSlicePrompt, claudeArgs } from './prompt.mjs';
+
+const REQUIRED_HEADERS = [
+  '## Operator basics',
+  '## Mission framing',
+  '## Active projects',
+  '## Active relationships',
+  '## Tools at your disposal',
+  '## Load-bearing rules right now',
+  '## Live state',
+];
+
+const SIZE_BUDGET_BYTES = 2048;
+
+function opError(msg, code = 2) {
+  const err = new Error(msg);
+  err.sliceExitCode = code;
+  return err;
+}
+
+function log(line, { stderr = process.stderr } = {}) {
+  stderr.write(`[slice] ${line}\n`);
+}
+
+/**
+ * Build a canonical audit record in stable field order. Required by the
+ * tasks-status consumer: ts (ISO-Z), status, exitCode. The status
+ * vocabulary is closed and matches the sibling tools (distill, wsd-ingest):
+ *   ok                    — slice generated, validated, written.
+ *   noop-dry-run          — dry-run path; no claude call, no write.
+ *   fail-usage            — caller-side input error (missing arg, bad path).
+ *   fail-validation       — claude returned content missing required headers.
+ *   fail-claude           — claude exited non-zero (transport failure).
+ *   fail-prereq           — input loading failed (missing profile / observations / template).
+ *   fail-write            — writing the slice output file failed.
+ *   fail-unexpected       — any other thrown exception (defensive catch-all
+ *                           so cron failures never disappear silently).
+ *
+ * `reason` is omitted on `ok`. `outputBytes` is null on paths that didn't
+ * produce a file.
+ */
+function buildAuditRecord({ ts, status, exitCode, durationSec, dryRun, outputBytes, reason }) {
+  const rec = {
+    ts,
+    status,
+    exitCode,
+    durationSec,
+    dryRun,
+    outputBytes,
+  };
+  if (reason !== undefined) rec.reason = reason;
+  return rec;
+}
+
+/**
+ * Append one audit record to runs.jsonl. Best-effort: a failed audit write
+ * must NOT change the slice's exit code (a lost audit line is less bad than
+ * a poll being misclassified as a transport failure). Mirrors the policy
+ * used by `distill`'s writeAudit.
+ *
+ * @param {string} runsLog
+ * @param {object} record
+ * @param {object} [opts]
+ * @param {object} [opts.stderr]
+ */
+export async function writeAudit(runsLog, record, { stderr = process.stderr } = {}) {
+  try {
+    await mkdir(dirname(runsLog), { recursive: true });
+    await appendFile(runsLog, JSON.stringify(record) + '\n');
+  } catch (e) {
+    log(`warning: failed to append audit record to ${runsLog}: ${e.message}`, { stderr });
+  }
+}
+
+/** ISO-Z timestamp at second precision; parseable by `new Date()`. */
+function tsNowIso(now = new Date()) {
+  return now.toISOString().replace(/\.\d+Z$/, 'Z');
+}
+
+/**
+ * Validate that the generated slice has the structural shape we asked for.
+ * Returns { ok: true } or { ok: false, missing: string[] }.
+ */
+export function validateSlice(text) {
+  const missing = REQUIRED_HEADERS.filter((h) => !text.includes(h));
+  if (missing.length > 0) return { ok: false, missing };
+  return { ok: true };
+}
+
+/**
+ * Compose a short session-name for the claude invocation. Filename-safe,
+ * UTC-compact, slice-prefixed.
+ */
+function sessionName(now) {
+  const d = now;
+  const pad = (n) => String(n).padStart(2, '0');
+  return (
+    `slice-${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}` +
+    `-${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}`
+  );
+}
+
+/**
+ * Run slice generation end-to-end.
+ *
+ * @param {object} opts
+ * @param {string} opts.profilePath
+ * @param {string} [opts.learnedRulesPath]
+ * @param {string} [opts.observationsDir]
+ * @param {string} opts.template          Template name (e.g. "dave-boot") or path.
+ * @param {string} opts.outputPath        Where to write the slice.
+ * @param {boolean} [opts.dryRun=false]   If true, build the prompt and report,
+ *                                        but skip the claude call and file write.
+ * @param {object} opts.runner            Shared runner (spawn/now/ts/tsIso).
+ * @param {object} [opts.stderr]          Capture stream for tests.
+ * @returns {Promise<number>}             Exit code.
+ */
+export async function runSlice({
+  profilePath,
+  learnedRulesPath,
+  observationsDir,
+  template,
+  outputPath,
+  runsLog,
+  dryRun = false,
+  runner,
+  stderr = process.stderr,
+} = {}) {
+  if (!runner) throw new Error('runSlice: runner is required');
+
+  // Capture invocation start FIRST so every exit path — including the
+  // early-validation throws below — emits a duration that reflects the
+  // whole pass, not just the claude call.
+  const startedAtMs = Date.now();
+  const overallDurationSec = () => Math.round((Date.now() - startedAtMs) / 1000);
+
+  // Audit helper. Only writes if --runs-log was passed; otherwise a no-op
+  // so unscheduled invocations (humans regenerating a slice by hand) don't
+  // accidentally pollute a freshness-monitor file.
+  //
+  // Best-effort: never throws — `writeAudit` swallows fs errors and the
+  // helper itself catches anything else (e.g. a runner.now bug). A lost
+  // audit line is less bad than masking the real exit code.
+  const emitAudit = async ({ status, exitCode, outputBytes = null, reason }) => {
+    if (!runsLog) return;
+    try {
+      await writeAudit(
+        runsLog,
+        buildAuditRecord({
+          ts: tsNowIso(runner.now ? runner.now() : new Date()),
+          status,
+          exitCode,
+          durationSec: overallDurationSec(),
+          dryRun,
+          outputBytes,
+          reason,
+        }),
+        { stderr },
+      );
+    } catch (e) {
+      log(`warning: emitAudit failed: ${e.message || e}`, { stderr });
+    }
+  };
+
+  // Defensive outer try/catch. Every cron-class tool must record one
+  // audit line per invocation (canonical contract). Without this catch,
+  // an exception in loadInputs (missing profile path), buildSlicePrompt
+  // (template not found), writeFile (permission denied), or the early
+  // arg-validation `opError`s below would propagate silently — leaving
+  // a runs.jsonl monitor seeing "no record" instead of a fail-status.
+  try {
+    // Early arg validation — separated from the !runner check above so we
+    // get an audit line even for misconfigured cron invocations.
+    if (!profilePath) throw opError('profilePath is required', 1);
+    if (!template) throw opError('template is required', 1);
+    if (!outputPath) throw opError('outputPath is required', 1);
+
+    // Step 1 — load inputs.
+    let inputsResult;
+    try {
+      inputsResult = await loadInputs({
+        profilePath,
+        learnedRulesPath,
+        observationsDir,
+        now: runner.now,
+      });
+    } catch (e) {
+      // Wrap so the outer catch can classify this as `fail-prereq` rather
+      // than the catch-all `fail-unexpected`. Preserve the original
+      // message so operators can diagnose without digging through
+      // stderr.
+      const wrapped = opError(`loadInputs: ${e.message || e}`, 2);
+      wrapped.sliceFailStatus = 'fail-prereq';
+      throw wrapped;
+    }
+    log(
+      `inputs: profile=${inputsResult.profileBytes}B (${inputsResult.profileLines} lines)` +
+        (learnedRulesPath ? `, learned-rules=${inputsResult.learnedRulesBytes}B` : '') +
+        (observationsDir
+          ? `, observations=${inputsResult.observationsCount} files / ${inputsResult.observationsBytes}B`
+          : ''),
+      { stderr },
+    );
+
+    // Step 2 — build prompt.
+    let prompt;
+    try {
+      prompt = await buildSlicePrompt({ template, inputs: inputsResult.text });
+    } catch (e) {
+      const wrapped = opError(`buildSlicePrompt: ${e.message || e}`, 2);
+      wrapped.sliceFailStatus = 'fail-prereq';
+      throw wrapped;
+    }
+    log(`prompt assembled: ${Buffer.byteLength(prompt, 'utf8')}B`, { stderr });
+
+    if (dryRun) {
+      log('DRY RUN — would invoke:', { stderr });
+      log(`  template:        ${template}`, { stderr });
+      log(`  output:          ${outputPath}`, { stderr });
+      log(`  session name:    ${sessionName(runner.now())}`, { stderr });
+      log('  command:         claude --print --permission-mode bypassPermissions \\', { stderr });
+      log('                     --no-session-persistence --name <session> <prompt>', { stderr });
+      await emitAudit({ status: 'noop-dry-run', exitCode: 0 });
+      return 0;
+    }
+
+    // Step 3 — invoke claude.
+    //
+    // v0.1.5: prompt piped via stdin (not argv). Slice prompts that include
+    // observations routinely exceed Linux's per-arg ARG_MAX limit (~128 KB);
+    // the legacy positional-arg shape surfaced as `spawn E2BIG` on Linux
+    // even when the prompt was a moderate 148 KB. Piping via stdin removes
+    // the limit entirely — the kernel's pipe buffer is the only ceiling and
+    // it streams.
+    const argv = claudeArgs({ sessionName: sessionName(runner.now()) });
+    log('invoking claude…', { stderr });
+    const start = Date.now();
+    const result = await runner.spawn('claude', argv, { stdin: prompt });
+    const durationSec = Math.round((Date.now() - start) / 1000);
+
+    if (result.code !== 0) {
+      log(`claude exited ${result.code} (${durationSec}s)`, { stderr });
+      if (result.stderr) log(`stderr: ${result.stderr.trim().slice(0, 500)}`, { stderr });
+      await emitAudit({
+        status: 'fail-claude',
+        exitCode: 3,
+        reason: `claude exited ${result.code}`,
+      });
+      return 3;
+    }
+    const sliceText = (result.stdout || '').trim() + '\n';
+    log(`claude ok (${durationSec}s) — produced ${Buffer.byteLength(sliceText, 'utf8')}B`, { stderr });
+
+    // Step 4 — validate.
+    const v = validateSlice(sliceText);
+    if (!v.ok) {
+      log(`generated slice missing required headers: ${v.missing.join(', ')}`, { stderr });
+      await emitAudit({
+        status: 'fail-validation',
+        exitCode: 2,
+        reason: `missing required headers: ${v.missing.join(', ')}`,
+      });
+      return 2;
+    }
+    const bytes = Buffer.byteLength(sliceText, 'utf8');
+    if (bytes > SIZE_BUDGET_BYTES) {
+      log(
+        `WARN: slice is ${bytes}B, exceeds soft budget of ${SIZE_BUDGET_BYTES}B — writing anyway`,
+        { stderr },
+      );
+    }
+
+    // Step 5 — write.
+    try {
+      await mkdir(dirname(outputPath), { recursive: true });
+      await writeFile(outputPath, sliceText, 'utf8');
+    } catch (e) {
+      const wrapped = opError(`writeFile ${outputPath}: ${e.message || e}`, 2);
+      wrapped.sliceFailStatus = 'fail-write';
+      throw wrapped;
+    }
+    log(`wrote slice to ${outputPath} (${bytes}B)`, { stderr });
+
+    await emitAudit({ status: 'ok', exitCode: 0, outputBytes: bytes });
+    return 0;
+  } catch (err) {
+    // Defensive catch-all. Emit an audit line, then re-throw so the CLI
+    // gets the same exit-code translation it already does (via main's
+    // try/catch on sliceExitCode). Without this, an unexpected throw in
+    // loadInputs / buildSlicePrompt / writeFile / etc. would produce a
+    // silent failure: cron logs it, but runs.jsonl has no record and
+    // the freshness monitor can't tell the difference between "tool
+    // exploded" and "tool was never invoked".
+    const exitCode = err?.sliceExitCode ?? 2;
+    // Status priority:
+    //   1. Specific `sliceFailStatus` set by a wrap-throw (fail-prereq,
+    //      fail-write).
+    //   2. `fail-usage` for exitCode 1 (caller-side: missing args).
+    //   3. `fail-unexpected` for everything else (defensive catch-all).
+    let status;
+    if (err?.sliceFailStatus) status = err.sliceFailStatus;
+    else if (exitCode === 1) status = 'fail-usage';
+    else status = 'fail-unexpected';
+    await emitAudit({
+      status,
+      exitCode,
+      reason: err?.message || String(err),
+    });
+    throw err;
+  }
+}
+
+export { REQUIRED_HEADERS, SIZE_BUDGET_BYTES };