@gajae-code/coding-agent 0.7.3 → 0.7.4

package/dist/types/gjc-runtime/psmux-detect.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Windows psmux detection and tmux-binary resolution.
+ *
+ * Recent psmux releases (see docs/compatibility.md in the psmux repo) close
+ * the round-trip gap for set-option / show-options user options and the
+ * set-window-option profile values gjc emits, which is what unblocks the
+ * native Windows gjc --tmux path. This module detects that capability so gjc
+ * can pick psmux when tmux is missing on Windows, and so callers can decide
+ * whether to treat a given tmux binary as psmux (affecting e.g. the untagged
+ * diagnostic wording and namespace handling).
+ *
+ * The probe is intentionally lightweight: it runs a single tmux -V (or
+ * --version) once per process and caches the verdict. Cache invalidation
+ * knobs:
+ *   - force: true re-probes on every call (used by tests).
+ *   - GJC_PSMUX_FORCE_DETECT=1 re-probes each call.
+ *   - GJC_PSMUX_DETECTION=off skips probing entirely.
+ */
+export declare const GJC_PSMUX_COMMAND_ENV = "GJC_PSMUX_COMMAND";
+export declare const GJC_PSMUX_DETECTION_ENV = "GJC_PSMUX_DETECTION";
+export declare const GJC_PSMUX_FORCE_DETECT_ENV = "GJC_PSMUX_FORCE_DETECT";
+/** Names that psmux installs as the canonical executable / alias. */
+export declare const PSMUX_BINARY_NAMES: readonly ["psmux", "pmux", "tmux"];
+export type PsmuxSpawnRunner = (command: string, args: string[]) => {
+    exitCode: number | null;
+    stdout?: string;
+    stderr?: string;
+};
+/**
+ * Resolves a tmux-class binary name (e.g. "psmux", "tmux") to an absolute
+ * filesystem path or returns null when the binary cannot be located. The
+ * default implementation uses `Bun.which`; production callers leave it
+ * alone and unit tests inject a stub via `__setBinaryResolverForTests`
+ * so the version-banner probe can be exercised hermetically.
+ */
+export type BinaryResolver = (candidate: string) => string | null;
+/** @internal Test-only seam; production code never calls this. */
+export declare function __setBinaryResolverForTests(resolver: BinaryResolver | null): void;
+export declare function envDisabled(value: string | undefined): boolean;
+/**
+ * Decide whether command resolves to a psmux binary by probing its version
+ * output. The result is cached per process unless force is set or
+ * GJC_PSMUX_FORCE_DETECT=1.
+ */
+export declare function detectPsmux(command: string, options?: {
+    force?: boolean;
+    env?: NodeJS.ProcessEnv;
+    runner?: PsmuxSpawnRunner;
+}): boolean;
+export interface ResolveGjcTmuxBinaryOptions {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    runner?: PsmuxSpawnRunner;
+}
+export interface ResolvedTmuxBinary {
+    command: string;
+    isPsmux: boolean;
+    viaExplicitOverride: boolean;
+}
+/**
+ * Resolve the tmux command GJC should invoke. Honors the existing
+ * GJC_TMUX_COMMAND / GJC_TEAM_TMUX_COMMAND overrides; on Windows when no
+ * override is set, psmux (installed as psmux, pmux, or tmux) is picked
+ * automatically so the default gjc --tmux flow lands on a real multiplexer.
+ */
+export declare function resolveGjcTmuxBinary(options?: ResolveGjcTmuxBinaryOptions): ResolvedTmuxBinary;
+/** Test-only helper: drop the in-process detection cache. */
+export declare function clearPsmuxDetectionCache(): void;
+export interface PsmuxProbe {
+    command: string;
+    versionOutput: string;
+    isPsmux: boolean;
+}
+export declare function probePsmux(command: string, options?: {
+    env?: NodeJS.ProcessEnv;
+    runner?: PsmuxSpawnRunner;
+    force?: boolean;
+}): PsmuxProbe;

package/dist/types/gjc-runtime/team-runtime.d.ts

@@ -281,6 +281,8 @@ export declare function persistGjcTeamModeStateSummary(snapshot: GjcTeamSnapshot
 export declare function recoverGjcTeamStaleClaims(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamLivenessRecoveryResult>;
 type GjcTeamTaskMetadataInput = Partial<Pick<GjcTeamTask, "owner" | "lane" | "required_role" | "allowed_roles" | "depends_on" | "blocked_by">>;
 export declare function resolveGjcWorkerCommand(cwd?: string, env?: NodeJS.ProcessEnv): string;
+/** @internal Exported for unit tests. */
+export declare function buildWorkerCommand(config: GjcTeamConfig, worker: GjcTeamWorker, platform?: NodeJS.Platform): string;
 export type GjcWorkerCheckpointClassification = {
     kind: "clean";
     files: string[];

package/dist/types/gjc-runtime/tmux-common.d.ts

@@ -23,7 +23,26 @@ export interface TmuxCommandResult {
 }
 export type TmuxCommandRunner = (args: string[]) => TmuxCommandResult;
 export declare function envDisabled(value: string | undefined): boolean;
-export declare function resolveGjcTmuxCommand(env?: NodeJS.ProcessEnv): string;
+/**
+ * Resolve the tmux (or tmux-compatible multiplexer) command GJC should invoke.
+ *
+ * This is the shared entry point used by every GJC code path that needs to talk
+ * to a multiplexer: `gjc --tmux` planning, `gjc session ...`, `gjc team ...`,
+ * the lifecycle controller, and the harness resident owner. Routing all of
+ * them through the same resolver means a single `GJC_TMUX_COMMAND` override or
+ * a single Windows psmux / pmux detection wins for the whole process — the
+ * failure mode where `gjc --tmux` creates a psmux-backed session and then
+ * `gjc session status` fails because it queries literal `tmux` is closed off.
+ *
+ * Explicit `GJC_TMUX_COMMAND` / `GJC_TEAM_TMUX_COMMAND` overrides are honored on
+ * every platform. On native Windows without an override the resolver walks
+ * `psmux`, then `pmux`, then `tmux` and uses the first binary present on PATH.
+ * On POSIX the resolver returns `tmux` (the historical default) and only
+ * falls through to the platform-aware walker if the caller opts in.
+ */
+export declare function resolveGjcTmuxCommand(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
+export type { PsmuxProbe, ResolvedTmuxBinary, ResolveGjcTmuxBinaryOptions } from "./psmux-detect";
+export { clearPsmuxDetectionCache, detectPsmux, probePsmux, resolveGjcTmuxBinary } from "./psmux-detect";
 /**
  * Build the exact-session target for tmux *option* commands
  * (`show-options` / `set-option`) and `display-message -t`.

package/dist/types/gjc-runtime/tmux-sessions.d.ts

@@ -41,4 +41,22 @@ export declare function createGjcTmuxSession(env?: NodeJS.ProcessEnv): GjcTmuxSe
 /** @internal */
 export declare function readTmuxSessionTagsForGc(sessionName: string, env?: NodeJS.ProcessEnv): GjcTmuxSessionTagsForGc;
 export declare function removeGjcTmuxSession(sessionName: string, env?: NodeJS.ProcessEnv): GjcTmuxSessionStatus;
+/**
+ * Force-close a GJC-managed tmux session, even if a live pane is attached.
+ *
+ * This is the lifecycle-control counterpart to {@link removeGjcTmuxSession}: it
+ * intentionally does NOT refuse live/attached panes (hard-kill is the contract),
+ * but it keeps every safety check so it can only ever kill a genuinely
+ * GJC-managed session:
+ * - re-reads the exact tmux profile immediately before kill (never a non-GJC
+ *   session, even one that collides by name);
+ * - when `expectedSessionId` is given, requires the `@gjc-session-id` tag match;
+ * - when `expectedStateFile` is given, requires the `@gjc-session-state-file`
+ *   tag match.
+ *
+ * Returns the prior status (for audit). Throws a tagged error otherwise:
+ * `gjc_tmux_session_not_found`, `gjc_tmux_session_not_managed`,
+ * `gjc_tmux_session_id_mismatch`, or `gjc_tmux_session_state_file_mismatch`.
+ */
+export declare function forceCloseGjcTmuxSession(sessionName: string, env?: NodeJS.ProcessEnv, expectedSessionId?: string, expectedStateFile?: string): GjcTmuxSessionStatus;
 export declare function attachGjcTmuxSession(sessionName: string, env?: NodeJS.ProcessEnv): never;

package/dist/types/main.d.ts

@@ -12,6 +12,7 @@ import type { SubmittedUserInput } from "./modes/types";
 import { type CreateAgentSessionOptions, type CreateAgentSessionResult, createAgentSession, discoverAuthStorage } from "./sdk";
 import type { AgentSession } from "./session/agent-session";
 import type { AuthStorage } from "./session/auth-storage";
+import { SessionManager } from "./session/session-manager";
 export interface InteractiveModeNotify {
     kind: "warn" | "error" | "info";
     message: string;
@@ -48,6 +49,7 @@ export declare function applyStartupModelProfilesOrExit(args: Parameters<typeof
  * tool registry and shadow the client-supplied servers (issue #1234).
  */
 export declare function createAcpSessionFactory(args: AcpSessionFactoryOptions): AcpSessionFactory;
+export declare function createSessionManager(parsed: Args, cwd: string, activeSettings?: Settings): Promise<SessionManager | undefined>;
 /**
  * Research-mode (RLM) preset hook. Lets `gjc rlm` augment the session options
  * (system prompt, restricted toolset, custom python tool) and assert the tool

package/dist/types/modes/components/model-selector.d.ts

@@ -35,9 +35,15 @@ export declare class ModelSelectorComponent extends Container {
         sessionId?: string;
         isFastForProvider?: (provider?: string) => boolean;
         isFastForSubagentProvider?: (provider?: string) => boolean;
+        isCurrentModelFastModeActive?: () => boolean;
         currentThinkingLevel?: ThinkingLevel;
         activeModelProfile?: string;
     });
+    refreshRoleAssignments(options?: {
+        currentModel?: Model;
+        currentThinkingLevel?: ThinkingLevel;
+        activeModelProfile?: string;
+    }): void;
     handleInput(keyData: string): void;
     getSearchInput(): Input;
     __testSelectProfile(profileName: string, setDefault: boolean): Promise<void>;

package/dist/types/notifications/html-format.d.ts

@@ -49,10 +49,21 @@ export declare function finalizeTelegramHtml(message?: string): string | undefin
  * `1. 1. …` and keeps the displayed number aligned with the button's real index.
  */
 export declare function buttonLabel(label: string, index: number): string;
+/** Numbered, escaped option list for the Telegram message body. */
+export declare function numberedOptionList(labels: string[]): string;
+/** Compact numeric button label; full option text belongs in the message body. */
+export declare function choiceButtonLabel(index: number): string;
 export interface InlineButton {
     text: string;
     callback_data: string;
 }
+/**
+ * Lay out option callbacks as compact numeric buttons. Telegram mobile clients
+ * ellipsize long inline-keyboard labels and tall keyboards can be obscured by
+ * the composer, so the full choice text is rendered in the message body while
+ * the keyboard keeps only stable one-based tap targets.
+ */
+export declare function buildCompactChoiceGrid(labels: string[], callbackForIndex: (index: number) => string): InlineButton[][];
 /**
  * Lay out option labels as a numbered button grid. Long buttons take a
  * full-width row; runs of short buttons are packed into rows of up to 3. The

package/dist/types/notifications/index.d.ts

@@ -12,12 +12,160 @@
  * - `ask` (unattended/RPC): observes emitted workflow gates and resolves the real
  *   gate on a remote reply via `ctx.workflowGate`.
  * - `turn_end` -> `action_needed` (kind `idle`, deduped per turn).
- * - `session_shutdown` -> stop the server + deregister the answer source.
+ * - `session_shutdown` -> `session_closed` frame, stop server, deregister answer source.
  *
  * Enable with Settings notifications config, `GJC_NOTIFICATIONS=1` (a token is
  * generated), or `GJC_NOTIFICATIONS_TOKEN`.
  */
 import type { ExtensionFactory } from "../extensibility/extensions";
+/** Where a `session_create` should run. Discriminated by `kind`. */
+export type SessionCreateTarget = {
+    kind: "existing_path";
+    path: string;
+} | {
+    kind: "worktree";
+    repo: string;
+    branch: string;
+} | {
+    kind: "plain_dir";
+    path: string;
+};
+/** Identifies the session a `session_close` targets. */
+export interface SessionCloseTarget {
+    sessionId: string;
+    /** Expected GJC-managed tmux session name (defense-in-depth match). */
+    tmuxSession?: string;
+    /** Expected `@gjc-session-state-file` tag (defense-in-depth match). */
+    sessionStateFile?: string;
+}
+/** Identifies the session a `session_resume` targets. */
+export interface SessionResumeTarget {
+    sessionIdOrPrefix: string;
+    /** Optional repo/working-dir hint to disambiguate matches. */
+    path?: string;
+}
+/** Create a new session. */
+export interface SessionCreateFrame {
+    type: "session_create";
+    requestId: string;
+    /** Deterministic lifecycle marker preallocated by the daemon before spawn. */
+    lifecycleRequestId: string;
+    /** Session id the daemon preallocated and propagates to the child. */
+    intendedSessionId: string;
+    /** Telegram update id (idempotency key on the daemon side). */
+    updateId: number;
+    chatId: string;
+    /** Control-endpoint token authorizing this frame. */
+    token: string;
+    target: SessionCreateTarget;
+    /** Reference to the daemon-written, once-consumed startup-prompt file. */
+    startupPromptRef?: string;
+}
+/** Close (hard-kill, history preserved) a session. */
+export interface SessionCloseFrame {
+    type: "session_close";
+    requestId: string;
+    updateId: number;
+    chatId: string;
+    token: string;
+    target: SessionCloseTarget;
+    /** Hard-kill even if a live pane is attached (GJC-managed only). */
+    force?: boolean;
+}
+/** Resume a session (reattach if alive, else cold-restart from history). */
+export interface SessionResumeFrame {
+    type: "session_resume";
+    requestId: string;
+    updateId: number;
+    chatId: string;
+    token: string;
+    target: SessionResumeTarget;
+    startupPromptRef?: string;
+}
+/** Any client -> ingress lifecycle request frame. */
+export type SessionLifecycleRequest = SessionCreateFrame | SessionCloseFrame | SessionResumeFrame;
+/** Terminal status of a lifecycle request. */
+export type LifecycleStatus = "ok" | "error";
+/** A connected session's per-session endpoint, returned to the control client. */
+export interface LifecycleEndpoint {
+    url: string;
+    token: string;
+}
+/** The Telegram topic/thread a session is surfaced in. */
+export interface LifecycleTopic {
+    chatId: string;
+    threadId: string;
+}
+/** How a create request was correlated to its spawned session. */
+export type MatchedBy = "spawn_marker" | "session_ready";
+/** Response to a successful `session_create`. */
+export interface SessionCreateResponseFrame {
+    type: "session_create_response";
+    requestId: string;
+    status: LifecycleStatus;
+    lifecycleRequestId: string;
+    sessionId: string;
+    matchedBy: MatchedBy;
+    endpoint: LifecycleEndpoint;
+    topic: LifecycleTopic;
+    target: SessionCreateTarget;
+}
+/** Response to a successful `session_close`. */
+export interface SessionCloseResponseFrame {
+    type: "session_close_response";
+    requestId: string;
+    status: LifecycleStatus;
+    sessionId: string;
+    processGone: boolean;
+    historyPreserved: boolean;
+    endpointStale: boolean;
+}
+/** Whether a resume reattached to a live session or cold-restarted a dead one. */
+export type ResumeMode = "reattached" | "cold_restarted";
+/** Response to a successful `session_resume`. */
+export interface SessionResumeResponseFrame {
+    type: "session_resume_response";
+    requestId: string;
+    status: LifecycleStatus;
+    sessionId: string;
+    mode: ResumeMode;
+    endpoint: LifecycleEndpoint;
+    topic: LifecycleTopic;
+}
+/** Machine-readable reason a lifecycle request failed. */
+export type LifecycleErrorReason = "unauthorized" | "rate_limited" | "duplicate_conflict" | "invalid_target" | "ambiguous_target" | "spawn_failed" | "discovery_timeout" | "readiness_timeout" | "close_refused" | "not_found" | "terminal_uncertain";
+/** A candidate returned with an `ambiguous_target` resume error. */
+export interface ResumeCandidate {
+    sessionId: string;
+    path?: string;
+    /** Last-activity epoch-millis (session history file mtime), if known. */
+    mtimeMs?: number;
+}
+/** A structured lifecycle error frame. */
+export interface SessionLifecycleErrorFrame {
+    type: "session_lifecycle_error";
+    requestId: string;
+    status: LifecycleStatus;
+    reason: LifecycleErrorReason;
+    message: string;
+    candidates?: ResumeCandidate[];
+}
+/** Any ingress -> client lifecycle response frame. */
+export type SessionLifecycleResponse = SessionCreateResponseFrame | SessionCloseResponseFrame | SessionResumeResponseFrame | SessionLifecycleErrorFrame;
+/**
+ * Replayable per-session readiness signal (mirror of the Rust `session_ready`
+ * frame). Buffered and replayed to late clients so WS-open alone never implies
+ * the session is live and surfaced.
+ */
+export interface SessionReadyFrame {
+    type: "session_ready";
+    sessionId: string;
+    lifecycleRequestId?: string;
+    startupPromptRef?: string;
+    repo?: string;
+    branch?: string;
+    title?: string;
+}
 /**
  * Best-effort real repository name (no git spawn): resolves the main worktree
  * root directory so linked worktrees report the repo (e.g. `gajae-code`)

package/dist/types/notifications/lifecycle-commands.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Paired-chat /session_* command grammar (G009).
+ *
+ * Pure parser + shared target validator for the Telegram session-lifecycle
+ * commands. The daemon parses an inbound paired-chat message here, then attaches
+ * transport identity (chatId/updateId/token/requestId) and routes the resulting
+ * frame to the orchestrator. Keeping this pure makes the grammar, the MVP
+ * prompt-rejection, and target validation unit-testable without the daemon.
+ *
+ * MVP scope: an initial prompt (`-- <prompt>`) is REJECTED with usage text — no
+ * prompt text ever enters a frame, audit, log, or response until daemon-owned
+ * 0600 prompt refs are designed.
+ */
+import type { SessionCloseTarget, SessionCreateTarget, SessionLifecycleResponse, SessionResumeTarget } from "./index";
+export type LifecycleCommandVerb = "session_create" | "session_close" | "session_resume";
+/** A parsed, validated lifecycle command (transport identity added by caller). */
+export type ParsedLifecycleCommand = {
+    kind: "create";
+    target: SessionCreateTarget;
+} | {
+    kind: "close";
+    target: SessionCloseTarget;
+} | {
+    kind: "resume";
+    target: SessionResumeTarget;
+} | {
+    kind: "recent";
+    which: "create" | "resume" | "all";
+} | {
+    kind: "usage";
+    message: string;
+} | {
+    kind: "reject";
+    reason: "invalid_target" | "prompt_unsupported";
+    message: string;
+} | {
+    kind: "none";
+};
+/** True when the text begins a /session_* command (cheap pre-gate). */
+export declare function isLifecycleCommandText(text: string | undefined): boolean;
+/**
+ * Parse a paired-chat message into a lifecycle command. Returns `none` for
+ * non-lifecycle text, `usage`/`reject` for malformed input (no side effect), or
+ * a validated `create`/`close`/`resume`/`recent` intent.
+ *
+ * The caller MUST have already enforced paired-chat authorization; this function
+ * performs grammar + target validation only.
+ */
+export declare function parseLifecycleCommand(text: string | undefined): ParsedLifecycleCommand;
+/** The canonical usage text (exported for the daemon's help replies). */
+export declare function lifecycleUsage(): string;
+/**
+ * Shared target validator reused at the policy/effect boundary (after paired-chat
+ * auth, before any side effect). Returns null when valid, or an `invalid_target`
+ * reason. The orchestrator remains authoritative; this is a defensive pre-check
+ * the parser and any other entry point share.
+ */
+export declare function validateLifecycleTarget(verb: LifecycleCommandVerb, target: SessionCreateTarget | SessionCloseTarget | SessionResumeTarget): {
+    ok: true;
+} | {
+    ok: false;
+    reason: "invalid_target";
+    message: string;
+};
+/**
+ * Map a lifecycle response/error to a user-facing Telegram message (G010).
+ *
+ * Only derives text from sessionId, mode, reason, a safe message, and candidate
+ * {sessionId,path} — never a token or prompt. Each error reason gets tailored,
+ * actionable copy; an "in progress" pending response is surfaced distinctly.
+ */
+export declare function formatLifecycleOutcome(r: SessionLifecycleResponse): string;

package/dist/types/notifications/lifecycle-control-runtime.d.ts

@@ -0,0 +1,98 @@
+import type { ResumeCandidate, SessionCreateFrame, SessionLifecycleRequest, SessionLifecycleResponse } from "./index";
+import { type AuditEvent, type CreateEffectResult, type LedgerStore, type LifecycleOutcome, type OrchestratorDeps, type ResumeEffectResult } from "./lifecycle-orchestrator";
+/** Minimal view of the native control server this runtime depends on. */
+export interface ControlServerLike {
+    onLifecycleRequest(cb: (err: Error | null, req: {
+        kind: string;
+        requestId: string;
+        payloadJson: string;
+    }) => void): void;
+    respond(responseJson: string): void;
+}
+/**
+ * A startable control server (the native NotificationControlServer, or a fake in
+ * tests). Extends {@link ControlServerLike} with the start/stop lifecycle the
+ * daemon owns.
+ */
+export interface LifecycleControlServer extends ControlServerLike {
+    start(): Promise<unknown>;
+    stop(): void;
+}
+/** Factory the daemon uses to construct a control server bound to its ownership. */
+export type LifecycleControlServerFactory = (input: {
+    token: string;
+    ownerId: string;
+    agentDir: string;
+}) => LifecycleControlServer;
+/** Atomic + fsynced file-backed idempotency ledger store. */
+export declare function fileLedgerStore(idempotencyFile: string): LedgerStore;
+/** Append-only JSONL audit sink (0600). Never receives tokens or raw prompts. */
+export declare function fileAudit(auditPath: string): (e: AuditEvent) => void;
+/** Simple per-chat sliding-window create rate limiter. */
+export declare function createRateLimiter(maxPerWindow: number, windowMs: number): (chatId: string, nowMs: number) => boolean;
+/** Build the `gjc` argv for a create target (existing path / worktree / dir).
+ *
+ *  The launched session id is carried via `GJC_SESSION_ID` in the child env (see
+ *  {@link daemonSpawnCreate}); the root `gjc` launcher has no `--session-id`
+ *  flag, so it must never appear in argv. Only flags the launch parser actually
+ *  supports are emitted (`--worktree <branch>` for worktree targets). */
+export declare function buildCreateArgv(frame: SessionCreateFrame, _ids: {
+    intendedSessionId: string;
+    startupPromptRef?: string;
+}): {
+    cwd: string;
+    args: string[];
+};
+/** Real daemon-safe tmux launcher: detached `tmux new-session -d` + GJC tags. */
+export declare function daemonSpawnCreate(env?: NodeJS.ProcessEnv): (frame: SessionCreateFrame, ids: {
+    lifecycleRequestId: string;
+    intendedSessionId: string;
+    startupPromptRef?: string;
+}) => Promise<CreateEffectResult>;
+/** Real force-close effect (GJC-managed only, id-matched). */
+export declare function daemonCloseSession(env?: NodeJS.ProcessEnv): (target: {
+    sessionId: string;
+    tmuxSession?: string;
+    sessionStateFile?: string;
+}) => Promise<{
+    processGone: boolean;
+}>;
+/** Real resume effect: reattach if a live GJC session matches; else resolve the
+ *  prefix against saved history and fail closed (`ambiguous`/`notFound`) before
+ *  cold-restarting exactly one resolved session via the daemon-safe launcher. */
+export declare function daemonResumeSession(env?: NodeJS.ProcessEnv, opts?: {
+    sessionsRoot?: string;
+}): (target: {
+    sessionIdOrPrefix: string;
+    path?: string;
+}) => Promise<ResumeEffectResult | {
+    ambiguous: ResumeCandidate[];
+} | {
+    notFound: true;
+}>;
+/** Translate an orchestrator outcome into a wire response frame. */
+export declare function outcomeToResponse(frame: SessionLifecycleRequest, outcome: LifecycleOutcome): SessionLifecycleResponse;
+/**
+ * Wire a control server's lifecycle requests through the orchestrator.
+ *
+ * Handlers run on a single serial queue (a promise chain): the daemon owns the
+ * one control endpoint, so serializing here makes each request's ledger
+ * read -> classify -> write atomic with respect to every other request. Two
+ * identical updates that arrive nearly simultaneously can no longer both
+ * classify as `new` and both spawn — the second sees the first's persisted
+ * `in_progress`/`success` entry and re-acks instead.
+ */
+export declare function attachLifecycleControl(server: ControlServerLike, deps: OrchestratorDeps): void;
+/** Assemble real orchestrator deps for the daemon (ledger/audit under agentDir). */
+export declare function buildOrchestratorDeps(input: {
+    pairedChatId: string;
+    agentNotificationsDir: string;
+    /** Root of saved session histories (`<agentDir>/sessions`), for resume resolution. */
+    sessionsRoot?: string;
+    env?: NodeJS.ProcessEnv;
+}): OrchestratorDeps;
+/**
+ * Default production factory: a real native NotificationControlServer bound to
+ * the daemon's control token, owner id, and agent dir.
+ */
+export declare const createNativeControlServer: LifecycleControlServerFactory;

package/dist/types/notifications/lifecycle-orchestrator.d.ts

@@ -0,0 +1,144 @@
+import type { LifecycleErrorReason, ResumeCandidate, SessionCreateFrame, SessionLifecycleRequest } from "./index";
+/** Durable idempotency state for a single lifecycle request. */
+export type LedgerState = "in_progress" | "success" | "failure" | "terminal_uncertain";
+/** One persisted idempotency entry, keyed by `chatId:updateId`. */
+export interface LedgerEntry {
+    requestHash: string;
+    state: LedgerState;
+    requestId: string;
+    verb: SessionLifecycleRequest["type"];
+    intendedSessionId?: string;
+    startupPromptRef?: string;
+    createdAt: number;
+    updatedAt: number;
+    targetSummary: Record<string, unknown>;
+    sessionId?: string;
+    tmuxSession?: string;
+    sessionStateFile?: string;
+    endpointUrl?: string;
+    /** Close effect outcome: whether the tmux process is confirmed gone. */
+    processGone?: boolean;
+    reason?: LifecycleErrorReason;
+}
+/** The full on-disk ledger document. */
+export interface LedgerDoc {
+    version: 1;
+    entries: Record<string, LedgerEntry>;
+}
+/** Persistence boundary: atomic + fsynced read/write of the ledger document. */
+export interface LedgerStore {
+    read(): Promise<LedgerDoc>;
+    /** Write atomically (temp + fsync + rename) under a per-ledger lock. */
+    write(doc: LedgerDoc): Promise<void>;
+}
+/** One audit line. Tokens and raw prompts are NEVER included. */
+export interface AuditEvent {
+    ts: string;
+    event: "accepted" | "rejected" | "duplicate_reack" | "rate_limited" | "spawn_started" | "recovered_in_progress" | "success" | "failure" | "terminal_uncertain";
+    chatId: string;
+    updateId: number;
+    requestId: string;
+    requestHash: string;
+    verb: SessionLifecycleRequest["type"];
+    targetSummary: Record<string, unknown>;
+    sessionId?: string;
+    tmuxSession?: string;
+    reason?: LifecycleErrorReason;
+    /** Prompt byte length only (never the prompt text). */
+    promptBytes?: number;
+    /** Prompt content hash only (never the prompt text). */
+    promptHash?: string;
+}
+export interface CreateEffectResult {
+    sessionId: string;
+    tmuxSession: string;
+    sessionStateFile?: string;
+    endpointUrl: string;
+    topicThreadId: string;
+}
+export interface ResumeEffectResult extends CreateEffectResult {
+    mode: "reattached" | "cold_restarted";
+}
+/** Injected effects + policy. Pure orchestration calls into these. */
+export interface OrchestratorDeps {
+    /** The single paired chat id. Anything else is rejected before parsing. */
+    pairedChatId: string;
+    now: () => number;
+    store: LedgerStore;
+    audit: (event: AuditEvent) => Promise<void> | void;
+    /** Per-chat create rate limiter: returns true when allowed. */
+    allowCreate: (chatId: string, nowMs: number) => boolean;
+    /** Persist the once-consumed 0600 startup-prompt file; returns its ref. */
+    writeStartupPrompt: (requestId: string, prompt: string | undefined) => Promise<string | undefined>;
+    /** Spawn a session for a create/cold-restart. */
+    spawnCreate: (frame: SessionCreateFrame, ids: {
+        lifecycleRequestId: string;
+        intendedSessionId: string;
+        startupPromptRef?: string;
+    }) => Promise<CreateEffectResult>;
+    closeSession: (target: {
+        sessionId: string;
+        tmuxSession?: string;
+        sessionStateFile?: string;
+    }) => Promise<{
+        processGone: boolean;
+    }>;
+    resumeSession: (target: {
+        sessionIdOrPrefix: string;
+        path?: string;
+    }) => Promise<ResumeEffectResult | {
+        ambiguous: ResumeCandidate[];
+    } | {
+        notFound: true;
+    }>;
+    newLifecycleRequestId: () => string;
+    newSessionId: () => string;
+}
+/** A redaction-safe summary of a request target (never includes the token). */
+export declare function summarizeTarget(frame: SessionLifecycleRequest): Record<string, unknown>;
+/**
+ * Stable request hash over the meaningful (non-token) request content. Used to
+ * detect a duplicate update id reused with a DIFFERENT body (conflict).
+ */
+export declare function requestHash(frame: SessionLifecycleRequest): string;
+export declare function ledgerKey(chatId: string, updateId: number): string;
+/** How a freshly-arrived request relates to the durable ledger. */
+export type DuplicateClass = {
+    kind: "new";
+} | {
+    kind: "reack_success";
+    entry: LedgerEntry;
+} | {
+    kind: "reack_failure";
+    entry: LedgerEntry;
+} | {
+    kind: "in_progress";
+    entry: LedgerEntry;
+} | {
+    kind: "terminal_uncertain";
+    entry: LedgerEntry;
+} | {
+    kind: "conflict";
+    entry: LedgerEntry;
+};
+/** Classify a request against an existing ledger entry (pure). */
+export declare function classifyDuplicate(existing: LedgerEntry | undefined, hash: string): DuplicateClass;
+/** The structured outcome the daemon translates into a wire response frame. */
+export type LifecycleOutcome = {
+    status: "ok";
+    entry: LedgerEntry;
+    mode?: "reattached" | "cold_restarted";
+} | {
+    status: "error";
+    reason: LifecycleErrorReason;
+    message: string;
+    candidates?: ResumeCandidate[];
+} | {
+    status: "pending";
+    entry: LedgerEntry;
+};
+/**
+ * Handle one authenticated lifecycle request. Enforces paired-chat gating,
+ * idempotency, and rate limiting BEFORE any side effect, then dispatches.
+ */
+export declare function handleLifecycleRequest(frame: SessionLifecycleRequest, deps: OrchestratorDeps): Promise<LifecycleOutcome>;