@gajae-code/coding-agent 0.16.7 → 0.17.1

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

@@ -1,3 +1,4 @@
+import type { NativeBrokerRestartIntent, NativeBrokerRestartIntentIdentity } from "@gajae-code/natives";
 import { processIncarnation } from "./process-incarnation";
 import { SDK_STATE_VERSION } from "./state-version";
 export type BrokerPublicationObservation = "owned" | "absent" | "replaced" | "ambiguous";
@@ -6,12 +7,30 @@ export interface RetainedBrokerDiscovery {
     observeAsync(): Promise<BrokerPublicationObservation>;
     heartbeat(heartbeatAt: number): Promise<boolean>;
     close(): void;
+    /** Owner-side `prepared`: exclusively creates the durable restart-intent slot. */
+    prepareRestartIntent(intent: NativeBrokerRestartIntent): Promise<boolean>;
+    /** Owner-side `prepared` -> `committed`: rewrites the exact slot prepare created. */
+    commitRestartIntent(intent: NativeBrokerRestartIntent): Promise<boolean>;
+    /** Owner-side cancel of this process's own prepared/committed slot. */
+    cancelRestartIntent(): Promise<boolean>;
+    /** Successor-side clear of a predecessor's slot this process never prepared. */
+    clearForeignRestartIntent(identity: NativeBrokerRestartIntentIdentity): Promise<boolean>;
 }
 export declare const BROKER_HEARTBEAT_TTL_MS = 15000;
 export interface BrokerDiscovery {
     version: typeof SDK_STATE_VERSION;
     protocolVersion: 3;
     packageGeneration: string;
+    /**
+     * The runtime image this broker launches internal SDK processes with. Present
+     * whenever the publisher could classify its own runtime, including when that
+     * image was already gone at publication time -- absence is the reader's
+     * verdict to reach, not a reason to publish nothing. Absent only for records
+     * written before this field existed and for a publisher whose runtime
+     * evidence could not be classified at all; readers then reuse the broker as
+     * before rather than retiring it on unknown evidence.
+     */
+    runtime?: string;
     ownerId: string;
     pid: number;
     incarnation: string;
@@ -21,6 +40,14 @@ export interface BrokerDiscovery {
     token: string;
     startedAt: number;
     heartbeatAt: number;
+    restartRequestId?: string;
+    rootDigest?: string;
+}
+export interface BrokerRestartIntent {
+    requestId: string;
+    lease: string;
+    expiresAt: number;
+    phase?: "prepared" | "committed" | "cancelled";
 }
 export type RedactedBrokerDiscovery = Omit<BrokerDiscovery, "token"> & {
     token: "[redacted]";
@@ -38,4 +65,15 @@ export declare function publishBrokerDiscovery(agentDir: string, discovery: Brok
 /** Heartbeat through retained authority, or the explicit Windows compatibility path. */
 export declare function heartbeatBrokerDiscoveryRetained(publication: RetainedBrokerDiscovery, heartbeatAt: number): Promise<boolean>;
 export declare function readBrokerDiscovery(agentDir: string, ttlMs?: number): Promise<BrokerDiscovery | null>;
+/**
+ * The restart-intent slot lives directly beneath `sdk/`, independent of
+ * `sdk/broker.lock/` -- so it durably survives a stale-lock reclaim that
+ * renames the incumbent's lock directory aside (`Broker#reclaimStaleLock`).
+ */
+export declare const brokerRestartIntentPath: (agentDir: string) => string;
+export interface BrokerRestartIntentWithIdentity extends BrokerRestartIntent {
+    /** Existing platform file identity, for a successor's exact-identity clear. */
+    identity: NativeBrokerRestartIntentIdentity;
+}
+export declare function readBrokerRestartIntent(agentDir: string): Promise<BrokerRestartIntentWithIdentity | null>;
 export declare function redactBrokerDiscovery(discovery: BrokerDiscovery): RedactedBrokerDiscovery;

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

@@ -0,0 +1,79 @@
+import { SdkClient } from "../client/client";
+import type { BrokerRestartOwnerIdentity, BrokerRestartPrepareResult, BrokerRestartResult } from "./broker";
+import { type BrokerDiscovery } from "./discovery";
+export interface DoctorBrokerRestartOptions {
+    agentDir: string;
+    deadlineMs?: number;
+    drain?: boolean;
+    requestId?: string;
+}
+/**
+ * Concrete typed before/after-effect outcome of a full D8 broker restart
+ * attempt. Every refusal names the exact stage and, where the broker itself
+ * refused, the broker's own typed error code -- never an opaque thrown
+ * message standing in for a decision this adapter could name.
+ */
+export type DoctorBrokerRestartOutcome = {
+    kind: "restarted";
+    requestId: string;
+    oldOwner: BrokerRestartOwnerIdentity;
+    successor: BrokerDiscovery;
+    /** True when an already-committed successor for this exact request was found and reused, not spawned. */
+    adopted: boolean;
+} | {
+    kind: "owner_unavailable";
+    reason: "no_discovery" | "owner_not_confirmed_live";
+} | {
+    kind: "prepare_refused";
+    code: string;
+    message: string;
+} | {
+    kind: "commit_refused";
+    code: string;
+    message: string;
+} | {
+    kind: "old_owner_exit_timeout";
+    requestId: string;
+    oldOwner: BrokerRestartOwnerIdentity;
+} | {
+    kind: "successor_refused";
+    requestId: string;
+    oldOwner: BrokerRestartOwnerIdentity;
+    reason: "deadline_elapsed" | "intent_not_committed" | "spawn_failed" | "spawn_exited_before_publication" | "publication_timeout";
+    detail?: string;
+};
+export declare function prepareDoctorBrokerRestart(client: SdkClient, discovery: BrokerDiscovery, options: DoctorBrokerRestartOptions & {
+    requestId: string;
+}): Promise<BrokerRestartResult>;
+export declare function commitDoctorBrokerRestart(client: SdkClient, discovery: BrokerDiscovery, prepared: BrokerRestartPrepareResult, requestId: string): Promise<BrokerRestartResult>;
+export declare function cancelDoctorBrokerRestart(client: SdkClient, requestId: string): Promise<BrokerRestartResult>;
+/**
+ * Owner-side prepare/commit/stop, positive-exit-confirmed cleanup, then
+ * exactly one successor launch or adoption. The exact sequence:
+ *
+ * 1. Read the CURRENT discovery snapshot (never a stale caller-supplied one)
+ *    and prove its owner is live via a real connected client, not an
+ *    incarnation string comparison alone.
+ * 2. `prepare_restart` against that exact owner tuple/generation; on any
+ *    prepare refusal, cancel the reservation and return the broker's own
+ *    typed refusal rather than throwing.
+ * 3. `commit_restart` with the exact lease/occupancyEpoch prepare returned.
+ *    Once committed, the owner is durably retiring: cancellation is no longer
+ *    safe and this function must never call cancel past this point.
+ * 4. Close the client (every path below runs with the client closed).
+ * 5. Wait, bounded by the request deadline, for `observeProcessIncarnation`
+ *    to positively confirm the exact old pid is OS-absent -- never inferred
+ *    from a changed/missing incarnation read, and never from discovery
+ *    disappearing (a crashed writer can leave a stale discovery file behind
+ *    just as easily as a clean exit can remove it).
+ * 6. Launch (or adopt an already-published) exactly one successor for this
+ *    requestId, holding the shared startup exclusion only around the launch
+ *    decision itself -- never across the successor's own publication wait,
+ *    which would deadlock this process against its own spawned child.
+ *
+ * The successor clears the durable committed intent itself, from inside its
+ * own `Broker#start()`, only after its own publication has independently
+ * proven it owns the root -- never here, and never before that proof exists.
+ */
+export declare function restartBrokerForDoctor(options: DoctorBrokerRestartOptions): Promise<DoctorBrokerRestartOutcome>;
+export type { BrokerRestartResult };

package/dist/types/sdk/broker/endpoint-authority.d.ts

@@ -13,6 +13,13 @@ export type IndexedEndpointAuthority = {
     endpointMtimeMs?: number;
     endpointFileId?: string;
 };
+/** Derive the broker-compatible opaque authority for one indexed endpoint generation. */
+export declare function endpointIncarnation(record: {
+    endpointGeneration: number;
+    endpointMtimeMs?: number;
+    pid: number;
+    endpointFileId?: string;
+}, sessionId: string): string | undefined;
 /**
  * Reads one endpoint from the descriptor opened for its pathname. The opened
  * object must remain a small, singly-linked regular file with stable identity

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

@@ -4,8 +4,22 @@ import { type FileLockOptions } from "../../config/file-lock";
 import { type BrokerDiscovery } from "./discovery";
 import { type SdkInternalSpawnCommand } from "./runtime";
 export declare function isBrokerGenerationCompatible(discovery: BrokerDiscovery | null): boolean;
+/**
+ * A live incumbent stops being reusable once the runtime image it launches
+ * internal processes with is provably gone. A broker outlives its own executable
+ * (a package manager replacing the interpreter it was started from, an install
+ * directory swapped underneath it): it keeps heartbeating and answering
+ * requests, but every `session.create` it accepts is refused at spawn time.
+ * Retiring it here repairs the endpoint before a caller reaches session
+ * creation. Absent runtime evidence -- a record predating the field, or a
+ * publisher that could not classify its own runtime at all -- and evidence this
+ * caller merely cannot inspect both keep the incumbent reusable.
+ */
+export declare function isBrokerReusable(discovery: BrokerDiscovery | null): Promise<boolean>;
 export interface EnsureBrokerSettings {
     agentDir: string;
+    /** Only an authorized doctor successor may consume a restart-intent publication. */
+    restartRequestId?: string;
     heartbeatTtlMs?: number;
     /**
      * Environment for the spawned detached broker. Defaults to `process.env`; tests

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

@@ -233,6 +233,8 @@ export declare function probePublishedReadyAuthorityForTest(root: string, id: st
 export declare function removeOwnedLifecycleArtifactsForTest(root: string, id: string, expected: EffectMarker): Promise<boolean>;
 /** Test seam for the worktree occupancy boundary. */
 export declare function worktreeOccupantForTest(sessions: IndexedSession[], worktreePath: string, observe?: (pid: number, expectedIncarnation: string | undefined) => ProcessObservation): string | null;
+/** Test seam for the forced stale-worktree release boundary. */
+export declare function releaseForcedStaleWorktreeForTest(broker: Broker, id: string, expected: IndexedSession): Promise<void>;
 export declare function canonicalDeleteLocatorPath(pathname: string): string;
 export interface LifecycleExecutionOutcome {
     response: BrokerResponse;

package/dist/types/sdk/broker/process-incarnation.d.ts

@@ -11,6 +11,56 @@ export interface ProcessIncarnationOptions {
 export declare function parseDarwinProcessIncarnation(info: Uint8Array): string | undefined;
 /** Whether `value` is a canonical process-incarnation string (`linux:`/`darwin:`/`windows:`). */
 export declare function isProcessIncarnation(value: unknown): value is string;
+/**
+ * Read-only, non-mutating observation of whether a pid currently names a
+ * verifiable process incarnation.
+ *
+ * - `status: "present"` carries the exact kernel-reported identity evidence
+ *   (the same value `processIncarnation` returns).
+ * - `status: "absent"` is positive OS-confirmed death proof (POSIX
+ *   `kill(pid, 0)` returning `ESRCH`, or Windows `OpenProcess` failing with
+ *   the exact code the kernel reports for an unresolved client id) — never a
+ *   permission failure or an ambiguous disappearance.
+ * - `status: "unknown"` covers every inconclusive case (invalid pid, missing
+ *   or unavailable native addon, permission denial, platform limitation).
+ *   Callers MUST NOT treat this as death proof.
+ */
+export type ProcessIncarnationObservation = {
+    status: "present";
+    incarnation: string;
+} | {
+    status: "absent";
+} | {
+    status: "unknown";
+    reasonCode: string;
+};
+/** Raw shape returned by the native `Process.observe` binding. */
+export type NativeProcessObserveResult = {
+    status?: unknown;
+    incarnation?: unknown;
+    reasonCode?: unknown;
+};
+export interface ObserveProcessIncarnationOptions {
+    /**
+     * Injectable native observe function, used by tests to exercise error
+     * classification (malformed shapes, unavailable addon) without a global
+     * mock. Defaults to the real `Process.observe` binding.
+     */
+    observe?: (pid: number) => NativeProcessObserveResult;
+}
+/**
+ * Read-only process-incarnation observation for `pid`, distinguishing a
+ * proved-live incarnation from positive OS-confirmed absence from every
+ * inconclusive outcome. Never signals, kills, reaps, waits on, or spawns any
+ * process — it only reads existing native process-table state via
+ * `Process.observe`.
+ *
+ * `pid` must be a positive safe integer; any other value (including `0`,
+ * negative, `NaN`, or non-integer) is reported as `unknown` rather than
+ * risking an ambiguous platform-specific interpretation (`0`/negative PIDs
+ * address process groups on POSIX, not a single process).
+ */
+export declare function observeProcessIncarnation(pid: number, options?: ObserveProcessIncarnationOptions): ProcessIncarnationObservation;
 /** A PID is reusable; bind it to the strongest OS-provided process start incarnation available. */
 export declare function processIncarnation(pid: number, options?: ProcessIncarnationOptions): string | undefined;
 export {};

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

@@ -26,8 +26,34 @@ export interface SdkInternalRuntimeDescriptorTestOptions {
     configPath?: string;
     bunAvailable?: boolean;
 }
+/**
+ * The on-disk image internal SDK spawns from this process execute, or
+ * `undefined` only when runtime evidence cannot be classified at all. It comes
+ * from the same marker authority a spawn uses, but deliberately not from the
+ * source-tree assets a spawn also proves (CLI entrypoint, isolated Bun config,
+ * package identity): a failure to read one of those says nothing about the
+ * runtime image, and publishing `undefined` for it would blind every reader.
+ *
+ * An image the classification names but this process can no longer prove is
+ * still published. `undefined` means only "no evidence" -- readers keep such a
+ * broker reusable, so a broker whose own image vanished before it published
+ * must not hide behind it.
+ */
+export declare function sdkInternalRuntimeImage(): string | undefined;
+/**
+ * Whether a published runtime image is still a regular file on disk. A resident broker keeps
+ * answering requests after the executable it was started from is deleted (a
+ * Homebrew Bun upgrade removing the Cellar path, an install directory swapped
+ * underneath it), yet every internal spawn it then attempts is refused. Callers
+ * use this to retire such an incumbent before a session launch reaches it, so it
+ * answers `true` on every inconclusive outcome, including a probe that outlives
+ * its bound: a false retirement kills a healthy broker.
+ */
+export declare function isSdkInternalRuntimeImagePresent(file: string): Promise<boolean>;
 /** Resolve the production descriptor from the statically imported marker and current Bun runtime evidence. */
 export declare function resolveSdkInternalSpawnCommand(action: SdkInternalAction): SdkInternalSpawnCommand;
 /** Test hook: injects runtime evidence without weakening the production marker authority. */
 export declare function resolveSdkInternalSpawnCommandForTest(action: SdkInternalAction, options: SdkInternalRuntimeDescriptorTestOptions): SdkInternalSpawnCommand;
+/** Test hook: the publication decision under injected evidence, same authority as production. */
+export declare function sdkInternalRuntimeImageForTest(options: SdkInternalRuntimeDescriptorTestOptions): string | undefined;
 export {};

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

@@ -77,6 +77,13 @@ export interface SessionIndexEvent {
     endpointFileId?: string;
     lifecycleRequestId?: string;
     terminalUncertain?: boolean;
+    /**
+     * Distinguishes the terminal-uncertain claim written by a forced stop of a
+     * stale-endpoint session from the one written by the fail-closed tail of an
+     * ordinary teardown. Only the forced claim releases the session's worktree;
+     * see `worktreeOccupant`.
+     */
+    forcedStaleRelease?: boolean;
     /** OS process incarnation (C1); absent on legacy v1/v2 events. */
     hostIncarnation?: string;
     /** Present on host_heartbeat checkpoints (C2). */
@@ -99,6 +106,8 @@ export interface IndexedSession {
     indexSeq: number;
     lifecycleRequestId?: string;
     terminalUncertain?: boolean;
+    /** True only for a terminal-uncertain claim written by a forced stale-worktree release. */
+    forcedStaleRelease?: boolean;
     hostIncarnation?: string;
     identityProvenance: SessionIdentityProvenance;
     activity?: SessionActivity;
@@ -192,7 +201,7 @@ export declare class SessionIndex {
     refresh(): Promise<void>;
     get indexSeq(): number;
     append(input: Omit<SessionIndexEvent, "version" | "indexSeq" | "checksum" | "ts"> & Partial<Pick<SessionIndexEvent, "ts">>): Promise<SessionIndexEvent>;
-    unregisterIfCurrent(expected: IndexedSession): Promise<boolean>;
+    unregisterIfCurrent(expected: Pick<SessionIndexEvent, "sessionId" | "locator" | "endpointGeneration" | "pid" | "indexSeq" | "endpointMtimeMs" | "endpointFileId" | "lifecycleRequestId" | "processIncarnation" | "hostIncarnation">): Promise<boolean>;
     /** Hold the canonical index lock across an authority-sensitive operation. */
     withLocked<T>(callback: () => Promise<T>): Promise<T>;
     snapshot(): Promise<void>;
@@ -229,12 +238,12 @@ export declare class SessionIndex {
         lifecycleRequestId?: string;
     }): IndexedSession | undefined;
     /** Returns the latest identity-bound terminal event, if retained. */
-    findSessionTerminalEvidence(expected: Pick<IndexedSession, "sessionId" | "locator" | "endpointGeneration" | "pid" | "processIncarnation" | "hostIncarnation" | "endpointMtimeMs" | "lifecycleRequestId">): {
+    findSessionTerminalEvidence(expected: Pick<IndexedSession, "sessionId" | "locator" | "endpointGeneration" | "pid" | "processIncarnation" | "hostIncarnation" | "endpointMtimeMs" | "endpointFileId" | "lifecycleRequestId">): {
         type: "host_unregistered" | "session_closed" | "session_deleted";
         indexSeq: number;
     } | undefined;
     /** Returns the latest identity-bound session_closed evidence, even after a tombstone. */
-    findSessionClosedEvidence(expected: Pick<IndexedSession, "sessionId" | "locator" | "endpointGeneration" | "pid" | "processIncarnation" | "hostIncarnation" | "endpointMtimeMs" | "lifecycleRequestId">): number | undefined;
+    findSessionClosedEvidence(expected: Pick<IndexedSession, "sessionId" | "locator" | "endpointGeneration" | "pid" | "processIncarnation" | "hostIncarnation" | "endpointMtimeMs" | "endpointFileId" | "lifecycleRequestId">): number | undefined;
     /**
      * Production coalesced heartbeat checkpoint pass (C2): appends one
      * `host_heartbeat` per session at most once per {@link SESSION_HEARTBEAT_INTERVAL_MS}.
@@ -247,7 +256,7 @@ export declare class SessionIndex {
      * unknown/not-live (never fresh forever). Returns the number of checkpoints written.
      */
     checkpointLiveHeartbeats(now?: number): Promise<number>;
-    hostUnregisteredAfter(registration: Pick<IndexedSession, "sessionId" | "locator" | "endpointGeneration" | "pid" | "indexSeq" | "lifecycleRequestId" | "hostIncarnation" | "processIncarnation">): {
+    hostUnregisteredAfter(registration: Pick<IndexedSession, "sessionId" | "locator" | "endpointGeneration" | "pid" | "indexSeq" | "lifecycleRequestId" | "hostIncarnation" | "processIncarnation" | "endpointFileId">): {
         indexSeq: number;
         lifecycleRequestId?: string;
     } | undefined;

package/dist/types/sdk/broker/worktree-occupancy.d.ts

@@ -24,5 +24,19 @@ export declare function observeProcess(pid: number, expectedIncarnation: string
  * `uncertain` counts as occupied: refusing a launch is recoverable by picking
  * another worktree name, whereas two live sessions sharing a checkout corrupts
  * work already done.
+ *
+ * A row carrying BOTH `terminalUncertain` and `forcedStaleRelease` is the one
+ * exception. That pair is written only by the forced stop of a stale-endpoint
+ * session: teardown was requested explicitly, so parking its worktree until an
+ * OS probe happens to prove exit would leave the checkout locked indefinitely
+ * (#5581) exactly when the probe returns `uncertain`. Such a row is released
+ * regardless of the process observation.
+ *
+ * `terminalUncertain` on its own is not enough. The fail-closed tail of a
+ * signal-escalated teardown sets it after SIGKILL without ever proving the child
+ * gone, so that process may still be running in the checkout; releasing on the
+ * flag alone would let a second session into the same worktree. Those rows stay
+ * under the strict "only definitive exit releases" rule like every other
+ * ordinary retained row.
  */
 export declare function worktreeOccupant(sessions: readonly IndexedSession[], worktreePath: string, observe?: (pid: number, expectedIncarnation: string | undefined) => ProcessObservation): string | null;

package/dist/types/sdk/bus/chat-daemon-cli.d.ts

@@ -7,6 +7,22 @@ export interface ChatDaemonRuntimeHandle {
     transportHealthy?(): boolean;
     /** Executes operator commands that must run inside the owning daemon. */
     bindExistingRoot?(request: ChatDaemonCommandBindInput): Promise<ChatDaemonCommandOutcome>;
+    prepareDoctorRestart?(): void;
+    cancelDoctorRestart?(): void;
+    doctorOccupancy?(): {
+        attached: number;
+        inflight: number;
+        inbound: number;
+        outbound: number;
+        cleanup: number;
+    };
+    doctorRestartReady?(): boolean;
+    doctorRestartStatus?(identity: {
+        owner: "discord" | "slack";
+        ownerId: string;
+        generation: number;
+        incarnation: string;
+    }, requestId: string, leaseExpiresAt: number): unknown;
 }
 export interface RunChatDaemonInternalDeps {
     processPid?: number;

package/dist/types/sdk/bus/chat-daemon-control.d.ts

@@ -1,5 +1,6 @@
 import type { Settings } from "../../config/settings";
 import type { BuiltInDaemonController, DaemonOperationOptions, DaemonOperationResult, DaemonRuntimeInfo, DaemonStatus } from "../../daemon/control-types";
+import { type DoctorDaemonControlRequest } from "./doctor-daemon-restart";
 export type ChatDaemonKind = "discord" | "slack";
 export type ChatDaemonAction = "stop" | "reload";
 /**
@@ -122,6 +123,14 @@ export interface ChatDaemonState {
     transportHealthy: boolean;
     generation: number;
     stoppedAt?: number;
+    /**
+     * Digest of the canonical (symlink-resolved) agent root this record was
+     * published for. Legacy records omit it and remain non-authorizing for the
+     * D9 cross-bind check: a state record without a matching rootDigest can
+     * never be treated as this root's live owner for that check, even though it
+     * is still valid for every other pre-existing owner check in this module.
+     */
+    rootDigest?: string;
 }
 /**
  * State files are untrusted persisted input. A record must be completely valid
@@ -161,12 +170,51 @@ export interface ChatDaemonControlDeps {
     sleep?: (ms: number) => Promise<void>;
     spawnReadyTimeoutMs?: number;
 }
+/**
+ * `version`/`ownerId`/`rootDigest` are the D9 cross-bind receipt delta: a
+ * legacy lock predating this generation omits them. Legacy records remain
+ * valid, signalable owner locks for every existing check in this module —
+ * they are simply non-authorizing for a D9 cross-bind check that requires a
+ * matching `ownerId`/`rootDigest` against the sibling state record.
+ */
+export interface ChatDaemonOwnerLock {
+    version?: 1;
+    pid: number;
+    incarnation: string;
+    createdAt: number;
+    ownerId?: string;
+    rootDigest?: string;
+}
+export interface ChatDaemonOwnerLockLease {
+    content: string;
+    dev: bigint;
+    ino: bigint;
+    size: bigint;
+    mtimeNs: bigint;
+    nlink: bigint;
+    parentDev: bigint;
+    parentIno: bigint;
+    sha256: string;
+}
+/** Result of a bounded, no-follow owner-lock lease capture. Only `"absent"` (ENOENT) means the lock currently does not exist; every other failure is `"unreadable"` and must never be treated as absence. */
+export type ChatDaemonOwnerLockLeaseResult = {
+    status: "present";
+    lease: ChatDaemonOwnerLockLease;
+} | {
+    status: "absent";
+} | {
+    status: "unreadable";
+};
 export declare function chatDaemonPaths(agentDir: string, kind: ChatDaemonKind): {
     dir: string;
     lock: string;
     state: string;
     control: string;
 };
+export declare function chatDoctorControlRequestPath(agentDir: string, kind: ChatDaemonKind): string;
+export declare function readChatDoctorControlRequest(agentDir: string, kind: ChatDaemonKind): Promise<DoctorDaemonControlRequest | undefined>;
+export declare function writeChatDoctorControlRequest(agentDir: string, kind: ChatDaemonKind, request: DoctorDaemonControlRequest): Promise<void>;
+export declare function clearChatDoctorControlRequest(agentDir: string, kind: ChatDaemonKind, requestId?: string): Promise<void>;
 /**
  * Configuration fingerprint that identifies which settings a daemon owner was
  * started for. `undefined` means the current settings cannot configure that
@@ -223,7 +271,7 @@ export declare class ChatDaemonController implements BuiltInDaemonController {
 export type EnsureChatDaemonResult = "disabled" | "owner_spawned" | "attached";
 export declare function ensureDiscordDaemon(settings: Settings, deps?: ChatDaemonControlDeps): Promise<EnsureChatDaemonResult>;
 export declare function ensureSlackDaemon(settings: Settings, deps?: ChatDaemonControlDeps): Promise<EnsureChatDaemonResult>;
-export declare function acquireChatDaemonOwnership(input: {
+export interface AcquireChatDaemonOwnershipInput {
     agentDir: string;
     kind: ChatDaemonKind;
     ownerId: string;
@@ -232,8 +280,40 @@ export declare function acquireChatDaemonOwnership(input: {
     incarnation?: string;
     pidAlive?: (pid: number) => boolean;
     pidIncarnation?: (pid: number) => string | undefined;
-}): Promise<boolean>;
-export declare function renewChatDaemonHeartbeat(input: {
+}
+/**
+ * Publishes this process as the `(agentDir, kind)` chat daemon owner
+ * (owner.lock + state.json). Runs behind the shared cross-process startup
+ * exclusion so it can never race a doctor startup/maintenance repair that
+ * holds the same guard (e.g. detaching a stale owner-lock quarantine) — the
+ * guard is acquired here and released before returning; the actual
+ * lock-creation/state-publication logic lives in the unlocked
+ * {@link acquireChatDaemonOwnershipLocked} so the guard is never held across
+ * a nested reacquisition of itself.
+ */
+export declare function acquireChatDaemonOwnership(input: AcquireChatDaemonOwnershipInput): Promise<boolean>;
+/**
+ * Bounded, no-follow, non-blocking owner-lock lease capture. Opens with the
+ * same `O_NOFOLLOW|O_NONBLOCK` posture as the canonical lock-info reader in
+ * config/file-lock.ts, reads at most {@link CHAT_DAEMON_OWNER_LOCK_LEASE_MAX_BYTES}
+ * bytes through the open descriptor (never an unbounded `readFile`), and
+ * revalidates identity/parent-directory metadata before and after the read so a
+ * TOCTOU replacement during the read is detected rather than silently trusted.
+ *
+ * Only `ENOENT` on the initial open means the lock is currently absent.
+ * SYMLINK, FIFO/special-file, oversize, and any other I/O failure are all
+ * `"unreadable"` — distinct from absence, and callers must not treat them as
+ * "no lock exists".
+ */
+export declare function captureChatDaemonOwnerLockLease(lock: string): Promise<ChatDaemonOwnerLockLeaseResult>;
+/**
+ * Strict: `pid`/`incarnation`/`createdAt` are always required. `version`,
+ * `ownerId`, and `rootDigest` are individually optional (legacy locks omit
+ * them), but any one that IS present must be well-formed — a malformed
+ * optional field is never silently ignored.
+ */
+export declare function isChatDaemonOwnerLock(value: unknown): value is ChatDaemonOwnerLock;
+export interface RenewChatDaemonHeartbeatInput {
     agentDir: string;
     kind: ChatDaemonKind;
     ownerId: string;
@@ -242,8 +322,16 @@ export declare function renewChatDaemonHeartbeat(input: {
     transportHealthy: boolean;
     pidAlive?: (pid: number) => boolean;
     pidIncarnation?: (pid: number) => string | undefined;
-}): Promise<boolean>;
-export declare function releaseChatDaemonOwnership(input: {
+}
+/**
+ * Renews the exact-owner heartbeat for `(agentDir, kind)`. Runs behind the
+ * shared cross-process startup exclusion so a heartbeat can never publish in
+ * the middle of a doctor startup/maintenance repair holding the same guard;
+ * the actual re-check-and-write logic lives in the unlocked
+ * {@link renewChatDaemonHeartbeatLocked}.
+ */
+export declare function renewChatDaemonHeartbeat(input: RenewChatDaemonHeartbeatInput): Promise<boolean>;
+export interface ReleaseChatDaemonOwnershipInput {
     agentDir: string;
     kind: ChatDaemonKind;
     ownerId: string;
@@ -251,4 +339,11 @@ export declare function releaseChatDaemonOwnership(input: {
     incarnation: string;
     pidAlive?: (pid: number) => boolean;
     pidIncarnation?: (pid: number) => string | undefined;
-}): Promise<void>;
+}
+/**
+ * Releases this process's `(agentDir, kind)` chat daemon ownership. Runs
+ * behind the shared cross-process startup exclusion for the same reason as
+ * {@link acquireChatDaemonOwnership}; the actual re-check-and-unpublish logic
+ * lives in the unlocked {@link releaseChatDaemonOwnershipLocked}.
+ */
+export declare function releaseChatDaemonOwnership(input: ReleaseChatDaemonOwnershipInput): Promise<void>;

package/dist/types/sdk/bus/chat-daemon-runtime.d.ts

@@ -2,6 +2,7 @@ import type { SessionRouterDeps } from "../router";
 import type { ChatDaemonCommandBindInput, ChatDaemonCommandOutcome } from "./chat-daemon-command-channel";
 import type { ChatDaemonKind } from "./chat-daemon-control";
 import type { DiscordProvider } from "./discord-provider";
+import { type DoctorDaemonIdentity, type DoctorDaemonOccupancy, type DoctorDaemonStatus } from "./doctor-daemon-restart";
 import { type SlackProviderClient } from "./slack-provider";
 export interface ChatDaemonRuntimeConfig {
     identity: string;
@@ -63,6 +64,21 @@ export declare class ChatDaemonRuntime {
     }, deps?: ChatDaemonRuntimeDeps);
     start(): Promise<void>;
     transportHealthy(): boolean;
+    /** Doctor reservation hook: stop admitting new `/sdk` command dispatch. Synchronous fence. */
+    prepareDoctorRestart(): boolean;
+    cancelDoctorRestart(): void;
+    /**
+     * Real runtime occupancy, not synthetic placeholders. `attached` is live
+     * session attachments; `inflight` is attachment (re)publication barriers
+     * currently resolving; `inbound` is admitted `/sdk` command dispatches
+     * (including operator `bindExistingRoot` binds) actually executing;
+     * `outbound` is real Discord/Slack notify/resume provider deliveries in
+     * flight; `cleanup` is provider close/retire work that has not yet
+     * settled.
+     */
+    doctorOccupancy(): DoctorDaemonOccupancy;
+    doctorRestartStatus(identity: DoctorDaemonIdentity, requestId: string, leaseExpiresAt: number): DoctorDaemonStatus;
+    doctorRestartReady(): boolean;
     /** Reconcile indexed attachments and optionally wait for their replay tails. */
     reconcile(options?: {
         waitForReplay?: boolean;

package/dist/types/sdk/bus/daemon-startup-exclusion.d.ts

@@ -0,0 +1,43 @@
+export type DaemonStartupExclusionOwner = "telegram" | "discord" | "slack";
+export interface DaemonStartupExclusionOptions {
+    /** Abort acquisition early; never releases a lease this call did not itself acquire. */
+    signal?: AbortSignal;
+    /** Upper bound on total wait while contended. Defaults to {@link DAEMON_STARTUP_EXCLUSION_DEFAULT_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/** Matches the production wall-time bound already established for other durable daemon locks. */
+export declare const DAEMON_STARTUP_EXCLUSION_DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * The canonical per-service guard path. Lives inside the SAME per-service
+ * directory as the service's ordinary owner/state artifacts (so it inherits
+ * that directory's existing parent-permission posture) but under a filename
+ * reserved exclusively for this guard — never a name any ownership,
+ * publication, or transition-marker code path reads or writes.
+ *
+ * This function only computes a path; it performs no filesystem I/O and
+ * creates nothing. (`withFileLock` itself creates the missing parent
+ * directory chain, mode 0o700, purely as lock-acquisition scaffolding — an
+ * empty directory carries no service state.)
+ */
+export declare function daemonStartupExclusionPath(agentDir: string, owner: DaemonStartupExclusionOwner): string;
+/**
+ * Run `operation` while holding the cross-process startup/maintenance
+ * exclusion for `(agentDir, owner)`. Bounded: acquisition retries back off
+ * for at most `timeoutMs` (default {@link DAEMON_STARTUP_EXCLUSION_DEFAULT_TIMEOUT_MS})
+ * and additionally honors `signal` if supplied — whichever bound is hit first
+ * rejects the acquisition. A rejected/timed-out/aborted acquisition never held
+ * a lease and therefore never releases one; it cannot touch a foreign owner's
+ * lock. On success, the lease this call acquired is released exactly once,
+ * through the same identity-bound release primitive `withFileLock` uses for
+ * every other durable lock in this codebase — never a recursive directory
+ * removal, and never a process signal.
+ *
+ * This primitive itself never reads, writes, or removes any owner/state/lock
+ * file belonging to the service; it only fences concurrent callers of this
+ * same function (and, by construction, is never consulted by ordinary
+ * ownership-acquisition or publication code, which uses its own distinct
+ * lock file).
+ */
+export declare function withDaemonStartupExclusion<T>(agentDir: string, owner: DaemonStartupExclusionOwner, operation: () => Promise<T>, options?: DaemonStartupExclusionOptions): Promise<T>;
+/** Retain the same exclusion across an existing acquire/release lifecycle. */
+export declare function acquireDaemonStartupExclusion(agentDir: string, owner: DaemonStartupExclusionOwner, options?: DaemonStartupExclusionOptions): Promise<() => Promise<void>>;