@songsid/agend 2.3.4-beta.7 → 2.3.5-alpha.3

package/dist/instance-lifecycle.js

@@ -1,3 +1,7 @@
+import { NativePaneRecoveryError } from "./native-pane-recovery.js";
+import { addsSecondGeneral } from "./web-only-fleet.js";
+import { NativePaneCrashBudget } from "./native-pane-crash-budget.js";
+import { localWindowsCliEnabled, remoteRuntimeEnabled } from "./runtime-switches.js";
 import { settingsUndo, undoSettingsPaths } from "./settings-transaction.js";
 import { measureSyncWork } from "./sync-work-attribution.js";
 import { REMOVED_BACKENDS, isRemovedBackend, removedBackendMessage } from "./backend/removed.js";
@@ -25,6 +29,7 @@ import { BACKEND_AUTH_CHECKS, checkAuthStatus, LOGIN_FLOWS } from "./login-flows
 import { CHAT_PROFILE_LOGIN_BACKENDS, credentialProfileEnv, credentialProfileLoginCommand } from "./backend/credential-profile.js";
 import { fetchClaudeUsage, fetchCodexUsage } from "./usage/providers.js";
 import { assertExplicitInstanceRemoval, authorizeExplicitInstanceRemoval } from "./instance-removal.js";
+import { WINDOWS_CREATE_REFUSED, isNativePaneInstance } from "./native-instance-registry.js";
 import { capturePendingTargetReconciliation, finishTargetReconciliation, reconcileTargetBeforeStart, RECONCILIATION_WRITE_DRAIN_TIMEOUT_MS, retireCapturedTargetWindows, } from "./delivery-reconciliation.js";
 import { noPlaceMarkers, placeRef } from "./topic-link.js";
 export { isFleetStartCommandLine } from "./fleet-lock.js";
@@ -285,6 +290,7 @@ export class InstanceLifecycle {
     activeTransition = new Map();
     /** Bumped synchronously by stop/restart: a start begun under an older epoch must not publish. */
     lifecycleEpochs = new Map();
+    nativeExitOwners = new Map();
     /** Single wake flight per instance: concurrent wakes share it. */
     wakeFlights = new Map();
     /** Starts that begin their idle window now instead of at the persisted last inbound. */
@@ -682,7 +688,108 @@ export class InstanceLifecycle {
             this.ctx.notifyInstanceTopic(name, t("delivery.cancelled_unsent", messages.length, name));
         }, this.ctx.logger, `daemon.human_messages_cancelled[${name}]`));
     }
+    nativeRecoveryPending(name) { return this.nativeExitOwners.has(name); }
+    cancelNativeRecovery(name, owner) {
+        for (const [target, run] of this.nativeExitOwners) {
+            if (name !== undefined && target !== name || owner !== undefined && run.token !== owner)
+                continue;
+            clearTimeout(run.timer);
+            this.nativeExitOwners.delete(target);
+        }
+    }
+    resetNativeCrashBudget(name) {
+        this.cancelNativeRecovery(name);
+        const pin = this.ctx.nativePanePinnedSession?.(name);
+        if (pin) {
+            ensureInstanceDir(this.ctx.getInstanceDir(name));
+            new NativePaneCrashBudget(join(this.ctx.getInstanceDir(name), "native-crash-state.json")).reset(pin);
+        }
+    }
+    async nativePaneExited(name, daemon, data) {
+        const config = this.ctx.fleetConfig?.instances[name], epoch = this.epochOf(name), pin = data.snapshot.sessionId, profilePin = this.ctx.nativePanePinnedSession?.(name) ?? undefined;
+        if (!isNativePaneInstance(config) || data.name !== name || this.daemons.get(name) !== daemon || !daemon.nativePaneExitCurrent(data.snapshot, data.owner)
+            || pin !== undefined && profilePin !== undefined && profilePin !== pin || this.nativeExitOwners.has(name) || this.ctx.isPlannedRestart())
+            return;
+        const token = Symbol(name), run = { token, daemon, timer: undefined };
+        this.nativeExitOwners.set(name, run);
+        const current = () => this.nativeExitOwners.get(name) === run && this.daemons.get(name) === daemon && this.epochOf(name) === epoch
+            && this.ctx.fleetConfig?.instances[name] === config && ((this.ctx.nativePanePinnedSession?.(name) ?? undefined) === profilePin || profilePin === undefined && pin !== undefined && this.ctx.nativePanePinnedSession?.(name) === pin) && !this.isPaused(name) && !this.ctx.isPlannedRestart()
+            && (config.machine_id ? remoteRuntimeEnabled() : localWindowsCliEnabled());
+        daemon.fenceDeliveryWritesForStop();
+        try {
+            const decision = pin && profilePin ? new NativePaneCrashBudget(join(this.ctx.getInstanceDir(name), "native-crash-state.json")).observe(pin, data.snapshot.exitCode, config.restart_policy) : null;
+            await this.runTransition(name, async () => {
+                if (!current())
+                    return;
+                if (!await daemon.waitForDeliveryWritesToDrain(RECONCILIATION_WRITE_DRAIN_TIMEOUT_MS) || !current())
+                    throw Error("Native input writes have not drained");
+                if (this.ctx.deliveryOutbox) {
+                    this.ctx.deliveryOutbox.markTargetReconciliationPending(name, daemon.bootId);
+                    if (!await daemon.reconcileNativeDeliveries(this.ctx.deliveryOutbox, current) || !current())
+                        throw Error("Native delivery reconciliation is unconfirmed");
+                }
+                // Close finalizes the exact positive exit; no PID lookup or signal exists on this path.
+                await daemon.stop({ nativePane: "close" });
+                if (!current())
+                    return;
+                this.ctx.eventLog?.insert(name, "native_pane_exited", { exitCode: data.snapshot.exitCode ?? null, sessionId: pin, decision: decision?.kind ?? "no-conversation", count: decision?.count ?? 0 });
+                if (!decision) {
+                    this.ctx.holdNativePaneRecovery?.(name, new NativePaneRecoveryError({ kind: "session-unconfirmed", launchId: data.snapshot.launchId, sessionId: this.ctx.nativePanePinnedSession?.(name) ?? undefined, ...(config.backend === "codex" ? { provider: "codex" } : {}) }));
+                    this.ctx.setTopicIcon(name, "red");
+                    return;
+                }
+                if (decision.kind !== "retry") {
+                    if (decision.kind === "normal")
+                        await this.ctx.notifyNormalExit(name);
+                    else
+                        this.notifyIncident(name, decision.kind === "loop" ? "crash_loop" : "supervision_ended", t("inst.respawn_paused", name));
+                    this.ctx.setTopicIcon(name, "red");
+                    return;
+                }
+                const timer = setTimeout(() => {
+                    run.timer = undefined;
+                    void this.runTransition(name, async () => {
+                        if (!current())
+                            return;
+                        await this.stopInTransition(name, token);
+                        // Our own stop advances once. An operator's concurrent stop/config change prevents publication.
+                        if (this.nativeExitOwners.get(name) !== run || this.epochOf(name) !== epoch + 1 || this.daemons.has(name)
+                            || this.ctx.fleetConfig?.instances[name] !== config || this.ctx.nativePanePinnedSession?.(name) !== pin || this.isPaused(name) || this.ctx.isPlannedRestart()
+                            || !(config.machine_id ? remoteRuntimeEnabled() : localWindowsCliEnabled()))
+                            return;
+                        await this.startInTransition(name, config, true, { kind: "fleet-topic", backend: config.backend ?? "codex", model: config.model || "default" });
+                        if (this.nativeExitOwners.get(name) !== run || this.epochOf(name) !== epoch + 1 || this.ctx.isPlannedRestart())
+                            return;
+                        await this.ctx.connectIpcToInstance(name);
+                    }).catch(error => { if (this.nativeExitOwners.get(name) === run && !this.ctx.isPlannedRestart()) {
+                        if (this.ctx.holdNativePaneRecovery?.(name, error))
+                            return;
+                        this.ctx.logger.error({ name, err: error }, "Native conversation resume failed; its pin was retained");
+                        this.notifyIncident(name, "supervision_ended", t("inst.respawn_paused", name));
+                    } })
+                        .finally(() => { this.cancelNativeRecovery(name, token); this.ctx.onNativePaneRecoverySettled?.(name); });
+                }, decision.delay);
+                timer.unref?.();
+                run.timer = timer;
+            });
+            if (!run.timer)
+                this.cancelNativeRecovery(name, token);
+        }
+        catch (error) {
+            if (this.nativeExitOwners.get(name) === run && !this.ctx.isPlannedRestart()) {
+                this.ctx.logger.error({ name, err: error }, "Native crash recovery held without a fresh fallback");
+                this.notifyIncident(name, "supervision_ended", t("inst.respawn_paused", name));
+            }
+            this.cancelNativeRecovery(name, token);
+        }
+        finally {
+            if (!run.timer)
+                this.ctx.onNativePaneRecoverySettled?.(name);
+        }
+    }
     attachIncidentHandlers(name, daemon) {
+        if (daemon.usesNativePane?.())
+            daemon.on("native_pane_exited", safeHandler((data) => this.nativePaneExited(name, daemon, data), this.ctx.logger, `daemon.native_pane_exited[${name}]`));
         daemon.on("capacity_nudge_cancelled", safeHandler((data) => {
             const reason = data.reason === "the user cancelled" ? t("inst.codex_retry_cancel_reason_user")
                 : data.reason === "the instance was stopped, paused or respawned" || data.reason === "the instance is not running" ? t("inst.codex_retry_cancel_reason_stopped")
@@ -981,19 +1088,22 @@ export class InstanceLifecycle {
             // labels, summaries and every exhaustive match for one picker's text.)
             // #1691: a prompt no table knows — what it asks (one sanitised, bounded line from the daemon, never the pane), and
             // that AgEnD will not press anything.
+            // S-35: a Windows agent's instance name is windows-<uuid>; people know it by its display name.
+            const label = this.ctx.fleetConfig?.instances[name]?.display_name?.trim() || name;
+            const place = placeRef({ kind: "instance", name }, label);
             if (data.unrecognised) {
                 // #1990: the question is a pane line — it may not name a place of its own.
                 const asked = data.question ? t("inst.unrecognised_prompt_question", noPlaceMarkers(data.question)) : "";
-                this.notifyParked(name, "dialog_parked", t("inst.unrecognised_prompt", name, asked), t("fleet.unrecognised_prompt", instancePlace(name), asked));
+                this.notifyParked(name, "dialog_parked", t("inst.unrecognised_prompt", label, asked), t("fleet.unrecognised_prompt", place, asked));
                 return;
             }
             const category = data.kind && data.kind !== "dialog" ? interactionCategory(data.kind, data.backend) : null;
-            const text = category ? t("inst.interaction_parked", name, category) : data.holdOnly
+            const text = category ? t("inst.interaction_parked", label, category) : data.holdOnly
                 // #2872: the Claude session-resume advice only for that prompt (it read as nonsense under a grok or kiro dialog).
-                ? t("inst.dialog_parked_hold", name, data.description) + (data.advice === "claude-resume" ? " " + t("inst.dialog_parked_hold_claude_resume") : "")
-                : t("inst.dialog_parked_stuck", name, data.description) + (data.advice === "claude-resume" ? " " + t("inst.dialog_parked_stuck_claude_resume") : "");
+                ? t("inst.dialog_parked_hold", label, data.description) + (data.advice === "claude-resume" ? " " + t("inst.dialog_parked_hold_claude_resume") : "")
+                : t("inst.dialog_parked_stuck", label, data.description) + (data.advice === "claude-resume" ? " " + t("inst.dialog_parked_stuck_claude_resume") : "");
             // #1990: in General, the instance's name links to its topic.
-            this.notifyParked(name, "dialog_parked", text, category ? t("fleet.interaction_parked", instancePlace(name), category) : t("fleet.dialog_parked", instancePlace(name), data.description));
+            this.notifyParked(name, "dialog_parked", text, category ? t("fleet.interaction_parked", place, category) : t("fleet.dialog_parked", place, data.description));
         }, this.ctx.logger, `daemon.dialog_parked[${name}]`));
         // #2897: the held dialog is gone (closed, answered, auto-answered) — its notices go with it.
         daemon.on("dialog_unparked", safeHandler(() => this.ctx.resolveParkedNotice?.(name), this.ctx.logger, `daemon.dialog_unparked[${name}]`));
@@ -1030,6 +1140,21 @@ export class InstanceLifecycle {
         daemon.on("pty_error", safeHandler(async (data) => {
             this.ctx.eventLog?.insert(name, "pty_error", { type: data.type, action: data.action });
             this.ctx.logger.warn({ name, errorType: data.type, action: data.action }, `PTY error: ${data.message}`);
+            if (daemon.usesNativePane?.()) {
+                // Native credentials and quotas belong to its runner. Never probe a Linux login or group its peers with it.
+                if (this.daemons.get(name) !== daemon)
+                    return;
+                this.notifyIncident(name, data.type, data.notice ?? data.message);
+                if (data.action === "pause") {
+                    if (data.type === "auth_error") {
+                        daemon.confirmAuthFailure?.();
+                        daemon.requestPauseWhenIdle({ reconfirmAuth: true, reason: "auth" });
+                    }
+                    else
+                        daemon.requestPauseWhenIdle({ reason: "error" });
+                }
+                return;
+            }
             // Antigravity's account-level cap is visible ONLY here: the quota summary
             // API keeps reporting its buckets as barely used while the CLI is blocked
             // (verified live — 0% used and "Individual quota reached" in the same
@@ -1366,7 +1491,10 @@ export class InstanceLifecycle {
         return this.lifecycleEpochs.get(name) ?? 0;
     }
     /** Invalidate every start/wake already running for `name` (they will not publish). */
-    invalidate(name) {
+    invalidate(name, nativeOwner) {
+        const native = this.nativeExitOwners.get(name);
+        if (native && native.token !== nativeOwner)
+            this.cancelNativeRecovery(name);
         this.lifecycleEpochs.set(name, this.epochOf(name) + 1);
     }
     /** Whether `transition` is `name`'s transition and is the one running now. */
@@ -1434,170 +1562,194 @@ export class InstanceLifecycle {
         const check = () => { execution?.assert(); if (this.epochOf(name) !== epoch)
             throw new SupersededStartError(name); };
         check();
+        this.ctx.assertGeneralBindingStart?.(name, config);
         assertNoSessionOomStop(this.ctx.getInstanceDir(name));
         const seedNow = this.activitySeedNow.delete(name);
         if (this.daemons.has(name)) {
             this.ctx.logger.info({ name }, "Instance already running, skipping");
             return;
         }
-        if (!existsSync(config.working_directory)) {
-            this.ctx.logger.info({ name, working_directory: config.working_directory }, "Working directory does not exist — creating it");
-            mkdirSync(config.working_directory, { recursive: true });
-        }
-        const instanceDir = this.ctx.getInstanceDir(name);
-        ensureInstanceDir(instanceDir);
-        // Daemon.start consumes the recovery marker after reading it. A start
-        // that fails before reaching the daemon must leave that intent intact.
-        const { Daemon } = await import("./daemon.js");
-        const { createBackend } = await import("./backend/factory.js");
-        check();
-        const backendName = config.backend ?? this.ctx.fleetConfig?.defaults?.backend ?? "claude-code";
-        // A removed backend (#1280): this instance refuses to start, says why and what to use instead, and the rest of
-        // the fleet is unaffected. Never a fallback to another backend.
-        if (isRemovedBackend(backendName)) {
-            const message = removedBackendMessage(backendName, name);
-            this.ctx.logger.error({ name, backend: backendName }, `Not starting: ${message}`);
-            this.ctx.notifyInstanceTopic(name, t("inst.backend_removed", name, backendName, REMOVED_BACKENDS[backendName].replacement));
-            return;
-        }
-        // Verify backend binary is in PATH before spawning. Off-loop resolve pins a
-        // hint so createBackend's resolveBinary does not run synchronous `which`
-        // (#1490 row 67). Missing still only logs; start continues.
-        const installation = BACKEND_INSTALLATION_INFO[backendName];
-        if (installation) {
-            const { resolveBackendBinary } = await import("./backend-availability.js");
-            const path = await resolveBackendBinary(backendName);
-            noteResolvedBinary(installation.binary, path ?? installation.binary);
+        const native = isNativePaneInstance(config) ? await this.ctx.nativePaneFor?.(name, config, check) : undefined;
+        let nativePublished = false;
+        try {
             check();
-            if (!path) {
-                this.ctx.logger.error({ binary: installation.binary, backend: backendName, instance: name }, `Backend binary "${installation.binary}" not found in PATH`);
+            if (isNativePaneInstance(config) && !native)
+                throw Error("Native pane ownership is unavailable; no local CLI was started");
+            if (native)
+                config = { ...config, agent_mode: "mcp" };
+            if (!native && !existsSync(config.working_directory)) {
+                this.ctx.logger.info({ name, working_directory: config.working_directory }, "Working directory does not exist — creating it");
+                mkdirSync(config.working_directory, { recursive: true });
             }
-        }
-        // claude-code refuses --dangerously-skip-permissions as root — fail fast
-        // Unless IS_SANDBOX=1 is set (recognized sandbox environment)
-        if (process.getuid?.() === 0 && backendName === "claude-code" && !process.env.IS_SANDBOX) {
-            const msg = `⚠️ claude-code cannot run with --dangerously-skip-permissions as root. Set IS_SANDBOX=1 or use a non-root user.`;
-            this.ctx.logger.error({ name, backend: backendName }, msg);
-            this.ctx.notifyInstanceTopic(name, t("inst.root_skip_perms"));
-            return;
-        }
-        const backend = createBackend(backendName, instanceDir);
-        const daemon = new Daemon(name, config, instanceDir, topicMode, backend, this.ctx.controlClient ?? undefined, this.ctx.logger, runtimeIdentity ?? {
-            kind: "fleet-topic",
-            backend: backendName,
-            model: config.model ?? "default",
-        }, this.ctx.spawnGate, this.ctx.stormWindow, this.ctx.backendOutage);
-        daemon.setDeliveryOutboxPort(this.ctx.deliveryOutbox ?? undefined);
-        daemon.setWorkLeaseCheck(() => this.hasWorkLease(name));
-        if (seedNow)
-            daemon.seedActivityNow();
-        // Read at each spawn so a fleet.yaml reload is honoured (#984).
-        daemon.setPeerWorkingDirectories(backendName === "kiro-cli"
-            ? this.ctx.kiroPeerWorkingDirectories ? () => this.ctx.kiroPeerWorkingDirectories(name) : undefined
-            : () => peerWorkingDirectories(this.ctx.fleetConfig, name, backendName));
-        daemon.setStatusEmojiAvoidList(() => this.ctx.statusEmojiAvoidList?.(name));
-        // Before start: the first spawn builds the command and emits its launch
-        // warning synchronously inside Daemon.start, long before
-        // attachIncidentHandlers runs (#984).
-        this.attachLaunchWarningHandler(name, daemon);
-        this.attachContextLostHandler(name, daemon);
-        daemon.on("durable_delivery_deferred", (data) => {
-            // A daemon without its outbox port cannot update the row directly. The
-            // lifecycle owns the same-process store and records a bounded pre-write
-            // retry instead of leaving the lane in delivering forever.
-            this.ctx.deliveryOutbox?.retryBeforeBegin(data.deliveryId, data.targetBootId, data.attemptNo, data.reason, 5_000);
-        });
-        daemon.on("mcp_tool_response_written", (data) => {
-            if (!data.operationId || data.daemonBootId !== daemon.bootId)
+            const instanceDir = this.ctx.getInstanceDir(name);
+            ensureInstanceDir(instanceDir);
+            // Daemon.start consumes the recovery marker after reading it. A start
+            // that fails before reaching the daemon must leave that intent intact.
+            const { Daemon } = await import("./daemon.js");
+            const { createBackend } = await import("./backend/factory.js");
+            check();
+            const backendName = config.backend ?? this.ctx.fleetConfig?.defaults?.backend ?? "claude-code";
+            // A removed backend (#1280): this instance refuses to start, says why and what to use instead, and the rest of
+            // the fleet is unaffected. Never a fallback to another backend.
+            if (isRemovedBackend(backendName)) {
+                const message = removedBackendMessage(backendName, name);
+                this.ctx.logger.error({ name, backend: backendName }, `Not starting: ${message}`);
+                this.ctx.notifyInstanceTopic(name, t("inst.backend_removed", name, backendName, REMOVED_BACKENDS[backendName].replacement));
                 return;
-            try {
-                this.ctx.deliveryOutbox?.markResponseDelivered(name, data.operationId);
             }
-            catch (err) {
-                this.ctx.logger.error({ name, operationId: data.operationId, err }, "Could not persist MCP response-delivered marker");
+            // Verify backend binary is in PATH before spawning. Off-loop resolve pins a
+            // hint so createBackend's resolveBinary does not run synchronous `which`
+            // (#1490 row 67). Missing still only logs; start continues.
+            const installation = BACKEND_INSTALLATION_INFO[backendName];
+            // alpha: a native Windows pane's CLI is on that PC — nothing to look for on this one.
+            if (!native && installation) {
+                const { resolveBackendBinary } = await import("./backend-availability.js");
+                const path = await resolveBackendBinary(backendName);
+                noteResolvedBinary(installation.binary, path ?? installation.binary);
+                check();
+                if (!path) {
+                    this.ctx.logger.error({ binary: installation.binary, backend: backendName, instance: name }, `Backend binary "${installation.binary}" not found in PATH`);
+                }
             }
-        });
-        this.applyCapacityBackoffBaseline(name, backendName, daemon);
-        // Catch errors from daemon internals (e.g. IPC server) to prevent crashing the fleet process
-        daemon.on("error", (err) => {
-            this.ctx.logger.error({ err, name }, "Daemon emitted error — instance isolated");
-        });
-        if (this.ctx.deliveryOutbox) {
-            // Fence older-generation submissions and reconcile them before Daemon.start
-            // reaches Strategy A's unconditional old-window kill.
-            const recovered = this.ctx.deliveryOutbox.recoverTargetGeneration(name, daemon.bootId);
-            if (recovered.queued || recovered.reconciliationPending) {
-                this.ctx.logger.warn({ name, ...recovered }, "Preparing durable outbox rows before target generation start");
-            }
-            const reconciled = await reconcileTargetBeforeStart(this.ctx.deliveryOutbox, name, instanceDir, this.ctx.logger);
-            if (reconciled.uncertain > 0) {
-                this.ctx.logger.warn({ name, ...reconciled }, "Some durable submissions need operator reconciliation");
-            }
-            if (!reconciled.safeToStart) {
-                const message = t("delivery.restart_blocked", name);
-                this.ctx.logger.error({ name, ...reconciled }, message);
-                this.ctx.notifyFleetError?.(message);
-                await daemon.abortStartup().catch(err => this.ctx.logger.warn({ err, name }, "Failed to dispose daemon after reconciliation could not verify old CLI exit"));
-                throw new Error(message);
-            }
-        }
-        if (this.epochOf(name) !== epoch || execution && !execution.current()) {
-            // A stop/restart arrived while this start was reconciling: do not spawn.
-            await daemon.abortStartup().catch(() => { });
-            throw new SupersededStartError(name);
-        }
-        // The startup scan can raise an incident (sign-in screen, fatal modal)
-        // before the handlers below exist and before this daemon is registered;
-        // hold it and deliver it once both are true.
-        daemon.holdStartupIncidents?.();
-        await InstanceLifecycle.startOrDispose(daemon, name, this.ctx.logger, execution ? check : undefined);
-        // Publication fence (Phase 2a): the spawn cannot be cancelled, so a stop or
-        // restart requested meanwhile has been waiting behind this transition. A
-        // superseded start must not register, signal ready, or keep its window.
-        if (this.epochOf(name) !== epoch || execution && !execution.current()) {
-            await daemon.abortStartup().catch(err => this.ctx.logger.warn({ err, name }, "Failed to dispose a superseded start"));
-            throw new SupersededStartError(name);
-        }
-        this.capacityBackoffBaselines.delete(name);
-        this.daemons.set(name, daemon);
-        published?.(daemon); // Exact publication, synchronously after the ownership fence.
-        if (seedNow)
-            this.noteWokeForWork(name);
-        this.ctx.onDaemonReady?.(name, daemon.bootId);
-        daemon.on("auto_pause_requested", safeHandler(async (data) => {
-            await this.pause(name, data?.reason ?? "idle");
-        }, this.ctx.logger, `autoPause[${name}]`));
-        daemon.on("auto_paused", (data) => {
-            this.ctx.eventLog?.insert(name, "instance_paused", { reason: "idle", paused_at: data.pausedAt });
-            this.ctx.logger.info({ name, pausedAt: data.pausedAt }, "Instance auto-paused after idle timeout");
-            this.ctx.setTopicIcon(name, "remove");
-            this.ctx.onAttentionChanged?.(name);
-        });
-        daemon.on("auto_woke", () => {
-            this.ctx.onAttentionChanged?.(name);
-            this.ctx.eventLog?.insert(name, "instance_resumed", { reason: "message" });
-            this.ctx.logger.info({ name }, "Instance auto-woke for delivery");
+            // claude-code refuses --dangerously-skip-permissions as root — fail fast
+            // Unless IS_SANDBOX=1 is set (recognized sandbox environment)
+            if (!native && process.getuid?.() === 0 && backendName === "claude-code" && !process.env.IS_SANDBOX) {
+                const msg = `⚠️ claude-code cannot run with --dangerously-skip-permissions as root. Set IS_SANDBOX=1 or use a non-root user.`;
+                this.ctx.logger.error({ name, backend: backendName }, msg);
+                this.ctx.notifyInstanceTopic(name, t("inst.root_skip_perms"));
+                return;
+            }
+            const backend = native?.backend ?? createBackend(backendName, instanceDir);
+            const daemon = new Daemon(name, config, instanceDir, topicMode, backend, this.ctx.controlClient ?? undefined, this.ctx.logger, runtimeIdentity ?? {
+                kind: "fleet-topic",
+                backend: backendName,
+                model: config.model ?? "default",
+            }, this.ctx.spawnGate, this.ctx.stormWindow, this.ctx.backendOutage);
+            if (native) {
+                daemon.setNativePaneLifecycle(native);
+                native.bindDaemon?.(daemon);
+            }
+            daemon.setDeliveryOutboxPort(this.ctx.deliveryOutbox ?? undefined);
+            daemon.setWorkLeaseCheck(() => this.hasWorkLease(name));
+            if (seedNow)
+                daemon.seedActivityNow();
+            // Read at each spawn so a fleet.yaml reload is honoured (#984).
+            daemon.setPeerWorkingDirectories(backendName === "kiro-cli"
+                ? this.ctx.kiroPeerWorkingDirectories ? () => this.ctx.kiroPeerWorkingDirectories(name) : undefined
+                : () => peerWorkingDirectories(this.ctx.fleetConfig, name, backendName));
+            daemon.setStatusEmojiAvoidList(() => this.ctx.statusEmojiAvoidList?.(name));
+            // Before start: the first spawn builds the command and emits its launch
+            // warning synchronously inside Daemon.start, long before
+            // attachIncidentHandlers runs (#984).
+            this.attachLaunchWarningHandler(name, daemon);
+            this.attachContextLostHandler(name, daemon);
+            daemon.on("durable_delivery_deferred", (data) => {
+                // A daemon without its outbox port cannot update the row directly. The
+                // lifecycle owns the same-process store and records a bounded pre-write
+                // retry instead of leaving the lane in delivering forever.
+                this.ctx.deliveryOutbox?.retryBeforeBegin(data.deliveryId, data.targetBootId, data.attemptNo, data.reason, 5_000);
+            });
+            daemon.on("mcp_tool_response_written", (data) => {
+                if (!data.operationId || data.daemonBootId !== daemon.bootId)
+                    return;
+                try {
+                    this.ctx.deliveryOutbox?.markResponseDelivered(name, data.operationId);
+                }
+                catch (err) {
+                    this.ctx.logger.error({ name, operationId: data.operationId, err }, "Could not persist MCP response-delivered marker");
+                }
+            });
+            this.applyCapacityBackoffBaseline(name, backendName, daemon);
+            // Catch errors from daemon internals (e.g. IPC server) to prevent crashing the fleet process
+            daemon.on("error", (err) => {
+                this.ctx.logger.error({ err, name }, "Daemon emitted error — instance isolated");
+            });
+            if (this.ctx.deliveryOutbox) {
+                // Fence older-generation submissions and reconcile them before Daemon.start
+                // reaches Strategy A's unconditional old-window kill.
+                const recovered = this.ctx.deliveryOutbox.recoverTargetGeneration(name, daemon.bootId);
+                if (recovered.queued || recovered.reconciliationPending) {
+                    this.ctx.logger.warn({ name, ...recovered }, "Preparing durable outbox rows before target generation start");
+                }
+                const reconciled = native
+                    ? { uncertain: 0, safeToStart: await this.ctx.reconcileNativePaneBeforeStart?.(name, daemon) === true }
+                    : await reconcileTargetBeforeStart(this.ctx.deliveryOutbox, name, instanceDir, this.ctx.logger);
+                if (reconciled.uncertain > 0) {
+                    this.ctx.logger.warn({ name, ...reconciled }, "Some durable submissions need operator reconciliation");
+                }
+                if (!reconciled.safeToStart) {
+                    const message = t("delivery.restart_blocked", name);
+                    this.ctx.logger.error({ name, ...reconciled }, message);
+                    this.ctx.notifyFleetError?.(message);
+                    await daemon.abortStartup().catch(err => this.ctx.logger.warn({ err, name }, "Failed to dispose daemon after reconciliation could not verify old CLI exit"));
+                    throw new Error(message);
+                }
+            }
+            if (this.epochOf(name) !== epoch || execution && !execution.current()) {
+                // A stop/restart arrived while this start was reconciling: do not spawn.
+                await daemon.abortStartup().catch(() => { });
+                throw new SupersededStartError(name);
+            }
+            // The startup scan can raise an incident (sign-in screen, fatal modal)
+            // before the handlers below exist and before this daemon is registered;
+            // hold it and deliver it once both are true.
+            daemon.holdStartupIncidents?.();
+            await InstanceLifecycle.startOrDispose(daemon, name, this.ctx.logger, execution || native ? check : undefined);
+            // Publication fence (Phase 2a): the spawn cannot be cancelled, so a stop or
+            // restart requested meanwhile has been waiting behind this transition. A
+            // superseded start must not register, signal ready, or keep its window.
+            if (this.epochOf(name) !== epoch || execution && !execution.current()) {
+                await daemon.abortStartup().catch(err => this.ctx.logger.warn({ err, name }, "Failed to dispose a superseded start"));
+                throw new SupersededStartError(name);
+            }
+            this.capacityBackoffBaselines.delete(name);
+            this.daemons.set(name, daemon);
+            nativePublished = !!native;
+            published?.(daemon); // Exact publication, synchronously after the ownership fence.
+            if (seedNow)
+                this.noteWokeForWork(name);
+            this.ctx.onDaemonReady?.(name, daemon.bootId);
+            daemon.on("auto_pause_requested", safeHandler(async (data) => {
+                await this.pause(name, data?.reason ?? "idle");
+            }, this.ctx.logger, `autoPause[${name}]`));
+            daemon.on("auto_paused", (data) => {
+                this.ctx.eventLog?.insert(name, "instance_paused", { reason: "idle", paused_at: data.pausedAt });
+                this.ctx.logger.info({ name, pausedAt: data.pausedAt }, "Instance auto-paused after idle timeout");
+                this.ctx.setTopicIcon(name, "remove");
+                this.ctx.onAttentionChanged?.(name);
+            });
+            daemon.on("auto_woke", () => {
+                this.ctx.onAttentionChanged?.(name);
+                this.ctx.eventLog?.insert(name, "instance_resumed", { reason: "message" });
+                this.ctx.logger.info({ name }, "Instance auto-woke for delivery");
+                this.ctx.setTopicIcon(name, "green");
+                this.ctx.touchActivity(name);
+            });
+            this.attachIncidentHandlers(name, daemon);
+            // #2897: a new daemon starts with no dialog held; a notice the last one left (a crash, a respawn) is out of date.
+            this.ctx.resolveParkedNotice?.(name);
+            daemon.on("pty_recovered", safeHandler((data) => {
+                const mins = Math.floor(data.downtime_s / 60);
+                const secs = data.downtime_s % 60;
+                const duration = mins > 0 ? `${mins}m ${secs}s` : `${secs}s`;
+                this.ctx.eventLog?.insert(name, "pty_recovered", { downtime_s: data.downtime_s });
+                this.ctx.logger.info({ name, downtime_s: data.downtime_s }, "PTY error recovered");
+                this.ctx.notifyInstanceTopic(name, t("inst.recovered", name, duration));
+                this.ctx.webhookEmit("pty_recovered", name, { downtime_s: data.downtime_s });
+            }, this.ctx.logger, `daemon.pty_recovered[${name}]`));
+            this.attachDeliveryStatusHandlers(name, daemon);
             this.ctx.setTopicIcon(name, "green");
             this.ctx.touchActivity(name);
-        });
-        this.attachIncidentHandlers(name, daemon);
-        // #2897: a new daemon starts with no dialog held; a notice the last one left (a crash, a respawn) is out of date.
-        this.ctx.resolveParkedNotice?.(name);
-        daemon.on("pty_recovered", safeHandler((data) => {
-            const mins = Math.floor(data.downtime_s / 60);
-            const secs = data.downtime_s % 60;
-            const duration = mins > 0 ? `${mins}m ${secs}s` : `${secs}s`;
-            this.ctx.eventLog?.insert(name, "pty_recovered", { downtime_s: data.downtime_s });
-            this.ctx.logger.info({ name, downtime_s: data.downtime_s }, "PTY error recovered");
-            this.ctx.notifyInstanceTopic(name, t("inst.recovered", name, duration));
-            this.ctx.webhookEmit("pty_recovered", name, { downtime_s: data.downtime_s });
-        }, this.ctx.logger, `daemon.pty_recovered[${name}]`));
-        this.attachDeliveryStatusHandlers(name, daemon);
-        this.ctx.setTopicIcon(name, "green");
-        this.ctx.touchActivity(name);
-        // Last: handlers attached and daemon registered, so a held startup incident
-        // (pause, notify) finds both.
-        daemon.releaseStartupIncidents?.();
+            // Last: handlers attached and daemon registered, so a held startup incident
+            // (pause, notify) finds both.
+            daemon.releaseStartupIncidents?.();
+        }
+        catch (error) {
+            // The factory registered helper authority before acquire(). A superseded pre-window start must release it too.
+            if (native && !nativePublished)
+                await native.release("detach").catch(err => this.ctx.logger.warn({ name, err }, "Prepared native authority could not detach"));
+            throw error;
+        }
     }
     isPaused(name) {
         return this.daemons.get(name)?.isPaused ?? hasPausedMarker(this.ctx.getInstanceDir(name));
@@ -1606,11 +1758,30 @@ export class InstanceLifecycle {
         return this.daemons.get(name)?.lastPausedAt ?? readPausedAt(this.ctx.getInstanceDir(name));
     }
     async pause(name, reason = "operator", admission) {
+        this.cancelNativeRecovery(name);
         // Final backstop shared by slash, MCP, Settings, warm-cap, and any future
         // caller. General is the coordinator and must remain resident to route work.
         if (isGeneralInstance(this.ctx.fleetConfig, name)) {
             throw new Error(GENERAL_PAUSE_ERROR);
         }
+        const nativeDaemon = this.daemons.get(name);
+        if (nativeDaemon?.usesNativePane?.()) {
+            if (admission && !admission.current())
+                return;
+            await this.runTransition(name, async () => {
+                if (this.daemons.get(name) !== nativeDaemon || admission && !admission.current())
+                    return;
+                if (!nativeDaemon.nativePaneHasExited() && (!await nativeDaemon.nativePauseReady(admission) || this.daemons.get(name) !== nativeDaemon || !nativeDaemon.nativePauseStillReady()))
+                    return;
+                if (this.daemons.get(name) !== nativeDaemon || admission && !admission.current())
+                    return;
+                await this.stopInTransition(name);
+                this.ctx.setNativePanePaused?.(name, true);
+                writePausedMarker(this.ctx.getInstanceDir(name), Date.now(), reason);
+                this.ctx.onAttentionChanged?.(name);
+            });
+            return;
+        }
         // B1: cancel any pending capacity backoff — a user-initiated pause should
         // not be undone by a queued restart 30–120s later.
         const pendingBackoff = this.capacityBackoffTimers.get(name);
@@ -1694,16 +1865,21 @@ export class InstanceLifecycle {
             clearPausedMarker(instanceDir);
             this.markActivitySeedNow(name);
             try {
+                if (isNativePaneInstance(this.ctx.fleetConfig?.instances[name]))
+                    this.ctx.setNativePanePaused?.(name, false);
                 await this.ctx.startPersistedPausedInstance(name, transition);
             }
             catch (err) {
                 this.clearActivitySeedNow(name);
                 writePausedMarker(instanceDir, pausedAt, reason);
+                if (isNativePaneInstance(this.ctx.fleetConfig?.instances[name]))
+                    this.ctx.setNativePanePaused?.(name, true);
                 throw err;
             }
         }
         this.noteWokeForWork(name);
-        this.ctx.startStatuslineWatcher(name);
+        if (!isNativePaneInstance(this.ctx.fleetConfig?.instances[name]))
+            this.ctx.startStatuslineWatcher(name);
     }
     /**
      * Ownership boundary for a daemon that is not yet registered: if start()
@@ -1737,8 +1913,8 @@ export class InstanceLifecycle {
             this.invalidate(name);
         return this.runTransition(name, () => this.stopInTransition(name), transition);
     }
-    async stopInTransition(name) {
-        this.invalidate(name);
+    async stopInTransition(name, nativeOwner) {
+        this.invalidate(name, nativeOwner);
         this.wokeAt.delete(name);
         this.ctx.setTopicIcon(name, "remove");
         // #2897: a stopped instance holds no dialog — its "needs a human" notices are out of date.
@@ -1763,11 +1939,20 @@ export class InstanceLifecycle {
                 if (!drained)
                     this.ctx.logger.warn({ name }, "Pane write did not drain before durable reconciliation capture; relying on the Enter write-ahead fence");
                 this.ctx.deliveryOutbox.markTargetReconciliationPending(name, daemon.bootId);
-                captured = await capturePendingTargetReconciliation(this.ctx.deliveryOutbox, name, this.ctx.getInstanceDir(name), getTmuxSession(), this.ctx.logger);
+                if (daemon.usesNativePane?.()) {
+                    const reconciled = await daemon.reconcileNativeDeliveries(this.ctx.deliveryOutbox, () => this.daemons.get(name) === daemon);
+                    if (!reconciled)
+                        this.ctx.logger.warn({ name }, "Native stop could not settle every old delivery; retained attempts will not be replayed");
+                }
+                if (!daemon.usesNativePane?.())
+                    captured = await capturePendingTargetReconciliation(this.ctx.deliveryOutbox, name, this.ctx.getInstanceDir(name), getTmuxSession(), this.ctx.logger);
             }
             let stopped = false;
             try {
-                await daemon.stop();
+                if (daemon.usesNativePane?.())
+                    await daemon.stop({ nativePane: "close" });
+                else
+                    await daemon.stop();
                 stopped = true;
             }
             finally {
@@ -1797,6 +1982,11 @@ export class InstanceLifecycle {
             if (this.daemons.get(name) === daemon)
                 this.daemons.delete(name);
         }
+        else if (isNativePaneInstance(this.ctx.fleetConfig?.instances[name])) {
+            if (!this.ctx.closeRetainedNativePane)
+                throw Error("Retained native pane owner is unavailable; no local PID was signalled");
+            await this.ctx.closeRetainedNativePane(name);
+        }
         else {
             const instanceDir = this.ctx.getInstanceDir(name);
             const pidPath = join(instanceDir, "daemon.pid");
@@ -1983,6 +2173,27 @@ export class InstanceLifecycle {
     async handleCreate(args, respond, adapterId, execution) {
         const check = () => execution?.assert();
         check();
+        if (args.runtime !== undefined && args.runtime !== "wsl" && args.runtime !== "windows") {
+            respond(null, "Unknown instance runtime");
+            return;
+        }
+        // M-2239 P1-1: a Windows agent is created only from the admin web dashboard (native-instance-api.ts), never through
+        // create_instance, deploy_template or any other path that reaches here — an agent holding create_instance could
+        // otherwise start one on the Windows host, in any drive path, with write access.
+        if (args.runtime === "windows") {
+            respond(null, WINDOWS_CREATE_REFUSED);
+            return;
+        }
+        // #3021 review: on a fleet with no chat connection a new agent never becomes a second General (it would inherit
+        // defaults.general_topic: true while the fleet has one).
+        if (this.ctx.fleetConfig && addsSecondGeneral(this.ctx.fleetConfig)) {
+            respond(null, "one_general: this fleet already has its General, and a new agent would inherit defaults.general_topic: true — set it to false in the defaults first");
+            return;
+        }
+        if (args.sandbox !== undefined) {
+            respond(null, "sandbox is supported only by the Windows runtime");
+            return;
+        }
         const rawDirectory = args.directory;
         const directory = rawDirectory ? rawDirectory.replace(/^~/, process.env.HOME || "~") : undefined;
         const topicName = args.topic_name || (directory ? basename(directory) : undefined);
@@ -2273,6 +2484,11 @@ export class InstanceLifecycle {
             createdConfig = instanceConfig;
             const beforeCreate = structuredClone(this.ctx.fleetConfig);
             const persist = () => {
+                // #3021 review r2: asked again at the commit, after every await — two creates that both saw no General at entry
+                // (defaults.general_topic: true) must not both become one.
+                if (addsSecondGeneral(this.ctx.fleetConfig, { general_topic: instanceConfig.general_topic })) {
+                    throw new Error("one_general: this fleet already has its General, and a new agent would inherit defaults.general_topic: true — set it to false in the defaults first");
+                }
                 this.ctx.fleetConfig.instances[newInstanceName] = instanceConfig;
                 if (createdTopicId != null)
                     this.ctx.routing.register(createdTopicId, { kind: "instance", name: newInstanceName });