@gajae-code/coding-agent 0.18.11 → 0.19.0

package/dist/types/runtime-mcp/content-limits.d.ts

@@ -1,4 +1,8 @@
 export declare const MCP_MAX_CONTENT_BYTES: number;
+export declare const MCP_MAX_IMAGES = 16;
+export declare const MCP_MAX_IMAGE_SOURCE_DIMENSION = 8192;
+export declare const MCP_MAX_IMAGE_SOURCE_PIXELS = 16000000;
+export declare const MCP_MAX_IMAGE_OUTPUT_BYTES: number;
 export declare const MCP_MAX_ERROR_BYTES: number;
 export declare const MCP_MAX_SSE_REQUEST_MESSAGES = 1024;
 export declare const MCP_MAX_SSE_BATCH_MESSAGES = 1024;

package/dist/types/runtime-mcp/manager.d.ts

@@ -71,6 +71,8 @@ export interface MCPToolCatalogSnapshot {
     publication: MCPToolCatalogPublication;
     generation: number;
 }
+/** Drop project stdio servers unless the user/global opt-in is set. */
+export declare function omitUnapprovedProjectStdio(configs: Record<string, MCPServerConfig>, sources: Record<string, SourceMeta>, allowProjectStdio: boolean, toolsOnly?: boolean): void;
 /** Options for discovering and connecting to MCP servers */
 export interface MCPDiscoverOptions {
     /** Whether to load project-level config (default: true) */
@@ -97,6 +99,11 @@ export interface MCPDiscoverOptions {
 export interface MCPManagerOptions {
     /** Restrict this instance to tools from an explicit MCP config. */
     toolsOnly?: boolean;
+    /**
+     * Spawn stdio servers loaded from a project MCP file. Default false.
+     * User-scope servers and an explicit `--mcp-config` file are unaffected.
+     */
+    allowUntrustedProjectStdio?: boolean;
     /**
      * Ceiling for the startup wait, in milliseconds. ACP lifecycle launches and
      * plugin MCP startup use bounded caller-owned budgets; other consumers keep

package/dist/types/runtime-mcp/plugin-mcp-name-filter.d.ts

@@ -0,0 +1,22 @@
+export declare const GJC_PLUGIN_MCP_PROVIDER = "gjc-plugins";
+/**
+ * A repository plugin MCP server must not occupy a normalized tool name that a
+ * non-plugin server already published. The whole plugin server is omitted so a
+ * sibling tool from that server is not left registered. Non-plugin collisions
+ * and the input order stay unchanged.
+ */
+export declare function omitPluginMcpNameShadows<T extends {
+    name: string;
+}>(tools: readonly T[]): T[];
+/** Normalized names of plugin tools that remain after shadow omission. */
+export declare function survivingPluginMcpToolNames<T extends {
+    name: string;
+}>(tools: readonly T[]): string[];
+/**
+ * The required-name list is the plugin tools that survived the name filter,
+ * plus requested names this batch did not omit. An omitted plugin tool, including
+ * a sibling that does not itself collide, is not required.
+ */
+export declare function retainPluginMcpMandatoryNames(tools: readonly {
+    name: string;
+}[], requested: readonly string[]): string[];

package/dist/types/runtime-mcp/project-host-values.d.ts

@@ -2,14 +2,20 @@
  * Host-value policy for MCP config that comes from an untrusted project file.
  *
  * User mcp.json and an explicit `--mcp-config` file may still substitute
- * secret-named environment variables and run `!` shell commands. A project
- * file (native `.gjc/mcp.json` or a repo-root `mcp.json`) uses the same
- * sensitive-name rule as project `ssh.json`: do not copy those host values
- * into server env or headers, and do not execute `!`.
+ * secret-named environment variables and run `!` shell commands. Any
+ * project-level source, including providers other than native `.gjc/mcp.json`
+ * and repo-root `mcp.json`, uses the same sensitive-name rule as project
+ * `ssh.json`: do not copy those host values into server env or headers, and
+ * do not execute `!`.
  */
 import type { SourceMeta } from "../capability/types";
 export declare function nativeMcpSource(level: "user" | "project", filePath: string): SourceMeta;
-/** True when this server was loaded from untrusted project MCP config. */
+/**
+ * True when this server was loaded from untrusted project MCP config.
+ * Every project-level provider is untrusted, including providers other than
+ * native `.gjc/mcp.json` and repo-root `mcp.json`. User scope and a tools-only
+ * load stay on the previous path.
+ */
 export declare function isUntrustedProjectMcpSource(source: SourceMeta | undefined, toolsOnly: boolean): boolean;
 export type ProjectHostValueDecision = {
     action: "resolve";

package/dist/types/runtime-mcp/tool-bridge.d.ts

@@ -72,6 +72,8 @@ export declare class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
     readonly mcpToolName: string;
     /** Server name */
     readonly mcpServerName: string;
+    /** True when this tool came from a repository GJC plugin bundle. */
+    readonly gjcPluginBundle: boolean;
     private connection;
     invalidateForSessionControl(): void;
     /** Create MCPTool instances for all tools from an MCP server lease/connection. */
@@ -98,6 +100,8 @@ export declare class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetai
     readonly mcpToolName: string;
     /** Server name */
     readonly mcpServerName: string;
+    /** True when this tool came from a repository GJC plugin bundle. */
+    readonly gjcPluginBundle: boolean;
     invalidateForSessionControl(): void;
     /** Create DeferredMCPTool instances for all tools from an MCP server */
     static fromTools(serverName: string, tools: MCPToolDefinition[], getConnection: () => Promise<MCPServerConnection>, source?: SourceMeta, reconnect?: MCPReconnect, options?: MCPToolOptions): DeferredMCPTool[];

package/dist/types/sdk/broker/broker-exit.d.ts

@@ -4,7 +4,7 @@ export type { BrokerExitWriterTestBarrier } from "./broker-exit-writer-worker";
 export declare function setBrokerExitWriterBarrierForTest(barrier?: BrokerExitWriterTestBarrier): void;
 export type BrokerExitMode = "owned-root" | "lost-root";
 export type BrokerFenceReason = "suspect-unpublished" | "observation-ambiguous" | "heartbeat-ambiguous";
-export type BrokerExitReason = "ownership-fence-expired" | "publication-liveness-timeout" | "heartbeat-renewal-blocked" | "restart-committed" | "shutdown-request" | "startup-failure" | "signal";
+export type BrokerExitReason = "ownership-fence-expired" | "publication-liveness-timeout" | "heartbeat-renewal-blocked" | "restart-committed" | "shutdown-request" | "startup-failure" | "abandoned" | "signal";
 export type BrokerStopRequest = {
     kind: "shutdown-request";
 } | {
@@ -29,7 +29,7 @@ export interface BrokerExitRecord {
 export interface BrokerStartupExitRecord {
     version: 1;
     mode: "startup";
-    reason: "startup-deadline" | "startup-signal" | "startup-lock-blocked";
+    reason: "startup-deadline" | "startup-signal" | "startup-lock-blocked" | "startup-lock-unavailable";
     fenceReason: null;
     fencedForMs: 0;
     uptimeMs: number;
@@ -38,7 +38,7 @@ export interface BrokerStartupExitRecord {
     exitCode: 1 | 130 | 143;
     timeoutMs: number | null;
     writtenAt: number;
-    /** For lock-blocked reason: path to the retained removal transition. */
+    /** For lock refusal reasons: path to the transition or lock that blocked startup. */
     blockingLockPath?: string;
 }
 export type BrokerStartupExitWriteStatus = {

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

@@ -1,4 +1,4 @@
-import type { NativeDirectoryTreeSnapshot } from "@gajae-code/natives";
+import { type NativeDirectoryTreeSnapshot } from "@gajae-code/natives";
 import type { ModelProfileErrorDetails } from "../../config/model-profile-contract";
 import type { TaskArtifactOwnerDeletionEvidence, TaskArtifactOwnerRetirementContinuation } from "../../session/task-artifact-owner-codec";
 import { type SdkHostModelResolver } from "../host/model-pin";
@@ -26,6 +26,21 @@ export interface BrokerSettings {
     masterCapabilityVerifier?: MasterCapabilityVerifier;
     /** Grace before an orphaned spawn child closes; schema-bounded in production. */
     masterOrphanGraceMs?: number;
+    /**
+     * Grace before a broker nobody is left to use exits on its own. The clock only
+     * runs while the index proves no live session host and no open spawn authority,
+     * so a broker whose client died without closing exits instead of holding its
+     * port, its publication, and its lock for the life of the machine.
+     */
+    abandonedGraceMs?: number;
+    /**
+     * Whether this broker may end itself once nobody is left to use it. Only the
+     * detached autostart entry point enables this: an operator-supervised
+     * `gjc sdk broker run` service owns its own lifetime, and its supervisor reads an
+     * owned-root completion as a clean exit, so self-reaping would quietly retire a
+     * service that was meant to keep serving.
+     */
+    reapWhenAbandoned?: boolean;
     /** Host model resolver override for lifecycle tests and embedders. */
     resolveModelPin?: SdkHostModelResolver;
     /**
@@ -62,10 +77,12 @@ type ResolvedBrokerSettings = {
     spawnSubstrateProvider?: SpawnSubstrateProvider;
     spawnPromptLayer?: SpawnPromptLayer;
     masterOrphanGraceMs: number;
+    abandonedGraceMs: number;
+    reapWhenAbandoned: boolean;
     restartRequestId?: string;
 };
 export declare function resolveBrokerPackageGeneration(): string;
-export type BrokerErrorCode = "idempotency_conflict" | "terminal_uncertain" | "broker_restarting" | "unavailable" | "endpoint_stale" | "resource_gone" | "invalid_input" | "spawn_failed" | "ready_then_exited" | "endpoint_unreadable" | "startup_admission_timeout" | "startup_admission_refused" | "readiness_timeout" | "worktree_preparation_timeout" | "dependency_preparation_timeout" | "worktree_in_use" | "incarnation_unavailable" | "close_refused" | "not_found" | "live_session" | "cleanup_pending" | (string & {});
+export type BrokerErrorCode = "idempotency_conflict" | "legacy_lifecycle_ambiguous" | "terminal_uncertain" | "broker_restarting" | "unavailable" | "endpoint_stale" | "resource_gone" | "invalid_input" | "spawn_failed" | "ready_then_exited" | "endpoint_unreadable" | "startup_admission_timeout" | "startup_admission_refused" | "readiness_timeout" | "worktree_preparation_timeout" | "dependency_preparation_timeout" | "worktree_in_use" | "incarnation_unavailable" | "close_refused" | "not_found" | "live_session" | "cleanup_pending" | (string & {});
 export type BrokerCleanupIdentity = {
     dev: string;
     ino: string;
@@ -283,6 +300,7 @@ export declare function reapStaleBrokerLockArtifacts(input: {
     now?: number;
     graceMs?: number;
     pidAlive?: (pid: number) => boolean;
+    processIncarnation?: (pid: number) => string | undefined;
 }): Promise<BrokerLockArtifactReapResult>;
 export interface StartupAdmissionTiming {
     now(): number;
@@ -372,6 +390,8 @@ export declare class Broker {
     runStartup<T>(queueWaitMs: number, timing: StartupAdmissionTiming, task: (admittedAt: number) => Promise<T>): Promise<StartupAdmissionResult<T>>;
     start(): Promise<BrokerDiscovery>;
     get ownsDiscovery(): boolean;
+    /** Whether this broker completed its initial retained discovery publication. */
+    get hasPublishedDiscovery(): boolean;
     get completion(): Promise<void>;
     /** Why this broker completed, or null while it is still running. */
     get terminalExit(): {
@@ -412,6 +432,13 @@ export declare function setTerminalPersistenceHookForTest(broker: Broker, hook:
 export declare function setAmbiguityGraceForTest(broker: Broker, graceMs: number | undefined): void;
 /** Test-only hook for shortening the startup lock-artifact reap bound. */
 export declare function setLockArtifactGraceForTest(broker: Broker, graceMs: number | undefined): void;
+/** Test-only barriers for exercising the cross-process broker-lock reclaim fence. */
+export declare function setBrokerLockReclaimHooksForTest(broker: Broker, hooks: {
+    beforeQuarantine?: () => Promise<void>;
+    onContended?: () => void;
+} | undefined): void;
+/** Test-only hook for shortening the bounded abandonment grace. */
+export declare function setAbandonedGraceForTest(broker: Broker, graceMs: number | undefined): void;
 /** Test-only hook for shortening the bounded liveness deadline. */
 export declare function setLivenessGraceForTest(broker: Broker, graceMs: number | undefined): void;
 /** Test-only hook for shortening the bounded wait before a deferred managed close is queued. */

package/dist/types/sdk/broker/daemon-entry.d.ts

@@ -1,4 +1,6 @@
+import type * as childProcess from "node:child_process";
 import { type BrokerDiscovery } from "./discovery";
+import { type BrokerLaunchHandoff, type BrokerLaunchResult } from "./ensure";
 export interface AuthorizedBrokerSuccessorOptions {
     agentDir: string;
     requestId: string;
@@ -11,10 +13,14 @@ export type AuthorizedBrokerSuccessorResult = {
     discovery: BrokerDiscovery;
 } | {
     kind: "spawned";
+    child: childProcess.ChildProcess;
+    realBrokerPid: number | undefined;
+    realBrokerIncarnation: string | undefined;
+    handoff: BrokerLaunchHandoff | undefined;
     discovery: BrokerDiscovery;
 } | {
     kind: "refused";
-    reason: "deadline_elapsed" | "intent_not_committed" | "spawn_failed" | "spawn_exited_before_publication" | "publication_timeout";
+    reason: "deadline_elapsed" | "intent_not_committed" | "spawn_failed" | "spawn_exited_before_publication" | "publication_timeout" | "startup_lock_unavailable";
     detail?: string;
 };
 /**
@@ -30,6 +36,10 @@ export type AuthorizedBrokerSuccessorResult = {
  * has been released.
  */
 export declare function launchAuthorizedBrokerSuccessor(options: AuthorizedBrokerSuccessorOptions): Promise<AuthorizedBrokerSuccessorResult>;
+/** Test hook: retries exact cleanup before mapping a launch error to refusal. */
+export declare function refuseFailedBrokerLaunchForTest(launched: BrokerLaunchResult): Promise<Extract<AuthorizedBrokerSuccessorResult, {
+    kind: "refused";
+}>>;
 /**
  * Positive OS-confirmed absence of the exact prior owner, distinguished from
  * every merely-inconclusive outcome (permission denial, PID reuse ambiguity,

package/dist/types/sdk/broker/doctor-restart.d.ts

@@ -44,7 +44,7 @@ export type DoctorBrokerRestartOutcome = {
     kind: "successor_refused";
     requestId: string;
     oldOwner: BrokerRestartOwnerIdentity;
-    reason: "deadline_elapsed" | "intent_not_committed" | "spawn_failed" | "spawn_exited_before_publication" | "publication_timeout";
+    reason: "deadline_elapsed" | "intent_not_committed" | "spawn_failed" | "spawn_exited_before_publication" | "publication_timeout" | "startup_lock_unavailable";
     detail?: string;
 };
 export declare function prepareDoctorBrokerRestart(client: SdkClient, discovery: BrokerDiscovery, options: DoctorBrokerRestartOptions & {

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

@@ -1,9 +1,102 @@
 import { type ChildProcess } from "node:child_process";
 import type { FileHandle } from "node:fs/promises";
+import { type ProjectEnvSnapshot } from "@gajae-code/utils/env-file";
 import { type FileLockOptions } from "../../config/file-lock";
+import { type BrokerStartupExitRecord } from "./broker-exit";
 import { type BrokerDiscovery } from "./discovery";
+import { type ProcessIncarnationObservation } from "./process-incarnation";
 import { type SdkInternalSpawnCommand } from "./runtime";
 import { type BrokerStartupFailureMarker } from "./startup-failure";
+/** Result of launching a broker through a hop/trampoline or as an exact fixture child. */
+export interface BrokerSpawnResult {
+    /** The launcher process, or the exact broker process for fixture leases. */
+    process: ChildProcess;
+    /** The real broker's pid (from the launcher reply or exact child). */
+    realBrokerPid: number | undefined;
+    /** Kernel identity returned by the POSIX trampoline when available. */
+    realBrokerIncarnation?: string;
+    handoff?: BrokerLaunchHandoff;
+}
+export interface BrokerLaunchHandoff {
+    release(): Promise<void>;
+    terminate(): Promise<void>;
+}
+/**
+ * Typed error returned when a Windows broker hop fails.
+ * The hop is mandatory on Windows for broker detachment; failure is unrecoverable.
+ */
+export declare class BrokerHopError extends Error {
+    readonly code = "broker_hop_failed";
+    readonly hopExitCode: number | null;
+    readonly hopStdout: string;
+    readonly hopStderr: string;
+    readonly reason: string;
+    constructor(fields: {
+        exitCode: number | null;
+        stdout: string;
+        stderr: string;
+        reason: string;
+    });
+}
+export declare function resolveBrokerLaunchMode(platform: NodeJS.Platform, initiator: "discovery" | "fixture-lease"): "windows-hop" | "posix-trampoline" | "darwin-trampoline" | "direct";
+/** What the parent sends the Windows hop. The broker environment is never serialized here. */
+export interface BrokerHopMessage {
+    command: {
+        file: string;
+        args: string[];
+    };
+    cwd?: string;
+    /** Path (never an inherited fd number) the hop opens for the broker's stderr. */
+    stderrLogPath?: string;
+}
+export interface BrokerLaunchResult {
+    process: ChildProcess;
+    realBrokerPid: number | undefined;
+    realBrokerIncarnation?: string;
+    error: Error | undefined;
+    handoff?: BrokerLaunchHandoff;
+}
+/** Test hook: proves a stuck launcher is terminated at its deadline. */
+export declare function awaitBrokerLauncherForTest(child: ChildProcess, timeoutMs: number, onTimeout?: () => void): Promise<{
+    kind: "closed";
+} | {
+    kind: "timeout";
+    terminated: boolean;
+}>;
+/**
+ * Windows only: launch the broker through the internal hop and await its reply.
+ *
+ * `taskkill /T /F` walks ParentProcessId, so a broker spawned directly by the client
+ * dies with it even when detached. The hop spawns the broker and exits after
+ * the parent acknowledges the complete reply, leaving the broker without a
+ * live parent in the client's tree. The broker inherits the environment set on
+ * the hop, never passed on the command line; stderr is passed as a path because
+ * a parent fd number does not exist inside the hop.
+ */
+export declare function launchBrokerViaHop(message: BrokerHopMessage, options: {
+    env: NodeJS.ProcessEnv;
+    cwd?: string;
+    timeoutMs?: number;
+}): Promise<BrokerLaunchResult>;
+/** Parses the hop's single-line pid/incarnation reply into broker identity or a typed error. */
+export declare function parseBrokerHopReply(code: number | null, stdout: string, spawnError?: Error, stderr?: string): {
+    realBrokerPid: number | undefined;
+    realBrokerIncarnation?: string;
+    error: Error | undefined;
+};
+/** POSIX only: the trampoline holds its exact broker child until the publication decision. */
+export declare function launchBrokerViaPosixTrampoline(agentDir: string, options: {
+    env: NodeJS.ProcessEnv;
+    cwd?: string;
+    stderrFd?: number;
+    timeoutMs?: number;
+    retainChildUntilPublication?: boolean;
+}): Promise<BrokerLaunchResult>;
+export declare function parseBrokerTrampolineReply(code: number | null, stdout: string, spawnError?: Error): {
+    realBrokerPid: number | undefined;
+    realBrokerIncarnation?: string;
+    error: Error | undefined;
+};
 export declare function isBrokerGenerationCompatible(discovery: BrokerDiscovery | null): boolean;
 /**
  * A live incumbent stops being reusable once the runtime image it launches
@@ -29,14 +122,16 @@ export interface EnsureBrokerSettings {
      */
     env?: NodeJS.ProcessEnv;
 }
-export interface BrokerStartupLockTestHooks {
+export interface BrokerStartupLockOptions {
+    /** Stop waiting for the startup lock at this absolute wall-clock deadline. */
+    deadlineAt?: number;
     onAcquired?: () => void;
     onContended?: () => void;
 }
 /**
  * Test-only phase observation for detached broker startup regressions. The
- * signal is opt-in through the child environment and never affects broker
- * ownership or error handling when the test seam is absent.
+ * directory is opt-in through a trusted operator environment and never affects
+ * broker ownership or error handling when the seam is absent.
  */
 export declare function emitBrokerStartupTestSignal(signal: string): Promise<void>;
 /**
@@ -48,7 +143,7 @@ export declare function emitBrokerStartupTestSignal(signal: string): Promise<voi
  */
 export declare const BROKER_DISCOVERY_BUDGET: {
     readonly staleRetirementMs: 5000;
-    readonly startupLockWaitMs: 9000;
+    readonly startupLockWaitMs: number;
     readonly publicationMs: 15000;
     /** What the startup fence grants its holder: retirement plus one publication attempt. */
     readonly fenceOperationMs: number;
@@ -94,7 +189,7 @@ declare function acquireSpawnLock(agentDir: string, options?: SpawnLockOptions):
  * The parent-held spawn lock prevents ordinary stampedes; this second fence keeps
  * startup single-flight if that detached child's launcher dies and its lock is reclaimed.
  */
-export declare function withBrokerStartupLock<T>(agentDir: string, operation: (deadline: number) => Promise<T>, testHooks?: BrokerStartupLockTestHooks): Promise<T>;
+export declare function withBrokerStartupLock<T>(agentDir: string, operation: (deadline: number) => Promise<T>, options?: BrokerStartupLockOptions): Promise<T>;
 /**
  * Tail of the detached broker's stderr folded into a discovery failure.
  *
@@ -138,13 +233,27 @@ export interface StartedFixtureBroker {
 interface BrokerOwner {
     stop(): Promise<void>;
     canReuse(discovery: BrokerDiscovery | null): boolean;
-    markReady(discovery: BrokerDiscovery): boolean;
-    setTarget(pid: number, incarnation: string): void;
+    markReady(discovery: BrokerDiscovery): Promise<boolean>;
 }
 interface ReapTiming {
     gracefulMs: number;
     killVerifyMs: number;
 }
+type DetachedBrokerSignal = (pid: number, brokerIncarnation: string, signal: NodeJS.Signals) => boolean;
+/**
+ * Reap a broker launched by a short-lived hop or trampoline. The launcher has
+ * already exited, so its ChildProcess carries no signal to await: the real broker
+ * is targeted by the reported pid, and every poll is fenced by incarnation.
+ * Signals use a pinned OS process handle; unsupported platforms fail closed.
+ */
+interface PinnedBrokerProcess {
+    readonly incarnation: string;
+    signalRoot(signal: number): boolean;
+}
+/** Reap a failed launch through its pending trampoline lease or retained broker handle. */
+export declare function reapFailedBrokerLaunch(launch: Pick<BrokerLaunchResult, "process" | "realBrokerPid" | "realBrokerIncarnation" | "handoff">): Promise<void>;
+/** Reap the direct broker child held by the startup trampoline before publication. */
+export declare function reapBrokerTrampolineChild(child: ChildProcess, brokerPid: number | undefined, brokerIncarnation?: string): Promise<void>;
 type BrokerOwnerIdentity = Pick<BrokerDiscovery, "ownerId" | "pid" | "incarnation">;
 /** Start client teardown, but never await it past the retirement operation's absolute deadline. */
 export declare function closeBrokerClientBeforeDeadline(client: {
@@ -173,6 +282,10 @@ export declare function startFixtureBrokerWithLeaseForTest(settings: EnsureBroke
  * Test-only launch surface for topology fixtures. It accepts an already-resolved
  * command and retains the exact spawned child; no production selection path
  * reaches this function.
+ *
+ * Note: This function does NOT use the Windows broker hop. Fixtures are test-only
+ * and do not require Windows process-tree detachment; the fixture needs to retain
+ * exact ownership of the actual broker process to control its stdio[3] control pipe.
  */
 export declare function startFixtureBrokerCommandWithLeaseForTest(command: FixtureBrokerCommand): StartedFixtureBrokerCommand;
 /** Test hook: returns a stop handle for the detached broker this process spawned. */
@@ -183,11 +296,30 @@ export declare function brokerOwnerForTest(agentDir: string): BrokerOwner | unde
 /** Test hook: verifies the complete broker owner identity used during stale retirement. */
 export declare function brokerOwnerIdentityMatchesForTest(left: BrokerOwnerIdentity | null, right: BrokerOwnerIdentity): boolean;
 /** Test hook: drives the detached-broker reap on a controllable child surface. */
-export declare function reapSpawnedBrokerForTest(child: ChildProcess, timing?: ReapTiming): Promise<void>;
+export declare function reapSpawnedBrokerForTest(child: ChildProcess, realBrokerPid?: number, brokerIncarnation?: string, timing?: ReapTiming): Promise<void>;
+/** Test hook: verifies detached PID reaping fences every signal and poll by incarnation. */
+export declare function reapDetachedBrokerPidForTest(pid: number, brokerIncarnation: string | undefined, timing?: ReapTiming, observe?: (pid: number) => ProcessIncarnationObservation, signalProcess?: DetachedBrokerSignal): Promise<void>;
+/** Test hook: verifies a pinned process handle matches before sending a signal. */
+export declare function signalPinnedBrokerProcessForTest(reference: PinnedBrokerProcess | null, expectedIncarnation: string, signal: NodeJS.Signals): boolean;
+/** Test hook: verifies platforms without identity-bound signaling fail closed. */
+export declare function signalDetachedBrokerProcessForTest(pid: number, brokerIncarnation: string, signal: NodeJS.Signals, platform: NodeJS.Platform): boolean;
+/** Test hook: the signal directory accepted from this environment and snapshot. */
+export declare function trustedBrokerSignalDirectoryForTest(env: NodeJS.ProcessEnv, snapshot: ProjectEnvSnapshot | readonly ProjectEnvSnapshot[]): string | undefined;
 /** Test hook: resolves the complete broker environment without spawning. */
 export declare function brokerSpawnEnvironmentForTest(command: SdkInternalSpawnCommand, override?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /** Test hook: installs an exact controllable owner to exercise replacement fencing. */
-export declare function registerBrokerOwnerForTest(agentDir: string, child: ChildProcess, timing?: ReapTiming): BrokerOwner;
+export declare function registerBrokerOwnerForTest(agentDir: string, child: ChildProcess, realBrokerPid?: number, brokerIncarnation?: string, timing?: ReapTiming): BrokerOwner;
 /** Test hook: exercises the same trusted-marker reason reconstruction used by ensureBroker. */
 export declare function brokerStartupFailureReasonForTest(marker: BrokerStartupFailureMarker | undefined): string;
+/** Test hook: verifies typed hop errors survive ensureBroker's spawn-failure mapping. */
+export declare function brokerSpawnFailureErrorForTest(spawnError: Error): Error;
+/** Test hook: preserves and reaps a verified broker reply captured at the hop deadline. */
+export declare function brokerHopTimeoutResultForTest(hop: ChildProcess, stdout: string, stderr: string, timeoutMs: number, launcherTerminated: boolean): Promise<BrokerLaunchResult>;
+/** Test hook: preserves and reaps a verified POSIX trampoline reply at its deadline. */
+export declare function brokerTrampolineTimeoutResultForTest(trampoline: ChildProcess, stdout: string, timeoutMs: number, trampolineTerminated: boolean): Promise<BrokerLaunchResult>;
+/** Test hook: verifies broker exit evidence takes precedence over the launcher's status. */
+export declare function brokerStartupExitStatusForTest(childExitCode: number | null, childSignal: NodeJS.Signals | null, startupExitRecord: Pick<BrokerStartupExitRecord, "exitCode" | "signal"> | undefined, startupFailureMarker: Pick<BrokerStartupFailureMarker, "exitCode" | "signal"> | undefined): {
+    exitCode: number | null;
+    signal: string | null;
+};
 export {};

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

@@ -0,0 +1,45 @@
+import * as childProcess from "node:child_process";
+import type * as stream from "node:stream";
+import type { Process } from "@gajae-code/natives";
+/** Handoff protocol frames written to the trampoline's stdin. */
+export declare const BROKER_HANDOFF_ACKNOWLEDGEMENT = "GJC_BROKER_HANDOFF_ACK\n";
+export declare const BROKER_HANDOFF_COMMIT = "GJC_BROKER_HANDOFF_COMMIT\n";
+export declare const BROKER_HANDOFF_ABORT = "GJC_BROKER_HANDOFF_ABORT\n";
+/**
+ * Backstop for a retained trampoline whose parent never sends a decision. It must
+ * outlive the parent's own broker discovery deadline (which is derived from the
+ * publication budget and can double across a guarded retry), otherwise the
+ * trampoline reaps the broker first and the parent misreports its own discovery
+ * timeout as an "exited before discovery" startup failure.
+ */
+export declare const BROKER_HANDOFF_DECISION_TIMEOUT_MS = 120000;
+/**
+ * Windows broker hop: spawns the real broker with detached:true and reports its pid.
+ *
+ * The hop is needed because a broker spawned with detached:true IS still killed when the
+ * parent process tree is terminated (e.g., by taskkill /T /F on Windows). Using an
+ * intermediate hop process that exits after spawning the real broker allows the broker
+ * to survive, because the hop's parent (the initiating client) can be killed without
+ * affecting the broker (the hop's pid is no longer valid).
+ *
+ * Invoked by gjc internals only. Usage:
+ *   gjc internal broker-hop <json-encoded-args>
+ *
+ * Exits with code 0 after writing the broker pid/incarnation to stdout and
+ * receiving the parent's acknowledgement. If stdin closes first, it terminates
+ * the pinned broker and exits with code 1.
+ */
+export declare function runBrokerHopFromArgv(argv: string[]): Promise<void>;
+type BrokerHopWriteCallback = (error?: Error | null) => void;
+type BrokerHopWriter = (chunk: string, callback: BrokerHopWriteCallback) => void;
+type BrokerHopAcknowledger = () => Promise<boolean>;
+export declare function writeBrokerHopReplyForTest(child: childProcess.ChildProcess, reference: Process, pid: number, write: BrokerHopWriter, waitForAcknowledgement?: BrokerHopAcknowledger): Promise<{
+    kind: "written";
+} | {
+    kind: "failed";
+    reason: string;
+}>;
+export declare function waitForBrokerHandoffAcknowledgement(input: stream.Readable): Promise<boolean>;
+/** Wait for a validated identity ACK followed by the parent's publication decision. */
+export declare function waitForBrokerHandoffDecision(input: stream.Readable, timeoutMs?: number): Promise<"commit" | "abort">;
+export {};

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

@@ -144,19 +144,27 @@ export declare class LifecycleLedger {
     findByOperationKey(operationKey: string, fingerprint?: string): LifecycleLedgerEntry | undefined;
     findAnyByOperationKey(operationKey: string): LifecycleLedgerEntry | undefined;
     /**
-     * Live or uncertain legacy rows predate the operation/key index. Their opaque
-     * identities cannot establish that a different target is safe, so callers
-     * must reject rather than create a second admission. A fresh session.create
-     * may ignore completed terminal legacy rows so old successful operations do
-     * not block coordinator startup. Other operations retain the legacy fence
-     * because target-bound legacy identities cannot prove key uniqueness. For
-     * target-bound terminal creates, the opaque legacy identity also cannot reveal
-     * the original caller key, so this exception retires that legacy key history;
-     * exact key-only legacy creates are still rejected by the earlier lookup.
+     * Live legacy rows predate the operation/key index. Their opaque identities
+     * cannot establish that a different target is safe, so callers must reject
+     * rather than create a second admission. A fresh session.create may ignore
+     * final legacy rows: exact legacy identities are still resolved before this
+     * check, and uncertain rows retain their session-scoped fences.
+     *
+     * A session-targeted request passes `sessionTarget` to ignore terminal legacy
+     * rows that record only other sessions, unless the row is the caller's key
+     * reused across targets (`keyReuseIdentities`). Terminal rows recording the
+     * target or no session, uncertain rows, and live rows keep the fence because
+     * they cannot prove the requested target is unrelated.
      */
     hasLegacyIdentity(excludedIdentities?: ReadonlySet<string>, options?: {
-        ignoreTerminalRows?: boolean;
+        ignoreFinalRows?: boolean;
+        sessionTarget?: {
+            sessionId: string;
+            keyReuseIdentities: ReadonlySet<string>;
+        };
     }): boolean;
+    /** Sessions recorded by terminal legacy rows, for deriving key-reuse identities. */
+    terminalLegacySessionIds(): Set<string>;
     migrateIdentity(from: string, to: string, metadata: {
         operationKey: string;
         fingerprint: string;

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

@@ -133,6 +133,28 @@ export type SessionLifecycleLaunchRequest = SessionLifecycleLaunchRequestBase &
     coordinatorSidecarSigningKey?: undefined;
 });
 export declare function readSessionLifecycleLaunchRequest(value: string | undefined, now?: number): SessionLifecycleLaunchRequest;
+/**
+ * Validates the optional per-session `env`/`unsetEnv` pair (#6735). Returns
+ * null when either is malformed so the caller fails the launch closed.
+ */
+export declare function lifecycleSessionEnv(input: {
+    env?: unknown;
+    unsetEnv?: unknown;
+}): {
+    env?: Record<string, string>;
+    unsetEnv?: string[];
+} | null;
+/**
+ * Composes the inherited part of a lifecycle session host's environment:
+ * drops the process-local master capability, every `unsetEnv` name, and any
+ * inherited name an explicit per-session `env` entry replaces (case-folded on
+ * Windows so `Path` and `PATH` never both reach the child), then layers the
+ * per-session `env` on top. Broker-issued `GJC_*` keys are applied after this.
+ */
+export declare function lifecycleSessionHostBaseEnv(inherited: NodeJS.ProcessEnv | Readonly<Record<string, string | undefined>>, launch: {
+    env?: Readonly<Record<string, string>>;
+    unsetEnv?: readonly string[];
+}): Record<string, string>;
 type CleanupEvidence = BrokerCleanupEvidence;
 export declare function validateBrokerModelPresetSync(agentDir: string, requestedProfile: string): string | BrokerResponse;
 export declare function validateBrokerModelPresetForTest(agentDir: string, requestedProfile: string): string | BrokerResponse;

package/dist/types/sdk/broker/lock-host-identity.d.ts

@@ -0,0 +1,5 @@
+export interface BrokerLockHostIdentity {
+    ownerHostId: string;
+    previousOwnerHostIds: readonly string[];
+}
+export declare function brokerLockHostIdentity(agentDir: string): Promise<BrokerLockHostIdentity>;

package/dist/types/sdk/broker/session-index.d.ts

@@ -1,3 +1,4 @@
+import { type FileLockOptions } from "../../config/file-lock";
 import { SDK_STATE_VERSION, SESSION_INDEX_EVENT_VERSION } from "./state-version";
 export type SessionIndexEventType = "host_registered" | "host_heartbeat" | "host_unregistered" | "lifecycle_started" | "lifecycle_terminal" | "session_closed" | "session_deleted" | "record_reconciled";
 export type SessionActivityState = "active" | "idle";
@@ -182,10 +183,14 @@ export declare const SESSION_HEARTBEAT_INTERVAL_MS = 60000;
 export declare const DEAD_HOST_HEARTBEAT_SILENCE_MS: number;
 export declare const DEFAULT_SESSION_RETENTION_MAX_AGE_MS: number;
 export declare const DEFAULT_SESSION_RETENTION_MAX_ROWS = 25000;
+/** Bound ordinary bootstrap waits; authorized doctor successors may use the full prepared window. */
+export declare function sessionIndexStartupLockOptions(deadline: number, signal?: AbortSignal, policy?: "ordinary" | "authorized-successor"): FileLockOptions;
+/** One elapsed budget for queueing, probing and every reacquisition in a pass. */
+export declare const SESSION_HEARTBEAT_CHECKPOINT_BUDGET_MS = 15000;
 export declare class SessionIndex {
     #private;
     constructor(agentDir: string, policy?: RetentionPolicy, observationDeps?: SessionIndexObservationDeps);
-    open(): Promise<this>;
+    open(options?: FileLockOptions): Promise<this>;
     replay(): Promise<void>;
     /**
      * Polling-path refresh (#4689): when both index files carry the exact change

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

@@ -6,6 +6,8 @@ export declare class BrokerTransport {
     #private;
     constructor(broker: Broker, token: string, port?: number);
     get port(): number;
+    /** Sockets a client holds open right now; the broker outlives every one of them. */
+    get clientCount(): number;
     start(): Promise<number>;
     stop(): Promise<void>;
 }

package/dist/types/sdk/bus/chat-command-policy.d.ts

@@ -1,8 +1,9 @@
+import { type AdapterValidationError } from "../protocol/adapter-validation";
 import { type Adapter, type OperationKind } from "../protocol/operation-registry";
 export type ChatTransport = Extract<Adapter, "telegram" | "discord" | "slack">;
 export type ChatOperationDisposition = "allowed" | "unsupported_on_chat";
 export interface ChatCommandError {
-    code: "unsupported_on_chat" | "secret_input_forbidden";
+    code: "unsupported_on_chat" | "secret_input_forbidden" | "ultrafast_tier_forbidden" | AdapterValidationError["code"];
     message: string;
 }
 export type ChatCommandDecision = {