@ornexus/neocortex 4.60.71 → 4.60.73

package/packages/client/dist/git/legacy-story-branch-setup.js

@@ -1,4 +1,348 @@
-import{execFileSync as T}from"node:child_process";import{createHash as w,randomBytes as V}from"node:crypto";import{closeSync as G,constants as B,existsSync as L,fstatSync as U,openSync as M,readFileSync as Y,realpathSync as y}from"node:fs";import{join as d,resolve as O}from"node:path";import{resolveBranchUnit as K}from"../../../shared/dist/yoloop/branch-unit.js";import{acquireGitLifecyclePhysicalIntegrationLock as Q,assertGitLifecyclePrivateFile as S,ensureGitLifecyclePrivateChildDirectory as X,gitLifecycleRuntimeDirectory as ee,releaseGitLifecyclePhysicalIntegrationLock as re}from"./git-lifecycle-store.js";import{GIT_LIFECYCLE_SETUP_BRANCH_STEP_ID as te}from"./git-lifecycle-step-ids.js";import{anchoredAtomicWriteFile as N}from"./secure-filesystem-boundary.js";const ae="legacy-story-branch-intents";function x(r){return`${w("sha256").update(r).digest("hex")}.json`}function _(r){return`${w("sha256").update(r).digest("hex")}.completed.json`}function P(r){return w("sha256").update(JSON.stringify(r)).digest("hex")}async function k(r){return X(await ee(r),ae)}function ne(r,e){const t=f(r);if(!t||Object.keys(t).sort().join(",")!==["baseBranch","baseHeadSha","branch","currentHeadSha","epicId","existingBranchHeadSha","kind","localOnly","schemaVersion","stateSha256","storyId","worktreePath"].sort().join(",")||t.schemaVersion!==1||t.kind!=="legacy-story-branch-plan"||t.storyId!==e||t.localOnly!==!0||t.existingBranchHeadSha!==null||typeof t.epicId!="string"||typeof t.branch!="string"||typeof t.baseBranch!="string"||typeof t.worktreePath!="string"||![t.baseHeadSha,t.currentHeadSha,t.stateSha256].every(a=>typeof a=="string"&&/^[0-9a-f]{40,64}$/.test(a)))throw new Error("legacy-branch-intent-invalid");return t}async function R(r,e){const t=await k(r),a=d(t,x(e));if(!L(a))return null;await S(a,t);const c=b(a);if(c.length>4096)throw new Error("legacy-branch-intent-invalid");return ne(JSON.parse(c),e)}async function ce(r,e){const t=await k(r),a=await R(r,e.storyId);if(a){if(JSON.stringify(a)!==JSON.stringify(e))throw new Error("legacy-branch-intent-conflict");return}await N(t,x(e.storyId),`${JSON.stringify(e)}
-`),await S(d(t,x(e.storyId)),t)}async function z(r,e){const t=await k(r),a=d(t,_(e.storyId));if(!L(a))return!1;await S(a,t);const c=b(a);if(c.length>512)throw new Error("legacy-branch-completion-invalid");const n=f(JSON.parse(c));if(!n||Object.keys(n).sort().join(",")!=="kind,planDigest,schemaVersion,storyId"||n.schemaVersion!==1||n.kind!=="legacy-story-branch-switch-completed"||n.storyId!==e.storyId||n.planDigest!==P(e))throw new Error("legacy-branch-completion-invalid");return!0}async function oe(r,e){if(await z(r,e))return;const t=await k(r);await N(t,_(e.storyId),`${JSON.stringify({schemaVersion:1,kind:"legacy-story-branch-switch-completed",storyId:e.storyId,planDigest:P(e)})}
-`),await S(d(t,_(e.storyId)),t)}function i(r){return{ok:!1,reasonCode:r}}function A(r,e){return T("git",[...e],{cwd:r,encoding:"utf8",stdio:["ignore","pipe","pipe"],maxBuffer:4*1024*1024})}function o(r,e){return A(r,e).trim()}function H(r,e){try{return o(r,e),!0}catch{return!1}}function f(r){return r&&typeof r=="object"&&!Array.isArray(r)?r:null}function m(r,e){return e.length>0&&e.length<=200&&!e.startsWith("-")&&!e.includes("..")&&!e.includes("@{")&&H(r,["check-ref-format","--branch",e])}function b(r){const e=M(r,B.O_RDONLY|(B.O_NOFOLLOW??0));try{const t=U(e);if(!t.isFile()||t.size>2*1024*1024)throw new Error("legacy-branch-state-unsafe");return Y(e,"utf8")}finally{G(e)}}function W(r){return o(r,["worktree","list","--porcelain"]).split(/\n\n+/).flatMap(e=>{const t=e.split(`
-`),a=t.find(n=>n.startsWith("worktree ")),c=t.find(n=>n.startsWith("branch refs/heads/"));return!a||!c?[]:[{path:a.slice(9),branch:c.slice(18),unsafe:t.some(n=>n.startsWith("prunable")||n.startsWith("locked"))}]})}function se(r){const e=y(r.projectRoot);if(!/^[A-Za-z0-9][A-Za-z0-9_-]*\.[A-Za-z0-9._-]+$/.test(r.storyId))throw new Error("legacy-branch-story-id-invalid");if(y(o(e,["rev-parse","--show-toplevel"]))!==e)throw new Error("legacy-branch-project-root-invalid");const t=d(e,".neocortex/state.json"),a=b(t),c=f(JSON.parse(a)),n=f(c?.stories),u=f(c?.epics),h=f(n?.[r.storyId]),s=h?.epic_id,g=typeof s=="string"?f(u?.[s]):null;if(!h||h.id!==r.storyId||typeof s!="string"||!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(s)||!g||g.id!==s)throw new Error("legacy-branch-story-state-invalid");const J=Object.entries(n??{}).flatMap(([p,q])=>{const D=f(q);return D?.epic_id===s?[{...D,id:p}]:[]});if(K(g,J).mode!=="story"||g.branch_mode==="epic")throw new Error("legacy-branch-mode-invalid");if(h.status!=="backlog"&&h.status!=="ready_to_start")throw new Error("legacy-branch-story-status-invalid");if(!Array.isArray(h.steps_completed)||h.steps_completed.includes(te)||h.branch_name)throw new Error("legacy-branch-story-already-started");const v=f(c?.config)?.default_branch,I=`story/${s}/${r.storyId}`;if(typeof v!="string"||!m(e,v)||!m(e,I)||!m(e,`epic/${s}`))throw new Error("legacy-branch-ref-invalid");const E=W(e).filter(p=>p.branch===`epic/${s}`);if(E.length!==1||E[0].unsafe)throw new Error("legacy-branch-epic-worktree-unavailable");const l=y(E[0].path);if(typeof g.worktree_path=="string"&&y(O(e,g.worktree_path))!==l)throw new Error("legacy-branch-epic-worktree-mismatch");const $=p=>y(O(p,o(p,["rev-parse","--git-common-dir"])));if($(l)!==$(e)||y(o(l,["rev-parse","--show-toplevel"]))!==l||o(l,["symbolic-ref","--quiet","--short","HEAD"])!==`epic/${s}`)throw new Error("legacy-branch-worktree-identity-invalid");const Z=d(l,".neocortex/state.json");if(b(Z)!==a)throw new Error("legacy-branch-worktree-state-mismatch");if(o(l,["status","--porcelain=v1","-uall"])!=="")throw new Error("legacy-branch-worktree-dirty");const j=`refs/remotes/origin/${v}`;if(!H(l,["show-ref","--verify","--quiet",j]))throw new Error("legacy-branch-origin-ref-missing");if(A(l,["show",`${j}:.neocortex/state.json`])!==a)throw new Error("legacy-branch-origin-state-mismatch");const F=`refs/heads/${I}`;if(H(l,["show-ref","--verify","--quiet",F]))throw new Error("legacy-branch-existing-ref-needs-review");return Object.freeze({schemaVersion:1,kind:"legacy-story-branch-plan",storyId:r.storyId,epicId:s,worktreePath:l,branch:I,baseBranch:v,baseHeadSha:o(l,["rev-parse",j]),currentHeadSha:o(l,["rev-parse","HEAD"]),existingBranchHeadSha:null,stateSha256:w("sha256").update(a).digest("hex"),localOnly:!0})}function C(r){try{return{ok:!0,value:se(r)}}catch(e){return i(e instanceof Error&&e.message.startsWith("legacy-branch-")?e.message:"legacy-branch-preflight-failed")}}async function ie(r){try{const e=y(r.projectRoot);if(y(o(e,["rev-parse","--show-toplevel"]))!==e||!/^[A-Za-z0-9][A-Za-z0-9_-]*\.[A-Za-z0-9._-]+$/.test(r.storyId))return i("legacy-branch-project-root-invalid");const t=await R(e,r.storyId);return t?await z(e,t)?{ok:!0,value:t}:i("legacy-branch-completion-missing"):i("legacy-branch-intent-missing")}catch(e){return i(e instanceof Error&&e.message.startsWith("legacy-branch-")?e.message:"legacy-branch-completion-read-failed")}}async function he(r){try{const e=y(r.projectRoot),t=await ie(r);if(!t.ok)return t;const a=t.value;if(a.epicId!==r.storyId.split(".")[0]||a.branch!==`story/${a.epicId}/${r.storyId}`||!m(e,a.branch)||!m(e,a.baseBranch)||y(a.worktreePath)!==a.worktreePath)return i("legacy-branch-intent-invalid");const c=W(e).filter(s=>s.branch===a.branch);if(c.length!==1||c[0].unsafe||y(c[0].path)!==a.worktreePath)return i("legacy-branch-story-worktree-mismatch");const n=a.worktreePath,u=s=>y(O(s,o(s,["rev-parse","--git-common-dir"])));if(u(n)!==u(e)||y(o(n,["rev-parse","--show-toplevel"]))!==n||o(n,["symbolic-ref","--quiet","--short","HEAD"])!==a.branch||o(n,["rev-parse","HEAD"])!==a.baseHeadSha||o(n,["rev-parse",`refs/heads/${a.branch}`])!==a.baseHeadSha||o(n,["rev-parse",`refs/remotes/origin/${a.baseBranch}`])!==a.baseHeadSha)return i("legacy-branch-physical-identity-mismatch");const h=b(d(n,".neocortex/state.json"));return w("sha256").update(h).digest("hex")!==a.stateSha256||A(n,["show","HEAD:.neocortex/state.json"])!==h||o(n,["status","--porcelain=v1","-uall"])!==""?i("legacy-branch-physical-state-mismatch"):{ok:!0,value:Object.freeze({...a,kind:"legacy-story-branch-setup-receipt",headSha:a.baseHeadSha,reused:!0,checkpointAccepted:!1})}}catch(e){return i(e instanceof Error&&e.message.startsWith("legacy-branch-")?e.message:"legacy-branch-verification-failed")}}async function ve(r){const e=C(r);if(!e.ok){if(e.reasonCode==="legacy-branch-epic-worktree-unavailable"){const c=await he(r);return c.ok?c:e}return e}const t=`legacy-setup-${V(16).toString("hex")}`,a=await Q(r.projectRoot,{kind:"direct",storyId:r.storyId,sessionId:t,idempotencyKey:t,expiresAt:new Date(Date.now()+5*6e4).toISOString(),persistent:!1});if(!a.ok)return i(a.reasonCode);try{const c=C(r);if(!c.ok||JSON.stringify(c.value)!==JSON.stringify(e.value))return i("legacy-branch-preflight-raced");const{worktreePath:n,branch:u,baseBranch:h}=c.value;await ce(r.projectRoot,c.value),o(n,["switch","-c",u,`refs/remotes/origin/${h}`]);const s=o(n,["rev-parse","HEAD"]);return o(n,["symbolic-ref","--quiet","--short","HEAD"])!==u||s!==c.value.baseHeadSha||o(n,["status","--porcelain=v1","-uall"])!==""||w("sha256").update(b(d(n,".neocortex/state.json"))).digest("hex")!==c.value.stateSha256?i("legacy-branch-post-switch-invalid"):(await oe(r.projectRoot,c.value),{ok:!0,value:Object.freeze({...c.value,kind:"legacy-story-branch-setup-receipt",headSha:s,reused:!1,checkpointAccepted:!1})})}catch(c){return i(c instanceof Error&&c.message.startsWith("legacy-branch-")?c.message:"legacy-branch-switch-failed")}finally{await re(a.path,a.owner).catch(()=>{})}}export{C as planLegacyStoryBranchSetup,ve as prepareLegacyStoryBranchSetup,ie as readCompletedLegacyStoryBranchPlan,he as verifyLegacyStoryBranchSetup};
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * Root-owned physical branch preparation for projects that recorded the
+ * legacy story-branch topology. It deliberately leaves state and story
+ * checkpoint acceptance to a separate root transaction.
+ */
+import { execFileSync } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { closeSync, constants, existsSync, fstatSync, openSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { resolveBranchUnit } from '../../../shared/dist/yoloop/branch-unit.js';
+import { acquireGitLifecyclePhysicalIntegrationLock, assertGitLifecyclePrivateFile, ensureGitLifecyclePrivateChildDirectory, gitLifecycleRuntimeDirectory, releaseGitLifecyclePhysicalIntegrationLock, } from './git-lifecycle-store.js';
+import { GIT_LIFECYCLE_SETUP_BRANCH_STEP_ID } from './git-lifecycle-step-ids.js';
+import { anchoredAtomicWriteFile } from './secure-filesystem-boundary.js';
+const INTENT_DIRECTORY = 'legacy-story-branch-intents';
+function intentName(storyId) {
+    return `${createHash('sha256').update(storyId).digest('hex')}.json`;
+}
+function completionName(storyId) {
+    return `${createHash('sha256').update(storyId).digest('hex')}.completed.json`;
+}
+function planDigest(plan) {
+    return createHash('sha256').update(JSON.stringify(plan)).digest('hex');
+}
+async function intentDirectory(projectRoot) {
+    return ensureGitLifecyclePrivateChildDirectory(await gitLifecycleRuntimeDirectory(projectRoot), INTENT_DIRECTORY);
+}
+function validatedIntent(value, storyId) {
+    const row = record(value);
+    if (!row || Object.keys(row).sort().join(',') !== [
+        'baseBranch', 'baseHeadSha', 'branch', 'currentHeadSha', 'epicId',
+        'existingBranchHeadSha', 'kind', 'localOnly', 'schemaVersion',
+        'stateSha256', 'storyId', 'worktreePath',
+    ].sort().join(',') || row.schemaVersion !== 1 || row.kind !== 'legacy-story-branch-plan'
+        || row.storyId !== storyId || row.localOnly !== true || row.existingBranchHeadSha !== null
+        || typeof row.epicId !== 'string' || typeof row.branch !== 'string'
+        || typeof row.baseBranch !== 'string' || typeof row.worktreePath !== 'string'
+        || ![row.baseHeadSha, row.currentHeadSha, row.stateSha256].every((item) => typeof item === 'string' && /^[0-9a-f]{40,64}$/.test(item))) {
+        throw new Error('legacy-branch-intent-invalid');
+    }
+    return row;
+}
+async function readIntent(projectRoot, storyId) {
+    const directory = await intentDirectory(projectRoot);
+    const path = join(directory, intentName(storyId));
+    if (!existsSync(path))
+        return null;
+    await assertGitLifecyclePrivateFile(path, directory);
+    const raw = readSafeState(path);
+    if (raw.length > 4096)
+        throw new Error('legacy-branch-intent-invalid');
+    return validatedIntent(JSON.parse(raw), storyId);
+}
+async function persistIntent(projectRoot, plan) {
+    const directory = await intentDirectory(projectRoot);
+    const prior = await readIntent(projectRoot, plan.storyId);
+    if (prior) {
+        if (JSON.stringify(prior) !== JSON.stringify(plan))
+            throw new Error('legacy-branch-intent-conflict');
+        return;
+    }
+    await anchoredAtomicWriteFile(directory, intentName(plan.storyId), `${JSON.stringify(plan)}\n`);
+    await assertGitLifecyclePrivateFile(join(directory, intentName(plan.storyId)), directory);
+}
+async function hasMatchingCompletion(projectRoot, plan) {
+    const directory = await intentDirectory(projectRoot);
+    const path = join(directory, completionName(plan.storyId));
+    if (!existsSync(path))
+        return false;
+    await assertGitLifecyclePrivateFile(path, directory);
+    const raw = readSafeState(path);
+    if (raw.length > 512)
+        throw new Error('legacy-branch-completion-invalid');
+    const row = record(JSON.parse(raw));
+    if (!row || Object.keys(row).sort().join(',') !== 'kind,planDigest,schemaVersion,storyId'
+        || row.schemaVersion !== 1 || row.kind !== 'legacy-story-branch-switch-completed'
+        || row.storyId !== plan.storyId || row.planDigest !== planDigest(plan)) {
+        throw new Error('legacy-branch-completion-invalid');
+    }
+    return true;
+}
+async function persistCompletion(projectRoot, plan) {
+    if (await hasMatchingCompletion(projectRoot, plan))
+        return;
+    const directory = await intentDirectory(projectRoot);
+    await anchoredAtomicWriteFile(directory, completionName(plan.storyId), `${JSON.stringify({
+        schemaVersion: 1, kind: 'legacy-story-branch-switch-completed',
+        storyId: plan.storyId, planDigest: planDigest(plan),
+    })}\n`);
+    await assertGitLifecyclePrivateFile(join(directory, completionName(plan.storyId)), directory);
+}
+function failure(reasonCode) {
+    return { ok: false, reasonCode };
+}
+function gitRaw(cwd, args) {
+    return execFileSync('git', [...args], { cwd, encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 4 * 1024 * 1024 });
+}
+function git(cwd, args) {
+    return gitRaw(cwd, args).trim();
+}
+function gitOk(cwd, args) {
+    try {
+        git(cwd, args);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value : null;
+}
+function safeBranch(cwd, name) {
+    return name.length > 0 && name.length <= 200 && !name.startsWith('-')
+        && !name.includes('..') && !name.includes('@{')
+        && gitOk(cwd, ['check-ref-format', '--branch', name]);
+}
+function readSafeState(path) {
+    const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > 2 * 1024 * 1024)
+            throw new Error('legacy-branch-state-unsafe');
+        return readFileSync(fd, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function worktrees(cwd) {
+    return git(cwd, ['worktree', 'list', '--porcelain']).split(/\n\n+/).flatMap((block) => {
+        const lines = block.split('\n');
+        const pathLine = lines.find((line) => line.startsWith('worktree '));
+        const branchLine = lines.find((line) => line.startsWith('branch refs/heads/'));
+        if (!pathLine || !branchLine)
+            return [];
+        return [{ path: pathLine.slice('worktree '.length),
+                branch: branchLine.slice('branch refs/heads/'.length),
+                unsafe: lines.some((line) => line.startsWith('prunable') || line.startsWith('locked')) }];
+    });
+}
+function inspect(options) {
+    const projectRoot = realpathSync(options.projectRoot);
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*\.[A-Za-z0-9._-]+$/.test(options.storyId)) {
+        throw new Error('legacy-branch-story-id-invalid');
+    }
+    if (realpathSync(git(projectRoot, ['rev-parse', '--show-toplevel'])) !== projectRoot) {
+        throw new Error('legacy-branch-project-root-invalid');
+    }
+    const statePath = join(projectRoot, '.neocortex/state.json');
+    const rawState = readSafeState(statePath);
+    const state = record(JSON.parse(rawState));
+    const stories = record(state?.stories);
+    const epics = record(state?.epics);
+    const story = record(stories?.[options.storyId]);
+    const epicId = story?.epic_id;
+    const epic = typeof epicId === 'string' ? record(epics?.[epicId]) : null;
+    if (!story || story.id !== options.storyId || typeof epicId !== 'string'
+        || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(epicId) || !epic || epic.id !== epicId) {
+        throw new Error('legacy-branch-story-state-invalid');
+    }
+    const epicStories = Object.entries(stories ?? {}).flatMap(([id, value]) => {
+        const row = record(value);
+        return row?.epic_id === epicId ? [{ ...row, id }] : [];
+    });
+    const branchUnit = resolveBranchUnit(epic, epicStories);
+    if (branchUnit.mode !== 'story' || epic.branch_mode === 'epic') {
+        throw new Error('legacy-branch-mode-invalid');
+    }
+    if (story.status !== 'backlog' && story.status !== 'ready_to_start') {
+        throw new Error('legacy-branch-story-status-invalid');
+    }
+    if (!Array.isArray(story.steps_completed)
+        || story.steps_completed.includes(GIT_LIFECYCLE_SETUP_BRANCH_STEP_ID) || story.branch_name) {
+        throw new Error('legacy-branch-story-already-started');
+    }
+    const config = record(state?.config);
+    const baseBranch = config?.default_branch;
+    const branch = `story/${epicId}/${options.storyId}`;
+    if (typeof baseBranch !== 'string' || !safeBranch(projectRoot, baseBranch)
+        || !safeBranch(projectRoot, branch) || !safeBranch(projectRoot, `epic/${epicId}`)) {
+        throw new Error('legacy-branch-ref-invalid');
+    }
+    const candidates = worktrees(projectRoot).filter((item) => item.branch === `epic/${epicId}`);
+    if (candidates.length !== 1 || candidates[0].unsafe)
+        throw new Error('legacy-branch-epic-worktree-unavailable');
+    const worktreePath = realpathSync(candidates[0].path);
+    if (typeof epic.worktree_path === 'string'
+        && realpathSync(resolve(projectRoot, epic.worktree_path)) !== worktreePath) {
+        throw new Error('legacy-branch-epic-worktree-mismatch');
+    }
+    const common = (cwd) => realpathSync(resolve(cwd, git(cwd, ['rev-parse', '--git-common-dir'])));
+    if (common(worktreePath) !== common(projectRoot)
+        || realpathSync(git(worktreePath, ['rev-parse', '--show-toplevel'])) !== worktreePath
+        || git(worktreePath, ['symbolic-ref', '--quiet', '--short', 'HEAD']) !== `epic/${epicId}`) {
+        throw new Error('legacy-branch-worktree-identity-invalid');
+    }
+    const worktreeStatePath = join(worktreePath, '.neocortex/state.json');
+    if (readSafeState(worktreeStatePath) !== rawState) {
+        throw new Error('legacy-branch-worktree-state-mismatch');
+    }
+    if (git(worktreePath, ['status', '--porcelain=v1', '-uall']) !== '') {
+        throw new Error('legacy-branch-worktree-dirty');
+    }
+    const baseRef = `refs/remotes/origin/${baseBranch}`;
+    if (!gitOk(worktreePath, ['show-ref', '--verify', '--quiet', baseRef])) {
+        throw new Error('legacy-branch-origin-ref-missing');
+    }
+    if (gitRaw(worktreePath, ['show', `${baseRef}:.neocortex/state.json`]) !== rawState) {
+        throw new Error('legacy-branch-origin-state-mismatch');
+    }
+    const existingRef = `refs/heads/${branch}`;
+    // A same-named ref is not a provenance receipt. It may belong to a previous
+    // attempt or another worktree, so manual reconciliation is required.
+    if (gitOk(worktreePath, ['show-ref', '--verify', '--quiet', existingRef])) {
+        throw new Error('legacy-branch-existing-ref-needs-review');
+    }
+    return Object.freeze({ schemaVersion: 1, kind: 'legacy-story-branch-plan',
+        storyId: options.storyId, epicId, worktreePath, branch, baseBranch,
+        baseHeadSha: git(worktreePath, ['rev-parse', baseRef]),
+        currentHeadSha: git(worktreePath, ['rev-parse', 'HEAD']),
+        existingBranchHeadSha: null, stateSha256: createHash('sha256').update(rawState).digest('hex'),
+        localOnly: true });
+}
+/** Read-only physical planning; no fetch, checkout, issue creation or state write. */
+export function planLegacyStoryBranchSetup(options) {
+    try {
+        return { ok: true, value: inspect(options) };
+    }
+    catch (error) {
+        return failure(error instanceof Error && error.message.startsWith('legacy-branch-')
+            ? error.message : 'legacy-branch-preflight-failed');
+    }
+}
+/** Local-only completion record; callers must still recompute physical truth. */
+export async function readCompletedLegacyStoryBranchPlan(options) {
+    try {
+        const projectRoot = realpathSync(options.projectRoot);
+        if (realpathSync(git(projectRoot, ['rev-parse', '--show-toplevel'])) !== projectRoot
+            || !/^[A-Za-z0-9][A-Za-z0-9_-]*\.[A-Za-z0-9._-]+$/.test(options.storyId)) {
+            return failure('legacy-branch-project-root-invalid');
+        }
+        const plan = await readIntent(projectRoot, options.storyId);
+        if (!plan)
+            return failure('legacy-branch-intent-missing');
+        if (!await hasMatchingCompletion(projectRoot, plan))
+            return failure('legacy-branch-completion-missing');
+        return { ok: true, value: plan };
+    }
+    catch (error) {
+        return failure(error instanceof Error && error.message.startsWith('legacy-branch-')
+            ? error.message : 'legacy-branch-completion-read-failed');
+    }
+}
+/** Proves a switched branch against the private intent durably written before switch. */
+export async function verifyLegacyStoryBranchSetup(options) {
+    try {
+        const projectRoot = realpathSync(options.projectRoot);
+        const completed = await readCompletedLegacyStoryBranchPlan(options);
+        if (!completed.ok)
+            return completed;
+        const plan = completed.value;
+        if (plan.epicId !== options.storyId.split('.')[0]
+            || plan.branch !== `story/${plan.epicId}/${options.storyId}`
+            || !safeBranch(projectRoot, plan.branch) || !safeBranch(projectRoot, plan.baseBranch)
+            || realpathSync(plan.worktreePath) !== plan.worktreePath) {
+            return failure('legacy-branch-intent-invalid');
+        }
+        const candidates = worktrees(projectRoot).filter((item) => item.branch === plan.branch);
+        if (candidates.length !== 1 || candidates[0].unsafe
+            || realpathSync(candidates[0].path) !== plan.worktreePath) {
+            return failure('legacy-branch-story-worktree-mismatch');
+        }
+        const cwd = plan.worktreePath;
+        const common = (path) => realpathSync(resolve(path, git(path, ['rev-parse', '--git-common-dir'])));
+        if (common(cwd) !== common(projectRoot)
+            || realpathSync(git(cwd, ['rev-parse', '--show-toplevel'])) !== cwd
+            || git(cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD']) !== plan.branch
+            || git(cwd, ['rev-parse', 'HEAD']) !== plan.baseHeadSha
+            || git(cwd, ['rev-parse', `refs/heads/${plan.branch}`]) !== plan.baseHeadSha
+            || git(cwd, ['rev-parse', `refs/remotes/origin/${plan.baseBranch}`]) !== plan.baseHeadSha) {
+            return failure('legacy-branch-physical-identity-mismatch');
+        }
+        const rawState = readSafeState(join(cwd, '.neocortex/state.json'));
+        if (createHash('sha256').update(rawState).digest('hex') !== plan.stateSha256
+            || gitRaw(cwd, ['show', 'HEAD:.neocortex/state.json']) !== rawState
+            || git(cwd, ['status', '--porcelain=v1', '-uall']) !== '') {
+            return failure('legacy-branch-physical-state-mismatch');
+        }
+        return { ok: true, value: Object.freeze({ ...plan,
+                kind: 'legacy-story-branch-setup-receipt', headSha: plan.baseHeadSha,
+                reused: true, checkpointAccepted: false }) };
+    }
+    catch (error) {
+        return failure(error instanceof Error && error.message.startsWith('legacy-branch-')
+            ? error.message : 'legacy-branch-verification-failed');
+    }
+}
+/** Switches only the proven epic worktree; root checkpoint acceptance is separate. */
+export async function prepareLegacyStoryBranchSetup(options) {
+    const initial = planLegacyStoryBranchSetup(options);
+    if (!initial.ok) {
+        if (initial.reasonCode === 'legacy-branch-epic-worktree-unavailable') {
+            const recovered = await verifyLegacyStoryBranchSetup(options);
+            return recovered.ok ? recovered : initial;
+        }
+        return initial;
+    }
+    const sessionId = `legacy-setup-${randomBytes(16).toString('hex')}`;
+    const lock = await acquireGitLifecyclePhysicalIntegrationLock(options.projectRoot, {
+        kind: 'direct', storyId: options.storyId, sessionId, idempotencyKey: sessionId,
+        expiresAt: new Date(Date.now() + 5 * 60_000).toISOString(), persistent: false,
+    });
+    if (!lock.ok)
+        return failure(lock.reasonCode);
+    try {
+        const checked = planLegacyStoryBranchSetup(options);
+        if (!checked.ok || JSON.stringify(checked.value) !== JSON.stringify(initial.value)) {
+            return failure('legacy-branch-preflight-raced');
+        }
+        const { worktreePath, branch, baseBranch } = checked.value;
+        await persistIntent(options.projectRoot, checked.value);
+        git(worktreePath, ['switch', '-c', branch, `refs/remotes/origin/${baseBranch}`]);
+        const headSha = git(worktreePath, ['rev-parse', 'HEAD']);
+        if (git(worktreePath, ['symbolic-ref', '--quiet', '--short', 'HEAD']) !== branch
+            || headSha !== checked.value.baseHeadSha
+            || git(worktreePath, ['status', '--porcelain=v1', '-uall']) !== ''
+            || createHash('sha256').update(readSafeState(join(worktreePath, '.neocortex/state.json'))).digest('hex')
+                !== checked.value.stateSha256) {
+            return failure('legacy-branch-post-switch-invalid');
+        }
+        await persistCompletion(options.projectRoot, checked.value);
+        return { ok: true, value: Object.freeze({ ...checked.value,
+                kind: 'legacy-story-branch-setup-receipt', headSha,
+                reused: false, checkpointAccepted: false }) };
+    }
+    catch (error) {
+        return failure(error instanceof Error && error.message.startsWith('legacy-branch-')
+            ? error.message : 'legacy-branch-switch-failed');
+    }
+    finally {
+        await releaseGitLifecyclePhysicalIntegrationLock(lock.path, lock.owner).catch(() => undefined);
+    }
+}