@gajae-code/coding-agent 0.18.7 → 0.18.9

package/dist/types/modes/utils/macos-option-forwarding.d.ts

@@ -0,0 +1,17 @@
+import type { KeyId } from "@gajae-code/tui";
+/** The Option chord that composes `text` on the macOS US/ABC layout, if any. */
+export declare function macosOptionChordForComposedText(text: string): KeyId | undefined;
+/** Terminal-specific instruction for sending Option as Alt/Meta, when the terminal is known. */
+export declare function macosOptionForwardingInstruction(terminalProgram: string | undefined): string | undefined;
+export interface UnforwardedOptionChordWarnerOptions {
+    platform: NodeJS.Platform;
+    terminalProgram: string | undefined;
+    formatKeyHint: (key: KeyId) => string;
+    showWarning: (message: string) => void;
+}
+/**
+ * Builds the composer callback that explains, once, why a bound Option shortcut
+ * produced a character instead of firing. Returns undefined off macOS, where the
+ * composition table does not apply.
+ */
+export declare function createUnforwardedOptionChordWarner(options: UnforwardedOptionChordWarnerOptions): ((key: KeyId, text: string) => void) | undefined;

package/dist/types/progress/collect-project-progress.d.ts

@@ -0,0 +1,38 @@
+import type { SubagentLifecycle } from "../async/job-manager";
+import type { Goal, GoalModeState } from "../goals/state";
+import type { SessionManager } from "../session/session-manager";
+import { type TodoPhase } from "../tools/todo-write";
+import { type ProjectProgressInput, type ProjectProgressReport } from "./project-progress";
+/** Session-owned state the overview reads; everything else comes from durable `.gjc` files. */
+export interface ProjectProgressSessionView {
+    cwd: string;
+    /** GJC session id that scopes `.gjc/_session-{id}` state; without it no workflow state is read. */
+    sessionId: string | undefined;
+    goal: Goal | undefined;
+    todoPhases: readonly TodoPhase[];
+    subagents: readonly SubagentLifecycle[];
+}
+/**
+ * Gather progress input strictly by reading state. A source that fails to read
+ * is reported as unreadable and excluded; it never aborts the overview and is
+ * never replaced by a guess. A source rebuilt from authoritative per-entry
+ * records after its snapshot failed to read is reported as recovered; one whose
+ * readable derived snapshot listed stale rows is reported as discarded; one whose
+ * rows could not be attributed to an authority is reported as unresolved.
+ */
+export declare function collectProjectProgressInput(view: ProjectProgressSessionView): Promise<ProjectProgressInput>;
+/** The live session state `/progress` and `session.progress` read; satisfied by `AgentSession`. */
+export interface ProjectProgressSessionSource {
+    getGoalModeState(): GoalModeState | undefined;
+    getTodoPhases(): TodoPhase[];
+    getSubagentLifecycleStatuses(): SubagentLifecycle[];
+}
+/**
+ * Single entry point shared by the human view and the machine snapshot.
+ *
+ * Todos come from the persisted branch history, as `/todo` reads them: the live
+ * list drops completed and abandoned items when a session is resumed, so it is
+ * only the fallback when no todo state was ever persisted. A persisted empty
+ * list is authoritative and is not replaced by live state.
+ */
+export declare function buildSessionProjectProgress(session: ProjectProgressSessionSource, sessionManager: Pick<SessionManager, "getCwd" | "getSessionId" | "getBranch">): Promise<ProjectProgressReport>;

package/dist/types/progress/progress-contract.d.ts

@@ -0,0 +1,154 @@
+/** Ultragoal story status (`UltragoalGoalStatus`). */
+export type ProgressStoryStatus = "pending" | "active" | "complete" | "failed" | "blocked" | "review_blocked" | "superseded";
+/** Session goal status (`GoalStatus`). */
+export type ProgressGoalStatus = "active" | "paused" | "complete" | "dropped";
+/** Todo item status (`TodoStatus`). */
+export type ProgressTodoStatus = "pending" | "in_progress" | "completed" | "abandoned";
+/** Workflow HUD chip severity (`WorkflowHudSeverity`). */
+export type ProgressChipSeverity = "info" | "warning" | "blocked" | "error" | "success";
+/** Durable `.gjc` session-state sources that can fail to read. */
+export type ProgressDurableSource = "workflow-state" | "ultragoal-plan";
+export type ProgressBasisKind = "ultragoal-stories" | "todos" | "goal-status" | "none";
+export type ProgressHeadline = "complete" | "awaiting-completion" | "blocked" | "in-progress" | "not-started" | "paused" | "dropped" | "no-tracked-work";
+export type ProgressSignalKind = "blocker" | "pending" | "note";
+export type ProgressSignalSource = "ultragoal" | "workflow" | "subagents" | "todos" | "goal" | "state";
+export interface ProgressAgentCounts {
+    total: number;
+    running: number;
+    /** Subagents that are queued or paused. */
+    waiting: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+}
+export interface ProgressReviewVerdict {
+    skill: string;
+    verdict: string;
+}
+export declare const PROJECT_PROGRESS_SNAPSHOT_SCHEMA = "gjc.project_progress.v1";
+/** Bounds keep one snapshot well under a single SDK query page. */
+export declare const PROGRESS_SNAPSHOT_LIMITS: {
+    readonly stories: 100;
+    readonly todos: 100;
+    readonly workflows: 16;
+    readonly attention: 50;
+    readonly text: 300;
+};
+export interface ProgressSnapshotStory {
+    id: string;
+    title: string;
+    status: ProgressStoryStatus;
+    /** A completion-verification (quality-gate) receipt is recorded on the story. */
+    verificationReceipt: boolean;
+}
+export interface ProgressSnapshotTodo {
+    content: string;
+    status: ProgressTodoStatus;
+}
+export interface ProgressSnapshotWorkflow {
+    skill: string;
+    phase: string;
+    summary: string | null;
+    chips: {
+        label: string;
+        value: string | null;
+        severity: ProgressChipSeverity | null;
+    }[];
+}
+export interface ProgressSnapshotAttention {
+    kind: ProgressSignalKind;
+    source: ProgressSignalSource;
+    ref: string | null;
+    text: string;
+}
+export interface ProjectProgressSnapshot {
+    schema: typeof PROJECT_PROGRESS_SNAPSHOT_SCHEMA;
+    /** Overall completion state; identical to the `/progress` headline. */
+    state: ProgressHeadline;
+    completion: {
+        /** Which countable units the indicator was derived from; `none` means nothing is countable. */
+        basis: ProgressBasisKind;
+        done: number;
+        total: number;
+        /** Whole percent; `null` when `basis` is `none`. Never 100 while a unit is open. */
+        percent: number | null;
+        /** Every counted unit is done (the session may still be awaiting goal completion or subagents). */
+        allUnitsDone: boolean;
+        /** `state === "complete"`: units done, goal (if any) complete, no subagents running, queued, or paused. */
+        complete: boolean;
+        explanation: string;
+    };
+    execution: {
+        goal: {
+            objective: string;
+            status: ProgressGoalStatus;
+            timeUsedSeconds: number;
+        } | null;
+        ultragoal: {
+            objective: string;
+            counts: {
+                total: number;
+                complete: number;
+                active: number;
+                pending: number;
+                blocked: number;
+                superseded: number;
+            };
+            stories: ProgressSnapshotStory[];
+            omittedStories: number;
+        } | null;
+        todos: {
+            counts: {
+                total: number;
+                completed: number;
+                inProgress: number;
+                pending: number;
+                abandoned: number;
+            };
+            items: ProgressSnapshotTodo[];
+            omittedItems: number;
+        } | null;
+    };
+    activeWork: {
+        /**
+         * Active story, else the next pending one, matching the Ultragoal scheduler.
+         * Blocked, review-blocked, and failed stories are never reported here (failed
+         * stories are retried only on explicit request); `null` when nothing is schedulable.
+         */
+        story: {
+            id: string;
+            title: string;
+        } | null;
+        /** In-progress todo, else the next pending one. */
+        todo: string | null;
+        workflows: ProgressSnapshotWorkflow[];
+        /** Active workflows beyond `PROGRESS_SNAPSHOT_LIMITS.workflows` that `workflows` leaves out. */
+        omittedWorkflows: number;
+        agents: ProgressAgentCounts;
+    };
+    verification: {
+        /** Present only when at least one story is complete. */
+        storyReceipts: {
+            complete: number;
+            withReceipt: number;
+            withoutReceipt: number;
+        } | null;
+        reviewVerdicts: ProgressReviewVerdict[];
+    };
+    attention: ProgressSnapshotAttention[];
+    omittedAttention: number;
+    sources: {
+        /** Session-scoped `.gjc` state (workflows, ultragoal plan) was consulted. */
+        sessionStateRead: boolean;
+        /** Sources that exist but could not be read; excluded from every count. */
+        unreadable: ProgressDurableSource[];
+        /** Sources whose primary record was unreadable but whose contents were recovered from authoritative per-entry records. */
+        recovered: ProgressDurableSource[];
+        /** Sources whose readable derived snapshot listed entries the authoritative per-entry records do not; those stale entries were discarded. */
+        discarded: ProgressDurableSource[];
+        /** Sources listing entries whose authority could not be established; those entries are excluded and their absence is unconfirmed. */
+        unresolved: ProgressDurableSource[];
+    };
+}
+/** Strip terminal escapes/control characters and bound length; durable text is untrusted. */
+export declare function boundSnapshotText(text: string, max?: number): string;

package/dist/types/progress/progress-snapshot.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Machine-facing projection of the project progress report (SDK query
+ * `session.progress`, Q32). It is a pure re-shaping of `ProjectProgressReport`:
+ * every number, state, and attention item comes from the same computation, and
+ * the human `/progress` view renders this snapshot (`render-progress.ts`), so
+ * the two can never disagree. Absent evidence is `null`/empty, never estimated.
+ * Every bounded list reports how many entries it omitted.
+ */
+import { type ProjectProgressSnapshot } from "./progress-contract";
+import type { ProjectProgressReport } from "./project-progress";
+export declare function toProjectProgressSnapshot(report: ProjectProgressReport): ProjectProgressSnapshot;

package/dist/types/progress/project-progress.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Read-only project progress projection. One report is re-shaped into the
+ * machine-facing `session.progress` SDK snapshot (`progress-snapshot.ts`), and
+ * the human-facing `/progress` view renders that same snapshot
+ * (`render-progress.ts`) in the TUI, text mode, and ACP.
+ *
+ * The completion indicator is derived exclusively from countable units that
+ * carry a durable completion status. It never weights units by size, never
+ * credits partial work on an open unit, and never infers progress from
+ * conversation text, elapsed time, or token spend. When no countable basis
+ * exists the indicator is reported as unknown instead of guessed.
+ */
+import type { SubagentLifecycle } from "../async/job-manager";
+import { type UltragoalGoalStatus } from "../gjc-runtime/ultragoal-runtime";
+import type { GoalStatus } from "../goals/state";
+import type { WorkflowHudSeverity } from "../skill-state/active-state";
+import type { TodoStatus } from "../tools/todo-write";
+import type { ProgressAgentCounts, ProgressBasisKind, ProgressDurableSource, ProgressHeadline, ProgressReviewVerdict, ProgressSignalKind, ProgressSignalSource } from "./progress-contract";
+export interface ProgressGoalInput {
+    objective: string;
+    status: GoalStatus;
+    timeUsedSeconds: number;
+}
+export interface ProgressTodoInput {
+    content: string;
+    status: TodoStatus;
+}
+export interface ProgressWorkflowChip {
+    label: string;
+    value?: string;
+    severity?: WorkflowHudSeverity;
+}
+export interface ProgressWorkflowInput {
+    skill: string;
+    phase: string;
+    summary?: string;
+    chips: ProgressWorkflowChip[];
+}
+export interface ProgressStoryInput {
+    id: string;
+    title: string;
+    status: UltragoalGoalStatus;
+    /** A completion-verification (quality-gate) receipt is recorded on the story. */
+    hasVerificationReceipt: boolean;
+}
+export interface ProgressUltragoalInput {
+    objective: string;
+    stories: ProgressStoryInput[];
+}
+export declare const PROGRESS_SOURCE_LABELS: Record<ProgressDurableSource, string>;
+export interface ProjectProgressInput {
+    goal?: ProgressGoalInput;
+    todos: ProgressTodoInput[];
+    workflows: ProgressWorkflowInput[];
+    ultragoal?: ProgressUltragoalInput;
+    subagents: SubagentLifecycle[];
+    /** Whether session-scoped `.gjc` state (workflows, ultragoal plan) was consulted at all. */
+    sessionStateRead: boolean;
+    /** Durable sources that exist but could not be read; excluded from the estimate. */
+    unreadable: ProgressDurableSource[];
+    /** Durable sources whose primary record was unreadable but whose contents were recovered from authoritative per-entry records. */
+    recovered: ProgressDurableSource[];
+    /** Durable sources whose readable derived snapshot listed entries the authoritative per-entry records do not; those stale entries were discarded. */
+    discarded: ProgressDurableSource[];
+    /** Durable sources listing entries whose authority could not be established; those entries are excluded and their absence is unconfirmed. */
+    unresolved: ProgressDurableSource[];
+}
+export interface ProgressSignal {
+    kind: ProgressSignalKind;
+    /** Which durable state produced the signal. */
+    source: ProgressSignalSource;
+    /** Stable identifier inside the source: story id, workflow skill, or durable source key. */
+    ref?: string;
+    text: string;
+}
+export interface ProgressCompletion {
+    basis: ProgressBasisKind;
+    done: number;
+    total: number;
+    /**
+     * Displayed whole percent, or undefined when no countable basis exists.
+     * Never rounds up to 100 while a unit is open, nor down to 0 once a unit is done.
+     */
+    percent: number | undefined;
+}
+export interface ProgressStoryCounts {
+    total: number;
+    complete: number;
+    active: number;
+    pending: number;
+    blocked: number;
+    superseded: number;
+    verified: number;
+    /** Active story, else the next pending one; blocked, review-blocked, and failed stories are never selected. */
+    current?: {
+        id: string;
+        title: string;
+    };
+}
+export interface ProgressTodoCounts {
+    total: number;
+    completed: number;
+    inProgress: number;
+    pending: number;
+    abandoned: number;
+    current?: string;
+}
+/** Verification evidence that durable state actually records; nothing is inferred. */
+export interface ProgressVerification {
+    /** Complete stories that carry a quality-gate completion receipt (only when stories are complete). */
+    storyReceipts?: {
+        complete: number;
+        withReceipt: number;
+    };
+    /** Latest review verdict chips published by active workflows. */
+    reviewVerdicts: ProgressReviewVerdict[];
+}
+export interface ProjectProgressReport {
+    headline: ProgressHeadline;
+    completion: ProgressCompletion;
+    /** How the completion indicator was derived, in plain words. */
+    basisExplanation: string;
+    goal?: ProgressGoalInput;
+    /** The ultragoal plan the story counts were derived from. */
+    ultragoal?: ProgressUltragoalInput;
+    stories?: ProgressStoryCounts;
+    todoItems: ProgressTodoInput[];
+    todos?: ProgressTodoCounts;
+    workflows: ProgressWorkflowInput[];
+    agents: ProgressAgentCounts;
+    verification: ProgressVerification;
+    signals: ProgressSignal[];
+    sessionStateRead: boolean;
+    unreadable: ProgressDurableSource[];
+    recovered: ProgressDurableSource[];
+    discarded: ProgressDurableSource[];
+    unresolved: ProgressDurableSource[];
+}
+/** Whole percent that never overstates (no 100 while open) nor erases (no 0 once started) progress. */
+export declare function displayPercent(done: number, total: number): number | undefined;
+export declare function computeProjectProgress(input: ProjectProgressInput): ProjectProgressReport;

package/dist/types/progress/render-progress.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Human-readable `/progress` view. It renders the machine-facing
+ * `session.progress` snapshot, so the TUI, text mode, and ACP (which reads the
+ * snapshot over the SDK) show exactly what an orchestrator receives.
+ *
+ * Like `progress-contract.ts`, this module must stay a dependency leaf: the ACP
+ * agent imports it, and the ACP entrypoint may not reach the session graph.
+ */
+import { type ProgressHeadline, type ProjectProgressSnapshot } from "./progress-contract";
+/** ACP palette copy for `/progress`, shared by the builtin registry and the production ACP agent. */
+export declare const PROGRESS_COMMAND_ACP_DESCRIPTION = "Show read-only project progress overview";
+export declare const PROGRESS_HEADLINE_LABELS: Record<ProgressHeadline, string>;
+/** Styling hooks so the TUI can colour output while ACP/text mode stays plain. */
+export interface ProgressRenderStyle {
+    bold(text: string): string;
+    fg(color: "accent" | "success" | "warning" | "error" | "dim" | "muted", text: string): string;
+}
+export interface ProgressRenderOptions {
+    style?: ProgressRenderStyle;
+    /**
+     * Sanitizes and bounds durable text to one display line of at most `max` columns.
+     * Defaults to a character-bounded plain-text clip for ACP and text mode.
+     */
+    clip?: (text: string, max: number) => string;
+    barWidth?: number;
+}
+/** Render the overview as display lines (no trailing newline). */
+export declare function renderProgressSnapshot(snapshot: ProjectProgressSnapshot, options?: ProgressRenderOptions): string[];

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

@@ -257,10 +257,11 @@ export declare class MCPManager {
     /**
      * Resolve auth and shell-command substitutions in config before connecting.
      */
-    prepareConfig(config: MCPServerConfig): Promise<MCPServerConfig>;
+    prepareConfig(config: MCPServerConfig, source?: SourceMeta): Promise<MCPServerConfig>;
     /** Acquire a prepared, pool-owned lease for a scoped transient operation. */
     withPreparedLease<T>(name: string, config: MCPServerConfig, fn: (lease: MCPPoolLease) => Promise<T> | T, options?: {
         signal?: AbortSignal;
+        source?: SourceMeta;
     }): Promise<T>;
     /** Read-only test seam for pending retired lease-release records. */
     get retiredLeaseReleaseCountForTests(): number;

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

@@ -0,0 +1,9 @@
+/**
+ * Follow same-origin MCP redirects only.
+ *
+ * A cross-origin 307/308 would carry custom credential headers, `Mcp-Session-Id`,
+ * and the JSON-RPC body. The first request uses `rawUrl` unchanged so a caller
+ * that cannot be parsed (diagnostic redaction) still reaches fetch, but with
+ * `redirect: "manual"` so that hop is not followed either.
+ */
+export declare function fetchMcpRespectingOrigin(rawUrl: string, init: BunFetchRequestInit): Promise<Response>;

package/dist/types/runtime-mcp/oauth-public-url.d.ts

@@ -0,0 +1,3 @@
+export declare function assertPublicOAuthUrl(url: string, options?: {
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/types/runtime-mcp/plugin-network-boundary.d.ts

@@ -3,6 +3,7 @@ import type { MCPHttpServerConfig, MCPSseServerConfig } from "./types";
 /** Mark an in-memory plugin-bundle remote MCP config for connection-bound public-network enforcement. */
 export declare function bindPluginMcpToPublicNetwork<T extends MCPHttpServerConfig | MCPSseServerConfig>(config: T): T;
 /** The marker is an internal symbol, so persisted user MCP configs cannot opt into or forge this path. */
+export declare function usesPublicNetworkMcpFetch(config: MCPHttpServerConfig | MCPSseServerConfig): boolean;
 export declare function isPluginMcpPublicNetworkBound(config: MCPHttpServerConfig | MCPSseServerConfig): boolean;
 /**
  * Fetch a plugin-bundle MCP request through a DNS-pinned public address. Every

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

@@ -0,0 +1,27 @@
+/**
+ * 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 `!`.
+ */
+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. */
+export declare function isUntrustedProjectMcpSource(source: SourceMeta | undefined, toolsOnly: boolean): boolean;
+export type ProjectHostValueDecision = {
+    action: "resolve";
+} | {
+    action: "drop";
+} | {
+    action: "literal";
+    value: string;
+};
+/**
+ * Decide how to interpret one env or header value.
+ * `drop` means "do not run the shell, and omit the value".
+ * `literal` means "do not read process.env".
+ */
+export declare function decideUntrustedProjectConfigValue(value: string, untrusted: boolean): ProjectHostValueDecision;

package/dist/types/runtime-mcp/smithery-registry.d.ts

@@ -1,4 +1,22 @@
+import { type AddressResolver } from "../web/insane/url-guard";
 import type { MCPServerConfig } from "./types";
+type SmitheryConnection = {
+    type?: "http" | "stdio";
+    deploymentUrl?: string;
+    configSchema?: SmitheryConfigSchema;
+};
+type SmitheryConfigSchema = {
+    type?: string;
+    required?: string[];
+    properties?: Record<string, SmitheryConfigProperty>;
+};
+type SmitheryConfigProperty = {
+    type?: string;
+    description?: string;
+    default?: unknown;
+    enum?: unknown[];
+    format?: string;
+};
 type RegistryInputType = "string" | "number" | "boolean";
 export type SmitherySearchResult = {
     id: string;
@@ -46,6 +64,12 @@ export declare class SmitheryRegistryError extends Error {
     status: number;
     constructor(message: string, status: number);
 }
+export declare function resolveSmitheryServerConfig(qualifiedName: string, selected: {
+    connection: SmitheryConnection;
+    useDirectHttp: boolean;
+}, options?: {
+    resolver?: AddressResolver;
+}): Promise<MCPServerConfig | null>;
 export declare function searchSmitheryRegistry(keyword: string, options?: SmitherySearchOptions): Promise<SmitherySearchResult[]>;
 export declare function toConfigName(candidate: string): string;
 export {};

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

@@ -119,6 +119,12 @@ export interface MCPHttpServerConfig extends MCPServerConfigBase {
     type: "http";
     url: string;
     headers?: Record<string, string>;
+    /**
+     * When true, every request and redirect for this URL is rechecked against
+     * the public-network policy. Persisted so a later process cannot fall back
+     * to an unguarded fetch. Ordinary localhost MCP servers leave this unset.
+     */
+    publicNetwork?: boolean;
 }
 /** SSE server configuration (deprecated, use HTTP) */
 export interface MCPSseServerConfig extends MCPServerConfigBase {

package/dist/types/sdk/acp/adapter.d.ts

@@ -129,5 +129,5 @@ export declare class AcpSdkAdapter {
     }): Promise<unknown>;
     /** Dispatches the ACP extension method names without exposing endpoint credentials. */
     handle(method: string, params?: JsonObject): Promise<unknown>;
-    registerProvider(provider: AcpProviderRegistration): Promise<void>;
+    registerProvider(provider: AcpProviderRegistration, timeoutMs?: number, deadline?: number): Promise<void>;
 }

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" | "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" | "signal";
 export type BrokerStopRequest = {
     kind: "shutdown-request";
 } | {
@@ -20,6 +20,8 @@ export interface BrokerExitRecord {
     fenceReason: BrokerFenceReason | null;
     fencedForMs: number;
     uptimeMs: number;
+    /** For a blocked heartbeat renewal: retained removal transition path. */
+    blockingLockPath?: string;
     pid: number;
     signal: "SIGINT" | "SIGTERM" | null;
     writtenAt: number;
@@ -27,7 +29,7 @@ export interface BrokerExitRecord {
 export interface BrokerStartupExitRecord {
     version: 1;
     mode: "startup";
-    reason: "startup-deadline" | "startup-signal";
+    reason: "startup-deadline" | "startup-signal" | "startup-lock-blocked";
     fenceReason: null;
     fencedForMs: 0;
     uptimeMs: number;
@@ -36,6 +38,8 @@ export interface BrokerStartupExitRecord {
     exitCode: 1 | 130 | 143;
     timeoutMs: number | null;
     writtenAt: number;
+    /** For lock-blocked reason: path to the retained removal transition. */
+    blockingLockPath?: string;
 }
 export type BrokerStartupExitWriteStatus = {
     kind: "written";

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

@@ -1,12 +1,14 @@
 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";
 import { type DirectoryMigrationPolicy } from "../session-directory";
-import { type BrokerStopRequest } from "./broker-exit";
+import { type BrokerExitMode, type BrokerExitReason, type BrokerStopRequest } from "./broker-exit";
 import { type BrokerDiscovery, type BrokerPublicationObservation, type RedactedBrokerDiscovery } from "./discovery";
 import { type LifecycleDurableEffectsReceipt, LifecycleLedger, type LifecycleStartupFailureReceipt } from "./lifecycle-ledger";
 import { type IndexedSession, SessionIndex } from "./session-index";
 import { type MasterCapabilityVerifier, type SpawnSubstrateFailure, type SpawnSubstrateProvider } from "./spawn-authority";
+import type { BrokerTaskArtifactOwnerRetirementDisposition } from "./task-artifact-owner-validation";
 export interface BrokerSettings {
     agentDir: string;
     packageGeneration?: string;
@@ -36,6 +38,8 @@ export interface BrokerSettings {
     restartRequestId?: string;
     /** Cancel bootstrap before retained publication when the owning CLI receives a signal. */
     startupAbortSignal?: AbortSignal;
+    /** Monotonic checkpoint deadline, leaving time for retained publication. */
+    startupCheckpointDeadline?: number;
     /** Called synchronously when retained publication establishes broker readiness. */
     onStartupReady?: () => void;
     /** Test-only delay after session checkpoint to verify unpublished discovery ownership. */
@@ -127,6 +131,19 @@ export type BrokerCleanupEvidence = {
     retainedTranscriptSuccessorPath?: string;
     retainedTranscriptPlaceholderPath?: string;
     retainedTranscriptUnknownPath?: string;
+    /** Immutable task-artifact owner authority captured before the first deletion effect. */
+    taskArtifactOwnerDeletionEvidence?: TaskArtifactOwnerDeletionEvidence;
+    /** Latest exact native remnant; it never replaces the original deletion evidence. */
+    taskArtifactOwnerRetirementContinuation?: TaskArtifactOwnerRetirementContinuation;
+    /** Strict owner-only wire disposition, decoded only with its separately stored evidence. */
+    taskArtifactOwnerRetirementOutcome?: BrokerTaskArtifactOwnerRetirementDisposition;
+    taskArtifactOwnerPayloadRetired?: true;
+    taskArtifactOwnerNamespaceRetained?: true;
+    taskArtifactOwnerRetired?: true;
+    /** Durable fact that transcript retirement completed while the owner namespace remains. */
+    taskArtifactOwnerTranscriptDeleted?: true;
+    /** Stable artifacts-phase owner refusal diagnostic. */
+    taskArtifactOwnerCleanupError?: string;
     /** Durable proof that artifact cleanup completed before transcript mutation. */
     artifactsRemoved?: boolean;
     artifactsAbsentAtAuthorization?: true;
@@ -356,13 +373,18 @@ export declare class Broker {
     start(): Promise<BrokerDiscovery>;
     get ownsDiscovery(): boolean;
     get completion(): Promise<void>;
+    /** Why this broker completed, or null while it is still running. */
+    get terminalExit(): {
+        readonly mode: BrokerExitMode;
+        readonly reason: BrokerExitReason;
+    } | null;
     prepareRestart(options: BrokerRestartPrepareOptions): Promise<BrokerRestartResult>;
     commitRestart(options: BrokerRestartCommitOptions): Promise<BrokerRestartResult>;
     cancelRestart(requestId: string): Promise<BrokerRestartResult>;
     status(): RedactedBrokerDiscovery | null;
     heartbeat(): Promise<void>;
     /** Re-observes provably live session hosts and checkpoints their liveness. */
-    heartbeatSessions(now?: number): Promise<number>;
+    heartbeatSessions(now?: number, abortSignal?: AbortSignal, deadlineAt?: number): Promise<number>;
     /**
      * Revalidate retained publication ownership and begin one synchronous effect in
      * the same stack. The callback is the authority boundary: callers must perform

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

@@ -23,6 +23,11 @@ export type DoctorBrokerRestartOutcome = {
 } | {
     kind: "owner_unavailable";
     reason: "no_discovery" | "owner_not_confirmed_live";
+}
+/** Attach-only mode: the broker belongs to an external supervisor, so restart through it. */
+ | {
+    kind: "attach_only_refused";
+    reason: "supervisor_owned";
 } | {
     kind: "prepare_refused";
     code: string;

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

@@ -152,7 +152,20 @@ export declare function closeBrokerClientBeforeDeadline(client: {
 }, deadline: number): Promise<void>;
 /** Reconcile an observed broker generation before entering a startup critical section. */
 export declare function reconcileBrokerGenerationForStartup(settings: EnsureBrokerSettings, deadline?: number): Promise<BrokerDiscovery | undefined>;
-/** Starts the detached broker entrypoint when discovery has no live owner. */
+/**
+ * Attach-only client mode. When `GJC_SDK_BROKER_AUTOSTART=0`, `ensureBroker`
+ * never spawns, retires or restarts a broker: it returns a live, reusable
+ * discovery or fails with `broker_unavailable`. Hosts that supervise their own
+ * broker (for example a system service) set it for every client they run. The
+ * broker entrypoints never call `ensureBroker`, so they ignore the variable and
+ * their descendants may inherit it.
+ */
+export declare const SDK_BROKER_AUTOSTART_ENV = "GJC_SDK_BROKER_AUTOSTART";
+export declare function isBrokerAttachOnly(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Starts the detached broker entrypoint when discovery has no live owner. In
+ * attach-only mode (`SDK_BROKER_AUTOSTART_ENV`) it only attaches.
+ */
 export declare function ensureBroker(settings: EnsureBrokerSettings): Promise<BrokerDiscovery>;
 /** Starts one fresh fixture broker and returns its sole exact-child close lease. */
 export declare function startFixtureBrokerWithLeaseForTest(settings: EnsureBrokerSettings): Promise<StartedFixtureBroker>;