@gajae-code/coding-agent 0.17.2 → 0.17.5

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

@@ -4,7 +4,7 @@ import { type SdkHostModelResolver } from "../host/model-pin";
 import { type DirectoryMigrationPolicy } from "../session-directory";
 import { type BrokerDiscovery, type BrokerPublicationObservation, type RedactedBrokerDiscovery } from "./discovery";
 import { type LifecycleDurableEffectsReceipt, LifecycleLedger, type LifecycleStartupFailureReceipt } from "./lifecycle-ledger";
-import { SessionIndex } from "./session-index";
+import { type IndexedSession, SessionIndex } from "./session-index";
 import { type MasterCapabilityVerifier, type SpawnSubstrateFailure, type SpawnSubstrateProvider } from "./spawn-authority";
 export interface BrokerSettings {
     agentDir: string;
@@ -94,7 +94,7 @@ export type BrokerCleanupEvidence = {
         dev: string;
         ino: string;
     };
-    /** Identity-bound lifecycle metadata marker retained when exact cleanup is deferred. */
+    /** Identity-bound lifecycle metadataker retained when exact cleanup is deferred. */
     metadataIdentity?: BrokerCleanupIdentity;
     metadataPath?: string;
     /** Monotonic append-only cleanup attempt. */
@@ -129,7 +129,7 @@ export type BrokerCleanupEvidence = {
         dev: string;
         ino: string;
     };
-    /** Delete metadata receipts authorize only the canonical marker/ready sibling pair. */
+    /** Delete metadata receipts authorize only the canonicalker/ready sibling pair. */
     lifecycleDeleteMetadata?: true;
 };
 export type BrokerResponse = {
@@ -149,6 +149,9 @@ export type BrokerResponse = {
     durableEffects?: LifecycleDurableEffectsReceipt;
     startupFailure?: LifecycleStartupFailureReceipt;
 };
+export type InputNormalization = {
+    input: Record<string, unknown>;
+} | BrokerResponse;
 /** Complete five-leg child endpoint pin captured at registration. */
 export type SpawnHostRegistration = {
     sessionId: string;
@@ -201,6 +204,13 @@ export interface SpawnPromptLayer {
         pinned: SpawnHostRegistration;
     }): Promise<SpawnQ26Reconciliation>;
 }
+/** Exact admission predicate for the child host row published after launch. */
+export declare function spawnRegistrationMatches(candidate: IndexedSession, expected: {
+    childId: string;
+    cwd: string;
+    stateRoot: string;
+}): boolean;
+export declare function normalizeBrokerInput(operation: string, input: Record<string, unknown>): InputNormalization;
 /** Test seam for lifecycle serialization identity. */
 export declare function lifecycleTargetForTest(operation: string, input: Record<string, unknown>): unknown;
 /** Tombstone prefix used by {@link Broker.reclaimStaleLock} when a dead owner's lock is renamed aside. */
@@ -235,7 +245,8 @@ export interface BrokerLockArtifactReapResult {
  * of the lock's dev+ino, so a machine accrues one directory per dead owner and
  * nothing ever removed them (54 on the install in #3963). Reaping is
  * best-effort and fail-closed: anything live, unreadable, permission-denied, or
- * otherwise ambiguous is kept and the reason is logged.
+ * otherwise ambiguous is kept. Retained paths are logged at debug level and
+ * summarized in one warning per reap pass.
  */
 export declare function reapStaleBrokerLockArtifacts(input: {
     agentDir: string;
@@ -368,6 +379,8 @@ export declare function setAmbiguityGraceForTest(broker: Broker, graceMs: number
 export declare function setLockArtifactGraceForTest(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. */
+export declare function setManagedCloseWaitForTest(broker: Broker, waitMs: number | undefined): void;
 /**
  * Test-only hook for stalling the heartbeat write, reproducing a publication tick
  * whose awaited IO does not settle. Clearing it releases the stalled tick the way

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

@@ -3,6 +3,7 @@ import type { FileHandle } from "node:fs/promises";
 import { type FileLockOptions } from "../../config/file-lock";
 import { type BrokerDiscovery } from "./discovery";
 import { type SdkInternalSpawnCommand } from "./runtime";
+import { type BrokerStartupFailureMarker } from "./startup-failure";
 export declare function isBrokerGenerationCompatible(discovery: BrokerDiscovery | null): boolean;
 /**
  * A live incumbent stops being reusable once the runtime image it launches
@@ -173,4 +174,6 @@ export declare function reapSpawnedBrokerForTest(child: ChildProcess, timing?: R
 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;
+/** Test hook: exercises the same trusted-marker reason reconstruction used by ensureBroker. */
+export declare function brokerStartupFailureReasonForTest(marker: BrokerStartupFailureMarker | undefined): string;
 export {};

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

@@ -1,4 +1,8 @@
 export declare function brokerIdentityPath(agentDir: string): string;
 export declare function getBrokerIdentityKey(agentDir: string): Promise<string>;
-export declare function deriveIdempotencyIdentity(agentDir: string, operation: string, callerKey: string, _protocolVersionOrLegacyTargetHash?: string): Promise<string>;
+export declare function deriveIdempotencyIdentity(agentDir: string, operation: string, callerKey: string, targetHash?: string): Promise<string>;
+/** Native identity for an idempotency key reserved inside one managed control root. */
+export declare function deriveScopedIdempotencyIdentity(agentDir: string, operation: string, callerKey: string, scope: string): Promise<string>;
+/** Identity format used by lifecycle rows written before target binding. */
+export declare function deriveLegacyIdentity(agentDir: string, operation: string, callerKey: string): Promise<string>;
 export declare function deriveLegacyTargetIdentity(agentDir: string, operation: string, callerKey: string, canonicalTargetHash: string): Promise<string>;

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

@@ -95,6 +95,23 @@ export type BeginResult = {
     kind: "in_progress";
     entry: LifecycleLedgerEntry;
 };
+type BoundedSourceReadRejection = "not-regular-file" | "oversized-by-stat" | "oversized-by-read" | "read-error";
+/**
+ * Why a terminal read-back produced no entry. `absent` means nothing terminal is
+ * recorded for the request; `rejected` means the source or a row was refused, which
+ * is evidence of a damaged ledger rather than of an unpersisted operation. Collapsing
+ * the two lets a corrupt source or row read as "not yet written" and unfence the session.
+ */
+export type TerminalReadBackRejection = "bounds" | "shape" | "undecodable" | "row-not-attributable" | "partial-row" | BoundedSourceReadRejection;
+export type TerminalReadBack = {
+    kind: "terminal";
+    entry: LifecycleLedgerEntry;
+} | {
+    kind: "absent";
+} | {
+    kind: "rejected";
+    reason: TerminalReadBackRejection;
+};
 export interface LifecycleLedgerLimits {
     maxBytes?: number;
     maxLineBytes?: number;
@@ -121,14 +138,15 @@ export declare class LifecycleLedger {
      * uncertainly persists that conclusion, and refusing to read it back would report a
      * synced row as unpersisted and replace its true reason with a generic one.
      */
-    readTerminal(identity: string, requestHash: string): Promise<LifecycleLedgerEntry | undefined>;
-    findByOperationKey(operationKey: string): LifecycleLedgerEntry | undefined;
+    readTerminal(identity: string, requestHash: string): Promise<TerminalReadBack>;
+    findByOperationKey(operationKey: string, fingerprint?: string): LifecycleLedgerEntry | undefined;
+    findAnyByOperationKey(operationKey: string): LifecycleLedgerEntry | undefined;
     /**
      * Legacy target-inclusive 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.
      */
-    hasLegacyIdentity(): boolean;
+    hasLegacyIdentity(excludedIdentities?: ReadonlySet<string>): boolean;
     migrateIdentity(from: string, to: string, metadata: {
         operationKey: string;
         fingerprint: string;
@@ -137,6 +155,7 @@ export declare class LifecycleLedger {
     begin(identity: string, requestHash: string, metadata?: {
         operationKey?: string;
         fingerprint?: string;
+        intendedSessionId?: string;
     }): Promise<BeginResult>;
     transition(identity: string, state: LifecycleState, fields?: Omit<Partial<LifecycleLedgerEntry>, "identity" | "requestHash" | "state" | "ts">): Promise<LifecycleLedgerEntry>;
     assertSupportedStateVersions(): Promise<void>;
@@ -152,3 +171,4 @@ export declare class LifecycleLedger {
     listUncertainCreatesBySessionId(sessionId: string, effectMarker?: string, remoteCreateKey?: string): LifecycleLedgerEntry[];
     findPendingCleanupByTarget(sessionId: string, cwd: string, transcriptPath: string): LifecycleLedgerEntry | undefined;
 }
+export {};

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

@@ -1,5 +1,6 @@
 import { type ChildProcess } from "node:child_process";
 import { type GjcLaunchWorktreePlan } from "../../gjc-runtime/launch-worktree";
+import type { SessionWorkLease } from "../../session/session-work-lease";
 import type { SessionLifecycleMcpServer } from "../acp/mcp";
 import { type SdkStartupFailure, type SdkStartupRollbackResult } from "../startup-capability";
 import type { Broker, BrokerCleanupEvidence, BrokerResponse } from "./broker";
@@ -8,8 +9,11 @@ import { type ProcessIncarnationCommandRunner, type ProcessIncarnationOptions, p
 import { type SdkInternalSpawnCommand } from "./runtime";
 import { type IndexedSession } from "./session-index";
 export { type ProcessIncarnationCommandRunner, type ProcessIncarnationOptions, parseDarwinProcessIncarnation, processIncarnation, };
+/** Remove lifecycle stderr artifacts abandoned by a broker or detached host crash. */
+export declare function reapOrphanedChildStderrLogs(agentDir: string, limit?: number): Promise<number>;
+export declare function lifecycleFailureMessage(message: string, child?: ChildProcess): string;
 export declare function terminalUncertainStartupMessage(response: BrokerResponse): string;
-export declare function waitForChildSpawn(spawned: Pick<ChildProcess, "off" | "on" | "once">, onPostSpawnError?: (error: Error) => void): Promise<void>;
+export declare function waitForChildSpawn(spawned: Pick<ChildProcess, "off" | "on" | "once" | "pid">, onPostSpawnError?: (error: Error) => void): Promise<void>;
 export interface LifecycleDeadlines {
     receivedAt: number;
     requestedReadinessTimeoutMs: number;
@@ -245,8 +249,9 @@ export interface LifecycleExecutionOutcome {
 /** Returns the response together with every durable lifecycle fact needed for truthful replay. */
 export declare function executeLifecycle(broker: Broker, operation: string, input: Input, identity: string, cleanup?: CleanupEvidence): Promise<LifecycleExecutionOutcome>;
 /**
- * The live client/socket subscription count of the SDK session endpoint this
- * process serves, or `undefined` while this process serves no endpoint.
+ * The live SDK demand count of the session endpoint this process serves, or
+ * `undefined` while this process serves no endpoint. Observer-only sockets are
+ * excluded by {@link SessionHostRuntimeEvidence.observerClients}.
  *
  * Only the SDK session runtime owns the real socket table, so it publishes a
  * reader here instead of every consumer re-deriving attachment from the OS.
@@ -257,8 +262,10 @@ export type SessionHostAttachmentReader = () => number;
 export interface SessionHostRuntimeEvidence {
     /** This runtime's own live SDK client/socket subscription count. */
     attachedClients: SessionHostAttachmentReader;
-    /** Whether this runtime currently has agent work in flight. */
-    workInFlight: () => boolean;
+    /** Optional subset of attached sockets that only observes the host. */
+    observerClients?: SessionHostAttachmentReader;
+    /** One authoritative lease held by every admitted or continuing work state. */
+    workLease: SessionWorkLease;
 }
 /** One runtime's live publication, retractable only by its owner. */
 export interface SessionHostRuntimePublication {
@@ -275,19 +282,19 @@ export interface SessionHostRuntimePublication {
  */
 export declare function publishSessionHostRuntimeEvidence(evidence: SessionHostRuntimeEvidence): SessionHostRuntimePublication;
 /**
- * This process's currently attached SDK client count, summed across every
+ * This process's currently demanding SDK client count, summed across every
  * serving runtime, or `undefined` when no runtime publishes a readable count
  * (before startup, after teardown, or when every reader itself fails). Never
  * guesses: absence of a reader is absence of evidence.
  */
 export declare function sessionHostAttachedClients(): number | undefined;
 /**
- * Whether any runtime in this process has agent work in flight right now.
+ * Whether any runtime in this process still holds its authoritative work lease.
  *
  * Positive evidence only: a runtime that publishes nothing, or whose reader
  * fails, reports no work, so this can never keep an abandoned host alive.
  */
-export declare function sessionHostWorkInFlight(): boolean;
+export declare function sessionHostWorkLeaseActive(): boolean;
 /**
  * How often a live broker re-checks its own session registrations against OS
  * process liveness.