@ornexus/neocortex 4.60.71 → 4.60.73

package/packages/client/dist/commands/refactor-commit.js

@@ -1,13 +1,399 @@
-import{createHash as Q}from"node:crypto";import{closeSync as _,constants as E,existsSync as X,fsyncSync as W,lstatSync as V,openSync as P,readFileSync as q,realpathSync as K,writeFileSync as tt}from"node:fs";import{join as $,resolve as H}from"node:path";import{mutationQaGit as y}from"./mutation-qa-git.js";import{privateRefactorDirectory as x,readPrivateRefactorAdmission as F,refactorSidecarDigest as j,verifyRootRefactor as et}from"./refactor-root.js";import{readRootRefactorSemanticReview as rt}from"./refactor-review.js";const S=/^[a-f0-9]{64}$/,T=/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/;function w(o){return Q("sha256").update(o).digest("hex")}function g(o,e){return y(o,e).toString("utf8").trim()}function b(o,e){return y(o,e).toString("utf8").split("\0").filter(Boolean)}function I(o){return[...o].sort((e,r)=>Buffer.from(e).compare(Buffer.from(r)))}function N(o,e){return o!==null&&typeof o=="object"&&!Array.isArray(o)&&Object.keys(o).sort().join("\0")===[...e].sort().join("\0")}function R(o,e){const r=$(o,e),t=V(r);if(!t.isFile()||t.isSymbolicLink()||K(r)!==r||t.size<1||t.size>8*1024*1024)throw new Error("refactor-root-commit-physical-drift");const n=q(r);if(n.length!==t.size)throw new Error("refactor-root-commit-physical-drift");return Object.freeze({sha256:w(n),mode:t.mode&511})}function L(o,e){if(!S.test(e))throw new Error("refactor-root-commit-plan-invalid");return $(x(o),`commit-plan-${e}.json`)}function C(o,e){if(!S.test(e))throw new Error("refactor-root-commit-plan-invalid");return $(x(o),`commit-checkpoint-${e}.json`)}function v(o,e){const r=V(o);if(!r.isFile()||r.isSymbolicLink()||r.uid!==process.getuid?.()||(r.mode&63)!==0||r.size<100||r.size>e)throw new Error("refactor-root-commit-plan-invalid");const t=q(o);if(t.length!==r.size)throw new Error("refactor-root-commit-plan-invalid");return t}function Y(o,e,r){if(X(e)){if(!v(e,128*1024).equals(r))throw new Error("refactor-root-commit-plan-conflict");return}const t=P(e,E.O_WRONLY|E.O_CREAT|E.O_EXCL|(E.O_NOFOLLOW??0),384);try{tt(t,r),W(t)}finally{_(t)}const n=P(x(o),E.O_RDONLY|(E.O_DIRECTORY??0));try{W(n)}finally{_(n)}}function A(o,e){const r=v(L(o,e),131072);let t;try{t=JSON.parse(new TextDecoder("utf-8",{fatal:!0}).decode(r))}catch{throw new Error("refactor-root-commit-plan-invalid")}if(!N(t,["schemaVersion","kind","storyId","baseHead","branchRef","admissionSha256","baselineSha256","candidateSha256","reviewSha256","reviewRecordSha256","sidecarSha256","files","planSha256"])||t.schemaVersion!==1||t.kind!=="private-root-refactor-commit-plan"||typeof t.storyId!="string"||!/^P[0-9]+(?:\.[0-9]+)+$/.test(t.storyId)||typeof t.baseHead!="string"||!T.test(t.baseHead)||typeof t.branchRef!="string"||![`refs/heads/epic/${t.storyId.split(".")[0]}`,`refs/heads/story/${t.storyId.split(".")[0]}/${t.storyId}`].includes(t.branchRef)||![t.admissionSha256,t.baselineSha256,t.candidateSha256,t.reviewSha256,t.reviewRecordSha256,t.sidecarSha256].every(a=>typeof a=="string"&&S.test(a))||!Array.isArray(t.files)||t.files.length<2||t.files.length>256||!t.files.every(a=>N(a,["path","sha256","mode"])&&typeof a.path=="string"&&/^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(a.path)&&typeof a.sha256=="string"&&S.test(a.sha256)&&Number.isSafeInteger(a.mode)&&Number(a.mode)>=0&&Number(a.mode)<=511)||t.files.map(a=>a.path).join("\0")!==I(t.files.map(a=>a.path)).join("\0")||new Set(t.files.map(a=>a.path)).size!==t.files.length||t.planSha256!==e)throw new Error("refactor-root-commit-plan-invalid");const{planSha256:n,...c}=t;if(w(JSON.stringify(c))!==e||!r.equals(Buffer.from(`${JSON.stringify(t)}
-`)))throw new Error("refactor-root-commit-plan-invalid");const i=F(o,t.admissionSha256),m=new Set([...i.files.map(a=>a.path),...i.schemaVersion===2?i.newFiles.map(a=>a.path):[]]);if(i.storyId!==t.storyId||i.sourceHead!==t.baseHead||i.sidecarSha256!==t.sidecarSha256||t.files.some(a=>!m.has(a.path)))throw new Error("refactor-root-commit-plan-invalid");return t}function B(o,e){return $(x(o),`review-${e.admissionSha256}-${e.candidateSha256}.json`)}function G(o){return`refactor(${o}): characterized change`}function U(o){return`Neocortex-Refactor-Plan: ${o}`}function k(o){return g(o,["symbolic-ref","-q","HEAD"])}function ot(o){return b(o,["status","--porcelain=v1","-z","--untracked-files=all"]).every(e=>e.length>=4&&e[2]===" "&&e.slice(3).startsWith(".neocortex/"))}function it(o,e,r,t){if(!t)throw new Error("refactor-root-commit-authorization-required");try{const n=H(o),c=rt(n,e,r),i=F(n,e),m=et(n,e),a=k(n),s=i.storyId.split(".")[0];if(![`refs/heads/epic/${s}`,`refs/heads/story/${s}/${i.storyId}`].includes(a))throw new Error("refactor-root-commit-branch-invalid");const u=b(n,["diff","--name-only","-z","--no-ext-diff","--no-textconv"]),d=b(n,["ls-files","--others","--exclude-standard","-z"]),l=I([...u,...d].filter(f=>!f.startsWith(".neocortex/"))),h=new Set([...i.files.map(f=>f.path),...i.schemaVersion===2?i.newFiles.map(f=>f.path):[]]);if(l.length!==m.changedFileCount||l.some(f=>!h.has(f)))throw new Error("refactor-root-commit-delta-invalid");const p=l.map(f=>Object.freeze({path:f,...R(n,f)})),z=w(v(B(n,{admissionSha256:e,candidateSha256:c.candidateSha256}),128*1024)),D={schemaVersion:1,kind:"private-root-refactor-commit-plan",storyId:i.storyId,baseHead:i.sourceHead,branchRef:a,admissionSha256:e,baselineSha256:r,candidateSha256:c.candidateSha256,reviewSha256:c.reviewSha256,reviewRecordSha256:z,sidecarSha256:i.sidecarSha256,files:p},O=w(JSON.stringify(D)),M={...D,planSha256:O};if(g(n,["rev-parse","--verify","HEAD"])!==i.sourceHead||j(n)!==i.sidecarSha256||p.some(f=>{const J=R(n,f.path);return J.sha256!==f.sha256||J.mode!==f.mode}))throw new Error("refactor-root-commit-physical-drift");return Y(n,L(n,O),Buffer.from(`${JSON.stringify(M)}
-`)),A(n,O),Object.freeze({schemaVersion:1,kind:"root-refactor-commit-plan",storyId:i.storyId,baseHead:i.sourceHead,branchRef:a,planSha256:O,fileCount:p.length,commitSubject:G(i.storyId),commitTrailer:U(O),gitCommitAuthorized:!1,checkpointAccepted:!1,publicSafe:!0})}catch(n){throw n instanceof Error&&n.message.startsWith("refactor-root-commit-")?n:new Error("refactor-root-commit-unverified")}}function at(o,e){try{const r=H(o),t=A(r,e);if(k(r)!==t.branchRef||g(r,["rev-parse","--verify","HEAD"])!==t.baseHead||j(r)!==t.sidecarSha256||w(v(B(r,t),128*1024))!==t.reviewRecordSha256)throw new Error("refactor-root-commit-physical-drift");const n=I(b(r,["diff","--cached","--name-only","-z","--no-renames"])),c=t.files.map(a=>a.path),i=b(r,["diff","--name-only","-z","--no-renames"]).filter(a=>!a.startsWith(".neocortex/")),m=b(r,["ls-files","--others","--exclude-standard","-z"]).filter(a=>!a.startsWith(".neocortex/"));if(n.join("\0")!==c.join("\0")||i.length||m.length)throw new Error("refactor-root-commit-staged-invalid");for(const a of t.files){const u=y(r,["ls-files","--stage","-z","--",a.path]).toString("utf8").match(/^(100644|100755) [a-f0-9]{40,64} 0\t([^\0]+)\0$/);if(!u||u[2]!==a.path||u[1]!==(a.mode&73?"100755":"100644")||w(y(r,["show",`:${a.path}`]))!==a.sha256||R(r,a.path).sha256!==a.sha256||R(r,a.path).mode!==a.mode)throw new Error("refactor-root-commit-staged-invalid")}if(k(r)!==t.branchRef||g(r,["rev-parse","--verify","HEAD"])!==t.baseHead||j(r)!==t.sidecarSha256)throw new Error("refactor-root-commit-physical-drift");return Object.freeze({schemaVersion:1,kind:"root-refactor-staged-verification",planSha256:e,baseHead:t.baseHead,fileCount:t.files.length,stagedWriteSetSha256:w(JSON.stringify(t.files)),gitCommitAuthorized:!0,checkpointAccepted:!1,publicSafe:!0})}catch(r){throw r instanceof Error&&r.message.startsWith("refactor-root-commit-")?r:new Error("refactor-root-commit-unverified")}}function Z(o,e){const r=g(o,["rev-parse","--verify","HEAD"]),t=g(o,["show","-s","--format=%P",r]),n=y(o,["cat-file","commit",r]),c=n.indexOf(Buffer.from(`
-
-`)),i=c<0?Buffer.alloc(0):n.subarray(c+2),m=Buffer.from(`${G(e.storyId)}
-
-${U(e.planSha256)}
-`);if(!T.test(r)||t!==e.baseHead||!i.equals(m)||k(o)!==e.branchRef||!ot(o)||j(o)!==e.sidecarSha256||w(v(B(o,e),128*1024))!==e.reviewRecordSha256)throw new Error("refactor-root-commit-physical-drift");if(I(b(o,["diff-tree","--no-commit-id","--name-only","--no-renames","-r","-z",r])).join("\0")!==e.files.map(s=>s.path).join("\0"))throw new Error("refactor-root-commit-physical-drift");for(const s of e.files){const d=y(o,["ls-tree","-z",r,"--",s.path]).toString("utf8").match(/^(100644|100755) blob [a-f0-9]{40,64}\t([^\0]+)\0$/);if(!d||d[2]!==s.path||d[1]!==(s.mode&73?"100755":"100644")||w(y(o,["show",`${r}:${s.path}`]))!==s.sha256||R(o,s.path).sha256!==s.sha256||R(o,s.path).mode!==s.mode)throw new Error("refactor-root-commit-physical-drift")}if(g(o,["rev-parse","--verify","HEAD"])!==r||k(o)!==e.branchRef)throw new Error("refactor-root-commit-physical-drift");return r}function nt(o,e,r){if(!r)throw new Error("refactor-root-commit-authorization-required");try{const t=H(o),n=A(t,e),c=Z(t,n),i=Object.freeze({schemaVersion:1,kind:"root-refactor-commit-checkpoint",storyId:n.storyId,baseHead:n.baseHead,commitSha:c,branchRef:n.branchRef,planSha256:e,candidateSha256:n.candidateSha256,reviewSha256:n.reviewSha256,fileCount:n.files.length,checkpointAccepted:!0,graphExecution:"NOT_RUN",publicSafe:!0});if(Y(t,C(t,e),Buffer.from(`${JSON.stringify(i)}
-`)),!v(C(t,e),8*1024).equals(Buffer.from(`${JSON.stringify(i)}
-`)))throw new Error("refactor-root-commit-checkpoint-invalid");return i}catch(t){throw t instanceof Error&&t.message.startsWith("refactor-root-commit-")?t:new Error("refactor-root-commit-unverified")}}function ct(o,e){try{const r=H(o),t=A(r,e),n=Z(r,t),c=v(C(r,e),8*1024),i=JSON.parse(c.toString("utf8"));if(!N(i,["schemaVersion","kind","storyId","baseHead","commitSha","branchRef","planSha256","candidateSha256","reviewSha256","fileCount","checkpointAccepted","graphExecution","publicSafe"])||i.schemaVersion!==1||i.kind!=="root-refactor-commit-checkpoint"||i.commitSha!==n||i.planSha256!==e||i.storyId!==t.storyId||i.baseHead!==t.baseHead||i.branchRef!==t.branchRef||i.candidateSha256!==t.candidateSha256||i.reviewSha256!==t.reviewSha256||i.fileCount!==t.files.length||i.checkpointAccepted!==!0||i.graphExecution!=="NOT_RUN"||i.publicSafe!==!0||!c.equals(Buffer.from(`${JSON.stringify(i)}
-`)))throw new Error("refactor-root-commit-checkpoint-invalid");return i}catch{throw new Error("refactor-root-commit-checkpoint-invalid")}}function ut(o){const e=o[0];let r="",t="",n="",c="",i=!1,m=!1,a=!1,s="plain";const u=new Set;try{if(!["commit-plan","commit-staged","commit-seal","commit-status"].includes(e??""))throw new Error("refactor-root-commit-arguments-invalid");for(let l=1;l<o.length;l++){const h=o[l];if(u.has(h))throw new Error("refactor-root-commit-arguments-invalid");u.add(h);const p=()=>{const z=o[++l];if(!z||z.startsWith("--"))throw new Error("refactor-root-commit-arguments-invalid");return z};if(h==="--project-root")r=p();else if(h==="--admission-sha")t=p();else if(h==="--baseline-sha")n=p();else if(h==="--plan-sha")c=p();else if(h==="--authorize-run")i=!0;else if(h==="--authorize-root-commit-plan")m=!0;else if(h==="--authorize-root-seal")a=!0;else if(h==="--format")s=p();else throw new Error("refactor-root-commit-arguments-invalid")}if(!r||!["plain","json"].includes(s)||e==="commit-plan"&&(!S.test(t)||!S.test(n)||c||!i||!m||a)||e!=="commit-plan"&&(!S.test(c)||t||n||i||m||a!==(e==="commit-seal")))throw new Error("refactor-root-commit-arguments-invalid");const d=e==="commit-plan"?it(r,t,n,m):e==="commit-staged"?at(r,c):e==="commit-seal"?nt(r,c,a):ct(r,c);return process.stdout.write(`${JSON.stringify({ok:!0,result:d})}
-`),0}catch(d){const l=d instanceof Error&&/^refactor-root-[a-z-]+$/.test(d.message)?d.message:"refactor-root-commit-unverified";return process.stdout.write(`${JSON.stringify({ok:!1,reasonCode:l})}
-`),1}}export{it as prepareRootRefactorCommit,ct as readRootRefactorCommitCheckpoint,ut as refactorCommitCliHandler,nt as sealRootRefactorCommit,at as verifyRootRefactorStaged};
+/** Root-owned, two-phase Git checkpoint for an accepted characterized refactor. */
+import { createHash } from 'node:crypto';
+import { closeSync, constants, existsSync, fsyncSync, lstatSync, openSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { mutationQaGit } from './mutation-qa-git.js';
+import { privateRefactorDirectory, readPrivateRefactorAdmission, refactorSidecarDigest, verifyRootRefactor } from './refactor-root.js';
+import { readRootRefactorSemanticReview } from './refactor-review.js';
+const SHA256 = /^[a-f0-9]{64}$/;
+const GIT_SHA = /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/;
+function sha(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function git(root, args) {
+    return mutationQaGit(root, args).toString('utf8').trim();
+}
+function names(root, args) {
+    return mutationQaGit(root, args).toString('utf8').split('\0').filter(Boolean);
+}
+function ordered(paths) {
+    return [...paths].sort((a, b) => Buffer.from(a).compare(Buffer.from(b)));
+}
+function exact(value, keys) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        && Object.keys(value).sort().join('\0') === [...keys].sort().join('\0');
+}
+function physical(root, path) {
+    const target = join(root, path);
+    const stat = lstatSync(target);
+    if (!stat.isFile() || stat.isSymbolicLink() || realpathSync(target) !== target
+        || stat.size < 1 || stat.size > 8 * 1024 * 1024) {
+        throw new Error('refactor-root-commit-physical-drift');
+    }
+    const bytes = readFileSync(target);
+    if (bytes.length !== stat.size)
+        throw new Error('refactor-root-commit-physical-drift');
+    return Object.freeze({ sha256: sha(bytes), mode: stat.mode & 0o777 });
+}
+function planPath(root, planSha256) {
+    if (!SHA256.test(planSha256))
+        throw new Error('refactor-root-commit-plan-invalid');
+    return join(privateRefactorDirectory(root), `commit-plan-${planSha256}.json`);
+}
+function checkpointPath(root, planSha256) {
+    if (!SHA256.test(planSha256))
+        throw new Error('refactor-root-commit-plan-invalid');
+    return join(privateRefactorDirectory(root), `commit-checkpoint-${planSha256}.json`);
+}
+function privateBytes(path, maximum) {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.uid !== process.getuid?.()
+        || (stat.mode & 0o077) !== 0 || stat.size < 100 || stat.size > maximum) {
+        throw new Error('refactor-root-commit-plan-invalid');
+    }
+    const bytes = readFileSync(path);
+    if (bytes.length !== stat.size)
+        throw new Error('refactor-root-commit-plan-invalid');
+    return bytes;
+}
+function persist(root, path, bytes) {
+    if (existsSync(path)) {
+        if (!privateBytes(path, 128 * 1024).equals(bytes)) {
+            throw new Error('refactor-root-commit-plan-conflict');
+        }
+        return;
+    }
+    const handle = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL
+        | (constants.O_NOFOLLOW ?? 0), 0o600);
+    try {
+        writeFileSync(handle, bytes);
+        fsyncSync(handle);
+    }
+    finally {
+        closeSync(handle);
+    }
+    const directory = openSync(privateRefactorDirectory(root), constants.O_RDONLY
+        | (constants.O_DIRECTORY ?? 0));
+    try {
+        fsyncSync(directory);
+    }
+    finally {
+        closeSync(directory);
+    }
+}
+function readPlan(root, planSha256) {
+    const raw = privateBytes(planPath(root, planSha256), 128 * 1024);
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(raw));
+    }
+    catch {
+        throw new Error('refactor-root-commit-plan-invalid');
+    }
+    if (!exact(parsed, ['schemaVersion', 'kind', 'storyId', 'baseHead', 'branchRef',
+        'admissionSha256', 'baselineSha256', 'candidateSha256', 'reviewSha256',
+        'reviewRecordSha256', 'sidecarSha256', 'files', 'planSha256'])
+        || parsed.schemaVersion !== 1 || parsed.kind !== 'private-root-refactor-commit-plan'
+        || typeof parsed.storyId !== 'string' || !/^P[0-9]+(?:\.[0-9]+)+$/.test(parsed.storyId)
+        || typeof parsed.baseHead !== 'string' || !GIT_SHA.test(parsed.baseHead)
+        || typeof parsed.branchRef !== 'string'
+        || ![`refs/heads/epic/${parsed.storyId.split('.')[0]}`,
+            `refs/heads/story/${parsed.storyId.split('.')[0]}/${parsed.storyId}`].includes(parsed.branchRef)
+        || ![parsed.admissionSha256, parsed.baselineSha256, parsed.candidateSha256,
+            parsed.reviewSha256, parsed.reviewRecordSha256, parsed.sidecarSha256]
+            .every((value) => typeof value === 'string' && SHA256.test(value))
+        || !Array.isArray(parsed.files) || parsed.files.length < 2 || parsed.files.length > 256
+        || !parsed.files.every((file) => exact(file, ['path', 'sha256', 'mode'])
+            && typeof file.path === 'string' && /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(file.path)
+            && typeof file.sha256 === 'string' && SHA256.test(file.sha256)
+            && Number.isSafeInteger(file.mode) && Number(file.mode) >= 0 && Number(file.mode) <= 0o777)
+        || parsed.files.map((file) => file.path).join('\0')
+            !== ordered(parsed.files.map((file) => file.path)).join('\0')
+        || new Set(parsed.files.map((file) => file.path)).size !== parsed.files.length
+        || parsed.planSha256 !== planSha256) {
+        throw new Error('refactor-root-commit-plan-invalid');
+    }
+    const { planSha256: _digest, ...body } = parsed;
+    if (sha(JSON.stringify(body)) !== planSha256
+        || !raw.equals(Buffer.from(`${JSON.stringify(parsed)}\n`))) {
+        throw new Error('refactor-root-commit-plan-invalid');
+    }
+    const admission = readPrivateRefactorAdmission(root, parsed.admissionSha256);
+    const admitted = new Set([...admission.files.map((file) => file.path),
+        ...(admission.schemaVersion === 2 ? admission.newFiles.map((file) => file.path) : [])]);
+    if (admission.storyId !== parsed.storyId || admission.sourceHead !== parsed.baseHead
+        || admission.sidecarSha256 !== parsed.sidecarSha256
+        || parsed.files.some((file) => !admitted.has(file.path))) {
+        throw new Error('refactor-root-commit-plan-invalid');
+    }
+    return parsed;
+}
+function reviewRecordPath(root, plan) {
+    return join(privateRefactorDirectory(root), `review-${plan.admissionSha256}-${plan.candidateSha256}.json`);
+}
+function commitSubject(storyId) {
+    return `refactor(${storyId}): characterized change`;
+}
+function commitTrailer(planSha256) {
+    return `Neocortex-Refactor-Plan: ${planSha256}`;
+}
+function branch(root) {
+    return git(root, ['symbolic-ref', '-q', 'HEAD']);
+}
+function allowedDirty(root) {
+    return names(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all'])
+        .every((entry) => entry.length >= 4 && entry[2] === ' ' && entry.slice(3).startsWith('.neocortex/'));
+}
+export function prepareRootRefactorCommit(projectRoot, admissionSha256, baselineSha256, authorizeRootPlan) {
+    if (!authorizeRootPlan)
+        throw new Error('refactor-root-commit-authorization-required');
+    try {
+        const root = resolve(projectRoot);
+        const accepted = readRootRefactorSemanticReview(root, admissionSha256, baselineSha256);
+        const admission = readPrivateRefactorAdmission(root, admissionSha256);
+        const containment = verifyRootRefactor(root, admissionSha256);
+        const branchRef = branch(root);
+        const epicId = admission.storyId.split('.')[0];
+        if (![`refs/heads/epic/${epicId}`,
+            `refs/heads/story/${epicId}/${admission.storyId}`].includes(branchRef)) {
+            throw new Error('refactor-root-commit-branch-invalid');
+        }
+        const tracked = names(root, ['diff', '--name-only', '-z', '--no-ext-diff', '--no-textconv']);
+        const untracked = names(root, ['ls-files', '--others', '--exclude-standard', '-z']);
+        const paths = ordered([...tracked, ...untracked].filter((path) => !path.startsWith('.neocortex/')));
+        const admitted = new Set([...admission.files.map((file) => file.path),
+            ...(admission.schemaVersion === 2 ? admission.newFiles.map((file) => file.path) : [])]);
+        if (paths.length !== containment.changedFileCount || paths.some((path) => !admitted.has(path))) {
+            throw new Error('refactor-root-commit-delta-invalid');
+        }
+        const files = paths.map((path) => Object.freeze({ path, ...physical(root, path) }));
+        const reviewRecordSha256 = sha(privateBytes(reviewRecordPath(root, {
+            admissionSha256, candidateSha256: accepted.candidateSha256,
+        }), 128 * 1024));
+        const body = { schemaVersion: 1, kind: 'private-root-refactor-commit-plan',
+            storyId: admission.storyId, baseHead: admission.sourceHead, branchRef,
+            admissionSha256, baselineSha256, candidateSha256: accepted.candidateSha256,
+            reviewSha256: accepted.reviewSha256, reviewRecordSha256,
+            sidecarSha256: admission.sidecarSha256, files };
+        const planSha256 = sha(JSON.stringify(body));
+        const record = { ...body, planSha256 };
+        if (git(root, ['rev-parse', '--verify', 'HEAD']) !== admission.sourceHead
+            || refactorSidecarDigest(root) !== admission.sidecarSha256
+            || files.some((file) => {
+                const current = physical(root, file.path);
+                return current.sha256 !== file.sha256 || current.mode !== file.mode;
+            })) {
+            throw new Error('refactor-root-commit-physical-drift');
+        }
+        persist(root, planPath(root, planSha256), Buffer.from(`${JSON.stringify(record)}\n`));
+        readPlan(root, planSha256);
+        return Object.freeze({ schemaVersion: 1, kind: 'root-refactor-commit-plan',
+            storyId: admission.storyId, baseHead: admission.sourceHead, branchRef,
+            planSha256, fileCount: files.length, commitSubject: commitSubject(admission.storyId),
+            commitTrailer: commitTrailer(planSha256), gitCommitAuthorized: false,
+            checkpointAccepted: false, publicSafe: true });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('refactor-root-commit-'))
+            throw error;
+        throw new Error('refactor-root-commit-unverified');
+    }
+}
+export function verifyRootRefactorStaged(projectRoot, planSha256) {
+    try {
+        const root = resolve(projectRoot);
+        const plan = readPlan(root, planSha256);
+        if (branch(root) !== plan.branchRef || git(root, ['rev-parse', '--verify', 'HEAD']) !== plan.baseHead
+            || refactorSidecarDigest(root) !== plan.sidecarSha256
+            || sha(privateBytes(reviewRecordPath(root, plan), 128 * 1024)) !== plan.reviewRecordSha256) {
+            throw new Error('refactor-root-commit-physical-drift');
+        }
+        const staged = ordered(names(root, ['diff', '--cached', '--name-only', '-z', '--no-renames']));
+        const expected = plan.files.map((file) => file.path);
+        const unstaged = names(root, ['diff', '--name-only', '-z', '--no-renames'])
+            .filter((path) => !path.startsWith('.neocortex/'));
+        const untracked = names(root, ['ls-files', '--others', '--exclude-standard', '-z'])
+            .filter((path) => !path.startsWith('.neocortex/'));
+        if (staged.join('\0') !== expected.join('\0') || unstaged.length || untracked.length) {
+            throw new Error('refactor-root-commit-staged-invalid');
+        }
+        for (const file of plan.files) {
+            const index = mutationQaGit(root, ['ls-files', '--stage', '-z', '--', file.path]).toString('utf8');
+            const match = index.match(/^(100644|100755) [a-f0-9]{40,64} 0\t([^\0]+)\0$/);
+            if (!match || match[2] !== file.path
+                || match[1] !== ((file.mode & 0o111) ? '100755' : '100644')
+                || sha(mutationQaGit(root, ['show', `:${file.path}`])) !== file.sha256
+                || physical(root, file.path).sha256 !== file.sha256
+                || physical(root, file.path).mode !== file.mode) {
+                throw new Error('refactor-root-commit-staged-invalid');
+            }
+        }
+        if (branch(root) !== plan.branchRef || git(root, ['rev-parse', '--verify', 'HEAD']) !== plan.baseHead
+            || refactorSidecarDigest(root) !== plan.sidecarSha256) {
+            throw new Error('refactor-root-commit-physical-drift');
+        }
+        return Object.freeze({ schemaVersion: 1, kind: 'root-refactor-staged-verification',
+            planSha256, baseHead: plan.baseHead, fileCount: plan.files.length,
+            stagedWriteSetSha256: sha(JSON.stringify(plan.files)), gitCommitAuthorized: true,
+            checkpointAccepted: false, publicSafe: true });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('refactor-root-commit-'))
+            throw error;
+        throw new Error('refactor-root-commit-unverified');
+    }
+}
+function physicalCommit(root, plan) {
+    const head = git(root, ['rev-parse', '--verify', 'HEAD']);
+    const parents = git(root, ['show', '-s', '--format=%P', head]);
+    const object = mutationQaGit(root, ['cat-file', 'commit', head]);
+    const bodyOffset = object.indexOf(Buffer.from('\n\n'));
+    const message = bodyOffset < 0 ? Buffer.alloc(0) : object.subarray(bodyOffset + 2);
+    const expectedMessage = Buffer.from(`${commitSubject(plan.storyId)}\n\n${commitTrailer(plan.planSha256)}\n`);
+    if (!GIT_SHA.test(head) || parents !== plan.baseHead || !message.equals(expectedMessage)
+        || branch(root) !== plan.branchRef || !allowedDirty(root)
+        || refactorSidecarDigest(root) !== plan.sidecarSha256
+        || sha(privateBytes(reviewRecordPath(root, plan), 128 * 1024)) !== plan.reviewRecordSha256) {
+        throw new Error('refactor-root-commit-physical-drift');
+    }
+    const changed = ordered(names(root, ['diff-tree', '--no-commit-id', '--name-only',
+        '--no-renames', '-r', '-z', head]));
+    if (changed.join('\0') !== plan.files.map((file) => file.path).join('\0')) {
+        throw new Error('refactor-root-commit-physical-drift');
+    }
+    for (const file of plan.files) {
+        const entry = mutationQaGit(root, ['ls-tree', '-z', head, '--', file.path]).toString('utf8');
+        const match = entry.match(/^(100644|100755) blob [a-f0-9]{40,64}\t([^\0]+)\0$/);
+        if (!match || match[2] !== file.path
+            || match[1] !== ((file.mode & 0o111) ? '100755' : '100644')
+            || sha(mutationQaGit(root, ['show', `${head}:${file.path}`])) !== file.sha256
+            || physical(root, file.path).sha256 !== file.sha256
+            || physical(root, file.path).mode !== file.mode) {
+            throw new Error('refactor-root-commit-physical-drift');
+        }
+    }
+    if (git(root, ['rev-parse', '--verify', 'HEAD']) !== head || branch(root) !== plan.branchRef) {
+        throw new Error('refactor-root-commit-physical-drift');
+    }
+    return head;
+}
+export function sealRootRefactorCommit(projectRoot, planSha256, authorizeRootSeal) {
+    if (!authorizeRootSeal)
+        throw new Error('refactor-root-commit-authorization-required');
+    try {
+        const root = resolve(projectRoot);
+        const plan = readPlan(root, planSha256);
+        const commitSha = physicalCommit(root, plan);
+        const receipt = Object.freeze({ schemaVersion: 1,
+            kind: 'root-refactor-commit-checkpoint', storyId: plan.storyId,
+            baseHead: plan.baseHead, commitSha, branchRef: plan.branchRef,
+            planSha256, candidateSha256: plan.candidateSha256, reviewSha256: plan.reviewSha256,
+            fileCount: plan.files.length, checkpointAccepted: true,
+            graphExecution: 'NOT_RUN', publicSafe: true });
+        persist(root, checkpointPath(root, planSha256), Buffer.from(`${JSON.stringify(receipt)}\n`));
+        if (!privateBytes(checkpointPath(root, planSha256), 8 * 1024)
+            .equals(Buffer.from(`${JSON.stringify(receipt)}\n`))) {
+            throw new Error('refactor-root-commit-checkpoint-invalid');
+        }
+        return receipt;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('refactor-root-commit-'))
+            throw error;
+        throw new Error('refactor-root-commit-unverified');
+    }
+}
+export function readRootRefactorCommitCheckpoint(projectRoot, planSha256) {
+    try {
+        const root = resolve(projectRoot);
+        const plan = readPlan(root, planSha256);
+        const commitSha = physicalCommit(root, plan);
+        const bytes = privateBytes(checkpointPath(root, planSha256), 8 * 1024);
+        const receipt = JSON.parse(bytes.toString('utf8'));
+        if (!exact(receipt, ['schemaVersion', 'kind', 'storyId', 'baseHead', 'commitSha',
+            'branchRef', 'planSha256', 'candidateSha256', 'reviewSha256', 'fileCount',
+            'checkpointAccepted', 'graphExecution', 'publicSafe'])
+            || receipt.schemaVersion !== 1 || receipt.kind !== 'root-refactor-commit-checkpoint'
+            || receipt.commitSha !== commitSha || receipt.planSha256 !== planSha256
+            || receipt.storyId !== plan.storyId || receipt.baseHead !== plan.baseHead
+            || receipt.branchRef !== plan.branchRef || receipt.candidateSha256 !== plan.candidateSha256
+            || receipt.reviewSha256 !== plan.reviewSha256 || receipt.fileCount !== plan.files.length
+            || receipt.checkpointAccepted !== true || receipt.graphExecution !== 'NOT_RUN'
+            || receipt.publicSafe !== true || !bytes.equals(Buffer.from(`${JSON.stringify(receipt)}\n`))) {
+            throw new Error('refactor-root-commit-checkpoint-invalid');
+        }
+        return receipt;
+    }
+    catch {
+        throw new Error('refactor-root-commit-checkpoint-invalid');
+    }
+}
+export function refactorCommitCliHandler(args) {
+    const action = args[0];
+    let projectRoot = '';
+    let admissionSha256 = '';
+    let baselineSha256 = '';
+    let planSha256 = '';
+    let authorizeRun = false;
+    let authorizePlan = false;
+    let authorizeSeal = false;
+    let format = 'plain';
+    const seen = new Set();
+    try {
+        if (!['commit-plan', 'commit-staged', 'commit-seal', 'commit-status'].includes(action ?? '')) {
+            throw new Error('refactor-root-commit-arguments-invalid');
+        }
+        for (let index = 1; index < args.length; index++) {
+            const token = args[index];
+            if (seen.has(token))
+                throw new Error('refactor-root-commit-arguments-invalid');
+            seen.add(token);
+            const next = () => {
+                const value = args[++index];
+                if (!value || value.startsWith('--'))
+                    throw new Error('refactor-root-commit-arguments-invalid');
+                return value;
+            };
+            if (token === '--project-root')
+                projectRoot = next();
+            else if (token === '--admission-sha')
+                admissionSha256 = next();
+            else if (token === '--baseline-sha')
+                baselineSha256 = next();
+            else if (token === '--plan-sha')
+                planSha256 = next();
+            else if (token === '--authorize-run')
+                authorizeRun = true;
+            else if (token === '--authorize-root-commit-plan')
+                authorizePlan = true;
+            else if (token === '--authorize-root-seal')
+                authorizeSeal = true;
+            else if (token === '--format')
+                format = next();
+            else
+                throw new Error('refactor-root-commit-arguments-invalid');
+        }
+        if (!projectRoot || !['plain', 'json'].includes(format)
+            || (action === 'commit-plan' && (!SHA256.test(admissionSha256)
+                || !SHA256.test(baselineSha256) || planSha256 || !authorizeRun
+                || !authorizePlan || authorizeSeal))
+            || (action !== 'commit-plan' && (!SHA256.test(planSha256)
+                || admissionSha256 || baselineSha256 || authorizeRun || authorizePlan
+                || authorizeSeal !== (action === 'commit-seal')))) {
+            throw new Error('refactor-root-commit-arguments-invalid');
+        }
+        const result = action === 'commit-plan'
+            ? prepareRootRefactorCommit(projectRoot, admissionSha256, baselineSha256, authorizePlan)
+            : action === 'commit-staged' ? verifyRootRefactorStaged(projectRoot, planSha256)
+                : action === 'commit-seal' ? sealRootRefactorCommit(projectRoot, planSha256, authorizeSeal)
+                    : readRootRefactorCommitCheckpoint(projectRoot, planSha256);
+        process.stdout.write(`${JSON.stringify({ ok: true, result })}\n`);
+        return 0;
+    }
+    catch (error) {
+        const reasonCode = error instanceof Error && /^refactor-root-[a-z-]+$/.test(error.message)
+            ? error.message : 'refactor-root-commit-unverified';
+        process.stdout.write(`${JSON.stringify({ ok: false, reasonCode })}\n`);
+        return 1;
+    }
+}

package/packages/client/dist/commands/refactor-control.js

@@ -1,3 +1,142 @@
-import{lstatSync as S,readFileSync as v,realpathSync as R}from"node:fs";import{join as w,resolve as g}from"node:path";import{signNxInvokeRequest as k}from"../../../shared/dist/nx-invoke-signature.js";import{COMMAND_REGISTRY_VERSION as q,COMMAND_REGISTRY_CHECKSUM as C}from"../generated/command-registry.generated.js";import{CLIENT_VERSION as N}from"../version.js";import{loadSecureConfig as b}from"../config/secure-config.js";import{neocortexProfileDirectory as _}from"../config/profile-directory.js";import{EncryptedCache as A}from"../cache/encrypted-cache.js";import{LicenseClient as T}from"../license/license-client.js";import{detectPlatform as I}from"../adapters/platform-detector.js";const y=new Set(["refactor-control-input-invalid","refactor-control-auth-required","refactor-control-tier-required","refactor-control-read-only","refactor-control-signature-required","refactor-control-client-unsupported","refactor-control-registry-mismatch","refactor-control-executor-unavailable"]),L=new Set(["arguments-invalid","authorization-required","host-unsupported","project-unbound","auth-required","response-invalid","request-refused","outcome-unknown"].map(e=>`refactor-root-control-${e}`));async function j(e){const o=e.body?.getReader();if(!o)throw new Error("refactor-root-control-response-invalid");let n=!1;try{const t=[];let c=0;for(;;){const a=await o.read();if(a.done){n=!0;break}if(c+=a.value.byteLength,c>16384)throw new Error("refactor-root-control-response-invalid");t.push(Buffer.from(a.value))}return JSON.parse(new TextDecoder("utf-8",{fatal:!0}).decode(Buffer.concat(t,c)))}catch{throw new Error("refactor-root-control-response-invalid")}finally{n||await o.cancel().catch(()=>{}),o.releaseLock()}}async function E(e,o,n=fetch){if(e!=="refactor"&&e!=="qa")throw new Error("refactor-root-control-arguments-invalid");const t=`/api/v1/invoke/${e}/control`,c=k({method:"POST",target:t,body:Buffer.from(JSON.stringify({projectId:o.projectId,storyId:o.storyId,platformTarget:o.platformTarget,registryVersion:q,registryChecksum:C})),bearerToken:o.token,clientVersion:N}),a=await n(`${o.serverUrl.replace(/\/+$/,"")}${t}`,{method:"POST",redirect:"error",signal:AbortSignal.timeout(2e5),headers:{...c.headers,Authorization:`Bearer ${o.token}`},body:c.body}),r=await j(a);if(!a.ok)throw new Error(typeof r?.error_code=="string"&&y.has(r.error_code.replace(/^qa-/,"refactor-"))&&r.error_code.startsWith(`${e}-`)?r.error_code:"refactor-root-control-request-refused");const l=["schemaVersion","kind","status","completedStages","authority","qaAccepted","gitAuthority","billingAuthority","publicSafe"];if(!r||typeof r!="object"||Array.isArray(r)||Object.keys(r).some(s=>!l.includes(s))||r.schemaVersion!==1||r.kind!==`root-${e}-control`||typeof r.status!="string"||!["advanced","waiting","blocked","candidate-ready",...e==="qa"?["debt"]:[]].includes(r.status)||r.authority!==(e==="qa"?"LOCAL_ROOT_QA_CANDIDATE_ONLY":"LOCAL_ROOT_CANDIDATE_ONLY")||r.qaAccepted!==!1||r.gitAuthority!=="NONE"||r.billingAuthority!=="NONE"||r.publicSafe!==!0||r.completedStages!==void 0&&(typeof r.completedStages!="number"||!Number.isInteger(r.completedStages)||r.completedStages<0||r.completedStages>(e==="qa"?3:7)))throw new Error("refactor-root-control-response-invalid");return r}async function B(e,o=fetch){return E("refactor",e,o)}async function Y(e,o="refactor"){try{let n="",t="",c=!1,a="json";const r=[...e];if(r.shift()!=="control")throw new Error("refactor-root-control-arguments-invalid");for(let i=0;i<r.length;i++){const d=r[i];if(d==="--authorize-root-control")c=!0;else if(d==="--project-root")n=r[++i]??"";else if(d==="--story")t=r[++i]??"";else if(d==="--format")a=r[++i]??"";else throw new Error("refactor-root-control-arguments-invalid")}if(!c||!n||a!=="json"||!/^P[0-9]{1,12}(?:\.[0-9]{1,12}){1,3}$/.test(t))throw new Error("refactor-root-control-authorization-required");const l=I({cwd:g(n),env:process.env}).targetId;if(l!=="codex")throw new Error("refactor-root-control-host-unsupported");const s=w(g(n),".neocortex","state.json"),u=S(s);if(!u.isFile()||u.isSymbolicLink()||R(s)!==s||u.size>16*1024*1024)throw new Error("refactor-root-control-project-unbound");const p=JSON.parse(v(s,"utf8")).config?.project_id;if(typeof p!="string"||!/^[A-Za-z0-9][A-Za-z0-9_-]{15,127}$/.test(p))throw new Error("refactor-root-control-project-unbound");const f=b({strictReadOnly:!0});if(!f?.licenseKey)throw new Error("refactor-root-control-auth-required");const h=process.env.NEOCORTEX_SERVER_URL??f.serverUrl;if(!h)throw new Error("refactor-root-control-auth-required");const m=await new T({serverUrl:h,licenseKey:f.licenseKey,cacheProvider:new A({cacheDir:w(_(),"cache"),passphrase:f.licenseKey})}).getToken();if(!m)throw new Error("refactor-root-control-auth-required");const O=await E(o,{serverUrl:h,token:m,projectId:p,storyId:t,platformTarget:l});return process.stdout.write(`${JSON.stringify({ok:!0,control:O})}
-`),0}catch(n){const t=n instanceof Error?n.message.replace(/^qa-/,"refactor-"):"",c=L.has(t)||y.has(t)?t:"refactor-root-control-outcome-unknown";return process.stdout.write(`${JSON.stringify({ok:!1,reasonCode:o==="qa"?c.replace(/^refactor-/,"qa-"):c})}
-`),1}}export{Y as refactorControlCliHandler,B as requestRefactorControl,E as requestRootControl};
+/** Mechanical authenticated control transport; workflow decisions stay server-side. */
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { signNxInvokeRequest } from '../../../shared/dist/nx-invoke-signature.js';
+import { COMMAND_REGISTRY_VERSION, COMMAND_REGISTRY_CHECKSUM } from '../generated/command-registry.generated.js';
+import { CLIENT_VERSION } from '../version.js';
+import { loadSecureConfig } from '../config/secure-config.js';
+import { neocortexProfileDirectory } from '../config/profile-directory.js';
+import { EncryptedCache } from '../cache/encrypted-cache.js';
+import { LicenseClient } from '../license/license-client.js';
+import { detectPlatform } from '../adapters/platform-detector.js';
+const CONTROL_ERRORS = new Set([
+    'refactor-control-input-invalid', 'refactor-control-auth-required',
+    'refactor-control-tier-required', 'refactor-control-read-only',
+    'refactor-control-signature-required', 'refactor-control-client-unsupported',
+    'refactor-control-registry-mismatch', 'refactor-control-executor-unavailable',
+]);
+const CLIENT_CONTROL_ERRORS = new Set(['arguments-invalid', 'authorization-required', 'host-unsupported',
+    'project-unbound', 'auth-required', 'response-invalid', 'request-refused', 'outcome-unknown']
+    .map(code => `refactor-root-control-${code}`));
+/** Enforce the byte budget while receiving; do not buffer an unbounded body. */
+async function readControlResponse(response) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('refactor-root-control-response-invalid');
+    let complete = false;
+    try {
+        const chunks = [];
+        let size = 0;
+        for (;;) {
+            const next = await reader.read();
+            if (next.done) {
+                complete = true;
+                break;
+            }
+            size += next.value.byteLength;
+            if (size > 16384)
+                throw new Error('refactor-root-control-response-invalid');
+            chunks.push(Buffer.from(next.value));
+        }
+        return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks, size)));
+    }
+    catch {
+        throw new Error('refactor-root-control-response-invalid');
+    }
+    finally {
+        if (!complete)
+            await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}
+export async function requestRootControl(family, input, fetchFn = fetch) {
+    if (family !== 'refactor' && family !== 'qa')
+        throw new Error('refactor-root-control-arguments-invalid');
+    const target = `/api/v1/invoke/${family}/control`;
+    const attempt = signNxInvokeRequest({ method: 'POST', target,
+        body: Buffer.from(JSON.stringify({ projectId: input.projectId, storyId: input.storyId,
+            platformTarget: input.platformTarget, registryVersion: COMMAND_REGISTRY_VERSION, registryChecksum: COMMAND_REGISTRY_CHECKSUM })),
+        bearerToken: input.token, clientVersion: CLIENT_VERSION });
+    const response = await fetchFn(`${input.serverUrl.replace(/\/+$/, '')}${target}`, {
+        method: 'POST', redirect: 'error', signal: AbortSignal.timeout(200000),
+        headers: { ...attempt.headers, Authorization: `Bearer ${input.token}` }, body: attempt.body,
+    });
+    const value = await readControlResponse(response);
+    if (!response.ok)
+        throw new Error(typeof value?.error_code === 'string'
+            && CONTROL_ERRORS.has(value.error_code.replace(/^qa-/, 'refactor-')) && value.error_code.startsWith(`${family}-`) ? value.error_code : 'refactor-root-control-request-refused');
+    const keys = ['schemaVersion', 'kind', 'status', 'completedStages', 'authority', 'qaAccepted', 'gitAuthority', 'billingAuthority', 'publicSafe'];
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+        || Object.keys(value).some(key => !keys.includes(key))
+        || value.schemaVersion !== 1 || value.kind !== `root-${family}-control`
+        || typeof value.status !== 'string' || !['advanced', 'waiting', 'blocked', 'candidate-ready', ...(family === 'qa' ? ['debt'] : [])].includes(value.status)
+        || value.authority !== (family === 'qa' ? 'LOCAL_ROOT_QA_CANDIDATE_ONLY' : 'LOCAL_ROOT_CANDIDATE_ONLY') || value.qaAccepted !== false
+        || value.gitAuthority !== 'NONE' || value.billingAuthority !== 'NONE' || value.publicSafe !== true
+        || value.completedStages !== undefined && (typeof value.completedStages !== 'number' || !Number.isInteger(value.completedStages)
+            || value.completedStages < 0 || value.completedStages > (family === 'qa' ? 3 : 7))) {
+        throw new Error('refactor-root-control-response-invalid');
+    }
+    return value;
+}
+export async function requestRefactorControl(input, fetchFn = fetch) {
+    return requestRootControl('refactor', input, fetchFn);
+}
+export async function refactorControlCliHandler(args, family = 'refactor') {
+    try {
+        let root = '';
+        let storyId = '';
+        let authorized = false;
+        let format = 'json';
+        const tokens = [...args];
+        if (tokens.shift() !== 'control')
+            throw new Error('refactor-root-control-arguments-invalid');
+        for (let i = 0; i < tokens.length; i++) {
+            const token = tokens[i];
+            if (token === '--authorize-root-control')
+                authorized = true;
+            else if (token === '--project-root')
+                root = tokens[++i] ?? '';
+            else if (token === '--story')
+                storyId = tokens[++i] ?? '';
+            else if (token === '--format')
+                format = tokens[++i] ?? '';
+            else
+                throw new Error('refactor-root-control-arguments-invalid');
+        }
+        if (!authorized || !root || format !== 'json' || !/^P[0-9]{1,12}(?:\.[0-9]{1,12}){1,3}$/.test(storyId)) {
+            throw new Error('refactor-root-control-authorization-required');
+        }
+        const platformTarget = detectPlatform({ cwd: resolve(root), env: process.env }).targetId;
+        if (platformTarget !== 'codex')
+            throw new Error('refactor-root-control-host-unsupported');
+        const path = join(resolve(root), '.neocortex', 'state.json');
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink() || realpathSync(path) !== path || stat.size > 16 * 1024 * 1024) {
+            throw new Error('refactor-root-control-project-unbound');
+        }
+        const projectId = JSON.parse(readFileSync(path, 'utf8')).config?.project_id;
+        if (typeof projectId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_-]{15,127}$/.test(projectId)) {
+            throw new Error('refactor-root-control-project-unbound');
+        }
+        const config = loadSecureConfig({ strictReadOnly: true });
+        if (!config?.licenseKey)
+            throw new Error('refactor-root-control-auth-required');
+        const serverUrl = process.env.NEOCORTEX_SERVER_URL ?? config.serverUrl;
+        if (!serverUrl)
+            throw new Error('refactor-root-control-auth-required');
+        const token = await new LicenseClient({ serverUrl, licenseKey: config.licenseKey,
+            cacheProvider: new EncryptedCache({ cacheDir: join(neocortexProfileDirectory(), 'cache'), passphrase: config.licenseKey }) }).getToken();
+        if (!token)
+            throw new Error('refactor-root-control-auth-required');
+        const result = await requestRootControl(family, { serverUrl, token, projectId, storyId, platformTarget });
+        process.stdout.write(`${JSON.stringify({ ok: true, control: result })}\n`);
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message.replace(/^qa-/, 'refactor-') : '';
+        const reasonCode = CLIENT_CONTROL_ERRORS.has(message) || CONTROL_ERRORS.has(message)
+            ? message : 'refactor-root-control-outcome-unknown';
+        process.stdout.write(`${JSON.stringify({ ok: false, reasonCode: family === 'qa' ? reasonCode.replace(/^refactor-/, 'qa-') : reasonCode })}\n`);
+        return 1;
+    }
+}