@gajae-code/coding-agent 0.18.5 → 0.18.6

package/CHANGELOG.md

@@ -2,6 +2,107 @@
 
 ## [Unreleased]
 
+## [0.18.6] - 2026-10-03
+
+### Added
+
+- Explicit correlated active-turn steering through coordinator send_prompt, with operator guidance separating requested evidence, queued tasks, and verified consumption. Retargeting feedback to a new active turn requires a new idempotency key; admission still does not prove consumption.
+
+- `gjc sdk diagnostics broker` and the exported `observeExistingBroker` facade now report a real running broker: the broker publishes a startup-fixed diagnostic generation, build snapshot and protocol, and the observation reads the publication only through the approved read-only native lease, opens exactly one client connection with no reconnect attempts, and returns a frozen snapshot with no token, endpoint, path, pid or environment value. An observed result exits 0 and a typed unavailability exits 1.
+
+- `gjc sdk diagnostics broker`: a read-only broker observation route that can never start, ensure, retire, restart or recover a broker. This entry ships the inert public entry, grammar and bounded observation document; the observation reader is wired in the accompanying fragment.
+
+### Changed
+
+- Built-in Codex profiles no longer use GPT-6 Sol or GPT-5.6 Terra. Every role that used `openai-codex/gpt-6-sol` or `openai-codex/gpt-5.6-terra` now uses `openai-codex/gpt-6.1-sol` at the same reasoning effort, so `codex-medium` and `codex-pro` are GPT-6.1 Sol in every role. Affected profiles: `codex-medium`, `codex-pro`, `astra-lite`, `astra-default`, `astra-heavy`, `opus-codex`, `codex-opencodego`, and `fable-opus-codex`. Moving Terra roles onto Sol is an intentional tier change; the catalog price of GPT-6.1 Sol is equal to or below Terra's. The `gpt-6-sol` and `gpt-5.6-terra` catalog entries are unchanged for explicit selection (#6163).
+- `codex-eco` is now `codex-medium` with Sol lowered to `openai-codex/gpt-6-luna` at the same effort, so it uses GPT-6 Luna in every role. Its default, critic, and architect move from GPT-5.6 Terra to GPT-6 Luna (#6163).
+- Roles that moved off GPT-5.6 Terra now compact earlier. GJC forces the Codex GPT-5.6 family to a 372K context window, while GPT-6.1 Sol and GPT-6 Luna use 272K, the window the Codex backend reports for both families (#6163).
+- Installs that load a signed preset registry revision defining these profiles keep that registry binding (built-in, then registry, then user `models.yml`) until a registry revision carries this change (#6163).
+
+- The `gjc` entry module is now inert on import: entry metadata moved to the pure `@gajae-code/utils/cli-metadata` leaf (re-exported from `dirs`), and the effectful bootstrap (startup timing, stderr drainer, malloc re-exec, managed-owner admission, public dispatch, registry) moved to `cli-ordinary` which loads lazily for every non-diagnostics command with unchanged ordering.
+
+### Removed
+
+- Removed the `codex-sol61` built-in profile added in 0.18.2. A saved or requested `codex-sol61` now resolves to `codex-pro`, which differs in two roles: critic is `openai-codex/gpt-6.1-sol:max` instead of `:xhigh`, and architect is `openai-codex/gpt-6.1-sol:xhigh` instead of `openai-codex/gpt-6-astra:xhigh`. Define a custom `codex-sol61` profile in `models.yml` to keep the previous mapping; a user-defined profile takes precedence over the alias (#6163).
+
+### Fixed
+
+- The isolated bash shell supervisor no longer busy-spins while its shell is idle. It reaped adopted zombies by sweeping all of `/proc` every 25 ms without waiting for the previous sweep to finish, which kept each supervisor at about 160% CPU and tens of thousands of context switches per second even during `sleep`. Sweeps now run only on `SIGCHLD`, one at a time, so an idle supervisor stays near 0% CPU (#5972).
+
+- Run compound pipeline stages concurrently to prevent pipe-buffer deadlocks.
+- Join remaining pipeline stages when a stage wait returns an error.
+
+- ACP `session/new` now waits for the model to settle before building the response when `modelRoles.default` is configured but no `--model` is passed. This ensures the `model` config option is always present in the response, preventing ACP clients (like Paseo) from failing with `model_not_selected` on the first prompt when the session uses a configured default model.
+
+- Resuming a session with an unavailable pinned credential no longer aborts when the startup model profile probes that provider; credential failure is reported so the user can re-pin or select AUTO.
+- Resuming a session with an unavailable pinned credential now honors an explicit `--api-key` or a literal `models.yml` `apiKey` when restoring the saved model, the settings default, and extension-registered models, instead of reporting the pin unavailable. An `apiKeyEnv` key does not unblock the pin, because another stored api_key account could take precedence over it; without an explicit key the provider stays blocked until the user re-pins or selects AUTO.
+
+- Windows Telegram daemon stop and reload now wait for the owner-fenced cooperative control request before force escalation, and post-update recovery failures exit cleanly with actionable guidance instead of an uncaught exception (#6138).
+- Added an owner-fenced control wakeup for blocked Telegram polls and extended hard-termination cooperative grace before escalation (#6138).
+
+- A process dying between the POSIX lock-removal detach and payload scrub no longer wedges every subsequent launch with `FileLockAcquireError` ("blocked by abandoned removal transition"): the dead owner's `.lock.removing` transition is reclaimed through the identity-bound guarded removal, and a refused reclamation keeps contending and still reports the abandoned transition at exhaustion (#6253).
+
+- Allow a fresh ACP prompt to wait for a previously failed or cancelled turn to finish winding down before reporting a busy conflict.
+- Admit the next ACP prompt immediately after cancellation settles instead of requiring a retry.
+
+- Scope ACP SDK session-router attachments to sessions owned or being attached by that ACP connection, preventing foreign session hosts from being kept alive.
+
+- Sessions without explicit `retry.*` settings now auto-retry a content-free OpenAI Codex `server_error` / `internal_error` error event, the same way a content-free `server_is_overloaded` event is already retried. Attempts that produced visible output or tool content are still never retried.
+
+- Coordinator MCP: `GJC_COORDINATOR_MCP_ARTIFACT_BYTE_CAP`, `GJC_COORDINATOR_MCP_SESSION_IDLE_TTL_MS` and `GJC_COORDINATOR_MCP_SESSION_SWEEP_INTERVAL_MS` accept only plain decimal digits; values such as `64KB`, `1e6` or `1.5` now fall back to the default instead of being read as their leading digits (`64KB` used to set a 64-byte artifact cap).
+- `gjc setup hermes --artifact-byte-cap` rejects integers above `Number.MAX_SAFE_INTEGER` (for example `9007199254740992` or `1e21`), which it used to write in a form the coordinator then ignored, silently leaving the 64 KiB default in place.
+
+- Report out-of-scope Coordinator evidence paths as invalid input instead of service unavailability, without exposing denied paths. Clarify evidence-root restrictions in the Hermes operator guide.
+
+- Coordinator MCP tool arguments `timeout_ms`, `poll_interval_ms`, `limit` and `lines`, and the `GJC_COORDINATOR_MCP_PROMPT_ACK_TIMEOUT_MS` env value, no longer read a leading digit prefix. A string such as `1e4` or `5s` became a 1 ms or 5 ms wait, and a one-element array such as `[50]` was accepted as `50`; strings must now be plain decimal digits and non-numeric types fall back to the defaults.
+
+- `GJC_COORDINATOR_MCP_EVENT_WEBHOOK_TIMEOUT_MS` and `GJC_COORDINATOR_MCP_EVENT_WEBHOOK_MAX_ATTEMPTS` now accept only plain decimal digits. Values such as `1.5`, `1e4` or `10s` were read as their leading digits, shrinking the per-attempt timeout to 1 ms or the retry budget to a single attempt; they now fall back to the defaults.
+
+- Reject active deep-interview questions missing structured round metadata instead of accepting answers that cannot be recorded, and reject extra interview questions before prompting.
+- Reject empty and whitespace-only ask question bodies, including metadata-free extra questions, in deferred, loaded, and direct execution paths while preserving ordinary multi-question and free-text asks, including next-workflow choices after final-spec handoff.
+
+- Restore cache prefix extension across LLM requests by keeping volatile project context and untrusted MCP server instructions in `agent.state.messages` after they are sent, rather than removing them after each turn. This allows subsequent requests to properly reuse the cache prefix from previous requests, improving cache hit rates and reducing unnecessary re-computation. Volatile ephemeral messages are still excluded from persistent storage as intended. Fixes #6167.
+
+- Gate the statusless typed overload check on `managedOutcome` in `#handleRetryableError` to prevent hanging when a managed fallback chain encounters a transport 503 error followed by a typed Responses overload error. The fix ensures that on the agent_end path, the statusless overload check returns false to allow proper session termination handling instead of deadlocking. Fixes #6180.
+
+- `AgentSession.messages` no longer exposes request-scoped ephemeral messages (`volatile-project-context`, `untrusted-mcp-server-instructions`) that #6167 retains in `agent.state.messages` for prompt-cache prefix reuse. The cache prefix behavior is unchanged; the public view and everything built on it match the pre-#6167 transcript again, which fixes the red `dev` CI in the managed fallback attempt transaction test (#6191).
+
+- Bash commands with auto-background disabled no longer leave the foreground via the timeout fold timer after timing out.
+
+- Lifecycle ledger compaction now evicts only safe settled identities while retaining unbound close replay fences and retirement-source dependencies.
+
+- Context-usage and compaction token estimates count the request-scoped ephemeral messages (`volatile-project-context`, `untrusted-mcp-server-instructions`) that are retained in `agent.state.messages` for prompt-cache reuse. They are hidden from `AgentSession.messages`, so estimating over that public view undercounted the real provider request and could delay auto-compaction until the context window overflowed.
+
+- Recover abandoned parseable lock removal transitions when their owner is proven dead.
+
+- Let SDK steering reach the active worker despite an earlier ordinary ordered control, while waiting behind abort-and-prompt replacements and fencing to the exact runtime command/turn identity so stale feedback is rejected instead of delivered to a successor.
+
+- Return an empty observation for missing assistant text instead of a resource-loss error, including compatibility with older running SDK hosts.
+
+- Stubbed credential-pin methods in the login preset recommendation test mock (follow-up to #6025).
+
+- Keep managed replacement receipts owned by their exact publishing attempt until it settles, preventing concurrent sessions in one workspace from stealing active receipts and failing transcript persistence with `identity_mismatch`. Peer recovery of publisher-bound receipts requires positive owner-exit or PID-reuse evidence; orphan receipt identity checks and external transcript replacement guards remain intact.
+
+- Fixed the resident-cache GC reaping a *running* session's cache on Linux hosts with a slewed wall clock (WSL2 in particular), which replaced tool results with `[Session resident text blob missing: …]` placeholders and logged `Resident cache trust rejection … blob_create_failed ENOENT`. The owner lease recorded the process start from `ps -o lstart`, which procps renders as `btime + ticks` where `btime` is re-derived from the current wall clock minus uptime, so the same live process reported a start time that drifted (observed: 15 minutes over 11 hours) and the sweep read the drift as PID reuse. On Linux the lease now records the `/proc/<pid>/stat` start tick count scoped by the kernel `boot_id` (basis `linux-proc-ticks:<boot_id>`), which never moves for a live process; reuse is only proven when the basis matches, so leases written by older builds or another boot are never reaped while their PID is alive.
+
+- Broker observation refuses everything it cannot prove: a publication without the diagnostic capability is `unsupported` (never `absent` or malformed), only the canonical loopback endpoint with an in-range port is accepted, the broker answers only from an already-owned healthy publication, one monotonic budget covers the whole observation so an expired budget never opens a socket and a late answer is discarded, and malformed arguments raise a typed argument error instead of a fabricated observation.
+
+- The read-only diagnostic addon's trusted digest now travels with the addon through the release path: each build emits a provenance sidecar, consuming jobs rebuild the record from those sidecars against the version actually being shipped, and embedding plus platform-package staging refuse bytes that do not match it.
+
+- Reverted the 0.18.2 readiness-cutoff reaping (#6126) because it left hosts in `terminal_uncertain` under concurrent recovery (#6143); unregistered hosts terminated by a signal at readiness cutoff again report `terminal_uncertain` until the fix re-lands.
+
+- Coordinator MCP: a `GJC_COORDINATOR_MCP_SESSION_SWEEP_INTERVAL_MS` above `2147483647` (about 24.9 days) no longer makes the idle-session reaper sweep continuously. The interval was passed straight to `setTimeout`, which treats longer delays as 1 ms; it is now capped at the timer maximum.
+
+- `gjc ssh add --port` now rejects ports that are not plain digits (`"22oops"`, `"2222.5"`, `"+22"`, `"1e3"`) instead of silently saving the leading digits to `ssh.json`.
+
+- `gjc web-search --limit` now rejects `0` and negative values with an error instead of passing them to providers, where a negative limit silently dropped results from the end of the source list.
+
+- The `web_search` tool schema now declares `limit` and `num_search_results` as positive integers, so a model-supplied `0`, negative or fractional count is rejected at validation instead of reaching providers, where a negative count silently dropped sources from the end of the list.
+
+### Tests
+
+- Add regression test for issue #6004: Verify that after overflow auto-compaction without a continuation scheduled, the session remains usable for subsequent prompts. The test exercises the overflow path to ensure pending agent_end events do not block future prompt submissions (related to #6004).
+
 ## [0.18.5] - 2026-09-30
 
 ## [0.18.4] - 2026-09-30

package/dist/types/cli-commands.d.ts

@@ -0,0 +1,10 @@
+import type { CommandEntry } from "@gajae-code/utils/cli";
+/**
+ * Public-family hooks kept available for private-worker tests without loading the
+ * full registry.
+ *
+ * This is the single shared array: the inert entry (`cli.ts`) and the ordinary
+ * dispatcher (`cli-ordinary.ts`) both re-export THIS object, so a test that
+ * mutates or injects an entry keeps affecting the dispatcher.
+ */
+export declare const commands: CommandEntry[];

package/dist/types/cli-ordinary.d.ts

@@ -0,0 +1,13 @@
+/** Ordinary CLI graph: everything the inert entry must not load eagerly.
+ *
+ * This module owns the effectful bootstrap (startup timing, stderr drainer,
+ * bash-shell worker protocol) plus the unchanged ordinary routing order:
+ * bash-shell workers -> darwin malloc re-exec -> internal smoke -> tmux owner
+ * isolation -> managed-owner supervisor/admission/recovery -> private sdk
+ * stderr drainer -> public family dispatch -> community app -> doctor worker /
+ * probe / cli -> full registry. `cli.ts` imports it lazily, only after argv has
+ * been proven not to be a `sdk diagnostics` observation. */
+import { commands } from "./cli-commands";
+export { commands };
+/** Run every non-diagnostics command with the original admission order. */
+export declare function runOrdinaryCli(argv: string[]): Promise<void>;

package/dist/types/cli.d.ts

@@ -1,6 +1,15 @@
 #!/usr/bin/env bun
-import type { CommandEntry } from "@gajae-code/utils/cli";
-/** Public-family hooks kept available for private-worker tests without loading the full registry. */
-export declare const commands: CommandEntry[];
+/** Inert CLI entry.
+ *
+ * `bin/gjc.js` imports THIS module, so anything statically imported here runs
+ * before argv is inspected. Keep it to pure metadata: the read-only
+ * `sdk diagnostics` observation route must not be able to resolve directories,
+ * consult NSS for a missing/ambiguous HOME, load the native addon, install
+ * runtime globals, re-exec for malloc env vars, run managed-owner admission or
+ * recovery, or touch the error-evidence store. Everything effectful lives in
+ * `./cli-ordinary`, which is imported lazily for every other command with its
+ * original ordering and admission semantics. */
+import { commands } from "./cli-commands";
+export { commands };
 /** Run the CLI with argv excluding process.argv prefix. */
 export declare function runCli(argv: string[]): Promise<void>;

package/dist/types/commands/contribution-prep.d.ts

@@ -3,9 +3,6 @@ export default class ContributionPrep extends Command {
     static description: string;
     static strict: boolean;
     static flags: {
-        "no-spawn": import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
-            description: string;
-        };
         "source-session-id": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
             description: string;
         };

package/dist/types/commands/sdk.d.ts

@@ -132,6 +132,9 @@ export declare function runSessionHost(timing?: {
 export type SdkInternalArgv = {
     action: "broker-internal";
     agentDir: string;
+} | {
+    action: "broker-trampoline-internal";
+    agentDir: string;
 } | {
     action: "session-host-internal";
 } | {

package/dist/types/commands/update.d.ts

@@ -1,4 +1,5 @@
 import { Command } from "@gajae-code/utils/cli";
+export declare function runUpdateRecoveryCommand(recover?: () => Promise<void>): Promise<void>;
 export default class Update extends Command {
     static description: string;
     static flags: {

package/dist/types/config/model-profile-activation.d.ts

@@ -44,6 +44,7 @@ export interface PrepareModelProfileActivationOptions {
     session: ModelProfileActivationSession;
     modelRegistry: Pick<ModelRegistry, "getModelProfile" | "getModelProfiles" | "getAvailableModelProfileNames" | "getApiKeyForProvider" | "getAll" | "resolveCanonicalModel" | "getCanonicalVariants" | "getCanonicalId" | "isSelectorCircuitOpen"> & Partial<Pick<ModelRegistry, "getAvailable" | "getAvailableForProfileActivation" | "resolveModelByLookupAlias" | "lookupAliasExists" | "clearCanonicalVariant" | "seedCanonicalVariant" | "getSessionCanonicalVariant" | "restoreSessionCanonicalVariant" | "getConfiguredProviderIds" | "isKnownProvider">> & {
         getError?: ModelRegistry["getError"];
+        authStorage?: ModelRegistry["authStorage"];
     };
     settings: Pick<Settings, "get" | "getGlobal" | "getOverride">;
     profileName: string;
@@ -129,6 +130,24 @@ export declare class ModelProfileCredentialError extends Error {
     readonly role: string | undefined;
     constructor(profileLabel: string, providers: readonly string[], role?: string);
 }
+interface SessionPinRegistry {
+    authStorage?: {
+        hasRuntimeApiKey(provider: string): boolean;
+        hasLiteralConfigApiKey(provider: string, owner?: object): boolean;
+        hasSessionCredentialUnavailable(provider: string, scopeId?: string): boolean;
+    };
+    getAuthStorageOwner?(): object;
+}
+/**
+ * Whether an unavailable session credential pin blocks `provider`.
+ *
+ * Mirrors `AuthStorage.getApiKey` precedence: a runtime `--api-key` override or a literal
+ * `models.yml` `apiKey` registered for this registry's owner is resolved before the
+ * unavailable-pin marker, so either one keeps the provider usable. An `apiKeyEnv` key does
+ * not: `getApiKey` prefers another stored api_key account over it, which would silently
+ * retarget the unavailable pin.
+ */
+export declare function isSessionCredentialPinBlocking(registry: SessionPinRegistry, provider: string, sessionId: string | undefined): boolean;
 export declare function formatModelProfileCredentialError(profileLabel: string, providers: readonly string[]): string;
 export declare function formatModelProfileUnknownProviderError(profileLabel: string, providers: readonly string[]): string;
 /**

package/dist/types/coordinator-mcp/session-reaper.d.ts

@@ -19,6 +19,11 @@ export declare const DEFAULT_SESSION_IDLE_TTL_MS: number;
 export declare const DEFAULT_SESSION_SWEEP_INTERVAL_MS: number;
 export declare const MIN_SESSION_IDLE_TTL_MS = 60000;
 export declare const MIN_SESSION_SWEEP_INTERVAL_MS = 30000;
+/**
+ * Longest delay setTimeout honors. Bun, like Node, treats any larger delay as 1 ms,
+ * so an operator's very long sweep interval would otherwise re-sweep back to back.
+ */
+export declare const MAX_SESSION_SWEEP_INTERVAL_MS: number;
 /** After this many consecutive reap failures the session is force-evicted from the index. */
 export declare const MAX_REAP_FAILURES = 3;
 /** Minimal projection of a coordinator session the reaper needs to decide. */

package/dist/types/edit/modes/replace.d.ts

@@ -1,8 +1,8 @@
 /**
  * Fuzzy matching utilities for the edit tool.
  *
- * Provides both character-level and line-level fuzzy matching with progressive
- * fallback strategies for finding text in files.
+ * Provides both character-level and line-level fuzzy matching with staged
+ * strategies for finding text in files.
  */
 import type { AgentToolResult } from "@gajae-code/agent-core";
 import * as z from "zod/v4";
@@ -92,7 +92,7 @@ export declare function findClosestSequenceMatch(lines: string[], pattern: strin
  */
 export declare function findContextLine(lines: string[], context: string, startFrom: number, options?: {
     allowFuzzy?: boolean;
-    skipFunctionFallback?: boolean;
+    skipParenRetry?: boolean;
 }): ContextLineResult;
 export declare const replaceEditEntrySchema: z.ZodObject<{
     old_text: z.ZodString;

package/dist/types/edit/streaming.d.ts

@@ -7,7 +7,7 @@
  * - compute unified diff previews for the in-flight args
  *   (`computeDiffPreview`), and
  * - render a text placeholder while no diff exists yet
- *   (`renderStreamingFallback`).
+ *   (`renderStreamingPlaceholder`).
  *
  * The shared renderer / `ToolExecutionComponent` consult the strategy via
  * the injected `editMode` rather than probing argument shape.
@@ -51,7 +51,7 @@ export interface EditStreamingStrategy<Args = unknown> {
      * Rendered inline while the diff hasn't been computed yet (or when the
      * compute returned `null` because args are still too partial).
      */
-    renderStreamingFallback(args: Args, uiTheme: Theme): string;
+    renderStreamingPlaceholder(args: Args, uiTheme: Theme): string;
 }
 export interface EditRequestTargetInventory {
     paths: string[];

package/dist/types/exec/bash-shell-supervisor.d.ts

@@ -1,4 +1,16 @@
+import type { EventEmitter } from "node:events";
 import { type BashShellWorkerResponse } from "./bash-shell-worker-protocol";
+/**
+ * Reap adopted zombies only when the kernel reports a child state change.
+ *
+ * As the Linux child subreaper, the supervisor inherits orphaned descendants
+ * and must reap them, but a full `/proc` sweep is expensive. Polling it on a
+ * short interval kept every idle supervisor busy (issue #5972), so sweeps are
+ * driven by SIGCHLD instead. At most one sweep runs at a time, and a SIGCHLD that
+ * arrives mid-sweep schedules exactly one follow-up so a zombie created after
+ * its `/proc` entry was passed is never missed. Returns the unsubscribe hook.
+ */
+export declare function startLinuxAdoptedZombieReaper(excludedPid: number | undefined, reap?: (excludedPid: number | undefined) => Promise<void>, signals?: Pick<EventEmitter, "on" | "off">): () => void;
 export declare function createUtf8LineDecoder(onLine: (line: string) => void, options?: {
     maxBufferedBytes?: number;
     onOverflow?: () => void;

package/dist/types/sdk/broker/discovery.d.ts

@@ -36,6 +36,14 @@ export interface BrokerDiscovery {
     ownerId: string;
     pid: number;
     incarnation: string;
+    /**
+     * Public publication-incarnation id for diagnostic observation, fixed at startup.
+     * Absent on publications written before the capability existed; an observer then
+     * reports `unsupported` instead of synthesizing compatibility.
+     */
+    diagnosticGeneration?: string;
+    /** Diagnostic protocol the publisher answers; absent means no capability. */
+    diagnosticProtocol?: number;
     host: "127.0.0.1";
     port: number;
     url: string;

package/dist/types/sdk/broker/ensure.d.ts

@@ -139,6 +139,7 @@ interface BrokerOwner {
     stop(): Promise<void>;
     canReuse(discovery: BrokerDiscovery | null): boolean;
     markReady(discovery: BrokerDiscovery): boolean;
+    setTarget(pid: number, incarnation: string): void;
 }
 interface ReapTiming {
     gracefulMs: number;

package/dist/types/sdk/broker/lifecycle-ledger.d.ts

@@ -61,6 +61,8 @@ export interface LifecycleDurableEffectsReceipt {
 export interface LifecycleLedgerEntry {
     operationKey?: string;
     fingerprint?: string;
+    /** True only when a session.close request supplied immutable generation authority. */
+    closeAuthorityBound?: boolean;
     version: typeof SDK_STATE_VERSION;
     identity: string;
     requestHash: string;
@@ -158,12 +160,14 @@ export declare class LifecycleLedger {
     migrateIdentity(from: string, to: string, metadata: {
         operationKey: string;
         fingerprint: string;
+        closeAuthorityBound?: boolean;
     }): Promise<LifecycleLedgerEntry | undefined>;
     get warnings(): readonly string[];
     begin(identity: string, requestHash: string, metadata?: {
         operationKey?: string;
         fingerprint?: string;
         intendedSessionId?: string;
+        closeAuthorityBound?: boolean;
     }): Promise<BeginResult>;
     transition(identity: string, state: LifecycleState, fields?: Omit<Partial<LifecycleLedgerEntry>, "identity" | "requestHash" | "state" | "ts">): Promise<LifecycleLedgerEntry>;
     assertSupportedStateVersions(): Promise<void>;

package/dist/types/sdk/broker/runtime.d.ts

@@ -1,4 +1,4 @@
-export type SdkInternalAction = "broker-internal" | "session-host-internal" | "stderr-drain-internal";
+export type SdkInternalAction = "broker-internal" | "broker-trampoline-internal" | "session-host-internal" | "stderr-drain-internal";
 export type SdkInternalSpawnCommand = {
     kind: "bun-source";
     file: string;

package/dist/types/sdk/bus/telegram-daemon-contract.d.ts

@@ -292,7 +292,7 @@ export declare const SDK_LIFECYCLE_ROUTER_PROTOCOL_VERSION = 1;
  * Generation 193 gates streamed content on negotiated observer capabilities,
  * so existing owners are replaced before exposing the new observer path.
  */
-export declare const DAEMON_GENERATION = 199;
+export declare const DAEMON_GENERATION = 200;
 /**
  * Serving-compatibility boundary for daemon lifecycle requests. Epoch 7
  * requires durable publication receipts and acknowledged attachment dispatch,

package/dist/types/sdk/bus/telegram-daemon.d.ts

@@ -1181,4 +1181,5 @@ export declare class TelegramNotificationDaemon {
     run(): Promise<void>;
     /** True when a signal-driven stop or an owner-scoped control request asks the loop to exit. */
     private controlStopRequested;
+    private checkControlStopRequested;
 }

package/dist/types/sdk/cli/diagnostics-cli.d.ts

@@ -0,0 +1,18 @@
+/** Isolated `gjc sdk diagnostics` parser and renderer.
+ *
+ * Reached from the inert entry before any effectful branch, so this module must
+ * stay a pure leaf: no command registry, session CLI, runtime globals, managed
+ * owner admission, malloc guard, evidence publisher, broker client, directory
+ * resolver or logger import. Help and usage never resolve a root or open a file,
+ * and every outcome is a fixed bounded string with a fixed exit code.
+ *
+ * Observation itself must never start, ensure, retire, restart or recover a
+ * broker. The read-only observation facade (DESIGN §B3) is wired: `observe()`
+ * below routes to it and to nothing else, so this command can report only what a
+ * supporting broker publishes to the read-only reader. An unsupported runtime
+ * tuple, a missing or mismatched native artifact and an old broker without a
+ * published generation all still fail closed with the fixed `unsupported`
+ * outcome.
+ */
+/** Run `gjc sdk diagnostics <argv…>`; argv excludes the `sdk diagnostics` prefix. */
+export declare function runDiagnosticsCli(argv: readonly string[]): Promise<void>;

package/dist/types/sdk/diagnostics/observe-broker.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Observation-only broker diagnostics facade (SPEC "Result contract").
+ *
+ * The publication is read ONLY through the approved read-only native lease
+ * (`loadDiagnosticNativeReadOnly` -> `openDiagnosticSnapshot` -> bounded read ->
+ * revalidate -> close), so every ancestor ACL/owner/mode and filesystem check of the
+ * earlier slices governs this route too. Ordinary discovery is deliberately not used: it
+ * would bypass that gate. An unsupported runtime tuple or artifact resolves to
+ * `unsupported` BEFORE any publication access. The facade then opens exactly ONE client
+ * connection with no reconnect attempts, asks the broker for its published diagnostics
+ * and returns a detached frozen snapshot. It never ensures, starts, recovers, retires or spawns
+ * anything, never touches the session index, ledger or evidence store, and never hands
+ * the caller a token, socket coordinate, path, pid or environment value.
+ */
+/** Allowed unavailability reasons; messages are fixed literals keyed by the enum. */
+export type BrokerObservationUnavailableReason = "absent" | "stale" | "incompatible" | "authentication_failed" | "unsupported" | "generation_mismatch" | "transport_unavailable" | "timeout" | "invalid_response" | "unsafe_discovery";
+export interface BrokerObservationBuild {
+    readonly packageVersion: string;
+    readonly buildId: string | null;
+}
+export interface BrokerObservationSuccess {
+    readonly schema: "gjc.broker-observation";
+    readonly version: 1;
+    readonly ok: true;
+    readonly observedAt: string;
+    readonly broker: {
+        readonly generation: string;
+        readonly build: BrokerObservationBuild;
+        readonly diagnosticProtocol: 1;
+    };
+}
+export interface BrokerObservationUnavailable {
+    readonly schema: "gjc.broker-observation";
+    readonly version: 1;
+    readonly ok: false;
+    readonly observedAt: string;
+    readonly unavailable: {
+        readonly reason: BrokerObservationUnavailableReason;
+        readonly message: string;
+    };
+}
+export type BrokerObservation = BrokerObservationSuccess | BrokerObservationUnavailable;
+export interface ObserveExistingBrokerOptions {
+    readonly agentDir: string;
+    readonly expectedGeneration?: string;
+    readonly timeoutMs?: number;
+}
+/** The broker's published diagnostics operation. */
+export declare const BROKER_DIAGNOSTICS_OPERATION = "broker.diagnostics";
+/** The only diagnostic protocol this client understands. */
+export declare const BROKER_DIAGNOSTIC_PROTOCOL = 1;
+/** Contract timeout: default 2000 ms, accepted range 1..10000 ms. */
+export declare const OBSERVATION_TIMEOUT_DEFAULT_MS = 2000;
+export declare const OBSERVATION_TIMEOUT_MIN_MS = 1;
+export declare const OBSERVATION_TIMEOUT_MAX_MS = 10000;
+export declare function setObservationClockForTest(clock: (() => number) | null): void;
+/**
+ * Test-only observers for the native stage boundary. Production installs none, and the
+ * hooks never change a branch, a budget or an outcome: they only report what the
+ * observation did (`onNativeOpen`) and give a test a point to disturb the environment
+ * between the first publication read and the connection (`afterInitialRead`), which is how
+ * the pre-socket identity recheck is proven instead of argued.
+ */
+export interface ObservationTestHooks {
+    onNativeOpen?: (info: {
+        agentDir: string;
+        budgetMs: number;
+    }) => void;
+    afterInitialRead?: () => void;
+    /** Reports that the retained lease was released, on every exit path. */
+    onLeaseClosed?: () => void;
+    /**
+     * Decorates the retained lease so a test can identify the real operation phases and make
+     * a chosen phase refuse or throw. Production installs none.
+     */
+    wrapLease?: (lease: DiagnosticSnapshotLease) => DiagnosticSnapshotLease;
+    /** Replaces the loader result so loader-stage outcomes can be observed deterministically. */
+    loaderOverride?: () => DiagnosticNativeLoad;
+}
+/** Minimal shapes this facade relies on from the approved read-only loader. */
+interface DiagnosticSnapshotRead {
+    readonly ok: boolean;
+    readonly reason?: string | null;
+    readonly bytes?: Uint8Array | null;
+}
+interface DiagnosticSnapshotStatus {
+    readonly ok: boolean;
+    readonly reason?: string | null;
+}
+interface DiagnosticSnapshotLease {
+    readonly ok: boolean;
+    readonly reason?: string | null;
+    read(): DiagnosticSnapshotRead;
+    revalidate(): DiagnosticSnapshotStatus;
+    close(): void;
+}
+type DiagnosticNativeLoad = {
+    ok: true;
+    value: {
+        openDiagnosticSnapshot(agentDir: string, budgetMs: number): DiagnosticSnapshotLease;
+    };
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function setObservationTestHooksForTest(hooks: ObservationTestHooks | null): void;
+/** Malformed arguments are a typed caller error, never an observed unavailability. */
+export declare class DiagnosticOptionsError extends Error {
+    readonly code: "invalid_arguments";
+    readonly field: string;
+    constructor(field: string);
+}
+export type ObservationOptionsVerdict = {
+    ok: true;
+    value: {
+        agentDir: string;
+        expectedGeneration?: string;
+        timeoutMs: number;
+    };
+} | {
+    ok: false;
+    error: {
+        code: "invalid_arguments";
+        field: string;
+    };
+};
+/** Validate the caller's options against the exact contract. Pure and total. */
+export declare function validateObservationOptions(options: unknown): ObservationOptionsVerdict;
+/** Whether the endpoint is the canonical owned loopback endpoint with an in-range port. */
+export declare function canonicalLoopbackEndpoint(url: string): boolean;
+/**
+ * Parse verdicts for the publication bytes. A publication that is well formed but
+ * carries no diagnostic capability is NOT malformed: an old broker like that is
+ * `unsupported`, never `invalid_response` and never `absent`.
+ */
+export type PublicationVerdict = {
+    kind: "ok";
+    value: ObservedPublication;
+} | {
+    kind: "no-capability";
+} | {
+    kind: "malformed";
+};
+/** The publication fields this route reads; every other field is ignored, never trusted. */
+export interface ObservedPublication {
+    readonly url: string;
+    readonly token: string;
+    readonly ownerId: string;
+    readonly pid: number;
+    readonly incarnation: string | null;
+    readonly agentRoot: string | null;
+    readonly generation: string;
+    readonly diagnosticProtocol: number;
+}
+/** Parse the publication bytes the native lease returned. Strict, bounded, total. */
+export declare function parsePublicationVerdict(bytes: Uint8Array): PublicationVerdict;
+/** Convenience wrapper for callers that only need the accepted shape. */
+export declare function parsePublication(bytes: Uint8Array): ObservedPublication | null;
+/** The exact answered payload this client accepts; unknown fields are refused. */
+interface AnsweredDiagnostics {
+    readonly generation: string;
+    readonly build: BrokerObservationBuild;
+    readonly identity: {
+        readonly ownerId: string;
+        readonly pid: number;
+        readonly agentRoot: string;
+    };
+}
+/** Strictly validate the broker's answer, mapping every refusal onto the reason enum. */
+export declare function parseAnsweredDiagnostics(response: unknown): {
+    kind: "ok";
+    value: AnsweredDiagnostics;
+} | {
+    kind: "unavailable";
+    reason: BrokerObservationUnavailableReason;
+};
+/** Two publication observations describe the same authority. */
+export declare function sameAuthority(first: ObservedPublication, second: ObservedPublication): boolean;
+/** The broker's answer agrees with the publication on generation and identity. */
+export declare function answerMatchesAuthority(answer: AnsweredDiagnostics, publication: ObservedPublication): boolean;
+/**
+ * Observe an already running broker. Never starts, ensures, recovers or retires one.
+ */
+export declare function observeExistingBroker(options: ObserveExistingBrokerOptions | unknown): Promise<BrokerObservation>;
+export {};

package/dist/types/sdk/host/control/operations.d.ts

@@ -20,7 +20,7 @@ export type ControlInput = Record<string, unknown>;
  */
 export interface ControlSurface {
     prompt(text: string, images?: ControlValue, clientRef?: string): Promise<ControlValue> | ControlValue;
-    steer(text: string, clientRef?: string): Promise<ControlValue> | ControlValue;
+    steer(text: string, clientRef?: string, expectedSdkRunToken?: string): Promise<ControlValue> | ControlValue;
     followUp(text: string): Promise<ControlValue> | ControlValue;
     abort(): Promise<ControlValue> | ControlValue;
     /** Terminal abort: stop the current root turn (and optionally exact owned work). */

package/dist/types/sdk/index.d.ts

@@ -1,6 +1,7 @@
 export { MODEL_PROFILE_DISCOVERY_QUERY, MODEL_PROFILE_ERROR_DETAIL_MAX_BYTES, type ModelProfileCatalogItem, type ModelProfileErrorCode, type ModelProfileErrorDetails, ModelProfileRegistryError, type ModelProfileRegistryErrorDetails, type UnknownModelProfileDetails, UnknownModelProfileError, } from "../config/model-profile-contract";
 export type { QueuedInputAdmission, QueuedInputDelivery, QueuedInputExecution, QueuedInputQueuePolicy, QueuedInputRemovalReason, QueuedInputSubmission, QueuedInputTerminal, SendUserMessageOptions, TrackedSendUserMessageOptions, } from "../session/agent-session";
 export * as bus from "./bus";
+export * from "./diagnostics/observe-broker";
 export * as host from "./host";
 export * as lifecycle from "./lifecycle";
 export * as mcp from "./mcp";

package/dist/types/sdk/router/session-router.d.ts

@@ -177,6 +177,8 @@ export interface SessionRouterOptions {
     agentDir: string;
     /** Limits attachment to exact ids selected by a Broker-scoped operation. */
     sessionIds?: readonly string[];
+    /** Dynamically limits attachment to sessions currently owned by the caller. */
+    attachFilter?: (sessionId: string) => boolean;
     /** Marks default SDK clients as notification-only observers; demanding by default. */
     observer?: boolean;
     deps?: SessionRouterDeps;

package/dist/types/sdk/session.d.ts

@@ -188,6 +188,12 @@ export interface CreateAgentSessionOptions {
      * @internal CLI-only ordering guard; SDK callers retain immediate startup by default.
      */
     deferMemoryBackendStartup?: boolean;
+    /**
+     * Skip optional model-catalog discovery during lifecycle startup. ACP hosts must
+     * publish their endpoint before unrelated provider credential refreshes begin.
+     * @internal lifecycle-only startup guard.
+     */
+    deferOptionalModelRefresh?: boolean;
     /** Enable LSP integration (tool, formatting, diagnostics, warmup). Default: true */
     enableLsp?: boolean;
     /** Skip Python kernel availability check and prelude warmup */
@@ -297,6 +303,13 @@ export interface CreateAgentSessionResult {
      */
     gjcRuntimeSnapshot?: GjcRuntimeSnapshotProvider;
 }
+/**
+ * Start optional provider/model discovery only when it is safe to add work to
+ * the caller's startup graph. Lifecycle hosts deliberately skip this during
+ * construction: discovery preflights every configured provider and may refresh
+ * an unrelated OAuth credential while several hosts are opening the same DB.
+ */
+export declare function startOptionalModelRefresh(modelRegistry: Pick<ModelRegistry, "refreshInBackground">, credentialSessionId: string | undefined, deferred: boolean): boolean;
 export interface DeferredMcpConfigStartupResult {
     loadedToolCount: number;
     hasErrors: boolean;