@ornexus/neocortex 4.60.72 → 4.60.73

package/packages/client/dist/yoloop/invoke-hooks.js

@@ -1,12 +1,669 @@
-import{statSync as q}from"node:fs";import{join as J}from"node:path";import{YoloopClientStateStore as U}from"./yoloop-client-state-store.js";import{isYoloopInvocation as X}from"./target-normalization.js";import{applyStateMigration as Q,StateMigrationApplyError as ee}from"../migrations/state-json.js";function te(e){return X(e)}const N=Object.freeze({stateReadFailed:"YOLOOP_STATE_READ_FAILED",authoritativeWritebackFailed:"YOLOOP_AUTHORITATIVE_WRITEBACK_FAILED",auxiliaryWritebackFailed:"YOLOOP_AUXILIARY_WRITEBACK_FAILED"});class oe extends Error{reasonCode;constructor(o){super(o),this.reasonCode=o,this.name="YoloopStateReadError"}}function L(e,o){return(e instanceof Error?e.message:String(e)).match(/\bYOLOOP_[A-Z0-9_]+\b/)?.[0]??o}const W=new Set(["YOLOOP_RUN_REVISION_CONFLICT","YOLOOP_RUN_SNAPSHOT_CONFLICT","YOLOOP_SUCCESSOR_TRANSITION_STATE_CONFLICT","EAGAIN","EBUSY","EMFILE","ENFILE"]);function re(e){const o=L(e,"");if(W.has(o))return!0;const r=e?.code;return typeof r=="string"&&W.has(r)}const ie=/^\s*\*?(yoloop|auto-yolo|epic-runner|story-runner|loop-yolo|auto-epic)\b/i;function fe(e){if(typeof e.args!="string"||e.args.length===0)return;const o=e.args.match(ie);if(!o)return;const r=o[0];if(e.args.slice(r.length).trim()!=="")return;let n=!1;try{const t=J(e.projectRoot,"docs","epics");n=q(t).isDirectory()}catch(t){const l=t instanceof Error?t.message:String(t);e.logger?.warn?.(`[Neocortex] Zero-config *yoloop hook (P121.05): could not stat docs/epics/: ${l}. Proceeding with raw args.`);return}n&&(e.args=`${r} @docs/epics/`,e.logger?.info?.("[Neocortex] Zero-config *yoloop (P121.05): auto-resolved empty args to @docs/epics/"))}async function ge(e,o,r){if(te(e))try{return await new U(o).readAll(r)}catch(i){const n=L(i,N.stateReadFailed);throw process.stderr.write(`[yoloop] ${n}. Local yoloop authority was not read; no request was sent.
-`),new oe(n)}}async function he(e,o,r){if(!e)return{ok:!0,authoritative:!1,reasonCodes:[]};const i=e.yoloopStateUpdate;if(!i||!Array.isArray(i.operations)||i.operations.length===0)return{ok:!0,authoritative:!1,reasonCodes:[]};const n=i.operations.some(p=>p.type==="rollover_session"||p.type==="commit_successor_transition");let t;const l=n?3:1;for(let p=0;p<l;p+=1)try{return await new U(o).applyUpdate(i,r),{ok:!0,authoritative:n,reasonCodes:[]}}catch(u){if(t=u,!n||p+1>=l||!re(u))break}{const u=L(t,n?N.authoritativeWritebackFailed:N.auxiliaryWritebackFailed);return n?(process.stderr.write(`[yoloop] ${u}. Authoritative yoloop transition was not persisted; no continuation instructions were released.
-`),{ok:!1,authoritative:!0,reasonCodes:[u]}):(process.stderr.write(`[yoloop] ${u}. Auxiliary state update was not persisted; retry the same command.
-`),{ok:!0,authoritative:!1,reasonCodes:[u]})}}function a(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function j(e,o){return Array.isArray(e)&&e.length<=o&&e.every(r=>typeof r=="string"&&r.length>0&&r.length<=160&&/^[A-Za-z0-9_.:+-]+$/.test(r))}function G(e){return a(e.scope)?e.scope.kind==="projected"||typeof e.scope.omittedStoryCount=="number"&&e.scope.omittedStoryCount>0||typeof e.scope.omittedEpicCount=="number"&&e.scope.omittedEpicCount>0:!1}function ne(e){const o={...e};return delete o.scope,delete o.stateSummary,delete o.graphRetrieval,delete o.runnerBootstrap,delete o.projectEvidence,delete o.continuity,delete o.implementCheckpoint,o}function ae(e){return typeof e=="string"&&["done","completed","merged"].includes(e.trim().toLowerCase())}function se(e){return/^[A-Za-z0-9][A-Za-z0-9._/-]{0,119}$/.test(e)&&!e.includes("..")&&!e.includes("//")&&!e.includes("@{")&&!e.endsWith("/")&&!e.endsWith(".")&&!e.endsWith(".lock")}async function ce(e,o){const r=e.syntheticStory;if(!a(r))return{applied:!1,blocking:!0,reasonCode:"inline-yolo-mutation-missing"};const i=r.schemaVersion,n=r.epicId,t=r.storyId,l=r.storyPath,p=r.deterministicKey,u=r.storyContent,A=r.storyContentSha256,y=r.lifecycle;if(i!==2||typeof n!="string"||!/^P9\d{18}$/.test(n)||typeof t!="string"||t!==`${n}.01.000001`||typeof l!="string"||l!==`docs/stories/${t}.story.md`||typeof p!="string"||!/^[a-f0-9]{16}$/.test(p)||typeof A!="string"||!/^[a-f0-9]{64}$/.test(A)||typeof u!="string"||u.length===0||u.length>131072||!a(y)||y.branchMode!=="epic"||y.executionBranch!==`epic/${n}`||typeof y.originBranch!="string"||!se(y.originBranch)||typeof y.graphRevision!="string"||!/^[a-f0-9]{64}$/.test(y.graphRevision)||y.isolatedSyntheticEpic!==!0||r.publicSafe!==!0||r.sanitized!==!0)return{applied:!1,blocking:!0,reasonCode:"inline-yolo-mutation-invalid"};const d=await import("node:fs/promises"),S=await import("node:path"),O=await import("node:crypto");if(O.createHash("sha256").update(u).digest("hex")!==A)return{applied:!1,blocking:!0,reasonCode:"inline-yolo-story-content-integrity-invalid"};const C=S.join(o,".neocortex"),I=S.join(C,"state.json"),w=S.join(o,...l.split("/"));let $;try{$=await d.readFile(I,"utf8")}catch{return{applied:!1,blocking:!0,reasonCode:"inline-yolo-state-missing"}}const P=O.createHash("sha256").update($).digest("hex");let f;try{f=JSON.parse($)}catch{return{applied:!1,blocking:!0,reasonCode:"inline-yolo-state-corrupt"}}if(!a(f)||!a(f.stories)||!a(f.epics)||G(f))return{applied:!1,blocking:!0,reasonCode:"inline-yolo-state-not-full"};if(!a(f.config)||f.config.default_branch!==y.originBranch)return{applied:!1,blocking:!0,reasonCode:"inline-yolo-origin-branch-conflict"};const c=f.stories[t];if(c!==void 0&&(!a(c)||c.epic_id!==n||c.story_file!==l||!a(c.inlineYolo)||c.inlineYolo.deterministicKey!==p))return{applied:!1,blocking:!0,reasonCode:"inline-yolo-story-conflict"};const g=f.epics[n];if(g!==void 0&&(!a(g)||g.id!==n||g.source!=="inline-yolo-materialization"||g.branch_mode!=="epic"||g.execution_branch!==y.executionBranch||g.origin_branch!==y.originBranch||g.graph_revision!==y.graphRevision||!a(g.inlineYoloLifecycle)||g.inlineYoloLifecycle.deterministicKey!==p||g.inlineYoloLifecycle.isolatedSyntheticEpic!==!0||!Array.isArray(g.stories)))return{applied:!1,blocking:!0,reasonCode:"inline-yolo-epic-conflict"};const E=a(g)?g:{},b=Array.isArray(E.stories)?E.stories:[];if(b.some(s=>typeof s!="string")||new Set(b).size!==b.length)return{applied:!1,blocking:!0,reasonCode:"inline-yolo-epic-story-list-invalid"};for(const s of b){const h=f.stories[s];if(!a(h)||h.id!==s||h.epic_id!==n)return{applied:!1,blocking:!0,reasonCode:"inline-yolo-epic-ownership-conflict"}}try{const s=await d.readFile(w,"utf8"),h=s.includes(`id: ${t}`)&&s.includes(`synthetic_key: ${p}`);if(s!==u&&!h)return{applied:!1,blocking:!0,reasonCode:"inline-yolo-story-file-conflict"}}catch(s){if(s.code!=="ENOENT")return{applied:!1,blocking:!0,reasonCode:"inline-yolo-story-file-unreadable"}}const k=b.includes(t)?[...b]:[...b,t],T={...f.stories,[t]:{...a(c)?c:{},id:t,epic_id:n,title:"Synthetic inline USER STORY for yolo",status:a(c)&&typeof c.status=="string"?c.status:"backlog",steps_completed:a(c)&&Array.isArray(c.steps_completed)?c.steps_completed:[],last_step:a(c)?c.last_step??null:null,branch_name:a(c)?c.branch_name??null:null,story_file:l,source:"inline-yolo-materialization",inlineYolo:{...a(c)&&a(c.inlineYolo)?c.inlineYolo:{},schemaVersion:2,deterministicKey:p,publicSafe:!0,sanitized:!0,materializedBeforeExecution:!0,ephemeralExecutionForbidden:!0}}},v=k.filter(s=>a(T[s])&&ae(T[s].status)).length,Y=a(f.inlineYolo)?f.inlineYolo:{},K=a(Y.materializations)?Y.materializations:{},Z=ne({...f,stories:T,epics:{...f.epics,[n]:{...E,id:n,title:typeof E.title=="string"?E.title:"Isolated synthetic inline yolo lifecycle",status:v===k.length&&k.length>0?"done":"in-progress",source:"inline-yolo-materialization",branch_mode:"epic",execution_branch:y.executionBranch,origin_branch:y.originBranch,graph_revision:y.graphRevision,stories:k,total_stories:k.length,completed_stories:v,...v===k.length&&k.length>0?{}:{completed_at:null},inlineYoloLifecycle:{schemaVersion:2,deterministicKey:p,isolatedSyntheticEpic:!0}}},inlineYolo:{...Y,schemaVersion:2,materializations:{...K,[t]:{schemaVersion:2,epicId:n,storyId:t,storyPath:l,deterministicKey:p,storyContentSha256:A,sourceStateSha256:P,lifecycle:y,publicSafe:!0,sanitized:!0,materializedBeforeExecution:!0,ephemeralExecutionForbidden:!0,pipelineTrigger:`*yolo @${l}`,reasonCodes:Array.isArray(r.reasonCodes)?r.reasonCodes:[]}}},last_updated:new Date().toISOString()}),B=`${Date.now()}-${O.randomBytes(6).toString("hex")}`,z=S.join(C,`state.json.tmp.${B}`),x=`${w}.tmp.${B}`,F=S.join(C,`state.json.backup-${new Date().toISOString().replace(/[:.]/g,"-")}`),V=S.join(C,"state.json.inline-yolo.lock");let D=!1,_;const H=async s=>{let h;try{h=await d.open(s,"r"),await h.sync()}catch(m){const R=m.code;if(!["EINVAL","ENOTSUP","EPERM","EISDIR"].includes(R??""))throw m}finally{await h?.close().catch(()=>{})}},M=async(s,h)=>{const m=await d.open(s,"wx",384);try{await m.writeFile(h,"utf8"),await m.sync()}finally{await m.close()}};try{await d.mkdir(C,{recursive:!0}),await d.mkdir(S.dirname(w),{recursive:!0});try{_=await d.open(V,"wx",384),await _.writeFile(`${process.pid}
-${P}
-`,"utf8"),await _.sync()}catch(R){if(R.code==="EEXIST")return{applied:!1,blocking:!0,reasonCode:"inline-yolo-writeback-locked"};throw R}const s=await d.readFile(I,"utf8");if(O.createHash("sha256").update(s).digest("hex")!==P)return{applied:!1,blocking:!0,reasonCode:"inline-yolo-state-cas-conflict"};try{await d.access(w)}catch{await M(x,u),await d.rename(x,w),await H(S.dirname(w)),D=!0}await d.copyFile(I,F);const m=await d.open(F,"r");try{await m.sync()}finally{await m.close()}return await M(z,JSON.stringify(Z,null,2)),await d.rename(z,I),await H(C),process.stderr.write(`[Neocortex] inline yolo story materialized with bounded full-state merge; story=${t}; backup=${S.basename(F)}.
-`),{applied:!0,blocking:!1,reasonCode:"inline-yolo-materialized"}}catch(s){await Promise.allSettled([d.unlink(z),d.unlink(x)]),D&&await d.readFile(w,"utf8").catch(()=>{})===u&&await d.unlink(w).catch(()=>{});const h=s.message??String(s);return process.stderr.write(`[Neocortex] inline yolo materialization failed: ${h}.
-`),{applied:!1,blocking:!0,reasonCode:"inline-yolo-persistence-failed"}}finally{await _?.close().catch(()=>{}),_&&await d.unlink(V).catch(()=>{})}}async function me(e,o){if(!e||e.stateMutated!==!0)return{applied:!1,blocking:!1,reasonCode:"state-writeback-not-requested"};if(e.stateMutationStrategy==="merge-inline-yolo-v2"||e.stateMutationReason==="inline-yolo-materialized-synthetic-story")return ce(e,o);if(e.stateMutationStrategy==="state-migration-v1"||e.stateMigrationPlan!==void 0){const i=e.stateMigrationPlan,n=new Set(["schemaVersion","operationId","sourceSchemaVersion","targetSchemaVersion","sourceCanonicalHash","targetCanonicalHash","steps","migratedEpicIds","migratedStoryIds","preservedUnknownFieldCount","reasonCodes","sourceByteDigest"]);if(!a(i)||Object.keys(i).some(t=>!n.has(t))||i.schemaVersion!=="StateMigrationPlan/1.0"||typeof i.operationId!="string"||!/^smig_[a-f0-9]{32}$/.test(i.operationId)||typeof i.sourceCanonicalHash!="string"||!/^[a-f0-9]{64}$/.test(i.sourceCanonicalHash)||typeof i.targetCanonicalHash!="string"||!/^[a-f0-9]{64}$/.test(i.targetCanonicalHash)||typeof i.sourceByteDigest!="string"||!/^[a-f0-9]{64}$/.test(i.sourceByteDigest)||![0,1,"absent"].includes(i.sourceSchemaVersion)||i.targetSchemaVersion!==1||!Array.isArray(i.steps)||i.steps.length>8192||i.steps.some(t=>!a(t)||Object.keys(t).some(l=>!["kind","source","target"].includes(l))||!["initialize-collection","merge-epic","merge-story","preserve-legacy","remove-legacy","set-schema-version"].includes(String(t.kind))||typeof t.target!="string"||t.target.length>512||!/^[A-Za-z0-9_.:[\]-]+$/.test(t.target)||t.source!==void 0&&(typeof t.source!="string"||t.source.length>512||!/^[A-Za-z0-9_.:[\]-]+$/.test(t.source)))||!j(i.migratedEpicIds,4096)||!j(i.migratedStoryIds,4096)||!j(i.reasonCodes,32)||!Number.isSafeInteger(i.preservedUnknownFieldCount)||i.preservedUnknownFieldCount<0)return{applied:!1,blocking:!0,reasonCode:"state-migration-plan-missing-or-invalid"};try{const t=Q(o,i),l=`.neocortex/state.json.migration-backup-${t.operationId}`;return process.stderr.write(`[P220-EV-STATE-MIGRATION] outcome=${t.outcome}; operation=${t.operationId}; backup=${t.backupHash?l:"none"}.
-`),{applied:t.outcome==="applied",blocking:!1,reasonCode:t.outcome==="applied"?"state-migration-applied":"state-migration-replay-verified"}}catch(t){const l=t instanceof ee?t.reasonCode:"state-migration-apply-failed";return process.stderr.write(`[P220-EV-STATE-MIGRATION] blocked=${l}.
-`),{applied:!1,blocking:!0,reasonCode:l}}}const r=e.migratedState;return!r||typeof r!="object"||Array.isArray(r)?{applied:!1,blocking:!0,reasonCode:"state-writeback-payload-missing"}:G(r)?(process.stderr.write(`[Neocortex] Refused projected/partial state replacement; canonical state was not modified.
-`),{applied:!1,blocking:!0,reasonCode:"state-writeback-partial-rejected"}):(process.stderr.write(`[P220-EV-STATE-MIGRATION] blocked=state-migration-plan-missing-or-invalid; canonical state was not modified.
-`),{applied:!1,blocking:!0,reasonCode:"state-migration-plan-missing-or-invalid"})}async function Se(e){if(!e.featureFlag)return{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:"flag off"};try{return await(await import("./discovery-hook.js")).runDiscoveryHook(e)}catch(o){const r=o instanceof Error?o.message:String(o);return e.logger?.warn?.(`[neocortex] discovery hook (lazy load) failed: ${r}. Proceeding without enrichment.`),{applied:!1,added:Object.freeze([]),skipped:Object.freeze([]),storiesAdded:0,reason:`lazy load error: ${r}`}}}async function we(e){if(!e.featureFlag)return{applied:!1,reason:"flag_off"};try{return await(await import("../graph-retrieval/pre-command-hook.js")).runGraphRetrievalHook(e)}catch(o){const r=o instanceof Error?o.message:String(o);return e.logger?.warn?.(`[neocortex] graph retrieval hook (lazy load) failed: ${r}. Proceeding without enrichment.`),{applied:!1,reason:"hook_error",warning:r}}}export{N as YOLOOP_PERSISTENCE_REASON_CODES,oe as YoloopStateReadError,te as isYoloopTrigger,fe as maybeAutoResolveYoloopArgs,Se as maybeRunDiscoveryHook,we as maybeRunGraphRetrievalHook,me as persistMigratedStateFromResponse,he as persistYoloopFromResponse,ge as readYoloopForRequest};
+/**
+ * Epic P101.07 -- invoke.ts hooks for yoloop state persistence.
+ *
+ * Two hooks:
+ *   - `readYoloopForRequest(args, projectRoot)` — pre-request; returns
+ *     `YoloopPersistedState | undefined` to embed in stateSnapshot.yoloop.
+ *     Returns undefined (no-op) for non-yoloop invocations to avoid I/O.
+ *   - `persistYoloopFromResponse(metadata, projectRoot)` — post-response;
+ *     if the server returned `yoloopStateUpdate`, apply operations locally.
+ *     Authoritative rollover/successor-transition failures are returned to the invoke boundary;
+ *     auxiliary legacy updates retain bounded fail-soft compatibility.
+ *
+ * Trigger detection is regex-based over the first token of `args`, aligned
+ * with the P96.01 TRIGGER_ALIASES set for yoloop. Cheap enough to run on
+ * every invoke.
+ */
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { YoloopClientStateStore } from './yoloop-client-state-store.js';
+import { isYoloopInvocation } from './target-normalization.js';
+import { applyStateMigration, StateMigrationApplyError } from '../migrations/state-json.js';
+/**
+ * Detect whether an args string is a yoloop invocation (including aliases).
+ * Matches: `*yoloop`, `yoloop`, `*auto-yolo`, `*epic-runner`, `*story-runner`,
+ * `*loop-yolo`, `*auto-epic` (case-insensitive, with optional leading whitespace
+ * and optional `*` prefix).
+ */
+export function isYoloopTrigger(args) {
+    return isYoloopInvocation(args);
+}
+export const YOLOOP_PERSISTENCE_REASON_CODES = Object.freeze({
+    stateReadFailed: 'YOLOOP_STATE_READ_FAILED',
+    authoritativeWritebackFailed: 'YOLOOP_AUTHORITATIVE_WRITEBACK_FAILED',
+    auxiliaryWritebackFailed: 'YOLOOP_AUXILIARY_WRITEBACK_FAILED',
+});
+export class YoloopStateReadError extends Error {
+    reasonCode;
+    constructor(reasonCode) {
+        super(reasonCode);
+        this.reasonCode = reasonCode;
+        this.name = 'YoloopStateReadError';
+    }
+}
+function publicPersistenceReason(error, fallback) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.match(/\bYOLOOP_[A-Z0-9_]+\b/)?.[0] ?? fallback;
+}
+const RECOVERABLE_AUTHORITATIVE_WRITE_CODES = new Set([
+    'YOLOOP_RUN_REVISION_CONFLICT',
+    'YOLOOP_RUN_SNAPSHOT_CONFLICT',
+    'YOLOOP_SUCCESSOR_TRANSITION_STATE_CONFLICT',
+    'EAGAIN',
+    'EBUSY',
+    'EMFILE',
+    'ENFILE',
+]);
+function shouldRetryAuthoritativeWrite(error) {
+    const reason = publicPersistenceReason(error, '');
+    if (RECOVERABLE_AUTHORITATIVE_WRITE_CODES.has(reason))
+        return true;
+    const code = error?.code;
+    return typeof code === 'string' && RECOVERABLE_AUTHORITATIVE_WRITE_CODES.has(code);
+}
+// =====================================================================
+// P121.05 -- Zero-config *yoloop auto-resolve
+// =====================================================================
+/**
+ * P121.05: Yoloop trigger regex (mirror of `isYoloopTrigger` predicate, but
+ * exposes capture group + match index for token-aware rewrites).
+ */
+const YOLOOP_TRIGGER_TOKEN_RE = /^\s*\*?(yoloop|auto-yolo|epic-runner|story-runner|loop-yolo|auto-epic)\b/i;
+/**
+ * P121.05 -- Zero-config `*yoloop`. When the user types `*yoloop` (or any
+ * alias) with no args, auto-resolve to `<projectRoot>/docs/epics/` if that
+ * directory exists.
+ *
+ * Behavior:
+ *   - Yoloop trigger detection: same regex as P101.07 / P120.04.
+ *   - Args-empty detection: trigger token + optional whitespace; remainder
+ *     `=== ''` after `.trim()`.
+ *   - Directory existence: synchronous `fs.statSync(...).isDirectory()`,
+ *     wrapped in try/catch.
+ *   - Rewrite: appends ` @docs/epics/` to the matched trigger token,
+ *     preserving the original token (canonical or alias) and any leading
+ *     `*` prefix.
+ *   - Fail-soft: any error -> `ctx.logger.warn` + return unchanged args.
+ *
+ * Mutates `ctx.args` in place when auto-resolve fires. Caller (invoke.ts)
+ * propagates the new value via the InvokeOptions immutable update pattern.
+ *
+ * AC1, AC2, AC3, AC4, AC5, AC6, AC7, AC8, AC13.
+ */
+export function maybeAutoResolveYoloopArgs(ctx) {
+    // Defensive: defensive types -- unexpected non-strings get a no-op.
+    if (typeof ctx.args !== 'string' || ctx.args.length === 0) {
+        return;
+    }
+    // 1. Match yoloop trigger token (with optional `*` prefix).
+    const match = ctx.args.match(YOLOOP_TRIGGER_TOKEN_RE);
+    if (!match) {
+        // Not a yoloop trigger -> nothing to do.
+        return;
+    }
+    // 2. Strip the matched trigger from `args` and check the remainder.
+    //    `match[0]` is the matched substring including any leading whitespace
+    //    and the optional `*` prefix and the trigger token. Anything after
+    //    the trigger token (and any trailing whitespace) is the explicit args.
+    const matchedToken = match[0]; // e.g., "*yoloop" or "  yoloop"
+    const remainder = ctx.args.slice(matchedToken.length).trim();
+    if (remainder !== '') {
+        // Explicit args present -> never rewrite (AC6, backward compat).
+        return;
+    }
+    // 3. Check whether `<projectRoot>/docs/epics/` exists and is a directory.
+    //    Wrapped in try/catch so any fs error (permission denied, ENOENT,
+    //    unexpected errors from `node:fs`) is swallowed -> args unchanged.
+    let isDir = false;
+    try {
+        const target = join(ctx.projectRoot, 'docs', 'epics');
+        const stat = statSync(target);
+        isDir = stat.isDirectory();
+    }
+    catch (err) {
+        // Fail-soft: log warn + bail. Args remain unchanged. Server emits the
+        // existing `INVALID_YOLOOP_TARGET` error if/when the request reaches it.
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.logger?.warn?.(`[Neocortex] Zero-config *yoloop hook (P121.05): could not stat docs/epics/: ${msg}. Proceeding with raw args.`);
+        return;
+    }
+    if (!isDir) {
+        // Directory does not exist (or `docs/epics` is a file) -> args unchanged.
+        return;
+    }
+    // 4. Rewrite: preserve the matched trigger token and append ` @docs/epics/`.
+    //    Canonical examples:
+    //      `*yoloop`       -> `*yoloop @docs/epics/`
+    //      `*auto-yolo`    -> `*auto-yolo @docs/epics/`
+    //      `  yoloop   `   -> `  yoloop @docs/epics/`
+    ctx.args = `${matchedToken} @docs/epics/`;
+    // 5. Surface the auto-resolution at info level so operators see the
+    //    transformation in stderr without being noisy on every invoke.
+    ctx.logger?.info?.(`[Neocortex] Zero-config *yoloop (P121.05): auto-resolved empty args to @docs/epics/`);
+}
+/**
+ * Pre-request hook: read client-side yoloop state for the given project.
+ * Returns undefined for non-yoloop invocations (no I/O). A yoloop read or
+ * recovery failure is authoritative and fails closed so the server can never
+ * reinterpret corrupt/unavailable persisted state as a fresh session.
+ */
+export async function readYoloopForRequest(args, projectRoot, nowIso) {
+    if (!isYoloopTrigger(args))
+        return undefined;
+    try {
+        const store = new YoloopClientStateStore(projectRoot);
+        return await store.readAll(nowIso);
+    }
+    catch (err) {
+        const reasonCode = publicPersistenceReason(err, YOLOOP_PERSISTENCE_REASON_CODES.stateReadFailed);
+        process.stderr.write(`[yoloop] ${reasonCode}. Local yoloop authority was not read; no request was sent.\n`);
+        throw new YoloopStateReadError(reasonCode);
+    }
+}
+/**
+ * Post-response hook: apply server-provided operations to local state.
+ * Safe to call for any response — no-op if no yoloopStateUpdate present.
+ * A `rollover_session` or `commit_successor_transition` update is
+ * authoritative: failure is returned to the caller so instructions cannot be
+ * released before durable state exists.
+ * Non-rollover legacy operations retain fail-soft compatibility.
+ */
+export async function persistYoloopFromResponse(metadata, projectRoot, nowIso) {
+    if (!metadata)
+        return { ok: true, authoritative: false, reasonCodes: [] };
+    const update = metadata.yoloopStateUpdate;
+    if (!update || !Array.isArray(update.operations) || update.operations.length === 0) {
+        return { ok: true, authoritative: false, reasonCodes: [] };
+    }
+    const authoritative = update.operations.some((operation) => operation.type === 'rollover_session'
+        || operation.type === 'commit_successor_transition');
+    let lastError;
+    const attempts = authoritative ? 3 : 1;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        try {
+            const store = new YoloopClientStateStore(projectRoot);
+            await store.applyUpdate(update, nowIso);
+            return { ok: true, authoritative, reasonCodes: [] };
+        }
+        catch (error) {
+            lastError = error;
+            if (!authoritative || attempt + 1 >= attempts || !shouldRetryAuthoritativeWrite(error))
+                break;
+            // A fresh store rereads and recovers any prepared manifest. These
+            // bounded internal attempts do not create a new server run, dispatch,
+            // entitlement charge, strike or cooldown.
+        }
+    }
+    {
+        const err = lastError;
+        const reasonCode = publicPersistenceReason(err, authoritative
+            ? YOLOOP_PERSISTENCE_REASON_CODES.authoritativeWritebackFailed
+            : YOLOOP_PERSISTENCE_REASON_CODES.auxiliaryWritebackFailed);
+        if (authoritative) {
+            process.stderr.write(`[yoloop] ${reasonCode}. Authoritative yoloop transition was not persisted; no continuation instructions were released.\n`);
+            return { ok: false, authoritative: true, reasonCodes: [reasonCode] };
+        }
+        process.stderr.write(`[yoloop] ${reasonCode}. Auxiliary state update was not persisted; retry the same command.\n`);
+        return { ok: true, authoritative: false, reasonCodes: [reasonCode] };
+    }
+}
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function boundedPublicStrings(value, max) {
+    return Array.isArray(value)
+        && value.length <= max
+        && value.every((entry) => typeof entry === 'string' && entry.length > 0 && entry.length <= 160 && /^[A-Za-z0-9_.:+-]+$/.test(entry));
+}
+function projectedOrPartialState(value) {
+    if (!isPlainRecord(value.scope))
+        return false;
+    return value.scope.kind === 'projected'
+        || (typeof value.scope.omittedStoryCount === 'number' && value.scope.omittedStoryCount > 0)
+        || (typeof value.scope.omittedEpicCount === 'number' && value.scope.omittedEpicCount > 0);
+}
+function stripRequestOnlyStateFields(value) {
+    const canonical = { ...value };
+    delete canonical.scope;
+    delete canonical.stateSummary;
+    delete canonical.graphRetrieval;
+    delete canonical.runnerBootstrap;
+    delete canonical.projectEvidence;
+    delete canonical.continuity;
+    delete canonical.implementCheckpoint;
+    return canonical;
+}
+function doneLikeStatus(value) {
+    return typeof value === 'string' && ['done', 'completed', 'merged'].includes(value.trim().toLowerCase());
+}
+function safeInlineYoloBranch(value) {
+    return /^[A-Za-z0-9][A-Za-z0-9._/-]{0,119}$/.test(value)
+        && !value.includes('..')
+        && !value.includes('//')
+        && !value.includes('@{')
+        && !value.endsWith('/')
+        && !value.endsWith('.')
+        && !value.endsWith('.lock');
+}
+async function persistInlineYoloMaterialization(metadata, projectRoot) {
+    const syntheticStory = metadata.syntheticStory;
+    if (!isPlainRecord(syntheticStory)) {
+        return { applied: false, blocking: true, reasonCode: 'inline-yolo-mutation-missing' };
+    }
+    const schemaVersion = syntheticStory.schemaVersion;
+    const epicId = syntheticStory.epicId;
+    const storyId = syntheticStory.storyId;
+    const storyPath = syntheticStory.storyPath;
+    const deterministicKey = syntheticStory.deterministicKey;
+    const storyContent = syntheticStory.storyContent;
+    const storyContentSha256 = syntheticStory.storyContentSha256;
+    const lifecycle = syntheticStory.lifecycle;
+    if (schemaVersion !== 2
+        || typeof epicId !== 'string' || !/^P9\d{18}$/.test(epicId)
+        || typeof storyId !== 'string' || storyId !== `${epicId}.01.000001`
+        || typeof storyPath !== 'string' || storyPath !== `docs/stories/${storyId}.story.md`
+        || typeof deterministicKey !== 'string' || !/^[a-f0-9]{16}$/.test(deterministicKey)
+        || typeof storyContentSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(storyContentSha256)
+        || typeof storyContent !== 'string' || storyContent.length === 0 || storyContent.length > 131_072
+        || !isPlainRecord(lifecycle)
+        || lifecycle.branchMode !== 'epic'
+        || lifecycle.executionBranch !== `epic/${epicId}`
+        || typeof lifecycle.originBranch !== 'string'
+        || !safeInlineYoloBranch(lifecycle.originBranch)
+        || typeof lifecycle.graphRevision !== 'string' || !/^[a-f0-9]{64}$/.test(lifecycle.graphRevision)
+        || lifecycle.isolatedSyntheticEpic !== true
+        || syntheticStory.publicSafe !== true || syntheticStory.sanitized !== true) {
+        return { applied: false, blocking: true, reasonCode: 'inline-yolo-mutation-invalid' };
+    }
+    const fs = await import('node:fs/promises');
+    const path = await import('node:path');
+    const crypto = await import('node:crypto');
+    if (crypto.createHash('sha256').update(storyContent).digest('hex') !== storyContentSha256) {
+        return { applied: false, blocking: true, reasonCode: 'inline-yolo-story-content-integrity-invalid' };
+    }
+    const stateDir = path.join(projectRoot, '.neocortex');
+    const statePath = path.join(stateDir, 'state.json');
+    const absoluteStoryPath = path.join(projectRoot, ...storyPath.split('/'));
+    let rawState;
+    try {
+        rawState = await fs.readFile(statePath, 'utf8');
+    }
+    catch {
+        return { applied: false, blocking: true, reasonCode: 'inline-yolo-state-missing' };
+    }
+    const sourceStateSha256 = crypto.createHash('sha256').update(rawState).digest('hex');
+    let parsedState;
+    try {
+        parsedState = JSON.parse(rawState);
+    }
+    catch {
+        return { applied: false, blocking: true, reasonCode: 'inline-yolo-state-corrupt' };
+    }
+    if (!isPlainRecord(parsedState) || !isPlainRecord(parsedState.stories) || !isPlainRecord(parsedState.epics)
+        || projectedOrPartialState(parsedState)) {
+        return { applied: false, blocking: true, reasonCode: 'inline-yolo-state-not-full' };
+    }
+    if (!isPlainRecord(parsedState.config) || parsedState.config.default_branch !== lifecycle.originBranch) {
+        return { applied: false, blocking: true, reasonCode: 'inline-yolo-origin-branch-conflict' };
+    }
+    const previousStory = parsedState.stories[storyId];
+    if (previousStory !== undefined && (!isPlainRecord(previousStory)
+        || previousStory.epic_id !== epicId
+        || previousStory.story_file !== storyPath
+        || !isPlainRecord(previousStory.inlineYolo)
+        || previousStory.inlineYolo.deterministicKey !== deterministicKey)) {
+        return { applied: false, blocking: true, reasonCode: 'inline-yolo-story-conflict' };
+    }
+    const previousEpic = parsedState.epics[epicId];
+    if (previousEpic !== undefined && (!isPlainRecord(previousEpic)
+        || previousEpic.id !== epicId
+        || previousEpic.source !== 'inline-yolo-materialization'
+        || previousEpic.branch_mode !== 'epic'
+        || previousEpic.execution_branch !== lifecycle.executionBranch
+        || previousEpic.origin_branch !== lifecycle.originBranch
+        || previousEpic.graph_revision !== lifecycle.graphRevision
+        || !isPlainRecord(previousEpic.inlineYoloLifecycle)
+        || previousEpic.inlineYoloLifecycle.deterministicKey !== deterministicKey
+        || previousEpic.inlineYoloLifecycle.isolatedSyntheticEpic !== true
+        || !Array.isArray(previousEpic.stories))) {
+        return { applied: false, blocking: true, reasonCode: 'inline-yolo-epic-conflict' };
+    }
+    const epic = isPlainRecord(previousEpic) ? previousEpic : {};
+    const previousStoryIds = Array.isArray(epic.stories) ? epic.stories : [];
+    if (previousStoryIds.some((entry) => typeof entry !== 'string') || new Set(previousStoryIds).size !== previousStoryIds.length) {
+        return { applied: false, blocking: true, reasonCode: 'inline-yolo-epic-story-list-invalid' };
+    }
+    for (const existingId of previousStoryIds) {
+        const existingStory = parsedState.stories[existingId];
+        if (!isPlainRecord(existingStory) || existingStory.id !== existingId || existingStory.epic_id !== epicId) {
+            return { applied: false, blocking: true, reasonCode: 'inline-yolo-epic-ownership-conflict' };
+        }
+    }
+    try {
+        const existingContent = await fs.readFile(absoluteStoryPath, 'utf8');
+        const materializationIdentityPreserved = existingContent.includes(`id: ${storyId}`)
+            && existingContent.includes(`synthetic_key: ${deterministicKey}`);
+        if (existingContent !== storyContent && !materializationIdentityPreserved) {
+            return { applied: false, blocking: true, reasonCode: 'inline-yolo-story-file-conflict' };
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            return { applied: false, blocking: true, reasonCode: 'inline-yolo-story-file-unreadable' };
+        }
+    }
+    const storyIds = previousStoryIds.includes(storyId)
+        ? [...previousStoryIds]
+        : [...previousStoryIds, storyId];
+    const stories = {
+        ...parsedState.stories,
+        [storyId]: {
+            ...(isPlainRecord(previousStory) ? previousStory : {}),
+            id: storyId,
+            epic_id: epicId,
+            title: 'Synthetic inline USER STORY for yolo',
+            status: isPlainRecord(previousStory) && typeof previousStory.status === 'string' ? previousStory.status : 'backlog',
+            steps_completed: isPlainRecord(previousStory) && Array.isArray(previousStory.steps_completed) ? previousStory.steps_completed : [],
+            last_step: isPlainRecord(previousStory) ? previousStory.last_step ?? null : null,
+            branch_name: isPlainRecord(previousStory) ? previousStory.branch_name ?? null : null,
+            story_file: storyPath,
+            source: 'inline-yolo-materialization',
+            inlineYolo: {
+                ...(isPlainRecord(previousStory) && isPlainRecord(previousStory.inlineYolo) ? previousStory.inlineYolo : {}),
+                schemaVersion: 2,
+                deterministicKey,
+                publicSafe: true,
+                sanitized: true,
+                materializedBeforeExecution: true,
+                ephemeralExecutionForbidden: true,
+            },
+        },
+    };
+    const completedStories = storyIds.filter((id) => isPlainRecord(stories[id]) && doneLikeStatus(stories[id].status)).length;
+    const previousInlineYolo = isPlainRecord(parsedState.inlineYolo) ? parsedState.inlineYolo : {};
+    const previousMaterializations = isPlainRecord(previousInlineYolo.materializations)
+        ? previousInlineYolo.materializations : {};
+    const nextState = stripRequestOnlyStateFields({
+        ...parsedState,
+        stories,
+        epics: {
+            ...parsedState.epics,
+            [epicId]: {
+                ...epic,
+                id: epicId,
+                title: typeof epic.title === 'string' ? epic.title : 'Isolated synthetic inline yolo lifecycle',
+                status: completedStories === storyIds.length && storyIds.length > 0 ? 'done' : 'in-progress',
+                source: 'inline-yolo-materialization',
+                branch_mode: 'epic',
+                execution_branch: lifecycle.executionBranch,
+                origin_branch: lifecycle.originBranch,
+                graph_revision: lifecycle.graphRevision,
+                stories: storyIds,
+                total_stories: storyIds.length,
+                completed_stories: completedStories,
+                ...(completedStories === storyIds.length && storyIds.length > 0 ? {} : { completed_at: null }),
+                inlineYoloLifecycle: {
+                    schemaVersion: 2,
+                    deterministicKey,
+                    isolatedSyntheticEpic: true,
+                },
+            },
+        },
+        inlineYolo: {
+            ...previousInlineYolo,
+            schemaVersion: 2,
+            materializations: {
+                ...previousMaterializations,
+                [storyId]: {
+                    schemaVersion: 2,
+                    epicId,
+                    storyId,
+                    storyPath,
+                    deterministicKey,
+                    storyContentSha256,
+                    sourceStateSha256,
+                    lifecycle,
+                    publicSafe: true,
+                    sanitized: true,
+                    materializedBeforeExecution: true,
+                    ephemeralExecutionForbidden: true,
+                    pipelineTrigger: `*yolo @${storyPath}`,
+                    reasonCodes: Array.isArray(syntheticStory.reasonCodes) ? syntheticStory.reasonCodes : [],
+                },
+            },
+        },
+        last_updated: new Date().toISOString(),
+    });
+    const suffix = `${Date.now()}-${crypto.randomBytes(6).toString('hex')}`;
+    const stateTmpPath = path.join(stateDir, `state.json.tmp.${suffix}`);
+    const storyTmpPath = `${absoluteStoryPath}.tmp.${suffix}`;
+    const backupPath = path.join(stateDir, `state.json.backup-${new Date().toISOString().replace(/[:.]/g, '-')}`);
+    const lockPath = path.join(stateDir, 'state.json.inline-yolo.lock');
+    let storyCreated = false;
+    let lockHandle;
+    const syncDirectory = async (directory) => {
+        let handle;
+        try {
+            handle = await fs.open(directory, 'r');
+            await handle.sync();
+        }
+        catch (error) {
+            const code = error.code;
+            if (!['EINVAL', 'ENOTSUP', 'EPERM', 'EISDIR'].includes(code ?? ''))
+                throw error;
+        }
+        finally {
+            await handle?.close().catch(() => undefined);
+        }
+    };
+    const durableExclusiveWrite = async (temporaryPath, content) => {
+        const handle = await fs.open(temporaryPath, 'wx', 0o600);
+        try {
+            await handle.writeFile(content, 'utf8');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    };
+    try {
+        await fs.mkdir(stateDir, { recursive: true });
+        await fs.mkdir(path.dirname(absoluteStoryPath), { recursive: true });
+        try {
+            lockHandle = await fs.open(lockPath, 'wx', 0o600);
+            await lockHandle.writeFile(`${process.pid}\n${sourceStateSha256}\n`, 'utf8');
+            await lockHandle.sync();
+        }
+        catch (error) {
+            if (error.code === 'EEXIST') {
+                return { applied: false, blocking: true, reasonCode: 'inline-yolo-writeback-locked' };
+            }
+            throw error;
+        }
+        // Compare-and-swap under the cooperative lock. A stale response may never
+        // replace state that changed after it was read and validated above.
+        const currentRawState = await fs.readFile(statePath, 'utf8');
+        const currentStateSha256 = crypto.createHash('sha256').update(currentRawState).digest('hex');
+        if (currentStateSha256 !== sourceStateSha256) {
+            return { applied: false, blocking: true, reasonCode: 'inline-yolo-state-cas-conflict' };
+        }
+        try {
+            await fs.access(absoluteStoryPath);
+        }
+        catch {
+            await durableExclusiveWrite(storyTmpPath, storyContent);
+            await fs.rename(storyTmpPath, absoluteStoryPath);
+            await syncDirectory(path.dirname(absoluteStoryPath));
+            storyCreated = true;
+        }
+        await fs.copyFile(statePath, backupPath);
+        const backupHandle = await fs.open(backupPath, 'r');
+        try {
+            await backupHandle.sync();
+        }
+        finally {
+            await backupHandle.close();
+        }
+        await durableExclusiveWrite(stateTmpPath, JSON.stringify(nextState, null, 2));
+        await fs.rename(stateTmpPath, statePath);
+        await syncDirectory(stateDir);
+        process.stderr.write(`[Neocortex] inline yolo story materialized with bounded full-state merge; story=${storyId}; backup=${path.basename(backupPath)}.\n`);
+        return { applied: true, blocking: false, reasonCode: 'inline-yolo-materialized' };
+    }
+    catch (error) {
+        await Promise.allSettled([fs.unlink(stateTmpPath), fs.unlink(storyTmpPath)]);
+        if (storyCreated) {
+            const currentStory = await fs.readFile(absoluteStoryPath, 'utf8').catch(() => undefined);
+            if (currentStory === storyContent)
+                await fs.unlink(absoluteStoryPath).catch(() => undefined);
+        }
+        const message = error.message ?? String(error);
+        process.stderr.write(`[Neocortex] inline yolo materialization failed: ${message}.\n`);
+        return { applied: false, blocking: true, reasonCode: 'inline-yolo-persistence-failed' };
+    }
+    finally {
+        await lockHandle?.close().catch(() => undefined);
+        if (lockHandle)
+            await fs.unlink(lockPath).catch(() => undefined);
+    }
+}
+export async function persistMigratedStateFromResponse(metadata, projectRoot) {
+    if (!metadata || metadata.stateMutated !== true) {
+        return { applied: false, blocking: false, reasonCode: 'state-writeback-not-requested' };
+    }
+    if (metadata.stateMutationStrategy === 'merge-inline-yolo-v2'
+        || metadata.stateMutationReason === 'inline-yolo-materialized-synthetic-story') {
+        return persistInlineYoloMaterialization(metadata, projectRoot);
+    }
+    if (metadata.stateMutationStrategy === 'state-migration-v1' || metadata.stateMigrationPlan !== undefined) {
+        const rawPlan = metadata.stateMigrationPlan;
+        const directiveKeys = new Set([
+            'schemaVersion', 'operationId', 'sourceSchemaVersion', 'targetSchemaVersion',
+            'sourceCanonicalHash', 'targetCanonicalHash', 'steps', 'migratedEpicIds',
+            'migratedStoryIds', 'preservedUnknownFieldCount', 'reasonCodes', 'sourceByteDigest',
+        ]);
+        if (!isPlainRecord(rawPlan)
+            || Object.keys(rawPlan).some((key) => !directiveKeys.has(key))
+            || rawPlan.schemaVersion !== 'StateMigrationPlan/1.0'
+            || typeof rawPlan.operationId !== 'string' || !/^smig_[a-f0-9]{32}$/.test(rawPlan.operationId)
+            || typeof rawPlan.sourceCanonicalHash !== 'string' || !/^[a-f0-9]{64}$/.test(rawPlan.sourceCanonicalHash)
+            || typeof rawPlan.targetCanonicalHash !== 'string' || !/^[a-f0-9]{64}$/.test(rawPlan.targetCanonicalHash)
+            || typeof rawPlan.sourceByteDigest !== 'string' || !/^[a-f0-9]{64}$/.test(rawPlan.sourceByteDigest)
+            || ![0, 1, 'absent'].includes(rawPlan.sourceSchemaVersion)
+            || rawPlan.targetSchemaVersion !== 1
+            || !Array.isArray(rawPlan.steps) || rawPlan.steps.length > 8192
+            || rawPlan.steps.some((step) => !isPlainRecord(step)
+                || Object.keys(step).some((key) => !['kind', 'source', 'target'].includes(key))
+                || !['initialize-collection', 'merge-epic', 'merge-story', 'preserve-legacy', 'remove-legacy', 'set-schema-version'].includes(String(step.kind))
+                || typeof step.target !== 'string' || step.target.length > 512 || !/^[A-Za-z0-9_.:[\]-]+$/.test(step.target)
+                || (step.source !== undefined && (typeof step.source !== 'string' || step.source.length > 512 || !/^[A-Za-z0-9_.:[\]-]+$/.test(step.source))))
+            || !boundedPublicStrings(rawPlan.migratedEpicIds, 4096)
+            || !boundedPublicStrings(rawPlan.migratedStoryIds, 4096)
+            || !boundedPublicStrings(rawPlan.reasonCodes, 32)
+            || !Number.isSafeInteger(rawPlan.preservedUnknownFieldCount) || rawPlan.preservedUnknownFieldCount < 0) {
+            return { applied: false, blocking: true, reasonCode: 'state-migration-plan-missing-or-invalid' };
+        }
+        try {
+            const migrationReceipt = applyStateMigration(projectRoot, rawPlan);
+            const backupPath = `.neocortex/state.json.migration-backup-${migrationReceipt.operationId}`;
+            process.stderr.write(`[P220-EV-STATE-MIGRATION] outcome=${migrationReceipt.outcome}; operation=${migrationReceipt.operationId}; backup=${migrationReceipt.backupHash ? backupPath : 'none'}.\n`);
+            return {
+                applied: migrationReceipt.outcome === 'applied',
+                blocking: false,
+                reasonCode: migrationReceipt.outcome === 'applied' ? 'state-migration-applied' : 'state-migration-replay-verified',
+            };
+        }
+        catch (error) {
+            const reasonCode = error instanceof StateMigrationApplyError ? error.reasonCode : 'state-migration-apply-failed';
+            process.stderr.write(`[P220-EV-STATE-MIGRATION] blocked=${reasonCode}.\n`);
+            return { applied: false, blocking: true, reasonCode };
+        }
+    }
+    const migratedState = metadata.migratedState;
+    if (!migratedState || typeof migratedState !== 'object' || Array.isArray(migratedState)) {
+        return { applied: false, blocking: true, reasonCode: 'state-writeback-payload-missing' };
+    }
+    if (projectedOrPartialState(migratedState)) {
+        process.stderr.write('[Neocortex] Refused projected/partial state replacement; canonical state was not modified.\n');
+        return { applied: false, blocking: true, reasonCode: 'state-writeback-partial-rejected' };
+    }
+    process.stderr.write('[P220-EV-STATE-MIGRATION] blocked=state-migration-plan-missing-or-invalid; canonical state was not modified.\n');
+    return { applied: false, blocking: true, reasonCode: 'state-migration-plan-missing-or-invalid' };
+}
+// =====================================================================
+// P120.04 -- Discovery hook integration
+// =====================================================================
+/**
+ * P120.04: lazy-loaded discovery hook wrapper.
+ *
+ * Short-circuits BEFORE the dynamic import when `featureFlag` is off, so
+ * clients with `YOLOOP_AUTO_DISCOVERY` unset (default) never load the
+ * discovery-hook module. ESM tree-shakers can prune the entire module +
+ * its `shared-discover-epics.ts` mirror in production builds.
+ *
+ * Defensive try/catch around the dynamic import handles the
+ * (vanishingly unlikely) case where the hook module is missing or the
+ * dynamic import itself throws -- never blocks the invoke flow.
+ *
+ * Caller (invoke.ts) is expected to ALSO wrap this in a try/catch as
+ * belt-and-suspenders.
+ */
+export async function maybeRunDiscoveryHook(ctx) {
+    // Flag-off short-circuit -- preserves tree-shaking + zero overhead.
+    if (!ctx.featureFlag) {
+        return {
+            applied: false,
+            added: Object.freeze([]),
+            skipped: Object.freeze([]),
+            storiesAdded: 0,
+            reason: 'flag off',
+        };
+    }
+    try {
+        const mod = await import('./discovery-hook.js');
+        return await mod.runDiscoveryHook(ctx);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.logger?.warn?.(`[neocortex] discovery hook (lazy load) failed: ${msg}. Proceeding without enrichment.`);
+        return {
+            applied: false,
+            added: Object.freeze([]),
+            skipped: Object.freeze([]),
+            storiesAdded: 0,
+            reason: `lazy load error: ${msg}`,
+        };
+    }
+}
+// =====================================================================
+// P158.06 -- Pre-command graph retrieval hook integration
+// =====================================================================
+/**
+ * P158.06 / P198.02: lazy-loaded graph retrieval wrapper.
+ *
+ * Short-circuits before dynamic import when the feature flag is off. When on,
+ * command eligibility, profiles and budgets are resolved by the public command
+ * context policy shadow. Runtime errors are public-warning/fail-soft and never
+ * block invoke.
+ */
+export async function maybeRunGraphRetrievalHook(ctx) {
+    if (!ctx.featureFlag) {
+        return {
+            applied: false,
+            reason: 'flag_off',
+        };
+    }
+    try {
+        const mod = await import('../graph-retrieval/pre-command-hook.js');
+        return await mod.runGraphRetrievalHook(ctx);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.logger?.warn?.(`[neocortex] graph retrieval hook (lazy load) failed: ${msg}. Proceeding without enrichment.`);
+        return {
+            applied: false,
+            reason: 'hook_error',
+            warning: msg,
+        };
+    }
+}