@makaio/framework 1.0.0-dev-1783355411417 → 1.0.0-dev-1783439621927

package/dist/hooks/index.d.mts

@@ -1,6 +1,6 @@
 import { ExtractSubjectPayload, SubjectDefinition } from "@makaio/framework/core";
 import { IMakaioBus, InterceptorContext } from "@makaio/framework/bus";
-import { IMakaioSession, JsonValue, MessageInput, SessionContext, SessionMessageBlock, SessionSubjects, StepFinished, StepType, Turn } from "@makaio/framework/contracts";
+import { IMakaioSession, JsonValue, MessageInput, SessionContext, SessionMessageBlock, SessionSubjects, StartMode, StepFinished, StepType, Turn } from "@makaio/framework/contracts";
 import { SessionSendMessageRequest } from "@makaio/framework/contracts/session";
 
 //#region packages/hooks/src/types/hook-name.d.ts
@@ -314,7 +314,24 @@ interface PostStepHookOptions extends BaseHookOptions {
 }
 type PreToolUseHookOptions = BaseHookOptions;
 type PostToolUseHookOptions = BaseHookOptions;
-type SessionStartHookOptions = BaseHookOptions;
+/**
+ * Options for SessionStart hook.
+ *
+ * SessionStart hooks fire on `agent.started` events filtered by
+ * {@link startModes}. The default filter is `['fresh', 'fork']` so that
+ * hooks behave as session-initialisation hooks rather than per-turn hooks.
+ */
+interface SessionStartHookOptions extends BaseHookOptions {
+  /**
+   * Start modes that trigger this hook.
+   *
+   * - `['fresh']` — only brand-new sessions (e.g. content injectors)
+   * - `['fresh', 'fork']` — new sessions and forks (default)
+   * - `START_MODES` — all modes (e.g. provider-lifecycle telemetry)
+   * Defaults to `['fresh', 'fork']`.
+   */
+  startModes?: readonly StartMode[];
+}
 type SessionEndHookOptions = BaseHookOptions;
 //#endregion
 //#region packages/hooks/src/create-hook.d.ts

package/dist/{identity-BarL3JYI.mjs → identity-DC3Pk0ps.mjs}

@@ -1 +1 @@
-import{AdapterRuntimeSubjects as e}from"./services/adapter-runtime/namespace.mjs";import{AdapterSubjects as t}from"@makaio/framework/contracts";const n=[1116352408,1899447441,3049323471,3921009573,961987163,1508970993,2453635748,2870763221,3624381080,310598401,607225278,1426881987,1925078388,2162078206,2614888103,3248222580,3835390401,4022224774,264347078,604807628,770255983,1249150122,1555081692,1996064986,2554220882,2821834349,2952996808,3210313671,3336571891,3584528711,113926993,338241895,666307205,773529912,1294757372,1396182291,1695183700,1986661051,2177026350,2456956037,2730485921,2820302411,3259730800,3345764771,3516065817,3600352804,4094571909,275423344,430227734,506948616,659060556,883997877,958139571,1322822218,1537002063,1747873779,1955562222,2024104815,2227730452,2361852424,2428436474,2756734187,3204031479,3329325298],r=[1779033703,3144134277,1013904242,2773480762,1359893119,2600822924,528734635,1541459225];function i(e,t){return e>>>t|e<<32-t}function a(e){let t=new TextEncoder().encode(e),a=t.length*8,o=t.length+9+63>>6<<6>>>0,s=new Uint8Array(o);s.set(t),s[t.length]=128;let c=new DataView(s.buffer),l=Math.floor(a/4294967296),u=a>>>0;c.setUint32(o-8,l,!1),c.setUint32(o-4,u,!1);let d=[...r],f=new Uint32Array(64);for(let e=0;e<s.length;e+=64){for(let t=0;t<16;t+=1)f[t]=c.getUint32(e+t*4,!1);for(let e=16;e<64;e+=1){let t=i(f[e-15],7)^i(f[e-15],18)^f[e-15]>>>3,n=i(f[e-2],17)^i(f[e-2],19)^f[e-2]>>>10;f[e]=f[e-16]+t+f[e-7]+n>>>0}let[t,r,a,o,s,l,u,p]=d;for(let e=0;e<64;e+=1){let c=i(s,6)^i(s,11)^i(s,25),d=s&l^~s&u,m=p+c+d+n[e]+f[e]>>>0,h=(i(t,2)^i(t,13)^i(t,22))+(t&r^t&a^r&a)>>>0;p=u,u=l,l=s,s=o+m>>>0,o=a,a=r,r=t,t=m+h>>>0}d[0]=d[0]+t>>>0,d[1]=d[1]+r>>>0,d[2]=d[2]+a>>>0,d[3]=d[3]+o>>>0,d[4]=d[4]+s>>>0,d[5]=d[5]+l>>>0,d[6]=d[6]+u>>>0,d[7]=d[7]+p>>>0}return d.map(e=>e.toString(16).padStart(8,`0`)).join(``)}function o(e,t){let n=a(JSON.stringify([e,t]));return[n.slice(0,8),n.slice(8,12),`5${n.slice(13,16)}`,`a${n.slice(17,20)}`,n.slice(20,32)].join(`-`)}function s(e,t){let n=e.machineId??t;if(!n)throw Error(`resolveId requires machineId when no runtime default machine is configured for adapterName="${e.adapterName}"`);return o(n,e.adapterName)}var c=class{currentMachineId;adapterNamesById=new Map;localAdapterIds=new Set;constructor(e){this.currentMachineId=e}replaceKnownAdapterNames(e){for(let e of this.localAdapterIds)this.adapterNamesById.delete(e);if(this.localAdapterIds=new Set,this.currentMachineId)for(let t of e){let e=o(this.currentMachineId,t);this.adapterNamesById.set(e,t),this.localAdapterIds.add(e)}}resolveId(e){let t=s(e,this.currentMachineId);return this.rememberAdapterId(t,e.adapterName),t}rememberAdapterId(e,t){this.adapterNamesById.set(e,t)}resolveAdapterName(e){return this.adapterNamesById.get(e)}async resolveAdapterNameFromKnownNames(e,t){return this.resolveAdapterName(e)||(this.replaceKnownAdapterNames(await t()),this.resolveAdapterName(e))}clear(){this.adapterNamesById.clear(),this.localAdapterIds.clear()}};function l(n,r={}){let i=new c(r.currentMachineId);r.knownAdapterNames&&i.replaceKnownAdapterNames(r.knownAdapterNames);let a=[n.on(t.initialized,e=>{i.rememberAdapterId(e.payload.adapterId,e.payload.adapterName)}),n.on(e.resolveId,e=>{e.setResult({adapterId:i.resolveId(e.payload)})}),n.on(e.resolveName,async e=>{let t=i.resolveAdapterName(e.payload.adapterId)??(r.listKnownAdapterNames?await i.resolveAdapterNameFromKnownNames(e.payload.adapterId,r.listKnownAdapterNames):void 0);if(!t)throw Error(`Adapter not found for adapterId="${e.payload.adapterId}"`);e.setResult({adapterName:t})})];return{registry:i,cleanup:()=>{for(let e of a)e()}}}export{s as i,o as n,l as r,c as t};
+import{AdapterRuntimeSubjects as e}from"./services/adapter-runtime/namespace.mjs";import{AdapterSubjects as t}from"@makaio/framework/contracts";const n=[1116352408,1899447441,3049323471,3921009573,961987163,1508970993,2453635748,2870763221,3624381080,310598401,607225278,1426881987,1925078388,2162078206,2614888103,3248222580,3835390401,4022224774,264347078,604807628,770255983,1249150122,1555081692,1996064986,2554220882,2821834349,2952996808,3210313671,3336571891,3584528711,113926993,338241895,666307205,773529912,1294757372,1396182291,1695183700,1986661051,2177026350,2456956037,2730485921,2820302411,3259730800,3345764771,3516065817,3600352804,4094571909,275423344,430227734,506948616,659060556,883997877,958139571,1322822218,1537002063,1747873779,1955562222,2024104815,2227730452,2361852424,2428436474,2756734187,3204031479,3329325298],r=[1779033703,3144134277,1013904242,2773480762,1359893119,2600822924,528734635,1541459225];function i(e,t){return e>>>t|e<<32-t}function a(e){let t=new TextEncoder().encode(e),a=t.length*8,o=t.length+9+63>>6<<6>>>0,s=new Uint8Array(o);s.set(t),s[t.length]=128;let c=new DataView(s.buffer),l=Math.floor(a/4294967296),u=a>>>0;c.setUint32(o-8,l,!1),c.setUint32(o-4,u,!1);let d=[...r],f=new Uint32Array(64);for(let e=0;e<s.length;e+=64){for(let t=0;t<16;t+=1)f[t]=c.getUint32(e+t*4,!1);for(let e=16;e<64;e+=1){let t=i(f[e-15],7)^i(f[e-15],18)^f[e-15]>>>3,n=i(f[e-2],17)^i(f[e-2],19)^f[e-2]>>>10;f[e]=f[e-16]+t+f[e-7]+n>>>0}let[t,r,a,o,s,l,u,p]=d;for(let e=0;e<64;e+=1){let c=i(s,6)^i(s,11)^i(s,25),d=s&l^~s&u,m=p+c+d+n[e]+f[e]>>>0,h=(i(t,2)^i(t,13)^i(t,22))+(t&r^t&a^r&a)>>>0;p=u,u=l,l=s,s=o+m>>>0,o=a,a=r,r=t,t=m+h>>>0}d[0]=d[0]+t>>>0,d[1]=d[1]+r>>>0,d[2]=d[2]+a>>>0,d[3]=d[3]+o>>>0,d[4]=d[4]+s>>>0,d[5]=d[5]+l>>>0,d[6]=d[6]+u>>>0,d[7]=d[7]+p>>>0}return d.map(e=>e.toString(16).padStart(8,`0`)).join(``)}function o(e,t){let n=a(JSON.stringify([e,t]));return[n.slice(0,8),n.slice(8,12),`5${n.slice(13,16)}`,`a${n.slice(17,20)}`,n.slice(20,32)].join(`-`)}function s(e,t){let n=e.machineId??t;if(!n)throw Error(`resolveId requires machineId when no runtime default machine is configured for adapterName="${e.adapterName}"`);return o(n,e.adapterName)}var c=class{currentMachineId;adapterNamesById=new Map;localAdapterIds=new Set;constructor(e){this.currentMachineId=e}replaceKnownAdapterNames(e){for(let e of this.localAdapterIds)this.adapterNamesById.delete(e);if(this.localAdapterIds=new Set,this.currentMachineId)for(let t of e){let e=o(this.currentMachineId,t);this.adapterNamesById.set(e,t),this.localAdapterIds.add(e)}}resolveId(e){let t=s(e,this.currentMachineId);return this.rememberAdapterId(t,e.adapterName),t}rememberAdapterId(e,t){this.adapterNamesById.set(e,t)}resolveAdapterName(e){return this.adapterNamesById.get(e)}async resolveAdapterNameFromKnownNames(e,t){return this.resolveAdapterName(e)||(this.replaceKnownAdapterNames(await t()),this.resolveAdapterName(e))}clear(){this.adapterNamesById.clear(),this.localAdapterIds.clear()}};function l(n,r={}){let i=new c(r.currentMachineId);r.knownAdapterNames&&i.replaceKnownAdapterNames(r.knownAdapterNames);let a=[n.on(t.initialized,e=>{i.rememberAdapterId(e.payload.adapterId,e.payload.adapterName)}),n.on(e.resolveId,e=>{e.setResult({adapterId:i.resolveId(e.payload)})}),n.on(e.getMachineId,e=>{e.setResult({machineId:r.currentMachineId})}),n.on(e.resolveName,async e=>{let t=i.resolveAdapterName(e.payload.adapterId)??(r.listKnownAdapterNames?await i.resolveAdapterNameFromKnownNames(e.payload.adapterId,r.listKnownAdapterNames):void 0);if(!t)throw Error(`Adapter not found for adapterId="${e.payload.adapterId}"`);e.setResult({adapterName:t})})];return{registry:i,cleanup:()=>{for(let e of a)e()}}}export{s as i,o as n,l as r,c as t};

package/dist/{index-4eP9DRL_.d.mts → index-B3fjN5HX.d.mts}

@@ -27,9 +27,9 @@ type MakaioVariant = z.infer<typeof MakaioVariantSchema>;
  */
 declare const VariantUpgradeStatusSchema: z.ZodEnum<{
   error: "error";
+  progress: "progress";
   complete: "complete";
   downloading: "downloading";
-  progress: "progress";
   applying: "applying";
 }>;
 /** Inferred TypeScript type for an upgrade status value. */
@@ -58,8 +58,8 @@ declare const VariantSchemas: {
       }>;
       bundleCEF: z.ZodBoolean;
       defaultRenderer: z.ZodEnum<{
-        cef: "cef";
         native: "native";
+        cef: "cef";
       }>;
     }, z.core.$strip>;
   };
@@ -101,9 +101,9 @@ declare const VariantSchemas: {
   upgradeProgress: z.ZodObject<{
     status: z.ZodEnum<{
       error: "error";
+      progress: "progress";
       complete: "complete";
       downloading: "downloading";
-      progress: "progress";
       applying: "applying";
     }>;
     percent: z.ZodOptional<z.ZodNumber>;
@@ -134,8 +134,8 @@ declare const VariantNamespace: _$_makaio_core0.BusNamespaceDefinition<"host:var
       }>;
       bundleCEF: _$zod.ZodBoolean;
       defaultRenderer: _$zod.ZodEnum<{
-        cef: "cef";
         native: "native";
+        cef: "cef";
       }>;
     }, _$zod_v4_core0.$strip>;
   };
@@ -158,9 +158,9 @@ declare const VariantNamespace: _$_makaio_core0.BusNamespaceDefinition<"host:var
   upgradeProgress: _$zod.ZodObject<{
     status: _$zod.ZodEnum<{
       error: "error";
+      progress: "progress";
       complete: "complete";
       downloading: "downloading";
-      progress: "progress";
       applying: "applying";
     }>;
     percent: _$zod.ZodOptional<_$zod.ZodNumber>;
@@ -181,8 +181,8 @@ declare const VariantSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatS
       }>;
       bundleCEF: _$zod.ZodBoolean;
       defaultRenderer: _$zod.ZodEnum<{
-        cef: "cef";
         native: "native";
+        cef: "cef";
       }>;
     }, _$zod_v4_core0.$strip>;
   };
@@ -205,9 +205,9 @@ declare const VariantSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatS
   upgradeProgress: _$zod.ZodObject<{
     status: _$zod.ZodEnum<{
       error: "error";
+      progress: "progress";
       complete: "complete";
       downloading: "downloading";
-      progress: "progress";
       applying: "applying";
     }>;
     percent: _$zod.ZodOptional<_$zod.ZodNumber>;

package/dist/{index-3X0368CL.d.mts → index-B5Uczo3R.d.mts}

@@ -18,11 +18,11 @@ import { ExtensionWarningEntry, ExtensionWarningEntrySchema } from "@makaio/fram
  * detail, not an externally observable state.
  */
 declare const ComponentStateSchema: z.ZodEnum<{
+  stopped: "stopped";
   failed: "failed";
   discovered: "discovered";
-  stopped: "stopped";
-  active: "active";
   skipped: "skipped";
+  active: "active";
   initializing: "initializing";
 }>;
 /** Inferred union of all valid component lifecycle states. */
@@ -47,11 +47,11 @@ declare const ComponentInfoSchema: z.ZodObject<{
   name: z.ZodString;
   displayName: z.ZodString;
   state: z.ZodEnum<{
+    stopped: "stopped";
     failed: "failed";
     discovered: "discovered";
-    stopped: "stopped";
-    active: "active";
     skipped: "skipped";
+    active: "active";
     initializing: "initializing";
   }>;
   error: z.ZodOptional<z.ZodString>;
@@ -68,11 +68,11 @@ declare const ServiceInfoSchema: z.ZodObject<{
   name: z.ZodString;
   displayName: z.ZodString;
   state: z.ZodEnum<{
+    stopped: "stopped";
     failed: "failed";
     discovered: "discovered";
-    stopped: "stopped";
-    active: "active";
     skipped: "skipped";
+    active: "active";
     initializing: "initializing";
   }>;
   error: z.ZodOptional<z.ZodString>;
@@ -90,11 +90,11 @@ declare const ExtensionInfoSchema: z.ZodObject<{
   name: z.ZodString;
   displayName: z.ZodString;
   state: z.ZodEnum<{
+    stopped: "stopped";
     failed: "failed";
     discovered: "discovered";
-    stopped: "stopped";
-    active: "active";
     skipped: "skipped";
+    active: "active";
     initializing: "initializing";
   }>;
   error: z.ZodOptional<z.ZodString>;
@@ -138,19 +138,19 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
     name: z.ZodString;
     displayName: z.ZodString;
     from: z.ZodEnum<{
+      stopped: "stopped";
       failed: "failed";
       discovered: "discovered";
-      stopped: "stopped";
-      active: "active";
       skipped: "skipped";
+      active: "active";
       initializing: "initializing";
     }>;
     to: z.ZodEnum<{
+      stopped: "stopped";
       failed: "failed";
       discovered: "discovered";
-      stopped: "stopped";
-      active: "active";
       skipped: "skipped";
+      active: "active";
       initializing: "initializing";
     }>;
     error: z.ZodOptional<z.ZodString>;
@@ -181,11 +181,11 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
         name: z.ZodString;
         displayName: z.ZodString;
         state: z.ZodEnum<{
+          stopped: "stopped";
           failed: "failed";
           discovered: "discovered";
-          stopped: "stopped";
-          active: "active";
           skipped: "skipped";
+          active: "active";
           initializing: "initializing";
         }>;
         error: z.ZodOptional<z.ZodString>;
@@ -219,11 +219,11 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
         name: z.ZodString;
         displayName: z.ZodString;
         state: z.ZodEnum<{
+          stopped: "stopped";
           failed: "failed";
           discovered: "discovered";
-          stopped: "stopped";
-          active: "active";
           skipped: "skipped";
+          active: "active";
           initializing: "initializing";
         }>;
         error: z.ZodOptional<z.ZodString>;
@@ -593,19 +593,19 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
     name: z.ZodString;
     displayName: z.ZodString;
     from: z.ZodEnum<{
+      stopped: "stopped";
       failed: "failed";
       discovered: "discovered";
-      stopped: "stopped";
-      active: "active";
       skipped: "skipped";
+      active: "active";
       initializing: "initializing";
     }>;
     to: z.ZodEnum<{
+      stopped: "stopped";
       failed: "failed";
       discovered: "discovered";
-      stopped: "stopped";
-      active: "active";
       skipped: "skipped";
+      active: "active";
       initializing: "initializing";
     }>;
     error: z.ZodOptional<z.ZodString>;
@@ -636,11 +636,11 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
         name: z.ZodString;
         displayName: z.ZodString;
         state: z.ZodEnum<{
+          stopped: "stopped";
           failed: "failed";
           discovered: "discovered";
-          stopped: "stopped";
-          active: "active";
           skipped: "skipped";
+          active: "active";
           initializing: "initializing";
         }>;
         error: z.ZodOptional<z.ZodString>;
@@ -674,11 +674,11 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
         name: z.ZodString;
         displayName: z.ZodString;
         state: z.ZodEnum<{
+          stopped: "stopped";
           failed: "failed";
           discovered: "discovered";
-          stopped: "stopped";
-          active: "active";
           skipped: "skipped";
+          active: "active";
           initializing: "initializing";
         }>;
         error: z.ZodOptional<z.ZodString>;

package/dist/{index-C6Ys8pxt.d.mts → index-BIZeIA5k.d.mts}

@@ -1,12 +1,12 @@
-import { J as ArtifactLifecycleHookEvent, Y as ArtifactLifecycleHookRegistration$1, z as AnyArtifactKindDefinition } from "./index-DV4nRk0h.mjs";
+import { J as ArtifactLifecycleHookEvent, Y as ArtifactLifecycleHookRegistration$1, z as AnyArtifactKindDefinition } from "./index-DS6kxiFl.mjs";
 import { A as VersionRange, O as VersionLiteral$1, r as ClientDefinition$1 } from "./definition-CuJvtYeG.mjs";
 import { c as ProviderDefinitionInput$1, r as ProtocolId$1 } from "./definition-Cllhr9mi.mjs";
 import { t as RequiredTimeoutConfig } from "./index-CuHqL95P.mjs";
-import { F as SessionMessage$1, b as SESSION_EVENT_TYPES, i as MakaioSessionEvent$1 } from "./types-C76EP81O.mjs";
-import { D as EntityUIConfig, I as FormFieldProps } from "./index-CaerrEDH.mjs";
-import { n as ExtensionTransitionRulesContribution, t as ExtensionTransitionActionsContribution, y as WorkflowBlockCollection$1 } from "./transition-Dq41YCkc.mjs";
-import { l as FacetNamespaceDefinition } from "./index-O08Q2ikz.mjs";
-import { t as SurfaceBindingDefinition } from "./definition-b9jyJqPD.mjs";
+import { V as SessionMessage$1, b as SESSION_EVENT_TYPES, i as MakaioSessionEvent$1 } from "./types-9XCB1aPK.mjs";
+import { D as EntityUIConfig, I as FormFieldProps } from "./index-NkNbYFud.mjs";
+import { n as ExtensionTransitionRulesContribution, t as ExtensionTransitionActionsContribution, y as WorkflowBlockCollection$1 } from "./transition-DYorNHZu.mjs";
+import { l as FacetNamespaceDefinition } from "./index-DTBQOCar.mjs";
+import { t as SurfaceBindingDefinition } from "./definition-DpkfJi8v.mjs";
 import { z } from "zod";
 import { MakaioBusLike, PayloadFilter, RegistrableBusNamespaceDefinition, SubjectSchema } from "@makaio/framework/core";
 import * as _$_makaio_contracts0 from "@makaio/framework/contracts";

package/dist/{index-BYfSAJRC.d.mts → index-BvTd61i5.d.mts}

@@ -87,6 +87,8 @@ declare class Turn$1 {
   private readonly _agentIds;
   /** Messages sent during this turn */
   private readonly _messageIds;
+  /** Message IDs currently claiming this turn while their storage append is in-flight. */
+  private readonly _pendingMessageAppends;
   /** Agents that have completed successfully */
   private readonly _completedAgents;
   /** Agents that errored (agentId → error message) */
@@ -108,6 +110,11 @@ declare class Turn$1 {
    * @returns Immutable array of message IDs
    */
   get messageIds(): readonly string[];
+  /**
+   * Whether a user message has claimed this turn before its storage append completes.
+   * @returns True when at least one message append is in-flight
+   */
+  get hasPendingMessageAppends(): boolean;
   /**
    * Agents that have completed successfully.
    * @returns Read-only set of completed agent IDs
@@ -123,6 +130,16 @@ declare class Turn$1 {
    * @param messageId - The message ID to add
    */
   addMessage(messageId: string): void;
+  /**
+   * Claim this turn for a message whose durable append has started.
+   * @param messageId - Message ID whose append is in-flight
+   */
+  claimMessageAppend(messageId: string): void;
+  /**
+   * Release a failed message append claim without adding the message.
+   * @param messageId - Message ID whose append failed
+   */
+  releaseMessageAppend(messageId: string): void;
   /**
    * Mark an agent as completed successfully.
    * @param agentId - The agent that completed
@@ -165,6 +182,12 @@ declare class Turn$1 {
    * @returns Turn context with turnId and the specified messageId
    */
   getContextForMessage(messageId: string): TurnContext;
+  /**
+   * Return the recorded terminal outcome for an agent, if any.
+   * @param agentId - Agent ID to inspect.
+   * @returns Terminal outcome already recorded for the agent.
+   */
+  private getAgentTerminalOutcome;
   /**
    * Check if turn should complete and return appropriate state change.
    * @returns State change indicating completion status and result if complete
@@ -216,10 +239,14 @@ declare class SessionTurnManager {
   private readonly bus;
   /** Active turns keyed by sessionId (one turn per session). */
   private readonly activeTurns;
-  /** Per-session usage accumulators, parallel to activeTurns. */
+  /** Per-turn usage accumulators, keyed by turnId. */
   private readonly usageAccumulators;
-  /** Sessions currently persisting turn completion (prevents concurrent writes). */
-  private readonly completingSessions;
+  /** Turns currently persisting completion (prevents concurrent writes). */
+  private readonly completingTurnIds;
+  /** Completing turns retained for usage correlation after active routing is cleared. */
+  private readonly completingTurns;
+  /** Pending terminal completions keyed by turnId; value records whether turn storage handled the transition. */
+  private readonly pendingTerminalCompletions;
   /** Usage events received while completion persistence is in-flight. */
   private readonly bufferedUsageDuringCompletion;
   /**
@@ -265,12 +292,25 @@ declare class SessionTurnManager {
   /**
    * Discard active in-memory state for a turn that failed before routing began.
    *
-   * The storage contract has no turn-delete operation, so this only rolls back
-   * the active manager state that would otherwise make the next user message
-   * reuse a turn whose first message was never persisted.
+   * Use when no durable turn row needs a terminal status transition.
    * @param turn - Newly created active turn to discard
    */
   discardActiveTurn(turn: Turn$1): void;
+  /**
+   * Mark an unclaimed newly created turn as failed and discard its active in-memory state.
+   *
+   * This preserves the durable turn lifecycle invariant when setup fails after
+   * `storage:turn.create` has already assigned a turn number.
+   * @param turn - Newly created active turn whose setup failed before any message claimed it
+   * @param error - Durable error code to store on the terminal turn
+   */
+  failActiveTurnSetup(turn: Turn$1, error: string): Promise<void>;
+  /**
+   * Remove a turn from the active routing index when it is no longer routable.
+   * @param turn - Turn to remove when it still owns the session slot
+   * @returns Whether the turn owned and cleared the active routing slot
+   */
+  private clearActiveRoutingTurn;
   /**
    * Register bus listeners for `agent.usage` and `agent.complete` events.
    *
@@ -301,6 +341,12 @@ declare class SessionTurnManager {
    * @param result - Turn result (success status and error messages)
    */
   completeTurn(turn: Turn$1, result: TurnCompletionResult): Promise<void>;
+  /**
+   * Clear in-memory state retained only while a turn completion is in progress.
+   * @param turn - Turn whose completion state should be removed
+   * @param usageAccumulator - Optional accumulator retained for late usage merges
+   */
+  private clearCompletionState;
   /**
    * Get the active turn for a session, if any.
    * @param sessionId - Session identifier
@@ -340,14 +386,58 @@ declare class SessionTurnManager {
    * @param success - Whether the agent completed successfully
    * @param error - Error message if the agent failed
    * @param onTurnComplete - Callback to invoke when the turn is complete
+   * @param completionTurnId - Turn identifier supplied by the adapter completion event
    */
   private handleAgentCompletion;
   /**
    * Buffer a usage event that arrived while turn completion persistence is in-flight.
-   * @param sessionId - Session whose turn is currently completing
+   * @param turnId - Turn whose completion is currently being persisted
    * @param usageEvent - Usage event to defer until after persistence
    */
   private bufferUsageDuringCompletion;
+  /**
+   * Find a turn that may still accept usage by turnId.
+   * @param turnId - Turn identifier from an agent usage event
+   * @returns Active or completing turn, if usage can still be recorded
+   */
+  private findTurnForUsage;
+  /**
+   * Find a turn that may still accept agent completion by turnId.
+   * @param turnId - Turn identifier from an agent completion event
+   * @returns Active or completing turn, if completion can still be correlated
+   */
+  private findTurnForCompletion;
+  /**
+   * Find the active turn for a legacy completion event without turnId.
+   * @param agentId - Agent ID from the completion event.
+   * @returns Active turn to mutate, or undefined when the event is ambiguous.
+   */
+  private findTurnForUncorrelatedCompletion;
+  /**
+   * Check whether a terminal outcome has already been recorded for an agent.
+   * @param turn - Turn being completed.
+   * @param agentId - Agent ID from the terminal event.
+   * @returns Whether the agent already has a terminal outcome on the turn.
+   */
+  private hasTerminalOutcome;
+  /**
+   * Persist a turn's terminal status and optional usage snapshot.
+   * @param turn - Turn being completed
+   * @param result - Completion result to persist
+   * @param usage - Usage snapshot to include, when available
+   * @param expectedStatus - Optional status guard for the first terminal transition
+   * @returns Whether turn storage handled the request and terminalized the turn
+   */
+  private persistTurnCompletion;
+  /**
+   * Merge buffered usage and persist the updated snapshot.
+   * @param turn - Turn whose buffered usage should be merged
+   * @param result - Completion result for the turn
+   * @param usageAccumulator - Usage accumulator captured by the completing turn
+   * @param currentUsage - Current completed usage snapshot
+   * @returns Updated usage snapshot
+   */
+  private flushBufferedUsageDuringCompletion;
   /**
    * Subscribe to `storage:message.stored` and count stored assistant messages
    * per turnId, resolving any pending barrier waiter on each increment.
@@ -423,9 +513,10 @@ declare function registerCompressHandler(bus: IMakaioBus): () => void;
  * Creates a new session with parent reference. The forked session starts
  * empty - its full conversation is assembled by traversing the parent chain.
  * @param bus - Bus instance for communication
+ * @param machineId - Stable runtime machine identity to stamp on child sessions
  * @returns Cleanup function to unsubscribe
  */
-declare function registerForkHandler(bus: IMakaioBus): () => void;
+declare function registerForkHandler(bus: IMakaioBus, machineId?: string): () => void;
 //#endregion
 //#region services/core/src/session/handlers/merge-handler.d.ts
 /**
@@ -449,6 +540,50 @@ interface CwdSwapMeta {
   previousCwd: string;
   newCwd: string;
 }
+/**
+ * Options for routing a message to target agents.
+ */
+interface RouteToAgentsOptions {
+  /** Bus instance for communication. */
+  readonly bus: IMakaioBus;
+  /** Session metadata (for fork detection). */
+  readonly session: IMakaioSession;
+  /** Target agents to route to. */
+  readonly agents: MakaioSessionAgent[];
+  /** Message content to send. */
+  readonly message: MessageInput;
+  /** Message identifier. */
+  readonly messageId: string;
+  /** Turn tracking object. */
+  readonly turn: Turn$1;
+  /** How to deliver the message. */
+  readonly deliveryMode: 'enqueue' | 'immediate' | undefined;
+  /** Callback when turn completes (all agents done). */
+  readonly onTurnComplete: (turn: Turn$1, result: {
+    success: boolean;
+    errors: string[];
+  }) => Promise<void>;
+  /** Session context with curated messageHistory and decision signals. */
+  readonly sessionContext?: SessionContext;
+  /** Optional enricher for immediate message context. */
+  readonly turnContextEnricher?: ITurnContextEnricher;
+  /** Whether this is the first message in a new turn. */
+  readonly isNewTurn?: boolean;
+  /** Context enriched with messageHistory for agents that were just recovered. */
+  readonly recoveryContext?: SessionContext;
+  /** Set of agent IDs that were recovered in this handler invocation. */
+  readonly recoveredAgentIds?: ReadonlySet<string>;
+  /** Set of agent IDs that swapped connector due to cwd mismatch. */
+  readonly swappedAgentIds?: ReadonlySet<string>;
+  /** Previous/new cwd metadata keyed by agent ID. */
+  readonly swappedAgentCwd?: ReadonlyMap<string, CwdSwapMeta>;
+  /** Curated history for agents forced into fresh mode. */
+  readonly freshMessageHistory?: Message[];
+  /** Optional structured output descriptor for the turn. */
+  readonly responseSchema?: ResponseSchemaDescriptor;
+  /** Stable machine identity of the current host process for locality evaluation. */
+  readonly localMachineId?: string;
+}
 /**
  * Route a message to target agents via agent.sendMessage.
  *
@@ -456,28 +591,9 @@ interface CwdSwapMeta {
  * and checks for turn completion.
  *
  * For fork sessions on their first turn, assembles projected context from parent chain.
- * @param bus - Bus instance for communication
- * @param session - Session metadata (for fork detection)
- * @param agents - Target agents to route to
- * @param message - Message content to send
- * @param messageId - Message identifier
- * @param turn - Turn tracking object
- * @param deliveryMode - How to deliver the message
- * @param onTurnComplete - Callback when turn completes (all agents done)
- * @param sessionContext - Session context with curated messageHistory and decision signals
- * @param turnContextEnricher - Optional enricher for immediate message context
- * @param isNewTurn - Whether this is the first message in a new turn
- * @param recoveryContext - Context enriched with messageHistory for agents that were just recovered
- * @param recoveredAgentIds - Set of agent IDs that were recovered in this handler invocation
- * @param swappedAgentIds - Set of agent IDs that swapped connector due to cwd mismatch
- * @param swappedAgentCwd - Previous/new cwd metadata keyed by agent ID
- * @param freshMessageHistory - Curated history for agents forced into fresh mode
- * @param responseSchema - Optional structured output descriptor for the turn
+ * @param options - Routing options including bus, session, agents, message, and lifecycle dependencies
  */
-declare function routeToAgents(bus: IMakaioBus, session: IMakaioSession, agents: MakaioSessionAgent[], message: MessageInput, messageId: string, turn: Turn$1, deliveryMode: 'enqueue' | 'immediate' | undefined, onTurnComplete: (turn: Turn$1, result: {
-  success: boolean;
-  errors: string[];
-}) => Promise<void>, sessionContext?: SessionContext, turnContextEnricher?: ITurnContextEnricher, isNewTurn?: boolean, recoveryContext?: SessionContext, recoveredAgentIds?: ReadonlySet<string>, swappedAgentIds?: ReadonlySet<string>, swappedAgentCwd?: ReadonlyMap<string, CwdSwapMeta>, freshMessageHistory?: Message[], responseSchema?: ResponseSchemaDescriptor): Promise<void>;
+declare function routeToAgents(options: RouteToAgentsOptions): Promise<void>;
 //#endregion
 //#region services/core/src/session/handlers/route-to-agents-core.d.ts
 /**
@@ -486,6 +602,12 @@ declare function routeToAgents(bus: IMakaioBus, session: IMakaioSession, agents:
  * Fans out to all agents in parallel. On routing failure, marks the agent
  * as errored and checks for turn completion. On `HookAbortError`, marks
  * the agent as completed with `cancelled` outcome.
+ *
+ * Contract: `sessionContext` must not carry a `nativeFork` directive. This
+ * function dispatches exclusively via `agent.sendMessage`, which never
+ * consumes the directive — fork directives are consumed only on the
+ * `startAgent` path. Callers assembling fork contexts must degrade them to
+ * fresh-with-history first (see `routeToAgents`).
  * @param bus - Bus instance for communication
  * @param session - Session metadata (for session ID)
  * @param agents - Target agents to route to