@gobing-ai/spur 0.3.91 → 0.3.92

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

@@ -5,27 +5,27 @@
  * Unlike the subprocess path (`spur workflow run`), the interactive inline driver
  * allocated a run id but never persisted an authoritative `runs` row, so bound
  * `run.artifact` registration (0785 R3) correctly refused every inline record. This
- * script is the thin delegate the driver now runs at Run setup: it resolves the spur
- * repo checkout from the SPUR_BIN chain, imports the real app service
+ * script is the thin delegate the driver now runs at Run setup: it loads the source
+ * app service when the SPUR_BIN chain identifies a checkout, otherwise its generated bundle
  * (`createOrAttachInlineRun` / `openInlineRunProjectDb` from packages/app), and lets it
- * resolve the SAME project-or-bundled definition the engine would launch, compute the
+ * resolve the SAME project/registered/shared definition the engine would launch, compute the
  * canonical definition digest with the exported hash machinery, and create-or-attach the
  * run row through the existing engine persistence adapter.
  *
  * The script itself contains NO direct SQL, NO second hasher and NO persistence policy —
- * every rule lives in packages/app (0804 D1). On a bundle-only install there is no repo
- * checkout to import the app service from, so the setup fails closed with actionable
- * remediation guidance (point SPUR_BIN at a repo checkout); it never falls back to an
- * unbound run (0804 R1 failure policy).
+ * every rule lives in packages/app (0804 D1). On a bundle-only install, the existing
+ * workflow-show projection selects the CLI's definition; the bundled app revalidates its
+ * schema and digest before recording the selected layer. It never creates an unbound run.
  *
- * Outcome JSON is written to `.spur/run/<run-id>-inline-setup.json` so the driver can
- * seed the inline var overlay (`__runId`, `__definitionDigest`) that proof capture and
- * bound registration verify against. Exit 0 = authoritative identity ready (created or
- * idempotently attached); exit 1 = fail closed, the driver must stop.
+ * The setup outcome is written into the two-file run record (task 0927 R1) — machine state
+ * at `.spur/run/<run-id>.state.json` (atomic replace) plus the `.spur/run/<run-id>.md`
+ * run-start header — so the driver can seed the inline var overlay (`__runId`,
+ * `__definitionDigest`) that proof capture and bound registration verify against. The
+ * pre-0927 `<run-id>-inline-setup.json` sidecar is no longer written. Exit 0 = authoritative
+ * identity ready (created or idempotently attached); exit 1 = fail closed, the driver must stop.
  *
- * Repo-only script (ADR-065): it imports the app workspace source, so it runs under bun
- * against a monorepo checkout only — the same posture as task-size-precheck.ts and
- * task-evidence-precheck.ts.
+ * Standard script (ADR-065): the generated Node-runnable twin re-enters Bun for the
+ * existing SQLite runtime. Bun on PATH is required; a monorepo checkout is not.
  *
  * Usage:
  *   bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]
@@ -41,7 +41,7 @@
  * 0868): `--action` records one completed action boundary as an `action_runs` row through the
  * shared `WorkflowActionTraceWriter`, `--close` marks the run row terminal through the same
  * writer. `--action` is best-effort: a persistence failure is appended to
- * `.spur/run/<run-id>.log` and the script still exits 0 with `{"ok":false}` on stdout, so
+ * `.spur/run/<run-id>.md` and the script still exits 0 with `{"ok":false}` on stdout, so
  * observation never wedges the run. `--close` is NOT best-effort: the run-row closure is
  * bookkeeping, so a missing run row or a persistence failure exits 1 with a named error.
  * Exit 2 is reserved for usage errors.
@@ -49,12 +49,24 @@
  * Env: SPUR_BIN
  */
 
-import { appendFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import {
+    appendFileSync,
+    closeSync,
+    existsSync,
+    mkdirSync,
+    openSync,
+    readFileSync,
+    renameSync,
+    unlinkSync,
+    writeFileSync,
+    writeSync,
+} from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getEnvVar } from '../lib/env';
 
-/** Outcome document written to `.spur/run/<run-id>-inline-setup.json`. */
+/** Setup outcome projected into the run-record state `.spur/run/<run-id>.state.json` (0927 R1). */
 interface SetupOutcome {
     readonly ok: boolean;
     readonly runId: string;
@@ -87,8 +99,8 @@ function usage(): never {
 }
 
 /**
- * The run id becomes a filename under `.spur/run/` (`<run-id>-inline-setup.json`), so it must be a
- * single safe filename component before anything is written — the same guard class the
+ * The run id becomes filenames under `.spur/run/` (`<run-id>.state.json` + `<run-id>.md`),
+ * so it must be a single safe filename component before anything is written — the same guard class the
  * task-pipeline.yaml route-reason action applies to `$__runId` (task 0804 R8). The allowlist
  * refuses path separators, dot traversal (leading `.`), unresolved interpolation (`$`/`{`/`}`) and
  * every other shell/unspecified metachar; valid UUID/timestamp-slug ids pass.
@@ -97,7 +109,7 @@ const SAFE_RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 
 function refuseUnsafeRunId(runId: string): never {
     // Refuse BEFORE any outcome write: an unsafe id must never reach
-    // `.spur/run/<run-id>-inline-setup.json` (no traversal, no unintended file).
+    // `.spur/run/<run-id>.state.json` / `.md` (no traversal, no unintended file).
     console.error(`inline-run-setup: refusing unsafe run id: ${runId}`);
     console.error(
         '  The run id must be a single safe filename component (alphanumeric/._-, no leading dot, ' +
@@ -112,12 +124,9 @@ function refuseUnsafeRunId(runId: string): never {
  * (--spur-bin > SPUR_BIN > monorepo-local CLI entry > PATH `spur`), then derive the repo
  * root from the resolved main module. `bun <repo>/apps/cli/src/index.ts` → repo root is
  * three levels up. A bundle-only install (`spur` on PATH, a bundled `spur.js`, or a spur
- * binary without the app workspace) has no app entry to import — the caller fails that
- * closed with remediation guidance.
+ * binary without the app workspace) uses the adjacent generated application bundle.
  */
-function resolveAppEntry(
-    spurBin: string,
-): { entry: string; repoRoot: string } | { entry: null; repoRoot: null; chain: string } {
+function resolveAppEntry(spurBin: string): { entry: string; portable: boolean } {
     let candidates: string[] = [];
     if (spurBin !== '') {
         candidates = [spurBin];
@@ -137,16 +146,119 @@ function resolveAppEntry(
         const srcDir = dirname(mainModule);
         const repoRoot = resolve(srcDir, '..', '..', '..');
         const appEntry = join(repoRoot, 'packages', 'app', 'src', 'index.ts');
-        if (existsSync(appEntry)) return { entry: appEntry, repoRoot };
-        return { entry: null, repoRoot: null, chain: `${candidate} (no ${appEntry})` };
+        if (existsSync(appEntry)) return { entry: appEntry, portable: false };
     }
-    return { entry: null, repoRoot: null, chain: spurBin === '' ? 'PATH spur (bundle-only install)' : spurBin };
+    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 };
+}
+
+/** Let the selected CLI own config and layer resolution, then revalidate its snapshot in the app. */
+async function readInstalledInventory(file: string, spurBin: string): Promise<unknown> {
+    const localCli = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));
+    const bundle = fileURLToPath(new URL('../lib/inline-run.generated.mjs', import.meta.url));
+    const { splitLaunchCommand } = (await import(bundle)) as typeof import('../lib/inline-run.generated.mjs');
+    const launch = spurBin
+        ? splitLaunchCommand(spurBin, 'inline-run-setup "spurBin"')
+        : existsSync(localCli)
+          ? { command: 'bun', leadingArgs: [localCli] }
+          : { command: 'spur', leadingArgs: [] };
+    if ('error' in launch) throw new Error(launch.error);
+    const result = spawnSync(
+        launch.command,
+        [...launch.leadingArgs, 'workflow', 'show', file, '--format', 'todo', '--json'],
+        { cwd: process.cwd(), encoding: 'utf8', timeout: 30_000, maxBuffer: 4 * 1024 * 1024 },
+    );
+    if (result.status !== 0) {
+        throw new Error(
+            `could not resolve the workflow definition with the installed CLI: ${result.error?.message ?? result.stderr}`,
+        );
+    }
+    const value: unknown = JSON.parse(result.stdout);
+    // Honor the existing optional JSON envelope without inventing another projection format.
+    if (value && typeof value === 'object' && 'ok' in value && 'data' in value && value.ok === true) {
+        return value.data;
+    }
+    return value;
 }
 
+/**
+ * Project the setup outcome into the two-file run record (task 0927 R1): the machine state
+ * merges into `.spur/run/<run-id>.state.json` (atomic same-directory temp + rename, the
+ * 0925 R1 pattern) and `.spur/run/<run-id>.md` receives its run-start header exactly once.
+ * A re-setup of the same run id rewrites the state from the current outcome but keeps the
+ * prior `startedAt` instead of resurrecting setup time. Identity/provenance fields only —
+ * never prompt bodies — so the record carries no secret-bearing content by construction
+ * (0927 AC2). The retired `<run-id>-inline-setup.json` sidecar is not written (0927 R4);
+ * its readers were migrated to the pair state in the same change.
+ */
 function writeOutcome(runId: string, outcome: SetupOutcome): void {
     const runDir = join(process.cwd(), '.spur', 'run');
     if (!existsSync(runDir)) mkdirSync(runDir, { recursive: true });
-    writeFileSync(join(runDir, `${runId}-inline-setup.json`), `${JSON.stringify(outcome, null, 4)}\n`);
+    const statePath = join(runDir, `${runId}.state.json`);
+    const markdownPath = join(runDir, `${runId}.md`);
+    let prior: Record<string, unknown> = {};
+    try {
+        const parsed: unknown = JSON.parse(readFileSync(statePath, 'utf8'));
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            prior = parsed as Record<string, unknown>;
+        }
+    } catch {
+        // No prior state (new run) or unreadable file — the outcome alone defines the state.
+    }
+    const at = new Date().toISOString();
+    const state = {
+        schemaVersion: 1 as const,
+        runId,
+        ...(outcome.workflowName !== undefined ? { workflowName: outcome.workflowName } : {}),
+        ...(outcome.status !== undefined ? { status: outcome.status } : {}),
+        startedAt: typeof prior.startedAt === 'string' ? prior.startedAt : at,
+        updatedAt: at,
+        ...(outcome.attached !== undefined ? { attached: outcome.attached } : {}),
+        ...(outcome.definitionDigest !== undefined ? { definitionDigest: outcome.definitionDigest } : {}),
+        ...(outcome.workflowVersion !== undefined ? { workflowVersion: outcome.workflowVersion } : {}),
+        ...(outcome.resolvedPath !== undefined ? { resolvedPath: outcome.resolvedPath } : {}),
+        ...(outcome.layer !== undefined ? { layer: outcome.layer } : {}),
+        ...(outcome.workdir !== undefined ? { workdir: outcome.workdir } : {}),
+        // 0948 R7: project the setup outcome itself, so the retired `-inline-setup.json`
+        // sidecar's `ok` is still readable from the pair, and a SUCCESSFUL re-setup
+        // explicitly drops any prior `error` — a stale failure message must not outlive
+        // the failure it described (the state object is rebuilt, never merged with `prior`).
+        ok: outcome.ok,
+        ...(outcome.ok === false && outcome.error !== undefined ? { error: outcome.error } : {}),
+    };
+    const temp = `${statePath}.tmp`;
+    try {
+        writeFileSync(temp, `${JSON.stringify(state, null, 4)}\n`);
+        renameSync(temp, statePath);
+    } catch {
+        // Best-effort: a failing record write must not wedge setup reporting — and never
+        // leaves `.tmp` residue behind (0926 R1).
+        try {
+            unlinkSync(temp);
+        } catch {
+            // Nothing to clean (temp was never created).
+        }
+    }
+    // 0948 R7: create the header with `wx` (O_EXCL) instead of `existsSync` → `appendFileSync`.
+    // The check-then-append pair could append a SECOND header when two setups raced, and it
+    // kept "header present" as a separate fact from the identity write. One exclusive create
+    // makes exactly-one-header atomic; EEXIST just means it is already there.
+    let headerFd: number | undefined;
+    try {
+        headerFd = openSync(markdownPath, 'wx');
+        writeSync(
+            headerFd,
+            `# spur inline run ${runId} — ${outcome.workflowName ?? 'unknown workflow'} — setup ${at}\n`,
+        );
+    } catch {
+        // EEXIST (already written) or an unwritable path — the human header is not the setup
+        // identity, so this stays best-effort exactly like the state write above.
+    } finally {
+        if (headerFd !== undefined) closeSync(headerFd);
+    }
 }
 
 /**
@@ -159,14 +271,7 @@ function writeOutcome(runId: string, outcome: SetupOutcome): void {
  * Returns the process exit code: 0 printed, 1 read/resolve failure.
  */
 async function printFingerprint(taskFile: string, featureFile: string, spurBin: string): Promise<number> {
-    const { entry, repoRoot, chain } = resolveAppEntry(spurBin);
-    if (entry === null || repoRoot === null) {
-        console.error(
-            `inline-run-setup: FAIL — no monorepo checkout of spur is reachable via ${chain}. ` +
-                'The proof-input digest must be computed by the app service; a bundle-only install cannot do it.',
-        );
-        return 1;
-    }
+    const { entry } = resolveAppEntry(spurBin);
     const app = (await import(entry)) as {
         computeProofInputFingerprint: (options: Record<string, unknown>) => Promise<string>;
         readProofInputContents: (
@@ -204,7 +309,7 @@ const CLOSE_STATUSES = new Set(['done', 'failed', 'paused']);
 const ACTION_STATUSES = new Set(['done', 'failed']);
 
 /** Input for the ADR-117 emission modes (`--action` / `--close`). */
-import type { WorkflowActionTraceWriter } from '@gobing-ai/app';
+import type { WorkflowActionTraceWriter } from '@gobing-ai/spur-app';
 
 interface TraceModeInput {
     readonly runId: string;
@@ -218,9 +323,23 @@ interface TraceModeInput {
 }
 
 /**
- * Append one emission-failure line to `.spur/run/<run-id>.log` — the run log the inline
- * driver already owns. Best-effort and synchronous (the process may exit immediately
- * after), and never throws: an unwritable log must not wedge the run (ADR-117 R3).
+ * The run-record file for appended driver lines (task 0927 R1): `.spur/run/<run-id>.md`
+ * for pair-based runs. A legacy run that predates the pair keeps appending to its declared
+ * `.spur/run/<run-id>.log` — the same precedence as `readWorkflowRunRecord` (the pair wins,
+ * legacy stays readable in place).
+ */
+function runRecordLogPath(runDir: string, runId: string): string {
+    const markdownPath = join(runDir, `${runId}.md`);
+    const legacyLogPath = join(runDir, `${runId}.log`);
+    if (existsSync(legacyLogPath) && !existsSync(markdownPath)) return legacyLogPath;
+    return markdownPath;
+}
+
+/**
+ * Append one emission-failure line to the run record markdown — `.spur/run/<run-id>.md`,
+ * the run log the inline driver already owns. Best-effort and synchronous (the process may
+ * exit immediately after), and never throws: an unwritable log must not wedge the run
+ * (ADR-117 R3).
  */
 function appendTraceFailureLine(runId: string, detail: string): void {
     try {
@@ -228,7 +347,7 @@ function appendTraceFailureLine(runId: string, detail: string): void {
         if (!existsSync(runDir)) mkdirSync(runDir, { recursive: true });
         const safeRunId = runId.replace(/[^A-Za-z0-9._-]/g, '_');
         const stamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
-        appendFileSync(join(runDir, `${safeRunId}.log`), `[${stamp}] ${detail}\n`);
+        appendFileSync(runRecordLogPath(runDir, safeRunId), `[${stamp}] ${detail}\n`);
     } catch {
         // Best-effort (R3): the run continues even when the failure cannot be recorded.
     }
@@ -254,27 +373,20 @@ async function runTraceMode(input: TraceModeInput): Promise<number> {
         return input.close ? 1 : 0;
     };
 
-    const { entry, repoRoot, chain } = resolveAppEntry(input.spurBin);
-    if (entry === null || repoRoot === null) {
-        return fail(
-            `no monorepo checkout of spur is reachable via ${chain} — the shared trace writer ` +
-                'lives in packages/app (point SPUR_BIN at a repo checkout)',
-        );
-    }
-
     // Compile-time link (0868 finding #5): the writer half is typed by the real packages/app
     // export (type-only import, erased at runtime) so a signature drift breaks THIS file's
     // typecheck instead of hiding behind the hand-declared cast.
-    const app = (await import(entry)) as {
-        openInlineRunProjectDb: (workdir: string) => Promise<{ adapter: unknown; close: () => void }>;
-        createWorkflowActionTraceWriter: (
-            db: unknown,
-            recordFailure?: (failure: unknown) => void,
-        ) => WorkflowActionTraceWriter;
-    };
-
     let projectDb: { adapter: unknown; close: () => void } | undefined;
     try {
+        const { entry } = resolveAppEntry(input.spurBin);
+        const app = (await import(entry)) as {
+            openInlineRunProjectDb: (workdir: string) => Promise<{ adapter: unknown; close: () => void }>;
+            createWorkflowActionTraceWriter: (
+                db: unknown,
+                recordFailure?: (failure: unknown) => void,
+            ) => WorkflowActionTraceWriter;
+        };
+
         projectDb = await app.openInlineRunProjectDb(process.cwd());
         const writer = app.createWorkflowActionTraceWriter(projectDb.adapter, (failure: unknown) => {
             const detail = failure as { operation?: string; error?: string };
@@ -321,6 +433,14 @@ async function runTraceMode(input: TraceModeInput): Promise<number> {
 }
 
 async function main(): Promise<void> {
+    // The portable Node twin has no workspace imports; SQLite still uses Spur's existing 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-setup requires Bun on PATH: ${child.error.message}`);
+        process.exit(child.status ?? 1);
+    }
     let runId = '';
     let file = '';
     let fingerprint = false;
@@ -396,23 +516,7 @@ async function main(): Promise<void> {
     if (runId.trim() === '' || file.trim() === '') usage();
     if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);
 
-    const { entry, repoRoot, chain } = resolveAppEntry(spurBin);
-    if (entry === null || repoRoot === null) {
-        const outcome: SetupOutcome = {
-            ok: false,
-            runId,
-            error:
-                `inline run setup failed closed: no monorepo checkout of spur is reachable via ${chain}. ` +
-                'The authoritative run identity must be persisted by the app service ' +
-                '(packages/app/src/services/inline-run-setup.ts); a bundle-only install cannot do this. ' +
-                'Remediation: point SPUR_BIN at a repo checkout, e.g. ' +
-                'SPUR_BIN="bun /path/to/spur/apps/cli/src/index.ts". The pipeline must not run unbound.',
-        };
-        writeOutcome(runId, outcome);
-        console.error(`inline-run-setup: FAIL for run ${runId}`);
-        console.error(`  ${outcome.error}`);
-        process.exit(1);
-    }
+    const { entry, portable } = resolveAppEntry(spurBin);
 
     // Dynamic import by absolute path: the app source graph resolves its own workspace
     // dependencies from the repo checkout, never from this plugin script's location.
@@ -422,11 +526,22 @@ async function main(): Promise<void> {
             getDb: () => Promise<unknown>;
             file: string;
             runId: string;
+            inventory?: unknown;
+            embeddedSchemas?: ReadonlyMap<string, string>;
         }) => Promise<SetupOutcome & { ok: boolean }>;
         openInlineRunProjectDb: (workdir: string) => Promise<{ adapter: unknown; close: () => void }>;
+        EMBEDDED_SPUR_SCHEMAS?: ReadonlyMap<string, string>;
     };
 
     const workdir = process.cwd();
+    let inventory: unknown;
+    try {
+        inventory = await readInstalledInventory(file, spurBin);
+    } catch (error) {
+        const message = `could not resolve the workflow definition: ${error instanceof Error ? error.message : String(error)}`;
+        writeOutcome(runId, { ok: false, runId, error: message });
+        throw new Error(message);
+    }
     const projectDb = await app.openInlineRunProjectDb(workdir);
     let exitCode = 0;
     try {
@@ -435,6 +550,8 @@ async function main(): Promise<void> {
             getDb: async () => projectDb.adapter,
             file,
             runId,
+            inventory,
+            ...(portable ? { embeddedSchemas: app.EMBEDDED_SPUR_SCHEMAS } : {}),
         });
         writeOutcome(runId, result);
         if (!result.ok) {

package/plugins/sp/scripts/record-feature-sync.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// plugins/sp/scripts/record-feature-sync.ts
+import { spawnSync } from "node:child_process";
+import { appendFileSync, existsSync } from "node:fs";
+
+// plugins/sp/lib/env.ts
+function getEnvVar(name, fallback) {
+  const raw = process.env[name];
+  return raw === undefined ? fallback : raw;
+}
+
+// plugins/sp/scripts/record-feature-sync.ts
+function resolveSpurBin(argv) {
+  const flag = argv.indexOf("--spur-bin");
+  const value = flag !== -1 ? argv[flag + 1] : undefined;
+  return value ?? getEnvVar("spurBin") ?? "spur";
+}
+function main() {
+  const argv = process.argv.slice(2);
+  const spurBin = resolveSpurBin(argv);
+  const wbs = getEnvVar("wbs") ?? "";
+  if (wbs.length === 0) {
+    console.error("record-feature-sync: env `wbs` is required");
+    process.exit(0);
+  }
+  const reportPath = `.spur/run/${wbs}-report.txt`;
+  const report = (line) => {
+    appendFileSync(reportPath, `${line}
+`);
+  };
+  const show = spawnSync(spurBin, ["task", "show", wbs, "--json"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  let featureId = "";
+  try {
+    const parsed = JSON.parse(show.stdout ?? "");
+    featureId = String(parsed.feature_id ?? parsed.frontmatter?.feature_id ?? "");
+  } catch {
+    featureId = "";
+  }
+  if (featureId.length === 0) {
+    report(`Orphan task ${wbs} — no feature_id linked — proposal: consider linking to a parent feature.`);
+    return;
+  }
+  if (existsSync("plugins/sp/scripts/feature-sync-bounded.ts")) {
+    spawnSync("bun", ["plugins/sp/scripts/feature-sync-bounded.ts", featureId, "--spur-bin", spurBin, "--json"], {
+      stdio: "inherit"
+    });
+    return;
+  }
+  const staged = spawnSync("superskill", ["script", "path", "sp", "feature-sync-bounded.mjs"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  const stagedPath = (staged.stdout ?? "").trim();
+  if (staged.status === 0 && stagedPath.length > 0 && existsSync(stagedPath)) {
+    spawnSync("node", [stagedPath, featureId, "--spur-bin", spurBin, "--json"], { stdio: "inherit" });
+    return;
+  }
+  spawnSync(spurBin, ["feature", "sync", featureId, "--json"], { stdio: "inherit" });
+}
+main();

package/plugins/sp/scripts/record-feature-sync.ts

@@ -0,0 +1,84 @@
+/**
+ * record-feature-sync — record-step post-record feature sync owner (tasks 0328 / 0411 / 0931).
+ *
+ * Extracted from the record onEnter shell (0931 R5): ADR-115 caps one workflow shell at 10
+ * logical commands and 800 chars, and the deferFeatureSync guard plus the sync chain can no
+ * longer share it. The pipeline shell resolves this script (in-repo first, superskill-staged
+ * .mjs fallback), notes a deferral, and delegates the rest here:
+ *
+ * - A task with no feature_id gets the orphan proposal note (0328).
+ * - The sync routes through feature-sync-bounded.ts (0411 retry suppression), then the
+ *   superskill-staged module, then bare `spur feature sync` (0328).
+ * - Best-effort by contract: a sync failure never fails the record step.
+ *
+ * Node-builtin imports only (ADR-065): this file is transpiled to a node-runnable .mjs twin
+ * by `superskill script convert`. Env: wbs (required), spurBin (default "spur"); the
+ * `--spur-bin <bin>` argument wins over the env var.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, existsSync } from 'node:fs';
+import { getEnvVar } from '../lib/env';
+
+function resolveSpurBin(argv: string[]): string {
+    const flag = argv.indexOf('--spur-bin');
+    const value = flag !== -1 ? argv[flag + 1] : undefined;
+    return value ?? getEnvVar('spurBin') ?? 'spur';
+}
+
+function main(): void {
+    const argv = process.argv.slice(2);
+    const spurBin = resolveSpurBin(argv);
+    const wbs = getEnvVar('wbs') ?? '';
+    if (wbs.length === 0) {
+        console.error('record-feature-sync: env `wbs` is required');
+        process.exit(0); // best-effort contract — never fail the record step
+    }
+
+    const reportPath = `.spur/run/${wbs}-report.txt`;
+    const report = (line: string): void => {
+        appendFileSync(reportPath, `${line}\n`);
+    };
+
+    const show = spawnSync(spurBin, ['task', 'show', wbs, '--json'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    let featureId = '';
+    try {
+        const parsed = JSON.parse(show.stdout ?? '') as {
+            feature_id?: string;
+            frontmatter?: { feature_id?: string };
+        };
+        featureId = String(parsed.feature_id ?? parsed.frontmatter?.feature_id ?? '');
+    } catch {
+        featureId = '';
+    }
+
+    if (featureId.length === 0) {
+        report(`Orphan task ${wbs} — no feature_id linked — proposal: consider linking to a parent feature.`);
+        return;
+    }
+
+    if (existsSync('plugins/sp/scripts/feature-sync-bounded.ts')) {
+        spawnSync('bun', ['plugins/sp/scripts/feature-sync-bounded.ts', featureId, '--spur-bin', spurBin, '--json'], {
+            stdio: 'inherit',
+        });
+        return;
+    }
+
+    const staged = spawnSync('superskill', ['script', 'path', 'sp', 'feature-sync-bounded.mjs'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const stagedPath = (staged.stdout ?? '').trim();
+    if (staged.status === 0 && stagedPath.length > 0 && existsSync(stagedPath)) {
+        spawnSync('node', [stagedPath, featureId, '--spur-bin', spurBin, '--json'], { stdio: 'inherit' });
+        return;
+    }
+
+    spawnSync(spurBin, ['feature', 'sync', featureId, '--json'], { stdio: 'inherit' });
+    // Falls through with exit 0: a sync failure never fails the record step (0411).
+}
+
+main();