@lmctl-ai/lmctl 0.1.342 → 0.2.3

package/dist/db/inflight-acquire.d.ts

@@ -0,0 +1,70 @@
+import type { AgentInflightInput, AgentInflightRow, Dal } from './index.js';
+import type { TrackedInvocationRow } from './tracked-invocation.js';
+import type { TerminalLockRecord } from './terminal-lock.js';
+export type InflightReclaimReason = 'force' | 'stale' | 'dead-pid' | 'session-idle';
+export type SharedInflightAcquireResult = {
+    acquired: true;
+    lease: AgentInflightInput;
+    leaseId: string;
+    previous: AgentInflightRow | null;
+    reclaimReason: InflightReclaimReason | null;
+} | {
+    acquired: false;
+    current: AgentInflightRow;
+};
+export interface SharedInflightAcquireInput {
+    receiver_teamfile: string;
+    receiver_alias: string;
+    sender_teamfile: string;
+    sender_alias: string;
+    force?: boolean;
+    reclaimReason?: InflightReclaimReason;
+    ttlMs: number;
+}
+export declare function inflightHeartbeatMsFromEnv(env?: NodeJS.ProcessEnv): number;
+export declare function startAgentInflightHeartbeat(touch: (heartbeatAt: string) => boolean | Promise<boolean>, options?: {
+    intervalMs?: number;
+    onError?: (error: unknown) => void;
+}): NodeJS.Timeout;
+export type ReceiverBusyState = {
+    busy: false;
+    reclaimable?: ReceiverReclaimableHolder;
+} | {
+    busy: true;
+    reason: 'terminal-held';
+    source: 'terminal-lock';
+    terminalLock: TerminalLockRecord;
+} | {
+    busy: true;
+    reason: 'terminal-held';
+    source: 'terminal-invocation';
+    terminalInvocation: ReceiverTerminalInvocation;
+} | {
+    busy: true;
+    reason: 'in-flight';
+    inFlight: AgentInflightRow;
+};
+/**
+ * A holder row exists but is NOT live, so the receiver is correctly reported
+ * idle (the lock is reclaimable) — yet the orphaned row lingers until the next
+ * acquire lazily reclaims it. Surfaced (proposal 4, session-liveness
+ * observability) so `lmctl status` can show "held by pid N, appears
+ * dead" instead of an "idle" indistinguishable from "no lock at all". This does
+ * NOT change the busy verdict: a dead holder is, and stays, not-busy.
+ */
+export interface ReceiverReclaimableHolder {
+    source: 'terminal-lock' | 'terminal-invocation' | 'in-flight';
+    holder_pid: number | null;
+    holder_host: string | null;
+    /** `dead-pid`: a local pid that is not alive. `stale`: a null pid or a
+     * remote/heartbeat-expired holder past its freshness window. */
+    reason: 'dead-pid' | 'stale';
+}
+export type ReceiverTerminalInvocation = Pick<TrackedInvocationRow, 'id' | 'started_at' | 'last_heartbeat_at' | 'holder_pid' | 'holder_host'>;
+export type TrackedInvocationHolderLiveness = 'live' | 'dead' | 'unknown' | null;
+export declare function acquireSharedInflight(dal: Pick<Dal, 'getAgentInflight' | 'tryAcquireAgentInflight'>, input: SharedInflightAcquireInput): SharedInflightAcquireResult;
+export declare function isReceiverBusy(dal: Pick<Dal, 'getAgentInflight' | 'getTerminalLock' | 'query'>, receiverTeamfile: string, receiverAlias: string): boolean;
+export declare function getTrackedInvocationHolderLiveness(row: Pick<TrackedInvocationRow, 'status' | 'holder_pid' | 'holder_host'>): TrackedInvocationHolderLiveness;
+export declare function getReceiverBusyState(dal: Pick<Dal, 'getAgentInflight' | 'getTerminalLock' | 'query'>, receiverTeamfile: string, receiverAlias: string): ReceiverBusyState;
+export declare function isReclaimableInflightHolder(row: AgentInflightRow, staleBefore: string): boolean;
+export declare function inflightTtlMsFromEnv(env?: NodeJS.ProcessEnv): number;

package/dist/db/invocation-event-projections.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Phase C dual-write for the INVOCATION lifecycle (Coder1's ownership).
+ *
+ * Mirror of Coder2's `live-event-projections.ts` for the mailbox/mutex side:
+ * each function appends the matching `message_event` row AND updates the
+ * `invocation_state` projection in the SAME transaction, routed through
+ * Architect's `appendEventWithProjection`. The caller (the DAL's
+ * tracked_invocation methods) wraps the legacy-table write and these appends in
+ * one `db.transaction`, so the old table and the new log/projection never land
+ * apart.
+ *
+ * TERMINAL TIER-2. A terminal-launched invocation additionally marks its target
+ * busy in `agent_state`. That table is Coder2's write-path end to end, so the
+ * terminal slice CALLS Coder2's `projectTerminalInvocation{Start,Finish}` —
+ * this module never writes `agent_state` fields directly. Receiver identity is
+ * `target_teamfile` + `target_alias` (never `from_identity`), per Coder2's
+ * busy-check contract.
+ *
+ * ROLLOUT SEAM — why FINISH/NOTIFY skip when the projection row is absent.
+ * Dual-write turns on at a deploy. Chat and terminal invocations start AND
+ * finish inside one same-binary process, so if the START was dual-written the
+ * FINISH will be too (row present) and vice versa — no seam. The one crossing
+ * case is the DAEMON reclaiming a stale invocation it did not start: that
+ * invocation may predate dual-write and have no `invocation_state` row. Coder2's
+ * `projectTerminalInvocationFinish` throws on a missing row, and a live DAL
+ * method must never throw on the seam. So FINISH/NOTIFY dual-write ONLY when the
+ * projection row exists (i.e. this invocation's START was dual-written); the
+ * pre-dual-write seam is reconciled by Phase D's cutover backfill, by design.
+ */
+import type Database from './sqlite.js';
+import type { TrackedInvocationRow } from './tracked-invocation.js';
+/**
+ * INVOCATION_START — append the event and insert the `invocation_state` row.
+ * For a terminal-launched invocation with a target, also marks the target busy
+ * via Coder2's `agent_state` entry point. `row` is the freshly-inserted
+ * tracked_invocation row (so `id` and every field are populated).
+ */
+export declare function appendInvocationStart(db: Database, row: TrackedInvocationRow): void;
+/**
+ * INVOCATION_FINISH — append the event and move `invocation_state` to terminal.
+ * `row` is the tracked_invocation row AFTER the finish update. No-ops (returns
+ * false) when no projection row exists — the deploy-seam case reconciled by
+ * Phase D backfill (see module header).
+ */
+export declare function appendInvocationFinish(db: Database, row: TrackedInvocationRow): boolean;
+/**
+ * INVOCATION_NOTIFY_CLAIM — append the event and stamp the notifier onto
+ * `invocation_state`. No-ops on the deploy seam (no projection row).
+ */
+export declare function appendInvocationNotifyClaim(db: Database, row: TrackedInvocationRow, notifiedBy: string, notifiedAt: string): boolean;
+/**
+ * Heartbeat — a mutable projection touch, NOT a log event (design §3: heartbeats
+ * stay projection-only to avoid log bloat, and do not advance last_seq).
+ * Updates `invocation_state.last_heartbeat_at`, and for a terminal invocation
+ * the mirrored `agent_state.terminal_invocation_heartbeat_at` via Coder2's fn.
+ */
+export declare function projectInvocationHeartbeat(db: Database, row: TrackedInvocationRow, heartbeatAt: string): void;
+/** Mutable projection touch for a corrected request payload (no event; the
+ * verbatim-prompt correlation is Phase E's concern). */
+export declare function projectInvocationRequestPayload(db: Database, invocationId: number, requestPayload: string): void;
+/** Mutable projection touch persisting the CREATE-time request message linkage
+ * (`msg_tcl_<id>`) onto the running invocation, so the dead-holder reconciler can
+ * find and terminalize the exact message. No event: linkage metadata, like the
+ * request-payload touch above. */
+export declare function projectInvocationRequestMessageId(db: Database, invocationId: number, requestMessageId: string): void;

package/dist/db/ledger-identity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/db/live-event-projections.d.ts

@@ -0,0 +1,92 @@
+import type Database from './sqlite.js';
+import type { AgentInflightRow } from './delegation.js';
+import type { TerminalLockRecord } from './terminal-lock.js';
+export type InflightReclaimReason = 'force' | 'stale' | 'dead-pid' | 'session-idle';
+export declare const CURRENT_HANDLING_TTL_MS: number;
+export interface ReceiverEventAttribution {
+    provider?: string | null;
+    sessionId?: string | null;
+}
+export declare function teamChatEventStreamId(teamChatLogId: number): string;
+export declare function invocationEventStreamId(invocationId: number): string;
+/** Mutable per-turn pointer. Like last_heartbeat_at, it is deliberately not
+ * backed by its own message_event. */
+export declare function projectCurrentlyHandlingMessage(db: Database, teamfile: string, alias: string, messageId: string, handlingSince?: string): void;
+export declare function clearCurrentlyHandlingMessage(db: Database, teamfile: string, alias: string, expectedMessageId: string): boolean;
+export interface SynchronousChatEventInput {
+    root_teamfile: string;
+    sender_teamfile: string | null;
+    sender_alias: string | null;
+    receiver_teamfile: string;
+    receiver_alias: string;
+    receiver_provider?: string | null;
+    receiver_session_id?: string | null;
+    provider_prompt?: string | null;
+    message: string;
+    response: string | null;
+    origin: string;
+    status: string;
+    error_detail: string | null;
+    truncated: number;
+    created_at: string;
+}
+/** Commit the live message identity before entering the provider turn. */
+export declare function appendSynchronousChatCreated(db: Database, legacyChatLogId: number, input: SynchronousChatEventInput): string;
+/** Append the terminal outcome and release only this turn's causal pointer. */
+export declare function appendSynchronousChatHandled(db: Database, legacyChatLogId: number, input: SynchronousChatEventInput): string;
+export declare function appendInflightAcquired(db: Database, current: AgentInflightRow, previous: AgentInflightRow | null, reclaimReason: InflightReclaimReason | null, callerStaleBefore?: string | null, force?: boolean): string;
+/** Mutable in-flight heartbeat projection; deliberately no message_event row. */
+export declare function projectInflightHeartbeat(db: Database, current: AgentInflightRow, leaseId: string, heartbeatAt: string): boolean;
+export declare function appendInflightReleased(db: Database, current: AgentInflightRow, eventType: 'INFLIGHT_RELEASE' | 'INFLIGHT_RECLAIM', reason?: InflightReclaimReason): void;
+export declare function appendTerminalLockTaken(db: Database, lock: TerminalLockRecord): void;
+export declare function appendTerminalLockReleased(db: Database, lock: TerminalLockRecord, expired?: boolean): void;
+export interface TerminalInvocationProjectionInput {
+    invocationId: string;
+    targetTeamfile: string;
+    targetAlias: string;
+    holderPid: number | null;
+    holderHost: string | null;
+    heartbeatAt: string;
+}
+/** Called from the INVOCATION_START append callback owned by the invocation path. */
+export declare function projectTerminalInvocationStart(db: Database, eventSeq: number, input: TerminalInvocationProjectionInput): void;
+/** Mutable heartbeat projection; deliberately no message_event heartbeat row. */
+export declare function projectTerminalInvocationHeartbeat(db: Database, invocationId: string, heartbeatAt: string): boolean;
+/** Called from the INVOCATION_FINISH append callback owned by the invocation path. */
+export declare function projectTerminalInvocationFinish(db: Database, eventSeq: number, invocationId: string): void;
+export interface MessageHandlingStartedResult {
+    appended: boolean;
+    seq: number;
+    handling_at: string;
+}
+export declare function appendMessageHandlingStarted(db: Database, opts: {
+    messageId: string;
+    handlingBy: string;
+    handlingTeamfile: string;
+    handlingAlias: string;
+    ts?: string;
+}): MessageHandlingStartedResult;
+export interface MessageAcknowledgedResult {
+    /** False when this actor already acked at the same stream state (retry). */
+    appended: boolean;
+    seq: number;
+    /** 'record-only' = terminalize was not requested; the receipt is recorded
+     * and normal delivery still happens later. 'removed' = this ack
+     * terminalized the queued pending row; 'claimed' = a delivery (daemon or
+     * sender-flush) already holds the message, removal no-oped and delivery
+     * proceeds; 'not-pending' = message already terminal. */
+    pending_outcome: 'record-only' | 'removed' | 'claimed' | 'not-pending';
+}
+export declare function appendMessageAcknowledged(db: Database, opts: {
+    messageId: string;
+    ackedBy: string;
+    note?: string;
+    ts?: string;
+    holderPid?: number;
+    holderHost?: string;
+    /** Opt-in (design.lmctl review): "an actor read this" and "the delivery
+     * obligation to the addressed receiver is fulfilled" are different facts.
+     * Default false = record-only; the relay script passes true explicitly
+     * because its read+ack composition IS the delivery-equivalent handling. */
+    terminalizePending?: boolean;
+}): MessageAcknowledgedResult;

package/dist/db/migrate.d.ts

@@ -0,0 +1,51 @@
+import Database from './sqlite.js';
+export declare const CURRENT_USER_VERSION = 61;
+export interface MigrateOptions {
+    dbPath: string;
+    /**
+     * Opt-in override for a db newer than this build understands (task #110
+     * ruling, 2026-09-18). Default `false`: refuse rather than silently
+     * degrade. lmctl's own house pattern is refuse-with-named-flag (9
+     * occurrences, e.g. `plan.ts`'s `--force`), not a blocking
+     * prompt — this codebase has NO user-stdin-prompt infrastructure at all
+     * (`isTTY` appears twice, both cosmetic), and the previous design's
+     * "no TTY -> proceed best-effort" escape hatch silently handed every
+     * headless agent the exact silent-degradation behavior this policy exists
+     * to abolish, on lmctl's majority (non-interactive) path.
+     */
+    allowSchemaSkew?: boolean;
+    /**
+     * Test-only seam: pretend this build's schema ceiling is this version
+     * instead of CURRENT_USER_VERSION, so the min_reader_version skew boundary
+     * can be exercised against a db this same code migrated forward. Only
+     * affects the skew comparison and its error/warning text; the fresh-create
+     * and migration paths always target CURRENT_USER_VERSION.
+     */
+    buildVersionForTests?: number;
+}
+/**
+ * A db schema newer than this build understands, encountered with
+ * `allowSchemaSkew` NOT set. Deliberately NOT a subtype of "this db file is
+ * broken" -- `createDal`'s recovery ladder (salvage + rebuild fresh) must
+ * never treat this as corruption; a live, valid, newer peer's real data
+ * would be destroyed. Callers that catch this must re-throw or handle it
+ * explicitly, never fall through to generic recovery.
+ */
+export declare class SchemaSkewError extends Error {
+    readonly dbPath: string;
+    readonly dbVersion: number;
+    readonly buildVersion: number;
+    constructor(dbPath: string, dbVersion: number, buildVersion?: number);
+}
+export declare function migrate(opts: MigrateOptions): Database;
+/** Test-only: clear the once-per-process warning latch between test cases. */
+export declare function _resetNewerSchemaWarningForTests(): void;
+export interface SchemaSkewInfo {
+    dbVersion: number;
+    buildVersion: number;
+}
+/** The current process's db-schema-skew state, if any was encountered by
+ * `migrate()` (proceed-allowed or refused) since the last reset. Read by
+ * the CLI's top-level error formatter to fold `schema_skew` into a
+ * `--json` refusal response. */
+export declare function currentSchemaSkew(): SchemaSkewInfo | null;

package/dist/db/open-readonly.d.ts

@@ -0,0 +1,2 @@
+import Database from './sqlite.js';
+export declare function openStateDbReadOnly(dbPath: string): Database;

package/dist/db/process-liveness.d.ts

@@ -0,0 +1,37 @@
+export declare function isProcessAlive(pid: number | null | undefined): boolean;
+/**
+ * Process identity for records that outlive the process — the guard that keeps
+ * `serve stop` from SIGTERMing a bystander.
+ *
+ * TOKEN = `<boot_id>:<starttime>`.
+ *
+ * `/proc/<pid>/stat` field 22 (starttime) is ticks SINCE BOOT, so it only
+ * disambiguates reuse WITHIN one boot: after a reboot a fresh process can hold
+ * the same pid at the same tick and match a stale record exactly. Pairing it
+ * with `/proc/sys/kernel/random/boot_id` — regenerated every boot — closes
+ * that. Neither half is sufficient alone.
+ *
+ * Returns null when either half is unreadable (non-Linux, permissions, process
+ * gone). Null means UNVERIFIED, never "same".
+ *
+ * comm (field 2) is parenthesised and may contain spaces/parens, so fields are
+ * counted after the LAST ')'.
+ */
+export declare function processStartToken(pid: number | null | undefined): string | null;
+/** A token is only usable if it has the exact recorded shape. */
+export declare function isWellFormedStartToken(token: unknown): token is string;
+/**
+ * Tri-state identity verdict. Deliberately NOT a boolean: "we could not check"
+ * is a distinct outcome from "it is a different process", and collapsing them
+ * is what makes a signalling path unsafe.
+ *
+ *   'same'       — alive AND identity confirmed.
+ *   'different'  — alive but the pid was REUSED. Never signal.
+ *   'gone'       — not alive.
+ *   'unverified' — alive, but identity could not be established (record
+ *                  predates tokens, malformed token, /proc unreadable,
+ *                  non-Linux). Callers that SIGNAL must refuse; callers that
+ *                  only report may say so.
+ */
+export type ProcessIdentity = 'same' | 'different' | 'gone' | 'unverified';
+export declare function verifyProcessIdentity(pid: number | null | undefined, expected: string | null | undefined): ProcessIdentity;

package/dist/db/sqlite.d.ts

@@ -0,0 +1,47 @@
+interface StatementSyncHandle {
+    all(...params: unknown[]): unknown[];
+    get(...params: unknown[]): unknown;
+    run(...params: unknown[]): {
+        changes: number | bigint;
+        lastInsertRowid: number | bigint;
+    };
+    setAllowBareNamedParameters(allowBareNamedParameters: boolean): void;
+}
+export interface DatabaseOptions {
+    readonly?: boolean;
+    fileMustExist?: boolean;
+}
+export interface RunResult {
+    changes: number;
+    lastInsertRowid: number;
+}
+declare class Database {
+    readonly name: string;
+    private readonly handle;
+    private transactionDepth;
+    private savepointId;
+    constructor(path: string, opts?: DatabaseOptions);
+    prepare(sql: string): Statement;
+    exec(sql: string): void;
+    pragma(str: string, opts?: {
+        simple?: boolean;
+    }): unknown;
+    transaction<Args extends unknown[], Return>(fn: (...args: Args) => Return): (...args: Args) => Return;
+    get inTransaction(): boolean;
+    close(): void;
+    private updateTransactionDepth;
+}
+export declare namespace Database {
+    type Database = InstanceType<typeof Database>;
+}
+export default Database;
+export declare class Statement {
+    private readonly handle;
+    private rawMode;
+    constructor(handle: StatementSyncHandle);
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+    run(...params: unknown[]): RunResult;
+    raw(): this;
+    private normalizeRow;
+}

package/dist/db/sqlite.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/db/terminal-lock.d.ts

@@ -0,0 +1,14 @@
+export declare const TERMINAL_LOCK_SCOPE = "terminal_lock";
+export declare const TERMINAL_LOCK_KIND = "member";
+export interface TerminalLockRecord {
+    lock_id: string;
+    teamfile: string;
+    alias: string;
+    holder_pid: number;
+    holder_host: string;
+    holder_ips: string[];
+    started_at: string;
+    last_heartbeat: string;
+}
+export declare function terminalLockKey(teamfile: string, alias: string): string;
+export declare function parseTerminalLock(data: string): TerminalLockRecord | null;

package/dist/db/tracked-invocation-reconcile.d.ts

@@ -0,0 +1,52 @@
+import type { Dal } from './index.js';
+import type { TrackedInvocationRow } from './tracked-invocation.js';
+export type TrackedInvocationReconcileRow = Pick<TrackedInvocationRow, 'id' | 'status' | 'holder_pid' | 'holder_host' | 'started_at' | 'last_heartbeat_at'>;
+/**
+ * Shared trigger core (used by BOTH the on-touch and startup paths): if this
+ * running row's holder process is VERIFIED dead — same host as us AND its pid
+ * confirmed gone, i.e. `getTrackedInvocationHolderLiveness(row) === 'dead'` —
+ * transition it to the 'aborted' terminal state AND terminalize the linked chat
+ * message, atomically, via the guarded abort CAS.
+ *
+ * Returns the aborted row, or null when the holder is live, is a cross-host
+ * `'unknown'` (a verdict lmctl cannot actually prove — left untouched on
+ * purpose, matching the accepted PID-reuse-after-reboot boundary), is not
+ * running, or the compare-and-set lost a race. It NEVER aborts on anything
+ * short of a proven-dead local holder. The abort CAS is the single gate, so
+ * repeated sweeps and a late normal finalizer all no-op after the first winner
+ * (exactly one terminal message event).
+ */
+export declare function abortTrackedInvocationIfHolderDead(dal: Pick<Dal, 'abortTrackedInvocationAndTerminalizeMessage'>, row: TrackedInvocationReconcileRow): TrackedInvocationRow | null;
+/**
+ * Trigger 2 — daemon-startup sweep, for the OS-reboot case. Runs the SAME
+ * per-row liveness check as the on-touch trigger across every status='running'
+ * row exactly once at startup, aborting only the rows it verifies dead.
+ *
+ * This is deliberately NOT "the daemon just started, so presume everything is
+ * dead": `holder_pid` is the dispatching/holding CLI process's own pid
+ * (chat-exec.ts), wholly independent of the daemon's lifecycle, so a routine
+ * supervised daemon restart (ops/systemd `Restart=always`) MUST leave live
+ * holders alone. It is literally "run trigger 1's check, in bulk, once."
+ * Returns the number of rows aborted.
+ */
+export declare function sweepDeadTrackedInvocations(dal: Pick<Dal, 'listAllRunningTrackedInvocations' | 'abortTrackedInvocationAndTerminalizeMessage'>): number;
+/**
+ * Trigger 1 — opportunistic, on next access. Mirrors agent_inflight's
+ * reclaim-on-touch (`INFLIGHT_RECLAIM`): when a dispatch or the relay evaluates
+ * whether a receiver is busy, reconcile any running tracked_invocation rows
+ * targeting that receiver whose holder is verified dead, so a phantom 'running'
+ * does not linger until the next daemon restart. Same per-row check as the
+ * startup sweep. Returns the number of rows aborted.
+ */
+export declare function reconcileDeadTrackedInvocationsForReceiver(dal: Pick<Dal, 'query' | 'abortTrackedInvocationAndTerminalizeMessage'>, receiverTeamfile: string, receiverAlias: string): number;
+/**
+ * Trigger 3 (periodic daemon tick) -- claim every un-notified terminal
+ * tracked_invocation via the pre-existing `notified_by` CAS (orphaned since
+ * `lmctl wait`, its original consumer, was removed in the synchronous-
+ * delivery rework) and notify the ones that need it. The claim itself is the
+ * single "already handled" gate, so a concurrent or repeated sweep can never
+ * double-notify the same row. Returns the number of synthetic notifications
+ * created (not the number of rows claimed -- most claims are silent backlog
+ * drain of non-'aborted' terminal rows, see `notifyTrackedInvocationFailure`).
+ */
+export declare function notifyTerminalTrackedInvocations(dal: Pick<Dal, 'listClaimableTerminalTrackedInvocations' | 'claimTrackedInvocationNotification' | 'insertTeamChatLog'>, notifiedBy: string, limit?: number): number;

package/dist/db/tracked-invocation.d.ts

@@ -0,0 +1,116 @@
+import type Database from './sqlite.js';
+export type TrackedInvocationKind = 'chat' | 'exec';
+export type TrackedInvocationOrigin = 'agent' | 'operator' | 'mcp' | 'unknown';
+export type TrackedInvocationLaunchSource = 'chat' | 'exec' | 'terminal' | 'unknown';
+export type TrackedInvocationStatus = 'running' | 'done' | 'error' | 'busy' | 'cancelled' | 'aborted';
+export interface TrackedInvocationRow {
+    id: number;
+    kind: TrackedInvocationKind;
+    origin: TrackedInvocationOrigin;
+    scope_teamfile: string | null;
+    from_identity: string;
+    target_teamfile: string | null;
+    target_alias: string | null;
+    root_teamfile: string | null;
+    cwd: string | null;
+    command: string | null;
+    status: TrackedInvocationStatus;
+    started_at: string;
+    ended_at: string | null;
+    holder_pid: number | null;
+    holder_host: string | null;
+    last_heartbeat_at: string | null;
+    exit_code: number | null;
+    signal: string | null;
+    result_summary: string | null;
+    error: string | null;
+    team_chat_log_id: number | null;
+    meta: string | null;
+    notified_by: string | null;
+    notified_at: string | null;
+    launch_source: TrackedInvocationLaunchSource | null;
+    request_payload: string | null;
+    /**
+     * The id of the tracked_invocation whose turn SENT the message that
+     * triggered this one -- the dispatch-lineage edge `lmctl running --tree`
+     * walks. Null for a root (a session not itself triggered by another
+     * tracked turn, e.g. the operator's own direct dispatch). Threaded via the
+     * LMCTL_INVOCATION_ID env var (set on the spawned provider process, read
+     * back by a NESTED dispatch it makes) -- not backfillable for rows
+     * created before this column existed.
+     */
+    parent_invocation_id: number | null;
+    /**
+     * JSON array of human-readable strings when this turn's provider silently
+     * dropped a declared model=/effort= (task #232) -- e.g.
+     * `["copilot terminal ignored model=X: <reason>"]`. Null when the
+     * provider honored its declared config; absence IS the signal, not a
+     * placeholder empty array.
+     */
+    config_warnings: string | null;
+}
+export interface TrackedInvocationInput {
+    kind: TrackedInvocationKind;
+    origin: TrackedInvocationOrigin;
+    /**
+     * Teamfile fields must already be canonical keys produced by the same
+     * resolver used for agent_inflight and team_chat_log. The DAL stores them
+     * verbatim so wait scopes cannot silently diverge from chat scopes.
+     */
+    scope_teamfile?: string | null;
+    from_identity: string;
+    target_teamfile?: string | null;
+    target_alias?: string | null;
+    root_teamfile?: string | null;
+    cwd?: string | null;
+    command?: string | null;
+    started_at?: string;
+    holder_pid?: number | null;
+    holder_host?: string | null;
+    last_heartbeat_at?: string | null;
+    meta?: string | null;
+    launch_source?: TrackedInvocationLaunchSource | null;
+    request_payload?: string | null;
+    parent_invocation_id?: number | null;
+}
+export interface TrackedInvocationFinishPatch {
+    status: Exclude<TrackedInvocationStatus, 'running'>;
+    ended_at?: string;
+    exit_code?: number | null;
+    signal?: string | null;
+    result_summary?: string | null;
+    error?: string | null;
+    team_chat_log_id?: number | null;
+    meta?: string | null;
+    /** JSON-encoded array of config-drop warning strings (task #232). Omit or
+     * pass null to leave any already-set value untouched (COALESCE, same
+     * convention as `meta`). */
+    config_warnings?: string | null;
+}
+export interface TrackedInvocationListFilter {
+    from?: string;
+    scope_teamfile?: string;
+    status?: TrackedInvocationStatus;
+    kind?: TrackedInvocationKind;
+    origin?: TrackedInvocationOrigin;
+    limit?: number;
+}
+export interface TrackedInvocationTerminalClaimFilter {
+    from?: string;
+    scope_teamfile?: string;
+    limit?: number;
+}
+export declare function prepareTrackedInvocationStatements(db: Database): {
+    insertTrackedInvocation: import("./sqlite.js").Statement;
+    getTrackedInvocation: import("./sqlite.js").Statement;
+    listAllRunningTrackedInvocations: import("./sqlite.js").Statement;
+    listRecentlyFinishedTrackedInvocations: import("./sqlite.js").Statement;
+    finishTrackedInvocation: import("./sqlite.js").Statement;
+    reclaimTrackedInvocationIfUnchanged: import("./sqlite.js").Statement;
+    heartbeatTrackedInvocation: import("./sqlite.js").Statement;
+    claimTrackedInvocationNotification: import("./sqlite.js").Statement;
+    updateTrackedInvocationRequestPayload: import("./sqlite.js").Statement;
+    linkTrackedInvocationChatLog: import("./sqlite.js").Statement;
+    abortTrackedInvocationIfUnchanged: import("./sqlite.js").Statement;
+};
+export declare function truncateTrackedInvocationField(value: string | null | undefined): string | null;

package/dist/mcp/dispatch.d.ts

@@ -0,0 +1,45 @@
+export interface BridgeConfig {
+    baseUrl: string;
+    token: string | null;
+}
+export interface BridgeOkResponse {
+    status: 'ok';
+    data: unknown;
+}
+export interface BridgeErrorResponse {
+    status: 'error';
+    code: number;
+    message: string;
+    body?: unknown;
+}
+export type BridgeResponse = BridgeOkResponse | BridgeErrorResponse;
+/**
+ * Minimal fetch-shape injection point for tests. The default uses
+ * `globalThis.fetch` (Node 22 native).
+ */
+export type FetchFn = (input: string, init: RequestInit) => Promise<Response>;
+export interface DispatchDeps {
+    config: BridgeConfig;
+    fetchFn?: FetchFn;
+    dal?: unknown;
+}
+/**
+ * Validate tool name + input shape against the registered schema, dispatch,
+ * then wrap the response.
+ *
+ * Schema validation here is intentionally shallow (required-field +
+ * type-tag checks) — full JSON Schema validation would pull a dependency
+ * we don't need for Phase 1 and the apicli HTTP routes already validate
+ * payloads themselves.
+ */
+export declare function dispatchTool(toolName: string, args: unknown, _deps: DispatchDeps): Promise<BridgeResponse>;
+/**
+ * Read api.url + api.token from the canonical SQLite config table
+ * (DB > env > default for api.url; LMCTL_API_TOKEN > DB for api.token).
+ * The `lmctl api config` surface that used to write these was removed with
+ * the daemon surface (moved to lmbee) — operators set them via env vars or
+ * lmbee-side tooling.
+ */
+export declare function readBridgeConfig(dal: {
+    getConfig(key: string): string | null;
+}, env?: NodeJS.ProcessEnv): BridgeConfig;