@parall/claude-agent 1.63.0 → 1.65.0

package/dist/dispatch.d.ts

@@ -1,4 +1,4 @@
-import type { CleanupForkOpts, CompactOpts, CompactResult, DispatchAdapter, DispatchInputLifecycle, DispatchOpts, ForkOpts, GatewayLogger, RuntimeActivityEvent, RuntimeBusyState, RuntimeEvent } from '@parall/agent-core';
+import type { CleanupForkOpts, CompactOpts, CompactResult, DiscardedInjectionOutcome, DispatchAdapter, DispatchInputLifecycle, DispatchOpts, ForkOpts, GatewayLogger, RuntimeActivityEvent, RuntimeBusyState, RuntimeEvent } from '@parall/agent-core';
 import type { ClaudeAgentConfig } from './config.js';
 import { ClaudeInputRegistry } from './input-lifecycle.js';
 import { ClaudeProcessPump } from './process-pump.js';
@@ -60,6 +60,7 @@ export type ProcessState = {
 export declare class ClaudeCodeAdapter implements DispatchAdapter {
     private readonly opts;
     readonly inputLifecycleMode: "explicit";
+    readonly inputSettlementMode: "receipt";
     private readonly processes;
     /** Retired by abortDispatch while the CLI still had its own work: busy until idle, then terminated. */
     private readonly retiring;
@@ -88,7 +89,19 @@ export declare class ClaudeCodeAdapter implements DispatchAdapter {
     abortDispatch(sessionKey: string): void;
     hasPendingInjections(sessionKey: string): boolean;
     hasUnsettledInjections(sessionKey: string): boolean;
-    acknowledgeDiscardedInjection(sessionKey: string, deliveryKey: string): void;
+    /**
+     * The gateway discarded the buffered copy of an injection without a
+     * dispatch(). A settled injection only owes bookkeeping. One that has NOT
+     * settled is an orphan: nothing will ever drain it, and the CLI does not
+     * start a queued input on its own once the turn it was steered into has
+     * ended — it works its queue only when the next stdin frame arrives, which
+     * would be the batch re-delivering this very member (prod 2026-09-03: lane
+     * dethroned after 10 idle minutes, then "refusing duplicate stdin write"
+     * on every retry). Withdraw it: kill the process (the session survives via
+     * --resume), report the input failed so the server releases the member,
+     * and let the gateway run it as a real turn.
+     */
+    acknowledgeDiscardedInjection(sessionKey: string, deliveryKey: string): Promise<DiscardedInjectionOutcome>;
     dispatch({ event, bodyForAgent, sessionKey, context, inputLifecycle, noteActivity, }: DispatchOpts): AsyncIterable<RuntimeEvent>;
     getBranchPoint(_sessionKey: string): string | undefined;
     getSessionHistoryPath(sessionKey: string): string | undefined;
@@ -125,6 +138,7 @@ export declare class ClaudeCodeAdapter implements DispatchAdapter {
     private maybeApplyRestart;
     private ensureProcess;
     private spawnProcess;
+    /** Resolves once every live input's failed report has settled (best effort). */
     private killProcess;
     private endStdin;
     private terminateHandle;

package/dist/dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"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"}

package/dist/dispatch.js

@@ -33,6 +33,7 @@ function killWin32Tree(pid) {
 export class ClaudeCodeAdapter {
     opts;
     inputLifecycleMode = 'explicit';
+    inputSettlementMode = 'receipt';
     processes = new Map();
     /** Retired by abortDispatch while the CLI still had its own work: busy until idle, then terminated. */
     retiring = new Set();
@@ -169,16 +170,44 @@ export class ClaudeCodeAdapter {
             return false;
         return state.inputs.hasUnsettledInjections();
     }
-    acknowledgeDiscardedInjection(sessionKey, deliveryKey) {
+    /**
+     * The gateway discarded the buffered copy of an injection without a
+     * dispatch(). A settled injection only owes bookkeeping. One that has NOT
+     * settled is an orphan: nothing will ever drain it, and the CLI does not
+     * start a queued input on its own once the turn it was steered into has
+     * ended — it works its queue only when the next stdin frame arrives, which
+     * would be the batch re-delivering this very member (prod 2026-09-03: lane
+     * dethroned after 10 idle minutes, then "refusing duplicate stdin write"
+     * on every retry). Withdraw it: kill the process (the session survives via
+     * --resume), report the input failed so the server releases the member,
+     * and let the gateway run it as a real turn.
+     */
+    async acknowledgeDiscardedInjection(sessionKey, deliveryKey) {
         const state = this.processes.get(sessionKey);
         if (!state)
-            return;
+            return 'discarded';
+        const delivery = state.inputs.getByKey(deliveryKey);
+        if (delivery && !delivery.terminal) {
+            state.log?.warn?.(`withdrawing orphaned Claude input ${delivery.commandUuid} (${delivery.reportedState ?? 'queued'}) on ${sessionKey}: its buffered copy was discarded before the CLI settled it${state.pump.hasOwnWork() ? '; the runtime-initiated turn dies with the process' : ''}`);
+            await this.killProcess(sessionKey, state);
+            state.inputs.discardBookkeeping(deliveryKey);
+            // 'cancelled' only when the server confirmed the failed receipt: the
+            // member is released and un-folded, so the gateway can re-fold and run
+            // it locally. A lost receipt (reportedState never reached 'failed') or
+            // a 'settled' answer (a reply effect already resolved the member)
+            // leaves nothing to re-run here — the lane complete releases an unread
+            // member for re-drive instead.
+            const confirmed = delivery.reportedState === 'failed' && delivery.terminal === 'failed';
+            if (!confirmed) {
+                state.log?.warn?.(`withdrawal of Claude input ${delivery.commandUuid} was not confirmed by the server (${delivery.terminal}); leaving the member to the lane complete`);
+            }
+            return confirmed ? 'cancelled' : 'discarded';
+        }
         state.inputs.discardBookkeeping(deliveryKey);
         // The discarded copy may have been the last thing a lazy restart was
-        // waiting on. Unlike the consume path's tail, the discarded delivery may
-        // still be RUNNING (non-terminal): killing the process now would fail a
-        // live input, so the restart also waits for every injection to settle.
+        // waiting on.
         this.maybeApplyRestart(sessionKey, state);
+        return 'discarded';
     }
     async *dispatch({ event, bodyForAgent, sessionKey, context, inputLifecycle, noteActivity, }) {
         const deliveryKey = inputLifecycle?.deliveryKey ?? event.dispatchEventId ?? event.messageId;
@@ -246,13 +275,13 @@ export class ClaudeCodeAdapter {
     cleanupFork({ fork }) {
         const state = this.processes.get(fork.sessionKey);
         if (state) {
-            this.killProcess(fork.sessionKey, state);
+            void this.killProcess(fork.sessionKey, state);
         }
         this.opts.sessionManager.cleanupFork(fork.sessionKey);
     }
     resetProcesses() {
         for (const [sessionKey, state] of this.processes) {
-            this.killProcess(sessionKey, state);
+            void this.killProcess(sessionKey, state);
         }
         this.processes.clear();
         const retired = [...this.retiring];
@@ -303,7 +332,7 @@ export class ClaudeCodeAdapter {
             await state.inputs.failBestEffort(delivery, log, `Claude stdin write failed: ${String(err)}`);
             state.inputs.remove(delivery);
             yield { type: 'error', message: `Claude stdin write failed: ${String(err)}` };
-            this.killProcess(sessionKey, state);
+            void this.killProcess(sessionKey, state);
             return;
         }
         try {
@@ -318,7 +347,9 @@ export class ClaudeCodeAdapter {
         return runClaudeCompact({
             ensureRuntimeCapability: (log) => this.ensureRuntimeCapability(log),
             ensureProcess: (sessionKey, log) => this.ensureProcess(sessionKey, log),
-            killProcess: (sessionKey, state) => this.killProcess(sessionKey, state),
+            killProcess: (sessionKey, state) => {
+                void this.killProcess(sessionKey, state);
+            },
             writeUserMessage: (handle, text, uuid) => this.writeUserMessage(handle, text, uuid),
             applyPendingRestart: (sessionKey, state) => this.maybeApplyRestart(sessionKey, state),
         }, opts);
@@ -451,7 +482,7 @@ export class ClaudeCodeAdapter {
         if (outstanding.total > 0) {
             state.log?.warn?.(`restarting ${sessionKey} with ${outstanding.total} live background task(s); they die with the process`);
         }
-        this.killProcess(sessionKey, state);
+        void this.killProcess(sessionKey, state);
     }
     ensureProcess(sessionKey, log) {
         if (this.shuttingDown) {
@@ -466,7 +497,7 @@ export class ClaudeCodeAdapter {
                     log?.info?.(`deferring lazy restart of ${sessionKey}: runtime-initiated turn in progress`);
                     return existing;
                 }
-                this.killProcess(sessionKey, existing);
+                void this.killProcess(sessionKey, existing);
             }
             else if (alive) {
                 return existing;
@@ -501,7 +532,7 @@ export class ClaudeCodeAdapter {
                     onFatal: () => {
                         const current = this.processes.get(sessionKey);
                         if (current === state)
-                            this.killProcess(sessionKey, state);
+                            void this.killProcess(sessionKey, state);
                     },
                     onEof: () => {
                         state.done = true;
@@ -509,10 +540,9 @@ export class ClaudeCodeAdapter {
                             this.processes.delete(sessionKey);
                         this.retiring.delete(state);
                     },
-                    // Main-session turns go to the gateway (steps + session activity);
-                    // fork-session turns only count as busy (fork-scope invariant).
                     onRuntimeTurnOpened: (turn) => this.activity.surfaceTurn(turn, this.opts.sessionManager.isMain(sessionKey), log),
                     onRuntimeTurnClosed: () => this.maybeApplyRestart(sessionKey, state),
+                    onObservation: (event) => this.activity.emit({ kind: 'observation', sessionKey, event }, log),
                 },
             }),
             done: false,
@@ -564,10 +594,12 @@ export class ClaudeCodeAdapter {
         });
         return { proc, exitPromise, stderrChunks };
     }
+    /** Resolves once every live input's failed report has settled (best effort). */
     killProcess(sessionKey, state) {
+        const reports = [];
         for (const delivery of state.inputs.values()) {
             if (!delivery.terminal)
-                void state.inputs.failBestEffort(delivery);
+                reports.push(state.inputs.failBestEffort(delivery, state.log));
         }
         state.done = true;
         const current = this.processes.get(sessionKey);
@@ -576,6 +608,7 @@ export class ClaudeCodeAdapter {
         }
         state.pump.close('killed', 'Claude process terminated by the bridge');
         this.terminateHandle(state.handle);
+        return Promise.all(reports).then(() => undefined);
     }
     endStdin(handle) {
         try {

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import * as os from 'node:os';
-import { capabilityBinDir, childLogger, clearAllProviderCreds, configureHttpKeepAlive, createLogger, createOtelLogger, createPlatformConfigManager, deriveModelIsPin, identityFromMe, initAgentTelemetry, llmSource, resolveServiceVersion, materializeChannelCapabilities, ParallAgentGateway, parseDispatchDeadlineMs, parseForkDeadlineMs, parseProviderConfig, parseShutdownDeadlineMs, resolveRuntimeContextWindow, resolveRuntimeMaxTokens, resolveRuntimeModel, traceContextHeaders, } from '@parall/agent-core';
+import { classifyStartupFailure, capabilityBinDir, childLogger, clearAllProviderCreds, configureHttpKeepAlive, createLogger, createOtelLogger, createPlatformConfigManager, deriveModelIsPin, identityFromMe, initAgentTelemetry, llmSource, resolveServiceVersion, materializeChannelCapabilities, ParallAgentGateway, parseDispatchDeadlineMs, parseForkDeadlineMs, parseProviderConfig, parseShutdownDeadlineMs, resolveRuntimeContextWindow, resolveRuntimeMaxTokens, resolveRuntimeModel, traceContextHeaders, newRuntimeInstanceId, } from '@parall/agent-core';
 import { ApiError, ParallClient, ParallWs } from '@parall/sdk';
 import { buildClaudeRuntimeKey, contextFilePathForSession, dispatchContextDirPath, resolveClaudeAgentConfig, resolveWsUrl, sessionStateFilePathForRuntime, stepIdFilePathForSession, } from './config.js';
 import { ClaudeCodeAdapter } from './dispatch.js';
@@ -84,8 +84,12 @@ async function main() {
         const sessionStateFilePath = sessionStateFilePathForRuntime(config.stateDir, runtimeKey);
         const sessionManager = new ClaudeSessionManager(runtimeKey, sessionStateFilePath, agentLog);
         const resolvedWsUrl = resolveWsUrl(config.apiUrl, config.wsUrl, config.swimlaneName);
+        // This process's runtime instance: rides the WS ticket and every claim so
+        // the server owns turns by process identity instead of a lease clock
+        // (agent-dispatch-idempotency-design.md#instance-ownership).
+        const instanceId = newRuntimeInstanceId();
         const ws = new ParallWs({
-            getTicket: () => client.getWsTicket(),
+            getTicket: () => client.getWsTicket({ instance_id: instanceId }),
             wsUrl: resolvedWsUrl,
         });
         const configMgr = createPlatformConfigManager({
@@ -237,6 +241,7 @@ async function main() {
             accountId: agentUserId,
             client,
             ws,
+            instanceId,
             connectionLabel: resolvedWsUrl,
             config: {
                 parall_url: config.apiUrl,
@@ -300,6 +305,19 @@ async function main() {
     }
 }
 main().catch((err) => {
-    activeLog.error(`fatal: ${String(err)}`);
-    process.exitCode = 1;
+    // A credential the server rejects during bootstrap is the same terminal
+    // failure the gateway reports as auth-invalid: exit with the re-mint code
+    // so the daemon mints a fresh launch credential instead of restarting
+    // this process with the same dead key.
+    const { exitCode, authRejection } = classifyStartupFailure(err);
+    if (authRejection) {
+        activeLog.error(`AUTH-INVALID at startup status=${authRejection.status}` +
+            `${authRejection.code ? ` code=${authRejection.code}` : ''} — ` +
+            `the server rejected this runtime's credential (${authRejection.message}); ` +
+            `exiting with code ${exitCode} so the supervisor can re-mint the launch credential.`);
+    }
+    else {
+        activeLog.error(`fatal: ${String(err)}`);
+    }
+    process.exitCode = exitCode;
 });

package/dist/output-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output-parser.d.ts","sourceRoot":"","sources":["../src/output-parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EACH,0BAA0B,GAC1B,cAAc,GACd,eAAe,GACf,cAAc,GACd,mBAAmB,GACnB,QAAQ,GACR,uBAAuB,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC/F,CAAC;AAYF,MAAM,MAAM,iBAAiB,GACzB,YAAY,GACZ;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,GACpE,sBAAsB,GAItB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAKnC;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,GAC5B;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;CACvE,GAID;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAI5C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAqBlE;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B,CAAC;AAgFN,wBAAuB,qBAAqB,CAC1C,QAAQ,EAAE,QAAQ,GACjB,cAAc,CAAC,iBAAiB,CAAC,CA6NnC"}
+{"version":3,"file":"output-parser.d.ts","sourceRoot":"","sources":["../src/output-parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EACH,0BAA0B,GAC1B,cAAc,GACd,eAAe,GACf,cAAc,GACd,mBAAmB,GACnB,QAAQ,GACR,uBAAuB,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC/F,CAAC;AAYF,MAAM,MAAM,iBAAiB,GACzB,YAAY,GACZ;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,GACpE,sBAAsB,GAItB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAKnC;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,GAC5B;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;CACvE,GAID;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAI5C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAqBlE;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B,CAAC;AAgFN,wBAAuB,qBAAqB,CAC1C,QAAQ,EAAE,QAAQ,GACjB,cAAc,CAAC,iBAAiB,CAAC,CAiOnC"}

package/dist/output-parser.js

@@ -1,3 +1,4 @@
+import { claudeObservation } from './runtime-observations.js';
 const RUNTIME_TASK_SUBTYPES = new Set([
     'background_tasks_changed',
     'task_started',
@@ -100,6 +101,10 @@ export async function* parseClaudeStreamJson(readable) {
         const now = Date.now();
         const eventTimestampMs = parseEventTimestampMs(event) ?? now;
         const eventRecord = event;
+        const observation = claudeObservation(eventRecord);
+        // Init must announce the native session before its observations drain.
+        if (observation && observation.content.event !== 'session_initialized')
+            yield observation;
         if (eventRecord.type === 'system' && eventRecord.subtype === 'compact_boundary') {
             const meta = eventRecord.compact_metadata && typeof eventRecord.compact_metadata === 'object'
                 ? eventRecord.compact_metadata
@@ -126,6 +131,8 @@ export async function* parseClaudeStreamJson(readable) {
                     ...(sessionId ? { sessionId } : {}),
                     capabilities,
                 };
+                if (observation)
+                    yield observation;
                 continue;
             }
             const subtype = asTrimmedString(eventRecord.subtype);

package/dist/process-pump.d.ts

@@ -1,4 +1,4 @@
-import { type GatewayLogger, type RuntimeBusyState } from '@parall/agent-core';
+import { type GatewayLogger, type RuntimeBusyState, type RuntimeObservationEvent } from '@parall/agent-core';
 import { ClaudeBusyTracker } from './busy-state.js';
 import type { ClaudeInputDelivery, ClaudeInputRegistry } from './input-lifecycle.js';
 import type { ClaudeParsedEvent } from './output-parser.js';
@@ -17,6 +17,7 @@ export type ClaudeProcessPumpHooks = {
     onEof(): void;
     onRuntimeTurnOpened(turn: ClaudeRuntimeTurn): void;
     onRuntimeTurnClosed(): void;
+    onObservation?(event: RuntimeObservationEvent): void;
 };
 export type ClaudeProcessPumpOptions = {
     sessionKey: string;
@@ -59,6 +60,7 @@ export declare class ClaudeProcessPump {
     private idleTimer;
     private activeDrain;
     private readonly now;
+    private pendingObservations;
     constructor(opts: ClaudeProcessPumpOptions);
     start(): void;
     /** The dispatch generator currently draining `delivery` (owner preference). */
@@ -92,6 +94,7 @@ export declare class ClaudeProcessPump {
     private run;
     private route;
     private touchAll;
+    private routeObservation;
     private liveDeliveries;
     private ownerFor;
     private openRuntimeTurn;

package/dist/process-pump.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-pump.d.ts","sourceRoot":"","sources":["../src/process-pump.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"process-pump.d.ts","sourceRoot":"","sources":["../src/process-pump.ts"],"names":[],"mappings":"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"}

package/dist/process-pump.js

@@ -33,6 +33,7 @@ export class ClaudeProcessPump {
     idleTimer = null;
     activeDrain = null;
     now;
+    pendingObservations = [];
     constructor(opts) {
         this.opts = opts;
         this.now = opts.now ?? Date.now;
@@ -153,7 +154,8 @@ export class ClaudeProcessPump {
             for await (const parsed of parser) {
                 if (this.closed)
                     break;
-                this.touchAll();
+                if (parsed.type !== 'observation')
+                    this.touchAll();
                 await this.route(parsed);
             }
         }
@@ -168,6 +170,9 @@ export class ClaudeProcessPump {
         switch (parsed.type) {
             case 'runtime_activity':
                 return;
+            case 'observation':
+                this.routeObservation(parsed);
+                return;
             case 'runtime_init':
                 this.handleInit(parsed);
                 return;
@@ -222,6 +227,27 @@ export class ClaudeProcessPump {
         }
         this.runtimeTurn?.touch();
     }
+    routeObservation(event) {
+        if (!this.sessionId) {
+            // SessionStart hooks precede init. Keep a bounded startup buffer and
+            // release only records whose native session matches the eventual init.
+            if (this.pendingObservations.length < 64)
+                this.pendingObservations.push(event);
+            else
+                this.opts.log?.warn('Claude startup observation buffer full; dropping observation');
+            return;
+        }
+        if (event.runtimeSessionId !== this.sessionId) {
+            this.opts.log?.warn('Claude observation does not match the initialized session');
+            return;
+        }
+        const owner = this.ownerFor(false) ??
+            (this.activeDrain && !this.activeDrain.terminal ? this.activeDrain : null);
+        if (owner)
+            owner.sink.push({ kind: 'runtime', event });
+        else
+            this.opts.hooks.onObservation?.(event);
+    }
     liveDeliveries() {
         const live = [];
         for (const delivery of this.opts.inputs.values())
@@ -293,6 +319,10 @@ export class ClaudeProcessPump {
             delivery.sessionAnnounced = true;
             delivery.sink.push({ kind: 'runtime', event: announce });
         }
+        const pending = this.pendingObservations;
+        this.pendingObservations = [];
+        for (const event of pending)
+            this.routeObservation(event);
     }
     async handleLifecycle(parsed) {
         if (!this.capabilities.has('msg_lifecycle_v1')) {
@@ -321,6 +351,9 @@ export class ClaudeProcessPump {
                 kind: 'runtime',
                 event: { type: 'error', message: `Claude input lifecycle update failed: ${String(err)}` },
             });
+            // failBestEffort may unregister this delivery before onFatal closes
+            // the process's remaining sinks. Its waiting drain still needs EOF.
+            delivery.sink.close();
             this.opts.hooks.onFatal();
             return;
         }

package/dist/runtime-observations.d.ts

@@ -0,0 +1,4 @@
+import { type RuntimeObservationEvent } from '@parall/agent-core';
+/** Only facts the CLI emitted. A result UUID is not a native turn identity. */
+export declare function claudeObservation(frame: Record<string, unknown>): RuntimeObservationEvent | undefined;
+//# sourceMappingURL=runtime-observations.d.ts.map

package/dist/runtime-observations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-observations.d.ts","sourceRoot":"","sources":["../src/runtime-observations.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,oBAAoB,CAAC;AAG5B,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,uBAAuB,GAAG,SAAS,CAqErC"}

package/dist/runtime-observations.js

@@ -0,0 +1,72 @@
+import { observationField, runtimeObservation, } from '@parall/agent-core';
+/** Only facts the CLI emitted. A result UUID is not a native turn identity. */
+export function claudeObservation(frame) {
+    const sessionId = observationField(frame.session_id);
+    if (!sessionId || frame.parent_tool_use_id)
+        return;
+    const native = {
+        session_id: sessionId,
+        event_id: observationField(frame.uuid),
+    };
+    let event;
+    let status = 'unknown';
+    if (frame.type === 'result') {
+        event = 'request_completed';
+        status =
+            frame.is_error === true ? 'failed' : frame.is_error === false ? 'completed' : 'unknown';
+        native.status = observationField(frame.subtype);
+        if (typeof frame.num_turns === 'number' &&
+            Number.isSafeInteger(frame.num_turns) &&
+            frame.num_turns >= 0) {
+            native.num_turns = frame.num_turns;
+        }
+    }
+    else if (frame.type === 'system') {
+        switch (frame.subtype) {
+            case 'init':
+                event = 'session_initialized';
+                status = 'initialized';
+                break;
+            case 'hook_started':
+            case 'hook_response':
+                event = frame.subtype === 'hook_started' ? 'hook_started' : 'hook_completed';
+                status =
+                    frame.subtype === 'hook_started'
+                        ? 'running'
+                        : frame.outcome === 'success'
+                            ? 'completed'
+                            : frame.outcome === 'error'
+                                ? 'failed'
+                                : frame.outcome === 'cancelled'
+                                    ? 'stopped'
+                                    : 'unknown';
+                native.hook_id = observationField(frame.hook_id);
+                native.hook_event = observationField(frame.hook_event);
+                native.status = observationField(frame.outcome);
+                break;
+            case 'status':
+            case 'session_state_changed':
+                event = 'session_status';
+                native.status = observationField(frame.status) ?? observationField(frame.state);
+                // Null does not prove the runtime is idle; only explicit known states
+                // can become public statuses.
+                if (native.status === 'compacting' ||
+                    native.status === 'running' ||
+                    native.status === 'idle') {
+                    status = native.status;
+                }
+                break;
+            default:
+                return;
+        }
+    }
+    else
+        return;
+    return runtimeObservation(sessionId, {
+        runtime: 'claude-code',
+        source: 'stream_json',
+        event,
+        status,
+        native,
+    });
+}

package/dist/spawn-env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spawn-env.d.ts","sourceRoot":"","sources":["../src/spawn-env.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,CAAC,UAAU,EAC5B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,EAChC,IAAI,EAAE;IACJ,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GACA,MAAM,CAAC,UAAU,CAiFnB"}
+{"version":3,"file":"spawn-env.d.ts","sourceRoot":"","sources":["../src/spawn-env.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,CAAC,UAAU,EAC5B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,EAChC,IAAI,EAAE;IACJ,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GACA,MAAM,CAAC,UAAU,CAoFnB"}

package/dist/spawn-env.js

@@ -8,6 +8,9 @@ export function buildSpawnEnv(parentEnv, claudeHome, context, opts) {
     const result = {
         ...env,
         HOME: claudeHome,
+        // Request native state frames for observation without changing user files.
+        // Preserve an operator's explicit opt-out; older CLIs can ignore the flag.
+        CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: env.CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS ?? '1',
         PRLL_API_URL: context.apiUrl,
         PRLL_API_KEY: context.apiKey,
         PRLL_ORG_ID: context.orgId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/claude-agent",
-  "version": "1.63.0",
+  "version": "1.65.0",
   "description": "Claude Code bridge runtime for self-hosted Parall agents",
   "license": "MIT",
   "repository": {
@@ -25,9 +25,9 @@
     "src"
   ],
   "dependencies": {
-    "@parall/agent-core": "1.63.0",
-    "@parall/cli": "1.63.0",
-    "@parall/sdk": "1.63.0"
+    "@parall/agent-core": "1.65.0",
+    "@parall/cli": "1.65.0",
+    "@parall/sdk": "1.65.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/dispatch.ts

@@ -6,6 +6,7 @@ import type {
   CleanupForkOpts,
   CompactOpts,
   CompactResult,
+  DiscardedInjectionOutcome,
   DispatchAdapter,
   DispatchInputLifecycle,
   DispatchOpts,
@@ -119,6 +120,7 @@ export type ProcessState = {
 
 export class ClaudeCodeAdapter implements DispatchAdapter {
   readonly inputLifecycleMode = 'explicit' as const;
+  readonly inputSettlementMode = 'receipt' as const;
   private readonly processes = new Map<string, ProcessState>();
   /** Retired by abortDispatch while the CLI still had its own work: busy until idle, then terminated. */
   private readonly retiring = new Set<ProcessState>();
@@ -260,15 +262,50 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     return state.inputs.hasUnsettledInjections();
   }
 
-  acknowledgeDiscardedInjection(sessionKey: string, deliveryKey: string): void {
+  /**
+   * The gateway discarded the buffered copy of an injection without a
+   * dispatch(). A settled injection only owes bookkeeping. One that has NOT
+   * settled is an orphan: nothing will ever drain it, and the CLI does not
+   * start a queued input on its own once the turn it was steered into has
+   * ended — it works its queue only when the next stdin frame arrives, which
+   * would be the batch re-delivering this very member (prod 2026-09-03: lane
+   * dethroned after 10 idle minutes, then "refusing duplicate stdin write"
+   * on every retry). Withdraw it: kill the process (the session survives via
+   * --resume), report the input failed so the server releases the member,
+   * and let the gateway run it as a real turn.
+   */
+  async acknowledgeDiscardedInjection(
+    sessionKey: string,
+    deliveryKey: string,
+  ): Promise<DiscardedInjectionOutcome> {
     const state = this.processes.get(sessionKey);
-    if (!state) return;
+    if (!state) return 'discarded';
+    const delivery = state.inputs.getByKey(deliveryKey);
+    if (delivery && !delivery.terminal) {
+      state.log?.warn?.(
+        `withdrawing orphaned Claude input ${delivery.commandUuid} (${delivery.reportedState ?? 'queued'}) on ${sessionKey}: its buffered copy was discarded before the CLI settled it${state.pump.hasOwnWork() ? '; the runtime-initiated turn dies with the process' : ''}`,
+      );
+      await this.killProcess(sessionKey, state);
+      state.inputs.discardBookkeeping(deliveryKey);
+      // 'cancelled' only when the server confirmed the failed receipt: the
+      // member is released and un-folded, so the gateway can re-fold and run
+      // it locally. A lost receipt (reportedState never reached 'failed') or
+      // a 'settled' answer (a reply effect already resolved the member)
+      // leaves nothing to re-run here — the lane complete releases an unread
+      // member for re-drive instead.
+      const confirmed = delivery.reportedState === 'failed' && delivery.terminal === 'failed';
+      if (!confirmed) {
+        state.log?.warn?.(
+          `withdrawal of Claude input ${delivery.commandUuid} was not confirmed by the server (${delivery.terminal}); leaving the member to the lane complete`,
+        );
+      }
+      return confirmed ? 'cancelled' : 'discarded';
+    }
     state.inputs.discardBookkeeping(deliveryKey);
     // The discarded copy may have been the last thing a lazy restart was
-    // waiting on. Unlike the consume path's tail, the discarded delivery may
-    // still be RUNNING (non-terminal): killing the process now would fail a
-    // live input, so the restart also waits for every injection to settle.
+    // waiting on.
     this.maybeApplyRestart(sessionKey, state);
+    return 'discarded';
   }
 
   async *dispatch({
@@ -360,14 +397,14 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
   cleanupFork({ fork }: CleanupForkOpts) {
     const state = this.processes.get(fork.sessionKey);
     if (state) {
-      this.killProcess(fork.sessionKey, state);
+      void this.killProcess(fork.sessionKey, state);
     }
     this.opts.sessionManager.cleanupFork(fork.sessionKey);
   }
 
   resetProcesses(): void {
     for (const [sessionKey, state] of this.processes) {
-      this.killProcess(sessionKey, state);
+      void this.killProcess(sessionKey, state);
     }
     this.processes.clear();
     const retired = [...this.retiring];
@@ -425,7 +462,7 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
       await state.inputs.failBestEffort(delivery, log, `Claude stdin write failed: ${String(err)}`);
       state.inputs.remove(delivery);
       yield { type: 'error', message: `Claude stdin write failed: ${String(err)}` };
-      this.killProcess(sessionKey, state);
+      void this.killProcess(sessionKey, state);
       return;
     }
 
@@ -442,7 +479,9 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
       {
         ensureRuntimeCapability: (log) => this.ensureRuntimeCapability(log),
         ensureProcess: (sessionKey, log) => this.ensureProcess(sessionKey, log),
-        killProcess: (sessionKey, state) => this.killProcess(sessionKey, state),
+        killProcess: (sessionKey, state) => {
+          void this.killProcess(sessionKey, state);
+        },
         writeUserMessage: (handle, text, uuid) => this.writeUserMessage(handle, text, uuid),
         applyPendingRestart: (sessionKey, state) => this.maybeApplyRestart(sessionKey, state),
       },
@@ -583,7 +622,7 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
         `restarting ${sessionKey} with ${outstanding.total} live background task(s); they die with the process`,
       );
     }
-    this.killProcess(sessionKey, state);
+    void this.killProcess(sessionKey, state);
   }
 
   private ensureProcess(sessionKey: string, log: GatewayLogger | undefined): ProcessState {
@@ -602,7 +641,7 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
           );
           return existing;
         }
-        this.killProcess(sessionKey, existing);
+        void this.killProcess(sessionKey, existing);
       } else if (alive) {
         return existing;
       } else {
@@ -635,18 +674,18 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
           },
           onFatal: () => {
             const current = this.processes.get(sessionKey);
-            if (current === state) this.killProcess(sessionKey, state);
+            if (current === state) void this.killProcess(sessionKey, state);
           },
           onEof: () => {
             state.done = true;
             if (this.processes.get(sessionKey) === state) this.processes.delete(sessionKey);
             this.retiring.delete(state);
           },
-          // Main-session turns go to the gateway (steps + session activity);
-          // fork-session turns only count as busy (fork-scope invariant).
           onRuntimeTurnOpened: (turn) =>
             this.activity.surfaceTurn(turn, this.opts.sessionManager.isMain(sessionKey), log),
           onRuntimeTurnClosed: () => this.maybeApplyRestart(sessionKey, state),
+          onObservation: (event) =>
+            this.activity.emit({ kind: 'observation', sessionKey, event }, log),
         },
       }),
       done: false,
@@ -723,9 +762,11 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     return { proc, exitPromise, stderrChunks };
   }
 
-  private killProcess(sessionKey: string, state: ProcessState) {
+  /** Resolves once every live input's failed report has settled (best effort). */
+  private killProcess(sessionKey: string, state: ProcessState): Promise<void> {
+    const reports: Promise<void>[] = [];
     for (const delivery of state.inputs.values()) {
-      if (!delivery.terminal) void state.inputs.failBestEffort(delivery);
+      if (!delivery.terminal) reports.push(state.inputs.failBestEffort(delivery, state.log));
     }
     state.done = true;
     const current = this.processes.get(sessionKey);
@@ -734,6 +775,7 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     }
     state.pump.close('killed', 'Claude process terminated by the bridge');
     this.terminateHandle(state.handle);
+    return Promise.all(reports).then(() => undefined);
   }
 
   private endStdin(handle: ClaudeProcessHandle): void {

package/src/index.ts

@@ -2,6 +2,7 @@
 
 import * as os from 'node:os';
 import {
+  classifyStartupFailure,
   capabilityBinDir,
   childLogger,
   clearAllProviderCreds,
@@ -24,6 +25,7 @@ import {
   resolveRuntimeMaxTokens,
   resolveRuntimeModel,
   traceContextHeaders,
+  newRuntimeInstanceId,
 } from '@parall/agent-core';
 import { ApiError, ParallClient, ParallWs } from '@parall/sdk';
 import {
@@ -124,8 +126,12 @@ async function main() {
     const sessionManager = new ClaudeSessionManager(runtimeKey, sessionStateFilePath, agentLog);
 
     const resolvedWsUrl = resolveWsUrl(config.apiUrl, config.wsUrl, config.swimlaneName);
+    // This process's runtime instance: rides the WS ticket and every claim so
+    // the server owns turns by process identity instead of a lease clock
+    // (agent-dispatch-idempotency-design.md#instance-ownership).
+    const instanceId = newRuntimeInstanceId();
     const ws = new ParallWs({
-      getTicket: () => client.getWsTicket(),
+      getTicket: () => client.getWsTicket({ instance_id: instanceId }),
       wsUrl: resolvedWsUrl,
     });
 
@@ -299,6 +305,7 @@ async function main() {
       accountId: agentUserId,
       client,
       ws,
+      instanceId,
       connectionLabel: resolvedWsUrl,
       config: {
         parall_url: config.apiUrl,
@@ -365,6 +372,20 @@ async function main() {
 }
 
 main().catch((err) => {
-  activeLog.error(`fatal: ${String(err)}`);
-  process.exitCode = 1;
+  // A credential the server rejects during bootstrap is the same terminal
+  // failure the gateway reports as auth-invalid: exit with the re-mint code
+  // so the daemon mints a fresh launch credential instead of restarting
+  // this process with the same dead key.
+  const { exitCode, authRejection } = classifyStartupFailure(err);
+  if (authRejection) {
+    activeLog.error(
+      `AUTH-INVALID at startup status=${authRejection.status}` +
+        `${authRejection.code ? ` code=${authRejection.code}` : ''} — ` +
+        `the server rejected this runtime's credential (${authRejection.message}); ` +
+        `exiting with code ${exitCode} so the supervisor can re-mint the launch credential.`,
+    );
+  } else {
+    activeLog.error(`fatal: ${String(err)}`);
+  }
+  process.exitCode = exitCode;
 });

package/src/output-parser.ts

@@ -1,5 +1,6 @@
 import type { Readable } from 'node:stream';
 import type { RuntimeEvent } from '@parall/agent-core';
+import { claudeObservation } from './runtime-observations.js';
 
 /**
  * Structured snapshot of the `result` frame's LLM-layer discriminators and
@@ -215,6 +216,9 @@ export async function* parseClaudeStreamJson(
     const now = Date.now();
     const eventTimestampMs = parseEventTimestampMs(event) ?? now;
     const eventRecord = event as Record<string, unknown>;
+    const observation = claudeObservation(eventRecord);
+    // Init must announce the native session before its observations drain.
+    if (observation && observation.content.event !== 'session_initialized') yield observation;
 
     if (eventRecord.type === 'system' && eventRecord.subtype === 'compact_boundary') {
       const meta =
@@ -244,6 +248,7 @@ export async function* parseClaudeStreamJson(
           ...(sessionId ? { sessionId } : {}),
           capabilities,
         };
+        if (observation) yield observation;
         continue;
       }
       const subtype = asTrimmedString(eventRecord.subtype) as

package/src/process-pump.ts

@@ -3,6 +3,7 @@ import {
   type GatewayLogger,
   type RuntimeBusyState,
   type RuntimeTurnTrigger,
+  type RuntimeObservationEvent,
 } from '@parall/agent-core';
 import { ClaudeBusyTracker } from './busy-state.js';
 import type { ClaudeInputDelivery, ClaudeInputRegistry } from './input-lifecycle.js';
@@ -24,6 +25,7 @@ export type ClaudeProcessPumpHooks = {
   onEof(): void;
   onRuntimeTurnOpened(turn: ClaudeRuntimeTurn): void;
   onRuntimeTurnClosed(): void;
+  onObservation?(event: RuntimeObservationEvent): void;
 };
 
 export type ClaudeProcessPumpOptions = {
@@ -67,6 +69,7 @@ export class ClaudeProcessPump {
   private idleTimer: NodeJS.Timeout | null = null;
   private activeDrain: ClaudeInputDelivery | null = null;
   private readonly now: () => number;
+  private pendingObservations: RuntimeObservationEvent[] = [];
 
   constructor(private readonly opts: ClaudeProcessPumpOptions) {
     this.now = opts.now ?? Date.now;
@@ -194,7 +197,7 @@ export class ClaudeProcessPump {
     try {
       for await (const parsed of parser) {
         if (this.closed) break;
-        this.touchAll();
+        if (parsed.type !== 'observation') this.touchAll();
         await this.route(parsed);
       }
     } catch (err) {
@@ -208,6 +211,9 @@ export class ClaudeProcessPump {
     switch (parsed.type) {
       case 'runtime_activity':
         return;
+      case 'observation':
+        this.routeObservation(parsed);
+        return;
       case 'runtime_init':
         this.handleInit(parsed);
         return;
@@ -261,6 +267,25 @@ export class ClaudeProcessPump {
     this.runtimeTurn?.touch();
   }
 
+  private routeObservation(event: RuntimeObservationEvent): void {
+    if (!this.sessionId) {
+      // SessionStart hooks precede init. Keep a bounded startup buffer and
+      // release only records whose native session matches the eventual init.
+      if (this.pendingObservations.length < 64) this.pendingObservations.push(event);
+      else this.opts.log?.warn('Claude startup observation buffer full; dropping observation');
+      return;
+    }
+    if (event.runtimeSessionId !== this.sessionId) {
+      this.opts.log?.warn('Claude observation does not match the initialized session');
+      return;
+    }
+    const owner =
+      this.ownerFor(false) ??
+      (this.activeDrain && !this.activeDrain.terminal ? this.activeDrain : null);
+    if (owner) owner.sink.push({ kind: 'runtime', event });
+    else this.opts.hooks.onObservation?.(event);
+  }
+
   private liveDeliveries(): ClaudeInputDelivery[] {
     const live: ClaudeInputDelivery[] = [];
     for (const delivery of this.opts.inputs.values()) if (isLive(delivery)) live.push(delivery);
@@ -328,6 +353,9 @@ export class ClaudeProcessPump {
       delivery.sessionAnnounced = true;
       delivery.sink.push({ kind: 'runtime', event: announce });
     }
+    const pending = this.pendingObservations;
+    this.pendingObservations = [];
+    for (const event of pending) this.routeObservation(event);
   }
 
   private async handleLifecycle(parsed: {
@@ -361,6 +389,9 @@ export class ClaudeProcessPump {
         kind: 'runtime',
         event: { type: 'error', message: `Claude input lifecycle update failed: ${String(err)}` },
       });
+      // failBestEffort may unregister this delivery before onFatal closes
+      // the process's remaining sinks. Its waiting drain still needs EOF.
+      delivery.sink.close();
       this.opts.hooks.onFatal();
       return;
     }

package/src/runtime-observations.ts

@@ -0,0 +1,80 @@
+import {
+  observationField,
+  runtimeObservation,
+  type RuntimeObservationEvent,
+} from '@parall/agent-core';
+import type { RuntimeObservationContent } from '@parall/sdk';
+
+/** Only facts the CLI emitted. A result UUID is not a native turn identity. */
+export function claudeObservation(
+  frame: Record<string, unknown>,
+): RuntimeObservationEvent | undefined {
+  const sessionId = observationField(frame.session_id);
+  if (!sessionId || frame.parent_tool_use_id) return;
+  const native: NonNullable<RuntimeObservationContent['native']> = {
+    session_id: sessionId,
+    event_id: observationField(frame.uuid),
+  };
+  let event: RuntimeObservationContent['event'];
+  let status: RuntimeObservationContent['status'] = 'unknown';
+  if (frame.type === 'result') {
+    event = 'request_completed';
+    status =
+      frame.is_error === true ? 'failed' : frame.is_error === false ? 'completed' : 'unknown';
+    native.status = observationField(frame.subtype);
+    if (
+      typeof frame.num_turns === 'number' &&
+      Number.isSafeInteger(frame.num_turns) &&
+      frame.num_turns >= 0
+    ) {
+      native.num_turns = frame.num_turns;
+    }
+  } else if (frame.type === 'system') {
+    switch (frame.subtype) {
+      case 'init':
+        event = 'session_initialized';
+        status = 'initialized';
+        break;
+      case 'hook_started':
+      case 'hook_response':
+        event = frame.subtype === 'hook_started' ? 'hook_started' : 'hook_completed';
+        status =
+          frame.subtype === 'hook_started'
+            ? 'running'
+            : frame.outcome === 'success'
+              ? 'completed'
+              : frame.outcome === 'error'
+                ? 'failed'
+                : frame.outcome === 'cancelled'
+                  ? 'stopped'
+                  : 'unknown';
+        native.hook_id = observationField(frame.hook_id);
+        native.hook_event = observationField(frame.hook_event);
+        native.status = observationField(frame.outcome);
+        break;
+      case 'status':
+      case 'session_state_changed':
+        event = 'session_status';
+        native.status = observationField(frame.status) ?? observationField(frame.state);
+        // Null does not prove the runtime is idle; only explicit known states
+        // can become public statuses.
+        if (
+          native.status === 'compacting' ||
+          native.status === 'running' ||
+          native.status === 'idle'
+        ) {
+          status = native.status;
+        }
+        break;
+      default:
+        return;
+    }
+  } else return;
+  return runtimeObservation(sessionId, {
+    runtime: 'claude-code',
+    source: 'stream_json',
+    event,
+    status,
+    native,
+  });
+}

package/src/spawn-env.ts

@@ -22,6 +22,9 @@ export function buildSpawnEnv(
   const result: NodeJS.ProcessEnv = {
     ...env,
     HOME: claudeHome,
+    // Request native state frames for observation without changing user files.
+    // Preserve an operator's explicit opt-out; older CLIs can ignore the flag.
+    CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: env.CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS ?? '1',
     PRLL_API_URL: context.apiUrl,
     PRLL_API_KEY: context.apiKey,
     PRLL_ORG_ID: context.orgId,