@gajae-code/coding-agent 0.11.5 → 0.11.7

package/dist/types/sdk/bus/notification-service.d.ts

@@ -74,6 +74,40 @@ export interface NotificationStatusReport {
 export declare function buildNotificationStatusReport(settings: Settings): NotificationStatusReport;
 /** Render a status report as human-readable lines (no secrets). */
 export declare function formatNotificationStatusReport(report: NotificationStatusReport): string;
+export interface NotificationEndpointView {
+    sessionId: string;
+    pid: number | undefined;
+    stale: boolean;
+}
+export type NotificationEndpointLiveness = "live" | "dead" | "unknown";
+/**
+ * Classification used by recovery and startup takeover. A file is an endpoint
+ * only when it has endpoint authority fields; lifecycle/audit records are never
+ * candidates for endpoint cleanup.
+ */
+export type NotificationEndpointClassification = {
+    kind: "endpoint";
+    view: NotificationEndpointView;
+    liveness: NotificationEndpointLiveness;
+    identity: NotificationEndpointFileIdentity;
+} | {
+    kind: "non-endpoint";
+} | {
+    kind: "unreadable";
+};
+/**
+ * Classify an endpoint using owner-proof semantics. An endpoint is only `dead`
+ * with positive proof: an explicit `stale` tombstone, or a recorded pid that is
+ * confirmed not alive. A PID-less endpoint is `unknown` (not provably dead) and
+ * must never be treated as dead — removing it could delete a live session's
+ * discovery file that simply omitted a pid.
+ */
+export declare function notificationEndpointLiveness(view: NotificationEndpointView, pidAlive: (pid: number) => boolean): NotificationEndpointLiveness;
+/**
+ * Read and classify one endpoint candidate. The returned identity belongs to
+ * exactly the bytes inspected and is required for any later deletion.
+ */
+export declare function classifyNotificationEndpoint(fs: Pick<NotificationServiceFs, "readEndpointFile">, file: string, pidAlive: (pid: number) => boolean): Promise<NotificationEndpointClassification>;
 export type HealthLevel = "ok" | "warn" | "error";
 export interface HealthCheck {
     name: string;

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

@@ -14,7 +14,17 @@ export declare const NOTIFICATION_PROTOCOL_VERSION = 3;
  * The current development baseline already includes #2299's generation 4,
  * incarnation fencing in generation 5, owner-lock authority in generation 6,
  * identity-atomic transition markers in generation 7, stable signaling plus
- * tri-state foreign-owner provenance in generation 8, and retained managed
- * filesystem authority changes in generation 9.
+ * tri-state foreign-owner provenance in generation 8, retained managed
+ * filesystem authority changes in generation 9, SDK-startup auto-reclaim of a
+ * confirmed-dead owner's lock in generation 10, legacy stopped-tombstone
+ * reclamation in generation 11, force-escalated SIGKILL of an unresponsive
+ * older-generation owner during automatic generation-upgrade reload in
+ * generation 12, restored macOS daemon signaling (kill(2) with a start-time
+ * incarnation recheck, replacing the darwin no-op) in generation 13, retained
+ * legacy stopped-lock reclamation in generation 14, Windows expected-identity
+ * ACL verification and repair in generation 15, identity-fenced stale endpoint
+ * startup recovery in generation 16, Telegram topic recovery authority fencing
+ * in generation 17, and fail-closed blank-token validation plus lifecycle-startup
+ * stop fencing in generation 18.
  */
-export declare const DAEMON_GENERATION = 9;
+export declare const DAEMON_GENERATION = 18;

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

@@ -9,6 +9,7 @@ import { type ControlServerLike, type LifecycleControlServerFactory } from "./li
 import type { OrchestratorDeps } from "./lifecycle-orchestrator";
 import { NotificationOperatorRuntime, OperatorBackoffPolicy } from "./operator-runtime";
 import { type AliasTable, type CallbackRoute } from "./telegram-reference";
+import { type TopicEndpointBinding } from "./topic-registry";
 export type EnsureDaemonResult = "owner_spawned" | "attached" | "disabled" | "blocked";
 /** Detailed result for orchestration that must distinguish a #2028 handoff from a fresh spawn. */
 export type EnsureTelegramDaemonDetailedResult = "spawned" | "reloaded" | "attached" | "disabled" | "blocked_identity";
@@ -389,6 +390,29 @@ export declare function buildTelegramDaemonSpawnArgs(input: {
  * already-persisted roots.
  */
 export declare function spawnTelegramDaemonOwner(input: TelegramSpawnOwnerInput, deps?: TelegramDaemonDeps): Promise<TelegramSpawnOwnerResult>;
+/**
+ * Owner-bound reclamation of a confirmed-dead daemon owner, mirroring the
+ * daemon step of `gjc notify recovery`. It returns a structured, actionable
+ * result and removes only identity-verified dead-owner artifacts while holding
+ * the transition fence; live, successor, unknown, or unreadable evidence is
+ * retained.
+ */
+export type DeadOwnerRecoveryResult = {
+    recovered: true;
+    reason: "cleared";
+} | {
+    recovered: false;
+    reason: "not-confirmed-dead" | "unsafe-lock" | "transition-contended" | "owner-superseded" | "unsafe-endpoint" | "endpoint-changed" | "endpoint-directory-unreadable" | "lock-changed";
+};
+/** Preflight cleanup for a confirmed-dead owner, with identity-bound removal. */
+export declare function reclaimDeadDaemonOwner(input: {
+    settings: Settings;
+    endpointDir?: string;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+    pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+}): Promise<DeadOwnerRecoveryResult>;
 /**
  * Ensure a configured daemon owns this session root, preserving ownership safety
  * while exposing whether a #2028 generation handoff was required.
@@ -469,6 +493,11 @@ export declare class TelegramEventDispatchState {
     readonly busy: Set<string>;
     readonly inboundReactions: Map<number, {
         messageId: number;
+        socketLease?: {
+            session: SessionSocket;
+            token: number;
+            logicalSessionId: string;
+        };
     }>;
     readonly seenUpdateIds: Set<number>;
 }
@@ -551,11 +580,15 @@ interface SessionSocket {
     sessionId: string;
     /** Current logical session carried by valid threaded frames on this transport. */
     logicalSessionId: string;
+    /** Endpoint metadata proved this logical id belongs to this discovery record. */
+    logicalSessionIdTrusted: boolean;
     token: string;
     endpointKey: string;
     endpointDigest: string;
     hostGeneration: number;
     ws: WebSocket;
+    /** Timestamp (via opts.now) at which this socket began connecting. */
+    connectingSince: number;
     pending: Map<string, {
         sessionId: string;
         actionId: string;
@@ -574,6 +607,13 @@ interface SessionSocket {
     /** Queues live frames until startup replay is applied. */
     replayPending: boolean;
     replayQueue: Record<string, unknown>[];
+    /** Trusted recovery may not route until its durable endpoint lease is committed. */
+    recoveryLease?: {
+        state: "pending" | "authorized" | "rejected";
+        logicalSessionId: string;
+        binding: TopicEndpointBinding;
+        token: number;
+    };
 }
 export declare class TelegramNotificationDaemon {
     #private;
@@ -598,12 +638,20 @@ export declare class TelegramNotificationDaemon {
     private readonly pollConflictBackoff;
     private readonly loopBackoff;
     private running;
+    /** Once set, a concurrent startup await can never restore a running daemon. */
+    private stopRequested;
     private readonly fsImpl;
     private readonly botApi;
     private readonly effects;
     private readonly topics;
     /** Serializes registry snapshots so an older atomic write cannot overwrite newer rename state. */
+    /** Legacy sockets have no durable token, so explicit teardown is their revocation fence. */
+    private readonly droppedSessions;
     private topicsPersistQueue;
+    /** Serializes recovery compare/write/publish claims so competing endpoint migrations cannot durably diverge. */
+    private recoveryBindingClaimQueue;
+    /** Durable compensation fences retry under supervision until persistence succeeds. */
+    private readonly compensationFenceRetries;
     /** Daemon edit attempts that can race an accepted user service message. */
     private readonly daemonRenameAttempts;
     private readonly selectedAckPending;
@@ -616,10 +664,17 @@ export declare class TelegramNotificationDaemon {
     private readonly draftStream;
     /** Identity-bearing sessions by repo/branch surface, used to avoid transient duplicate topics. */
     private readonly topicOwnerByIdentity;
+    /** Ephemeral legacy topic owners retained across a same-socket config rekey. */
+    private readonly legacyTopicOwners;
+    /** Preserved initiator topics must not route through a rekeyed transport. */
+    private readonly preservedInitiatorTopics;
     /** Non-identity frames held until identity creates the correct thread. */
     private readonly pendingThreadedFrames;
-    /** Endpoint generation tombstones for sessions that already sent session_closed. */
+    /** Durable endpoint leases for sessions that already sent an authorized session_closed. */
     private readonly closedEndpointKeys;
+    /** Exactly one authorized transport may route each recovered logical session. */
+    private readonly logicalSessionOwners;
+    private nextSocketLeaseToken;
     /** True once the daemon has nudged the user to enable Threaded Mode. */
     private threadedFallbackNoticeSent;
     /** Sessions whose identity header was already sent flat (Threaded Mode off). */
@@ -698,6 +753,7 @@ export declare class TelegramNotificationDaemon {
     private pruneSeenUpdateIds;
     private rememberSeenUpdateId;
     private reserveSeenUpdateId;
+    private releaseSeenUpdateId;
     scanRoots(): Promise<void>;
     connectSession(sessionId: string, url: string, token: string): void;
     /**
@@ -734,7 +790,6 @@ export declare class TelegramNotificationDaemon {
     private topicIdentityKey;
     private topicIdentityBase;
     private topicOwnerForIdentity;
-    private sessionCanClaimIdentity;
     private toolActivityOwner;
     private toolActivityAuthorityIsCurrent;
     private submitThreadedFrame;
@@ -759,7 +814,9 @@ export declare class TelegramNotificationDaemon {
     private deleteTopic;
     private persistTopics;
     loadTopics(): Promise<void>;
-    /** Download a Telegram file by its file_path (from getFile) into memory. */
+    /** Retry crash-interrupted topic deletes; only a definite Telegram result clears the durable fence. */
+    private reconcilePendingTopicDeletes;
+    /** Download one Telegram file with the Bot API's 20 MiB ceiling and one end-to-end deadline. */
     private downloadTelegramFile;
     /**
      * Per-session private temp directories (mode 0700) holding inbound non-image
@@ -781,6 +838,7 @@ export declare class TelegramNotificationDaemon {
      * to append to the injected text.
      */
     private resolveInboundAttachment;
+    private resolveInboundAttachmentSerial;
     /**
      * Serialize all pool flushes. Every caller (`submitThreadedFrame`, the flat
      * fallback, the drain timer's `void this.flushPool()`, topic teardown) goes

package/dist/types/sdk/bus/topic-registry.d.ts

@@ -38,8 +38,22 @@ export interface TopicRecord {
     replaySeq?: number;
     /** Serialized authority epoch; a late create may commit only in its starting epoch. */
     authorityEpoch?: number;
+    /** Immutable authority epoch held when this remote topic create began. */
+    creationLeaseEpoch?: number;
     /** An uncertain delete fences future creation and inbound routing. */
     authorityState?: "active" | "delete_pending";
+    /** Telegram chat and endpoint authority last proven to use this topic. */
+    chatId?: string;
+    /** Canonical endpoint tuple (URL + token) that currently holds the lease. */
+    endpointKey?: string;
+    /** Authenticated endpoint authority digest, excluding transport presentation. */
+    endpointDigest?: string;
+    /** SDK event generation associated with the current endpoint lease. */
+    endpointGeneration?: number;
+    /** Monotonic authenticated endpoint handoffs; legacy bindings begin at zero. */
+    endpointIncarnation?: number;
+    /** True when persisted binding fields were present but malformed; recovery must fail closed. */
+    bindingMalformed?: true;
 }
 /** Serialisable shape persisted to disk. */
 export interface TopicRegistryState {
@@ -47,6 +61,34 @@ export interface TopicRegistryState {
     topics: Record<string, TopicRecord>;
     /** Durable deletion epochs retained after a definite delete. */
     fences?: Record<string, number>;
+    /** Closed transport endpoint leases; unchanged endpoint discovery remains fenced across restart. */
+    closedEndpoints?: Record<string, TopicEndpointBinding>;
+}
+/** Authenticated runtime binding for a durable topic lease. */
+export interface TopicEndpointBinding {
+    chatId: string;
+    endpointKey: string;
+    endpointDigest: string;
+    endpointGeneration?: number;
+}
+/** Discriminated durable endpoint authority for identity-less replay admission. */
+export type TopicEndpointAuthority = {
+    state: "none";
+} | {
+    state: "unique";
+    sessionId: string;
+} | {
+    state: "ambiguous";
+};
+/** Conditional rollback token for a delete fence publication. */
+export interface TopicDeleteAuthoritySnapshot {
+    sessionId: string;
+    topicId?: string;
+    authorityEpoch?: number;
+    authorityState?: TopicRecord["authorityState"];
+    fenceEpoch?: number;
+    /** Exact fenced record, retained to restore an in-memory tombstone after a failed clear publication. */
+    record?: TopicRecord;
 }
 export declare function emptyTopicRegistryState(): TopicRegistryState;
 /**
@@ -61,9 +103,17 @@ export declare class TopicRegistry {
     private readonly byTopic;
     /** In-flight create promises, keyed by session, to dedupe concurrent creates. */
     private readonly inflight;
+    /** Newly-created records being durably published; never routable until committed. */
+    private readonly staged;
+    /** Socket-specific provenance for transient endpoint claims. */
+    private readonly transientClaimants;
+    /** Endpoint claims registered before a remote topic create can publish a record. */
+    private readonly creatingBindings;
     /** Monotonic authority epochs, including deletion fences for absent records. */
     private readonly epochs;
     constructor(state?: TopicRegistryState);
+    /** Replace all runtime state after a successfully persisted staged publication. */
+    replace(state: TopicRegistryState): void;
     /** Merge serialized state and normalize authority fields from older releases. */
     load(state: TopicRegistryState): void;
     private rebuildInboundRoutes;
@@ -71,13 +121,39 @@ export declare class TopicRegistry {
     sessionForTopic(topicId: string): string | undefined;
     /** All session ids with a persisted topic record. */
     sessionIds(): string[];
+    /** Persisted remote deletes that must be reconciled before recovery can proceed. */
+    deletePendingSessionIds(): string[];
     /** The existing topic record for a session, if any. */
     get(sessionId: string): TopicRecord | undefined;
+    /** Current immutable authority epoch for a creation lease. */
+    authorityEpoch(sessionId: string): number;
+    /** Whether this session has an active, unambiguous topic authority. */
+    isActiveUnambiguous(sessionId: string): boolean;
+    /**
+     * Resolve endpoint authority for identity-less replay. An endpoint may bootstrap
+     * only when no committed, staged, or pre-create claim can own it; malformed
+     * partial bindings and deletion fences deliberately fail closed.
+     */
+    endpointAuthority(binding: TopicEndpointBinding, excludedTransientClaimant?: object): TopicEndpointAuthority;
+    /** Resolve a uniquely bound logical owner for callers that only need the owner. */
+    uniqueSessionForEndpoint(binding: TopicEndpointBinding): string | undefined;
+    /** Whether this exact session owns the complete durable endpoint binding. */
+    matchesEndpoint(sessionId: string, binding: TopicEndpointBinding): boolean;
+    /**
+     * Rebind an existing topic to an authenticated successor endpoint. The exact
+     * logical session id is proved by replay before this method is called. A
+     * rotated credential may replace only an inactive incumbent; concurrent
+     * incumbents, cross-chat records, malformed evidence, collisions, and delete
+     * fences remain fail-closed.
+     */
+    bindEndpoint(sessionId: string, binding: TopicEndpointBinding, activeEndpointKeys?: ReadonlySet<string>, allowEndpointRotation?: boolean): "bound" | "unchanged" | "rejected";
+    /** Undo a failed durable endpoint migration without disturbing concurrent metadata writers. */
+    restoreEndpointBinding(sessionId: string, expected: TopicEndpointBinding, previous: Pick<TopicRecord, "chatId" | "endpointKey" | "endpointDigest" | "endpointGeneration" | "endpointIncarnation">): boolean;
     /**
      * Return the existing active topic for `sessionId`, or create one via
      * `create` (called only on first use).
      */
-    getOrCreateTopic(sessionId: string, create: () => Promise<unknown>, now?: () => number, name?: string): Promise<TopicRecord>;
+    getOrCreateTopic(sessionId: string, create: () => Promise<unknown>, now?: () => number, name?: string, binding?: TopicEndpointBinding, commit?: () => Promise<void>, transientClaimant?: object): Promise<TopicRecord>;
     /** Mark the identity header as sent for a session. Idempotent. */
     markIdentitySent(sessionId: string): void;
     /** Whether the identity header still needs sending for this session. */
@@ -109,14 +185,24 @@ export declare class TopicRegistry {
     markUserNamePending(sessionId: string, name: string): boolean;
     /** Commit a successfully-applied daemon topic title. */
     markNameApplied(sessionId: string, name: string): void;
+    /** Capture only authority fields that a failed delete publication may restore. */
+    captureDeleteAuthority(sessionId: string): TopicDeleteAuthoritySnapshot;
+    /** Restore a failed delete fence only while its exact authority mutation remains current. */
+    restoreDeleteAuthority(snapshot: TopicDeleteAuthoritySnapshot): boolean;
+    /** Restore the exact delete fence after a failed compensation publication. */
+    restoreDeleteFence(snapshot: TopicDeleteAuthoritySnapshot): boolean;
     /** Fence new work before the remote delete starts, including an absent in-flight create. */
     beginDelete(sessionId: string): TopicRecord | undefined;
+    /** Retain an accepted create as deletion-fenced before remote compensation can begin. */
+    fenceAcceptedCreate(sessionId: string, topicId: string, now?: () => number, name?: string, binding?: TopicEndpointBinding): TopicRecord;
+    /** Fence an accepted create only when its exact creator lease still owns the record. */
+    fenceAcceptedCreateForLease(sessionId: string, topicId: string, creationLeaseEpoch: number, now?: () => number, name?: string, binding?: TopicEndpointBinding): TopicRecord | undefined;
     /** Wait for a revoked create to settle before admitting a later lifecycle epoch. */
     awaitInflight(sessionId: string): Promise<void>;
     /** Remove only after a definite remote deletion; ambiguity deliberately retains its fence. */
     settleDelete(sessionId: string, topicId: string): boolean;
     /** Remove a topic record immediately for local/test cleanup compatibility. */
     delete(sessionId: string): boolean;
-    /** Serialise for atomic persistence beside the daemon state. */
+    /** Serialise active records plus unpublished staged creates for atomic commit. */
     serialize(): TopicRegistryState;
 }

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

@@ -3,6 +3,8 @@ export interface SdkSessionEndpoint {
     sessionId: string;
     url: string;
     token: string;
+    pid?: number;
+    stale?: boolean;
     path: string;
 }
 export interface SdkDiscoveryWarning {

package/dist/types/sdk/client/liveness.d.ts

@@ -0,0 +1,7 @@
+import type { SdkSessionEndpoint } from "./discovery";
+export type SdkEndpointLiveness = "live" | "stale" | "dead" | "unknown";
+export interface SdkEndpointSelectionError {
+    code: "endpoint_stale" | "endpoint_dead" | "endpoint_unknown" | "no_live_endpoint" | "multiple_live_endpoints" | "not_found";
+}
+export declare function classifyEndpoint(endpoint: SdkSessionEndpoint): SdkEndpointLiveness;
+export declare function selectLiveEndpoint(records: readonly SdkSessionEndpoint[], explicitSessionId?: string): SdkSessionEndpoint | SdkEndpointSelectionError;

package/dist/types/sdk/transport/auth-preface.d.ts

@@ -0,0 +1,9 @@
+import type * as net from "node:net";
+type AuthFailureCode = "auth_missing" | "auth_malformed" | "auth_invalid" | "auth_oversize" | "auth_timeout" | "unsupported_version";
+export declare class AuthPrefaceError extends Error {
+    readonly code: AuthFailureCode;
+    constructor(code: AuthFailureCode);
+}
+/** Consumes the one-shot socket authentication preface and leaves later bytes readable. */
+export declare function authenticatePreface(socket: net.Socket, token: string): Promise<Buffer>;
+export {};

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

@@ -0,0 +1,12 @@
+export { DEFAULT_PENDING_CEILING_BYTES, MIN_PENDING_CEILING_BYTES, REQUEST_FRAME_BYTES, } from "./relay";
+export { startSocketServe } from "./socket";
+export { startStdioServe } from "./stdio";
+export type ServeOptions = {
+    url: string;
+    token: string;
+    pendingCeilingBytes: number;
+};
+export type ServeHandle = {
+    close(): Promise<void>;
+    readonly done: Promise<void>;
+};

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

@@ -0,0 +1,43 @@
+import type { Readable, Writable } from "node:stream";
+export declare const REQUEST_FRAME_BYTES: number;
+export declare const DEFAULT_PENDING_CEILING_BYTES: number;
+export declare const MIN_PENDING_CEILING_BYTES: number;
+export type RelayDirection = "downstream->ws" | "ws->downstream";
+export type TransportError = {
+    type: "transport_error";
+    code: "frame_oversize" | "pending_overflow" | "protocol_error";
+    direction?: RelayDirection;
+};
+export type RelayPair = {
+    close(): Promise<void>;
+    readonly done: Promise<void>;
+};
+export declare class RelayOpenAbortedError extends Error {
+    constructor();
+}
+export type RelayWebSocketEvent = {
+    data?: unknown;
+};
+export type RelayWebSocket = {
+    readonly bufferedAmount: number;
+    readonly readyState: number;
+    close(): void;
+    send(data: string): void;
+    addEventListener(type: string, listener: (event: RelayWebSocketEvent) => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: string, listener: (event: RelayWebSocketEvent) => void): void;
+};
+export type RelayOptions = {
+    url: string;
+    token: string;
+    pendingCeilingBytes: number;
+    downstream: Readable;
+    downstreamSink: Writable;
+    initialDownstreamBytes?: Buffer;
+    onTransportError: (error: TransportError) => void;
+    webSocketFactory?: (url: string) => RelayWebSocket;
+    signal?: AbortSignal;
+};
+/** Starts a dedicated raw-WebSocket relay for exactly one downstream stream. */
+export declare function startRelayPair(options: RelayOptions): Promise<RelayPair>;

package/dist/types/sdk/transport/serve-cli.d.ts

@@ -0,0 +1,4 @@
+/** Resolves the pending ceiling with flag > env > default precedence; exported for tests. */
+export declare function resolveServePendingCeiling(flagValue: string | undefined, envValue: string | undefined): number;
+/** Attaches a stdio or Unix-socket relay to one live SDK session endpoint. */
+export declare function runSdkServe(argv: string[]): Promise<void>;

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

@@ -0,0 +1,7 @@
+import type { ServeHandle, ServeOptions } from "./index";
+import type { RelayOptions } from "./relay";
+/** Serves authenticated SDK JSONL clients over a private Unix-domain socket. */
+export declare function startSocketServe(options: ServeOptions & {
+    socketPath: string;
+    webSocketFactory?: RelayOptions["webSocketFactory"];
+}): Promise<ServeHandle>;

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

@@ -0,0 +1,3 @@
+import type { ServeHandle, ServeOptions } from "./index";
+/** Serves one parent-owned JSONL connection over the process standard streams. */
+export declare function startStdioServe(options: ServeOptions): Promise<ServeHandle>;

package/dist/types/session/agent-session.d.ts

@@ -15,6 +15,7 @@
 import { type Agent, type AgentContext, type AgentEvent, type AgentLoopConfig, type AgentMessage, type AgentState, type AgentTool, type MidRunMaintenanceOutcome, type StablePrefixSnapshot, ThinkingLevel } from "@gajae-code/agent-core";
 import { type CompactionResult, type EmergencyCompactionSample } from "@gajae-code/agent-core/compaction";
 import type { AssistantMessage, Effort, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, TextContent, ToolCall, ToolChoice, Usage, UsageReport } from "@gajae-code/ai";
+import { type BtwTextExchange } from "./btw-contract";
 export interface ForkContextSeedMetadata {
     sourceSessionId: string;
     parentMessageCount: number;
@@ -392,8 +393,29 @@ interface EphemeralTurnBaseArgs {
     onTextDelta?: (delta: string) => void;
     signal?: AbortSignal;
 }
-export type EphemeralTurnArgs = (EphemeralTurnBaseArgs & {
+export interface BtwRoleTextMessage {
+    role: "user" | "assistant";
+    text: string;
+}
+export interface BtwConversationScope {
+    model: Model;
+    systemPrompt: string[];
+    messages: BtwRoleTextMessage[];
+    thinkingLevel: ThinkingLevel;
+    hideThinkingSummary: boolean;
+    serviceTier: ServiceTier | undefined;
+    credentialSessionId: string;
+    providerAffinitySessionId: string;
+    sideSessionId: string;
+}
+export interface BtwTurnCapture {
+    question: string;
+    scope: BtwConversationScope | undefined;
+}
+export type EphemeralTurnArgs = (Omit<EphemeralTurnBaseArgs, "promptText"> & {
     purpose: "btw";
+    turn: BtwTurnCapture;
+    contextExchanges?: readonly BtwTextExchange[];
 }) | (EphemeralTurnBaseArgs & {
     purpose?: "background";
     /** Internal caller-supplied, non-persistent context such as the IRC roster. */
@@ -1271,11 +1293,12 @@ export declare class AgentSession {
         timestamp?: number;
     }): void;
     emitSubagentSteerRelayObservation(record: CustomMessage): void;
+    createBtwConversationScope(instruction: string): BtwConversationScope;
     /**
-     * Run a single ephemeral side-channel turn against this session's current
-     * model + system prompt + history. No tools are used and session history is
-     * not modified. Background turns retain the IRC/session behavior used by
-     * autoreplies; `/btw` turns use an isolated committed-context policy.
+     * Run a single ephemeral side-channel turn without modifying session history.
+     * Background turns retain IRC/session behavior. `/btw` turns require a
+     * pre-frozen, visible-text-only scope and bypass extension context transforms,
+     * provider observability hooks, and session persistence surfaces.
      */
     runEphemeralTurn(args: EphemeralTurnArgs): Promise<EphemeralTurnResult>;
     /**

package/dist/types/session/btw-contract.d.ts

@@ -0,0 +1,16 @@
+export declare const BTW_MAX_CONTEXT_TURNS = 12;
+export declare const BTW_MAX_CONTEXT_UTF8_BYTES: number;
+export declare const BTW_MAX_QUESTION_UTF8_BYTES: number;
+export declare const BTW_MAX_ANSWER_UTF8_BYTES: number;
+export declare const BTW_MAX_ERROR_UTF8_BYTES: number;
+export declare const BTW_STREAM_IDLE_TIMEOUT_MS = 30000;
+export declare const BTW_STREAM_TOTAL_TIMEOUT_MS = 120000;
+export interface BtwTextExchange {
+    question: string;
+    answer: string;
+}
+export declare function utf8ByteLength(text: string): number;
+export declare function truncateUtf8(text: string, maxBytes: number): string;
+export declare function sanitizeBtwError(text: string): string;
+export declare function exchangeUtf8Bytes(exchange: BtwTextExchange): number;
+export declare function boundBtwExchanges(exchanges: readonly BtwTextExchange[]): BtwTextExchange[];

package/dist/types/session/internal/managed-session-scope.d.ts

@@ -1,5 +1,6 @@
 import * as native from "@gajae-code/natives";
 import type { ResumeSessionIdentity } from "../session-manager";
+import { type ManagedDirectoryRoot, type ManagedSessionSecurityPolicy } from "./managed-session-storage";
 export declare const MANAGED_SESSION_LAYOUT_VERSION: 2;
 export declare const MANAGED_SESSION_IDENTITY_VERSION: 1;
 export declare const MANAGED_SESSION_BINDING_FILE = ".gjc-managed-session-scope.v2.json";
@@ -15,12 +16,22 @@ export interface ManagedScope {
     directoryPath: string;
     platform: "posix" | "win32";
 }
+/**
+ * Opaque managed writer authority captured by a trusted destination. The open
+ * transaction must use this authority rather than reacquiring its root from a
+ * pathname after resume inspection.
+ */
+export interface ManagedCandidateWriteAuthority {
+    readonly rootAuthority: ManagedDirectoryRoot;
+    readonly retainedAuthority?: native.RecoveryFsRoot;
+    readonly retainedDirectory?: string;
+}
 export declare function managedDirectoryAuthorityForScope(scope: ManagedScope): native.RecoveryFsRoot | undefined;
 export declare function managedDirectoryIdentityForScope(scope: ManagedScope): {
     dev: bigint;
     ino: bigint;
 };
-export declare function managedRootForScope(scope: ManagedScope): import("./managed-session-storage").ManagedDirectoryRoot;
+export declare function managedRootForScope(scope: ManagedScope): ManagedDirectoryRoot;
 export type ManagedMigrationPolicy = "copy-retain" | "disabled";
 export type ManagedScopeErrorCode = "cwd_missing" | "cwd_not_directory" | "identity_unavailable" | "network_unsupported" | "sessions_root_unavailable" | "binding_conflict" | "binding_invalid";
 export type ManagedScopeResolution = {
@@ -86,24 +97,27 @@ export declare const computeManagedScopeDigest: typeof scopeDigest;
  * attacker-plantable component below the root.
  */
 export declare function canonicalizeTrustedPath(target: string): string;
-export declare function resolveManagedScope(input: {
+interface ManagedScopeInput {
     cwd: string;
     agentDir: string;
     sessionsRoot: string;
-}): ManagedScopeResolution;
-export declare function ensureManagedScope(scope: ManagedScope): Promise<ManagedScopeResolution>;
+}
+export declare function resolveManagedScope(input: ManagedScopeInput): ManagedScopeResolution;
+/** Resolve a scope for a synchronous write without mutating an existing ACL mismatch. */
+export declare function resolveManagedScopeForWrite(input: ManagedScopeInput): ManagedScopeResolution;
+export declare function ensureManagedScope(scope: ManagedScope, policy?: ManagedSessionSecurityPolicy): Promise<ManagedScopeResolution>;
 /** Synchronously create and validate the v2 binding before a default session writer exists. */
-export declare function prepareManagedSessionScopeForWriteSync(scope: ManagedScope): ManagedScopeResolution;
+export declare function prepareManagedSessionScopeForWriteSync(scope: ManagedScope, policy?: ManagedSessionSecurityPolicy, authority?: ManagedCandidateWriteAuthority): ManagedScopeResolution;
 export declare function listManagedCandidates(scope: ManagedScope): ManagedCandidateListing;
 /** Resume tombstoned cleanup under its original operation lease without restoring retired candidates. */
 export declare function reconcileManagedTombstones(scope: ManagedScope): Promise<void>;
 /** Create the v2 binding and private write protocol directories before managed writes. */
-export declare function prepareManagedSessionScopeForWrite(scope: ManagedScope): Promise<ManagedScopeResolution>;
+export declare function prepareManagedSessionScopeForWrite(scope: ManagedScope, policy?: ManagedSessionSecurityPolicy, authority?: ManagedCandidateWriteAuthority, expectedCandidate?: ManagedCandidate, expectedIdentity?: ResumeSessionIdentity): Promise<ManagedScopeResolution>;
 /**
  * Open a validated candidate for mutation. Legacy transcripts are copied exactly once
  * into v2 and retained at their original location; no transcript data is merged.
  */
-export declare function openManagedCandidateForWrite(scope: ManagedScope, candidate: ManagedCandidate, migrationPolicy?: ManagedMigrationPolicy): Promise<ManagedOpenCandidateResult>;
+export declare function openManagedCandidateForWrite(scope: ManagedScope, candidate: ManagedCandidate, expectedIdentityOrMigrationPolicy?: ResumeSessionIdentity | ManagedMigrationPolicy, migrationPolicy?: ManagedMigrationPolicy, authority?: ManagedCandidateWriteAuthority): Promise<ManagedOpenCandidateResult>;
 /** Tombstone a verified managed candidate before exact-identity deletion. */
 export declare function deleteManagedSessionCandidate(scope: ManagedScope, candidate: ManagedCandidate): Promise<ManagedDeleteCandidateResult>;
 export {};