@ornexus/neocortex 4.60.71 → 4.60.73

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

@@ -1,9 +1,259 @@
-import{execFileSync as O}from"node:child_process";import{createHash as K,randomBytes as R}from"node:crypto";import{closeSync as G,constants as L,existsSync as Z,fstatSync as q,openSync as T,readFileSync as V,realpathSync as B}from"node:fs";import{join as k,resolve as Y}from"node:path";import{parseDocument as M}from"yaml";import{resolveBranchUnit as U}from"../../../shared/dist/yoloop/branch-unit.js";import{acquireGitLifecyclePhysicalIntegrationLock as Q,assertGitLifecyclePrivateFile as j,ensureGitLifecyclePrivateChildDirectory as X,gitLifecycleRuntimeDirectory as tt,releaseGitLifecyclePhysicalIntegrationLock as et}from"./git-lifecycle-store.js";import{GIT_LIFECYCLE_SETUP_BRANCH_STEP_ID as v}from"./git-lifecycle-step-ids.js";import{anchoredAtomicWriteFile as rt,anchoredCompareAndSwapFile as D}from"./secure-filesystem-boundary.js";import{readCompletedLegacyStoryBranchPlan as st}from"./legacy-story-branch-setup.js";function p(t){return{ok:!1,reasonCode:t}}function g(t){return K("sha256").update(t).digest("hex")}function S(t){return t&&typeof t=="object"&&!Array.isArray(t)?t:null}function l(t,c){return O("git",[...c],{cwd:t,encoding:"utf8",stdio:["ignore","pipe","pipe"],maxBuffer:4*1024*1024}).trim()}function C(t,c){return O("git",[...c],{cwd:t,encoding:"utf8",stdio:["ignore","pipe","pipe"],maxBuffer:4*1024*1024})}function $(t){const c=T(t,L.O_RDONLY|(L.O_NOFOLLOW??0));try{const e=q(c);if(!e.isFile()||e.size>2*1024*1024)throw new Error("legacy-branch-checkpoint-file-unsafe");return V(c,"utf8")}finally{G(c)}}function ct(t){const e=l(t,["remote","get-url","origin"]).match(/^(?:https:\/\/github\.com\/|git@github\.com:)([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?$/);if(!e||e[1].includes("..")||e[2].includes(".."))throw new Error("legacy-branch-issue-repository-invalid");return`${e[1]}/${e[2]}`}async function nt(t,c){const e=O("gh",["issue","view",String(c),"--repo",t,"--json","number,title,state,url"],{encoding:"utf8",timeout:15e3,stdio:["ignore","pipe","pipe"],maxBuffer:16384});return JSON.parse(e)}function ot(t,c,e,s,r){if(t.number!==s||t.title!==`[YOLO] Story ${e} - Workflow Run`||t.state!=="OPEN"&&!(r&&t.state==="CLOSED")||t.url.toLowerCase()!==`https://github.com/${c}/issues/${s}`.toLowerCase())throw new Error("legacy-branch-issue-evidence-invalid")}function at(t,c){const e=t.worktreePath,s=C(e,["show","HEAD:.neocortex/state.json"]);if(g(s)!==t.stateSha256)throw new Error("legacy-branch-checkpoint-base-state-mismatch");const r=S(JSON.parse(s)),h=S(r?.stories),o=S(r?.epics),a=S(h?.[t.storyId]),f=S(o?.[t.epicId]),i=Object.entries(h??{}).flatMap(([d,z])=>{const P=S(z);return P?.epic_id===t.epicId?[{...P,id:d}]:[]});if(!f||f.id!==t.epicId||f.branch_mode==="epic"||U(f,i).mode!=="story"||!a||a.id!==t.storyId||a.epic_id!==t.epicId||a.status!=="backlog"&&a.status!=="ready_to_start"||!Array.isArray(a.steps_completed)||a.steps_completed.length!==0||a.branch_name||a.issue_number||a.last_step)throw new Error("legacy-branch-checkpoint-state-conflict");a.status="branch-ready",a.steps_completed=[v],a.last_step=v,a.branch_name=t.branch,a.issue_number=c;const u=`${JSON.stringify(r,null,2)}
-`,b=`docs/stories/${t.storyId}.story.md`,y=C(e,["show",`HEAD:${b}`]),I=y.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);if(!I)throw new Error("legacy-branch-checkpoint-frontmatter-invalid");const n=M(I[1],{strict:!0,uniqueKeys:!0});if(n.errors.length>0||n.get("id")!==t.storyId||(n.get("epic_id")??n.get("epic"))!==t.epicId)throw new Error("legacy-branch-checkpoint-frontmatter-invalid");const w=S(n.toJS()),m=["stepsCompleted","steps_completed"].filter(d=>n.has(d)),A=["branchName","branch_name"].filter(d=>n.has(d)),_=["lastStep","last_step"].filter(d=>n.has(d)),N=["issueNumber","issue_number"].filter(d=>n.has(d));if(m.length>1||A.length>1||_.length>1||N.length>1||n.has("status")&&!["backlog","ready","ready_to_start"].includes(String(n.get("status")))||n.has("currentStatus")&&!["backlog","ready","ready_to_start"].includes(String(w?.currentStatus))||m.length===1&&(!Array.isArray(w?.[m[0]])||(w?.[m[0]]).length!==0)||A.length===1&&w?.[A[0]]!=null||_.length===1&&w?.[_[0]]!=null||N.length===1&&w?.[N[0]]!=null)throw new Error("legacy-branch-checkpoint-frontmatter-conflict");n.set("status","branch-ready"),n.has("currentStatus")&&n.set("currentStatus","branch-ready"),n.set(m[0]??"stepsCompleted",[v]),n.set(_[0]??"lastStep",v),n.set(A[0]??"branchName",t.branch),n.set(N[0]??"issueNumber",c);const F=`---
-${n.toString({lineWidth:0})}---
-${y.slice(I[0].length)}`;return{storyPath:b,stateBefore:s,stateAfter:u,storyBefore:y,storyAfter:F}}function E(t,c,e){const s=B(t.worktreePath);if(t.epicId!==t.storyId.split(".")[0]||t.branch!==`story/${t.epicId}/${t.storyId}`||!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(t.epicId)||!l(c,["check-ref-format","--branch",t.branch])||!l(c,["check-ref-format","--branch",t.baseBranch]))throw new Error("legacy-branch-checkpoint-plan-invalid");const r=i=>B(Y(i,l(i,["rev-parse","--git-common-dir"]))),h=l(c,["worktree","list","--porcelain"]).split(/\n\n+/).filter(i=>i.split(`
-`).includes(`branch refs/heads/${t.branch}`));if(s!==t.worktreePath||h.length!==1||!h[0].split(`
-`).includes(`worktree ${s}`)||h[0].split(`
-`).some(i=>i.startsWith("locked")||i.startsWith("prunable"))||r(s)!==r(c)||B(l(s,["rev-parse","--show-toplevel"]))!==s||l(s,["symbolic-ref","--quiet","--short","HEAD"])!==t.branch||l(s,["rev-parse","HEAD"])!==t.baseHeadSha||l(s,["rev-parse",`refs/heads/${t.branch}`])!==t.baseHeadSha||l(s,["rev-parse",`refs/remotes/origin/${t.baseBranch}`])!==t.baseHeadSha)throw new Error("legacy-branch-checkpoint-physical-mismatch");const o=$(k(s,".neocortex/state.json")),a=$(k(s,e.storyPath));if(![e.stateBefore,e.stateAfter].includes(o)||![e.storyBefore,e.storyAfter].includes(a))throw new Error("legacy-branch-checkpoint-preimage-conflict");if(C(s,["status","--porcelain=v1","-uall"]).split(`
-`).filter(Boolean).some(i=>{if(!i.startsWith(" M "))return!0;const u=i.slice(3);return u!==".neocortex/state.json"&&u!==e.storyPath}))throw new Error("legacy-branch-checkpoint-worktree-dirty");return{stateCurrent:o,storyCurrent:a}}async function it(t){return X(await tt(t),"legacy-story-branch-intents")}function x(t){return`${g(t)}.c01.json`}function J(t){return`${g(t)}.c01.accepted.json`}async function H(t,c){const e=k(t,c);if(!Z(e))return null;await j(e,t);const s=$(e);if(s.length>4096)throw new Error("legacy-branch-checkpoint-journal-invalid");return JSON.parse(s)}async function W(t,c,e){await rt(t,c,`${JSON.stringify(e)}
-`),await j(k(t,c),t)}async function wt(t){if(!Number.isSafeInteger(t.issueNumber)||t.issueNumber<=0)return p("legacy-branch-issue-number-invalid");const c=`legacy-c01-${R(16).toString("hex")}`,e=await Q(t.projectRoot,{kind:"direct",storyId:t.storyId,sessionId:c,idempotencyKey:c,expiresAt:new Date(Date.now()+5*6e4).toISOString(),persistent:!1});if(!e.ok)return p(e.reasonCode);try{const s=await st(t);if(!s.ok)return s;const r=s.value,h=B(t.projectRoot),o=at(r,t.issueNumber),a=E(r,h,o),f=ct(h),i=await it(h),u={schemaVersion:1,kind:"legacy-story-c01-acceptance-intent",storyId:r.storyId,planDigest:g(JSON.stringify(r)),repository:f,issueNumber:t.issueNumber,stateBefore:g(o.stateBefore),stateAfter:g(o.stateAfter),storyBefore:g(o.storyBefore),storyAfter:g(o.storyAfter)},b=await H(i,x(r.storyId));if(b&&JSON.stringify(b)!==JSON.stringify(u))return p("legacy-branch-checkpoint-journal-conflict");if(!b&&(a.stateCurrent!==o.stateBefore||a.storyCurrent!==o.storyBefore))return p("legacy-branch-checkpoint-unjournaled-drift");const y=await H(i,J(r.storyId));if(y&&JSON.stringify(y)!==JSON.stringify(u))return p("legacy-branch-checkpoint-accepted-conflict");const I=await(t.verifyIssue??nt)(f,t.issueNumber);ot(I,f,r.storyId,t.issueNumber,!!y),b||await W(i,x(r.storyId),u);const n=E(r,h,o);if(y&&(n.stateCurrent!==o.stateAfter||n.storyCurrent!==o.storyAfter))return p("legacy-branch-checkpoint-accepted-physical-mismatch");n.stateCurrent===o.stateBefore&&(await D(k(r.worktreePath,".neocortex"),"state.json",o.stateAfter,u.stateBefore),await t.afterStatePersist?.()),E(r,h,o).storyCurrent===o.storyBefore&&(await D(k(r.worktreePath,"docs/stories"),`${r.storyId}.story.md`,o.storyAfter,u.storyBefore),await t.afterStoryPersist?.());const m=E(r,h,o);return m.stateCurrent!==o.stateAfter||m.storyCurrent!==o.storyAfter?p("legacy-branch-checkpoint-post-write-mismatch"):(y||await W(i,J(r.storyId),u),{ok:!0,value:Object.freeze({schemaVersion:1,kind:"legacy-story-c01-checkpoint",storyId:r.storyId,epicId:r.epicId,branch:r.branch,issueNumber:t.issueNumber,repository:f,stateSha256:u.stateAfter,storySha256:u.storyAfter,reused:!!y,checkpointAccepted:!0,localOnly:!0})})}catch(s){const r=s instanceof Error?s.message:"";return p(r.startsWith("legacy-branch-")?r:r.includes("secure-filesystem-cas-conflict")?"legacy-branch-checkpoint-write-raced":"legacy-branch-checkpoint-failed")}finally{await et(e.path,e.owner).catch(()=>{})}}export{wt as acceptLegacyStoryBranchC01};
+/** Root-owned, replayable C01 checkpoint for explicitly recorded story branches. */
+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 { parseDocument } from 'yaml';
+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, anchoredCompareAndSwapFile } from './secure-filesystem-boundary.js';
+import { readCompletedLegacyStoryBranchPlan } from './legacy-story-branch-setup.js';
+function fail(reasonCode) { return { ok: false, reasonCode }; }
+function digest(value) { return createHash('sha256').update(value).digest('hex'); }
+function row(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function git(cwd, args) {
+    return execFileSync('git', [...args], { cwd, encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 4 * 1024 * 1024 }).trim();
+}
+function gitRaw(cwd, args) {
+    return execFileSync('git', [...args], { cwd, encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 4 * 1024 * 1024 });
+}
+function safeRead(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-checkpoint-file-unsafe');
+        return readFileSync(fd, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function repository(cwd) {
+    const remote = git(cwd, ['remote', 'get-url', 'origin']);
+    const match = remote.match(/^(?:https:\/\/github\.com\/|git@github\.com:)([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?$/);
+    if (!match || match[1].includes('..') || match[2].includes('..')) {
+        throw new Error('legacy-branch-issue-repository-invalid');
+    }
+    return `${match[1]}/${match[2]}`;
+}
+async function ghIssueVerifier(repo, number) {
+    const raw = execFileSync('gh', ['issue', 'view', String(number), '--repo', repo,
+        '--json', 'number,title,state,url'], { encoding: 'utf8', timeout: 15_000,
+        stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 16 * 1024 });
+    return JSON.parse(raw);
+}
+function validateIssue(issue, repo, storyId, number, replay) {
+    if (issue.number !== number || issue.title !== `[YOLO] Story ${storyId} - Workflow Run`
+        || (issue.state !== 'OPEN' && !(replay && issue.state === 'CLOSED'))
+        || issue.url.toLowerCase() !== `https://github.com/${repo}/issues/${number}`.toLowerCase()) {
+        throw new Error('legacy-branch-issue-evidence-invalid');
+    }
+}
+function project(plan, number) {
+    const cwd = plan.worktreePath;
+    const stateBefore = gitRaw(cwd, ['show', 'HEAD:.neocortex/state.json']);
+    if (digest(stateBefore) !== plan.stateSha256)
+        throw new Error('legacy-branch-checkpoint-base-state-mismatch');
+    const state = row(JSON.parse(stateBefore));
+    const stories = row(state?.stories);
+    const epics = row(state?.epics);
+    const story = row(stories?.[plan.storyId]);
+    const epic = row(epics?.[plan.epicId]);
+    const epicStories = Object.entries(stories ?? {}).flatMap(([id, value]) => {
+        const item = row(value);
+        return item?.epic_id === plan.epicId ? [{ ...item, id }] : [];
+    });
+    if (!epic || epic.id !== plan.epicId || epic.branch_mode === 'epic'
+        || resolveBranchUnit(epic, epicStories).mode !== 'story'
+        || !story || story.id !== plan.storyId || story.epic_id !== plan.epicId
+        || (story.status !== 'backlog' && story.status !== 'ready_to_start')
+        || !Array.isArray(story.steps_completed) || story.steps_completed.length !== 0
+        || story.branch_name || story.issue_number || story.last_step) {
+        throw new Error('legacy-branch-checkpoint-state-conflict');
+    }
+    story.status = 'branch-ready';
+    story.steps_completed = [GIT_LIFECYCLE_SETUP_BRANCH_STEP_ID];
+    story.last_step = GIT_LIFECYCLE_SETUP_BRANCH_STEP_ID;
+    story.branch_name = plan.branch;
+    story.issue_number = number;
+    const stateAfter = `${JSON.stringify(state, null, 2)}\n`;
+    const storyPath = `docs/stories/${plan.storyId}.story.md`;
+    const storyBefore = gitRaw(cwd, ['show', `HEAD:${storyPath}`]);
+    const frontmatter = storyBefore.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+    if (!frontmatter)
+        throw new Error('legacy-branch-checkpoint-frontmatter-invalid');
+    const document = parseDocument(frontmatter[1], { strict: true, uniqueKeys: true });
+    if (document.errors.length > 0 || document.get('id') !== plan.storyId
+        || (document.get('epic_id') ?? document.get('epic')) !== plan.epicId) {
+        throw new Error('legacy-branch-checkpoint-frontmatter-invalid');
+    }
+    const frontmatterData = row(document.toJS());
+    const stepKeys = ['stepsCompleted', 'steps_completed'].filter((key) => document.has(key));
+    const branchKeys = ['branchName', 'branch_name'].filter((key) => document.has(key));
+    const lastKeys = ['lastStep', 'last_step'].filter((key) => document.has(key));
+    const issueKeys = ['issueNumber', 'issue_number'].filter((key) => document.has(key));
+    if (stepKeys.length > 1 || branchKeys.length > 1 || lastKeys.length > 1 || issueKeys.length > 1
+        || (document.has('status') && !['backlog', 'ready', 'ready_to_start'].includes(String(document.get('status'))))
+        || (document.has('currentStatus')
+            && !['backlog', 'ready', 'ready_to_start'].includes(String(frontmatterData?.currentStatus)))
+        || (stepKeys.length === 1 && (!Array.isArray(frontmatterData?.[stepKeys[0]])
+            || (frontmatterData?.[stepKeys[0]]).length !== 0))
+        || (branchKeys.length === 1 && frontmatterData?.[branchKeys[0]] != null)
+        || (lastKeys.length === 1 && frontmatterData?.[lastKeys[0]] != null)
+        || (issueKeys.length === 1 && frontmatterData?.[issueKeys[0]] != null)) {
+        throw new Error('legacy-branch-checkpoint-frontmatter-conflict');
+    }
+    document.set('status', 'branch-ready');
+    if (document.has('currentStatus'))
+        document.set('currentStatus', 'branch-ready');
+    document.set(stepKeys[0] ?? 'stepsCompleted', [GIT_LIFECYCLE_SETUP_BRANCH_STEP_ID]);
+    document.set(lastKeys[0] ?? 'lastStep', GIT_LIFECYCLE_SETUP_BRANCH_STEP_ID);
+    document.set(branchKeys[0] ?? 'branchName', plan.branch);
+    document.set(issueKeys[0] ?? 'issueNumber', number);
+    const storyAfter = `---\n${document.toString({ lineWidth: 0 })}---\n${storyBefore.slice(frontmatter[0].length)}`;
+    return { storyPath, stateBefore, stateAfter, storyBefore, storyAfter };
+}
+function physical(plan, sourceRoot, projection) {
+    const cwd = realpathSync(plan.worktreePath);
+    if (plan.epicId !== plan.storyId.split('.')[0]
+        || plan.branch !== `story/${plan.epicId}/${plan.storyId}`
+        || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(plan.epicId)
+        || !git(sourceRoot, ['check-ref-format', '--branch', plan.branch])
+        || !git(sourceRoot, ['check-ref-format', '--branch', plan.baseBranch])) {
+        throw new Error('legacy-branch-checkpoint-plan-invalid');
+    }
+    const common = (path) => realpathSync(resolve(path, git(path, ['rev-parse', '--git-common-dir'])));
+    const worktrees = git(sourceRoot, ['worktree', 'list', '--porcelain']).split(/\n\n+/)
+        .filter((block) => block.split('\n').includes(`branch refs/heads/${plan.branch}`));
+    if (cwd !== plan.worktreePath || worktrees.length !== 1
+        || !worktrees[0].split('\n').includes(`worktree ${cwd}`)
+        || worktrees[0].split('\n').some((line) => line.startsWith('locked') || line.startsWith('prunable'))
+        || common(cwd) !== common(sourceRoot)
+        || 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) {
+        throw new Error('legacy-branch-checkpoint-physical-mismatch');
+    }
+    const stateCurrent = safeRead(join(cwd, '.neocortex/state.json'));
+    const storyCurrent = safeRead(join(cwd, projection.storyPath));
+    if (![projection.stateBefore, projection.stateAfter].includes(stateCurrent)
+        || ![projection.storyBefore, projection.storyAfter].includes(storyCurrent)) {
+        throw new Error('legacy-branch-checkpoint-preimage-conflict');
+    }
+    const statuses = gitRaw(cwd, ['status', '--porcelain=v1', '-uall']);
+    if (statuses.split('\n').filter(Boolean).some((line) => {
+        if (!line.startsWith(' M '))
+            return true;
+        const path = line.slice(3);
+        return path !== '.neocortex/state.json' && path !== projection.storyPath;
+    }))
+        throw new Error('legacy-branch-checkpoint-worktree-dirty');
+    return { stateCurrent, storyCurrent };
+}
+async function privateDirectory(projectRoot) {
+    return ensureGitLifecyclePrivateChildDirectory(await gitLifecycleRuntimeDirectory(projectRoot), 'legacy-story-branch-intents');
+}
+function journalName(storyId) { return `${digest(storyId)}.c01.json`; }
+function acceptedName(storyId) { return `${digest(storyId)}.c01.accepted.json`; }
+async function readPrivateJson(directory, name) {
+    const path = join(directory, name);
+    if (!existsSync(path))
+        return null;
+    await assertGitLifecyclePrivateFile(path, directory);
+    const raw = safeRead(path);
+    if (raw.length > 4096)
+        throw new Error('legacy-branch-checkpoint-journal-invalid');
+    return JSON.parse(raw);
+}
+async function writePrivateJson(directory, name, value) {
+    await anchoredAtomicWriteFile(directory, name, `${JSON.stringify(value)}\n`);
+    await assertGitLifecyclePrivateFile(join(directory, name), directory);
+}
+export async function acceptLegacyStoryBranchC01(options) {
+    if (!Number.isSafeInteger(options.issueNumber) || options.issueNumber <= 0) {
+        return fail('legacy-branch-issue-number-invalid');
+    }
+    const sessionId = `legacy-c01-${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 fail(lock.reasonCode);
+    try {
+        const completed = await readCompletedLegacyStoryBranchPlan(options);
+        if (!completed.ok)
+            return completed;
+        const plan = completed.value;
+        const sourceRoot = realpathSync(options.projectRoot);
+        const projection = project(plan, options.issueNumber);
+        const before = physical(plan, sourceRoot, projection);
+        const repo = repository(sourceRoot);
+        const directory = await privateDirectory(sourceRoot);
+        const journal = {
+            schemaVersion: 1, kind: 'legacy-story-c01-acceptance-intent', storyId: plan.storyId,
+            planDigest: digest(JSON.stringify(plan)), repository: repo, issueNumber: options.issueNumber,
+            stateBefore: digest(projection.stateBefore), stateAfter: digest(projection.stateAfter),
+            storyBefore: digest(projection.storyBefore), storyAfter: digest(projection.storyAfter),
+        };
+        const existing = await readPrivateJson(directory, journalName(plan.storyId));
+        if (existing && JSON.stringify(existing) !== JSON.stringify(journal)) {
+            return fail('legacy-branch-checkpoint-journal-conflict');
+        }
+        if (!existing && (before.stateCurrent !== projection.stateBefore
+            || before.storyCurrent !== projection.storyBefore)) {
+            return fail('legacy-branch-checkpoint-unjournaled-drift');
+        }
+        const accepted = await readPrivateJson(directory, acceptedName(plan.storyId));
+        if (accepted && JSON.stringify(accepted) !== JSON.stringify(journal)) {
+            return fail('legacy-branch-checkpoint-accepted-conflict');
+        }
+        const issue = await (options.verifyIssue ?? ghIssueVerifier)(repo, options.issueNumber);
+        validateIssue(issue, repo, plan.storyId, options.issueNumber, Boolean(accepted));
+        if (!existing)
+            await writePrivateJson(directory, journalName(plan.storyId), journal);
+        const beforeWrite = physical(plan, sourceRoot, projection);
+        if (accepted && (beforeWrite.stateCurrent !== projection.stateAfter
+            || beforeWrite.storyCurrent !== projection.storyAfter)) {
+            return fail('legacy-branch-checkpoint-accepted-physical-mismatch');
+        }
+        if (beforeWrite.stateCurrent === projection.stateBefore) {
+            await anchoredCompareAndSwapFile(join(plan.worktreePath, '.neocortex'), 'state.json', projection.stateAfter, journal.stateBefore);
+            await options.afterStatePersist?.();
+        }
+        const middle = physical(plan, sourceRoot, projection);
+        if (middle.storyCurrent === projection.storyBefore) {
+            await anchoredCompareAndSwapFile(join(plan.worktreePath, 'docs/stories'), `${plan.storyId}.story.md`, projection.storyAfter, journal.storyBefore);
+            await options.afterStoryPersist?.();
+        }
+        const after = physical(plan, sourceRoot, projection);
+        if (after.stateCurrent !== projection.stateAfter || after.storyCurrent !== projection.storyAfter) {
+            return fail('legacy-branch-checkpoint-post-write-mismatch');
+        }
+        if (!accepted)
+            await writePrivateJson(directory, acceptedName(plan.storyId), journal);
+        return { ok: true, value: Object.freeze({
+                schemaVersion: 1, kind: 'legacy-story-c01-checkpoint', storyId: plan.storyId,
+                epicId: plan.epicId, branch: plan.branch, issueNumber: options.issueNumber,
+                repository: repo, stateSha256: journal.stateAfter, storySha256: journal.storyAfter,
+                reused: Boolean(accepted), checkpointAccepted: true, localOnly: true,
+            }) };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : '';
+        return fail(message.startsWith('legacy-branch-') ? message
+            : message.includes('secure-filesystem-cas-conflict') ? 'legacy-branch-checkpoint-write-raced'
+                : 'legacy-branch-checkpoint-failed');
+    }
+    finally {
+        await releaseGitLifecyclePhysicalIntegrationLock(lock.path, lock.owner).catch(() => undefined);
+    }
+}