@fastagent-sh/fastagent 0.18.0 → 0.20.0

package/dist/channels/telegram/telegram.js

@@ -29,25 +29,17 @@ import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
 import { invokeTurn } from "./invoke-turn.js";
 import { collectAttachments, createContextBuffer } from "./context-buffer.js";
-import { attachmentSummary, defaultTelegramRoute, extractFiles, extractImages, fromLabel, messageText, ownFiles, ownImages, pickMessage, telegramEnvelope, } from "./parse.js";
+import { attachmentSummary, defaultTelegramRoute, extractFiles, extractImages, fromLabel, messageText, ownFiles, ownImages, pickMessage, telegramEnvelope, telegramStop, } from "./parse.js";
 import { defaultErrorMessage, streamReply } from "./preview.js";
-import { ensureStateHome } from "../state.js";
-import { dispatchStop } from "../stop-command.js";
+import { ensureStateHome } from "../kit/state.js";
+import { dispatchStop } from "../kit/stop-command.js";
 import { callApi, editMessageText, sendMessage } from "./telegram-api.js";
-import { createTurnQueue } from "../turn-queue.js";
+import { createTurnQueue } from "../kit/turn-queue.js";
+import { commitAnsweredTurn } from "../kit/turn-store.js";
+import { discussionBlock } from "../kit/context-buffer.js";
 import { createTurnStore } from "./turn-store.js";
 // Re-export the public surface authored elsewhere, so `@fastagent-sh/fastagent/telegram` keeps one entry point.
-export { defaultTelegramRoute, telegramEnvelope };
-/** Execution ceiling: a turn that has STARTED running this many times without finishing is dropped
- *  rather than run again (a poison turn must not loop forever under a restart policy). Counted per turn
- *  at dequeue, so a never-run turn queued behind a poison one keeps its full budget.
- *
- *  Known limitation: `startAttempt` cannot tell a self-inflicted process crash from an external SIGTERM
- *  (no graceful drain), so a legitimately LONG turn interrupted by this many successive deploys is
- *  dropped ("please ask again") as if it were poison. Accepted: catching SIGTERM to spare it would
- *  reintroduce the drain the design refuses, and a turn outliving this many deploy cycles is an outlier
- *  — raise this constant if such turns are expected. */
-const MAX_TURN_ATTEMPTS = 3;
+export { defaultTelegramRoute, telegramEnvelope, telegramStop };
 /** Update body cap — Telegram updates are small JSON; 1 MiB is generous and guards a public endpoint. */
 const MAX_UPDATE_BYTES = 1 << 20;
 /** Constant-time compare so the secret-token check leaks no timing signal. */
@@ -77,9 +69,10 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
             throw new Error("telegramChannel requires a non-empty botToken (used to send the agent's reply)");
         }
         const formatError = onError ?? defaultErrorMessage;
-        // One getMe at startup: the bot's @username (for the default route's group @mention summon, only when
-        // not supplied) and the group-privacy flag — privacy mode off is required to receive the un-summoned
-        // group messages that feed the context buffer, so warn if it is on.
+        // One getMe at startup: the bot's @username (for the default route's group @mention summon and for
+        // recognising an addressed `/stop`, only when not supplied) and the group-privacy flag — privacy
+        // mode off is required to receive the un-summoned group messages that feed the context buffer, so
+        // warn if it is on.
         let mentionName = botUsername;
         void callApi(apiBaseUrl, botToken, "getMe", {}).then((me) => {
             if (mentionName === undefined)
@@ -88,7 +81,11 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 log.warn("[telegram] privacy mode is on: the bot only sees @mentions / replies / commands, so group " +
                     "context (un-summoned messages) won't be captured. Disable it via @BotFather → /setprivacy.");
             }
-        }, (e) => log.warn(`[telegram] getMe failed; @mention summon + privacy check skipped: ${String(e)}`));
+        }, 
+        // Name every capability the missing username costs, so "the bot ignores /stop@name" is
+        // diagnosable from this ONE line — the alternative, a warn per undecidable message, repeats a
+        // single startup fact on every update.
+        (e) => log.warn(`[telegram] getMe failed; @mention summon, addressed /stop, and the privacy check are skipped: ${String(e)}`));
         // A bot token is "<bot_id>:<secret>" — the bot's own id is knowable synchronously, so reply-to-bot
         // targeting is precise from the first update (no getMe race; getMe only resolves the @username).
         // Every real token parses; one that doesn't (a mock/test token) degrades visibly: reply summon stays
@@ -154,10 +151,10 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 await notices.get(rec.id);
                 notices.delete(rec.id);
                 // Count this execution against the durable record (poison-turn ceiling) before running it again.
-                const decision = store.startAttempt(rec.id, MAX_TURN_ATTEMPTS);
+                const decision = store.startAttempt(rec.id);
                 if (decision === "exceeded") {
-                    // Started MAX_TURN_ATTEMPTS times without finishing — tell the asker (reusing its ⏳ notice if
-                    // any), drop it.
+                    // Started the ceiling's worth of times without finishing (turn-store.ts MAX_TURN_ATTEMPTS) —
+                    // tell the asker (reusing its ⏳ notice if any), drop it.
                     notifyDropped(rec);
                     return;
                 }
@@ -182,7 +179,7 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 // Fold the un-summoned discussion since the last answered turn into the prompt; it is cleared
                 // only when the turn COMPLETES (then it lives in the session).
                 const { text: recent, consumed } = buffer.peek(rec.placeKey);
-                const prompt = recent ? `[recent group discussion:\n${recent}\n]\n\n${rec.baseText}` : rec.baseText;
+                const prompt = `${discussionBlock(recent)}${rec.baseText}`;
                 const buffered = collectAttachments(consumed, {
                     files: new Set(rec.fileIds),
                     images: new Set(rec.imageFileIds),
@@ -204,14 +201,7 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                             fileIds: rec.fileIds,
                         },
                         buffered,
-                    }, () => {
-                        // On completed, ORDER the two durable clears so a crash between them can't replay a
-                        // context-stripped turn: drop the intent FIRST (a crash after this won't replay it), THEN
-                        // commit the context buffer (a crash before this just re-folds the same context into the
-                        // next summon — harmless and additive). The reverse order would leave intent+no-context.
-                        store.remove(rec.id);
-                        buffer.commit(rec.placeKey, consumed);
-                    }), apiBaseUrl, botToken, target, formatError, rec.previewId);
+                    }, () => commitAnsweredTurn(store, buffer, { id: rec.id, bufferKey: rec.placeKey, consumed })), apiBaseUrl, botToken, target, formatError, rec.previewId);
                     log.info(`[telegram] turn done: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms)`);
                 }
                 catch (error) {
@@ -313,47 +303,45 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 }
                 return new Response(null, { status: 200 });
             }
-            {
-                const session = r.session ?? placeKey;
-                const chatId = r.chatId ?? m.chat.id;
-                // Reply to the summoning message in groups (threads the answer under the asker); a 1:1 DM needs no
-                // reply-quote. Only when the RESOLVED target is the message's own chat+thread: a route that
-                // redirects elsewhere must not carry a reply_parameters that resolves in the wrong place (fail, or
-                // quote a same-id message there). Compare VALUES, not whether the route touched the field — a route
-                // that explicitly returns the same chat/thread still quotes.
-                const threadId = r.threadId ?? m.message_thread_id;
-                const sameTarget = String(chatId) === String(m.chat.id) && threadId === m.message_thread_id;
-                // Explicit user stop (`/stop`): a control action, never a turn — it must not queue behind the
-                // run it stops. `/stop@otherbot` is not ours; a bare `/stop` always is. Awaited before the ACK:
-                // dispatch + one sendMessage is fast, and a delivery failure logs instead of failing the webhook.
-                const stopMatch = /^\/stop(?:@([A-Za-z0-9_]+))?$/i.exec(messageText(m).trim());
-                if (stopMatch && (!stopMatch[1] || stopMatch[1].toLowerCase() === mentionName?.toLowerCase())) {
-                    const feedback = await dispatchStop(control, session, "[telegram]");
-                    const target = {
-                        chatId,
-                        threadId,
-                        replyTo: m.chat.type !== "private" && sameTarget ? m.message_id : undefined,
-                    };
-                    await sendMessage(apiBaseUrl, botToken, target, feedback, { html: false }).catch((e) => log.warn(`[telegram] stop feedback failed: ${String(e)}`));
-                    return new Response(null, { status: 200 });
-                }
-                const baseText = r.text ?? telegramEnvelope(m);
-                const imageFileIds = extractImages(m);
-                const fileIds = extractFiles(m);
-                if (baseText.trim() !== "" || imageFileIds.length > 0 || fileIds.length > 0) {
-                    // Everything the turn needs, as a plain record; persisted pre-ACK then run serially per session.
-                    submit({
-                        id: `${update.update_id}`,
-                        session,
-                        placeKey,
-                        baseText,
-                        chatId,
-                        threadId,
-                        replyTo: m.chat.type !== "private" && sameTarget ? m.message_id : undefined,
-                        imageFileIds,
-                        fileIds,
-                    }, true);
-                }
+            const session = r.session ?? placeKey;
+            const chatId = r.chatId ?? m.chat.id;
+            // Reply to the summoning message in groups (threads the answer under the asker); a 1:1 DM needs no
+            // reply-quote. Only when the RESOLVED target is the message's own chat+thread: a route that
+            // redirects elsewhere must not carry a reply_parameters that resolves in the wrong place (fail, or
+            // quote a same-id message there). Compare VALUES, not whether the route touched the field — a route
+            // that explicitly returns the same chat/thread still quotes.
+            const threadId = r.threadId ?? m.message_thread_id;
+            const sameTarget = String(chatId) === String(m.chat.id) && threadId === m.message_thread_id;
+            const replyTo = m.chat.type !== "private" && sameTarget ? m.message_id : undefined;
+            // Explicit user stop (`/stop`): a control action, never a turn — it must not queue behind the
+            // run it stops. Awaited before the ACK: dispatch + one sendMessage is fast, and a delivery failure
+            // logs instead of failing the webhook. Read AFTER the route, on the route's own session: the route
+            // is both the gate (a route that ignores this chat must not have the bot abort or answer in it) and
+            // the session authority (a route that remaps `session` would otherwise have its stop abort a
+            // session nobody runs). The default route summons an ADDRESSED `/stop` in a group for this reason:
+            // the general slash-command refusal would leave it buffered as discussion while the run kept going.
+            // An unaddressed one is not a command at all (see telegramStop) and never reaches here.
+            if (telegramStop(update, { botUsername: mentionName, botId })) {
+                const feedback = await dispatchStop(control, session, "[telegram]");
+                await sendMessage(apiBaseUrl, botToken, { chatId, threadId, replyTo }, feedback, { html: false }).catch((e) => log.warn(`[telegram] stop feedback failed: ${String(e)}`));
+                return new Response(null, { status: 200 });
+            }
+            const baseText = r.text ?? telegramEnvelope(m);
+            const imageFileIds = extractImages(m);
+            const fileIds = extractFiles(m);
+            if (baseText.trim() !== "" || imageFileIds.length > 0 || fileIds.length > 0) {
+                // Everything the turn needs, as a plain record; persisted pre-ACK then run serially per session.
+                submit({
+                    id: `${update.update_id}`,
+                    session,
+                    placeKey,
+                    baseText,
+                    chatId,
+                    threadId,
+                    replyTo,
+                    imageFileIds,
+                    fileIds,
+                }, true);
             }
             return new Response(null, { status: 200 });
         };

package/dist/channels/telegram/turn-store.d.ts

@@ -1,10 +1,10 @@
 /**
  * The telegram-shaped turn store: the channel's persisted record (what its runner needs to re-execute a
  * turn), its IO-boundary shape validator, and its arrival ordering, over the generic L1 turn store
- * (../turn-store.ts — the semantics live there: pre-ACK persist, replay on the next start, the poison-
+ * (../kit/turn-store.ts — the semantics live there: pre-ACK persist, replay on the next start, the poison-
  * turn execution ceiling, the fail-closed attempt bump).
  */
-import { type TurnStore } from "../turn-store.ts";
+import { type TurnStore } from "../kit/turn-store.ts";
 /** An accepted turn's persisted intent — the SOURCE for the fields a runner needs to re-execute it
  *  (telegram.ts's PendingTurn derives from this, so a new execution field added here propagates and
  *  cannot silently drop from the persisted record). Minus the live `previewId` (a restart's queue

package/dist/channels/telegram/turn-store.js

@@ -1,10 +1,10 @@
 /**
  * The telegram-shaped turn store: the channel's persisted record (what its runner needs to re-execute a
  * turn), its IO-boundary shape validator, and its arrival ordering, over the generic L1 turn store
- * (../turn-store.ts — the semantics live there: pre-ACK persist, replay on the next start, the poison-
+ * (../kit/turn-store.ts — the semantics live there: pre-ACK persist, replay on the next start, the poison-
  * turn execution ceiling, the fail-closed attempt bump).
  */
-import { createTurnStore as createGenericTurnStore } from "../turn-store.js";
+import { createTurnStore as createGenericTurnStore } from "../kit/turn-store.js";
 /** State files are an IO boundary: valid JSON of the WRONG SHAPE must degrade like a corrupt file
  *  (warn + empty), not flow in as trusted data (mirrors context-buffer's isBufferEntry). */
 function isStoredTurn(t) {

package/dist/cli/add-slack.js

@@ -27,7 +27,7 @@ export async function onboardSlackInternalApp(input) {
         throw new Error("`add slack` needs an interactive terminal for internal-app creation and OAuth — " +
             "re-run in a terminal, or pass --no-onboard to scaffold only");
     }
-    let state = await readSlackOnboardingState(input.stateRoot);
+    let state = readSlackOnboardingState(input.stateRoot);
     const resumed = state !== undefined;
     if (input.replaceConfig && !state) {
         throw new Error("--replace-config found no local Slack onboarding state on this machine — nothing to replace. " +
@@ -84,7 +84,7 @@ export async function onboardSlackInternalApp(input) {
             if (!configToken.startsWith("xoxe.") || !configRefreshToken.startsWith("xoxe-")) {
                 throw new Error("invalid Slack configuration token prefix (expected xoxe. access + xoxe- refresh)");
             }
-            await writeSlackOnboardingState(input.stateRoot, {
+            writeSlackOnboardingState(input.stateRoot, {
                 ...state,
                 configToken,
                 configRefreshToken,
@@ -116,11 +116,11 @@ export async function onboardSlackInternalApp(input) {
             configToken,
             configRefreshToken,
         });
-        await writeSlackOnboardingState(input.stateRoot, state);
+        writeSlackOnboardingState(input.stateRoot, state);
     }
     else if (input.groupBehavior.explicit && !state.appId) {
         state = { ...state, groupBehavior: input.groupBehavior.behavior };
-        await writeSlackOnboardingState(input.stateRoot, state);
+        writeSlackOnboardingState(input.stateRoot, state);
     }
     if (state.createAttemptedAt && !state.appId) {
         throw new Error(`a prior Slack app creation attempt at ${state.createAttemptedAt} returned no app ID — ` +
@@ -144,6 +144,7 @@ export async function onboardSlackInternalApp(input) {
             action = answer;
         }
         if (action === "replace-config") {
+            console.error(`[fastagent] generate a fresh App Configuration Token pair at ${CONFIG_TOKEN_URL}`);
             openExternalUrl(CONFIG_TOKEN_URL);
             state = {
                 ...state,
@@ -154,7 +155,7 @@ export async function onboardSlackInternalApp(input) {
             if (!state.configToken.startsWith("xoxe.") || !state.configRefreshToken.startsWith("xoxe-")) {
                 throw new Error("invalid Slack configuration token prefix (expected xoxe. access + xoxe- refresh)");
             }
-            await writeSlackOnboardingState(input.stateRoot, state);
+            writeSlackOnboardingState(input.stateRoot, state);
         }
     }
     const server = await startSlackSetupServer();

package/dist/cli/commands/add.js

@@ -8,13 +8,9 @@ import { join, relative, resolve } from "node:path";
 import { isCancel, select } from "@clack/prompts";
 import { onboardFeishuCloudApp } from "../add-feishu.js";
 import { dotEnvPath, loadDotEnv } from "../../env.js";
-import { resolveStateRoot } from "../../paths.js";
-import { SECRETS_DIRNAME } from "../../paths.js";
+import { resolveStateRoot, SECRETS_DIRNAME, isUnderDir, displayPath, exists } from "../../paths.js";
 import { detectRuntime, readPackageJson } from "../../runtime.js";
-import { isUnderDir } from "../../engines/pi/definition.js";
-import { displayPath } from "../../paths.js";
 import { appendChannelDotEnv, appendChannelEnv, assertChannelReady, channelExists, channelSetup, scaffoldChannel, } from "../../scaffold/add-channel.js";
-import { exists } from "../../paths.js";
 import { vendorSkill } from "../../scaffold/vendor-skill.js";
 import { failStartup, failUsage, placementOrExit } from "../fail.js";
 /** `fastagent add <kind> [dir]`: scaffold `channels/<kind>.ts` — the adapter import plus a starter `on()`. */

package/dist/cli/commands/attach.d.ts

@@ -1,4 +1,4 @@
-import type { SessionControl, SessionEntry } from "../../session.ts";
+import { type SessionControl, type SessionEntry } from "../../session.ts";
 export interface AttachOptions {
     /** Override the control endpoint (skip control.json discovery) — for a remote serve. */
     url?: string;
@@ -63,7 +63,7 @@ export interface AttachIo {
     warn: (line: string) => void;
 }
 /**
- * The backfill slice REDUCED TO THE ACTIVE PATH — a session is a tree (a `navigate`, or a
+ * The backfill slice REDUCED TO THE ACTIVE PATH — a session is a tree (a leaf move, or a
  * compaction, leaves sibling branches behind), and printing the slice raw renders the abandoned
  * branch interleaved with the live one as if it were one conversation. Reachability is computed
  * backwards from the leaf; an entry whose parent lies BEFORE the slice is path-connected by
@@ -106,5 +106,3 @@ settleMs?: number): Promise<{
     cursor: string | undefined;
     sawProgress: boolean;
 }>;
-/** The cursor a failed round reached, if it recorded one. */
-export declare function roundCursor(error: unknown): string | undefined;

package/dist/cli/commands/attach.js

@@ -16,7 +16,7 @@ import { loadDotEnv } from "../../env.js";
 import { resolveStateRoot } from "../../paths.js";
 import { log, setLogLevel } from "../../log.js";
 import { ABORTED_CODE, SESSION_BUSY_CODE } from "../../agent.js";
-import { NO_ACTIVE_RUN_CODE } from "../../session.js";
+import { NO_ACTIVE_RUN_CODE, } from "../../session.js";
 import { ControlRequestError, connectAgent, connectSessionControl } from "../../session-remote.js";
 import { failStartup, placementOrExit } from "../fail.js";
 /** Read the serving process's local discovery file. */
@@ -157,7 +157,7 @@ export async function runAttach(sessionArg, dirArg, opts) {
                 if (!endpoint)
                     endpoint = discover(dir); // discovered: the first read shares the budget
                 const connected = await connectSessionControl(endpoint);
-                return { control: connected, state: await connected.state(sessionArg) };
+                return { control: connected, state: await connected.sessions.get(sessionArg).state() };
             }
             catch (error) {
                 const decision = decideRound(errorFacts(error), {
@@ -208,7 +208,7 @@ export async function runAttach(sessionArg, dirArg, opts) {
             // ABORTED_CODE: a deliberate stop from ANY client (this attach's /abort, another attach, a
             // Web panel) — the settled line reports it either way; no source discrimination here.
         }
-        // session_busy = the LEASE is held — by another run OR a boundary mutation (compact/set_model
+        // session_busy = the LEASE is held — by another run OR a boundary mutation (compact/update
         // contend on the same lease); "a run started" would be a guess, and "steer it" bad advice
         // against a compact. State the lease fact, promise nothing.
         if (sawBusy)
@@ -225,12 +225,14 @@ export async function runAttach(sessionArg, dirArg, opts) {
             void answerSlashInput(trimmed, control, (l) => console.log(l));
             return;
         }
-        const command = trimmed === "/abort" ? { type: "abort" } : { type: "steer", prompt: { text: trimmed } };
-        void control.dispatch(sessionArg, command).then((result) => {
+        const stopping = trimmed === "/abort";
+        const label = stopping ? "abort" : "steer";
+        const session = control.sessions.get(sessionArg);
+        void (stopping ? session.abort() : session.steer({ text: trimmed })).then((result) => {
             if (result.ok) {
-                console.log(`[${command.type} accepted]`);
+                console.log(`[${label} accepted]`);
             }
-            else if (command.type === "steer" && result.error.code === NO_ACTIVE_RUN_CODE) {
+            else if (!stopping && result.error.code === NO_ACTIVE_RUN_CODE) {
                 // The invoke stream attach holds IS this run's driver (design: disconnect = cancel), so
                 // unlike channel-started runs, this one dies with the attach. Say so up front.
                 // Intent, not fact: admission may still fail (session_busy — the lease could be held
@@ -240,9 +242,9 @@ export async function runAttach(sessionArg, dirArg, opts) {
                 void startRun(trimmed).catch((error) => console.log(`[prompt failed: ${String(error)}]`));
             }
             else {
-                console.log(`[${command.type} rejected: ${result.error.code} — ${result.error.message}]`);
+                console.log(`[${label} rejected: ${result.error.code} — ${result.error.message}]`);
             }
-        }, (error) => console.log(`[${command.type} failed: ${String(error)}]`));
+        }, (error) => console.log(`[${label} failed: ${String(error)}]`));
     });
     // Every round has ONE shape: subscribe → backfill (render the durable record since the cursor)
     // → drain live until the stream drops. Subscribing first + the server's eager registration
@@ -424,7 +426,7 @@ const isAuthError = (error) => error instanceof ControlRequestError && error.sta
  *  startup (a serve restart hours in), so the local name must not imply "startup only". */
 const exitWith = failStartup;
 /**
- * The backfill slice REDUCED TO THE ACTIVE PATH — a session is a tree (a `navigate`, or a
+ * The backfill slice REDUCED TO THE ACTIVE PATH — a session is a tree (a leaf move, or a
  * compaction, leaves sibling branches behind), and printing the slice raw renders the abandoned
  * branch interleaved with the live one as if it were one conversation. Reachability is computed
  * backwards from the leaf; an entry whose parent lies BEFORE the slice is path-connected by
@@ -437,7 +439,7 @@ export function activePathSlice(entries, leafEntryId) {
         return entries;
     const byId = new Map(entries.map((e) => [e.id, e]));
     // An append always moves the leaf, so a leaf BEHIND the slice means every entry in it was
-    // appended and then abandoned — a navigate backwards with no new turn since. Nothing here is on
+    // appended and then abandoned — a leaf move backwards with no new turn since. Nothing here is on
     // the active path.
     if (!byId.has(leafEntryId))
         return [];
@@ -509,7 +511,7 @@ settleMs = 300) {
     // The round HOLDS its subscription's iterator: one round = one stream, on every path — a
     // backfill failure must close it before propagating, or the caller's retry round would stack a
     // second concurrent stream interleaving the same session's output.
-    const iterator = control.events(session)[Symbol.asyncIterator]();
+    const iterator = control.sessions.get(session).events()[Symbol.asyncIterator]();
     // Live output is BUFFERED while the replay block prints, then flushed — the drain runs
     // concurrently with the backfill, and interleaving raw deltas into the labeled replay would make
     // both unreadable; the [end of replay] label is only honest if the block is contiguous.
@@ -554,7 +556,7 @@ settleMs = 300) {
     let next = cursor;
     let sawBackfill = false;
     try {
-        const backfill = await control.entries(session, cursor !== undefined ? { since: cursor } : undefined);
+        const backfill = await control.sessions.get(session).entries(cursor !== undefined ? { since: cursor } : undefined);
         sawBackfill = backfill.entries.length > 0;
         // Advance by APPEND ORDER (the last returned record), never by leafEntryId: `since` is an
         // append-position cursor (design §7), and a leaf that sits before later appends (abandoned
@@ -579,7 +581,7 @@ settleMs = 300) {
         }
         // The protocol's reconnect step the replay cannot cover: status changes while away are
         // LIVE-only events (state_changed before a restart is neither replayed nor re-emitted).
-        const now = await control.state(session);
+        const now = await control.sessions.get(session).state();
         io.println(`[live — ${now.status}${now.activeRunId ? ` (run ${now.activeRunId})` : ""}]`);
     }
     catch (error) {
@@ -612,7 +614,7 @@ function withCursor(error, cursor) {
     return Object.assign(e, { attachCursor: cursor });
 }
 /** The cursor a failed round reached, if it recorded one. */
-export function roundCursor(error) {
+function roundCursor(error) {
     return error.attachCursor;
 }
 /** Render one durable record on replay — the guaranteed kind vocabulary; other kinds are skipped. */

package/dist/cli/commands/deploy.d.ts

@@ -1,4 +1,10 @@
-export type DeployHost = "docker" | "fly" | "railway" | "agentcore";
+/** The deploy targets, as a value: {@link HOST_ONLY_FLAGS} is checked against this list by a test, and
+ *  a type alone cannot be enumerated at runtime. NOT the only copy — `cli/program.ts` repeats it as the
+ *  `<host>` argument's `choices`, because that file may not import a command module at load time (its
+ *  per-command imports are lazy). Adding a host means editing both; the type there rides in on a
+ *  `import type`, which costs nothing at runtime. */
+export declare const DEPLOY_HOSTS: readonly ["docker", "fly", "railway", "agentcore"];
+export type DeployHost = (typeof DEPLOY_HOSTS)[number];
 export interface DeployOptions {
     run?: boolean;
     tunnel?: boolean;
@@ -12,12 +18,50 @@ export interface DeployOptions {
     /** false ⇔ `--no-input`. */
     input?: boolean;
 }
+/** A flag exactly one host honours, and what the OTHERS do instead. `instead` is exhaustive over the
+ *  non-owners, so a host added to {@link DEPLOY_HOSTS} cannot silently lose its line. */
+interface HostOnlyFlag<Owner extends DeployHost> {
+    flag: string;
+    owner: Owner;
+    passed: (opts: DeployOptions) => boolean;
+    instead: Record<Exclude<DeployHost, Owner>, string>;
+}
+/**
+ * ONE table for "this flag belongs to that host", because the fact is symmetric and was not stored
+ * that way: each host branch stated the OTHER hosts' flags in its own words, so the same sentence
+ * existed three times per flag and had already drifted (`Railway-only` twice, `railway-only` once).
+ *
+ * Every row is a flag that only WARNS elsewhere. `--tunnel` is host-only too and is deliberately not
+ * here: it is a usage GATE (`failUsage`, exit 2) raised in `runDeploy`, not a warning — moving it in
+ * would downgrade a refusal to a line of advice.
+ *
+ * Exported for the exhaustiveness test: the type stops a missing `instead` line, and the test stops it
+ * from being typed away.
+ */
+export declare const HOST_ONLY_FLAGS: (HostOnlyFlag<"fly"> | HostOnlyFlag<"railway">)[];
+/** Exported for its own test: nothing covered these six sentences, which is how three of them came to
+ *  disagree about the spelling of a host name. */
+export declare function warnHostOnlyFlags(host: DeployHost, opts: DeployOptions): void;
 export declare function runDeploy(host: DeployHost, dirArg: string, opts: DeployOptions): Promise<void>;
 /**
- * Write the plan's artifacts under `target`, honouring the ownership rule: a file we did not generate is
- * never touched, ours is kept unless `--force`. Exported for its own test — this is a four-branch state
- * machine over (exists, ours, force) that used to be proven by spawning the CLI eight times, which is
- * command LOGIC re-run through a subprocess (see vitest.config.ts) and the suite's slowest test.
+ * Write each generated artifact under `target`, under ONE ownership rule: **deploy only ever overwrites
+ * its own output.** Each generated file opens with a marker, so a file on disk is either OURS (a previous
+ * `deploy` wrote it) or the author's — and `--force` means "my generated artifact is authoritative",
+ * which never licenses clobbering a file we did not write. To hand a path back to fastagent, delete it.
+ *
+ * That single rule replaced a second mechanism (a per-host list of paths exempt from `--force`), which
+ * only described one shape: with the agent inside the workspace, the root `.dockerignore` is the
+ * WORKSPACE's file and was listed; with the agent flat, the list was empty — so `--force` would have
+ * overwritten a hand-written root `Dockerfile` in a repository `init --flat` had explicitly adopted.
+ * Ownership is a property of the file, not of where the agent sits.
+ *
+ * A KEPT file of OURS that no longer matches what deploy would generate now (config/channel/lockfile/
+ * version drift — or the author's edits, which we cannot tell apart) is flagged stale; `--force`
+ * regenerates that one.
+ *
+ * Exported for its own test — this is a four-branch state machine over (exists, ours, force) that used
+ * to be proven by spawning the CLI eight times, which is command LOGIC re-run through a subprocess
+ * (see vitest.config.ts) and the suite's slowest test.
  */
 export declare function writeArtifacts(target: string, artifacts: {
     path: string;
@@ -26,3 +70,4 @@ export declare function writeArtifacts(target: string, artifacts: {
     force: boolean;
     alwaysWrite?: string[];
 }): Promise<void>;
+export {};