pi-amq 0.1.1

package/dist/extension/runtime.js

@@ -0,0 +1,1095 @@
+import { access, readFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { CommandContextFreshSessionCapability, FreshSessionDispatcher, } from "../integration/fresh-session-dispatcher.js";
+import { ConfirmedBindOnboarding, parseRosterInput, } from "../integration/confirmed-bind-onboarding.js";
+import { FleetListModel, FleetDetailController, MutableFleetProjectionSource, handleFleetInput, renderFleetDetail, } from "../integration/fleet-view.js";
+import { AmqCliAdapter } from "../transport/amq-cli-adapter.js";
+import { AmqOperations, safeProjection } from "../transport/amq-operations.js";
+import { BindingResolver, PI_AMQ_BINDING_ENTRY_TYPE, } from "../transport/binding-resolver.js";
+import { BridgeJournal } from "../transport/bridge-journal.js";
+import { InboxPump, LeaseBackedInboxAuthority } from "../transport/inbox-pump.js";
+import { PresenceProjector } from "../transport/presence-projector.js";
+import { PI_AMQ_CUSTOM_TYPE, planPriorityDeliveries, PriorityDeliveryScheduler, } from "../transport/priority-delivery-scheduler.js";
+import { LocalProcessIdentityInspector, ReceiverLeaseManager } from "../transport/receiver-lease.js";
+import { InboxStatusStore, projectInboxStatus, receiverLeaseRuntimeDisposition, } from "../transport/runtime-status.js";
+import { ALL_AMQ_TOOLS, NON_CONSUMING_AMQ_TOOLS, registerAmqTools } from "./tools.js";
+import { InstalledPackageGuide, registerGuideTool } from "./guide.js";
+import { PiWorkerRuntime } from "./worker-runtime.js";
+import { registerWorkerTools } from "./worker-tools.js";
+import { parseCleanupAge } from "../workflow/run-cleanup.js";
+import { appendAmqMessagingDoctrine, appendWorkerTeamDoctrine, buildBeforeAgentGuidance, buildPendingProjection, } from "./guidance.js";
+const PENDING_PROJECTION_TYPE = "pi-amq-pending/v1";
+const WIDGET_KEY = "pi-amq-fleet";
+const FRESH_SESSION_COMMAND = "amq-new-task";
+export class PiAmqRuntime {
+    #pi;
+    #workers;
+    #freshSessionPort;
+    #guide = new InstalledPackageGuide();
+    #status = new InboxStatusStore();
+    #fleet = new MutableFleetProjectionSource([]);
+    #mainFleet;
+    #workerFleet = [];
+    #adapter;
+    #resolver;
+    #binding;
+    #operations;
+    #receiver;
+    #ctx;
+    #unsubscribeStatus;
+    #unsubscribeTerminal;
+    #fleetModel;
+    #started = false;
+    #paused = false;
+    constructor(pi) {
+        this.#pi = pi;
+        this.#freshSessionPort = new PiFreshSessionReplacementPort(pi);
+        this.#workers = new PiWorkerRuntime((records) => {
+            this.#workerFleet = records;
+            this.#commitFleet();
+        }, () => this.#pi.getFlag("worker-unlimited"), async (projection) => {
+            const operations = this.#operations;
+            const recipients = (process.env.PI_AMQ_LIFECYCLE_TO ?? "")
+                .split(",")
+                .map((item) => item.trim())
+                .filter(Boolean);
+            if (!operations || recipients.length === 0)
+                return;
+            const result = await operations.send({
+                to: recipients,
+                body: projection.body,
+                kind: "status",
+                labels: projection.labels,
+                context: projection.context,
+            });
+            if (!result.ok) {
+                this.#status.update({ lastError: `Worker lifecycle projection failed: ${result.error.message}` });
+            }
+        }, (notice) => {
+            this.#ctx?.ui.notify(notice.message, notice.level);
+        });
+    }
+    register() {
+        this.#registerFlags();
+        this.#registerRenderers();
+        registerAmqTools(this.#pi, {
+            operations: () => this.#operations,
+            canConsume: () => this.#receiver !== undefined && !this.#paused,
+            canSetPresence: () => this.#receiver !== undefined && !this.#paused,
+        });
+        registerWorkerTools(this.#pi, this.#workers);
+        registerGuideTool(this.#pi, this.#guide);
+        this.#registerCommands();
+        this.#pi.on("session_start", async (_event, ctx) => {
+            this.#ctx = ctx;
+            await this.#workers.start(ctx);
+            await this.start(ctx);
+        });
+        this.#pi.on("session_shutdown", async () => {
+            await this.#workers.shutdown();
+            await this.shutdown();
+        });
+        this.#pi.on("agent_start", async (_event, ctx) => {
+            this.#updateMainFleet(ctx, "busy");
+            await this.#receiver?.presence.busy(ctx.signal);
+        });
+        this.#pi.on("agent_settled", async (_event, ctx) => {
+            this.#updateMainFleet(ctx, "idle");
+            await this.#receiver?.presence.idle(ctx.signal);
+        });
+        this.#pi.on("model_select", async (event, ctx) => {
+            await this.#workers.refreshGuidance(ctx);
+            this.#updateMainFleet(ctx, ctx.isIdle() ? "idle" : "busy", event.model.id);
+            await this.#receiver?.presence.modelNote(event.model.id, ctx.signal);
+        });
+        this.#pi.on("session_compact", async () => {
+            const records = await this.#receiver?.journal.list() ?? [];
+            this.#pi.appendEntry(PENDING_PROJECTION_TYPE, buildPendingProjection(records.filter((record) => record.phase === "pending").map((record) => record.id), this.#status.snapshot()));
+        });
+        this.#pi.on("before_agent_start", (event, ctx) => ({
+            systemPrompt: this.#workers.appendGuidance(appendWorkerTeamDoctrine(appendAmqMessagingDoctrine(event.systemPrompt))),
+            message: {
+                customType: "pi-amq-guidance",
+                display: false,
+                content: buildBeforeAgentGuidance({
+                    ...(this.#binding ? {
+                        identity: {
+                            handle: this.#binding.handle,
+                            project: this.#binding.project,
+                            session: this.#binding.session,
+                            mode: this.#receiver ? "receiving" : "send-only",
+                        },
+                    } : {}),
+                    envelopes: collectEnvelopeDetails(ctx),
+                    status: this.#status.snapshot(),
+                }),
+            },
+        }));
+        this.#pi.on("input", (_event, ctx) => {
+            this.#ctx = ctx;
+        });
+    }
+    async start(ctx) {
+        if (this.#started)
+            await this.shutdown();
+        this.#started = true;
+        this.#ctx = ctx;
+        let binaryPath;
+        try {
+            binaryPath = await resolveAmqBinary(process.env.PI_AMQ_BINARY);
+            this.#adapter = new AmqCliAdapter({ binaryPath });
+        }
+        catch (error) {
+            this.#binding = undefined;
+            this.#operations = undefined;
+            this.#status.update({
+                receiver: "dormant",
+                watch: "disabled",
+                receiverGeneration: null,
+                lastError: `AMQ binary configuration failed: ${toError(error).message}; /amq bind`,
+            });
+            this.#activateTools("dormant");
+            this.#installSurfaces(ctx);
+            this.#updateMainFleet(ctx, "offline");
+            return;
+        }
+        this.#resolver = new BindingResolver(this.#adapter);
+        const persisted = latestBinding(ctx);
+        const resolution = await this.#resolver.resolve({
+            flags: this.#flags(),
+            environment: process.env,
+            ...(persisted ? { persistedBinding: persisted } : {}),
+        });
+        if (resolution.kind === "dormant") {
+            this.#binding = undefined;
+            this.#operations = undefined;
+            this.#status.update({
+                receiver: "dormant",
+                watch: "disabled",
+                receiverGeneration: null,
+                lastError: await this.#bindingFailureDiagnostic(resolution.diagnostic),
+            });
+            this.#activateTools("dormant");
+            this.#installSurfaces(ctx);
+            this.#updateMainFleet(ctx, "offline");
+            return;
+        }
+        await this.#activateBound(ctx, resolution.binding);
+    }
+    async shutdown() {
+        if (!this.#started)
+            return;
+        this.#started = false;
+        this.#paused = false;
+        const receiver = this.#receiver;
+        this.#receiver = undefined;
+        if (receiver) {
+            receiver.abortController.abort(new Error("pi-amq session shutdown"));
+            await receiver.pumpTask.catch((error) => {
+                this.#status.update({ lastError: `Inbox pump shutdown failed: ${toError(error).message}` });
+            });
+            await receiver.presence.offline();
+            try {
+                const release = await receiver.lease.release(receiver.generation);
+                if (release.kind === "refused")
+                    this.#status.update({ lastError: release.diagnostic });
+            }
+            catch (error) {
+                this.#status.update({ lastError: `Receiver lease release failed: ${toError(error).message}` });
+            }
+        }
+        this.#unsubscribeStatus?.();
+        this.#unsubscribeStatus = undefined;
+        this.#unsubscribeTerminal?.();
+        this.#unsubscribeTerminal = undefined;
+        this.#fleetModel?.dispose();
+        this.#fleetModel = undefined;
+        this.#ctx?.ui.setStatus("pi-amq", undefined);
+        this.#ctx?.ui.setWidget(WIDGET_KEY, undefined);
+        this.#status.update({ receiver: "dormant", watch: "stopped", receiverGeneration: null });
+    }
+    async #activateBound(ctx, binding) {
+        if (!this.#adapter || !this.#resolver)
+            throw new Error("AMQ runtime is not initialized");
+        this.#binding = binding;
+        this.#pi.appendEntry(PI_AMQ_BINDING_ENTRY_TYPE, binding);
+        this.#operations = new AmqOperations({
+            adapter: this.#adapter,
+            binding: {
+                root: binding.root,
+                handle: binding.handle,
+                project: binding.project,
+                session: binding.session,
+            },
+            replyRouteLookup: replyRoutes(ctx),
+        });
+        this.#installSurfaces(ctx);
+        if (ctx.mode === "print" || ctx.mode === "json") {
+            this.#status.update({
+                receiver: "send-only",
+                watch: "disabled",
+                receiverGeneration: null,
+                lastError: null,
+            });
+            this.#activateTools("send-only");
+            this.#updateMainFleet(ctx, "idle");
+            return;
+        }
+        const sessionFile = ctx.sessionManager.getSessionFile();
+        if (!sessionFile || !isAbsolute(sessionFile)) {
+            this.#status.update({
+                receiver: "send-only",
+                watch: "disabled",
+                receiverGeneration: null,
+                lastError: "Pi session file is not disk-visible; receiver activation is deferred",
+            });
+            this.#activateTools("send-only");
+            this.#updateMainFleet(ctx, "idle");
+            return;
+        }
+        const namespaceDirectory = join(binding.root, "agents", binding.handle, "extensions", "pi-amq-extension");
+        const lease = new ReceiverLeaseManager({
+            namespaceDirectory,
+            rootId: binding.rootId,
+            inspector: new LocalProcessIdentityInspector(),
+        });
+        let acquired;
+        try {
+            acquired = await lease.acquire({
+                piSessionId: ctx.sessionManager.getSessionId(),
+                piSessionFile: sessionFile,
+            });
+        }
+        catch (error) {
+            this.#status.update({
+                receiver: "send-only",
+                watch: "disabled",
+                receiverGeneration: null,
+                lastError: `Receiver lease activation failed: ${toError(error).message}`,
+            });
+            this.#activateTools("send-only");
+            this.#updateMainFleet(ctx, "idle");
+            return;
+        }
+        const leaseDisposition = receiverLeaseRuntimeDisposition(acquired);
+        if (leaseDisposition.mode === "send-only") {
+            this.#status.update({
+                receiver: "send-only",
+                watch: "disabled",
+                receiverGeneration: null,
+                lastError: leaseDisposition.diagnostic,
+            });
+            this.#activateTools("send-only");
+            this.#updateMainFleet(ctx, "idle");
+            return;
+        }
+        if (acquired.kind !== "acquired")
+            throw new Error("Receiver lease disposition disagrees with acquisition result");
+        const journal = new BridgeJournal({ namespaceDirectory, leaseManager: lease });
+        const lookup = new PiSessionProjectionLookup(ctx);
+        const sink = new PiDeliverySink(this.#pi, lookup);
+        const scheduler = new PriorityDeliveryScheduler({ sink });
+        const authority = new LeaseBackedInboxAuthority({
+            lease,
+            generation: acquired.owner.generation,
+            verifyBinding: async () => {
+                const current = await this.#resolver.resolve({
+                    flags: this.#flags(),
+                    environment: process.env,
+                    persistedBinding: binding,
+                });
+                return current.kind === "bound"
+                    && current.binding.rootId === binding.rootId
+                    && current.binding.handle === binding.handle
+                    ? { kind: "valid" }
+                    : { kind: "invalid", diagnostic: current.kind === "dormant" ? current.diagnostic : "AMQ binding authority changed" };
+            },
+        });
+        const fresh = new FreshSessionDispatcher({
+            capability: new CommandContextFreshSessionCapability(this.#freshSessionPort),
+            policy: {
+                trustedProject: ctx.isProjectTrusted(),
+                allowlisted: (sender, project) => freshAllowlist().has(`${sender}@${project}`),
+                ...(ctx.hasUI ? {
+                    confirm: async (message) => ctx.ui.confirm("AMQ fresh session", `${message.header.from} [${message.header.fromProject || "unknown project"}] requests replacing the current session: ${message.header.subject || "(no subject)"}`),
+                } : {}),
+                canReplaceSession: async () => this.#workers.canReplaceSession(),
+                notifyOnce: (message) => ctx.ui.notify(message, "warning"),
+            },
+        });
+        const pump = new InboxPump({
+            adapter: this.#adapter,
+            binding: {
+                root: binding.root,
+                rootId: binding.rootId,
+                handle: binding.handle,
+            },
+            receiverGeneration: acquired.owner.generation,
+            targetSessionId: ctx.sessionManager.getSessionId(),
+            authority,
+            journal,
+            scheduler,
+            status: this.#status,
+            projectionLookup: lookup,
+            freshSessionDispatcher: fresh,
+        });
+        this.#operations = new AmqOperations({
+            adapter: this.#adapter,
+            binding: {
+                root: binding.root,
+                handle: binding.handle,
+                project: binding.project,
+                session: binding.session,
+            },
+            claimPort: pump,
+            replyRouteLookup: replyRoutes(ctx),
+        });
+        const presence = new PresenceProjector({
+            writer: {
+                setStatus: async (status, note, signal) => {
+                    const result = await this.#operations.setStatus(status, note, signal);
+                    return result.ok ? { ok: true } : { ok: false, error: result.error };
+                },
+            },
+        });
+        const abortController = new AbortController();
+        const receiver = {
+            lease,
+            generation: acquired.owner.generation,
+            journal,
+            pump,
+            presence,
+            abortController,
+            pumpTask: Promise.resolve(),
+        };
+        this.#paused = false;
+        receiver.pumpTask = pump.run(abortController.signal).catch((error) => {
+            this.#status.update({ lastError: `Inbox pump stopped: ${toError(error).message}` });
+        });
+        this.#receiver = receiver;
+        this.#status.update({
+            receiver: "receiving",
+            receiverGeneration: acquired.owner.generation,
+            lastError: null,
+        });
+        this.#activateTools("receiving");
+        this.#updateMainFleet(ctx, "idle");
+        await presence.idle();
+    }
+    #registerFlags() {
+        this.#pi.registerFlag("amq-handle", { type: "string", description: "Explicit AMQ handle" });
+        this.#pi.registerFlag("amq-root", { type: "string", description: "Explicit physical AMQ root" });
+        this.#pi.registerFlag("amq-session", { type: "string", description: "Explicit AMQ session" });
+        this.#pi.registerFlag("amq-mode", { type: "string", description: "Opaque AMQ mode modifier" });
+        this.#pi.registerFlag("worker-unlimited", {
+            type: "string",
+            description: "Explicit comma-separated unlimited worker-run budget dimensions (or all)",
+        });
+    }
+    async #bindingFailureDiagnostic(primary) {
+        if (!this.#adapter)
+            return `${primary}; /amq bind`;
+        const root = stringFlag(this.#pi.getFlag("amq-root")) ?? process.env.AM_ROOT;
+        const handle = stringFlag(this.#pi.getFlag("amq-handle")) ?? process.env.AM_ME;
+        if (!root || !handle || !isAbsolute(root))
+            return `${primary}; /amq bind`;
+        return diagnoseBindingFailure(this.#adapter, primary, root, handle);
+    }
+    #registerRenderers() {
+        this.#pi.registerMessageRenderer(PI_AMQ_CUSTOM_TYPE, (message, { expanded }, theme) => {
+            const count = message.details?.messageIds.length ?? 0;
+            const header = theme.fg("accent", `[AMQ ${message.details?.priority ?? "mail"} · ${count}]`);
+            const raw = typeof message.content === "string" ? message.content : "[non-text AMQ message]";
+            const text = expanded ? raw : raw.split("\n").slice(0, 12).join("\n");
+            return {
+                render: (width) => `${header}\n${text}`.split("\n").map((line) => bounded(line, Math.max(1, width))),
+                invalidate: () => undefined,
+            };
+        });
+    }
+    #registerCommands() {
+        this.#pi.registerCommand("amq", {
+            description: "AMQ status, inbox, bind, pause, resume, ingest, takeover, dlq, trace, or doctor",
+            handler: async (args, ctx) => this.#handleCommand(args, ctx),
+        });
+        this.#pi.registerCommand("pi-amq-guide", {
+            description: "Read installed pi-amq guidance by topic",
+            handler: async (args, ctx) => {
+                try {
+                    this.#show(ctx, await this.#guide.read(args));
+                }
+                catch (error) {
+                    this.#show(ctx, { error: { category: "guide", message: toError(error).message } });
+                }
+            },
+        });
+        this.#pi.registerCommand("pi-amq-cleanup", {
+            description: "Dry-run or explicitly delete old terminal workflow runs",
+            handler: async (args, ctx) => {
+                try {
+                    const params = parseCleanupCommand(args);
+                    this.#show(ctx, await this.#workers.cleanupRuns(params, ctx.signal, ctx));
+                }
+                catch (error) {
+                    this.#show(ctx, { error: { category: "workflow-cleanup", message: toError(error).message } });
+                }
+            },
+        });
+        this.#pi.registerCommand("pi-amq-doctor", {
+            description: "Read-only workflow ledger, process, lease, session, and disk diagnostics",
+            handler: async (_args, ctx) => {
+                try {
+                    this.#show(ctx, await this.#workers.doctorWorkflow(ctx.signal, ctx));
+                }
+                catch (error) {
+                    this.#show(ctx, { error: { category: "workflow-doctor", message: toError(error).message } });
+                }
+            },
+        });
+        this.#pi.registerCommand(FRESH_SESSION_COMMAND, {
+            description: "Internal: complete a fresh-session AMQ dispatch (invoked via expandPromptTemplates, not by hand)",
+            handler: async (args, ctx) => this.#freshSessionPort.handleCommand(args, ctx),
+        });
+    }
+    async #handleCommand(raw, ctx) {
+        const [command = "status", ...rest] = raw.trim().split(/\s+/).filter(Boolean);
+        switch (command) {
+            case "status":
+                return this.#show(ctx, {
+                    binding: this.#binding ?? null,
+                    mode: ctx.mode,
+                    status: this.#status.snapshot(),
+                    presence: this.#receiver?.presence.snapshot() ?? null,
+                    lease: this.#receiver ? await this.#receiver.lease.inspectLease() : null,
+                });
+            case "inbox": {
+                if (!this.#operations)
+                    return this.#show(ctx, "pi-amq is dormant; use /amq bind");
+                const [fresh, current, journal] = await Promise.all([
+                    this.#operations.inbox({ box: "new", limit: 20 }, ctx.signal),
+                    this.#operations.inbox({ box: "cur", limit: 20 }, ctx.signal),
+                    this.#receiver?.journal.list() ?? [],
+                ]);
+                return this.#show(ctx, { new: fresh, cur: current, bridge: journal });
+            }
+            case "bind":
+                return this.#bind(ctx);
+            case "pause":
+                return this.#pause(ctx);
+            case "resume":
+                return this.#resume(ctx);
+            case "ingest": {
+                if (!this.#receiver)
+                    return this.#show(ctx, "No owning receiver; /amq ingest is unavailable");
+                if (this.#paused)
+                    return this.#show(ctx, "AMQ receiver is paused; resume before ingesting staged mail");
+                const count = await this.#receiver.pump.ingestStaged(ctx.signal);
+                return this.#show(ctx, `Promoted ${count} staged envelope(s)`);
+            }
+            case "takeover":
+                return this.#takeover(ctx);
+            case "dlq": {
+                if (!this.#operations)
+                    return this.#show(ctx, "pi-amq is dormant; use /amq bind");
+                return this.#show(ctx, await this.#operations.dlqList(20, ctx.signal));
+            }
+            case "trace": {
+                if (!this.#operations)
+                    return this.#show(ctx, "pi-amq is dormant; use /amq bind");
+                if (!rest[0])
+                    return this.#show(ctx, "Usage: /amq trace <id>");
+                return this.#show(ctx, await this.#operations.trace(rest[0], ctx.signal));
+            }
+            case "doctor": {
+                if (!this.#operations)
+                    return this.#show(ctx, "pi-amq is dormant; use /amq bind");
+                const result = await this.#operations.doctor(ctx.signal);
+                return this.#showDoctor(ctx, result);
+            }
+            default:
+                return this.#show(ctx, "Usage: /amq status|inbox|bind|pause|resume|ingest|takeover|dlq|trace <id>|doctor");
+        }
+    }
+    async #bind(ctx) {
+        if (!this.#resolver || !this.#adapter)
+            return this.#show(ctx, "AMQ binary is not initialized; reload the session");
+        const resolution = await this.#resolver.resolve({ flags: this.#flags(), environment: process.env });
+        if (resolution.kind === "bound") {
+            if (!ctx.hasUI)
+                return this.#show(ctx, `Binding requires confirmation. Candidate: ${JSON.stringify(resolution.binding)}`);
+            const confirmed = await ctx.ui.confirm("Bind pi-amq", `Bind ${resolution.binding.handle} to ${resolution.binding.root} (${resolution.binding.project}/${resolution.binding.session || "base"})?`);
+            if (!confirmed)
+                return this.#show(ctx, "AMQ bind cancelled; no state changed");
+            return this.#finishConfirmedBind(ctx, resolution.binding);
+        }
+        const onboarding = new ConfirmedBindOnboarding(this.#adapter, this.#resolver);
+        let preview;
+        try {
+            preview = await this.#onboardingPreview(onboarding, ctx);
+        }
+        catch (error) {
+            return this.#show(ctx, `${resolution.diagnostic}; onboarding refused: ${toError(error).message}`);
+        }
+        if (!ctx.hasUI) {
+            return this.#show(ctx, `Binding requires TUI confirmation; pi-amq remains dormant. Preview: ${renderBindPreview(preview)}`);
+        }
+        const confirmed = await ctx.ui.confirm("Provision and bind pi-amq", renderBindPreview(preview));
+        const result = await onboarding.confirm(preview, confirmed, process.env);
+        if (result.kind !== "bound")
+            return this.#show(ctx, result.diagnostic);
+        return this.#finishConfirmedBind(ctx, result.binding);
+    }
+    async #onboardingPreview(onboarding, ctx) {
+        const defaults = this.#flags();
+        let root = defaults.root ?? join(ctx.cwd, ".agent-mail");
+        let handle = defaults.handle ?? process.env.AM_ME ?? "pi-main";
+        let agents = parseRosterInput(`user,${handle}`, handle);
+        if (ctx.hasUI) {
+            const selectedRoot = await ctx.ui.input("AMQ physical root", root);
+            if (selectedRoot === undefined)
+                throw new Error("AMQ bind cancelled before root selection; no state changed");
+            root = selectedRoot;
+            const selectedHandle = await ctx.ui.input("AMQ handle", handle);
+            if (selectedHandle === undefined)
+                throw new Error("AMQ bind cancelled before handle selection; no state changed");
+            handle = selectedHandle;
+            const selectedAgents = await ctx.ui.input("Complete AMQ roster (comma-separated, including user)", `user,${handle}`);
+            if (selectedAgents === undefined)
+                throw new Error("AMQ bind cancelled before roster selection; no state changed");
+            agents = parseRosterInput(selectedAgents, handle);
+        }
+        return onboarding.preview({
+            projectDirectory: ctx.cwd,
+            root,
+            handle,
+            agents,
+            environment: process.env,
+        });
+    }
+    async #finishConfirmedBind(ctx, binding) {
+        await this.shutdown();
+        this.#started = true;
+        this.#ctx = ctx;
+        this.#adapter = new AmqCliAdapter({ binaryPath: await resolveAmqBinary(process.env.PI_AMQ_BINARY) });
+        this.#resolver = new BindingResolver(this.#adapter);
+        await this.#activateBound(ctx, binding);
+        this.#show(ctx, `Bound and verified ${binding.handle}`);
+    }
+    async #pause(ctx) {
+        const receiver = this.#receiver;
+        if (!receiver)
+            return this.#show(ctx, "No owning receiver to pause");
+        this.#paused = true;
+        this.#activateTools("send-only");
+        receiver.abortController.abort(new Error("pi-amq paused"));
+        await receiver.pumpTask;
+        await receiver.presence.paused();
+        this.#status.update({ watch: "stopped" });
+        this.#updateMainFleet(ctx, "paused");
+        this.#show(ctx, "AMQ receiver paused; lease retained");
+    }
+    async #resume(ctx) {
+        const receiver = this.#receiver;
+        if (!receiver)
+            return this.#show(ctx, "No owning receiver to resume");
+        if (!receiver.abortController.signal.aborted)
+            return this.#show(ctx, "AMQ receiver is already running");
+        if (!await this.#bindingIsCurrent()) {
+            return this.#show(ctx, "AMQ binding revalidation failed; resume refused");
+        }
+        const authority = await receiver.lease.withCurrentLease(receiver.generation, async () => true).catch(() => false);
+        if (!authority)
+            return this.#show(ctx, "Receiver lease revalidation failed; resume refused");
+        this.#paused = false;
+        this.#activateTools("receiving");
+        receiver.abortController = new AbortController();
+        receiver.pumpTask = receiver.pump.run(receiver.abortController.signal).catch((error) => {
+            this.#status.update({ lastError: `Inbox pump stopped: ${toError(error).message}` });
+        });
+        await receiver.presence.idle();
+        this.#updateMainFleet(ctx, "idle");
+        this.#show(ctx, "AMQ receiver resumed after lease revalidation");
+    }
+    async #bindingIsCurrent() {
+        if (!this.#resolver || !this.#binding)
+            return false;
+        const resolution = await this.#resolver.resolve({
+            flags: this.#flags(),
+            environment: process.env,
+            persistedBinding: this.#binding,
+        });
+        return resolution.kind === "bound"
+            && resolution.binding.rootId === this.#binding.rootId
+            && resolution.binding.handle === this.#binding.handle;
+    }
+    async #takeover(ctx) {
+        if (this.#receiver)
+            return this.#show(ctx, "This session already owns the receiver lease");
+        if (!this.#binding)
+            return this.#show(ctx, "pi-amq is dormant; bind first");
+        if (!ctx.hasUI)
+            return this.#show(ctx, "Takeover requires UI confirmation and never forces live or unverifiable ownership");
+        if (!await ctx.ui.confirm("AMQ takeover", "Re-inspect and quarantine only a proven-stale receiver generation?")) {
+            return this.#show(ctx, "AMQ takeover cancelled");
+        }
+        await this.start(ctx);
+        this.#show(ctx, this.#receiver ? "Receiver acquired through the ordinary stale-proof path" : this.#status.snapshot().lastError ?? "Takeover refused");
+    }
+    #installSurfaces(ctx) {
+        this.#unsubscribeStatus?.();
+        this.#unsubscribeStatus = this.#status.subscribe((status) => {
+            const projected = projectInboxStatus(ctx.mode, status);
+            ctx.ui.setStatus("pi-amq", projected.surface === "tui" ? projected.text : projected.surface === "rpc" ? JSON.stringify(projected.value) : undefined);
+        });
+        const initial = projectInboxStatus(ctx.mode, this.#status.snapshot());
+        ctx.ui.setStatus("pi-amq", initial.surface === "tui" ? initial.text : initial.surface === "rpc" ? JSON.stringify(initial.value) : undefined);
+        this.#unsubscribeTerminal?.();
+        this.#fleetModel?.dispose();
+        if (ctx.mode === "tui") {
+            ctx.ui.setWidget(WIDGET_KEY, (tui) => {
+                const model = new FleetListModel(this.#fleet, () => tui.requestRender());
+                this.#fleetModel = model;
+                return {
+                    render: () => model.render(),
+                    invalidate: () => undefined,
+                    dispose: () => model.dispose(),
+                };
+            }, { placement: "belowEditor" });
+            this.#unsubscribeTerminal = ctx.ui.onTerminalInput((data) => {
+                const list = this.#fleetModel;
+                if (!list)
+                    return undefined;
+                const result = handleFleetInput({ data, editorText: ctx.ui.getEditorText(), list });
+                if (!result.consume)
+                    return undefined;
+                if (result.action === "detail" && list.selected)
+                    void this.#openFleetDetail(ctx, list.selected);
+                return { consume: true };
+            });
+        }
+        else if (ctx.mode === "rpc") {
+            ctx.ui.setWidget(WIDGET_KEY, this.#fleet.snapshot().flatMap(renderFleetRow), { placement: "belowEditor" });
+        }
+        else {
+            ctx.ui.setWidget(WIDGET_KEY, undefined);
+        }
+    }
+    async #openFleetDetail(ctx, record) {
+        await ctx.ui.custom((tui, _theme, _keys, done) => {
+            const unsubscribe = this.#fleet.subscribe(() => tui.requestRender());
+            const controller = new FleetDetailController({
+                record,
+                resolve: () => this.#fleet.snapshot().find((candidate) => candidate.id === record.id),
+                steer: async (workerId, generation, message) => {
+                    await this.#workers.steerFromFleet(workerId, generation, message);
+                    tui.requestRender();
+                },
+                cancel: async (workerId, generation) => {
+                    await this.#workers.cancelFromFleet(workerId, generation);
+                    tui.requestRender();
+                },
+            });
+            return {
+                render: () => controller.render(),
+                invalidate: () => undefined,
+                handleInput: (data) => {
+                    const result = controller.handleInput(data);
+                    if (result.close)
+                        done(undefined);
+                    else if (result.consumed)
+                        tui.requestRender();
+                },
+                dispose: unsubscribe,
+            };
+        }, { overlay: true });
+    }
+    #updateMainFleet(ctx, state, selectedModel) {
+        const previous = this.#mainFleet;
+        this.#mainFleet = {
+            id: ctx.sessionManager.getSessionId(),
+            handle: this.#binding?.handle ?? "main",
+            role: "main",
+            model: selectedModel ?? ctx.model?.id ?? previous?.model ?? "unselected",
+            state,
+            spend: null,
+            lastActivity: new Date().toISOString(),
+            mode: "main",
+        };
+        this.#commitFleet();
+    }
+    #commitFleet() {
+        this.#fleet.update([
+            ...(this.#mainFleet ? [this.#mainFleet] : []),
+            ...this.#workerFleet,
+        ]);
+        if (this.#ctx?.mode === "rpc") {
+            this.#ctx.ui.setWidget(WIDGET_KEY, this.#fleet.snapshot().flatMap(renderFleetRow), { placement: "belowEditor" });
+        }
+    }
+    #activateTools(mode) {
+        const existing = this.#pi.getActiveTools().filter((name) => !ALL_AMQ_TOOLS.includes(name));
+        const enabled = mode === "dormant"
+            ? []
+            : mode === "send-only"
+                ? ["amq_send", "amq_reply", ...NON_CONSUMING_AMQ_TOOLS]
+                : [...ALL_AMQ_TOOLS];
+        this.#pi.setActiveTools([...existing, ...enabled]);
+    }
+    #flags() {
+        return {
+            ...flag(this.#pi.getFlag("amq-handle"), "handle"),
+            ...flag(this.#pi.getFlag("amq-root"), "root"),
+            ...flag(this.#pi.getFlag("amq-session"), "session"),
+            ...flag(this.#pi.getFlag("amq-mode"), "mode"),
+        };
+    }
+    #show(ctx, value) {
+        const text = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+        ctx.ui.notify(bounded(text, 12 * 1024), text.includes("error") ? "warning" : "info");
+    }
+    #showDoctor(ctx, value) {
+        if (ctx.mode === "print" || ctx.mode === "json") {
+            return this.#show(ctx, "Doctor UI cards are unavailable in this mode; run `amq doctor --root <verified-root> --ops --json` manually");
+        }
+        if (typeof value === "object" && value && "ok" in value && "value" in value
+            && value.ok) {
+            const payload = value.value;
+            const findings = Array.isArray(payload)
+                ? payload
+                : payload && typeof payload === "object" && "checks" in payload && Array.isArray(payload.checks)
+                    ? payload.checks
+                    : undefined;
+            if (findings) {
+                for (const finding of findings.slice(0, 50)) {
+                    const card = finding && typeof finding === "object"
+                        ? finding
+                        : { message: finding };
+                    const status = typeof card.status === "string" ? card.status : "info";
+                    const name = typeof card.name === "string" ? card.name : "AMQ doctor";
+                    const message = typeof card.message === "string" ? card.message : JSON.stringify(card);
+                    ctx.ui.notify(`${name}: ${message}`, status === "error" ? "error" : status === "warn" ? "warning" : "info");
+                }
+                return;
+            }
+        }
+        this.#show(ctx, value);
+    }
+}
+export function parseCleanupCommand(raw) {
+    const args = raw.trim().split(/\s+/).filter(Boolean);
+    let age;
+    let dryRun = true;
+    let yes = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        switch (arg) {
+            case "--older-than": {
+                const value = args[index + 1];
+                if (!value)
+                    throw new TypeError("--older-than requires a duration");
+                age = parseCleanupAge(value);
+                index += 1;
+                break;
+            }
+            case "--dry-run":
+                dryRun = true;
+                break;
+            case "--delete":
+                dryRun = false;
+                break;
+            case "--yes":
+                yes = true;
+                break;
+            default:
+                throw new TypeError(`Unknown cleanup option: ${arg}`);
+        }
+    }
+    if (age === undefined) {
+        throw new TypeError("Usage: /pi-amq-cleanup --older-than <duration> [--delete] [--yes]");
+    }
+    return { older_than_ms: age, dry_run: dryRun, yes };
+}
+export async function diagnoseBindingFailure(adapter, primary, root, handle) {
+    const diagnostic = await adapter.runJson([
+        "route", "explain", "--root", root, "--me", handle, "--to", handle,
+    ]);
+    const projected = diagnostic.ok
+        ? safeProjection(diagnostic.json)
+        : {
+            category: diagnostic.category,
+            message: diagnostic.stderr.trim() || diagnostic.jsonError?.message || diagnostic.processError?.message,
+        };
+    return `${primary}; /amq bind; route=${JSON.stringify(projected)}`;
+}
+class PiSessionProjectionLookup {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    async find(messageId, targetSessionId) {
+        if (this.#ctx.sessionManager.getSessionId() !== targetSessionId)
+            return undefined;
+        const sessionFile = this.#ctx.sessionManager.getSessionFile();
+        if (!sessionFile)
+            return undefined;
+        let contents;
+        try {
+            contents = await readFile(sessionFile, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+        const found = contents.split("\n").some((line) => diskLineContainsMessage(line, messageId));
+        return found ? { messageId, sessionId: targetSessionId, diskVisible: true } : undefined;
+    }
+}
+export function diskLineContainsMessage(line, messageId) {
+    if (line.length === 0)
+        return false;
+    try {
+        const entry = JSON.parse(line);
+        if (entry.type !== "custom_message" || entry.customType !== PI_AMQ_CUSTOM_TYPE)
+            return false;
+        const details = entry.details;
+        if (!details || typeof details !== "object" || Array.isArray(details))
+            return false;
+        const messageIds = details.messageIds;
+        return Array.isArray(messageIds) && messageIds.includes(messageId);
+    }
+    catch {
+        return false;
+    }
+}
+export class PiDeliverySink {
+    #pi;
+    #lookup;
+    constructor(pi, lookup) {
+        this.#pi = pi;
+        this.#lookup = lookup;
+    }
+    async deliver(request) {
+        try {
+            this.#pi.sendMessage(request.message, request.options);
+            const projections = await Promise.all(request.message.details.messageIds.map(async (messageId) => (await this.#lookup.find(messageId, request.targetSessionId, request.signal)
+                ?? { messageId, sessionId: request.targetSessionId, diskVisible: false })));
+            return { kind: "accepted", projections };
+        }
+        catch (error) {
+            return { kind: "indeterminate", error: toError(error) };
+        }
+    }
+}
+const FRESH_SESSION_PROVENANCE_TYPE = "pi-amq-fresh-session-provenance/v1";
+const DEFAULT_FRESH_SESSION_DISPATCH_TIMEOUT_MS = 30_000;
+/**
+ * Bridges the `FreshSessionReplacementPort` contract to real pi command-context session
+ * control (design.md §8.3). `waitForIdle` cannot itself call `ctx.waitForIdle()`: that method
+ * only exists on `ExtensionCommandContext`, which pi hands over solely by dispatching the
+ * `/amq-new-task` command, and dispatch requires the message ID that `waitForIdle` never
+ * receives. So `replace()` fires that dispatch and correlates the eventual command-handler
+ * completion (which performs the real `ctx.waitForIdle()` as its first step, unconditionally)
+ * back to this call via a per-messageId handoff.
+ */
+export class PiFreshSessionReplacementPort {
+    #pi;
+    #dispatchTimeoutMs;
+    #pending = new Map();
+    constructor(pi, options = {}) {
+        this.#pi = pi;
+        this.#dispatchTimeoutMs = options.dispatchTimeoutMs ?? DEFAULT_FRESH_SESSION_DISPATCH_TIMEOUT_MS;
+    }
+    async waitForIdle(signal) {
+        if (signal?.aborted)
+            throw abortError(signal);
+    }
+    replace(message, signal) {
+        const messageId = message.header.id;
+        if (this.#pending.has(messageId)) {
+            return Promise.reject(new Error(`Fresh-session dispatch for ${messageId} is already in flight`));
+        }
+        return new Promise((resolve, reject) => {
+            const onAbort = () => settle.reject(abortError(signal));
+            const settle = {
+                message,
+                resolve: (result) => {
+                    this.#finish(messageId, onAbort, signal);
+                    resolve(result);
+                },
+                reject: (error) => {
+                    this.#finish(messageId, onAbort, signal);
+                    reject(error);
+                },
+                timer: setTimeout(() => {
+                    settle.reject(new Error(`Fresh-session command dispatch for ${messageId} did not reach the /${FRESH_SESSION_COMMAND} `
+                        + `handler within ${this.#dispatchTimeoutMs}ms`));
+                }, this.#dispatchTimeoutMs),
+            };
+            this.#pending.set(messageId, settle);
+            signal?.addEventListener("abort", onAbort, { once: true });
+            try {
+                this.#pi.sendUserMessage(`/${FRESH_SESSION_COMMAND} ${messageId}`, { expandPromptTemplates: true });
+            }
+            catch (error) {
+                settle.reject(toError(error));
+            }
+        });
+    }
+    #finish(messageId, onAbort, signal) {
+        const handoff = this.#pending.get(messageId);
+        if (!handoff)
+            return;
+        clearTimeout(handoff.timer);
+        signal?.removeEventListener("abort", onAbort);
+        this.#pending.delete(messageId);
+    }
+    /** Invoked by the registered `/amq-new-task` command once pi dispatches it. */
+    async handleCommand(rawArgs, ctx) {
+        const messageId = rawArgs.trim();
+        const handoff = messageId.length > 0 ? this.#pending.get(messageId) : undefined;
+        if (!handoff) {
+            ctx.ui.notify(`AMQ fresh-session dispatch has no matching pending request for "${messageId}"`, "warning");
+            return;
+        }
+        try {
+            handoff.resolve(await this.#replaceSession(handoff.message, ctx));
+        }
+        catch (error) {
+            handoff.reject(toError(error));
+        }
+    }
+    async #replaceSession(message, ctx) {
+        await ctx.waitForIdle();
+        let projection;
+        const parentSessionFile = ctx.sessionManager.getSessionFile();
+        const { cancelled } = await ctx.newSession({
+            ...(parentSessionFile ? { parentSession: parentSessionFile } : {}),
+            setup: async (sessionManager) => {
+                sessionManager.appendCustomEntry(FRESH_SESSION_PROVENANCE_TYPE, {
+                    schema: 1,
+                    messageId: message.header.id,
+                    from: message.header.from,
+                    fromProject: message.header.fromProject,
+                    parentSessionId: ctx.sessionManager.getSessionId(),
+                });
+            },
+            withSession: async (fresh) => {
+                const freshSessionId = fresh.sessionManager.getSessionId();
+                const [request] = planPriorityDeliveries([message], freshSessionId, {
+                    deliveryOverride: { deliverAs: "followUp", triggerTurn: true },
+                });
+                if (!request)
+                    throw new Error(`Fresh-session kickoff envelope for ${message.header.id} could not be built`);
+                await fresh.sendMessage(request.message, request.options);
+                // Pi persists a fresh session's file lazily: nothing is written to disk until its
+                // first assistant entry arrives (session-manager `_persist`). Immediately after the
+                // kickoff send, the session file may legitimately not exist yet, so a missing disk
+                // projection is not an error here — fall back to the in-memory branch, which pi
+                // always keeps current. Journal reconciliation later promotes this to `injected`
+                // once the projection becomes disk-visible (transport/inbox-pump.ts `#reconcileStartup`).
+                const diskProjection = await new PiSessionProjectionLookup(fresh)
+                    .find(message.header.id, freshSessionId);
+                projection = diskProjection ?? (branchContainsMessage(fresh.sessionManager.getBranch(), message.header.id)
+                    ? { messageId: message.header.id, sessionId: freshSessionId, diskVisible: false }
+                    : undefined);
+            },
+        });
+        if (cancelled)
+            return { cancelled: true };
+        if (!projection || projection.messageId !== message.header.id) {
+            throw new Error(`Fresh-session replacement for ${message.header.id} completed without a matching in-memory or `
+                + "disk-visible projection");
+        }
+        return { cancelled: false, projection };
+    }
+}
+function branchContainsMessage(entries, messageId) {
+    return entries.some((entry) => {
+        if (entry.type !== "custom_message" || entry.customType !== PI_AMQ_CUSTOM_TYPE)
+            return false;
+        const details = entry.details;
+        return Array.isArray(details?.messageIds) && details.messageIds.includes(messageId);
+    });
+}
+function abortError(signal) {
+    return signal?.reason instanceof Error ? signal.reason : new Error("Fresh-session dispatch was cancelled");
+}
+function collectEnvelopeDetails(ctx) {
+    return ctx.sessionManager.getBranch().flatMap((entry) => {
+        if (entry.type !== "custom_message" || entry.customType !== PI_AMQ_CUSTOM_TYPE)
+            return [];
+        const details = entry.details;
+        return Array.isArray(details?.envelopes) ? details.envelopes : [];
+    });
+}
+function replyRoutes(ctx) {
+    return {
+        lookup(messageId) {
+            const envelope = collectEnvelopeDetails(ctx).find((candidate) => candidate.id === messageId);
+            if (!envelope)
+                return undefined;
+            const to = envelope.replyTo || envelope.from;
+            if (!to)
+                return undefined;
+            const project = envelope.replyProject || envelope.fromProject;
+            return { to, ...(project ? { project } : {}) };
+        },
+    };
+}
+function renderBindPreview(preview) {
+    return [
+        `kind=${preview.kind}`,
+        `physical-root=${preview.root}`,
+        `session=${preview.session || "base"}`,
+        `project=${preview.project}`,
+        `handle=${preview.handle}`,
+        `roster=${preview.agents.join(",")}`,
+        `command=${preview.commandText}`,
+        ...preview.effects.map((effect) => `effect=${effect}`),
+    ].join("\n");
+}
+function latestBinding(ctx) {
+    const entries = ctx.sessionManager.getEntries();
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry.type !== "custom" || entry.customType !== PI_AMQ_BINDING_ENTRY_TYPE)
+            continue;
+        return entry.data;
+    }
+    return undefined;
+}
+async function resolveAmqBinary(configured) {
+    if (configured) {
+        if (!isAbsolute(configured))
+            throw new Error("PI_AMQ_BINARY must be an absolute path");
+        return configured;
+    }
+    for (const candidate of ["/opt/homebrew/bin/amq", "/usr/local/bin/amq", "/usr/bin/amq"]) {
+        try {
+            await access(candidate);
+            return candidate;
+        }
+        catch {
+            // Try the next conventional absolute path.
+        }
+    }
+    return "/usr/local/bin/amq";
+}
+function freshAllowlist() {
+    return new Set((process.env.PI_AMQ_FRESH_ALLOWLIST ?? "").split(",").map((item) => item.trim()).filter(Boolean));
+}
+function renderFleetRow(record) {
+    return [`${record.handle}/${record.role} ${record.model} ${record.state} ${record.lastActivity}`];
+}
+function flag(value, key) {
+    return typeof value === "string" && value.length > 0 ? { [key]: value } : {};
+}
+function stringFlag(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function bounded(value, maximum) {
+    return value.length <= maximum ? value : `${value.slice(0, maximum - 1)}…`;
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+//# sourceMappingURL=runtime.js.map