specrails-desktop 2.15.0 → 2.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.15.0",
+  "version": "2.16.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server/dist/loop-command-catalog.js

@@ -116,6 +116,33 @@ exports.LOOP_COMMANDS = [
         providerNative: { claude: '/loop', codex: '$goal' },
         template: LOOP_FALLBACK_PROMPT,
     },
+    // ── OpenSpec lifecycle (opsx:*) — provider-native slash commands ─────────────
+    // The opsx commands are installed by OpenSpec itself (NOT the specrails
+    // framework) and live under the `/opsx:` namespace, so they are `providerNative`
+    // — NOT `coreCommand` (which would wrongly emit `/specrails:<name>`). claude and
+    // gemini use the slash form; codex uses the `$`-skill form. Providers without a
+    // native opsx command fall back to the `template` prompt. Archive is invoked via
+    // the `openspec` CLI in a shell node (provider-independent) and has no command.
+    // NOTE: opsx commands are confirmed on claude today; codex/gemini lean on the
+    // fallback until OpenSpec ships their native commands (see opsx-lifecycle loop).
+    {
+        name: 'opsx:ff', label: 'opsx:ff', ticketScope: 'per-ticket',
+        description: 'OpenSpec fast-forward: create (or continue) a change and generate all its artifacts (proposal, specs, design, tasks). Native /opsx:ff (claude/gemini) or $opsx:ff (codex).',
+        providerNative: { claude: '/opsx:ff', gemini: '/opsx:ff', codex: '$opsx:ff' },
+        template: 'Create or continue an OpenSpec change for the work described next and generate all of its artifacts (proposal, specs, design, and tasks) so it is ready to implement.',
+    },
+    {
+        name: 'opsx:apply', label: 'opsx:apply', ticketScope: 'per-ticket',
+        description: 'OpenSpec apply: implement all pending tasks of the active change. Native /opsx:apply (claude/gemini) or $opsx:apply (codex).',
+        providerNative: { claude: '/opsx:apply', gemini: '/opsx:apply', codex: '$opsx:apply' },
+        template: 'Implement every pending task of the active OpenSpec change, editing the code as needed and marking each task complete as you finish it.',
+    },
+    {
+        name: 'opsx:verify', label: 'opsx:verify', ticketScope: 'per-ticket',
+        description: "OpenSpec verify: check the active change's implementation against its specs/tasks; ends with VERIFICATION: PASS|FAIL. Native /opsx:verify (claude/gemini) or $opsx:verify (codex).",
+        providerNative: { claude: '/opsx:verify', gemini: '/opsx:verify', codex: '$opsx:verify' },
+        template: 'Verify the active OpenSpec change: inspect the REAL implementation against its specs, design, and tasks. Finish with exactly `VERIFICATION: PASS` when nothing required is missing, or `VERIFICATION: FAIL — <what is still missing>` otherwise.',
+    },
     // ── Merge-resolver (parallel rails: integrate worktree branches back) ───────
     {
         name: 'resolve-merge', label: 'resolve-merge', ticketScope: 'per-ticket',
@@ -185,7 +212,9 @@ const COMMANDS_BY_NAME = new Map(exports.LOOP_COMMANDS.map((c) => [c.name, c]));
 function getLoopCommand(name) {
     return COMMANDS_BY_NAME.get(name);
 }
-const CMD_TOKEN_RE = /\{\{\s*cmd:([\w-]+)\s*\}\}/g;
+// Allow `:` in the command name so namespaced commands like `{{cmd:opsx:ff}}`
+// (whose name is literally `opsx:ff`) tokenize — colon-free names are unaffected.
+const CMD_TOKEN_RE = /\{\{\s*cmd:([\w:-]+)\s*\}\}/g;
 /** Build the native, provider-correct invocation of a core slash command —
  *  identical in shape to the rail's `/specrails:implement #1 #2 --yes`. Codex has
  *  no `/namespace:cmd` parser, so it invokes the equivalent `$<name>` skill. */

package/server/dist/loop-run-manager.js

@@ -5,6 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LoopRunManager = void 0;
 exports.truncate = truncate;
+exports.resolveRunVars = resolveRunVars;
+exports.extractChangeId = extractChangeId;
 const tree_kill_1 = __importDefault(require("tree-kill"));
 const db_1 = require("./db");
 const loop_graph_1 = require("./loop-graph");
@@ -29,6 +31,25 @@ function truncate(s, max = 600) {
     const tail = max - head;
     return s.slice(0, head) + '\n…\n' + s.slice(s.length - tail);
 }
+// ── Run-scoped captured variables ({{run.<name>}}) ───────────────────────────
+// A run can capture values from a step's output and reference them in LATER
+// ai-step prompts and shell commands as `{{run.<name>}}`. v1 captures exactly one
+// — `changeId`, the OpenSpec change id — written so the family can generalize.
+const RUN_TOKEN_RE = /\{\{\s*run\.(\w+)\s*\}\}/g;
+/** First `openspec/changes/<id>` path mentioned in a step's output (the same
+ *  detection SpecLauncherManager uses). The id stops at the first `/`. */
+const CHANGE_ID_RE = /openspec\/changes\/([A-Za-z0-9._-]+)/;
+/** Replace `{{run.<name>}}` with the captured value; uncaptured → '' (never a
+ *  leaked literal token). Applied AFTER `{{cmd:*}}` and `{{spec.*}}`. */
+function resolveRunVars(text, vars) {
+    return text.replace(RUN_TOKEN_RE, (_m, key) => vars[key] ?? '');
+}
+/** Extract the OpenSpec change id from a step's output (first match wins), or
+ *  undefined when none is present. */
+function extractChangeId(text) {
+    const m = CHANGE_ID_RE.exec(text);
+    return m ? m[1] : undefined;
+}
 class LoopRunManager {
     db;
     broadcast;
@@ -187,6 +208,10 @@ class LoopRunManager {
         // values layer on top. Used to expand `{{const:*}}` in every node's text.
         const constMap = { ...loop_constants_1.BUILTIN_CONSTANTS, ...(req.constants ?? {}) };
         const history = [];
+        // Run-scoped captured variables ({{run.<name>}}). Populated as steps run
+        // (e.g. `changeId` from the first opsx:ff step's output) and resolved in later
+        // ai-step prompts and shell commands. Empty until something is captured.
+        const runVars = {};
         // Backstop against a cycle with no Decider (would otherwise never increment
         // `iteration`): cap total node executions well above any honest run.
         const stepCap = (maxIterations + 1) * (req.graph.nodes.length + 2) + 16;
@@ -316,7 +341,7 @@ class LoopRunManager {
                         // --yes`, codex `$implement #<id> --yes`) — then resolve `{{spec.*}}`
                         // data tokens and finally `{{const:*}}` library constants.
                         const rawTemplate = String(node.data?.prompt ?? '');
-                        const base = (0, loop_constants_1.resolveConstants)((0, loop_graph_1.interpolateSpec)((0, loop_command_catalog_1.expandCommands)(rawTemplate, { provider: nodeProvider, ticketIds: req.spec?.ticketIds, specId: req.spec?.id }), req.spec), constMap);
+                        const base = (0, loop_constants_1.resolveConstants)(resolveRunVars((0, loop_graph_1.interpolateSpec)((0, loop_command_catalog_1.expandCommands)(rawTemplate, { provider: nodeProvider, ticketIds: req.spec?.ticketIds, specId: req.spec?.id }), req.spec), runVars), constMap);
                         // Inject the cross-iteration history only when there's no live session
                         // to carry it (a fresh pass) OR right after a Decider 'continue' (so the
                         // step sees the verdict). A mid-body resumed step already has it.
@@ -342,6 +367,17 @@ class LoopRunManager {
                             aiSessionId = res.sessionId;
                         history.push(`AI Step: ${truncate(res.text)}`);
                         record(`loop:${runId}`, res, aiStepStart);
+                        // Capture the OpenSpec change id from a step's output the FIRST time it
+                        // appears (first-match-wins, kept stable across loop-back iterations so
+                        // the re-pass amends the same change). Used by `{{run.changeId}}` in the
+                        // loop-back ff prompt and the unattended archive shell node.
+                        if (!runVars.changeId) {
+                            const cid = extractChangeId(res.text);
+                            if (cid) {
+                                runVars.changeId = cid;
+                                logLine(`↪ Captured OpenSpec change id: ${cid}`);
+                            }
+                        }
                         // Fail-fast: a hard-failed step (non-zero exit / spawn error) that
                         // produced NO output means the provider never really ran — quota,
                         // auth, crash. One can be transient; AI_FAILFAST_THRESHOLD in a row
@@ -363,7 +399,23 @@ class LoopRunManager {
                         break;
                     }
                     case 'shell': {
-                        const command = (0, loop_constants_1.resolveConstants)((0, loop_graph_1.interpolateSpec)(String(node.data?.command ?? ''), req.spec), constMap);
+                        // Guard: refuse to run when a declared run-variable was never captured
+                        // (e.g. an archive node whose `{{run.changeId}}` is empty) — running
+                        // `openspec archive  -y` against an unknown change would archive the
+                        // wrong thing. Settle the run failed with a clear reason instead.
+                        const reqVarsRaw = node.data?.requireRunVars;
+                        const requireRunVars = Array.isArray(reqVarsRaw)
+                            ? reqVarsRaw.filter((v) => typeof v === 'string')
+                            : [];
+                        const missingRunVars = requireRunVars.filter((name) => !runVars[name]);
+                        if (missingRunVars.length > 0) {
+                            emitStep('shell', `⚡ ${nodeLabel || 'Shell'}`);
+                            logLine(`Skipped: required run variable(s) not captured: ${missingRunVars.map((n) => `{{run.${n}}}`).join(', ')} — refusing to run the command against an unknown target.`, 'stderr');
+                            outcome = 'failed';
+                            settled = true;
+                            break;
+                        }
+                        const command = (0, loop_constants_1.resolveConstants)(resolveRunVars((0, loop_graph_1.interpolateSpec)(String(node.data?.command ?? ''), req.spec), runVars), constMap);
                         emitStep('shell', `⚡ ${nodeLabel || 'Shell'}`);
                         logLine(`$ ${command}`);
                         const sh = await this.executors.runShell({ command, cwd: req.cwd, onLine: logLine, onSpawn: (c) => this._activeChild.set(runId, c) });

package/server/dist/loop-templates.js

@@ -4,6 +4,7 @@ exports.LOOP_TEMPLATES = exports.LOOP_CATEGORIES = void 0;
 exports.compilePortSpec = compilePortSpec;
 exports.aiLoopGraph = aiLoopGraph;
 exports.fixLoopGraph = fixLoopGraph;
+exports.opsxLifecycleGraph = opsxLifecycleGraph;
 exports.getLoopTemplate = getLoopTemplate;
 const loop_templates_ported_1 = require("./loop-templates-ported");
 /** Closed taxonomy a template's `category` must belong to. Single source of truth
@@ -102,7 +103,79 @@ function fixLoopGraph(mainPrompts, deciderGoal, maxIterations = 12, timeoutMinut
     edges.push({ id: 'e-stop', source: 'decide', target: 'done', branch: 'stop' }); // green → exit (drops down)
     return { nodes, edges, config: { maxIterations, timeoutMinutes, ...(aiStepTimeoutMinutes != null ? { aiStepTimeoutMinutes } : {}) } };
 }
+// ── OpenSpec lifecycle loop ──────────────────────────────────────────────────
+// A hand-authored graph (NOT a PortSpec) because it combines an AI-step spine, a
+// Decider, a `shell` archive node, AND a terminal action on the Decider's `stop`
+// branch — a shape the stock aiLoopGraph/fixLoopGraph builders do not produce.
+// Per iteration: opsx:ff → opsx:apply → opsx:verify → Decider. The Decider stops
+// when verify reports PASS (→ unattended `openspec archive <id> -y` shell node);
+// otherwise it loops back to opsx:ff, which AMENDS the same change ({{run.changeId}}
+// captured by the engine from ff's first-pass output) using the gaps verify found.
+const OPSX_FF_PROMPT = [
+    '{{cmd:opsx:ff}} {{spec.title}}',
+    '',
+    '{{spec.description}}',
+    '',
+    'If a change id appears here — "{{run.changeId}}" — an OpenSpec change for this ticket already exists: CONTINUE that change (do NOT create a new one) and address only what the verification reported as still missing (see the context below). If it is blank, create the change and generate all required artifacts.',
+    '',
+    'Run fully unattended: make reasonable decisions to keep momentum and NEVER stop to ask — there is no human to answer. When something is unclear, pick the most sensible option, proceed, and note the assumption.',
+].join('\n');
+const OPSX_APPLY_PROMPT = [
+    '{{cmd:opsx:apply}}',
+    '',
+    'Implement every pending task of the active OpenSpec change for ticket "{{spec.title}}", editing code as needed and marking tasks complete as you finish them.',
+    '',
+    'Run fully unattended: decide and keep momentum, never pause to ask. If you hit an ambiguity or blocker, make the most reasonable choice, implement it, and continue.',
+].join('\n');
+const OPSX_VERIFY_PROMPT = [
+    '{{cmd:opsx:verify}}',
+    '',
+    'Verify the active OpenSpec change against its specs, design, and tasks for ticket "{{spec.title}}". Be strict and honest — inspect the REAL code and tests, not any step\'s self-report.',
+    '',
+    'Finish with a clear final line: exactly `{{const:VERIFICATION_PASS}}` when the change fully matches the ticket with nothing required missing, or `{{const:VERIFICATION_FAIL}} — <what is still missing>` otherwise.',
+].join('\n');
+const OPSX_DECIDER_GOAL = 'The verify step reported {{const:VERIFICATION_PASS}} — the implementation fully matches ticket "{{spec.title}}" and nothing required is missing.';
+/** The OpenSpec-lifecycle graph (see comment above). Exported for unit testing. */
+function opsxLifecycleGraph() {
+    return {
+        nodes: [
+            { id: 'start', type: 'start', position: { x: COL_X, y: 0 } },
+            { id: 'ff', type: 'ai-step', position: { x: COL_X, y: ROW_GAP * 1 }, data: { label: 'opsx:ff', prompt: OPSX_FF_PROMPT } },
+            { id: 'apply', type: 'ai-step', position: { x: COL_X, y: ROW_GAP * 2 }, data: { label: 'opsx:apply', prompt: OPSX_APPLY_PROMPT } },
+            { id: 'verify', type: 'ai-step', position: { x: COL_X, y: ROW_GAP * 3 }, data: { label: 'opsx:verify', prompt: OPSX_VERIFY_PROMPT } },
+            { id: 'decide', type: 'decider', position: { x: COL_X, y: ROW_GAP * 4 }, data: { goal: OPSX_DECIDER_GOAL } },
+            // Unattended archive: deterministic CLI, no AI, no prompt. `requireRunVars`
+            // makes the engine REFUSE to run if no change id was captured (never archive
+            // an unknown change); `openspec archive -y` syncs the main specs by default.
+            { id: 'archive', type: 'shell', position: { x: COL_X, y: ROW_GAP * 5 }, data: { label: 'archive', command: 'openspec archive {{run.changeId}} -y', requireRunVars: ['changeId'] } },
+            { id: 'done', type: 'end', position: { x: COL_X, y: ROW_GAP * 6 }, data: { outcome: 'success' } },
+        ],
+        edges: [
+            { id: 'e-start', source: 'start', target: 'ff' },
+            { id: 'e-ff', source: 'ff', target: 'apply' },
+            { id: 'e-apply', source: 'apply', target: 'verify' },
+            { id: 'e-verify', source: 'verify', target: 'decide' },
+            // not-done (verify FAIL) → loop back to ff (firstStepId ⇒ session resets, the
+            // pass re-reads disk; verify's gaps ride in the injected history).
+            { id: 'e-continue', source: 'decide', target: 'ff', branch: 'continue' },
+            // done (verify PASS) → archive then end.
+            { id: 'e-stop', source: 'decide', target: 'archive', branch: 'stop' },
+            { id: 'e-archive', source: 'archive', target: 'done' },
+        ],
+        // Conservative bounds so a never-satisfied verify can't spin: at most 3 full
+        // lifecycle passes; per-step cap raised (apply can implement a whole change).
+        config: { maxIterations: 3, timeoutMinutes: 180, aiStepTimeoutMinutes: 45 },
+    };
+}
 exports.LOOP_TEMPLATES = [
+    {
+        id: 'opsx-lifecycle',
+        name: 'OpenSpec Lifecycle',
+        description: 'Single-agent, ticket-to-archive OpenSpec lifecycle: generate artifacts (opsx:ff) → implement (opsx:apply) → verify (opsx:verify); on a FAIL verdict loop back to amend the SAME change, on PASS archive it unattended. The artifact-centric counterpart to the implement pipeline. Claude-first — codex/gemini fall back to a generic prompt until OpenSpec ships their native opsx commands.',
+        category: 'Automation',
+        tags: ['Automation', 'openspec', 'lifecycle'],
+        graph: opsxLifecycleGraph(),
+    },
     {
         id: 'ship-and-green',
         name: 'Ship & Green',

package/server/dist/rail-isolation.js

@@ -28,16 +28,17 @@ function mutatesRepo(loop) {
     return !loop.readOnly;
 }
 /**
- * The isolation gate flag. **Opt-in during rollout**: worktree isolation runs
- * ONLY when `SPECRAILS_RAIL_WORKTREES` is `1`/`true`/`on`; otherwise every loop run
- * keeps the legacy single shared cwd (byte-identical to before this feature). This
- * lets the integration land inert and be validated on a live rail before it is
- * flipped to default-on. Read per-call so a test can flip the env without
- * re-importing.
+ * The isolation gate flag. **Default-on kill-switch**: worktree isolation runs for
+ * every repo-mutating per-ticket rail UNLESS `SPECRAILS_RAIL_WORKTREES` is set to
+ * `0`/`false`/`off`, which restores the legacy single shared cwd (byte-identical to
+ * before this feature). Default-on is safe because the launch path degrades
+ * gracefully when isolation is unavailable — a non-git repo, an unborn HEAD, or a
+ * worktree-allocation error all fall back to the shared cwd (see rails-router).
+ * Read per-call so a test can flip the env without re-importing.
  */
 function isRailWorktreesEnabled() {
     const v = (process.env.SPECRAILS_RAIL_WORKTREES ?? '').trim().toLowerCase();
-    return v === '1' || v === 'true' || v === 'on';
+    return v !== '0' && v !== 'false' && v !== 'off';
 }
 /**
  * True when this launch should isolate each ticket's run in its own worktree.

package/server/dist/rails-router.js

@@ -377,11 +377,11 @@ function createRailsRouter() {
                     return;
                 }
                 const scope = (0, loop_command_catalog_1.dominantTicketScope)(promptsText);
-                // Parallel isolation (opt-in via SPECRAILS_RAIL_WORKTREES): a per-ticket
-                // rail fanning out >1 ticket on a repo-mutating loop runs each ticket in
-                // its own git worktree, then merges the branches back. Inert by default —
-                // falls through to the shared-cwd path below unless the flag is on; a
-                // worktree-allocation failure also falls back. See rail-isolation.ts.
+                // Parallel isolation (default-on; disable with SPECRAILS_RAIL_WORKTREES=0):
+                // a per-ticket rail on a repo-mutating loop runs each ticket in its own git
+                // worktree, then merges the branches back. Degrades gracefully — a non-git
+                // repo, an unborn HEAD, or a worktree-allocation failure all fall through to
+                // the shared-cwd path below. See rail-isolation.ts.
                 let isolationUnavailable;
                 if ((0, rail_isolation_1.isolationApplies)({ loopsEnabled: (0, feature_flags_1.isLoopsEnabled)(), scope, ticketCount: rail.ticketIds.length, readOnly: false })) {
                     // Worktree isolation needs a git repo WITH at least one commit (an

package/server/dist/workspace-manager.js

@@ -135,6 +135,7 @@ function ensureWorkspace(slug, projectPath, home) {
     const ws = workspacePathFor(slug, home);
     fs_1.default.mkdirSync(ws, { recursive: true });
     ensureProjectLink(ws, projectPath);
+    ensureOpenspecLink(ws, projectPath);
     return ws;
 }
 /**
@@ -192,24 +193,28 @@ function removeWorkspace(slug, home) {
     const ws = workspacePathFor(slug, home);
     if (!fs_1.default.existsSync(ws))
         return;
-    const linkPath = path_1.default.join(ws, 'project');
-    try {
-        const st = fs_1.default.lstatSync(linkPath);
-        if (st.isSymbolicLink() || (process.platform === 'win32' && st.isDirectory())) {
-            // unlink works on POSIX symlinks; rmdir on Windows junctions
-            try {
-                fs_1.default.unlinkSync(linkPath);
-            }
-            catch {
+    // Unlink the carve-out links BEFORE the recursive remove so the user's repo is
+    // never followed/deleted: `project` → the repo, and `openspec` → the repo's
+    // openspec carve-out. (POSIX symlinks unlink; Windows junctions rmdir.)
+    for (const name of ['project', 'openspec']) {
+        const linkPath = path_1.default.join(ws, name);
+        try {
+            const st = fs_1.default.lstatSync(linkPath);
+            if (st.isSymbolicLink() || (process.platform === 'win32' && st.isDirectory())) {
                 try {
-                    fs_1.default.rmdirSync(linkPath);
+                    fs_1.default.unlinkSync(linkPath);
+                }
+                catch {
+                    try {
+                        fs_1.default.rmdirSync(linkPath);
+                    }
+                    catch { /* best-effort */ }
                 }
-                catch { /* best-effort */ }
             }
         }
-    }
-    catch {
-        /* link may not exist */
+        catch {
+            /* link may not exist */
+        }
     }
     fs_1.default.rmSync(ws, { recursive: true, force: true });
 }
@@ -281,3 +286,118 @@ function ensureProjectLink(cwd, projectPath) {
         catch { /* ignore */ }
     }
 }
+/**
+ * Ensure `<ws>/openspec` is a LINK to `<repo>/openspec` — the openspec carve-out.
+ *
+ * openspec is a repo-resident deliverable (CLAUDE.md: "openspec/** … the versioned
+ * spec deliverable … repo-relative by design"). For specrails-core's own slash
+ * commands the `${SPECRAILS_REPO_DIR:-.}` indirection re-points openspec I/O to the
+ * repo — but the EXTERNAL `openspec` binary (invoked as `openspec new change` /
+ * `openspec archive` by the opsx lifecycle) does NOT read that env var; it writes
+ * relative to its cwd. Since relocated rails/loops spawn with cwd = the WORKSPACE,
+ * without this link every `openspec` write would strand the change under
+ * `~/.specrails/projects/<slug>/workspace/openspec` instead of the user's repo.
+ *
+ * Mirrors `ensureProjectLink` (symlink on POSIX, junction on Windows) and adds a
+ * one-time, NON-DESTRUCTIVE migration: a pre-carve-out workspace that already holds
+ * a REAL `openspec/` dir (created by the binary writing to the workspace cwd) has
+ * its contents rescued into the repo — never clobbering the repo's own files —
+ * before the dir is replaced by the link. Idempotent: a no-op once the correct
+ * link exists. Best-effort throughout — a link failure must never abort a spawn.
+ */
+function ensureOpenspecLink(cwd, projectPath) {
+    const linkPath = path_1.default.join(cwd, 'openspec');
+    const repoOpenspec = path_1.default.join(projectPath, 'openspec');
+    try {
+        const st = fs_1.default.lstatSync(linkPath);
+        if (st.isSymbolicLink()) {
+            const current = fs_1.default.readlinkSync(linkPath);
+            if (path_1.default.resolve(cwd, current) === path_1.default.resolve(repoOpenspec))
+                return; // already correct
+            try {
+                fs_1.default.unlinkSync(linkPath);
+            }
+            catch { /* replaced below */ }
+        }
+        else if (st.isDirectory()) {
+            // Pre-carve-out workspace: a real openspec/ dir the binary wrote to the
+            // workspace cwd. Rescue its contents into the repo, then replace with a link.
+            mergeDirInto(linkPath, repoOpenspec);
+            try {
+                fs_1.default.rmSync(linkPath, { recursive: true, force: true });
+            }
+            catch {
+                return;
+            }
+        }
+        else {
+            try {
+                fs_1.default.unlinkSync(linkPath);
+            }
+            catch {
+                return;
+            }
+        }
+    }
+    catch {
+        /* does not exist — create below */
+    }
+    // The carve-out target must exist for the link to resolve (the binary expects to
+    // write under it). openspec/** is an intentional repo carve-out, so creating it
+    // does not violate the pristine-repo guarantee.
+    try {
+        fs_1.default.mkdirSync(repoOpenspec, { recursive: true });
+    }
+    catch { /* best-effort */ }
+    if (process.platform === 'win32') {
+        try {
+            fs_1.default.symlinkSync(repoOpenspec, linkPath, 'junction');
+            return;
+        }
+        catch { /* fall through to POSIX symlink */ }
+    }
+    try {
+        fs_1.default.symlinkSync(repoOpenspec, linkPath);
+    }
+    catch { /* best-effort: a failed link just means the binary writes a fresh workspace dir next run */ }
+}
+/**
+ * Recursively copy `src` into `dest`, creating directories and copying only files
+ * that do NOT already exist in `dest` (the repo's own copy always wins). Used by
+ * the openspec carve-out migration to rescue workspace-stranded artifacts into the
+ * repo without overwriting committed content. Best-effort per entry.
+ */
+function mergeDirInto(src, dest) {
+    let entries;
+    try {
+        entries = fs_1.default.readdirSync(src, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    try {
+        fs_1.default.mkdirSync(dest, { recursive: true });
+    }
+    catch { /* best-effort */ }
+    for (const e of entries) {
+        const s = path_1.default.join(src, e.name);
+        const d = path_1.default.join(dest, e.name);
+        if (e.isDirectory()) {
+            mergeDirInto(s, d);
+        }
+        else if (e.isSymbolicLink()) {
+            if (!fs_1.default.existsSync(d)) {
+                try {
+                    fs_1.default.symlinkSync(fs_1.default.readlinkSync(s), d);
+                }
+                catch { /* skip */ }
+            }
+        }
+        else if (!fs_1.default.existsSync(d)) {
+            try {
+                fs_1.default.copyFileSync(s, d);
+            }
+            catch { /* skip */ }
+        }
+    }
+}