ftown-bridge 0.19.1 → 0.19.2

package/dist/mail-delivery.d.ts

@@ -0,0 +1,114 @@
+import type { MailMessage, Session } from './types.js';
+export declare const MAX_MAIL_BODY_LENGTH: number;
+export declare const MAX_MAIL_WAIT_SECONDS = 30;
+export declare const MAIL_NUDGE_DELAY_MS = 5000;
+export declare const MAIL_NUDGE_DELAY_HOOKED_MS = 60000;
+export declare const MAIL_NUDGE_MIN_INTERVAL_MS = 30000;
+export declare const MAIL_NUDGE_BUSY_RECHECK_MS = 60000;
+export declare const AGENT_BUSY_STALE_MS: number;
+export declare const MAIL_TYPES: ReadonlyArray<MailMessage['type']>;
+export declare function sanitizeMessageText(text: string): string;
+/** The slice of SessionStore the mail engine needs. */
+export interface MailDeliverySessionStore {
+    loadSession(sessionId: string): Promise<Session | null>;
+    listSessions(): Promise<Session[]>;
+}
+/** The slice of MailStore the mail engine needs. */
+export interface MailDeliveryMailStore {
+    append(msg: MailMessage): Promise<void>;
+    listUndelivered(sessionId: string): Promise<MailMessage[]>;
+    listAll(sessionId: string, limit: number): Promise<MailMessage[]>;
+    markDelivered(sessionId: string, ids: string[], via: NonNullable<MailMessage['deliveredVia']>): Promise<MailMessage[]>;
+}
+/** The slice of ProcessRunner the mail engine needs. */
+export interface MailDeliveryRunner {
+    isRunning(sessionId: string): boolean;
+    write(sessionId: string, data: string): boolean;
+}
+/** Timer handle as returned by the injected setTimeout (Node's supports unref). */
+export type MailTimerHandle = {
+    unref?: () => void;
+};
+export interface MailDeliveryOptions {
+    store?: MailDeliverySessionStore | null;
+    mailStore?: MailDeliveryMailStore | null;
+    runner?: MailDeliveryRunner | null;
+    /** Clock seam — defaults to the real Date.now/setTimeout/clearTimeout. */
+    now?: () => number;
+    setTimeout?: (fn: () => void, ms: number) => MailTimerHandle;
+    clearTimeout?: (handle: MailTimerHandle) => void;
+}
+export type AcceptMailResult = {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    error: string;
+};
+export type InboxReadResult = {
+    kind: 'immediate';
+    messages: MailMessage[];
+} | {
+    kind: 'longpoll';
+    messages: Promise<MailMessage[]>;
+    abandon: () => void;
+};
+/**
+ * The bridge's mail-delivery engine, extracted from the HTTP router so its
+ * timing logic (long-poll waiters, nudge debounce/rate-limit/busy-recheck,
+ * composer-paste injection) is unit-testable with a controlled clock.
+ *
+ * Owns ALL mail state: one long-poll waiter per session, nudge timers,
+ * pending-nudge sender labels, last-nudge timestamps, and agent busy markers.
+ * The HTTP server keeps route parsing/response writing and delegates here.
+ */
+export declare class MailDeliveryService {
+    private store;
+    private mailStore;
+    private runner;
+    private readonly now;
+    private readonly setTimeoutFn;
+    private readonly clearTimeoutFn;
+    private mailWaiters;
+    private nudgeTimers;
+    private pendingNudgeFrom;
+    private lastNudgeAt;
+    private agentBusySince;
+    constructor(options?: MailDeliveryOptions);
+    setStore(store: MailDeliverySessionStore): void;
+    setMailStore(mailStore: MailDeliveryMailStore): void;
+    setRunner(runner: MailDeliveryRunner): void;
+    /** Both the session store and the mail store are wired. */
+    isReady(): boolean;
+    /** Clear all timers and resolve every pending long poll with []. */
+    stop(): void;
+    /** Hook activity (UserPromptSubmit/PreToolUse/PostToolUse): the agent is mid-turn. */
+    markAgentBusy(sessionId: string): void;
+    /** Hook Stop/SessionEnd: the agent's turn ended. */
+    markAgentIdle(sessionId: string): void;
+    injectPtyLine(session: Session, sender: string, text: string): Promise<boolean>;
+    /**
+     * Store incoming mail for a session: validate, append, then either kick the
+     * session's long-poll waiter or schedule an idle nudge.
+     */
+    acceptMail(session: Session, body: Record<string, unknown>): Promise<AcceptMailResult>;
+    /**
+     * Read a session's inbox: peek, drain, or long poll. A long poll returns a
+     * promise that resolves when mail arrives (or the wait elapses) plus an
+     * `abandon` callback the caller must invoke if the client disconnects —
+     * abandoning never marks messages delivered, so no mail is lost.
+     */
+    readMail(session: Session, query: {
+        wait: number;
+        peek: boolean;
+        all: boolean;
+        limit: number;
+    }): Promise<InboxReadResult>;
+    /** A session earns the Stop-hook listen window only if mail can plausibly
+     *  arrive: it has a parent, has children, was marked an orchestrator, or has
+     *  exchanged mail before. */
+    participatesInMail(session: Session): Promise<boolean>;
+    private scheduleMailNudge;
+    private fireMailNudge;
+    private delay;
+}

package/dist/mail-delivery.js

@@ -0,0 +1,315 @@
+import { createMailMessage } from './mail-store.js';
+import { HOOKED_SHELL_TYPES } from './harness-registry.js';
+export const MAX_MAIL_BODY_LENGTH = 64 * 1024;
+export const MAX_MAIL_WAIT_SECONDS = 30;
+export const MAIL_NUDGE_DELAY_MS = 5_000;
+// Hooked agents (claude/codex and claude flavors) get mail through their Stop
+// pump; the nudge is only a safety net for them, so wait much longer before
+// typing into their pane — fast nudges race the pump and queue stale prompts.
+export const MAIL_NUDGE_DELAY_HOOKED_MS = 60_000;
+export const MAIL_NUDGE_MIN_INTERVAL_MS = 30_000;
+// While an agent is mid-turn its Stop hook pump delivers mail at turn end, so
+// nudging would only queue a stale prompt; re-check periodically in case the
+// turn never reaches Stop, and ignore busy markers old enough to be a crash.
+export const MAIL_NUDGE_BUSY_RECHECK_MS = 60_000;
+export const AGENT_BUSY_STALE_MS = 30 * 60_000;
+export const MAIL_TYPES = ['message', 'task', 'result', 'escalation'];
+// Composer TUIs detect pastes by input arrival rate; the submit CR must come well
+// after that window or it is treated as a pasted newline.
+const COMPOSER_PASTE_SETTLE_MS = 600;
+// Messages are sanitized to a single line, so a delayed plain CR submits everywhere.
+// (ESC+CR reads as Alt+Enter — insert newline — on current Claude Code.)
+function submitSuffixFor(_shellType) {
+    return '\r';
+}
+// Strip control chars and collapse whitespace so a message cannot inject keystrokes.
+export function sanitizeMessageText(text) {
+    return text
+        .replace(/[\u0000-\u001f\u007f]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * The bridge's mail-delivery engine, extracted from the HTTP router so its
+ * timing logic (long-poll waiters, nudge debounce/rate-limit/busy-recheck,
+ * composer-paste injection) is unit-testable with a controlled clock.
+ *
+ * Owns ALL mail state: one long-poll waiter per session, nudge timers,
+ * pending-nudge sender labels, last-nudge timestamps, and agent busy markers.
+ * The HTTP server keeps route parsing/response writing and delegates here.
+ */
+export class MailDeliveryService {
+    store;
+    mailStore;
+    runner;
+    now;
+    setTimeoutFn;
+    clearTimeoutFn;
+    mailWaiters = new Map();
+    nudgeTimers = new Map();
+    pendingNudgeFrom = new Map();
+    lastNudgeAt = new Map();
+    agentBusySince = new Map();
+    constructor(options = {}) {
+        this.store = options.store ?? null;
+        this.mailStore = options.mailStore ?? null;
+        this.runner = options.runner ?? null;
+        this.now = options.now ?? (() => Date.now());
+        this.setTimeoutFn = options.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimeoutFn = options.clearTimeout ?? ((handle) => clearTimeout(handle));
+    }
+    setStore(store) {
+        this.store = store;
+    }
+    setMailStore(mailStore) {
+        this.mailStore = mailStore;
+    }
+    setRunner(runner) {
+        this.runner = runner;
+    }
+    /** Both the session store and the mail store are wired. */
+    isReady() {
+        return this.store !== null && this.mailStore !== null;
+    }
+    /** Clear all timers and resolve every pending long poll with []. */
+    stop() {
+        for (const timer of this.nudgeTimers.values())
+            this.clearTimeoutFn(timer);
+        this.nudgeTimers.clear();
+        for (const waiter of [...this.mailWaiters.values()])
+            waiter.deliver([]);
+        this.mailWaiters.clear();
+    }
+    /** Hook activity (UserPromptSubmit/PreToolUse/PostToolUse): the agent is mid-turn. */
+    markAgentBusy(sessionId) {
+        this.agentBusySince.set(sessionId, this.now());
+    }
+    /** Hook Stop/SessionEnd: the agent's turn ended. */
+    markAgentIdle(sessionId) {
+        this.agentBusySince.delete(sessionId);
+    }
+    // Plain shells would execute the message as a command; deliver it as a quoted no-op
+    // (`: '...'`) — interactive zsh has no '#' comments by default.
+    async injectPtyLine(session, sender, text) {
+        if (!this.runner)
+            return false;
+        const isAgent = session.shellType && session.shellType !== 'shell';
+        const line = isAgent
+            ? `[ftown msg from ${sender}] ${text}`
+            : `: '[ftown msg from ${sender}] ${text.replace(/'/g, '')}'`;
+        if (!this.runner.write(session.id, line))
+            return false;
+        // Composer TUIs detect pastes by input arrival rate; the submit CR must come well
+        // after that window or it is treated as a pasted newline.
+        await this.delay(COMPOSER_PASTE_SETTLE_MS);
+        this.runner.write(session.id, submitSuffixFor(session.shellType));
+        return true;
+    }
+    /**
+     * Store incoming mail for a session: validate, append, then either kick the
+     * session's long-poll waiter or schedule an idle nudge.
+     */
+    async acceptMail(session, body) {
+        if (!this.mailStore) {
+            return { ok: false, error: 'Mail store not ready' };
+        }
+        const text = body.body;
+        if (typeof text !== 'string' || !text.trim()) {
+            return { ok: false, error: 'Missing body' };
+        }
+        if (text.length > MAX_MAIL_BODY_LENGTH) {
+            return { ok: false, error: `Body too long (max ${MAX_MAIL_BODY_LENGTH} chars)` };
+        }
+        let type = 'message';
+        if (body.type !== undefined) {
+            if (typeof body.type !== 'string' || !MAIL_TYPES.includes(body.type)) {
+                return { ok: false, error: `Invalid type (expected one of: ${MAIL_TYPES.join(', ')})` };
+            }
+            type = body.type;
+        }
+        const from = typeof body.from === 'string' && body.from.trim() ? body.from.trim() : 'external';
+        const fromName = typeof body.fromName === 'string' && body.fromName.trim() ? body.fromName.trim() : undefined;
+        const threadId = typeof body.threadId === 'string' && body.threadId.trim() ? body.threadId.trim() : undefined;
+        const msg = createMailMessage({ from, fromName, to: session.id, type, threadId, body: text });
+        await this.mailStore.append(msg);
+        const waiter = this.mailWaiters.get(session.id);
+        if (waiter) {
+            const undelivered = await this.mailStore.listUndelivered(session.id);
+            // Mirror the timeout path's settled-guard: the waiter may have died
+            // (client disconnected, or a newer waiter replaced it) while we awaited
+            // above. Only mark messages delivered if it is still the live waiter —
+            // otherwise leave them undelivered so the next reader gets them instead
+            // of writing to a dead socket and losing them.
+            if (this.mailWaiters.get(session.id) === waiter && undelivered.length > 0) {
+                const marked = await this.mailStore.markDelivered(session.id, undelivered.map((m) => m.id), 'poll');
+                waiter.deliver(marked);
+            }
+        }
+        else {
+            const nudgeDelay = HOOKED_SHELL_TYPES.has(session.shellType ?? 'claude')
+                ? MAIL_NUDGE_DELAY_HOOKED_MS
+                : MAIL_NUDGE_DELAY_MS;
+            this.scheduleMailNudge(session.id, fromName ?? from, nudgeDelay);
+        }
+        return { ok: true, id: msg.id };
+    }
+    /**
+     * Read a session's inbox: peek, drain, or long poll. A long poll returns a
+     * promise that resolves when mail arrives (or the wait elapses) plus an
+     * `abandon` callback the caller must invoke if the client disconnects —
+     * abandoning never marks messages delivered, so no mail is lost.
+     */
+    async readMail(session, query) {
+        const mailStore = this.mailStore;
+        if (!mailStore) {
+            return { kind: 'immediate', messages: [] };
+        }
+        const wait = Math.min(query.wait, MAX_MAIL_WAIT_SECONDS);
+        if (query.peek) {
+            const messages = query.all
+                ? await mailStore.listAll(session.id, query.limit)
+                : await mailStore.listUndelivered(session.id);
+            return { kind: 'immediate', messages };
+        }
+        // The listen window is earned, not universal: a session with no mail
+        // relationships (no parent, no children, not an orchestrator) gets an
+        // instant stop instead of holding its Stop hook open for `wait` seconds.
+        // Late mail for everyone is still covered by the idle nudge.
+        let effectiveWait = wait;
+        if (wait > 0 && !(await this.participatesInMail(session))) {
+            effectiveWait = 0;
+        }
+        const undelivered = await mailStore.listUndelivered(session.id);
+        if (undelivered.length > 0 || effectiveWait <= 0) {
+            const marked = await mailStore.markDelivered(session.id, undelivered.map((m) => m.id), effectiveWait > 0 ? 'poll' : 'drain');
+            return { kind: 'immediate', messages: marked };
+        }
+        // Long poll: hold until mail arrives or `wait` seconds elapse. One waiter
+        // per session — a newer waiter resolves the previous one with [].
+        const existing = this.mailWaiters.get(session.id);
+        if (existing)
+            existing.deliver([]);
+        let settled = false;
+        let resolveMessages;
+        const messages = new Promise((resolve) => {
+            resolveMessages = resolve;
+        });
+        const waiter = {
+            deliver: (delivered) => {
+                if (settled)
+                    return;
+                settled = true;
+                this.clearTimeoutFn(timer);
+                if (this.mailWaiters.get(session.id) === waiter) {
+                    this.mailWaiters.delete(session.id);
+                }
+                resolveMessages(delivered);
+            },
+        };
+        const timer = this.setTimeoutFn(() => {
+            // Guard each async step on settled: once the client disconnects (or a new
+            // waiter replaced this one) we must not mark messages delivered — they
+            // would be lost without ever reaching a session.
+            if (settled || this.mailWaiters.get(session.id) !== waiter)
+                return;
+            mailStore
+                .listUndelivered(session.id)
+                .then((pending) => {
+                if (settled || pending.length === 0)
+                    return [];
+                return mailStore.markDelivered(session.id, pending.map((m) => m.id), 'poll');
+            })
+                .then((marked) => waiter.deliver(marked))
+                .catch(() => waiter.deliver([]));
+        }, effectiveWait * 1000);
+        this.mailWaiters.set(session.id, waiter);
+        const abandon = () => {
+            if (this.mailWaiters.get(session.id) !== waiter)
+                return;
+            settled = true;
+            this.clearTimeoutFn(timer);
+            this.mailWaiters.delete(session.id);
+        };
+        return { kind: 'longpoll', messages, abandon };
+    }
+    /** A session earns the Stop-hook listen window only if mail can plausibly
+     *  arrive: it has a parent, has children, was marked an orchestrator, or has
+     *  exchanged mail before. */
+    async participatesInMail(session) {
+        if (session.parentSessionId)
+            return true;
+        if (session.env?.FTOWN_ORCHESTRATOR === '1')
+            return true;
+        if (!this.store || !this.mailStore)
+            return false;
+        const sessions = await this.store.listSessions();
+        if (sessions.some((s) => s.parentSessionId === session.id))
+            return true;
+        const history = await this.mailStore.listAll(session.id, 1);
+        return history.length > 0;
+    }
+    // Debounced wake-up for mail that no long-poll consumed: after 5s, if it is still
+    // undelivered and the session is running, inject a one-line pointer to the
+    // harness mail command. At most one nudge per session per 30s; senders coalesce.
+    scheduleMailNudge(sessionId, fromLabel, delayMs = MAIL_NUDGE_DELAY_MS) {
+        this.pendingNudgeFrom.set(sessionId, fromLabel);
+        if (this.nudgeTimers.has(sessionId))
+            return;
+        const timer = this.setTimeoutFn(() => {
+            this.nudgeTimers.delete(sessionId);
+            this.fireMailNudge(sessionId).catch((err) => {
+                console.error('[MailDelivery] Mail nudge failed:', err instanceof Error ? err.message : String(err));
+            });
+        }, delayMs);
+        timer.unref?.();
+        this.nudgeTimers.set(sessionId, timer);
+    }
+    async fireMailNudge(sessionId) {
+        if (!this.store || !this.mailStore || !this.runner)
+            return;
+        const fromLabel = this.pendingNudgeFrom.get(sessionId) ?? 'ftown';
+        const undelivered = await this.mailStore.listUndelivered(sessionId);
+        if (undelivered.length === 0) {
+            this.pendingNudgeFrom.delete(sessionId);
+            return;
+        }
+        const busySince = this.agentBusySince.get(sessionId);
+        if (busySince !== undefined && this.now() - busySince < AGENT_BUSY_STALE_MS) {
+            this.scheduleMailNudge(sessionId, fromLabel, MAIL_NUDGE_BUSY_RECHECK_MS);
+            return;
+        }
+        // "Never nudged" must be its own state, not `lastNudgeAt ?? 0` — a clock
+        // that starts near zero (tests, or a freshly booted process) would make
+        // `now() - 0` look like it's already inside the rate-limit window.
+        const lastNudgeAt = this.lastNudgeAt.get(sessionId);
+        if (lastNudgeAt !== undefined) {
+            const sinceLast = this.now() - lastNudgeAt;
+            if (sinceLast < MAIL_NUDGE_MIN_INTERVAL_MS) {
+                // Rate-limited: retry once the window reopens (mail may still be unread).
+                this.scheduleMailNudge(sessionId, fromLabel, MAIL_NUDGE_MIN_INTERVAL_MS - sinceLast);
+                return;
+            }
+        }
+        // The session isn't running (crashed/restarting): don't clear the pending
+        // marker. No timer is armed for this session at this point (the caller
+        // already removed it before invoking us), so clearing it here would lose
+        // the sender label until unrelated new mail happens to call
+        // scheduleMailNudge again. Keeping it means the next opportunity to
+        // re-check this session (new mail via acceptMail, or an external
+        // restart/idle hook re-invoking this nudge check) still knows who to
+        // credit.
+        if (!this.runner.isRunning(sessionId))
+            return;
+        const session = await this.store.loadSession(sessionId);
+        if (!session)
+            return;
+        this.pendingNudgeFrom.delete(sessionId);
+        this.lastNudgeAt.set(sessionId, this.now());
+        const text = sanitizeMessageText(`You have new ftown mail from ${fromLabel} — run \`~/.ftown/bin/ftown-harness mail read\` to read it.`);
+        await this.injectPtyLine(session, 'ftown-mail', text);
+    }
+    delay(ms) {
+        return new Promise((resolve) => this.setTimeoutFn(resolve, ms));
+    }
+}
+//# sourceMappingURL=mail-delivery.js.map

package/dist/mail-delivery.js.map

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

package/dist/session-controller.d.ts

@@ -0,0 +1,107 @@
+import { type CreateFtownSessionDeps, type CreateFtownSessionInput } from './create-ftown-session.js';
+import type { RemoveFtownSessionOptions } from './remove-ftown-session.js';
+import type { Session, SessionUsage } from './types.js';
+/**
+ * Transport-agnostic session operations, defined ONCE and shared by the two
+ * dispatch surfaces (the Centrifugo RPC switch in index.ts and the local HTTP
+ * router in local-api-server.ts). Methods take already-parsed typed input and
+ * return typed results/errors; the adapters own all wire concerns (command
+ * envelopes, HTTP statuses, toWireSession payload shaping).
+ *
+ * Error-propagation contract (matches the pre-refactor adapters byte for byte):
+ * - `create` and `retry` let ProviderAuthMissingError / WorkingDirMissingError /
+ *   generic Errors THROW — each adapter already owns a per-error-class mapping
+ *   (RPC outer catch with the working-dir data envelope; HTTP 422/400/500).
+ * - State/lookup failures return typed `{ ok: false, code, message }` results.
+ */
+export type SessionErrorCode = 'not_found' | 'invalid' | 'conflict';
+export interface SessionControllerError {
+    ok: false;
+    code: SessionErrorCode;
+    message: string;
+}
+export type SessionControllerResult<T> = ({
+    ok: true;
+} & T) | SessionControllerError;
+/** Combined rename/reparent input. `parent` PRESENT means "reparent"; a value
+ * of null/undefined/'' clears the parent (both dispatchers treat all three as
+ * clear). `value` is unknown so adapters can hand over unvalidated wire input. */
+export interface SessionUpdateInput {
+    name?: string;
+    parent?: {
+        value: unknown;
+    };
+}
+/** Narrow structural slice of SessionStore so tests can use in-memory fakes. */
+export interface SessionStoreLike {
+    loadSession(sessionId: string): Promise<Session | null>;
+    saveSession(session: Session): Promise<void>;
+    listSessions(): Promise<Session[]>;
+    clearTerminalLog(sessionId: string): Promise<void>;
+}
+export interface SessionControllerDeps {
+    store: SessionStoreLike;
+    runner: {
+        stop(sessionId: string): boolean;
+    };
+    publishSessionUpdate(session: Session): Promise<void>;
+    /** removeFtownSession closed over its dep bundle. Returns the removed
+     * session, or null when nothing was removed (unknown id, or the
+     * onlyIfFinished guard rejected it). */
+    removeSession(sessionId: string, options?: RemoveFtownSessionOptions): Promise<Session | null>;
+    /** Full factory bundle, required by create/retry only. */
+    sessionFactory?: CreateFtownSessionDeps;
+    /** Optional: extract token/cost usage from harness-native session files.
+     * Required only by usage(); omitted in adapters that never call it. */
+    collectUsage?(session: Session): Promise<SessionUsage | null>;
+    publishSyntheticStop?(sessionId: string, reason: 'complete' | 'error' | 'stopped'): void;
+    withSessionWrite?(sessionId: string, task: () => Promise<void>): Promise<void>;
+    unregisterSession?(sessionId: string): void;
+    flushTerminalBuffer?(sessionId: string): void;
+    destroyTerminal?(sessionId: string): void;
+}
+export declare class SessionController {
+    private readonly deps;
+    constructor(deps: SessionControllerDeps);
+    private require;
+    /** Create + launch a session. Throws (see class doc) — adapters map errors. */
+    create(input: CreateFtownSessionInput): Promise<Session>;
+    /** Stop a running session and persist/publish its completed state. */
+    stop(sessionId: string): Promise<{
+        stopped: boolean;
+    }>;
+    list(): Promise<Session[]>;
+    get(sessionId: string): Promise<Session | null>;
+    /**
+     * Per-session token/cost usage. Returns the persisted snapshot when
+     * present; otherwise collects on demand (covers live sessions and sessions
+     * that finished before usage collection existed). An on-demand result is
+     * persisted + published only when the session is terminal — a live
+     * session's numbers are still moving, so caching them would go stale.
+     */
+    usage(sessionId: string): Promise<SessionControllerResult<{
+        usage: SessionUsage | null;
+    }>>;
+    /** Re-run a finished/dead session's stored command verbatim. */
+    retry(sessionId: string): Promise<SessionControllerResult<{
+        session: Session;
+    }>>;
+    /**
+     * Rename and/or reparent in ONE load-mutate-save-publish pass (the HTTP
+     * PATCH route updates both fields atomically; the RPC adapter calls with a
+     * single field). Reparenting flattens to the proposed parent's root so
+     * session trees stay one level deep.
+     */
+    update(sessionId: string, input: SessionUpdateInput): Promise<SessionControllerResult<{
+        session: Session;
+    }>>;
+    /** Remove (archive + delete + publish removed). removed=false when nothing
+     * was removed — unknown id, or the onlyIfFinished guard rejected it. */
+    remove(sessionId: string, options?: RemoveFtownSessionOptions): Promise<{
+        removed: boolean;
+    }>;
+    /** Flush pending output, wipe the persisted log, drop the live buffer. */
+    clearTerminal(sessionId: string): Promise<{
+        cleared: true;
+    }>;
+}