@gobing-ai/spur 0.3.99 → 0.4.1

package/plugins/sp/scripts/commit-guard.ts

@@ -0,0 +1,249 @@
+#!/usr/bin/env bun
+/**
+ * commit-guard — refuse a driver commit that would sweep a *foreign* writer's working-tree changes
+ * (task 1129, feature H1). Incidents: `a94f9f431` (a batch pipeline commit swept another session's
+ * uncommitted files) and `36f274590` (a close-out commit swept two other tasks' files through
+ * `git add -A`). The runbooks already said "stage only what the batch wrote"; nothing enforced it.
+ *
+ * Read/write `.spur/run/<id>-tree-start.json`; stage only the listed paths this run wrote; report
+ * the ones it did not. "Written by this run" = "changed since base" (task-diffstat semantics) minus
+ * start-dirty paths whose content still matches the start snapshot — a path dirty at start and
+ * untouched by the run belongs to another writer. Exit codes: 0 = staged all requested · 2 = some
+ * refused as foreign · 3 = conflict or unmerged target (nothing staged) · 1 = mis-invocation, or a
+ * missing start snapshot (`start` first).
+ *
+ * `node:*` builtins and relative imports only (sp-plugin-standalone); `options.git` is the test
+ * seam; `.spur/` is excluded from both sets (run bookkeeping is not product work — task-diffstat).
+ *
+ * shortcut: a foreign edit to a path that was CLEAN at `start` is indistinguishable from this run's
+ * own write — git records content, not authorship — so it is caught only once it is dirty in the
+ * start snapshot. Upgrade path: a per-run write journal if that case ever recurs.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Base directory for the probes; `git` is the test seam (a fake runner instead of spawning). */
+export interface GuardOptions {
+    cwd?: string;
+    base?: string;
+    git?: GitRunner;
+}
+/** Minimal spawnable git surface — tests fake this to return canned probe output. */
+export interface GitRunResult {
+    status: number;
+    stdout: string;
+}
+export type GitRunner = (args: string[]) => GitRunResult;
+export interface TreeStart {
+    head: string;
+    /** Working-file blob hashes at start; `sha` is null when the path did not exist. */
+    dirty: Array<{ path: string; sha: string | null }>;
+}
+/** `exitCode` is what `main` returns: 0 all staged · 2 some refused · 3 conflict · 1 usage. */
+export type StageResult = { staged: string[]; foreign: string[]; exitCode: number };
+
+export const COMMIT_GUARD_USAGE =
+    'usage: commit-guard start --run <id> | stage --run <id> [--base <sha>] -- <paths…> | check --run <id>';
+
+/** Run bookkeeping is not product work — neither set may contain it (task-diffstat's rule). */
+function isBookkeeping(path: string): boolean {
+    return path === '.spur' || path.startsWith('.spur/');
+}
+/** Probe/artifact paths are repo-relative; `cwd` only anchors them for tests and callers. */
+function at(options: GuardOptions, rel: string): string {
+    return options.cwd ? join(options.cwd, rel) : rel;
+}
+function artifactPath(run: string): string {
+    return join('.spur', 'run', `${run}-tree-start.json`);
+}
+function gitOf(options: GuardOptions): GitRunner {
+    if (options.git) return options.git;
+    return (args: string[]): GitRunResult => {
+        const run = spawnSync('git', args, { cwd: options.cwd, encoding: 'utf8' });
+        return { status: run.status ?? 1, stdout: run.stdout ?? '' };
+    };
+}
+/** Working-file blob hash, or null when the path is absent (`git hash-object` failed). */
+function hashPath(path: string, git: GitRunner): string | null {
+    const run = git(['hash-object', '--', path]);
+    return run.status === 0 ? run.stdout.trim() : null;
+}
+/** Paths from `git status --porcelain=v1 -z` (`XY <path>` entries; a rename's source token is
+ * consumed, not registered). */
+export function parsePorcelainZ(stdout: string): string[] {
+    const tokens = stdout.split('\u0000');
+    const paths: string[] = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const entry = tokens[i] ?? '';
+        if (entry.length < 4) continue;
+        const path = entry.slice(3);
+        if (!isBookkeeping(path)) paths.push(path);
+        if (/[RC]/.test(entry.slice(0, 2))) i++;
+    }
+    return paths;
+}
+/** An unresolved conflict marker: an opener or closer line, or a `=======` between them — a `===`
+ * setext underline in prose is not a marker without an opener. */
+export function conflictMarkerLine(content: string): boolean {
+    let opener = false;
+    for (const line of content.split('\n')) {
+        if (/^<{7}( |$)/.test(line)) opener = true;
+        else if (/^={7}(\s|$)/.test(line) && opener) return true;
+        else if (/^>{7}( |$)/.test(line)) return true;
+    }
+    return opener;
+}
+/** "Changed since base" (task-diffstat semantics): tracked changes + untracked, minus bookkeeping. */
+function changedSinceBase(base: string, git: GitRunner): Set<string> {
+    const tracked = git(['diff', '--name-only', base]);
+    const others = git(['ls-files', '--others', '--exclude-standard', '-z']);
+    if (tracked.status !== 0 || others.status !== 0) return new Set();
+    const clean = (out: string, sep: string): string[] =>
+        out
+            .split(sep)
+            .map((p) => p.trim())
+            .filter((p) => p.length > 0 && !isBookkeeping(p));
+    return new Set([...clean(tracked.stdout, '\n'), ...clean(others.stdout, '\u0000')]);
+}
+function readTreeStart(run: string, options: GuardOptions): TreeStart | null {
+    try {
+        const parsed = JSON.parse(readFileSync(at(options, artifactPath(run)), 'utf8')) as TreeStart;
+        if (typeof parsed.head === 'string' && Array.isArray(parsed.dirty)) return parsed;
+    } catch {
+        /* absent or malformed — the caller fails closed */
+    }
+    return null;
+}
+/** Start snapshot + resolved base + the paths this run wrote: "changed since base", keeping only
+ * start-dirty paths whose content its own edits changed. */
+function runContext(run: string, options: GuardOptions) {
+    const git = gitOf(options);
+    const start = readTreeStart(run, options);
+    if (!start) return null;
+    let base = options.base ?? '';
+    if (!base) {
+        try {
+            const anchored = readFileSync(at(options, join('.spur', 'run', `${run}-base.sha`)), 'utf8').trim();
+            if (/^[0-9a-f]{7,40}$/i.test(anchored)) base = anchored;
+        } catch {
+            /* no precheck anchor — the start head is the base */
+        }
+    }
+    if (!base) base = start.head.length > 0 ? start.head : 'HEAD';
+    const written = changedSinceBase(base, git);
+    for (const entry of start.dirty) if (hashPath(entry.path, git) === entry.sha) written.delete(entry.path);
+    return { git, base, start, written };
+}
+function missingStart(run: string): number {
+    process.stderr.write(`commit-guard: no ${artifactPath(run)} — run \`commit-guard start --run ${run}\` first\n`);
+    return 1;
+}
+/** Fingerprint the tree once, before the run writes anything (R1). */
+export function runStart(run: string, options: GuardOptions = {}): number {
+    const git = gitOf(options);
+    const head = git(['rev-parse', 'HEAD']);
+    const status = git(['status', '--porcelain=v1', '-z']);
+    if (head.status !== 0 || status.status !== 0) {
+        process.stderr.write('commit-guard: git probe failed (rev-parse HEAD / status) — is this a work tree?\n');
+        return 1;
+    }
+    const snapshot: TreeStart = {
+        head: head.stdout.trim(),
+        dirty: parsePorcelainZ(status.stdout).map((path) => ({ path, sha: hashPath(path, git) })),
+    };
+    const abs = at(options, artifactPath(run));
+    mkdirSync(join(abs, '..'), { recursive: true });
+    writeFileSync(`${abs}.tmp`, `${JSON.stringify(snapshot, null, 2)}\n`);
+    renameSync(`${abs}.tmp`, abs); // atomic: a concurrent reader never sees a half-written snapshot
+    return 0;
+}
+/** The first path that is unmerged or carries conflict markers, or null (R4, fail closed). */
+function conflictingTarget(paths: string[], options: GuardOptions, git: GitRunner): string | null {
+    const unmerged = new Set(
+        git(['diff', '--name-only', '--diff-filter=U'])
+            .stdout.split('\n')
+            .map((p) => p.trim()),
+    );
+    for (const path of paths) {
+        if (unmerged.has(path)) return `${path} (unmerged)`;
+        try {
+            if (conflictMarkerLine(readFileSync(at(options, path), 'utf8'))) return `${path} (conflict markers)`;
+        } catch {
+            /* deleted target — nothing to scan */
+        }
+    }
+    return null;
+}
+/** Stage only the listed paths this run wrote (R2) and print `{staged, foreign}` (AC1). */
+export function runStage(run: string, paths: string[], options: GuardOptions = {}): StageResult {
+    if (paths.length === 0) {
+        process.stderr.write(`${COMMIT_GUARD_USAGE}\n`);
+        return { staged: [], foreign: [], exitCode: 1 };
+    }
+    const context = runContext(run, options);
+    if (!context) return { staged: [], foreign: [], exitCode: missingStart(run) };
+    const conflict = conflictingTarget(paths, options, context.git);
+    if (conflict) {
+        process.stderr.write(`commit-guard: refusing to stage ${conflict}; nothing staged\n`);
+        return { staged: [], foreign: [], exitCode: 3 };
+    }
+    const dirtyAtStart = new Set(context.start.dirty.map((entry) => entry.path));
+    const staged = paths.filter((path) => context.written.has(path));
+    const refused = paths.filter((path) => !context.written.has(path));
+    for (const path of refused) {
+        const why = dirtyAtStart.has(path) ? 'foreign — dirty at start, untouched by this run' : 'unchanged since base';
+        process.stderr.write(`commit-guard: refused ${path} (${why})\n`);
+    }
+    if (staged.length > 0 && context.git(['add', '--', ...staged]).status !== 0) {
+        process.stderr.write('commit-guard: git add failed — nothing staged\n');
+        return { staged: [], foreign: [], exitCode: 1 };
+    }
+    const foreign = refused.filter((path) => dirtyAtStart.has(path));
+    process.stdout.write(`${JSON.stringify({ staged, foreign })}\n`);
+    return { staged, foreign, exitCode: refused.length > 0 ? 2 : 0 };
+}
+/** Report the working-tree changes this run did not write, staging nothing (R3). */
+export function runCheck(run: string, options: GuardOptions = {}): number {
+    const context = runContext(run, options);
+    if (!context) return missingStart(run);
+    const foreign = [...changedSinceBase(context.base, context.git)]
+        .filter((path) => !context.written.has(path))
+        .sort();
+    process.stdout.write(`${JSON.stringify({ foreign })}\n`);
+    return 0;
+}
+/** Pull one `--flag value` pair out of argv, or undefined when absent (a missing value is usage). */
+function takeFlag(args: string[], name: string): string | undefined {
+    const index = args.indexOf(name);
+    const value = index === -1 ? undefined : args[index + 1];
+    const missing = value === undefined || value.startsWith('--');
+    if (index !== -1) args.splice(index, missing ? 1 : 2);
+    return missing ? undefined : value;
+}
+export function main(argv: string[], options: GuardOptions = {}): number {
+    const args = [...argv];
+    takeFlag(args, '--spur-bin'); // 0482 R2: pipelines hand every plugin script this flag
+    const sub = args.shift();
+    const run = takeFlag(args, '--run');
+    const base = takeFlag(args, '--base');
+    const usage = (): number => {
+        process.stderr.write(`${COMMIT_GUARD_USAGE}\n`);
+        return 1;
+    };
+    if (!run) return usage();
+    if (sub === 'start') return args.length === 0 ? runStart(run, options) : usage();
+    if (sub === 'check') return args.length === 0 ? runCheck(run, { ...options, base }) : usage();
+    if (sub === 'stage')
+        return runStage(
+            run,
+            args.filter((arg) => arg !== '--'),
+            { ...options, base },
+        ).exitCode;
+    return usage();
+}
+
+if (import.meta.main) {
+    process.exit(main(process.argv.slice(2)));
+}

package/plugins/sp/scripts/history-anatomy-cache.mjs

@@ -264,6 +264,7 @@ var FINDING_CATEGORIES = [
   "telemetry",
   "positive"
 ];
+var FINDING_CONFIDENCES = ["high", "medium", "low"];
 function checkReportStructure(reportMarkdown) {
   const problems = [];
   if (/TODO|PLACEHOLDER|FIXME|^\|\s*\|/im.test(reportMarkdown))
@@ -308,6 +309,10 @@ function checkReportStructure(reportMarkdown) {
       if (!/(^|[\s`])P[123]([\s`.]|$)/.test(block) && !block.includes("symbolic-severity")) {
         problems.push("finding-invalid-severity");
       }
+      const confValue = block.match(/`confidence`\s*[:=]\s*`?([^`\n]*?)`?\s*(?:\n|$)/)?.[1]?.trim();
+      if (confValue !== undefined && confValue !== "" && !FINDING_CONFIDENCES.includes(confValue.toLowerCase())) {
+        problems.push(`finding-invalid-confidence:${confValue}`);
+      }
       const catValue = block.match(/`category`\s*[:=]\s*`?([^`\n]+?)`?\s*(?:\n|$)/)?.[1];
       if (catValue && !FINDING_CATEGORIES.includes(catValue.trim())) {
         problems.push(`finding-invalid-category:${catValue.trim()}`);

package/plugins/sp/scripts/inline-run-dispatch.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// @bun
+
+// plugins/sp/scripts/inline-run-dispatch.ts
+import { spawnSync } from "child_process";
+import { existsSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+
+// plugins/sp/lib/env.ts
+function getEnvVar(name, fallback) {
+  const raw = process.env[name];
+  return raw === undefined ? fallback : raw;
+}
+
+// plugins/sp/lib/inline-run-app.ts
+async function loadInlineApp(spurBin, resolveAppEntry, required) {
+  const { entry, portable } = resolveAppEntry(spurBin);
+  const app = await import(entry);
+  const missing = portable ? required.filter((name) => typeof app[name] !== "function") : [];
+  if (missing.length > 0) {
+    throw new Error(`inline application bundle ${entry} is older than its scripts — missing ${missing.join(", ")}. Reinstall sp with a superskill release that stages lib/ (commit b42961b), or pass --spur-bin <spur checkout>/apps/cli/src/index.ts.`);
+  }
+  return { app, portable };
+}
+
+// plugins/sp/scripts/inline-run-dispatch.ts
+function usage() {
+  console.error([
+    "Usage: bun plugins/sp/scripts/inline-run-dispatch.ts --attribution --run-id <id> --stage <state> [--executor <name>] [--agent <name>] [--model <m>] [--spur-bin <path>]",
+    "       bun plugins/sp/scripts/inline-run-dispatch.ts --dispatch-failure --run-id <id> --stage <state> --decision <escalate|stop|host-inline> (--text <record> | --text-file <path>) [--executor <name>] [--agent <name>] [--model <m>] [--spur-bin <path>]",
+    "       --attribution writes .spur/run/<run-id>-attribution.jsonl; an omitted/empty --executor records the explicit no-attribution marker.",
+    "       --dispatch-failure classifies the record upstream, writes .spur/run/<run-id>-dispatch-fallback.json, and carries an attributed capacity exhaustion onto the durable availability path."
+  ].join(`
+`));
+  process.exit(2);
+}
+var SAFE_RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function resolveAppEntry(spurBin) {
+  const fallback = fileURLToPath(new URL("../../../apps/cli/src/index.ts", import.meta.url));
+  const candidates = spurBin !== "" ? [spurBin] : [fallback];
+  for (const candidate of candidates) {
+    const tokens = candidate.split(/\s+/).filter(Boolean);
+    const mainModule = [...tokens].reverse().find((t) => t.endsWith(".ts"));
+    if (mainModule === undefined || !existsSync(mainModule))
+      continue;
+    const repoRoot = resolve(dirname(mainModule), "..", "..", "..");
+    const appEntry = join(repoRoot, "packages", "app", "src", "index.ts");
+    if (existsSync(appEntry))
+      return { entry: appEntry, portable: false };
+  }
+  const entry = fileURLToPath(new URL("../lib/inline-run.generated.mjs", import.meta.url));
+  if (!existsSync(entry)) {
+    throw new Error("inline application bundle is missing \u2014 rebuild/install the sp plugin before running inline");
+  }
+  return { entry, portable: true };
+}
+async function main() {
+  if (!process.versions.bun) {
+    const child = spawnSync("bun", [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+      stdio: "inherit"
+    });
+    if (child.error)
+      console.error(`inline-run-dispatch requires Bun on PATH: ${child.error.message}`);
+    process.exit(child.status ?? 1);
+  }
+  const flags = new Map;
+  let attribution = false;
+  let dispatchFailure = false;
+  let spurBin = getEnvVar("SPUR_BIN") ?? "";
+  const argv = process.argv.slice(2);
+  for (let i = 0;i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === "--attribution")
+      attribution = true;
+    else if (flag === "--dispatch-failure")
+      dispatchFailure = true;
+    else if (flag === "--spur-bin")
+      spurBin = argv[++i] ?? spurBin;
+    else if (flag !== undefined)
+      flags.set(flag, argv[++i] ?? "");
+  }
+  const runId = flags.get("--run-id") ?? "";
+  const stage = flags.get("--stage") ?? "";
+  const decision = flags.get("--decision") ?? "";
+  const text = flags.get("--text") ?? "";
+  const textFile = flags.get("--text-file") ?? "";
+  const executor = flags.get("--executor") ?? "";
+  const agent = flags.get("--agent") ?? "";
+  const model = flags.get("--model") ?? "";
+  if (attribution === dispatchFailure)
+    usage();
+  if (runId.trim() === "" || stage.trim() === "" || !SAFE_RUN_ID_RE.test(runId))
+    usage();
+  const identity = {
+    executor: executor.trim() === "" ? null : executor,
+    agent: agent.trim() === "" ? null : agent,
+    ...model.trim() === "" ? {} : { model }
+  };
+  const { app, portable } = await loadInlineApp(spurBin, resolveAppEntry, [
+    "recordInlineRunAttribution",
+    "runInlineRunDispatchFailure"
+  ]);
+  if (attribution) {
+    app.recordInlineRunAttribution(process.cwd(), runId, {
+      stage,
+      ...identity,
+      observedAt: new Date().toISOString()
+    });
+    process.stdout.write(`${JSON.stringify({ ok: true, runId, stage })}
+`);
+    process.exit(0);
+  }
+  if (decision.trim() === "" || text === "" === (textFile === ""))
+    usage();
+  const { app: lib } = await loadInlineApp(spurBin, () => ({ entry: fileURLToPath(new URL("../lib/inline-run.generated.mjs", import.meta.url)), portable }), ["loadSpurConfig"]);
+  const spurConfig = await lib.loadSpurConfig(process.cwd(), portable ? { embeddedSchemas: lib.EMBEDDED_SPUR_SCHEMAS } : undefined);
+  process.exit(await app.runInlineRunDispatchFailure({
+    runId,
+    stage,
+    decision,
+    ...text === "" ? { textFile } : { text },
+    ...identity,
+    spurConfig
+  }));
+}
+main().catch((e) => {
+  console.error(`inline-run-dispatch: FAIL \u2014 ${e instanceof Error ? e.message : String(e)}`);
+  process.exit(1);
+});

package/plugins/sp/scripts/inline-run-dispatch.ts

@@ -0,0 +1,135 @@
+#!/usr/bin/env bun
+/** Inline dispatch fail-fast facade (task 1134 R1–R4): argv/env only. The classification, the
+ *  decision artifact and the durable availability write all live in the app runners
+ *  (`recordInlineRunAttribution`, `runInlineRunDispatchFailure`), reached through the same
+ *  `loadInlineApp` seam the setup facade uses. It is a SEPARATE script from `inline-run-setup.ts`
+ *  because it is a separate operation and the ADR-130 glue budget is per script. */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// Type-only namespace import (erased before bundling; the smoke scanner exempts `import type`).
+import type * as spurApp from '@gobing-ai/spur-app';
+import { getEnvVar } from '../lib/env';
+import { loadInlineApp } from '../lib/inline-run-app';
+
+// EMBEDDED_SPUR_SCHEMAS is declared by the bundle twin, never exported by the barrel.
+type InlineApp = typeof spurApp & { EMBEDDED_SPUR_SCHEMAS?: ReadonlyMap<string, string> };
+
+function usage(): never {
+    console.error(
+        [
+            'Usage: bun plugins/sp/scripts/inline-run-dispatch.ts --attribution --run-id <id> --stage <state> [--executor <name>] [--agent <name>] [--model <m>] [--spur-bin <path>]',
+            '       bun plugins/sp/scripts/inline-run-dispatch.ts --dispatch-failure --run-id <id> --stage <state> --decision <escalate|stop|host-inline> (--text <record> | --text-file <path>) [--executor <name>] [--agent <name>] [--model <m>] [--spur-bin <path>]',
+            '       --attribution writes .spur/run/<run-id>-attribution.jsonl; an omitted/empty --executor records the explicit no-attribution marker.',
+            '       --dispatch-failure classifies the record upstream, writes .spur/run/<run-id>-dispatch-fallback.json, and carries an attributed capacity exhaustion onto the durable availability path.',
+        ].join('\n'),
+    );
+    process.exit(2);
+}
+
+/** Run ids become filenames under `.spur/run/` — single safe component only (0804 R8). */
+const SAFE_RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** Resolve the app entry: --spur-bin/SPUR_BIN main module if it proves a repo checkout, else the bundle. */
+function resolveAppEntry(spurBin: string): { entry: string; portable: boolean } {
+    const fallback = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));
+    const candidates = spurBin !== '' ? [spurBin] : [fallback];
+    for (const candidate of candidates) {
+        const tokens = candidate.split(/\s+/).filter(Boolean);
+        // Main module = last path-like token; only a .ts source entry proves a repo checkout.
+        const mainModule = [...tokens].reverse().find((t) => t.endsWith('.ts'));
+        if (mainModule === undefined || !existsSync(mainModule)) continue;
+        const repoRoot = resolve(dirname(mainModule), '..', '..', '..');
+        const appEntry = join(repoRoot, 'packages', 'app', 'src', 'index.ts');
+        if (existsSync(appEntry)) return { entry: appEntry, portable: false };
+    }
+    const entry = fileURLToPath(new URL('../lib/inline-run.generated.mjs', import.meta.url));
+    if (!existsSync(entry)) {
+        throw new Error('inline application bundle is missing — rebuild/install the sp plugin before running inline');
+    }
+    return { entry, portable: true };
+}
+
+async function main(): Promise<void> {
+    // The portable Node twin has no workspace imports; the app bundle still uses Spur's Bun runtime.
+    if (!process.versions.bun) {
+        const child = spawnSync('bun', [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+            stdio: 'inherit',
+        });
+        if (child.error) console.error(`inline-run-dispatch requires Bun on PATH: ${child.error.message}`);
+        process.exit(child.status ?? 1);
+    }
+    const flags = new Map<string, string>();
+    let attribution = false;
+    let dispatchFailure = false;
+    let spurBin = getEnvVar('SPUR_BIN') ?? '';
+    const argv = process.argv.slice(2);
+    for (let i = 0; i < argv.length; i++) {
+        const flag = argv[i];
+        if (flag === '--attribution') attribution = true;
+        else if (flag === '--dispatch-failure') dispatchFailure = true;
+        else if (flag === '--spur-bin') spurBin = argv[++i] ?? spurBin;
+        else if (flag !== undefined) flags.set(flag, argv[++i] ?? '');
+    }
+    const runId = flags.get('--run-id') ?? '';
+    const stage = flags.get('--stage') ?? '';
+    const decision = flags.get('--decision') ?? '';
+    const text = flags.get('--text') ?? '';
+    const textFile = flags.get('--text-file') ?? '';
+    const executor = flags.get('--executor') ?? '';
+    const agent = flags.get('--agent') ?? '';
+    const model = flags.get('--model') ?? '';
+
+    if (attribution === dispatchFailure) usage();
+    if (runId.trim() === '' || stage.trim() === '' || !SAFE_RUN_ID_RE.test(runId)) usage();
+    // R3: the executor identity the inline stage actually used. An omitted/empty `--executor` is the
+    // explicit no-attribution marker — never a silent drop.
+    const identity = {
+        executor: executor.trim() === '' ? null : executor,
+        agent: agent.trim() === '' ? null : agent,
+        ...(model.trim() === '' ? {} : { model }),
+    };
+    const { app, portable } = await loadInlineApp<InlineApp>(spurBin, resolveAppEntry, [
+        'recordInlineRunAttribution',
+        'runInlineRunDispatchFailure',
+    ]);
+
+    if (attribution) {
+        app.recordInlineRunAttribution(process.cwd(), runId, {
+            stage,
+            ...identity,
+            observedAt: new Date().toISOString(),
+        });
+        process.stdout.write(`${JSON.stringify({ ok: true, runId, stage })}\n`);
+        process.exit(0);
+    }
+
+    if (decision.trim() === '' || (text === '') === (textFile === '')) usage();
+    // ADR-082: this facade is the composition root, so it loads the effective config once and
+    // threads the merged result into the app runner (never a per-slice load in packages/app).
+    const { app: lib } = await loadInlineApp<typeof import('../lib/inline-run.generated.mjs')>(
+        spurBin,
+        () => ({ entry: fileURLToPath(new URL('../lib/inline-run.generated.mjs', import.meta.url)), portable }),
+        ['loadSpurConfig'],
+    );
+    const spurConfig = await lib.loadSpurConfig(
+        process.cwd(),
+        portable ? { embeddedSchemas: lib.EMBEDDED_SPUR_SCHEMAS } : undefined,
+    );
+    process.exit(
+        await app.runInlineRunDispatchFailure({
+            runId,
+            stage,
+            decision: decision as 'escalate' | 'stop' | 'host-inline',
+            ...(text === '' ? { textFile } : { text }),
+            ...identity,
+            spurConfig,
+        }),
+    );
+}
+
+main().catch((e: unknown) => {
+    console.error(`inline-run-dispatch: FAIL — ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(1);
+});