ftown-bridge 0.3.16 → 0.5.0

package/dist/session-store.d.ts

@@ -1,6 +1,7 @@
-import type { Session } from './types.js';
+import type { ArchivedSession, Session } from './types.js';
 export declare class SessionStore {
     private readonly sessionsDir;
+    private readonly archivePath;
     private readonly writeLocks;
     constructor(dataDir: string);
     private sessionDir;
@@ -11,6 +12,10 @@ export declare class SessionStore {
     listSessions(): Promise<Session[]>;
     appendTerminalData(sessionId: string, data: string): Promise<void>;
     deleteSession(sessionId: string): Promise<void>;
+    /** Append a tombstone for a removed session to <dataDir>/archive.jsonl. */
+    archiveSession(session: Session): Promise<void>;
+    /** All tombstones, newest last. Missing file and corrupt lines are tolerated. */
+    listArchived(): Promise<ArchivedSession[]>;
     clearTerminalLog(sessionId: string): Promise<void>;
     loadTerminalLog(sessionId: string): Promise<string>;
 }

package/dist/session-store.js

@@ -1,11 +1,13 @@
 import { readFile, writeFile, mkdir, readdir, appendFile, rm, truncate } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { existsSync } from 'node:fs';
 export class SessionStore {
     sessionsDir;
+    archivePath;
     writeLocks = new Map();
     constructor(dataDir) {
         this.sessionsDir = join(dataDir, 'sessions');
+        this.archivePath = join(dataDir, 'archive.jsonl');
     }
     sessionDir(sessionId) {
         return join(this.sessionsDir, sessionId);
@@ -60,6 +62,35 @@ export class SessionStore {
             await rm(dir, { recursive: true, force: true });
         }
     }
+    /** Append a tombstone for a removed session to <dataDir>/archive.jsonl. */
+    async archiveSession(session) {
+        await mkdir(dirname(this.archivePath), { recursive: true });
+        const record = { ...session, removedAt: new Date().toISOString() };
+        // Tombstones retain session env (API keys); owner-only like session-registry.
+        await appendFile(this.archivePath, `${JSON.stringify(record)}\n`, { encoding: 'utf-8', mode: 0o600 });
+    }
+    /** All tombstones, newest last. Missing file and corrupt lines are tolerated. */
+    async listArchived() {
+        if (!existsSync(this.archivePath)) {
+            return [];
+        }
+        const raw = await readFile(this.archivePath, 'utf-8');
+        const archived = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const record = JSON.parse(line);
+                if (record && typeof record.id === 'string' && typeof record.removedAt === 'string') {
+                    archived.push(record);
+                }
+            }
+            catch {
+                // Skip corrupt lines (e.g. partial write from a crashed bridge).
+            }
+        }
+        return archived;
+    }
     async clearTerminalLog(sessionId) {
         const filePath = this.terminalLogPath(sessionId);
         if (existsSync(filePath)) {

package/dist/session-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-store.js","sourceRoot":"","sources":["../src/session-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjG,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAIrC,MAAM,OAAO,YAAY;IACN,WAAW,CAAS;IACpB,UAAU,GAA+B,IAAI,GAAG,EAAE,CAAC;IAEpE,YAAY,OAAe;QACzB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAC/C,CAAC;IAEO,UAAU,CAAC,SAAiB;QAClC,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC3C,CAAC;IAEO,eAAe,CAAC,SAAiB;QACvC,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC,CAAC;IAC1D,CAAC;IAEO,eAAe,CAAC,SAAiB;QACvC,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,OAAgB;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACxC,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACtC,MAAM,SAAS,CAAC,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC/F,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,SAAiB;QACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;QACjD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,YAAY;QAChB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;YAClC,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACzE,MAAM,QAAQ,GAAc,EAAE,CAAC;QAE/B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACnD,IAAI,OAAO,EAAE,CAAC;oBACZ,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACzB,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IACpG,CAAC;IAED,KAAK,CAAC,kBAAkB,CAAC,SAAiB,EAAE,IAAY;QACtD,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QACvC,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAEtC,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;QAEjD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACrE,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;QACzE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACxC,MAAM,OAAO,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,SAAiB;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QACvC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,SAAiB;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;QACjD,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACrE,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;YAC3D,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YACxC,MAAM,OAAO,CAAC;QAChB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,SAAiB;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;QACjD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC;CAEF"}
+{"version":3,"file":"session-store.js","sourceRoot":"","sources":["../src/session-store.ts"],"names":[],"mappings":"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"}

package/dist/tmux.d.ts

@@ -0,0 +1,24 @@
+/** Dedicated tmux server socket so ftown never touches the user's tmux. */
+export declare const TMUX_SOCKET_NAME = "ftown";
+export declare function isTmuxAvailable(): boolean;
+export declare function tmuxSessionName(sessionId: string): string;
+/** Read (and remove) the real exit code of the command that ran inside tmux. */
+export declare function readAndClearExitCode(sessionId: string): number | undefined;
+export interface CreateTmuxSessionOptions {
+    sessionId: string;
+    command: string;
+    cwd: string;
+    cols: number;
+    rows: number;
+    /**
+     * Full environment for the command. Delivered via a 0600 file sourced
+     * inside the session — never via `new-session -e` argv (visible to other
+     * local users) and never via the tmux server env (stale after restarts).
+     */
+    env: Record<string, string>;
+}
+export declare function createTmuxSession(options: CreateTmuxSessionOptions): Promise<void>;
+export declare function hasTmuxSession(sessionId: string): boolean;
+/** Session ids of all live ftown-* sessions on the dedicated socket. */
+export declare function listFtownTmuxSessions(): string[];
+export declare function killTmuxSession(sessionId: string): Promise<boolean>;

package/dist/tmux.js

@@ -0,0 +1,149 @@
+import { execFile, execFileSync } from 'node:child_process';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/** Dedicated tmux server socket so ftown never touches the user's tmux. */
+export const TMUX_SOCKET_NAME = 'ftown';
+const SESSION_PREFIX = 'ftown-';
+// new-session -e requires tmux >= 3.2; older versions fall back to direct spawn.
+const MIN_TMUX_VERSION = 3.02;
+let tmuxAvailable;
+export function isTmuxAvailable() {
+    if (tmuxAvailable === undefined) {
+        try {
+            const output = execFileSync('tmux', ['-V'], { encoding: 'utf8' });
+            const match = /(\d+)\.(\d+)/.exec(output);
+            // Unparseable versions (e.g. "tmux next-3.7") are assumed recent enough.
+            tmuxAvailable = match
+                ? Number(match[1]) + Number(match[2]) / 100 >= MIN_TMUX_VERSION
+                : true;
+        }
+        catch {
+            tmuxAvailable = false;
+        }
+    }
+    return tmuxAvailable;
+}
+export function tmuxSessionName(sessionId) {
+    return `${SESSION_PREFIX}${sessionId}`;
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function exitFilePath(sessionId) {
+    return join(tmpdir(), `ftown-exit-${sessionId}`);
+}
+/** Read (and remove) the real exit code of the command that ran inside tmux. */
+export function readAndClearExitCode(sessionId) {
+    const path = exitFilePath(sessionId);
+    try {
+        const raw = readFileSync(path, 'utf8').trim();
+        rmSync(path, { force: true });
+        const code = Number.parseInt(raw, 10);
+        return Number.isNaN(code) ? undefined : code;
+    }
+    catch {
+        return undefined;
+    }
+}
+function tmuxConfigPath() {
+    const dir = join(homedir(), '.ftown');
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, 'tmux.conf');
+    // Rewritten on every server start so option changes ship with bridge updates.
+    // Only applied when the ftown server starts; never touches ~/.tmux.conf.
+    writeFileSync(path, [
+        'set -g status off',
+        'set -g prefix None',
+        'set -g prefix2 None',
+        'unbind-key -a -T prefix',
+        'unbind-key -a -T root',
+        'set -g mouse off',
+        'set -g history-limit 100000',
+        'set -g remain-on-exit off',
+        'set -g destroy-unattached off',
+        'set -g exit-empty on',
+        'setw -g window-size latest',
+        'setw -g aggressive-resize on',
+        'set -s escape-time 0',
+        'set -g default-terminal "xterm-256color"',
+    ].join('\n') + '\n');
+    return path;
+}
+const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function envFilePath(sessionId) {
+    return join(tmpdir(), `ftown-env-${sessionId}`);
+}
+export async function createTmuxSession(options) {
+    const name = tmuxSessionName(options.sessionId);
+    // Replace any stale session with the same name (e.g. retry after error).
+    await killTmuxSession(options.sessionId);
+    rmSync(exitFilePath(options.sessionId), { force: true });
+    const envFile = envFilePath(options.sessionId);
+    const exports = Object.entries(options.env)
+        .filter(([key]) => ENV_KEY_PATTERN.test(key))
+        .map(([key, value]) => `export ${key}=${shellQuote(value)}`)
+        .join('\n');
+    writeFileSync(envFile, exports + '\n', { mode: 0o600 });
+    // Capture the real exit code so it survives the tmux attach client, whose
+    // own exit code is unrelated. An EXIT trap fires even on explicit `exit`.
+    const inner = [
+        // buildEnv strips these, but the tmux server env may still carry them.
+        'unset NO_COLOR FORCE_COLOR',
+        `. ${shellQuote(envFile)}`,
+        `command rm -f ${shellQuote(envFile)}`,
+        `__ftown_exit_file=${shellQuote(exitFilePath(options.sessionId))}`,
+        `trap 'printf "%s" "$?" > "$__ftown_exit_file"' EXIT`,
+        options.command,
+    ].join('\n');
+    const args = [
+        '-L', TMUX_SOCKET_NAME,
+        '-f', tmuxConfigPath(),
+        'new-session', '-d',
+        '-s', name,
+        '-c', options.cwd,
+        '-x', String(options.cols),
+        '-y', String(options.rows),
+    ];
+    // Single-string shell-command keeps compatibility across tmux versions.
+    args.push(`/bin/zsh -l -c ${shellQuote(inner)}`);
+    await execFileAsync('tmux', args, { env: options.env });
+}
+export function hasTmuxSession(sessionId) {
+    try {
+        execFileSync('tmux', ['-L', TMUX_SOCKET_NAME, 'has-session', '-t', `=${tmuxSessionName(sessionId)}`], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Session ids of all live ftown-* sessions on the dedicated socket. */
+export function listFtownTmuxSessions() {
+    try {
+        const output = execFileSync('tmux', ['-L', TMUX_SOCKET_NAME, 'list-sessions', '-F', '#{session_name}'], { encoding: 'utf8' });
+        return output
+            .split('\n')
+            .filter((name) => name.startsWith(SESSION_PREFIX))
+            .map((name) => name.slice(SESSION_PREFIX.length));
+    }
+    catch {
+        return [];
+    }
+}
+export async function killTmuxSession(sessionId) {
+    try {
+        await execFileAsync('tmux', [
+            '-L', TMUX_SOCKET_NAME,
+            'kill-session',
+            '-t', `=${tmuxSessionName(sessionId)}`,
+        ]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=tmux.js.map

package/dist/tmux.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmux.js","sourceRoot":"","sources":["../src/tmux.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C,2EAA2E;AAC3E,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC;AAExC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEhC,iFAAiF;AACjF,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAE9B,IAAI,aAAkC,CAAC;AAEvC,MAAM,UAAU,eAAe;IAC7B,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;YAClE,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC1C,yEAAyE;YACzE,aAAa,GAAG,KAAK;gBACnB,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,gBAAgB;gBAC/D,CAAC,CAAC,IAAI,CAAC;QACX,CAAC;QAAC,MAAM,CAAC;YACP,aAAa,GAAG,KAAK,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,OAAO,GAAG,cAAc,GAAG,SAAS,EAAE,CAAC;AACzC,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC;AAC/C,CAAC;AAED,SAAS,YAAY,CAAC,SAAiB;IACrC,OAAO,IAAI,CAAC,MAAM,EAAE,EAAE,cAAc,SAAS,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,MAAM,IAAI,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;IACrC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QAC9C,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACtC,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,cAAc;IACrB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC;IACtC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACpC,8EAA8E;IAC9E,yEAAyE;IACzE,aAAa,CACX,IAAI,EACJ;QACE,mBAAmB;QACnB,oBAAoB;QACpB,qBAAqB;QACrB,yBAAyB;QACzB,uBAAuB;QACvB,kBAAkB;QAClB,6BAA6B;QAC7B,2BAA2B;QAC3B,+BAA+B;QAC/B,sBAAsB;QACtB,4BAA4B;QAC5B,8BAA8B;QAC9B,sBAAsB;QACtB,0CAA0C;KAC3C,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CACpB,CAAC;IACF,OAAO,IAAI,CAAC;AACd,CAAC;AAgBD,MAAM,eAAe,GAAG,0BAA0B,CAAC;AAEnD,SAAS,WAAW,CAAC,SAAiB;IACpC,OAAO,IAAI,CAAC,MAAM,EAAE,EAAE,aAAa,SAAS,EAAE,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAiC;IACvE,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChD,yEAAyE;IACzE,MAAM,eAAe,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACzC,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAEzD,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC;SACxC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;SAC5C,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,UAAU,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;SAC3D,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAExD,0EAA0E;IAC1E,0EAA0E;IAC1E,MAAM,KAAK,GAAG;QACZ,uEAAuE;QACvE,4BAA4B;QAC5B,KAAK,UAAU,CAAC,OAAO,CAAC,EAAE;QAC1B,iBAAiB,UAAU,CAAC,OAAO,CAAC,EAAE;QACtC,qBAAqB,UAAU,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE;QAClE,qDAAqD;QACrD,OAAO,CAAC,OAAO;KAChB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,MAAM,IAAI,GAAG;QACX,IAAI,EAAE,gBAAgB;QACtB,IAAI,EAAE,cAAc,EAAE;QACtB,aAAa,EAAE,IAAI;QACnB,IAAI,EAAE,IAAI;QACV,IAAI,EAAE,OAAO,CAAC,GAAG;QACjB,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;QAC1B,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;KAC3B,CAAC;IACF,wEAAwE;IACxE,IAAI,CAAC,IAAI,CAAC,kBAAkB,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAEjD,MAAM,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,IAAI,CAAC;QACH,YAAY,CACV,MAAM,EACN,CAAC,IAAI,EAAE,gBAAgB,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,eAAe,CAAC,SAAS,CAAC,EAAE,CAAC,EAC/E,EAAE,KAAK,EAAE,QAAQ,EAAE,CACpB,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,qBAAqB;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,YAAY,CACzB,MAAM,EACN,CAAC,IAAI,EAAE,gBAAgB,EAAE,eAAe,EAAE,IAAI,EAAE,iBAAiB,CAAC,EAClE,EAAE,QAAQ,EAAE,MAAM,EAAE,CACrB,CAAC;QACF,OAAO,MAAM;aACV,KAAK,CAAC,IAAI,CAAC;aACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;aACjD,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,SAAiB;IACrD,IAAI,CAAC;QACH,MAAM,aAAa,CAAC,MAAM,EAAE;YAC1B,IAAI,EAAE,gBAAgB;YACtB,cAAc;YACd,IAAI,EAAE,IAAI,eAAe,CAAC,SAAS,CAAC,EAAE;SACvC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 export type ShellType = 'claude' | 'cursor' | 'shell' | 'zai' | 'kimi' | 'opencode' | 'deepseek' | 'fireworks';
+export type SessionRuntime = 'tmux' | 'direct';
 export interface Session {
     id: string;
     name: string;
@@ -15,8 +16,13 @@ export interface Session {
     cursorSessionId?: string;
     env?: Record<string, string>;
     parentSessionId?: string;
+    runtime?: SessionRuntime;
 }
 export type SessionStatus = 'pending' | 'running' | 'completed' | 'error';
+/** Tombstone written to <dataDir>/archive.jsonl when a session is removed. */
+export interface ArchivedSession extends Session {
+    removedAt: string;
+}
 export interface SessionMessage {
     sessionId: string;
     type: SessionMessageType;
@@ -46,6 +52,7 @@ export interface CreateSessionPayload {
     claudeSessionId?: string;
     cursorSessionId?: string;
     parentSessionId?: string;
+    orchestrator?: boolean;
 }
 export interface BridgeExecPayload {
     command: string;
@@ -70,6 +77,8 @@ export interface UpdateSessionParentPayload {
 }
 export interface RemoveSessionPayload {
     sessionId: string;
+    /** Only remove if the session is completed/error (bulk-clear race guard). */
+    onlyIfFinished?: boolean;
 }
 export interface ClearTerminalPayload {
     sessionId: string;

package/hooks/notify.sh

@@ -4,6 +4,7 @@ INPUT=$(cat)
 PORT="${FTOWN_HOOK_PORT:-}"
 SESSION_ID="${FTOWN_SESSION_ID:-}"
 TOKEN="${FTOWN_HOOK_TOKEN:-}"
+SOURCE=""
 
 BRIDGE_JSON="${HOME}/.ftown/bridge.json"
 REGISTRY="${HOME}/.ftown/session-registry.json"
@@ -15,15 +16,23 @@ if [ -z "$PORT" ] && [ -f "$BRIDGE_JSON" ]; then
   fi
 fi
 
-if [ -z "$SESSION_ID" ] && [ -n "$INPUT" ]; then
+if [ -n "$SESSION_ID" ]; then
+  SOURCE="env"
+elif [ -n "$INPUT" ]; then
   CONV=$(echo "$INPUT" | jq -r '.conversation_id // empty' 2>/dev/null)
   WS=$(echo "$INPUT" | jq -r '.workspace_roots[0] // empty' 2>/dev/null)
   if [ -f "$REGISTRY" ]; then
     if [ -n "$CONV" ]; then
       SESSION_ID=$(jq -r --arg c "$CONV" '.byConversation[$c] // empty' "$REGISTRY" 2>/dev/null)
+      if [ -n "$SESSION_ID" ]; then
+        SOURCE="conversation"
+      fi
     fi
     if [ -z "$SESSION_ID" ] && [ -n "$WS" ]; then
       SESSION_ID=$(jq -r --arg w "$WS" '.byWorkspace[$w] // empty' "$REGISTRY" 2>/dev/null)
+      if [ -n "$SESSION_ID" ]; then
+        SOURCE="workspace"
+      fi
     fi
   fi
 fi
@@ -32,19 +41,32 @@ if [ -z "$PORT" ] || [ -z "$SESSION_ID" ]; then
   exit 0
 fi
 
-PAYLOAD=$(echo "$INPUT" | jq -c --arg sid "$SESSION_ID" '. + {ftown_session_id: $sid}' 2>/dev/null)
+PAYLOAD=$(echo "$INPUT" | jq -c --arg sid "$SESSION_ID" --arg src "$SOURCE" \
+  '. + {ftown_session_id: $sid, ftown_session_source: $src}' 2>/dev/null)
 if [ -z "$PAYLOAD" ]; then
-  PAYLOAD=$(jq -nc --arg sid "$SESSION_ID" --arg ev "${HOOK_EVENT_NAME:-hook}" \
-    '{ftown_session_id: $sid, hook_event_name: $ev}')
+  PAYLOAD=$(jq -nc --arg sid "$SESSION_ID" --arg src "$SOURCE" --arg ev "${HOOK_EVENT_NAME:-hook}" \
+    '{ftown_session_id: $sid, ftown_session_source: $src, hook_event_name: $ev}')
 fi
 
-AUTH_ARGS=()
-if [ -n "$TOKEN" ]; then
-  AUTH_ARGS+=(-H "Authorization: Bearer ${TOKEN}")
-fi
+post_hook() {
+  local port="$1" token="$2"
+  local auth=()
+  if [ -n "$token" ]; then
+    auth=(-H "Authorization: Bearer ${token}")
+  fi
+  curl -sf -X POST "http://localhost:${port}/hook" \
+    -H "Content-Type: application/json" \
+    "${auth[@]}" \
+    -d "$PAYLOAD" > /dev/null 2>&1
+}
 
-curl -s -X POST "http://localhost:${PORT}/hook" \
-  -H "Content-Type: application/json" \
-  "${AUTH_ARGS[@]}" \
-  -d "$PAYLOAD" > /dev/null 2>&1
+if ! post_hook "$PORT" "$TOKEN" && [ -f "$BRIDGE_JSON" ]; then
+  # Env vars are stale inside tmux sessions that outlive their bridge; the
+  # current bridge rewrites bridge.json with the live port/token on startup.
+  BPORT=$(jq -r '.port // empty' "$BRIDGE_JSON" 2>/dev/null)
+  BTOKEN=$(jq -r '.token // empty' "$BRIDGE_JSON" 2>/dev/null)
+  if [ -n "$BPORT" ] && { [ "$BPORT" != "$PORT" ] || [ "$BTOKEN" != "$TOKEN" ]; }; then
+    post_hook "$BPORT" "$BTOKEN"
+  fi
+fi
 exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ftown-bridge",
-  "version": "0.3.16",
+  "version": "0.5.0",
   "description": "CLI bridge for ftown — generic PTY-over-Centrifugo relay",
   "type": "module",
   "main": "dist/index.js",

package/skills/ftown-sessions/SKILL.md

@@ -47,8 +47,39 @@ Skill copy (same binary via wrapper): `scripts/ftown-sessions` in this skill dir
 
 # Liveness
 ~/.ftown/ftown-sessions running <session-id>
+
+# Stop and remove a session (kept as a tombstone in the archive)
+~/.ftown/ftown-sessions remove <session-id>
+
+# List archived (removed) sessions: id, name, removedAt, shellType
+~/.ftown/ftown-sessions archive
+
+# Recreate a removed session from its tombstone (resumes the agent
+# conversation when a claude/cursor session id was recorded; the revived
+# session gets a NEW id)
+~/.ftown/ftown-sessions revive <session-id>
+```
+
+## Messaging
+
+Send a short text line into another session's terminal. The message is sanitized
+(control characters stripped, capped at 2000 chars) and delivered as
+`[ftown msg from <sender>] <text>` followed by submit, so the target agent reads it
+as a normal prompt.
+
+```bash
+# Tell a specific session
+~/.ftown/ftown-sessions tell <session-id> "tests are green, ship it"
+
+# Tell my parent / children / siblings (resolved via FTOWN_SESSION_ID)
+~/.ftown/ftown-sessions tell --parent "child finished phase 1"
+~/.ftown/ftown-sessions tell --children "pause and report status"
+~/.ftown/ftown-sessions tell --siblings "I grabbed the lock, stand by"
 ```
 
+Sender is resolved from `FTOWN_SESSION_ID` (falls back to `unknown` when unset).
+Fan-out targets are messaged sequentially, one JSON result line per target.
+
 ### Create options
 
 | Flag | Description |
@@ -60,6 +91,7 @@ Skill copy (same binary via wrapper): `scripts/ftown-sessions` in this skill dir
 | `--command` | Full command override (skips `--shell` builder) |
 | `--parent` | Set parent to `$FTOWN_SESSION_ID` |
 | `--parent-id` | Explicit parent session UUID |
+| `--orchestrator` | Brief the new agent (non-`shell`) to spawn and coordinate sibling sessions |
 | `--model` | Cursor model name |
 
 Returns JSON with the new `session.id` — use that id for `screen` / `grep` / `keys`.
@@ -82,8 +114,21 @@ $CLI grep <child-id> --pattern 'FAIL|Error'
 Spawned ftown sessions receive:
 
 - `FTOWN_SESSION_ID` — this session (use with `--parent`)
+- `FTOWN_PARENT_SESSION_ID` — the parent session id, set on children spawned with `--parent` / `--parent-id`
 - `FTOWN_HOOK_PORT` / `FTOWN_HOOK_TOKEN` — hook forwarding (not for cross-session control)
 
+Agent children (any `--shell` except `shell`) spawned with a parent also get an
+automatic one-paragraph briefing prepended to their first input: it states their
+name/id and parent name/id, and how to reach parent and siblings via `tell`. The
+creator's `--prompt` follows after a `Task:` line.
+
+An agent session created with `--orchestrator` additionally gets a one-paragraph
+briefing teaching it to spawn worker sessions with `create --parent`, that those
+children report back via `tell` (arriving as `[ftown msg from <name>]` lines in its
+terminal), and how to inspect/message any session with `list` / `screen` / `grep` /
+`tell`. When both apply, the child paragraph comes first, then the orchestrator
+paragraph, separated by a blank line.
+
 ## HTTP API (optional)
 
 The CLI wraps the loopback API. Raw access if needed:
@@ -95,6 +140,10 @@ The CLI wraps the loopback API. Raw access if needed:
 | GET | `/api/sessions/:id/screen` | Terminal lines |
 | POST | `/api/sessions/:id/grep` | Search |
 | POST | `/api/sessions/:id/keys` | Send keys |
+| POST | `/api/sessions/:id/message` | Deliver a message line (`{ text, from? }`) |
+| DELETE | `/api/sessions/:id` | Remove (tombstone-archived) |
+| GET | `/api/archive` | List removed-session tombstones |
+| POST | `/api/sessions/:id/revive` | Recreate a removed session (new id) |
 
 ## If the CLI is missing
 

package/skills/bridge-harness/SKILL.md

@@ -1,43 +0,0 @@
----
-name: bridge-harness
-description: Control local ftown-bridge sessions via auto-deployed ~/.ftown/bin/ftown-harness. Triggers on bridge harness, /bridge-harness, bridge sessions.
----
-
-# bridge-harness
-
-## Entry (auto-deployed)
-
-```bash
-~/.ftown/bin/ftown-harness <cmd>
-```
-
-Read `~/.ftown/harness-agent.md` on each bridge start. Never curl/lsof the local bridge API.
-
-## Playbook
-
-```bash
-ftown-harness status
-ftown-harness here -n 25    # tails log even if process dead (status=error)
-ftown-harness ls --tail 3   # log=N on each row; previews dead sessions with logs
-ftown-harness grep ftown "error|FAIL" -C 2
-```
-
-## Commands
-
-| Cmd | Notes |
-|-----|-------|
-| `here -n N` | Workspace walk-up; **tails when dead** if log exists |
-| `ls --tail N` | Shows `log=lines`; preview any session with logs |
-| `tail` / `grep` | ANSI+OSC stripped; `grep -C 2` context |
-| `send` | `--dry-run` first; `-s` submit; only when user asks |
-| `--json` | `ftown-harness --json ls` etc. |
-
-Lookup: exact name → substring → id prefix.
-
-## Dead vs error
-
-`status=error` + `alive=false` does **not** mean no logs. Use `here`/`tail` — they read persisted terminal logs.
-
-## context-mode
-
-Use `ftown-harness` in Bash only. No curl/wget to 127.0.0.1.