@ornexus/neocortex 4.60.74 → 4.60.75

package/packages/client/dist/license/host-auth-recovery.d.ts

@@ -0,0 +1,158 @@
+import { EncryptedCache } from '../cache/encrypted-cache.js';
+export type AuthCauseV1 = 'valid' | 'near-expiry' | 'expired' | 'not-configured' | 'store-unavailable' | 'store-corrupt' | 'keychain-unavailable' | 'transport-error' | 'timeout' | 'rate-limited' | 'service-unavailable' | 'revoked' | 'scope-denied' | 'client-denied' | 'protocol-invalid' | 'persistence-failed' | 'rotation-uncertain' | 'capability-unavailable' | 'revision-conflict';
+export type AuthRecoveryResultV1 = {
+    readonly status: 'authenticated';
+    readonly generation: number;
+    readonly accessCredential: string;
+    readonly expiresAt: string;
+} | {
+    readonly status: 'refresh-required';
+    readonly cause: AuthCauseV1;
+    readonly action: 'prepare' | 'retry-later' | 'reactivate' | 'request-scope' | 'recover-explicitly' | 'stop';
+} | {
+    readonly status: 'uncertain';
+    readonly cause: 'rotation-uncertain' | 'persistence-failed';
+    readonly recoveryId: string;
+    readonly action: 'reconcile' | 'recover-explicitly';
+} | {
+    readonly status: 'not-configured';
+    readonly action: 'activate';
+};
+export type AuthRecoveryPhase = 'prepared' | 'request-started' | 'response-received' | 'generation-committed' | 'uncertain' | 'completed' | 'aborted-before-request';
+export interface AuthRecoveryJournalV1 {
+    readonly recoveryId: string;
+    readonly operationId: string;
+    readonly idempotencyKey: string;
+    readonly requestDigest: string;
+    readonly owner: string;
+    readonly createdAt: string;
+    readonly expiresAt: string;
+    readonly attemptCount: 0 | 1;
+    readonly replayCount: 0 | 1;
+    readonly phase: AuthRecoveryPhase;
+    readonly responseDigest?: string;
+}
+export interface AuthGenerationDocumentV1 {
+    readonly schemaVersion: 'AuthGeneration/1.0';
+    readonly revision: number;
+    readonly identityHash: string;
+    readonly accepted: null | {
+        readonly generation: number;
+        readonly accessToken: string;
+        readonly accessExpiresAt: string;
+        readonly refreshToken: string | null;
+        readonly refreshExpiresAt: string | null;
+        readonly acceptedAt: string;
+        readonly responseDigest: string;
+    };
+    readonly activeRecovery: AuthRecoveryJournalV1 | null;
+    readonly receipts: readonly {
+        readonly recoveryId: string;
+        readonly operationId: string;
+        readonly outcome: string;
+        readonly completedAt: string;
+    }[];
+}
+export interface AuthGenerationStore {
+    read(identityHash: string): Promise<AuthGenerationDocumentV1 | null>;
+    compareAndSet(expectedRevision: number, document: AuthGenerationDocumentV1): Promise<void>;
+}
+/** Private generation adapter backed by EncryptedCache's mandatory CAS path. */
+export declare class EncryptedAuthGenerationStore implements AuthGenerationStore {
+    private readonly cache;
+    constructor(cache: EncryptedCache);
+    private key;
+    read(identityHash: string): Promise<AuthGenerationDocumentV1 | null>;
+    compareAndSet(expectedRevision: number, document: AuthGenerationDocumentV1): Promise<void>;
+}
+export interface AuthRefreshSuccess {
+    readonly token: string;
+    readonly expiresAt: string;
+    readonly refreshToken?: string | null;
+    readonly refreshExpiresAt?: string | null;
+}
+export interface AuthRecoveryInput {
+    readonly identityHash: string;
+    readonly recoveryId: string;
+    readonly operationId: string;
+    readonly idempotencyKey: string;
+    readonly requestDigest: string;
+    readonly owner: string;
+    readonly leaseMs?: number;
+    readonly timeoutMs?: number;
+    readonly now?: () => number;
+    readonly refresh: (signal?: AbortSignal) => Promise<AuthRefreshSuccess>;
+}
+export declare function createAuthIdentityHash(parts: readonly string[]): string;
+export declare function validateAuthGenerationDocument(value: unknown, expectedIdentityHash?: string): AuthGenerationDocumentV1;
+export declare function recoverHostAuthentication(store: AuthGenerationStore, input: AuthRecoveryInput): Promise<AuthRecoveryResultV1>;
+export type AuthBusinessReplayDecisionV1 = {
+    readonly kind: 'replay-once';
+    readonly recoveryId: string;
+} | {
+    readonly kind: 'reconcile-receipt';
+    readonly operationId: string;
+} | {
+    readonly kind: 'stop';
+    readonly reasonCode: string;
+};
+export declare function decideAuthBusinessReplay(input: {
+    readonly recoveryId: string;
+    readonly operationId: string;
+    readonly generationCommitted: boolean;
+    readonly identityMatches: boolean;
+    readonly requestMatches: boolean;
+    readonly replayCount: number;
+    readonly receipt: 'not-accepted' | 'accepted' | 'unknown';
+    readonly supportsIdempotency: boolean;
+    readonly rotationUncertain: boolean;
+}): AuthBusinessReplayDecisionV1;
+/**
+ * Reserves the single business replay by CAS before returning authorization.
+ * Consumers perform the business effect only after this function succeeds.
+ */
+export declare function reserveAuthBusinessReplay(store: AuthGenerationStore, input: {
+    readonly identityHash: string;
+    readonly recoveryId: string;
+    readonly operationId: string;
+    readonly requestDigest: string;
+    readonly receipt: 'not-accepted' | 'accepted' | 'unknown';
+    readonly supportsIdempotency: boolean;
+    readonly rotationUncertain?: boolean;
+}): Promise<AuthBusinessReplayDecisionV1>;
+/** Records the compare-bound business outcome before a later recovery may replace the journal. */
+export declare function completeAuthRecovery(store: AuthGenerationStore, input: {
+    readonly identityHash: string;
+    readonly recoveryId: string;
+    readonly operationId: string;
+    readonly outcome: string;
+    readonly completedAt?: string;
+}): Promise<AuthGenerationDocumentV1>;
+export type AuthCausalEvidenceV1 = {
+    readonly kind: 'token';
+    readonly credential: string;
+    readonly expiresAt: string;
+    readonly generation: number;
+    readonly now?: number;
+} | {
+    readonly kind: 'configuration';
+    readonly configured: boolean;
+} | {
+    readonly kind: 'store';
+    readonly cause: 'store-unavailable' | 'store-corrupt' | 'keychain-unavailable';
+} | {
+    readonly kind: 'transport';
+    readonly timeout?: boolean;
+    readonly requestStarted?: boolean;
+    readonly recoveryId?: string;
+} | {
+    readonly kind: 'http';
+    readonly status: number;
+    readonly errorCode?: string;
+} | {
+    readonly kind: 'persistence';
+    readonly recoveryId: string;
+};
+/** Pure evidence-to-cause mapping. Generic HTTP status never proves revocation. */
+export declare function classifyAuthCausalEvidence(evidence: AuthCausalEvidenceV1): AuthRecoveryResultV1;
+export declare function newRecoveryId(): string;

package/packages/client/dist/license/host-auth-recovery.js

@@ -0,0 +1 @@
+import{createHash as v,randomUUID as D}from"node:crypto";class K{cache;constructor(t){this.cache=t}key(t){if(!u.test(t))throw new Error("auth-business-identity-mismatch");return`neocortex:auth-generation:v1:${t}`}async read(t){const r=await this.cache.getAuthoritative(this.key(t));if(r===null)return null;try{return d(JSON.parse(r),t)}catch(o){throw new Error("auth-generation-corrupt",{cause:o})}}async compareAndSet(t,r){d(r,r.identityHash);const o=this.key(r.identityHash),i=await this.cache.getAuthoritative(o);let s=0;if(i!==null)try{s=d(JSON.parse(i),r.identityHash).revision}catch(n){throw new Error("auth-generation-corrupt",{cause:n})}if(s!==t||r.revision!==t+1)throw new Error("auth-generation-revision-conflict");await this.cache.setAuthoritative(o,JSON.stringify(r),{expectedPlaintextSha256:i===null?null:v("sha256").update(i).digest("hex")})}}const u=/^[a-f0-9]{64}$/,p=/^[A-Za-z0-9._:-]{1,128}$/;function J(e){if(e.length!==5||e.some(t=>t.length===0||t.length>256||/[\r\n\0]/.test(t)))throw new Error("auth-business-identity-mismatch");return v("sha256").update("neocortex-auth-generation-v1\0").update(e.join("\0")).digest("hex")}function d(e,t){let r;try{r=JSON.stringify(e)}catch{throw new Error("auth-generation-corrupt")}if(!l(e)||typeof r!="string")throw new Error("auth-generation-corrupt");if(Buffer.byteLength(r,"utf8")>256*1024)throw new Error("auth-generation-capacity");const o=e;if(o.schemaVersion!=="AuthGeneration/1.0"||!Number.isSafeInteger(o.revision)||o.revision<0||!u.test(o.identityHash)||t&&o.identityHash!==t||!Array.isArray(o.receipts)||o.receipts.length>32)throw new Error("auth-generation-corrupt");if(!m(e,["schemaVersion","revision","identityHash","accepted","activeRecovery","receipts"]))throw new Error("auth-generation-corrupt");S(o.accepted),H(o.activeRecovery);for(const i of o.receipts)T(i);return o}function C(e){return{schemaVersion:"AuthGeneration/1.0",revision:0,identityHash:e,accepted:null,activeRecovery:null,receipts:[]}}async function h(e,t,r){const o=d({...t,...r,revision:t.revision+1},t.identityHash);return await e.compareAndSet(t.revision,o),o}async function U(e,t){if(!u.test(t.identityHash)||!u.test(t.requestDigest)||![t.recoveryId,t.operationId,t.idempotencyKey,t.owner].every(a=>p.test(a)))return{status:"refresh-required",cause:"protocol-invalid",action:"stop"};const r=t.now??Date.now,o=Math.min(Math.max(t.leaseMs??3e4,1),6e4),i=Math.min(Math.max(t.timeoutMs??3e4,1),3e4);let s;try{s=d(await e.read(t.identityHash)??C(t.identityHash),t.identityHash)}catch(a){return x(a)}const n=s.activeRecovery;if(n)if(n.recoveryId===t.recoveryId){if(!_(n,t))return{status:"refresh-required",cause:"protocol-invalid",action:"stop"};if((n.phase==="generation-committed"||n.phase==="completed")&&s.accepted)return A(s.accepted);if(n.attemptCount===1)return y(t.recoveryId,n.phase==="response-received"?"persistence-failed":"rotation-uncertain");if(Date.parse(n.expiresAt)>r()&&n.owner!==t.owner)return{status:"refresh-required",cause:"revision-conflict",action:"retry-later"}}else{if(n.attemptCount===1&&!["generation-committed","completed","aborted-before-request"].includes(n.phase))return y(n.recoveryId,n.phase==="response-received"?"persistence-failed":"rotation-uncertain");if(n.phase==="generation-committed")return{status:"refresh-required",cause:"revision-conflict",action:"retry-later"};if(n.attemptCount===0&&Date.parse(n.expiresAt)>r())return{status:"refresh-required",cause:"revision-conflict",action:"retry-later"}}const g={recoveryId:t.recoveryId,operationId:t.operationId,idempotencyKey:t.idempotencyKey,requestDigest:t.requestDigest,owner:t.owner,createdAt:new Date(r()).toISOString(),expiresAt:new Date(r()+o).toISOString(),attemptCount:0,replayCount:0,phase:"prepared"};try{(!n||n.recoveryId!==t.recoveryId||n.owner!==t.owner||n.phase!=="prepared")&&(s=await h(e,s,{activeRecovery:g}));const a={...g,attemptCount:1,phase:"request-started"};s=await h(e,s,{activeRecovery:a});let c;try{c=await M(t.refresh,i)}catch{return await q(e,s,a),y(t.recoveryId,"rotation-uncertain")}if(!c.token||c.token.length>65536||!Number.isFinite(Date.parse(c.expiresAt)))return await q(e,s,a),y(t.recoveryId,"rotation-uncertain");const w=v("sha256").update(JSON.stringify(c)).digest("hex"),I={...a,phase:"response-received",responseDigest:w};s=await h(e,s,{activeRecovery:I});const k={generation:(s.accepted?.generation??0)+1,accessToken:c.token,accessExpiresAt:c.expiresAt,refreshToken:c.refreshToken??null,refreshExpiresAt:c.refreshExpiresAt??null,acceptedAt:new Date(r()).toISOString(),responseDigest:w},E={...I,phase:"generation-committed"},b=await h(e,s,{accepted:k,activeRecovery:E});return A(b.accepted)}catch(a){return s.activeRecovery?.attemptCount!==1?x(a):y(t.recoveryId,"persistence-failed")}}function R(e){return!e.identityMatches||!e.requestMatches?{kind:"stop",reasonCode:"auth-business-identity-mismatch"}:e.rotationUncertain||!e.generationCommitted?{kind:"stop",reasonCode:"auth-business-replay-unsafe"}:e.replayCount!==0?{kind:"stop",reasonCode:"auth-business-replay-exhausted"}:e.receipt==="accepted"?{kind:"reconcile-receipt",operationId:e.operationId}:e.receipt==="unknown"&&!e.supportsIdempotency?{kind:"reconcile-receipt",operationId:e.operationId}:{kind:"replay-once",recoveryId:e.recoveryId}}async function B(e,t){let r;try{r=d(await e.read(t.identityHash),t.identityHash)}catch{return{kind:"stop",reasonCode:"auth-business-replay-unsafe"}}const o=r.activeRecovery;if(!o||o.recoveryId!==t.recoveryId||o.operationId!==t.operationId)return{kind:"stop",reasonCode:"auth-business-identity-mismatch"};const i=R({recoveryId:t.recoveryId,operationId:t.operationId,generationCommitted:o.phase==="generation-committed"&&r.accepted!==null,identityMatches:r.identityHash===t.identityHash,requestMatches:o.requestDigest===t.requestDigest,replayCount:o.replayCount,receipt:t.receipt,supportsIdempotency:t.supportsIdempotency,rotationUncertain:t.rotationUncertain===!0||o.phase==="uncertain"});if(i.kind!=="replay-once")return i;try{return await h(e,r,{activeRecovery:{...o,replayCount:1}}),i}catch{return{kind:"stop",reasonCode:"auth-generation-revision-conflict"}}}async function G(e,t){if(!u.test(t.identityHash)||![t.recoveryId,t.operationId,t.outcome].every(n=>p.test(n)))throw new Error("auth-business-identity-mismatch");const r=d(await e.read(t.identityHash),t.identityHash),o=r.activeRecovery;if(!o||o.recoveryId!==t.recoveryId||o.operationId!==t.operationId)throw new Error("auth-business-identity-mismatch");const i=r.receipts.find(n=>n.recoveryId===t.recoveryId);if(i){if(i.operationId!==t.operationId||i.outcome!==t.outcome)throw new Error("auth-business-identity-mismatch");return r}if(o.phase!=="generation-committed"||r.accepted===null)throw new Error("auth-business-replay-unsafe");if(r.receipts.length>=32)throw new Error("auth-generation-capacity");const s=t.completedAt??new Date().toISOString();if(!f(s))throw new Error("auth-business-identity-mismatch");return h(e,r,{activeRecovery:{...o,phase:"completed"},receipts:[...r.receipts,{recoveryId:t.recoveryId,operationId:t.operationId,outcome:t.outcome,completedAt:s}]})}function F(e){switch(e.kind){case"token":{const t=e.now??Date.now(),r=Date.parse(e.expiresAt);return Number.isFinite(r)?r<=t?{status:"refresh-required",cause:"expired",action:"prepare"}:r-t<=3e5?{status:"refresh-required",cause:"near-expiry",action:"prepare"}:{status:"authenticated",generation:e.generation,accessCredential:e.credential,expiresAt:e.expiresAt}:{status:"refresh-required",cause:"protocol-invalid",action:"stop"}}case"configuration":return e.configured?{status:"refresh-required",cause:"store-unavailable",action:"stop"}:{status:"not-configured",action:"activate"};case"store":return{status:"refresh-required",cause:e.cause,action:e.cause==="store-unavailable"?"retry-later":"stop"};case"transport":return e.requestStarted?y(e.recoveryId??"unknown-recovery","rotation-uncertain"):{status:"refresh-required",cause:e.timeout?"timeout":"transport-error",action:"retry-later"};case"http":{const t=e.errorCode??"";return e.status===429?{status:"refresh-required",cause:"rate-limited",action:"retry-later"}:e.status>=500?{status:"refresh-required",cause:"service-unavailable",action:"retry-later"}:t==="invalid_grant"||t==="revoked"?{status:"refresh-required",cause:"revoked",action:"reactivate"}:t==="invalid_scope"||t==="scope_denied"?{status:"refresh-required",cause:"scope-denied",action:"request-scope"}:t==="client_denied"?{status:"refresh-required",cause:"client-denied",action:"stop"}:{status:"refresh-required",cause:"protocol-invalid",action:"stop"}}case"persistence":return y(e.recoveryId,"persistence-failed")}}function P(){return D()}function S(e){if(e!==null){if(!l(e)||!m(e,["generation","accessToken","accessExpiresAt","refreshToken","refreshExpiresAt","acceptedAt","responseDigest"]))throw new Error("auth-generation-corrupt");if(!Number.isSafeInteger(e.generation)||e.generation<1||typeof e.accessToken!="string"||e.accessToken.length===0||e.accessToken.length>65536||e.refreshToken!==null&&(typeof e.refreshToken!="string"||e.refreshToken.length>65536)||!f(e.accessExpiresAt)||!f(e.acceptedAt)||e.refreshExpiresAt!==null&&!f(e.refreshExpiresAt)||!u.test(e.responseDigest))throw new Error("auth-generation-corrupt")}}function H(e){if(e===null)return;if(!l(e)||!m(e,["recoveryId","operationId","idempotencyKey","requestDigest","owner","createdAt","expiresAt","attemptCount","replayCount","phase","responseDigest"],!0))throw new Error("auth-generation-corrupt");const t=["prepared","request-started","response-received","generation-committed","uncertain","completed","aborted-before-request"];if(![e.recoveryId,e.operationId,e.idempotencyKey,e.owner].every(r=>p.test(r))||!u.test(e.requestDigest)||!f(e.createdAt)||!f(e.expiresAt)||![0,1].includes(e.attemptCount)||![0,1].includes(e.replayCount)||!t.includes(e.phase)||e.responseDigest!==void 0&&!u.test(e.responseDigest))throw new Error("auth-generation-corrupt")}function T(e){if(!l(e)||!m(e,["recoveryId","operationId","outcome","completedAt"])||!p.test(e.recoveryId)||!p.test(e.operationId)||!p.test(e.outcome)||!f(e.completedAt))throw new Error("auth-generation-corrupt")}function _(e,t){return e.operationId===t.operationId&&e.idempotencyKey===t.idempotencyKey&&e.requestDigest===t.requestDigest}function A(e){return{status:"authenticated",generation:e.generation,accessCredential:e.accessToken,expiresAt:e.accessExpiresAt}}function y(e,t){return{status:"uncertain",cause:t,recoveryId:e,action:"recover-explicitly"}}function x(e){const t=e instanceof Error?e.message:"";return t==="auth-generation-revision-conflict"||t==="auth-recovery-backpressure"?{status:"refresh-required",cause:"revision-conflict",action:"retry-later"}:t==="auth-generation-corrupt"||t==="auth-generation-path-unsafe"?{status:"refresh-required",cause:"store-corrupt",action:"stop"}:{status:"refresh-required",cause:"store-unavailable",action:"retry-later"}}async function q(e,t,r){try{await h(e,t,{activeRecovery:{...r,phase:"uncertain"}})}catch{}}async function M(e,t){const r=new AbortController;let o;const i=new Promise((s,n)=>{o=setTimeout(()=>{r.abort(),n(new Error("auth-refresh-timeout"))},t),o.unref?.()});try{return await Promise.race([e(r.signal),i])}finally{o&&clearTimeout(o)}}function f(e){return typeof e=="string"&&Number.isFinite(Date.parse(e))}function l(e){return e!==null&&typeof e=="object"&&!Array.isArray(e)}function m(e,t,r=!1){const o=Object.keys(e).sort();return(r?t.slice(0,-1):t).every(s=>o.includes(s))&&o.every(s=>t.includes(s))}export{K as EncryptedAuthGenerationStore,F as classifyAuthCausalEvidence,G as completeAuthRecovery,J as createAuthIdentityHash,R as decideAuthBusinessReplay,P as newRecoveryId,U as recoverHostAuthentication,B as reserveAuthBusinessReplay,d as validateAuthGenerationDocument};

package/packages/client/dist/license/license-client.d.ts

@@ -11,6 +11,7 @@
  * See the LICENSE file in the project root for full license text.
  */
 import type { CacheProvider } from '../types/index.js';
+import type { AuthRecoveryResultV1 } from './host-auth-recovery.js';
 export interface LicenseClientOptions {
     readonly serverUrl: string;
     readonly licenseKey: string;
@@ -18,6 +19,8 @@ export interface LicenseClientOptions {
     readonly clientVersion?: string;
     /** Use only an already-valid cached JWT; never refresh or activate. */
     readonly strictReadOnly?: boolean;
+    /** Opt into P224 causal recovery. P224.04 owns enabling this in invoke wiring. */
+    readonly causalAuthRecovery?: boolean;
 }
 interface ActivationResult {
     readonly token: string;
@@ -42,8 +45,10 @@ export declare class LicenseClient {
     private readonly clientVersion;
     private readonly machineId;
     private readonly strictReadOnly;
+    private readonly causalAuthRecovery;
     private token;
     private refreshToken;
+    private lastRecoveryResult;
     constructor(options: LicenseClientOptions);
     /**
      * Get a valid JWT token. Checks memory, cache, refresh token, then activation.
@@ -60,6 +65,9 @@ export declare class LicenseClient {
     getToken(): Promise<string | null>;
     /** Read-only authentication classification. It never refreshes, activates, clears or writes cache state. */
     inspectToken(): Promise<LicenseTokenInspection>;
+    /** Last causal result, excluding raw server bodies and refresh credentials. */
+    getLastRecoveryResult(): AuthRecoveryResultV1 | null;
+    private refreshRequired;
     /**
      * Activate through the endpoint matching the configured credential type.
      * Stores token and refresh_token in memory and cache on success.
@@ -81,7 +89,8 @@ export declare class LicenseClient {
     /**
      * Force-refresh the token.
      * Used when tier_changed is detected or a 401 response indicates the token is expired.
-     * Falls back to re-activation if refresh fails.
+     * Does not clear or re-activate on an ambiguous refresh failure. Recovery is
+     * governed by the causal result so transient or uncertain state is preserved.
      * NEVER throws - returns new token or null on failure.
      *
      * Story 18.8: Updated to prefer refresh over re-activate (preserves updated tier).

package/packages/client/dist/license/license-client.js

@@ -1 +1 @@
-import{decodeJwt as h}from"jose";import{NoOpCache as o}from"../types/index.js";import{getMachineFingerprint as l}from"../machine/fingerprint.js";import{CLIENT_VERSION as u}from"../version.js";const a="neocortex:jwt:token",s="neocortex:jwt:refresh_token",f=300,c=10080*60*1e3;class w{serverUrl;licenseKey;cache;clientVersion;machineId;strictReadOnly;token=null;refreshToken=null;constructor(e){this.serverUrl=e.serverUrl.replace(/\/+$/,""),this.licenseKey=e.licenseKey,this.cache=e.cacheProvider??new o,this.clientVersion=e.clientVersion??u,this.strictReadOnly=e.strictReadOnly??!1,this.machineId=l({strictReadOnly:this.strictReadOnly})}async getToken(){try{if(this.strictReadOnly){const t=await this.inspectToken();return t.status==="authenticated"?t.token:null}if(this.token){const t=this.checkTokenValidity(this.token);if(t==="valid")return this.token;if(t==="needs-refresh")return this.strictReadOnly?this.token:(await this.refresh())?.token??this.token;this.token=null}const e=await this.loadFromCache();if(e){this.token=e;const t=this.checkTokenValidity(e);if(t==="valid")return e;if(t==="needs-refresh")return this.strictReadOnly?e:(await this.refresh())?.token??e;this.token=null}if(this.strictReadOnly)return null;if(this.refreshToken||(this.refreshToken=await this.loadRefreshTokenFromCache()),this.refreshToken){const t=await this.refresh();if(t?.token)return t.token}return(await this.activate())?.token??null}catch{return null}}async inspectToken(){try{const e=this.token??await this.loadFromCache();if(e){const i=this.checkTokenValidity(e);return i==="valid"?{status:"authenticated",token:e}:{status:"refresh-required",reason:i==="needs-refresh"?"near-expiry":"expired"}}return this.licenseKey?{status:"refresh-required",reason:"unavailable"}:{status:"not-configured"}}catch{return this.licenseKey?{status:"refresh-required",reason:"unavailable"}:{status:"not-configured"}}}async activate(){if(this.strictReadOnly)return null;try{const e=this.licenseKey.startsWith("nxk_"),i=e?"activate-key":"activate",t=e?{api_key:this.licenseKey}:{license_key:this.licenseKey},r=await fetch(`${this.serverUrl}/api/v1/license/${i}`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({...t,machine_id:this.machineId,client_version:this.clientVersion})});if(!r.ok)return null;const n=await r.json();return n.tier!==void 0&&n.tier!=="free"&&n.tier!=="pro"&&n.tier!=="enterprise"?null:(this.token=n.token,this.refreshToken=n.refresh_token??null,await this.cache.set(a,n.token,n.expires_in*1e3).catch(()=>{}),n.refresh_token&&await this.cache.set(s,n.refresh_token,c).catch(()=>{}),{token:n.token,expiresIn:n.expires_in,refreshToken:n.refresh_token,tier:n.tier})}catch{return null}}async refresh(e){if(this.strictReadOnly)return null;try{const i=this.refreshToken??await this.loadRefreshTokenFromCache();if(!i)return null;const t=await fetch(`${this.serverUrl}/api/v1/license/refresh`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({refresh_token:i})});if(!t.ok)return this.refreshToken=null,await this.cache.set(s,"",1).catch(()=>{}),null;const r=await t.json();return this.token=r.token,this.refreshToken=r.refresh_token??null,await this.cache.set(a,r.token,r.expires_in*1e3).catch(()=>{}),r.refresh_token&&await this.cache.set(s,r.refresh_token,c).catch(()=>{}),{token:r.token,expiresIn:r.expires_in,refreshToken:r.refresh_token}}catch{return null}}async forceRefresh(){if(this.strictReadOnly)return null;try{const e=await this.refresh();return e?.token?e.token:(this.token=null,this.refreshToken=null,await this.cache.clear().catch(()=>{}),(await this.activate())?.token??null)}catch{return null}}checkTokenValidity(e){try{const i=h(e);if(!i.exp)return"expired";const t=Math.floor(Date.now()/1e3);return i.exp<=t?"expired":i.exp-t<=f?"needs-refresh":"valid"}catch{return"expired"}}async loadFromCache(){try{return await this.cache.get(a)}catch{return null}}async loadRefreshTokenFromCache(){try{const e=await this.cache.get(s);return e&&e.length>0?e:null}catch{return null}}}export{w as LicenseClient};
+import{decodeJwt as h}from"jose";import{NoOpCache as o}from"../types/index.js";import{getMachineFingerprint as l}from"../machine/fingerprint.js";import{CLIENT_VERSION as u}from"../version.js";const s="neocortex:jwt:token",a="neocortex:jwt:refresh_token",f=300,c=10080*60*1e3;class v{serverUrl;licenseKey;cache;clientVersion;machineId;strictReadOnly;causalAuthRecovery;token=null;refreshToken=null;lastRecoveryResult=null;constructor(e){this.serverUrl=e.serverUrl.replace(/\/+$/,""),this.licenseKey=e.licenseKey,this.cache=e.cacheProvider??new o,this.clientVersion=e.clientVersion??u,this.strictReadOnly=e.strictReadOnly??!1,this.causalAuthRecovery=e.causalAuthRecovery??!1,this.machineId=l({strictReadOnly:this.strictReadOnly})}async getToken(){try{if(this.strictReadOnly){const t=await this.inspectToken();return t.status==="authenticated"?t.token:null}if(this.token){const t=this.checkTokenValidity(this.token);if(t==="valid")return this.token;if(t==="needs-refresh")return this.strictReadOnly?this.token:(await this.refresh())?.token??this.token;this.token=null}const e=await this.loadFromCache();if(e){this.token=e;const t=this.checkTokenValidity(e);if(t==="valid")return e;if(t==="needs-refresh")return this.strictReadOnly?e:(await this.refresh())?.token??e;this.token=null}if(this.strictReadOnly)return null;if(this.refreshToken||(this.refreshToken=await this.loadRefreshTokenFromCache()),this.refreshToken){const t=await this.refresh();if(t?.token)return t.token;if(this.causalAuthRecovery)return null}return(await this.activate())?.token??null}catch{return null}}async inspectToken(){try{const e=this.token??await this.loadFromCache();if(e){const n=this.checkTokenValidity(e);return n==="valid"?{status:"authenticated",token:e}:{status:"refresh-required",reason:n==="needs-refresh"?"near-expiry":"expired"}}return this.licenseKey?{status:"refresh-required",reason:"unavailable"}:{status:"not-configured"}}catch{return this.licenseKey?{status:"refresh-required",reason:"unavailable"}:{status:"not-configured"}}}getLastRecoveryResult(){return this.lastRecoveryResult}refreshRequired(e,n){return this.lastRecoveryResult={status:"refresh-required",cause:e,action:n},null}async activate(){if(this.strictReadOnly)return null;try{const e=this.licenseKey.startsWith("nxk_"),n=e?"activate-key":"activate",t=e?{api_key:this.licenseKey}:{license_key:this.licenseKey},i=await fetch(`${this.serverUrl}/api/v1/license/${n}`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({...t,machine_id:this.machineId,client_version:this.clientVersion})});if(!i.ok)return null;const r=await i.json();return r.tier!==void 0&&r.tier!=="free"&&r.tier!=="pro"&&r.tier!=="enterprise"?null:(this.token=r.token,this.refreshToken=r.refresh_token??null,await this.cache.set(s,r.token,r.expires_in*1e3).catch(()=>{}),r.refresh_token&&await this.cache.set(a,r.refresh_token,c).catch(()=>{}),{token:r.token,expiresIn:r.expires_in,refreshToken:r.refresh_token,tier:r.tier})}catch{return null}}async refresh(e){if(this.strictReadOnly)return null;try{const n=this.refreshToken??await this.loadRefreshTokenFromCache();if(!n)return this.refreshRequired("not-configured","reactivate");const t=await fetch(`${this.serverUrl}/api/v1/license/refresh`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({refresh_token:n})});if(!t.ok){let r="";try{r=String((await t.json()).error??"")}catch{}return t.status===429?this.refreshRequired("rate-limited","retry-later"):t.status>=500?this.refreshRequired("service-unavailable","retry-later"):r==="invalid_grant"||r==="revoked"?this.refreshRequired("revoked","reactivate"):r==="invalid_scope"||r==="scope_denied"?this.refreshRequired("scope-denied","request-scope"):r==="client_denied"?this.refreshRequired("client-denied","stop"):this.refreshRequired("protocol-invalid","stop")}const i=await t.json();return this.token=i.token,this.refreshToken=i.refresh_token??null,await this.cache.set(s,i.token,i.expires_in*1e3).catch(()=>{}),i.refresh_token&&await this.cache.set(a,i.refresh_token,c).catch(()=>{}),this.lastRecoveryResult={status:"authenticated",generation:0,accessCredential:i.token,expiresAt:new Date(Date.now()+i.expires_in*1e3).toISOString()},{token:i.token,expiresIn:i.expires_in,refreshToken:i.refresh_token}}catch{return this.refreshRequired("transport-error","retry-later")}}async forceRefresh(){if(this.strictReadOnly)return null;try{const e=await this.refresh();return e?.token?e.token:this.causalAuthRecovery?null:(this.token=null,this.refreshToken=null,await this.cache.clear().catch(()=>{}),(await this.activate())?.token??null)}catch{return null}}checkTokenValidity(e){try{const n=h(e);if(!n.exp)return"expired";const t=Math.floor(Date.now()/1e3);return n.exp<=t?"expired":n.exp-t<=f?"needs-refresh":"valid"}catch{return"expired"}}async loadFromCache(){try{return await this.cache.get(s)}catch{return null}}async loadRefreshTokenFromCache(){try{const e=await this.cache.get(a);return e&&e.length>0?e:null}catch{return null}}}export{v as LicenseClient};

package/packages/client/dist/runner/epic-background-dispatcher.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Contract-first admission for root-owned native background execution.
+ *
+ * This module deliberately does not spawn, persist tracked state, select graph
+ * work, or perform Git effects. It only converts an exact server-owned task
+ * directive into closed per-story entries for the host root.
+ */
+import { type NativeBackgroundDispatchContractV1, type NativeDispatchBindingV1, type NativeHostAttestationV1 } from '../continuity/native-agent-types.js';
+export declare const NATIVE_BACKGROUND_REASON_CODES: Readonly<{
+    readonly CONTRACT_INVALID: "directive-background-contract-invalid";
+    readonly BINDING_MISSING: "directive-background-binding-missing";
+    readonly WAVE_MISMATCH: "directive-background-wave-mismatch";
+    readonly GRAPH_STALE: "directive-background-graph-stale";
+    readonly CAPABILITY_UNVALIDATED: "native-background-capability-unvalidated";
+    readonly DEPTH_DENIED: "native-background-depth-denied";
+    readonly SETTLEMENT_INVALID: "native-background-settlement-invalid";
+}>;
+export type NativeBackgroundReasonCode = (typeof NATIVE_BACKGROUND_REASON_CODES)[keyof typeof NATIVE_BACKGROUND_REASON_CODES];
+export interface NativeBackgroundTaskDirectiveV1 {
+    readonly kind: 'task';
+    readonly subagentType: 'neocortex';
+    readonly promptTemplate: string;
+    readonly storyIds: readonly string[];
+    readonly promptTemplates: readonly string[];
+    readonly dispatchBinding: NativeDispatchBindingV1;
+    readonly dispatchBindings: readonly NativeDispatchBindingV1[];
+    readonly backgroundDispatch: NativeBackgroundDispatchContractV1;
+    readonly rationale?: string;
+}
+export interface NativeBackgroundAdmissionInput {
+    readonly directive: unknown;
+    readonly supportsTaskDelegation: boolean;
+    readonly taskDelegationCapability: 'native_safe' | 'unsupported' | 'unvalidated' | 'disabled_by_override';
+    readonly hostAttestation: unknown;
+    readonly currentGraphRevision: string;
+}
+export interface AuthorizedNativeBackgroundEntryV1 {
+    readonly storyId: string;
+    readonly prompt: string;
+    readonly binding: NativeDispatchBindingV1;
+}
+export type EpicBackgroundDispatchDecisionV1 = Readonly<{
+    kind: 'launch';
+    entries: readonly AuthorizedNativeBackgroundEntryV1[];
+    hostAttestation: NativeHostAttestationV1;
+}> | Readonly<{
+    kind: 'reconcile-existing';
+    dispatchKeys: readonly string[];
+    reasonCode: 'native-background-reconcile-existing';
+}> | Readonly<{
+    kind: 'inline';
+    reasonCode: NativeBackgroundReasonCode;
+}> | Readonly<{
+    kind: 'denied';
+    reasonCode: NativeBackgroundReasonCode;
+}>;
+/**
+ * Admit only the exact P224-CON-DISPATCH chain. Missing native authority is an
+ * explicit inline fallback; malformed or stale authority is denied.
+ */
+export declare function planEpicBackgroundDispatch(input: NativeBackgroundAdmissionInput): EpicBackgroundDispatchDecisionV1;

package/packages/client/dist/runner/epic-background-dispatcher.js

@@ -0,0 +1 @@
+import{isNativeBackgroundDispatchContractV1 as b,isNativeDispatchBindingV1 as h,isNativeHostAttestationV1 as I}from"../continuity/native-agent-types.js";const i=Object.freeze({CONTRACT_INVALID:"directive-background-contract-invalid",BINDING_MISSING:"directive-background-binding-missing",WAVE_MISMATCH:"directive-background-wave-mismatch",GRAPH_STALE:"directive-background-graph-stale",CAPABILITY_UNVALIDATED:"native-background-capability-unvalidated",DEPTH_DENIED:"native-background-depth-denied",SETTLEMENT_INVALID:"native-background-settlement-invalid"}),v=/^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)+$/,f=/^\*yolo @docs\/stories\/([A-Za-z0-9._-]+)\.story\.md(?: branchless-preparation)?$/,y=/^(?:sha256:)?[a-f0-9]{64}$/i;function D(e){return!!e&&typeof e=="object"&&!Array.isArray(e)}function C(e,t){return e.schemaVersion===t.schemaVersion&&e.storyId===t.storyId&&e.graphRevision.toLowerCase()===t.graphRevision.toLowerCase()&&e.dispatchKey.toLowerCase()===t.dispatchKey.toLowerCase()&&e.requiredCapability===t.requiredCapability&&e.maxDepth===t.maxDepth&&e.publicSafe===t.publicSafe}function p(e){return e.toLowerCase().replace(/^sha256:/,"")}function T(e,t,n){return Object.freeze({storyId:e,prompt:t,binding:Object.freeze({...n})})}function _(e){if(!e.supportsTaskDelegation||e.taskDelegationCapability!=="native_safe"||!I(e.hostAttestation))return Object.freeze({kind:"inline",reasonCode:i.CAPABILITY_UNVALIDATED});if(!D(e.directive)||e.directive.kind!=="task"||e.directive.subagentType!=="neocortex"||!b(e.directive.backgroundDispatch))return Object.freeze({kind:"denied",reasonCode:i.CONTRACT_INVALID});if(!h(e.directive.dispatchBinding)||!Array.isArray(e.directive.dispatchBindings)||e.directive.dispatchBindings.length===0||!e.directive.dispatchBindings.every(h))return Object.freeze({kind:"denied",reasonCode:i.BINDING_MISSING});if(!y.test(e.currentGraphRevision))return Object.freeze({kind:"denied",reasonCode:i.GRAPH_STALE});const t=e.directive.storyIds,n=e.directive.promptTemplates,a=e.directive.dispatchBindings;if(!Array.isArray(t)||!Array.isArray(n)||t.length===0||t.length!==n.length||t.length!==a.length||new Set(t).size!==t.length||new Set(a.map(r=>r.dispatchKey)).size!==a.length||!C(e.directive.dispatchBinding,a[0]))return Object.freeze({kind:"denied",reasonCode:i.WAVE_MISMATCH});const g=p(e.currentGraphRevision),c=[];for(let r=0;r<t.length;r+=1){const s=t[r],d=n[r],o=a[r],A=typeof d=="string"?d.match(f):null;if(typeof s!="string"||!v.test(s)||!A||A[1]!==s||o.storyId!==s)return Object.freeze({kind:"denied",reasonCode:i.WAVE_MISMATCH});if(p(o.graphRevision)!==g)return Object.freeze({kind:"denied",reasonCode:i.GRAPH_STALE});if(o.maxDepth!==1||e.directive.backgroundDispatch.maxDepth!==1)return Object.freeze({kind:"denied",reasonCode:i.DEPTH_DENIED});c.push(T(s,d,o))}return Object.freeze({kind:"launch",entries:Object.freeze(c),hostAttestation:Object.freeze({...e.hostAttestation})})}export{i as NATIVE_BACKGROUND_REASON_CODES,_ as planEpicBackgroundDispatch};

package/packages/client/dist/runner/headless/background-root.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Root-owned execution of an already admitted native background frontier.
+ * Host-specific APIs are injected; raw handles never leave the launch/observe
+ * bridge and are absent from this module's public result.
+ */
+import { type NativeAgentDispatchReceiptV1, type NativeHostAttestationV1 } from '../../continuity/native-agent-types.js';
+import { type AuthorizedNativeBackgroundEntryV1 } from '../epic-background-dispatcher.js';
+export declare const NATIVE_BACKGROUND_MAX_POLLS = 30;
+export interface NativeBackgroundReservationV1 {
+    readonly action: 'spawn-once' | 'reconcile-existing';
+    readonly receipt: NativeAgentDispatchReceiptV1;
+}
+interface PrivateNativeHostLaunchV1 {
+    readonly rawHandle: string;
+    readonly rawParentHandle?: string | null;
+}
+export interface NativeBackgroundRootPorts {
+    /**
+     * Root-owned continuation/session/auth preflight. Implementations may use the
+     * supported P224.02/P224.03 interfaces, but must return only a public reason.
+     */
+    readonly preflight: (entries: readonly AuthorizedNativeBackgroundEntryV1[], hostAttestation: NativeHostAttestationV1) => Promise<Readonly<{
+        ok: true;
+    } | {
+        ok: false;
+        reasonCode: string;
+    }>>;
+    readonly reserve: (entry: AuthorizedNativeBackgroundEntryV1, hostAttestation: NativeHostAttestationV1) => Promise<NativeBackgroundReservationV1>;
+    readonly launch: (entry: AuthorizedNativeBackgroundEntryV1) => Promise<PrivateNativeHostLaunchV1>;
+    readonly recordSpawned: (entry: AuthorizedNativeBackgroundEntryV1, reservation: NativeBackgroundReservationV1, launch: PrivateNativeHostLaunchV1) => Promise<NativeAgentDispatchReceiptV1>;
+    readonly reconcileExisting: (entry: AuthorizedNativeBackgroundEntryV1, reservation: NativeBackgroundReservationV1) => Promise<NativeAgentDispatchReceiptV1>;
+    readonly awaitSettlement: (entry: AuthorizedNativeBackgroundEntryV1, receipt: NativeAgentDispatchReceiptV1, options: Readonly<{
+        maxPolls: 30;
+        signal?: AbortSignal;
+    }>) => Promise<NativeAgentDispatchReceiptV1>;
+}
+export interface NativeBackgroundRootResultV1 {
+    readonly kind: 'settled';
+    readonly settlement: NativeAgentDispatchReceiptV1;
+    readonly started: readonly NativeAgentDispatchReceiptV1[];
+    readonly publicSafe: true;
+}
+export declare class NativeBackgroundRootError extends Error {
+    readonly reasonCode: string;
+    constructor(reasonCode: string);
+}
+/**
+ * Reserve the whole frontier, launch only `spawn-once` entries, reconcile
+ * existing dispatches, then begin settlement. No settlement is awaited before
+ * every entry has produced a launch/reconciliation receipt.
+ */
+export declare function runNativeBackgroundRoot(entries: readonly AuthorizedNativeBackgroundEntryV1[], hostAttestation: NativeHostAttestationV1, ports: NativeBackgroundRootPorts, options?: Readonly<{
+    signal?: AbortSignal;
+}>): Promise<NativeBackgroundRootResultV1>;
+export interface BoundedNativeBackgroundPollResultV1 {
+    readonly receipt: NativeAgentDispatchReceiptV1 | null;
+    readonly polls: number;
+    readonly exhausted: boolean;
+}
+/** Sequential by construction: at most one poll is in flight for one dispatch. */
+export declare function boundedNativeBackgroundPoll(poll: (attempt: number) => Promise<NativeAgentDispatchReceiptV1 | null>, options?: Readonly<{
+    maxPolls?: number;
+    signal?: AbortSignal;
+}>): Promise<BoundedNativeBackgroundPollResultV1>;
+export {};

package/packages/client/dist/runner/headless/background-root.js

@@ -0,0 +1 @@
+import{isNativeAgentDispatchReceiptV1 as m,NATIVE_AGENT_TERMINAL_STATES as g}from"../../continuity/native-agent-types.js";import{NATIVE_BACKGROUND_REASON_CODES as d}from"../epic-background-dispatcher.js";const w=30;class c extends Error{reasonCode;constructor(a){super(a),this.reasonCode=a,this.name="NativeBackgroundRootError"}}function u(e,a){if(!m(e)||e.storyId!==a.storyId||e.dispatchKey!==a.binding.dispatchKey||e.graphRevision.replace(/^sha256:/,"").toLowerCase()!==a.binding.graphRevision.replace(/^sha256:/,"").toLowerCase()||e.topology!=="native-agent")throw new c(d.SETTLEMENT_INVALID);return e}async function T(e,a,r,o={}){if(e.length===0)throw new c(d.WAVE_MISMATCH);const n=await r.preflight(e,a);if(!n.ok)throw new c(n.reasonCode);const i=await Promise.all(e.map(t=>r.reserve(t,a))),E=await Promise.all(e.map(async(t,l)=>{const s=i[l];if(u(s.receipt,t),s.action==="reconcile-existing")return u(await r.reconcileExisting(t,s),t);const h=await r.launch(t);return u(await r.recordSpawned(t,s,h),t)}));let f;try{f=await Promise.any(E.map((t,l)=>r.awaitSettlement(e[l],t,{maxPolls:w,...o.signal?{signal:o.signal}:{}}).then(s=>{const h=u(s,e[l]);if(!g.has(h.state))throw new c(d.SETTLEMENT_INVALID);return h})))}catch{throw new c(d.SETTLEMENT_INVALID)}return Object.freeze({kind:"settled",settlement:f,started:Object.freeze([...E]),publicSafe:!0})}async function A(e,a={}){const r=Math.max(1,Math.min(w,a.maxPolls??w));let o=null,n=0;for(let i=1;i<=r&&!a.signal?.aborted;i+=1)if(o=await e(i),n=i,o&&g.has(o.state))return Object.freeze({receipt:o,polls:n,exhausted:!1});return Object.freeze({receipt:o,polls:n,exhausted:n>=r})}export{w as NATIVE_BACKGROUND_MAX_POLLS,c as NativeBackgroundRootError,A as boundedNativeBackgroundPoll,T as runNativeBackgroundRoot};

package/packages/client/dist/runner/headless/epic-terminal-git-runner.d.ts

@@ -3,6 +3,7 @@ import { type EpicTerminalReleaseAuthority, type P205TransientExecutionAuthority
 import { type EpicMergeCandidateQaAuthority } from './epic-merge-candidate-qa.js';
 import type { EpicMergeCandidateQaReceipt } from '../../../../shared/dist/yoloop/epic-terminal-git.js';
 import type { EpicPullRequestMergeGuardReceipt } from '../../../../shared/dist/yoloop/epic-terminal-git.js';
+import { type ManagedEnvironmentCleanupAdapter, type ManagedEnvironmentCleanupReceiptV1, type ManagedEnvironmentCleanupRequestV1 } from './managed-environment-cleanup.js';
 export interface EpicTerminalGitSnapshot {
     readonly executionHeadSha: string;
     readonly originHeadSha: string;
@@ -15,6 +16,8 @@ export interface EpicTerminalGitSnapshot {
     readonly originBinding?: import('../../../../shared/dist/yoloop/epic-terminal-git.js').EpicOriginBindingEvidence | null;
     readonly nowIso?: string;
     readonly reconciliationCandidates: readonly GitReconciliationCandidate[];
+    /** Optional capability-bound resources. Absence means no environment effect is authorized. */
+    readonly managedEnvironmentCleanupRequests?: readonly ManagedEnvironmentCleanupRequestV1[];
 }
 export type EpicTerminalEffectResult<T extends object = object> = ({
     readonly ok: true;
@@ -25,6 +28,8 @@ export type EpicTerminalEffectResult<T extends object = object> = ({
     readonly externalPolicy: boolean;
 };
 export interface EpicTerminalGitAdapter {
+    /** Optional installed capability. Missing capability preserves managed resources as pending. */
+    readonly managedEnvironmentCleanup?: ManagedEnvironmentCleanupAdapter;
     /** Produce missing physical origin/aggregate-QA evidence before server projection. */
     prepareLifecycleEvidence?(input: {
         readonly epicId: string;
@@ -128,6 +133,8 @@ export interface EpicTerminalGitAdapter {
         readonly terminalReceipt: EpicTerminalGitReceipt;
         readonly reconciliationReceipts: readonly GitReconciliationReceipt[];
         readonly preservedDecisions: readonly GitReconciliationDecision[];
+        /** Kept separate from merge/Git reconciliation; production persistence requires an accepted store claim. */
+        readonly managedEnvironmentCleanupReceipts?: readonly ManagedEnvironmentCleanupReceiptV1[];
     }): Promise<EpicTerminalEffectResult>;
 }
 export interface EpicTerminalGitExecutionResult {
@@ -135,6 +142,8 @@ export interface EpicTerminalGitExecutionResult {
     readonly receipt: EpicTerminalGitReceipt;
     readonly reconciliationReceipts: readonly GitReconciliationReceipt[];
     readonly preservedDecisions: readonly GitReconciliationDecision[];
+    readonly managedEnvironmentCleanupReceipts: readonly ManagedEnvironmentCleanupReceiptV1[];
+    readonly managedEnvironmentCleanupPending: boolean;
     readonly reasonCodes: readonly string[];
     readonly publicSafe: true;
 }

package/packages/client/dist/runner/headless/epic-terminal-git-runner.js

@@ -1,2 +1,2 @@
-import{createHash as w}from"node:crypto";import{EPIC_TERMINAL_GIT_REASON_CODES as x,classifyGitReconciliationCandidate as N,validateEpicTerminalGitDirective as q}from"../../../../shared/dist/yoloop/epic-terminal-git.js";import{consumeEpicTerminalReleaseAuthority as P}from"../../git/git-lifecycle-store.js";import{verifiedEpicMergeCandidateReceipt as E}from"./epic-merge-candidate-qa.js";async function O(e,r,s){const c=await r.inspectReconciliation(e);if(!c.ok)return{ok:!1,reconciliationReceipts:[],preservedDecisions:[],reasonCodes:[c.reasonCode],publicSafe:!0};const o=await k({idempotencyKey:e.idempotencyKey,enabled:!0,dryRun:e.dryRun},c.candidates,r,s),l=await r.persistReconciliation({epicId:e.epicId,reconciliationReceipts:o.receipts,preservedDecisions:o.preserved}),u=C([...o.reasonCodes,...l.ok?[]:[l.reasonCode]]);return{ok:o.ok&&l.ok,reconciliationReceipts:o.receipts,preservedDecisions:o.preserved,reasonCodes:u,publicSafe:!0}}async function T(e,r,s,c){const o=s();if(!r.prepareLifecycleEvidence)return S(e,{ok:!1,reasonCode:"epic-aggregate-qa-producer-required",retryEligible:!1,externalPolicy:!1},o);const l=c?{ok:!0,originBindingCaptured:!1,aggregateQaRecorded:!0,terminalAuthority:c}:await r.prepareLifecycleEvidence({epicId:e.epicId,nowIso:o});if(!l.ok)return S(e,l,o);const u=l.terminalAuthority??l.p205Authority;if(!u)return S(e,{ok:!1,reasonCode:"epic-aggregate-qa-authority-required",retryEligible:!1,externalPolicy:!1},o);const p=await r.inspect(e);if(!p.ok)return S(e,p,o);const a=p.snapshot,h=q(e,{...a,nowIso:o});if(!h.ready)return y(!1,R(e,a,o,{strategy:e.strategy==="single_pr"?"single_pr":"direct",physicalStatus:"blocked_local_or_repo",retryEligible:h.reasonCodes.some(t=>t.endsWith("mismatch")||t.endsWith("active")),reasonCodes:h.reasonCodes}),[],[],h.reasonCodes);if(!a.aggregateQaReceipt||!P(u,{executionHeadSha:a.executionHeadSha,graphRevision:e.graphRevision,aggregateQaReceipt:a.aggregateQaReceipt,headReconciliationReceipt:a.headReconciliationReceipt}))return S(e,{ok:!1,reasonCode:"epic-aggregate-qa-authority-binding-mismatch",retryEligible:!1,externalPolicy:!1},o);if(h.reasonCodes.includes(x.ALREADY_COMPLETE)&&a.existingReceipt){const t=await r.verifyTerminalReceipt(e,a.existingReceipt,o);if(!t.ok)return y(!1,a.existingReceipt,[],[],[t.reasonCode]);const I=E(t.candidateAuthority,{mergeSha:a.existingReceipt.mergeSha,originHeadSha:a.existingReceipt.baseSha,executionHeadSha:a.existingReceipt.executionHeadSha,graphRevision:e.graphRevision});if(!I)return y(!1,a.existingReceipt,[],[],["epic-merge-candidate-authority-required"]);const B={...a.existingReceipt,candidateQa:I,...t.providerGuard?{providerGuard:t.providerGuard}:{}},f=await k({idempotencyKey:e.idempotencyKey,enabled:e.reconcile.enabled,dryRun:e.reconcile.dryRun},a.reconciliationCandidates,r,s),_=await r.persist({terminalReceipt:B,reconciliationReceipts:f.receipts,preservedDecisions:f.preserved}),A=C([...h.reasonCodes,...f.reasonCodes,..._.ok?[]:[_.reasonCode]]);return y(_.ok&&f.ok,B,f.receipts,f.preserved,A)}let i;const n=await r.prepareMergeObject({originBranch:e.originBranch,executionBranch:e.executionBranch,originHeadSha:a.originHeadSha,executionHeadSha:a.executionHeadSha,graphRevision:e.graphRevision,nowIso:o,message:[`merge(${e.epicId}): integrate ${e.executionBranch} into ${e.originBranch}`,"",`Neocortex-Epic: ${e.epicId}`,`Neocortex-Origin-Branch: ${e.originBranch}`,`Neocortex-Execution-Branch: ${e.executionBranch}`,`Neocortex-Execution-Head: ${a.executionHeadSha}`,`Neocortex-Origin-Base: ${a.originHeadSha}`,`Neocortex-Graph-Revision: ${e.graphRevision}`,`Neocortex-Aggregate-QA: ${e.localGates.aggregateQaReceipt.receiptRef}`,`Neocortex-Idempotency: ${e.idempotencyKey}`].join(`
-`)});if(!n.ok)return i=R(e,a,o,{strategy:"direct",physicalStatus:"blocked_local_or_repo",retryEligible:n.retryEligible,reasonCodes:[n.reasonCode]}),await r.persist({terminalReceipt:i,reconciliationReceipts:[],preservedDecisions:[]}),y(!1,i,[],[],i.reasonCodes);const g=E(n.candidateAuthority,{originHeadSha:a.originHeadSha,executionHeadSha:a.executionHeadSha,mergeSha:n.mergeSha,graphRevision:e.graphRevision});if(!g)return S(e,{ok:!1,reasonCode:"epic-merge-candidate-authority-required",retryEligible:!1,externalPolicy:!1},o);if(e.strategy!=="single_pr"){const t=await r.pushMergeObject({epicId:e.epicId,originBranch:e.originBranch,executionBranch:e.executionBranch,executionHeadSha:a.executionHeadSha,expectedOriginSha:a.originHeadSha,mergeSha:n.mergeSha,graphRevision:e.graphRevision,candidateAuthority:n.candidateAuthority,storyCheckpointIds:e.storyCheckpointIds,aggregateQaReceipt:e.localGates.aggregateQaReceipt,nowIso:s()});t.ok?i=R(e,a,o,{strategy:"direct",mergeSha:n.mergeSha,pushedSha:t.pushedSha,candidateQa:g,physicalStatus:"pushed",retryEligible:!1,reasonCodes:[x.READY],completedAt:s()}):e.strategy==="direct_or_single_pr"&&t.externalPolicy?i=await H(e,a,r,o,s,g,n.candidateAuthority):i=R(e,a,o,{strategy:"direct",mergeSha:n.mergeSha,physicalStatus:t.externalPolicy?"denied_external_gate":"blocked_local_or_repo",retryEligible:t.retryEligible,reasonCodes:[t.reasonCode,...t.retryEligible?[x.RETRY_ELIGIBLE]:[]]})}else i=await H(e,a,r,o,s,g,n.candidateAuthority);const d=i.physicalStatus==="pushed"?await r.verifyTerminalReceipt(e,i,s()):null;if(d&&!d.ok){const t=R(e,a,o,{...i,physicalStatus:"blocked_local_or_repo",retryEligible:d.retryEligible,reasonCodes:[d.reasonCode]});return await r.persist({terminalReceipt:t,reconciliationReceipts:[],preservedDecisions:[]}),y(!1,t,[],[],t.reasonCodes)}if(d?.ok){const t=E(d.candidateAuthority,{mergeSha:i.mergeSha,originHeadSha:i.baseSha,executionHeadSha:i.executionHeadSha,graphRevision:e.graphRevision});if(!t)return y(!1,i,[],[],["epic-merge-candidate-authority-required"]);i={...i,candidateQa:t,...d.providerGuard?{providerGuard:d.providerGuard}:{}}}const m=i.physicalStatus==="pushed"?await k({idempotencyKey:e.idempotencyKey,enabled:e.reconcile.enabled,dryRun:e.reconcile.dryRun},a.reconciliationCandidates,r,s):{ok:!0,receipts:[],preserved:[],reasonCodes:[]},b=await r.persist({terminalReceipt:i,reconciliationReceipts:m.receipts,preservedDecisions:m.preserved}),G=C([...i.reasonCodes,...m.reasonCodes,...b.ok?[]:[b.reasonCode]]);return y(i.physicalStatus==="pushed"&&m.ok&&b.ok,i,m.receipts,m.preserved,G)}async function H(e,r,s,c,o,l,u){const p=await s.ensureSingleEpicPullRequest({epicId:e.epicId,originBranch:e.originBranch,executionBranch:e.executionBranch,expectedStoryHeadSha:r.executionHeadSha,expectedPullRequestHeadSha:l.mergeSha,candidateQa:l,candidateAuthority:u,idempotencyKey:e.idempotencyKey,terminalBinding:{graphRevision:e.graphRevision,storyCheckpointIds:e.storyCheckpointIds,aggregateQaReceipt:e.localGates.aggregateQaReceipt,nowIso:o()}});if(!p.ok)return R(e,r,c,{strategy:"single_pr",physicalStatus:p.externalPolicy?"denied_external_gate":"blocked_local_or_repo",retryEligible:p.retryEligible,reasonCodes:[p.reasonCode]});const a=await s.mergeEpicPullRequest({epicId:e.epicId,prNumber:p.prNumber,originBranch:e.originBranch,executionBranch:e.executionBranch,expectedStoryHeadSha:r.executionHeadSha,expectedPullRequestHeadSha:l.mergeSha,expectedOriginHeadSha:r.originHeadSha,candidateQa:l,candidateAuthority:u,nowIso:o(),terminalBinding:{graphRevision:e.graphRevision,storyCheckpointIds:e.storyCheckpointIds,aggregateQaReceipt:e.localGates.aggregateQaReceipt}});return a.ok?R(e,r,c,{strategy:"single_pr",prNumber:p.prNumber,mergeSha:a.mergeSha,pushedSha:a.pushedSha,candidateQa:l,providerGuard:a.providerGuard,physicalStatus:"pushed",retryEligible:!1,reasonCodes:[x.READY],completedAt:o()}):R(e,r,c,{strategy:"single_pr",prNumber:p.prNumber,physicalStatus:a.externalPolicy?"denied_external_gate":"blocked_local_or_repo",retryEligible:a.retryEligible,reasonCodes:[a.reasonCode,...a.retryEligible?[x.RETRY_ELIGIBLE]:[]]})}async function k(e,r,s,c){if(!e.enabled)return{ok:!0,receipts:[],preserved:[],reasonCodes:[]};const o=[],l=[],u=[];let p=!0;const a=new Set,h={pull_request:0,local_branch:1,remote_branch:2};for(const i of[...r].sort((n,g)=>h[n.kind]-h[g.kind]||n.resourceId.localeCompare(g.resourceId))){const n=N(i);if(u.push(...n.reasonCodes),n.action==="preserve"){l.push(n);continue}if(i.kind!=="pull_request"&&a.has(i.branchName)){l.push({...n,action:"preserve",reasonCodes:["git-resource-related-pr-close-pending"]}),u.push("git-resource-related-pr-close-pending");continue}const g=`reconciliation:v2:${w("sha256").update([i.resourceId,n.action].join("\0")).digest("hex")}`,d=await s.applyReconciliation(i,n,e.dryRun);if(!d.ok){p=!1,i.kind==="pull_request"&&a.add(i.branchName),u.push(d.reasonCode),o.push({schemaVersion:1,resourceId:i.resourceId,action:n.action,outcome:"failed",idempotencyKey:g,reasonCodes:[d.reasonCode],recordedAt:c(),publicSafe:!0});continue}o.push({schemaVersion:1,resourceId:i.resourceId,action:n.action,outcome:d.outcome,idempotencyKey:g,reasonCodes:n.reasonCodes,recordedAt:c(),publicSafe:!0})}return{ok:p,receipts:o,preserved:l,reasonCodes:C(u)}}function R(e,r,s,c){return Object.freeze({schemaVersion:1,epicId:e.epicId,executionBranch:e.executionBranch,originBranch:e.originBranch,baseSha:r.originHeadSha,executionHeadSha:r.executionHeadSha,localGateReceiptRefs:e.localGates.receiptRefs,idempotencyKey:e.idempotencyKey,attemptStartedAt:s,publicSafe:!0,...c})}function S(e,r,s){const c="0".repeat(40),o={schemaVersion:1,epicId:e.epicId,executionBranch:e.executionBranch,originBranch:e.originBranch,baseSha:c,executionHeadSha:e.expectedExecutionHeadSha,strategy:e.strategy==="single_pr"?"single_pr":"direct",physicalStatus:r.externalPolicy?"denied_external_gate":"blocked_local_or_repo",localGateReceiptRefs:e.localGates.receiptRefs,idempotencyKey:e.idempotencyKey,attemptStartedAt:s,retryEligible:r.retryEligible,reasonCodes:[r.reasonCode],publicSafe:!0};return y(!1,o,[],[],o.reasonCodes)}function y(e,r,s,c,o){return{ok:e,receipt:r,reconciliationReceipts:s,preservedDecisions:c,reasonCodes:C(o),publicSafe:!0}}function C(e){return[...new Set(e)]}export{O as executeEpicGitReconciliation,T as executeEpicTerminalGit};
+import{createHash as K}from"node:crypto";import{EPIC_TERMINAL_GIT_REASON_CODES as x,classifyGitReconciliationCandidate as D,validateEpicTerminalGitDirective as $}from"../../../../shared/dist/yoloop/epic-terminal-git.js";import{consumeEpicTerminalReleaseAuthority as Q}from"../../git/git-lifecycle-store.js";import{verifiedEpicMergeCandidateReceipt as I}from"./epic-merge-candidate-qa.js";import{executeManagedEnvironmentCleanup as A}from"./managed-environment-cleanup.js";async function Y(e,n,t){const p=await n.inspectReconciliation(e);if(!p.ok)return{ok:!1,reconciliationReceipts:[],preservedDecisions:[],reasonCodes:[p.reasonCode],publicSafe:!0};const r=await B({idempotencyKey:e.idempotencyKey,enabled:!0,dryRun:e.dryRun},p.candidates,n,t),c=await n.persistReconciliation({epicId:e.epicId,reconciliationReceipts:r.receipts,preservedDecisions:r.preserved}),u=C([...r.reasonCodes,...c.ok?[]:[c.reasonCode]]);return{ok:r.ok&&c.ok,reconciliationReceipts:r.receipts,preservedDecisions:r.preserved,reasonCodes:u,publicSafe:!0}}async function V(e,n,t,p){const r=t();if(!n.prepareLifecycleEvidence)return S(e,{ok:!1,reasonCode:"epic-aggregate-qa-producer-required",retryEligible:!1,externalPolicy:!1},r);const c=p?{ok:!0,originBindingCaptured:!1,aggregateQaRecorded:!0,terminalAuthority:p}:await n.prepareLifecycleEvidence({epicId:e.epicId,nowIso:r});if(!c.ok)return S(e,c,r);const u=c.terminalAuthority??c.p205Authority;if(!u)return S(e,{ok:!1,reasonCode:"epic-aggregate-qa-authority-required",retryEligible:!1,externalPolicy:!1},r);const l=await n.inspect(e);if(!l.ok)return S(e,l,r);const a=l.snapshot,h=$(e,{...a,nowIso:r});if(!h.ready)return y(!1,m(e,a,r,{strategy:e.strategy==="single_pr"?"single_pr":"direct",physicalStatus:"blocked_local_or_repo",retryEligible:h.reasonCodes.some(s=>s.endsWith("mismatch")||s.endsWith("active")),reasonCodes:h.reasonCodes}),[],[],h.reasonCodes);if(!a.aggregateQaReceipt||!Q(u,{executionHeadSha:a.executionHeadSha,graphRevision:e.graphRevision,aggregateQaReceipt:a.aggregateQaReceipt,headReconciliationReceipt:a.headReconciliationReceipt}))return S(e,{ok:!1,reasonCode:"epic-aggregate-qa-authority-binding-mismatch",retryEligible:!1,externalPolicy:!1},r);if(h.reasonCodes.includes(x.ALREADY_COMPLETE)&&a.existingReceipt){const s=await n.verifyTerminalReceipt(e,a.existingReceipt,r);if(!s.ok)return y(!1,a.existingReceipt,[],[],[s.reasonCode]);const H=I(s.candidateAuthority,{mergeSha:a.existingReceipt.mergeSha,originHeadSha:a.existingReceipt.baseSha,executionHeadSha:a.existingReceipt.executionHeadSha,graphRevision:e.graphRevision});if(!H)return y(!1,a.existingReceipt,[],[],["epic-merge-candidate-authority-required"]);const G={...a.existingReceipt,candidateQa:H,...s.providerGuard?{providerGuard:s.providerGuard}:{}},f=await B({idempotencyKey:e.idempotencyKey,enabled:e.reconcile.enabled,dryRun:e.reconcile.dryRun},a.reconciliationCandidates,n,t),E=await A(a.managedEnvironmentCleanupRequests??[],n.managedEnvironmentCleanup,t),k=await n.persist({terminalReceipt:G,reconciliationReceipts:f.receipts,preservedDecisions:f.preserved,managedEnvironmentCleanupReceipts:E.receipts}),P=C([...h.reasonCodes,...f.reasonCodes,...E.reasonCodes,...k.ok?[]:[k.reasonCode]]);return y(k.ok&&f.ok&&E.ok,G,f.receipts,f.preserved,P,E)}let o;const i=await n.prepareMergeObject({originBranch:e.originBranch,executionBranch:e.executionBranch,originHeadSha:a.originHeadSha,executionHeadSha:a.executionHeadSha,graphRevision:e.graphRevision,nowIso:r,message:[`merge(${e.epicId}): integrate ${e.executionBranch} into ${e.originBranch}`,"",`Neocortex-Epic: ${e.epicId}`,`Neocortex-Origin-Branch: ${e.originBranch}`,`Neocortex-Execution-Branch: ${e.executionBranch}`,`Neocortex-Execution-Head: ${a.executionHeadSha}`,`Neocortex-Origin-Base: ${a.originHeadSha}`,`Neocortex-Graph-Revision: ${e.graphRevision}`,`Neocortex-Aggregate-QA: ${e.localGates.aggregateQaReceipt.receiptRef}`,`Neocortex-Idempotency: ${e.idempotencyKey}`].join(`
+`)});if(!i.ok)return o=m(e,a,r,{strategy:"direct",physicalStatus:"blocked_local_or_repo",retryEligible:i.retryEligible,reasonCodes:[i.reasonCode]}),await n.persist({terminalReceipt:o,reconciliationReceipts:[],preservedDecisions:[]}),y(!1,o,[],[],o.reasonCodes);const g=I(i.candidateAuthority,{originHeadSha:a.originHeadSha,executionHeadSha:a.executionHeadSha,mergeSha:i.mergeSha,graphRevision:e.graphRevision});if(!g)return S(e,{ok:!1,reasonCode:"epic-merge-candidate-authority-required",retryEligible:!1,externalPolicy:!1},r);if(e.strategy!=="single_pr"){const s=await n.pushMergeObject({epicId:e.epicId,originBranch:e.originBranch,executionBranch:e.executionBranch,executionHeadSha:a.executionHeadSha,expectedOriginSha:a.originHeadSha,mergeSha:i.mergeSha,graphRevision:e.graphRevision,candidateAuthority:i.candidateAuthority,storyCheckpointIds:e.storyCheckpointIds,aggregateQaReceipt:e.localGates.aggregateQaReceipt,nowIso:t()});s.ok?o=m(e,a,r,{strategy:"direct",mergeSha:i.mergeSha,pushedSha:s.pushedSha,candidateQa:g,physicalStatus:"pushed",retryEligible:!1,reasonCodes:[x.READY],completedAt:t()}):e.strategy==="direct_or_single_pr"&&s.externalPolicy?o=await q(e,a,n,r,t,g,i.candidateAuthority):o=m(e,a,r,{strategy:"direct",mergeSha:i.mergeSha,physicalStatus:s.externalPolicy?"denied_external_gate":"blocked_local_or_repo",retryEligible:s.retryEligible,reasonCodes:[s.reasonCode,...s.retryEligible?[x.RETRY_ELIGIBLE]:[]]})}else o=await q(e,a,n,r,t,g,i.candidateAuthority);const d=o.physicalStatus==="pushed"?await n.verifyTerminalReceipt(e,o,t()):null;if(d&&!d.ok){const s=m(e,a,r,{...o,physicalStatus:"blocked_local_or_repo",retryEligible:d.retryEligible,reasonCodes:[d.reasonCode]});return await n.persist({terminalReceipt:s,reconciliationReceipts:[],preservedDecisions:[]}),y(!1,s,[],[],s.reasonCodes)}if(d?.ok){const s=I(d.candidateAuthority,{mergeSha:o.mergeSha,originHeadSha:o.baseSha,executionHeadSha:o.executionHeadSha,graphRevision:e.graphRevision});if(!s)return y(!1,o,[],[],["epic-merge-candidate-authority-required"]);o={...o,candidateQa:s,...d.providerGuard?{providerGuard:d.providerGuard}:{}}}const R=o.physicalStatus==="pushed"?await B({idempotencyKey:e.idempotencyKey,enabled:e.reconcile.enabled,dryRun:e.reconcile.dryRun},a.reconciliationCandidates,n,t):{ok:!0,receipts:[],preserved:[],reasonCodes:[]},b=o.physicalStatus==="pushed"?await A(a.managedEnvironmentCleanupRequests??[],n.managedEnvironmentCleanup,t):w(),_=await n.persist({terminalReceipt:o,reconciliationReceipts:R.receipts,preservedDecisions:R.preserved,managedEnvironmentCleanupReceipts:b.receipts}),N=C([...o.reasonCodes,...R.reasonCodes,...b.reasonCodes,..._.ok?[]:[_.reasonCode]]);return y(o.physicalStatus==="pushed"&&R.ok&&b.ok&&_.ok,o,R.receipts,R.preserved,N,b)}async function q(e,n,t,p,r,c,u){const l=await t.ensureSingleEpicPullRequest({epicId:e.epicId,originBranch:e.originBranch,executionBranch:e.executionBranch,expectedStoryHeadSha:n.executionHeadSha,expectedPullRequestHeadSha:c.mergeSha,candidateQa:c,candidateAuthority:u,idempotencyKey:e.idempotencyKey,terminalBinding:{graphRevision:e.graphRevision,storyCheckpointIds:e.storyCheckpointIds,aggregateQaReceipt:e.localGates.aggregateQaReceipt,nowIso:r()}});if(!l.ok)return m(e,n,p,{strategy:"single_pr",physicalStatus:l.externalPolicy?"denied_external_gate":"blocked_local_or_repo",retryEligible:l.retryEligible,reasonCodes:[l.reasonCode]});const a=await t.mergeEpicPullRequest({epicId:e.epicId,prNumber:l.prNumber,originBranch:e.originBranch,executionBranch:e.executionBranch,expectedStoryHeadSha:n.executionHeadSha,expectedPullRequestHeadSha:c.mergeSha,expectedOriginHeadSha:n.originHeadSha,candidateQa:c,candidateAuthority:u,nowIso:r(),terminalBinding:{graphRevision:e.graphRevision,storyCheckpointIds:e.storyCheckpointIds,aggregateQaReceipt:e.localGates.aggregateQaReceipt}});return a.ok?m(e,n,p,{strategy:"single_pr",prNumber:l.prNumber,mergeSha:a.mergeSha,pushedSha:a.pushedSha,candidateQa:c,providerGuard:a.providerGuard,physicalStatus:"pushed",retryEligible:!1,reasonCodes:[x.READY],completedAt:r()}):m(e,n,p,{strategy:"single_pr",prNumber:l.prNumber,physicalStatus:a.externalPolicy?"denied_external_gate":"blocked_local_or_repo",retryEligible:a.retryEligible,reasonCodes:[a.reasonCode,...a.retryEligible?[x.RETRY_ELIGIBLE]:[]]})}async function B(e,n,t,p){if(!e.enabled)return{ok:!0,receipts:[],preserved:[],reasonCodes:[]};const r=[],c=[],u=[];let l=!0;const a=new Set,h={pull_request:0,local_branch:1,remote_branch:2};for(const o of[...n].sort((i,g)=>h[i.kind]-h[g.kind]||i.resourceId.localeCompare(g.resourceId))){const i=D(o);if(u.push(...i.reasonCodes),i.action==="preserve"){c.push(i);continue}if(o.kind!=="pull_request"&&a.has(o.branchName)){c.push({...i,action:"preserve",reasonCodes:["git-resource-related-pr-close-pending"]}),u.push("git-resource-related-pr-close-pending");continue}const g=`reconciliation:v2:${K("sha256").update([o.resourceId,i.action].join("\0")).digest("hex")}`,d=await t.applyReconciliation(o,i,e.dryRun);if(!d.ok){l=!1,o.kind==="pull_request"&&a.add(o.branchName),u.push(d.reasonCode),r.push({schemaVersion:1,resourceId:o.resourceId,action:i.action,outcome:"failed",idempotencyKey:g,reasonCodes:[d.reasonCode],recordedAt:p(),publicSafe:!0});continue}r.push({schemaVersion:1,resourceId:o.resourceId,action:i.action,outcome:d.outcome,idempotencyKey:g,reasonCodes:i.reasonCodes,recordedAt:p(),publicSafe:!0})}return{ok:l,receipts:r,preserved:c,reasonCodes:C(u)}}function m(e,n,t,p){return Object.freeze({schemaVersion:1,epicId:e.epicId,executionBranch:e.executionBranch,originBranch:e.originBranch,baseSha:n.originHeadSha,executionHeadSha:n.executionHeadSha,localGateReceiptRefs:e.localGates.receiptRefs,idempotencyKey:e.idempotencyKey,attemptStartedAt:t,publicSafe:!0,...p})}function S(e,n,t){const p="0".repeat(40),r={schemaVersion:1,epicId:e.epicId,executionBranch:e.executionBranch,originBranch:e.originBranch,baseSha:p,executionHeadSha:e.expectedExecutionHeadSha,strategy:e.strategy==="single_pr"?"single_pr":"direct",physicalStatus:n.externalPolicy?"denied_external_gate":"blocked_local_or_repo",localGateReceiptRefs:e.localGates.receiptRefs,idempotencyKey:e.idempotencyKey,attemptStartedAt:t,retryEligible:n.retryEligible,reasonCodes:[n.reasonCode],publicSafe:!0};return y(!1,r,[],[],r.reasonCodes)}function y(e,n,t,p,r,c=w()){return{ok:e,receipt:n,reconciliationReceipts:t,preservedDecisions:p,managedEnvironmentCleanupReceipts:c.receipts,managedEnvironmentCleanupPending:c.pending,reasonCodes:C(r),publicSafe:!0}}function w(){return{ok:!0,pending:!1,receipts:[],reasonCodes:[],publicSafe:!0}}function C(e){return[...new Set(e)]}export{Y as executeEpicGitReconciliation,V as executeEpicTerminalGit};

package/packages/client/dist/runner/headless/managed-environment-cleanup.d.ts

@@ -0,0 +1,95 @@
+/**
+ * P224.05 -- fail-closed cleanup of explicitly managed temporary resources.
+ *
+ * This module owns policy and replay ordering only. Concrete host, process and
+ * interface effects stay behind an injected adapter. Production callers that
+ * do not have a supported adapter preserve resources as pending.
+ */
+export type ManagedEnvironmentResourceKind = 'worktree' | 'process' | 'interface_entry';
+export type ManagedEnvironmentEffect = 'remove_managed_worktree' | 'stop_owned_process' | 'remove_interface_entry';
+export interface ManagedEnvironmentCleanupReceiptV1 {
+    readonly schemaVersion: 1;
+    readonly resourceId: string;
+    readonly effect: ManagedEnvironmentEffect;
+    readonly outcome: 'applied' | 'already_absent' | 'preserved' | 'failed';
+    readonly expectedOwnerDigest: string;
+    readonly expectedRevision: string;
+    readonly idempotencyKey: string;
+    readonly reasonCodes: readonly string[];
+    readonly checkedAt: string;
+    readonly recordedAt: string;
+    readonly publicSafe: true;
+}
+export interface ManagedEnvironmentCleanupRequestV1 {
+    readonly schemaVersion: 1;
+    readonly resourceId: string;
+    readonly epicId: string;
+    readonly expectedKind: ManagedEnvironmentResourceKind;
+    readonly expectedOwnerDigest: string;
+    readonly expectedRevision: string;
+    readonly effect: ManagedEnvironmentEffect;
+    readonly existingReceipt?: ManagedEnvironmentCleanupReceiptV1;
+    readonly publicSafe: true;
+}
+export interface ManagedEnvironmentSnapshotV1 {
+    readonly schemaVersion: 1;
+    readonly resourceId: string;
+    readonly epicId: string;
+    readonly ownerDigest: string;
+    readonly revision: string;
+    readonly kind: ManagedEnvironmentResourceKind;
+    readonly presence: 'present' | 'absent' | 'unknown';
+    readonly managed: boolean;
+    readonly active: boolean;
+    readonly clean: boolean | 'unknown';
+    readonly integrated: boolean;
+    readonly capability: 'supported' | 'unsupported';
+    readonly protected: boolean;
+    readonly primary: boolean;
+    readonly locked: boolean;
+    readonly submoduleActive: boolean;
+    readonly preservableIgnored: boolean;
+    readonly publicSafe: true;
+}
+export type ManagedEnvironmentEffectResult<T extends object> = ({
+    readonly ok: true;
+} & T) | {
+    readonly ok: false;
+    readonly reasonCode: string;
+};
+export interface ManagedEnvironmentCleanupAdapter {
+    inspect(request: ManagedEnvironmentCleanupRequestV1): Promise<ManagedEnvironmentEffectResult<{
+        readonly snapshot: ManagedEnvironmentSnapshotV1;
+    }>>;
+    apply(input: {
+        readonly request: ManagedEnvironmentCleanupRequestV1;
+        readonly snapshot: ManagedEnvironmentSnapshotV1;
+        readonly effect: ManagedEnvironmentEffect;
+        readonly idempotencyKey: string;
+    }): Promise<ManagedEnvironmentEffectResult<{
+        readonly receipt: ManagedEnvironmentCleanupReceiptV1;
+    }>>;
+    reconcile(input: {
+        readonly request: ManagedEnvironmentCleanupRequestV1;
+        readonly receipt: ManagedEnvironmentCleanupReceiptV1;
+    }): Promise<ManagedEnvironmentEffectResult<{
+        readonly receipt: ManagedEnvironmentCleanupReceiptV1;
+    }>>;
+}
+export interface ManagedEnvironmentCleanupResult {
+    readonly ok: boolean;
+    readonly pending: boolean;
+    readonly receipts: readonly ManagedEnvironmentCleanupReceiptV1[];
+    readonly reasonCodes: readonly string[];
+    readonly publicSafe: true;
+}
+interface Classification {
+    readonly action: 'apply' | 'already_absent' | 'preserve';
+    readonly pending: boolean;
+    readonly reasonCodes: readonly string[];
+}
+/** Reconcile durable evidence before any new effect, then apply at most once. */
+export declare function executeManagedEnvironmentCleanup(requests: readonly ManagedEnvironmentCleanupRequestV1[], adapter: ManagedEnvironmentCleanupAdapter | undefined, now: () => string): Promise<ManagedEnvironmentCleanupResult>;
+export declare function classifyManagedEnvironmentSnapshot(request: ManagedEnvironmentCleanupRequestV1, snapshot: ManagedEnvironmentSnapshotV1): Classification;
+export declare function managedEnvironmentCleanupIdempotencyKey(request: Pick<ManagedEnvironmentCleanupRequestV1, 'resourceId' | 'effect' | 'expectedOwnerDigest' | 'expectedRevision'>): string;
+export {};

package/packages/client/dist/runner/headless/managed-environment-cleanup.js

@@ -0,0 +1 @@
+import{createHash as E}from"node:crypto";const D={remove_managed_worktree:"worktree",stop_owned_process:"process",remove_interface_entry:"interface_entry"};async function M(e,n,c){const t=[],a=[],h=new Set;let d=!1,s=!1;for(const r of e){const R=`${r.resourceId}\0${r.effect}`;if(h.has(R)){const i=m(r,I(r),"managed-environment-request-duplicate",c());t.push(i),a.push(...i.reasonCodes),d=!0,s=!0;continue}h.add(R);const w=$(r);if(w){const i=m(r,I(r),w,c());t.push(i),a.push(w),d=!0,s=!0;continue}const u=I(r);if(!n){const i=x(r,u,"preserved",["managed-environment-capability-unsupported"],c());t.push(i),a.push(...i.reasonCodes),d=!0;continue}if(r.existingReceipt){if(!k(r.existingReceipt,r)||r.existingReceipt.idempotencyKey!==u){const b=m(r,u,"managed-environment-receipt-binding-mismatch",c());t.push(b),a.push(...b.reasonCodes),d=!0,s=!0;continue}const i=await n.reconcile({request:r,receipt:r.existingReceipt});if(!i.ok||!k(i.receipt,r)||i.receipt.idempotencyKey!==u){const b=i.ok?"managed-environment-receipt-binding-mismatch":i.reasonCode,A=m(r,u,b,c());t.push(A),a.push(b),d=!0,s=!0;continue}const f=K(i.receipt);if(f.failed||!f.pending){t.push(i.receipt),a.push(...i.receipt.reasonCodes),d||=f.pending,s||=f.failed;continue}}const y=await n.inspect(r);if(!y.ok){const i=m(r,u,y.reasonCode,c());t.push(i),a.push(y.reasonCode),d=!0,s=!0;continue}const l=V(r,y.snapshot);if(a.push(...l.reasonCodes),l.action==="preserve"){t.push(x(r,u,"preserved",l.reasonCodes,c())),d||=l.pending;continue}if(l.action==="already_absent"){t.push(x(r,u,"already_absent",l.reasonCodes,c()));continue}const g=await n.apply({request:r,snapshot:y.snapshot,effect:r.effect,idempotencyKey:u});if(!g.ok||!k(g.receipt,r)||g.receipt.idempotencyKey!==u){const i=g.ok?"managed-environment-receipt-binding-mismatch":g.reasonCode,f=m(r,u,i,c());t.push(f),a.push(i),d=!0,s=!0;continue}const p=await n.reconcile({request:r,receipt:g.receipt});if(!p.ok||!k(p.receipt,r)||p.receipt.idempotencyKey!==u){const i=p.ok?"managed-environment-receipt-binding-mismatch":p.reasonCode,f=m(r,u,i,c());t.push(f),a.push(i),d=!0,s=!0;continue}t.push(p.receipt),a.push(...p.receipt.reasonCodes);const _=K(p.receipt);d||=_.pending,s||=_.failed}return{ok:!s&&!d,pending:d,receipts:t,reasonCodes:S(a),publicSafe:!0}}function V(e,n){return N(n)?n.resourceId!==e.resourceId||n.epicId!==e.epicId?o(!1,"managed-environment-identity-mismatch"):n.kind!==e.expectedKind||D[e.effect]!==n.kind?o(!1,"managed-environment-kind-mismatch"):n.managed?n.ownerDigest!==e.expectedOwnerDigest?o(!1,"managed-environment-owner-replaced"):n.revision!==e.expectedRevision?o(!1,"managed-environment-revision-stale"):n.presence==="absent"?{action:"already_absent",pending:!1,reasonCodes:["managed-environment-already-absent"]}:n.presence!=="present"?o(!0,"managed-environment-presence-unknown"):n.capability!=="supported"?o(!0,"managed-environment-capability-unsupported"):n.primary?o(!0,"managed-environment-primary-preserved"):n.protected?o(!0,"managed-environment-protected"):n.active?o(!0,"managed-environment-active"):n.locked?o(!0,"managed-environment-locked"):n.submoduleActive?o(!0,"managed-environment-submodule-active"):n.clean==="unknown"?o(!0,"managed-environment-cleanliness-unknown"):n.clean?n.preservableIgnored?o(!0,"managed-environment-preservable-ignored"):n.integrated?{action:"apply",pending:!1,reasonCodes:[]}:o(!0,"managed-environment-integration-unproven"):o(!0,"managed-environment-dirty"):o(!1,"managed-environment-ownership-unproven"):o(!0,"managed-environment-snapshot-invalid")}function I(e){return`environment-cleanup:v1:${E("sha256").update([e.resourceId,e.effect,e.expectedOwnerDigest,e.expectedRevision].join("\0")).digest("hex")}`}function $(e){return e.schemaVersion!==1||e.publicSafe!==!0||!v(e.resourceId)||!v(e.epicId)||!C(e.expectedOwnerDigest)||!C(e.expectedRevision)||D[e.effect]!==e.expectedKind?"managed-environment-request-invalid":null}function N(e){return e.schemaVersion===1&&e.publicSafe===!0&&v(e.resourceId)&&v(e.epicId)&&C(e.ownerDigest)&&C(e.revision)&&["worktree","process","interface_entry"].includes(e.kind)&&["present","absent","unknown"].includes(e.presence)&&["supported","unsupported"].includes(e.capability)&&(typeof e.clean=="boolean"||e.clean==="unknown")&&[e.managed,e.active,e.integrated,e.protected,e.primary,e.locked,e.submoduleActive,e.preservableIgnored].every(n=>typeof n=="boolean")}function k(e,n){return e.schemaVersion===1&&e.publicSafe===!0&&e.resourceId===n.resourceId&&e.effect===n.effect&&e.expectedOwnerDigest===n.expectedOwnerDigest&&e.expectedRevision===n.expectedRevision&&["applied","already_absent","preserved","failed"].includes(e.outcome)&&v(e.idempotencyKey)&&e.reasonCodes.length<=128&&e.reasonCodes.every(v)&&O(e.checkedAt)&&O(e.recordedAt)}function K(e){return e.outcome==="failed"?{pending:!0,failed:!0}:e.outcome!=="preserved"?{pending:!1,failed:!1}:{pending:!e.reasonCodes.every(c=>["managed-environment-ownership-unproven","managed-environment-owner-replaced","managed-environment-revision-stale","managed-environment-kind-mismatch","managed-environment-identity-mismatch"].includes(c)),failed:!1}}function o(e,n){return{action:"preserve",pending:e,reasonCodes:[n]}}function x(e,n,c,t,a){return{schemaVersion:1,resourceId:e.resourceId,effect:e.effect,outcome:c,expectedOwnerDigest:e.expectedOwnerDigest,expectedRevision:e.expectedRevision,idempotencyKey:n,reasonCodes:S(t),checkedAt:a,recordedAt:a,publicSafe:!0}}function m(e,n,c,t){return x(e,n,"failed",[c],t)}function v(e){return typeof e=="string"&&e.length>0&&e.length<=240&&/^[A-Za-z0-9._:/@#-]+$/.test(e)}function C(e){return typeof e=="string"&&/^[a-f0-9]{64}$/.test(e)}function O(e){return typeof e=="string"&&Number.isFinite(Date.parse(e))}function S(e){return[...new Set(e)]}export{V as classifyManagedEnvironmentSnapshot,M as executeManagedEnvironmentCleanup,I as managedEnvironmentCleanupIdempotencyKey};