fix(build,test): snapshot the process hit synchronously before state bindings

Generated stateful scopes incremented processLifetime.hits, awaited state
bindings, then snapshotted the value, so concurrent requests could observe the
same count; the harness's in-memory server claimed its hit only after the
bindings resolved. Both now claim and snapshot in one synchronous step before
any await: the emitted scopes bind `processHit` at the increment, and the
harness claims through claimProcessHit before requestBindings. The harness also
looks up CLI command paths among authored commands only, since projected MCP
commands carry their tool's route id and render through the tool branch.

Author: ScriptedAlchemy

packages/agent-bundle/src/build/entry-shell.ts

@@ -293,7 +293,7 @@ export const generatedCliBinEntrySource = (options: GeneratedCliBinEntryOptions)
     "  if (route === undefined || typeof route.module.default !== 'function') throw new TypeError('Generated CLI route must default-export an async function.');",
     '  const parsed = parseInput(route, input);',
     '  const cwd = process.cwd();',
-    '  processLifetime.hits += 1;',
+    ...processHitSource('  '),
     ...(options.state === undefined
       ? []
       : ['  const bindings = await runtimeState.requestBindings({ signal: context.signal });', '  try {']),
@@ -412,7 +412,7 @@ export const generatedRenderedRouteWorkerSource = (
     "  if (route === undefined || typeof route.module.default !== 'function') throw new TypeError('Generated rendered route must default-export an async function component.');",
     '  const controller = new AbortController();',
     '  requests.set(message.id, controller);',
-    '  processLifetime.hits += 1;',
+    ...processHitSource('  '),
     '  try {',
     '    const cwd = process.cwd();',
     ...(options.state === undefined
@@ -583,8 +583,18 @@ const providerRegistrySource = (providers: readonly CompiledProvider[]): readonl
     ? []
     : ['const providers = Object.freeze([', ...providerRecords(providers), ']);'];
 
-const processLifetimeValueSource =
-  '{ hits: processLifetime.hits, instanceId: processLifetime.instanceId, pid: processLifetime.pid }';
+/**
+ * Claims this request's hit on the process identity and snapshots it in the
+ * same synchronous step, before any state binding or provider `await`, so a
+ * concurrent request on the same scope cannot move the value this request
+ * mounts as `providers.processLifetime`.
+ */
+const processHitSource = (indent: string): readonly string[] => [
+  `${indent}processLifetime.hits += 1;`,
+  `${indent}const processHit = { hits: processLifetime.hits, instanceId: processLifetime.instanceId, pid: processLifetime.pid };`,
+];
+
+const processLifetimeValueSource = 'processHit';
 
 /**
  * Per-request provider execution shared by every generated request scope
@@ -661,7 +671,7 @@ export const generatedRouteFlightWorkerSource = (options: GeneratedRouteFlightWo
     "  if (route === undefined || typeof route.module.default !== 'function') throw new TypeError('Generated route must default-export an async Server Component.');",
     '  const controller = new AbortController();',
     '  requests.set(message.id, controller);',
-    '  processLifetime.hits += 1;',
+    ...processHitSource('  '),
     '  try {',
     ...(options.state === undefined
       ? []

packages/agent-bundle/src/routes/provider-execution.ts

@@ -41,9 +41,15 @@ export const createProviderProcessLifetime = (): ProviderProcessLifetime => ({
 });
 
 /** The immutable snapshot of one process lifetime a request observes. */
+export interface ProviderProcessLifetimeValue {
+  readonly hits: number;
+  readonly instanceId: string;
+  readonly pid: number;
+}
+
 export const providerProcessLifetimeValue = (
   lifetime: ProviderProcessLifetime,
-): { readonly hits: number; readonly instanceId: string; readonly pid: number } => ({
+): ProviderProcessLifetimeValue => ({
   hits: lifetime.hits,
   instanceId: lifetime.instanceId,
   pid: lifetime.pid,

packages/agent-bundle/src/test/cli.ts

@@ -25,7 +25,7 @@ import { createProviderProcessLifetime } from '../routes/provider-execution.ts';
 import type { CompiledCliCommand } from '../routes/types.ts';
 import { AgentTestError, captured } from './errors.ts';
 import { CLI_DISPATCH_PROOF_LEVEL, type AgentBundleTestManifest } from './manifest.ts';
-import { mountProviders } from './providers.ts';
+import { claimProcessHit, mountProviders } from './providers.ts';
 import { registeredRouteLoader, testManifest } from './registry.ts';
 import { prepareCliRenderHost, type HarnessOptionsArguments, type RenderRouteContextInit } from './render.ts';
 import type { AgentRouteModule, RenderedRouteProvenance } from './types.ts';
@@ -239,7 +239,7 @@ export const invokeCli = async (
           explicit: context.providers,
           invocation: { kind: 'cli', props: { args: execution.args, command: commandPath(command) } },
           manifest,
-          processLifetime,
+          processHit: claimProcessHit(processLifetime),
           provenance: { ...provenance, kind: 'cli', routeId: command.routeId, source: 'manifest', targets: [] },
           signal: execution.signal,
         });

packages/agent-bundle/src/test/mcp.ts

@@ -25,7 +25,7 @@ import type { createGeneratedRuntimeState } from '@agent-bundle/runtime/mount';
 import { createProviderProcessLifetime } from '../routes/provider-execution.ts';
 import { AgentTestError, captured } from './errors.ts';
 import { MCP_IN_MEMORY_PROOF_LEVEL, type AgentBundleTestManifest } from './manifest.ts';
-import { mountProviders } from './providers.ts';
+import { claimProcessHit, mountProviders } from './providers.ts';
 import { registeredRouteLoader, testManifest } from './registry.ts';
 import type { HarnessOptionsArguments, RenderRouteContextInit } from './render.ts';
 import type { RenderedRouteProvenance, TestableRouteDescriptor } from './types.ts';
@@ -333,6 +333,10 @@ export const openInMemoryMcpServer = async <
             details: [`registered:   ${Object.keys(routes).sort().join(', ')}`],
           });
         }
+        // The hit is claimed before state bindings are awaited, in the
+        // generated worker's order, so a failed or slow binding still consumes
+        // this request's hit and concurrent requests keep arrival order.
+        const processHit = claimProcessHit(processLifetime);
         const bindings = await runtimeState?.requestBindings({ signal: request.signal });
         try {
           // Conventional providers run before the scope opens, over the same
@@ -342,7 +346,7 @@ export const openInMemoryMcpServer = async <
             explicit: context.providers,
             invocation: request.invocation,
             manifest,
-            processLifetime,
+            processHit,
             ...(descriptor === undefined ? {} : { provenance: routeProvenance(descriptor, manifest) }),
             signal: request.signal,
           });

packages/agent-bundle/src/test/providers.ts

@@ -5,6 +5,7 @@ import {
   providerProcessLifetimeValue,
   type ExecutableProvider,
   type ProviderProcessLifetime,
+  type ProviderProcessLifetimeValue,
 } from '../routes/provider-execution.ts';
 import { AgentTestError } from './errors.ts';
 import type { AgentBundleTestManifest, TestableProviderDescriptor } from './manifest.ts';
@@ -31,15 +32,10 @@ export interface MountProvidersOptions {
   /** Absent for a module rendered directly: no project, so nothing to discover. */
   readonly manifest: AgentBundleTestManifest | undefined;
   /**
-   * The process identity of the simulated executable, scoped exactly as the
-   * artifact scopes its module-level `processLifetime`: one per CLI
-   * invocation (each generated executable starts at hit 1), one per rendered
-   * route request, and one per open in-memory MCP server session (shared by
-   * every request that session handles). Never shared across unrelated
-   * helper calls, so a provider branching on `hits` or `instanceId` cannot
-   * observe warmth the artifact would not exhibit.
+   * This request's claimed hit on the simulated executable's process identity
+   * (see {@link claimProcessHit}); mounted verbatim as `providers.processLifetime`.
    */
-  readonly processLifetime: ProviderProcessLifetime;
+  readonly processHit: ProviderProcessLifetimeValue;
   readonly provenance?: RenderedRouteProvenance;
   readonly signal: AbortSignal;
 }
@@ -63,29 +59,41 @@ const loadProvider = async (
   return { key: descriptor.key, module: await loader(), source: descriptor.relativePath };
 };
 
+/**
+ * Claims one request's hit on a simulated executable's process identity and
+ * snapshots it in the same synchronous step, exactly where the generated
+ * scopes do: before any state binding or provider module `await`, so a
+ * concurrent request on the same identity cannot move this request's value.
+ *
+ * Callers scope the identity as the artifact scopes its module-level
+ * `processLifetime`: one per CLI invocation (each generated executable starts
+ * at hit 1), one per rendered route request, and one per open in-memory MCP
+ * server session (shared by every request that session handles). It is never
+ * shared across unrelated helper calls, so a provider branching on `hits` or
+ * `instanceId` cannot observe warmth the artifact would not exhibit.
+ */
+export const claimProcessHit = (processLifetime: ProviderProcessLifetime): ProviderProcessLifetimeValue => {
+  processLifetime.hits += 1;
+  return providerProcessLifetimeValue(processLifetime);
+};
+
 /**
  * The `providers` value for one harness request scope: the explicit map when
  * the test supplied one, otherwise the project's conventional providers
- * executed in the generated order over the caller's process identity.
+ * executed in the generated order over the claimed process hit.
  */
 export const mountProviders = async (options: MountProvidersOptions): Promise<AgentProviderValues> => {
   if (options.explicit !== undefined) return options.explicit;
-  const { processLifetime } = options;
-  processLifetime.hits += 1;
-  // Snapshot before the first await, as the generated worker does right after
-  // its increment: a concurrent request on the same lifetime must not move
-  // this request's hit count while its provider modules load.
-  const snapshot = providerProcessLifetimeValue(processLifetime);
   if (options.manifest === undefined) {
-    return { processLifetime: snapshot };
+    return { processLifetime: options.processHit };
   }
   const providers: ExecutableProvider[] = [];
   for (const descriptor of options.manifest.providers ?? []) {
     providers.push(await loadProvider(options.manifest, descriptor, options.provenance));
   }
   return executeProviders({
     invocation: options.invocation,
-    processLifetime: { ...snapshot },
+    processLifetime: { ...options.processHit },
     providers,
     signal: options.signal,
   });

packages/agent-bundle/src/test/render.ts

@@ -30,7 +30,7 @@ import { createProviderProcessLifetime, type ProviderProcessLifetime } from '../
 import type { CompiledCliCommand } from '../routes/types.ts';
 import { AgentTestError, captured } from './errors.ts';
 import { ROUTE_UNIT_PROOF_LEVEL, type AgentBundleTestManifest } from './manifest.ts';
-import { mountProviders } from './providers.ts';
+import { claimProcessHit, mountProviders } from './providers.ts';
 import {
   registeredManifestIdentity,
   registeredRouteLoader,
@@ -238,7 +238,12 @@ const executableSurface = (
     case 'event-route':
       return routeId.startsWith('event:') ? routeId.slice('event:'.length) : routeId;
     case 'cli': {
-      const command = manifest?.cliCommands.find((candidate) => candidate.routeId === routeId);
+      // Only authored `src/cli/**` commands have a `cli` route kind. Projected
+      // MCP commands (`command.mcp`) carry their tool's route id, so a request
+      // for one resolves as that `tool` route above, exactly like the generated
+      // entry's `command.mcp !== undefined` branch.
+      const command = manifest?.cliCommands.find((candidate) =>
+        candidate.mcp === undefined && candidate.routeId === routeId);
       if (command !== undefined) return command.path.join(' ');
       return (routeId.startsWith('cli:') ? routeId.slice('cli:'.length) : routeId).replaceAll('/', ' ');
     }
@@ -717,7 +722,7 @@ export const prepareCliRenderHost = async (
             explicit: context.providers,
             invocation,
             manifest: options.manifest,
-            processLifetime: options.processLifetime,
+            processHit: claimProcessHit(options.processLifetime),
             provenance: { ...options.provenance, routeId: command.routeId },
             signal: request.signal,
           });
@@ -813,7 +818,7 @@ const prepareRender = async (
         explicit: context.providers,
         invocation: request.invocation,
         manifest: resolved.manifest,
-        processLifetime,
+        processHit: claimProcessHit(processLifetime),
         provenance: resolved.provenance,
         signal: request.signal,
       }),

packages/agent-bundle/tests/entry-shell.test.ts

@@ -364,7 +364,7 @@ it('generates the warm react-server Flight worker separately from the MCP dispat
     '"hook:event-route:tool-after": Object.freeze({ event: "tool/after", id: "event:tool/after", kind: \'event-route\'',
   );
   expect(createHash('sha256').update(source).digest('hex')).toBe(
-    'f0a574cc26aa4c7d5556e7468d13743c1da55d372fe5e6eae9151df0be873948',
+    '36f042498df1933c6321bd21e4585599a0d39e5ddb3890657bd660c322f4cc23',
   );
   expect(generate({
     artifactEpoch: 'route-fixture@1.2.3',
@@ -518,6 +518,12 @@ it('mounts deterministic per-request providers for plain routed CLI commands (#3
   expect(withProviders.indexOf('for (const provider of providers)')).toBeLessThan(
     withProviders.indexOf('const result = await runAgentRequest({'),
   );
+  // The request's hit is claimed and snapshotted in one synchronous step
+  // before any await, so concurrent requests cannot move each other's value.
+  expect(withProviders).toContain(
+    'processLifetime.hits += 1;\n  const processHit = { hits: processLifetime.hits, instanceId: processLifetime.instanceId, pid: processLifetime.pid };',
+  );
+  expect(withProviders).toContain('const providerValues = { processLifetime: processHit };');
 
   // A project without providers still mounts only the framework-owned process identity.
   const withoutProviders = entryShellModule.generatedCliBinEntrySource({
@@ -526,9 +532,7 @@ it('mounts deterministic per-request providers for plain routed CLI commands (#3
     routes: [route],
   });
   expect(withoutProviders).not.toContain('const providers = Object.freeze([');
-  expect(withoutProviders).toContain(
-    'providers: { processLifetime: { hits: processLifetime.hits, instanceId: processLifetime.instanceId, pid: processLifetime.pid } },',
-  );
+  expect(withoutProviders).toContain('providers: { processLifetime: processHit },');
   expect(withoutProviders).not.toContain('import * as provider0');
 });
 

packages/agent-bundle/tests/projection/providers.test.ts

@@ -1,4 +1,8 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+
 import { describe, expect, it } from '@rstest/core';
+import { createMemoryStateDriver, defineState, type AgentStateDriver } from '@agent-bundle/runtime/state';
+import { z } from 'zod';
 
 import { cliJson, invokeCli } from '../../src/test/cli.ts';
 import { AgentTestError } from '../../src/test/errors.ts';
@@ -72,7 +76,11 @@ describe('conventional providers through the harness', () => {
     });
   });
 
-  it('mounts providers for an MCP route at the route-unit level', async () => {
+  it('mounts providers for an MCP route at the route-unit level, including when it is also a projected CLI command', async () => {
+    // `harness tooling` is projected onto the CLI from this tool; its command
+    // carries the tool's route id, so rendering it takes the tool branch the
+    // generated entry takes for `command.mcp !== undefined`.
+    expect(testManifest().cliCommands.find((command) => command.mcp?.tool === 'tooling')?.routeId).toBe('tool:harness/tooling');
     const rendered = await renderRoute('tool:harness/tooling');
 
     expect(rendered.result).toEqual({
@@ -152,6 +160,44 @@ describe('conventional providers through the harness', () => {
     expect(new Set(lifetimes.map((lifetime) => lifetime.instanceId)).size).toBe(1);
   });
 
+  it('claims the hit before awaiting state bindings, so hits follow arrival order like the generated worker', async () => {
+    type Lifetime = { processLifetime: { hits: number; instanceId: string } };
+    const definition = defineState({
+      events: { changed: z.object({ value: z.string() }).strict() },
+      id: 'providers/request-state',
+      initial: { value: '' },
+      lifetime: 'request',
+      reduce: (_state, event) => ({ value: event.payload.value }),
+      schema: z.object({ value: z.string() }).strict(),
+    });
+    const inner = createMemoryStateDriver({ lifetime: 'request' });
+    let projectOpens = 0;
+    const driver: AgentStateDriver = {
+      ...inner,
+      open: async (opened) => {
+        // Only the first request's project store is slow to open; the second
+        // request's bindings resolve first.
+        if (opened.id === definition.id && projectOpens++ === 0) await sleep(150);
+        return inner.open(opened);
+      },
+    };
+    await using session = await openInMemoryMcpServer({ state: { definition, driver } });
+
+    const [first, second] = await Promise.all([
+      session.client.callTool({ arguments: {}, name: 'tooling' }),
+      session.client.callTool({ arguments: {}, name: 'tooling' }),
+    ]);
+    const lifetimeOf = (result: unknown): Lifetime['processLifetime'] =>
+      (result as { structuredContent: Lifetime }).structuredContent.processLifetime;
+
+    // The generated worker increments and snapshots before `requestBindings`;
+    // the request that arrived first keeps hit 1 even though its state
+    // bindings resolved last.
+    expect(lifetimeOf(first).hits).toBe(1);
+    expect(lifetimeOf(second).hits).toBe(2);
+    expect(projectOpens).toBe(2);
+  });
+
   it('gives every route-unit render a fresh process identity', async () => {
     type Result = { processLifetime: { hits: number; instanceId: string } };
     const first = (await renderRoute('tool:harness/tooling')).result as Result;