@songsid/agend 2.1.8 → 2.1.10-beta.1

package/dist/forged-envelope-scan.d.ts

@@ -0,0 +1,160 @@
+/**
+ * #995 (#856-B): post-hoc detection of fabricated peer envelopes.
+ *
+ * (A) lets an agent verify a peer message before acting; (C) instruments the
+ * transport. This module is the defense-in-depth fallback: scan a receiver's
+ * OWN kiro
+ * transcript for fleet-envelope shapes (`[from:<instance>] … (message_id:
+ * xmsg-…)`) and check each message_id against the durable delivery record
+ * (#856's `delivery_status` message_id selector). An id nobody delivered is
+ * not a transport glitch — the receiver's model fabricated the turn.
+ *
+ * Only kiro has a reader here: its conversation store
+ * (`~/.local/share/kiro-cli/data.sqlite3`, conversations_v2) is on disk.
+ * Claude jsonl / Codex rollouts / other backends are per-backend follow-ups.
+ *
+ * Everything query-side is read-only: the kiro store opens readonly and the
+ * outbox is read through `DeliveryOutbox.queryStatusReadOnly` (operator
+ * semantics — existence only, content stays redacted).
+ */
+import type { InstanceConfig } from "./types.js";
+export interface EnvelopeCandidate {
+    /** Resolved real instance name (display-name wrapper stripped). */
+    fromInstance: string;
+    messageId: string;
+    /** Short single-line window around the match, for operator review. */
+    excerpt: string;
+}
+export interface ForgedEnvelopeFinding extends EnvelopeCandidate {
+    /** Exact text to inject into the instance (via send_to_instance/steer). */
+    warning: string;
+}
+export type CandidateVerdict = "delivered" | "forged" | "unverifiable";
+/**
+ * Find fleet-envelope candidates in one assistant text. Each message_id is
+ * paired with the nearest `[from:]` tag naming a real instance within
+ * MAX_ENVELOPE_SPAN characters (preceding preferred); pairs are deduped.
+ */
+export declare function extractEnvelopeCandidates(text: string, knownInstances: Set<string>): EnvelopeCandidate[];
+export type KiroScanRead = {
+    kind: "ok";
+    conversationId: string;
+    texts: string[];
+} | {
+    kind: "no-conversation";
+} | {
+    kind: "unreadable";
+    reason: string;
+};
+/**
+ * Assistant texts the kiro store holds for one instance conversation.
+ * Discriminated (#1007): a missing/unreadable store is NOT an empty
+ * transcript — the caller must not report it as clean.
+ */
+export declare function readKiroAssistantTexts(workingDirectory: string, kiroDbPath?: string): KiroScanRead;
+/**
+ * Verify candidates against the durable record — the same oracle (A) agents
+ * use before destructive ops. Missing outbox DB (or an unreadable one) is
+ * `unverifiable`, never forged: absence of evidence is not fabrication.
+ */
+export declare function verifyEnvelopeCandidates(outboxDbPath: string, messageIds: string[]): Map<string, CandidateVerdict>;
+/**
+ * The exact correction to inject into the instance (send_to_instance or a
+ * mid-turn steer): the message it acted on was never fleet-delivered.
+ */
+export declare function formatForgedEnvelopeWarning(instanceName: string, finding: EnvelopeCandidate): string;
+export type KiroForgedScanStatus = "clean" | "forged-envelopes" | "no-conversation" | "unreadable-store" | "partially-unverified";
+export interface KiroForgedScanResult {
+    instanceName: string;
+    status: KiroForgedScanStatus;
+    /** Why the store could not be read (unreadable-store only). */
+    reason?: string;
+    conversationId: string | null;
+    /** Envelope candidates found in the transcript (any verdict). */
+    checked: number;
+    delivered: number;
+    unverifiable: number;
+    /** Forged ids not already reported. */
+    findings: ForgedEnvelopeFinding[];
+}
+/**
+ * Full point-in-time scan of one kiro instance: read its transcript, extract
+ * envelope candidates, verify each against the outbox. `alreadyReportedIds`
+ * suppresses repeat findings; the caller persists newly reported ids.
+ *
+ * Fail-closed (#1007): an unreadable store is `unreadable-store`, a missing
+ * outbox with candidates is `partially-unverified` — never `clean`. Only a
+ * successfully read transcript with every candidate verified is clean.
+ */
+export declare function scanKiroInstanceForForgedEnvelopes(opts: {
+    instanceName: string;
+    workingDirectory: string;
+    outboxDbPath: string;
+    knownInstances: Set<string>;
+    /** Explicit store DB (tests/overrides). Otherwise resolved from storeHome. */
+    kiroDbPath?: string;
+    /**
+     * Credential-profile store home, exactly as the transcript factory resolves
+     * it per instance — a profiled instance keeps its transcript in its own
+     * data.sqlite3, not the shared store.
+     */
+    storeHome?: string;
+    alreadyReportedIds?: Set<string>;
+}): KiroForgedScanResult;
+export interface ScanTargetConfig {
+    name: string;
+    backend: string;
+    workingDirectory?: string;
+    backendOptions?: Record<string, Record<string, unknown>>;
+}
+/**
+ * Effective per-instance scan config, merged EXACTLY like the daemon's
+ * (`loadFleetConfig`: fleet defaults deep-merged under instance overrides).
+ * The credential profile most often lives in defaults — resolving it from the
+ * raw instance block alone scans the wrong store (#1007 round-3).
+ */
+export declare function resolveScanTarget(name: string, rawInstance: Partial<InstanceConfig> | undefined, fleetDefaults: Partial<InstanceConfig>): ScanTargetConfig;
+export interface ScanCommandFinding {
+    from: string;
+    message_id: string;
+    excerpt: string;
+    suggested_injection: string;
+}
+export interface ScanCommandRow {
+    instance: string;
+    backend: string;
+    status: string;
+    reason?: string;
+    note?: string;
+    conversation?: string | null;
+    checked?: number;
+    delivered?: number;
+    unverifiable?: number;
+    findings: ScanCommandFinding[];
+}
+export interface ScanCommandResult {
+    rows: ScanCommandRow[];
+    newFindings: number;
+    unreadable: number;
+    /** no-conversation, partially-unverified, or missing working_directory. */
+    incomplete: number;
+    /**
+     * Fail-closed exit codes: 2 forged, 3 unreadable store, 4 incomplete
+     * verification, 0 only when every scanned transcript verified clean.
+     */
+    exitCode: number;
+}
+/**
+ * Run the scan over resolved targets. Pure orchestration over
+ * {@link scanKiroInstanceForForgedEnvelopes} — the CLI only formats and exits.
+ */
+export declare function executeForgedEnvelopeScan(opts: {
+    targets: ScanTargetConfig[];
+    knownInstances: Set<string>;
+    outboxDbPath: string;
+    dataDir: string;
+    kiroDbOverride?: string;
+    alreadyReportedIds?: Set<string>;
+}): ScanCommandResult;
+export declare function loadReportedEnvelopeIds(dataDir: string): Set<string>;
+export declare function recordReportedEnvelopeIds(dataDir: string, ids: Iterable<string>): void;

package/dist/forged-envelope-scan.js

@@ -0,0 +1,309 @@
+/**
+ * #995 (#856-B): post-hoc detection of fabricated peer envelopes.
+ *
+ * (A) lets an agent verify a peer message before acting; (C) instruments the
+ * transport. This module is the defense-in-depth fallback: scan a receiver's
+ * OWN kiro
+ * transcript for fleet-envelope shapes (`[from:<instance>] … (message_id:
+ * xmsg-…)`) and check each message_id against the durable delivery record
+ * (#856's `delivery_status` message_id selector). An id nobody delivered is
+ * not a transport glitch — the receiver's model fabricated the turn.
+ *
+ * Only kiro has a reader here: its conversation store
+ * (`~/.local/share/kiro-cli/data.sqlite3`, conversations_v2) is on disk.
+ * Claude jsonl / Codex rollouts / other backends are per-backend follow-ups.
+ *
+ * Everything query-side is read-only: the kiro store opens readonly and the
+ * outbox is read through `DeliveryOutbox.queryStatusReadOnly` (operator
+ * semantics — existence only, content stays redacted).
+ */
+import { t } from "./locale.js";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { credentialStoreHomeForInstance } from "./backend/credential-profile.js";
+import { deepMergeGeneric, getEffectiveInstanceDefaults } from "./config.js";
+import { DeliveryOutbox, deliveryStatusSelector } from "./delivery-outbox.js";
+import { extractKiroAssistantStrings, kiroStoreDbPath, readKiroConversationStatus } from "./transcript-sources.js";
+const FROM_TAG_RE = /\[from:([^\]\n]{1,160})\]/g;
+// No closing paren required: the daemon renders metadata pipe-separated in
+// one pair — `(message_id: … | correlation_id: …)` — so the id is usually
+// followed by ` |`, not `)`.
+const MESSAGE_ID_RE = /\(message_id:\s*(xmsg-[A-Za-z0-9_-]{1,64})/g;
+/** A pasted envelope keeps header and metadata within one screen of text. */
+const MAX_ENVELOPE_SPAN = 8000;
+/**
+ * A `[from:…]` tag only counts when it names a real instance — either the
+ * bare name or the daemon's `Display (name)` render. Anything else is a
+ * quote, a doc snippet, or a name the model invented along with the turn.
+ */
+function resolveInstanceName(raw, knownInstances) {
+    const name = raw.trim();
+    if (knownInstances.has(name))
+        return name;
+    const wrapped = /^(.+?)\s*\(([^()]+)\)$/.exec(name);
+    if (wrapped && knownInstances.has(wrapped[2].trim()))
+        return wrapped[2].trim();
+    return null;
+}
+/**
+ * Find fleet-envelope candidates in one assistant text. Each message_id is
+ * paired with the nearest `[from:]` tag naming a real instance within
+ * MAX_ENVELOPE_SPAN characters (preceding preferred); pairs are deduped.
+ */
+export function extractEnvelopeCandidates(text, knownInstances) {
+    const tags = [];
+    FROM_TAG_RE.lastIndex = 0;
+    let tag;
+    while ((tag = FROM_TAG_RE.exec(text)) !== null) {
+        const instance = resolveInstanceName(tag[1], knownInstances);
+        if (instance)
+            tags.push({ index: tag.index, instance });
+    }
+    if (tags.length === 0)
+        return [];
+    const out = [];
+    const seen = new Set();
+    MESSAGE_ID_RE.lastIndex = 0;
+    let mid;
+    while ((mid = MESSAGE_ID_RE.exec(text)) !== null) {
+        let best = null;
+        for (const t of tags) {
+            const dist = Math.abs(t.index - mid.index);
+            if (dist > MAX_ENVELOPE_SPAN)
+                continue;
+            if (!best) {
+                best = t;
+                continue;
+            }
+            const bestDist = Math.abs(best.index - mid.index);
+            // Prefer the preceding tag; on the same side prefer the nearer one.
+            const tPre = t.index <= mid.index;
+            const bPre = best.index <= mid.index;
+            if ((tPre && !bPre) || (tPre === bPre && dist < bestDist))
+                best = t;
+        }
+        if (!best)
+            continue;
+        const key = `${best.instance}|${mid[1]}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const start = Math.max(0, Math.min(best.index, mid.index) - 120);
+        out.push({
+            fromInstance: best.instance,
+            messageId: mid[1],
+            excerpt: text.slice(start, mid.index + mid[0].length).replace(/\s+/g, " ").slice(0, 300),
+        });
+    }
+    return out;
+}
+/**
+ * Assistant texts the kiro store holds for one instance conversation.
+ * Discriminated (#1007): a missing/unreadable store is NOT an empty
+ * transcript — the caller must not report it as clean.
+ */
+export function readKiroAssistantTexts(workingDirectory, kiroDbPath = kiroStoreDbPath()) {
+    const read = readKiroConversationStatus(kiroDbPath, workingDirectory, true);
+    if (read.status === "no-row")
+        return { kind: "no-conversation" };
+    if (read.status === "error")
+        return { kind: "unreadable", reason: read.reason };
+    const history = read.conversation.history;
+    if (!history)
+        return { kind: "unreadable", reason: "conversation history is missing or unparseable" };
+    const texts = [];
+    for (const entry of history)
+        texts.push(...extractKiroAssistantStrings(entry));
+    return { kind: "ok", conversationId: read.conversation.conversationId, texts };
+}
+/**
+ * Verify candidates against the durable record — the same oracle (A) agents
+ * use before destructive ops. Missing outbox DB (or an unreadable one) is
+ * `unverifiable`, never forged: absence of evidence is not fabrication.
+ */
+export function verifyEnvelopeCandidates(outboxDbPath, messageIds) {
+    const verdicts = new Map();
+    if (!existsSync(outboxDbPath)) {
+        for (const id of messageIds)
+            verdicts.set(id, "unverifiable");
+        return verdicts;
+    }
+    for (const id of new Set(messageIds)) {
+        try {
+            const page = DeliveryOutbox.queryStatusReadOnly(outboxDbPath, deliveryStatusSelector({ message_id: id }));
+            verdicts.set(id, page.items.length > 0 ? "delivered" : "forged");
+        }
+        catch {
+            verdicts.set(id, "unverifiable");
+        }
+    }
+    return verdicts;
+}
+/**
+ * The exact correction to inject into the instance (send_to_instance or a
+ * mid-turn steer): the message it acted on was never fleet-delivered.
+ */
+export function formatForgedEnvelopeWarning(instanceName, finding) {
+    return t("delivery.forged_warning", finding.fromInstance, finding.messageId);
+}
+/**
+ * Full point-in-time scan of one kiro instance: read its transcript, extract
+ * envelope candidates, verify each against the outbox. `alreadyReportedIds`
+ * suppresses repeat findings; the caller persists newly reported ids.
+ *
+ * Fail-closed (#1007): an unreadable store is `unreadable-store`, a missing
+ * outbox with candidates is `partially-unverified` — never `clean`. Only a
+ * successfully read transcript with every candidate verified is clean.
+ */
+export function scanKiroInstanceForForgedEnvelopes(opts) {
+    const base = {
+        instanceName: opts.instanceName, conversationId: null, checked: 0, delivered: 0, unverifiable: 0, findings: [],
+    };
+    const kiroDbPath = opts.kiroDbPath ?? kiroStoreDbPath(opts.storeHome);
+    const convo = readKiroAssistantTexts(opts.workingDirectory, kiroDbPath);
+    if (convo.kind === "unreadable") {
+        return { ...base, status: "unreadable-store", reason: convo.reason };
+    }
+    if (convo.kind === "no-conversation") {
+        return { ...base, status: "no-conversation" };
+    }
+    const candidates = [];
+    for (const text of convo.texts)
+        candidates.push(...extractEnvelopeCandidates(text, opts.knownInstances));
+    const verdicts = verifyEnvelopeCandidates(opts.outboxDbPath, candidates.map(c => c.messageId));
+    const reported = opts.alreadyReportedIds ?? new Set();
+    const result = {
+        ...base, status: "clean", conversationId: convo.conversationId, checked: candidates.length,
+    };
+    const seenFinding = new Set();
+    for (const c of candidates) {
+        const verdict = verdicts.get(c.messageId);
+        if (verdict === "delivered")
+            result.delivered++;
+        else if (verdict === "unverifiable")
+            result.unverifiable++;
+        else if (!reported.has(c.messageId) && !seenFinding.has(c.messageId)) {
+            seenFinding.add(c.messageId);
+            result.findings.push({ ...c, warning: formatForgedEnvelopeWarning(opts.instanceName, c) });
+        }
+    }
+    if (result.findings.length > 0)
+        result.status = "forged-envelopes";
+    else if (result.unverifiable > 0)
+        result.status = "partially-unverified";
+    return result;
+}
+/**
+ * Effective per-instance scan config, merged EXACTLY like the daemon's
+ * (`loadFleetConfig`: fleet defaults deep-merged under instance overrides).
+ * The credential profile most often lives in defaults — resolving it from the
+ * raw instance block alone scans the wrong store (#1007 round-3).
+ */
+export function resolveScanTarget(name, rawInstance, fleetDefaults) {
+    const merged = deepMergeGeneric(getEffectiveInstanceDefaults(fleetDefaults), rawInstance ?? {});
+    const backend = merged.backend ?? "claude-code";
+    return {
+        name,
+        backend,
+        workingDirectory: merged.working_directory,
+        backendOptions: merged.backend_options,
+    };
+}
+/**
+ * Run the scan over resolved targets. Pure orchestration over
+ * {@link scanKiroInstanceForForgedEnvelopes} — the CLI only formats and exits.
+ */
+export function executeForgedEnvelopeScan(opts) {
+    const reported = opts.alreadyReportedIds ?? new Set();
+    let newFindings = 0;
+    let unreadable = 0;
+    let incomplete = 0;
+    const rows = [];
+    for (const target of opts.targets) {
+        if (target.backend !== "kiro-cli") {
+            // Other backends keep their transcripts elsewhere (Claude jsonl, Codex
+            // rollouts, …) — per-backend follow-ups, not silent skips.
+            rows.push({
+                instance: target.name,
+                backend: target.backend,
+                status: "unsupported-backend",
+                note: "transcript source is a per-backend follow-up (#995)",
+                findings: [],
+            });
+            continue;
+        }
+        if (!target.workingDirectory) {
+            incomplete++;
+            rows.push({
+                instance: target.name,
+                backend: target.backend,
+                status: "error",
+                note: "fleet config has no working_directory for this instance",
+                findings: [],
+            });
+            continue;
+        }
+        // A profiled instance writes its transcript to its own store, not the
+        // shared one — scan the store its CLI actually uses.
+        const storeHome = opts.kiroDbOverride
+            ? undefined
+            : credentialStoreHomeForInstance(opts.dataDir, target.backend, target.backendOptions?.[target.backend]);
+        const result = scanKiroInstanceForForgedEnvelopes({
+            instanceName: target.name,
+            workingDirectory: target.workingDirectory,
+            outboxDbPath: opts.outboxDbPath,
+            knownInstances: opts.knownInstances,
+            ...(opts.kiroDbOverride ? { kiroDbPath: opts.kiroDbOverride } : {}),
+            ...(storeHome ? { storeHome } : {}),
+            alreadyReportedIds: reported,
+        });
+        for (const f of result.findings)
+            reported.add(f.messageId);
+        newFindings += result.findings.length;
+        if (result.status === "unreadable-store")
+            unreadable++;
+        if (result.status === "no-conversation" || result.status === "partially-unverified")
+            incomplete++;
+        rows.push({
+            instance: target.name,
+            backend: target.backend,
+            status: result.status,
+            ...(result.reason ? { reason: result.reason } : {}),
+            conversation: result.conversationId,
+            checked: result.checked,
+            delivered: result.delivered,
+            unverifiable: result.unverifiable,
+            findings: result.findings.map(f => ({
+                from: f.fromInstance,
+                message_id: f.messageId,
+                excerpt: f.excerpt,
+                // Inject this text into the instance (send_to_instance or a
+                // mid-turn steer): the CLI cannot paste into a live pane itself.
+                suggested_injection: f.warning,
+            })),
+        });
+    }
+    const exitCode = newFindings > 0 ? 2 : unreadable > 0 ? 3 : incomplete > 0 ? 4 : 0;
+    return { rows, newFindings, unreadable, incomplete, exitCode };
+}
+/* ------------------------------------------------------- report dedup state */
+export function loadReportedEnvelopeIds(dataDir) {
+    try {
+        const raw = JSON.parse(readFileSync(join(dataDir, "forged-envelope-reports.json"), "utf-8"));
+        if (!Array.isArray(raw.reported_message_ids))
+            return new Set();
+        return new Set(raw.reported_message_ids.filter((id) => typeof id === "string"));
+    }
+    catch {
+        return new Set();
+    }
+}
+export function recordReportedEnvelopeIds(dataDir, ids) {
+    const merged = loadReportedEnvelopeIds(dataDir);
+    for (const id of ids)
+        merged.add(id);
+    mkdirSync(dataDir, { recursive: true });
+    const path = join(dataDir, "forged-envelope-reports.json");
+    writeFileSync(path, JSON.stringify({ reported_message_ids: [...merged] }, null, 2), { encoding: "utf8", mode: 0o600 });
+}
+//# sourceMappingURL=forged-envelope-scan.js.map

package/dist/forged-envelope-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forged-envelope-scan.js","sourceRoot":"","sources":["../src/forged-envelope-scan.ts"],"names":[],"mappings":"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"}

package/dist/general-knowledge/skills/persona-emoji/SKILL.md

@@ -45,8 +45,11 @@ persona emoji replaces your `delivered` stamp with one of your own, the way
    Don't retry the same value.
 
 Only change your own `delivered` stamp unless someone asked for more. The
-other statuses are how people see a message is still in progress, and
-`progress_prefix` is the emoji leading your progress messages.
+other statuses are how people see a message is still in progress,
+`progress_prefix` is the emoji leading your progress messages, and `photo` /
+`attachment` are the stamps on a photo / file your bot saved (default 📸 / 📎;
+👌 / 👍 on Telegram, which only takes its fixed reaction set — the same check
+applies to them).
 
 ClassicBot instances have no per-instance stamps. The tool says so, and the
 connection's emojis are set by an operator in Settings.

package/dist/instance-lifecycle.d.ts

@@ -6,6 +6,7 @@ import type { EventLog } from "./event-log.js";
 import type { TmuxControlClient } from "./tmux-control.js";
 import type { FleetInstructionsParams } from "./instructions.js";
 import type { DeliveryStatus } from "./status-emojis.js";
+import { type PauseReason } from "./pause-marker.js";
 import { type ProviderUsage } from "./usage/providers.js";
 import type { SpawnGate } from "./spawn-gate.js";
 import type { StormWindow } from "./storm-window.js";
@@ -16,6 +17,15 @@ export { isFleetStartCommandLine } from "./fleet-lock.js";
 export interface BackendInstallationInfo {
     binary: string;
     install: string;
+    /**
+     * #1092: where this backend's own installer puts the binary, read from the
+     * installer script itself. /install-cli verifies on a fresh login shell
+     * first, but an installer may record its PATH only in a file a login shell
+     * never runs: codex's writes `~/.bashrc` when `$SHELL` is bash, below the
+     * stock early `return` for non-interactive shells. Checked only when the
+     * login shell cannot find the binary.
+     */
+    binDirs?: (env: NodeJS.ProcessEnv, home: string) => string[];
 }
 /** Shared CLI metadata used by startup validation and ClassicBot onboarding. */
 export declare const BACKEND_INSTALLATION_INFO: Readonly<Record<string, BackendInstallationInfo>>;
@@ -113,8 +123,32 @@ export interface LifecycleContext {
     finishDeliveryStatus?(instanceName: string, chatId: string, messageId: string, status: DeliveryStatus, threadId?: string): void;
     /** #1005: the instance's own status emojis, for the instructions' "avoid these" line. */
     statusEmojiAvoidList?(instanceName: string): string[];
-    startPersistedPausedInstance(name: string): Promise<void>;
+    startPersistedPausedInstance(name: string, transition?: TransitionHandle): Promise<void>;
+    /** The restart already in flight for `name`, if any — an explicit wake joins it (Phase 2a). */
+    restartInFlight?(name: string): Promise<void> | undefined;
+    /** Phase 2b: a wake that the wake coordinator did not start (operator, user message) succeeded. */
+    onExternalWake?(name: string): void;
 }
+/**
+ * Proof that the caller is running inside `name`'s current transition. Only
+ * direct internal calls hand it on (restart → stop → start, wake → marker-only
+ * start); a detached callback — an event handler, timer or setImmediate fired
+ * while a transition is still awaiting — has none and queues behind it.
+ */
+export interface TransitionHandle {
+    readonly name: string;
+    readonly token: symbol;
+}
+/** Thrown by a start whose generation was invalidated (stop/restart) before it could publish. */
+export declare class SupersededStartError extends Error {
+    constructor(name: string);
+}
+/**
+ * How long a target just woken for queued work is held from idle auto-pause
+ * before its first queued delivery is claimed (Phase 2 design §1.6): the
+ * cross-instance idle gate (60s) plus a 60s grace.
+ */
+export declare const PRECLAIM_LEASE_MS = 120000;
 /**
  * Working directories of the fleet's other instances on `backendName` (#984):
  * Codex consults them only to decide whether `resume --last` could take a
@@ -124,7 +158,10 @@ export declare function peerWorkingDirectories(fleetConfig: FleetConfig | null,
 /** What attachIncidentHandlers needs from a Daemon — the real one satisfies it. */
 export interface IncidentEventSource {
     on(event: string, handler: (...args: any[]) => void): unknown;
-    requestPauseWhenIdle(): void;
+    requestPauseWhenIdle(opts?: {
+        reconfirmAuth?: boolean;
+        reason?: PauseReason;
+    }): void;
     /** Re-checks that a Codex pane is live after an async quota probe. */
     isCodexLivePane?(): Promise<boolean>;
     /** Existing occurrence count used to preserve Codex capacity history on restart. */
@@ -133,6 +170,9 @@ export interface IncidentEventSource {
     getHangDetector?(): {
         on(event: string, handler: (...args: any[]) => void): unknown;
     } | null;
+    /** Real daemons buffer `pty_error` raised by the startup scan until the lifecycle can handle it. */
+    holdStartupIncidents?(): void;
+    releaseStartupIncidents?(): void;
 }
 /** Arguments accepted by handleCreate — mirrors CreateInstanceArgs in outbound-schemas.ts
  *  plus internal-only fields forwarded by deploy_template (profile-derived). */
@@ -193,6 +233,21 @@ export declare class InstanceLifecycle {
     private ctx;
     /** Active daemon processes: instanceName → Daemon */
     readonly daemons: Map<string, import("./daemon.js").Daemon>;
+    /**
+     * Phase 2a: one transition (start / stop / wake / restart) at a time per
+     * instance. A call that passes the current transition's handle runs inline;
+     * anything else queues.
+     */
+    private transitionTails;
+    private activeTransition;
+    /** Bumped synchronously by stop/restart: a start begun under an older epoch must not publish. */
+    private lifecycleEpochs;
+    /** Single wake flight per instance: concurrent wakes share it. */
+    private wakeFlights;
+    /** Starts that begin their idle window now instead of at the persisted last inbound. */
+    private activitySeedNow;
+    /** When each instance was last woken or started for work — the pre-claim lease clock. */
+    private wokeAt;
     /** backend → last auth-error alert time, so one expiry sends one alert. */
     private lastAuthAlertAt;
     /**
@@ -325,11 +380,39 @@ export declare class InstanceLifecycle {
      */
     attachDeliveryStatusHandlers(name: string, daemon: IncidentEventSource): void;
     attachIncidentHandlers(name: string, daemon: IncidentEventSource): void;
-    start(name: string, config: InstanceConfig, topicMode: boolean, runtimeIdentity?: FleetInstructionsParams["runtimeIdentity"]): Promise<void>;
+    epochOf(name: string): number;
+    /** Invalidate every start/wake already running for `name` (they will not publish). */
+    invalidate(name: string): void;
+    /** Whether `transition` is `name`'s transition and is the one running now. */
+    holds(name: string, transition: TransitionHandle | undefined): transition is TransitionHandle;
+    /** Run `fn` as `name`'s next transition, or inline when `parent` is the transition running now. */
+    runTransition<T>(name: string, fn: (transition: TransitionHandle) => Promise<T>, parent?: TransitionHandle): Promise<T>;
+    /** The next start of `name` is a wake/restart/explicit start: begin its idle window now. */
+    markActivitySeedNow(name: string): void;
+    /** Drop a seed request that no start consumed (the start returned early or failed before it). */
+    clearActivitySeedNow(name: string): void;
+    /** Record that `name` was just woken or (re)started, opening its pre-claim lease window. */
+    noteWokeForWork(name: string, now?: number): void;
+    /**
+     * Phase 2a work lease (design §1.6). Held while a durable submission to the
+     * target is in flight (unbounded: no timer releases a writer), or for
+     * PRECLAIM_LEASE_MS after a wake/start while queued work is still waiting to
+     * be claimed. It holds only the idle-timeout pause and warm-cap eviction —
+     * never an auth-deferred or operator pause.
+     */
+    hasWorkLease(name: string, now?: number): boolean;
+    start(name: string, config: InstanceConfig, topicMode: boolean, runtimeIdentity?: FleetInstructionsParams["runtimeIdentity"], transition?: TransitionHandle): Promise<void>;
+    private startInTransition;
     isPaused(name: string): boolean;
     getLastPausedAt(name: string): number | null;
-    pause(name: string): Promise<void>;
-    wake(name: string, timeoutMs?: number): Promise<void>;
+    pause(name: string, reason?: PauseReason): Promise<void>;
+    /** When `name` was last woken or (re)started for work, if recorded. */
+    wokeAtFor(name: string): number | undefined;
+    wake(name: string, timeoutMs?: number, transition?: TransitionHandle, opts?: {
+        source?: "coordinator" | "external";
+    }): Promise<void>;
+    private wakeInner;
+    private wakeInTransition;
     /**
      * Ownership boundary for a daemon that is not yet registered: if start()
      * rejects, nothing else will ever dispose it, so do it here before
@@ -342,7 +425,8 @@ export declare class InstanceLifecycle {
     }, name: string, logger: Logger): Promise<void>;
     /** Stop the registered daemon only if it is still `daemon` (a concurrent restart may have replaced it). */
     stopIfCurrent(name: string, daemon: unknown): Promise<boolean>;
-    stop(name: string): Promise<void>;
+    stop(name: string, transition?: TransitionHandle): Promise<void>;
+    private stopInTransition;
     remove(name: string, authorization: ExplicitInstanceRemoval): Promise<void>;
     /** Handle create_instance tool call from a daemon. */
     handleCreate(args: LifecycleCreateArgs, respond: (result: unknown, error?: string) => void, adapterId?: string): Promise<void>;