ftown-bridge 0.19.39 → 0.19.41

package/dist/setup-state.js

@@ -0,0 +1,163 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, unlinkSync, rmdirSync, rmSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { CLI_RUNTIME_MODULES } from './install-ftown-command-cli.js';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export function setupStatePath(home = homedir()) { return join(home, '.ftown', 'setup-state.json'); }
+export function readSetupState(home = homedir()) {
+    try {
+        const value = JSON.parse(readFileSync(setupStatePath(home), 'utf8'));
+        if (!value || typeof value !== 'object' || Array.isArray(value) || value.schema !== 1 || !Array.isArray(value.completedMigrations) || !value.completedMigrations.every((id) => typeof id === 'string'))
+            return { schema: 1, completedMigrations: [] };
+        return { schema: 1, ...(typeof value.packageVersion === 'string' ? { packageVersion: value.packageVersion } : {}), completedMigrations: value.completedMigrations };
+    }
+    catch (error) {
+        if (error instanceof SyntaxError || ['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+            return { schema: 1, completedMigrations: [] };
+        throw error;
+    }
+}
+export function writeSetupState(state, home = homedir()) {
+    const dir = join(home, '.ftown');
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (lstatSync(dir).isSymbolicLink() || !lstatSync(dir).isDirectory())
+        throw new Error('Setup directory must be a real directory');
+    const path = setupStatePath(home);
+    if (existsSync(path) && lstatSync(path).isSymbolicLink())
+        throw new Error('Setup state must not be a symlink');
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+    renameSync(temporary, path);
+}
+export function setupHint(version) {
+    return `npm exec --yes --package ftown-bridge@${version} -- ftown setup`;
+}
+export function assertSetupReady(version, home = homedir()) {
+    const state = readSetupState(home);
+    const missing = REQUIRED_SETUP_ASSETS.some((asset) => {
+        try {
+            return !lstatSync(join(home, '.ftown', asset)).isFile();
+        }
+        catch {
+            return true;
+        }
+    });
+    if (state.packageVersion !== version || missing) {
+        const repair = state.packageVersion === version ? ' --repair' : '';
+        throw new Error(`FTown setup is missing, incomplete or outdated. Run: ${setupHint(version)}${repair}`);
+    }
+}
+/** Existence/type inventory; startup never repairs or hashes global integrations. */
+export const REQUIRED_SETUP_ASSETS = [
+    'ftown', 'ftown-sessions', 'ftown-env', 'bin/ftown-harness', 'notify.sh',
+    'pi/ftown.js', 'harness-agent.md', 'skills/ftown/SKILL.md',
+    'cli/package.json', 'cli/node_modules/commander/package.json', 'cli/node_modules/commander/index.js',
+    'cli/hooks/notify.sh', 'cli/pi-extension/ftown.js', 'cli/opencode-plugin/ftown.js',
+    'cli/muse-plugin/.muse-plugin/plugin.json', 'cli/skills/ftown/SKILL.md',
+    ...CLI_RUNTIME_MODULES.map((name) => `cli/dist/${name}.js`),
+];
+/** Reject stale npm-cache setup rather than overwrite a newer installed runtime. */
+export function assertSetupVersion(version, installed) {
+    if (installed && installed.localeCompare(version, undefined, { numeric: true }) > 0) {
+        throw new Error(`Installed FTown ${installed} is newer than ${version}. Run matching setup: ${setupHint(installed)} --repair`);
+    }
+}
+/** Atomic nonempty-directory lock. Reclaim only an exact provably dead owner. */
+export function acquireSetupLock(home = homedir()) {
+    const parent = join(home, '.ftown');
+    mkdirSync(parent, { recursive: true, mode: 0o700 });
+    if (lstatSync(parent).isSymbolicLink())
+        throw new Error('Setup directory must be real');
+    const token = randomBytes(12).toString('hex');
+    const owner = `owner-${process.pid}-${token}.json`;
+    const candidate = join(parent, `.setup-pending-${process.pid}-${token}`);
+    const lock = join(parent, 'setup.lock');
+    mkdirSync(candidate, { mode: 0o700 });
+    writeFileSync(join(candidate, owner), JSON.stringify({ pid: process.pid, token }), { mode: 0o600 });
+    let acquired = false;
+    try {
+        for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+                renameSync(candidate, lock);
+                acquired = true;
+                break;
+            }
+            catch (error) {
+                if (!['EEXIST', 'ENOTEMPTY'].includes(error.code ?? ''))
+                    throw error;
+                const stat = lstatSync(lock);
+                if (!stat.isDirectory() || stat.isSymbolicLink())
+                    throw new Error('Setup lock has an unknown owner; preserved');
+                const entries = readdirSync(lock);
+                if (entries.length === 0)
+                    continue; // owner is releasing; never recursively remove a lock
+                const match = entries.length === 1 ? /^owner-(\d+)-([a-f0-9]+)\.json$/.exec(entries[0]) : null;
+                if (!match)
+                    throw new Error('Setup lock has an unknown owner; preserved');
+                const marker = join(lock, entries[0]);
+                let recorded;
+                try {
+                    if (!lstatSync(marker).isFile() || lstatSync(marker).isSymbolicLink())
+                        throw new Error('unknown marker');
+                    recorded = JSON.parse(readFileSync(marker, 'utf8'));
+                }
+                catch {
+                    throw new Error('Setup lock has an unknown owner; preserved');
+                }
+                const pid = Number(match[1]);
+                if (!recorded || recorded.pid !== pid || recorded.token !== match[2])
+                    throw new Error('Setup lock has an unknown owner; preserved');
+                let dead = false;
+                if (Number.isSafeInteger(pid) && pid > 0) {
+                    try {
+                        process.kill(pid, 0);
+                    }
+                    catch (probe) {
+                        dead = probe.code === 'ESRCH';
+                    }
+                }
+                if (!dead)
+                    throw new Error(`Another ftown setup owns the lock (pid ${pid}); retry after it finishes`);
+                // An active successor uses a different owner filename. Removing this exact
+                // dead marker and rmdir of an empty dir cannot displace a successor.
+                try {
+                    unlinkSync(join(lock, entries[0]));
+                }
+                catch (unlinkError) {
+                    if (unlinkError.code !== 'ENOENT')
+                        throw unlinkError;
+                }
+                try {
+                    rmdirSync(lock);
+                }
+                catch (removeError) {
+                    if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(removeError.code ?? ''))
+                        throw removeError;
+                }
+            }
+        }
+        if (!acquired)
+            throw new Error('Setup lock changed; retry after the other setup finishes');
+        return () => {
+            try {
+                unlinkSync(join(lock, owner));
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            try {
+                rmdirSync(lock);
+            }
+            catch (error) {
+                if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code ?? ''))
+                    throw error;
+            }
+        };
+    }
+    finally {
+        if (!acquired)
+            rmSync(candidate, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=setup-state.js.map

package/dist/setup-state.js.map

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

package/dist/setup.d.ts

@@ -0,0 +1,25 @@
+export interface IntegrationResult {
+    name: string;
+    status: 'installed' | 'skipped';
+    detail?: string;
+}
+export interface SetupDependencies {
+    installRuntime: (packageRoot: string) => void;
+    integrations: (runtimeRoot: string) => Promise<IntegrationResult[]>;
+    skillAndPath: (runtimeRoot: string) => void;
+    migrate: (repair: boolean) => string[];
+}
+export interface SetupResult {
+    version: string;
+    action: 'installed' | 'current';
+    migrations: string[];
+    integrations: IntegrationResult[];
+}
+export declare function packageRoot(): string;
+export declare function packageVersion(root?: string): string;
+export declare function performSetup(options?: {
+    root?: string;
+    repair?: boolean;
+    dependencies?: SetupDependencies;
+}): Promise<SetupResult>;
+export declare function runSetup(argv: string[]): Promise<number>;

package/dist/setup.js

@@ -0,0 +1,120 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { installFtownCommandCli } from './install-ftown-command-cli.js';
+import { installNotifyScript } from './install-notify-script.js';
+import { installPiExtension } from './pi-extension-installer.js';
+import { installClaudeHooks } from './hook-installer.js';
+import { installCursorHooks } from './cursor-hook-installer.js';
+import { codexBinaryAvailable, ensureCodexHooks } from './codex-installer.js';
+import { opencodeBinaryAvailable, installOpencodePlugin } from './opencode-plugin-installer.js';
+import { ensureMusePlugin } from './muse-plugin-installer.js';
+import { installFtownSkill } from './install-ftown-skill.js';
+import { writeHarnessAgentGuide } from './harness-installer.js';
+import { ensureFtownOnPath } from './ensure-ftown-path.js';
+import { readSetupState, writeSetupState, assertSetupReady, acquireSetupLock, assertSetupVersion } from './setup-state.js';
+import { runSetupMigrations } from './setup-migrations.js';
+export function packageRoot() { return resolve(dirname(fileURLToPath(import.meta.url)), '..'); }
+export function packageVersion(root = packageRoot()) {
+    return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version;
+}
+async function installIntegrations(root) {
+    const notify = installNotifyScript(join(root, 'hooks', 'notify.sh'));
+    installPiExtension(join(root, 'pi-extension', 'ftown.js'));
+    if (!installClaudeHooks(notify))
+        throw new Error('Claude hook setup failed; fix settings.json and rerun ftown setup --repair');
+    if (!installCursorHooks(notify))
+        throw new Error('Cursor hook setup failed; fix hooks.json and rerun ftown setup --repair');
+    const results = [{ name: 'claude/cursor/pi', status: 'installed' }];
+    if (await codexBinaryAvailable()) {
+        if (!ensureCodexHooks(join(homedir(), '.ftown', 'bin', 'ftown-harness'), notify))
+            throw new Error('Codex hook setup failed; fix hooks.json and rerun ftown setup --repair');
+        results.push({ name: 'codex', status: 'installed' });
+    }
+    else
+        results.push({ name: 'codex', status: 'skipped', detail: 'binary not installed' });
+    if (await opencodeBinaryAvailable()) {
+        installOpencodePlugin(join(root, 'opencode-plugin', 'ftown.js'));
+        results.push({ name: 'opencode', status: 'installed' });
+    }
+    else
+        results.push({ name: 'opencode', status: 'skipped', detail: 'binary not installed' });
+    const muse = await ensureMusePlugin(join(root, 'muse-plugin'));
+    if (muse.action === 'skipped')
+        results.push({ name: 'muse', status: 'skipped', detail: muse.warning ?? 'binary not installed' });
+    else {
+        if (muse.action === 'failed' || !muse.approved || muse.warning)
+            throw new Error(muse.warning ?? 'Muse plugin setup failed; rerun ftown setup --repair');
+        results.push({ name: 'muse', status: 'installed' });
+    }
+    return results;
+}
+function defaultDependencies() {
+    return {
+        installRuntime: (root) => { installFtownCommandCli(root); },
+        integrations: installIntegrations,
+        skillAndPath: (root) => {
+            installFtownSkill('ftown', join(root, 'skills', 'ftown'));
+            writeHarnessAgentGuide({ wrapperPath: join(homedir(), '.ftown', 'bin', 'ftown-harness') });
+            ensureFtownOnPath();
+        },
+        migrate: (repair) => runSetupMigrations(repair),
+    };
+}
+export async function performSetup(options = {}) {
+    const root = options.root ?? packageRoot();
+    const version = packageVersion(root);
+    const release = acquireSetupLock();
+    try {
+        const state = readSetupState();
+        let installedVersion = state.packageVersion;
+        try {
+            installedVersion = packageVersion(join(homedir(), '.ftown', 'cli'));
+        }
+        catch { /* Fresh runtime; durable ready version still applies. */ }
+        assertSetupVersion(version, state.packageVersion);
+        assertSetupVersion(version, installedVersion);
+        if (!options.repair && state.packageVersion === version) {
+            // Explicit repair is the recovery path for missing assets or new integrations.
+            assertSetupReady(version);
+            return { version, action: 'current', migrations: [], integrations: [] };
+        }
+        const deps = options.dependencies ?? defaultDependencies();
+        // Invalidate readiness BEFORE changing any integration; a failure remains retryable.
+        writeSetupState({ schema: 1, completedMigrations: state.completedMigrations });
+        const migrations = deps.migrate(!!options.repair);
+        deps.installRuntime(root);
+        const installedRoot = join(homedir(), '.ftown', 'cli');
+        const integrations = await deps.integrations(installedRoot);
+        deps.skillAndPath(installedRoot);
+        writeSetupState({ ...readSetupState(), packageVersion: version });
+        return { version, action: 'installed', migrations, integrations };
+    }
+    finally {
+        release();
+    }
+}
+export async function runSetup(argv) {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        console.log('Usage: ftown setup [--repair]\nInstall or upgrade local runtime, integrations, skill and PATH. --repair rechecks current setup and cleanup.');
+        return 0;
+    }
+    if (argv.some((arg) => arg !== '--repair')) {
+        console.error('Usage: ftown setup [--repair]');
+        return 1;
+    }
+    try {
+        const result = await performSetup({ repair: argv.includes('--repair') });
+        console.log(`ftown setup ${result.version}: ${result.action}`);
+        for (const integration of result.integrations)
+            console.log(`  ${integration.name}: ${integration.status}${integration.detail ? ` (${integration.detail})` : ''}`);
+        console.log('Open a new shell for PATH changes; start ftown-bridge when ready.');
+        return 0;
+    }
+    catch (error) {
+        console.error(`ftown setup: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}
+//# sourceMappingURL=setup.js.map

package/dist/setup.js.map

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

package/dist/types.d.ts

@@ -99,6 +99,7 @@ export interface CreateSessionPayload {
     opencodeSessionId?: string;
     museSessionId?: string;
     parentSessionId?: string;
+    /** @deprecated Ignored compatibility input. Ordinary sessions use task + parent. */
     orchestrator?: boolean;
     suppressBriefing?: boolean;
     createMissingWorkingDir?: boolean;

package/dist/wire-types.js

@@ -1,11 +1,4 @@
-// No imports beyond Node builtins — this file must stay dependency-free so compiled
-// sibling copies work standalone when this file is copied alongside harness-cli.js
-// and ftown-sessions-cli.js into ~/.ftown (see harness-installer.ts / install-ftown-cli.ts).
-//
-// This module holds the wire shapes shared by the standalone CLIs (harness-cli.ts,
-// ftown-sessions-cli.ts) that talk to LocalApiServer over ~/.ftown/bridge.json. These
-// are the shapes as seen over the wire by those CLIs — not necessarily identical to the
-// richer internal types in ./types.ts.
+// Shared wire shapes for the in-process CLI runtime and local bridge API.
 export const MAIL_TYPES = ['message', 'task', 'result', 'escalation'];
 export const AUTOMATION_REMOVED_CODE = 'automation_removed';
 export const AUTOMATION_REMOVED_MESSAGE = 'Recurring loops and factory automation have been removed';

package/dist/wire-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"wire-types.js","sourceRoot":"","sources":["../src/wire-types.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,mFAAmF;AACnF,6FAA6F;AAC7F,EAAE;AACF,mFAAmF;AACnF,sFAAsF;AACtF,wFAAwF;AACxF,uCAAuC;AAwDvC,MAAM,CAAC,MAAM,UAAU,GAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC;AAgB3F,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAA6B,CAAC;AACrE,MAAM,CAAC,MAAM,0BAA0B,GAAG,0DAA0D,CAAC;AAErG;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,UAAmB;IAC9C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,iBAAiB,CAAC,CAAc;IAC9C,OAAO,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;AACpE,CAAC"}
+{"version":3,"file":"wire-types.js","sourceRoot":"","sources":["../src/wire-types.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAwD1E,MAAM,CAAC,MAAM,UAAU,GAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC;AAgB3F,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAA6B,CAAC;AACrE,MAAM,CAAC,MAAM,0BAA0B,GAAG,0DAA0D,CAAC;AAErG;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,UAAmB;IAC9C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,iBAAiB,CAAC,CAAc;IAC9C,OAAO,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;AACpE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ftown-bridge",
-  "version": "0.19.39",
+  "version": "0.19.41",
   "description": "CLI bridge for ftown — generic PTY-over-Centrifugo relay",
   "type": "module",
   "main": "dist/index.js",
@@ -10,7 +10,6 @@
     "ftown-harness": "dist/harness-cli.js",
     "ftown-env": "dist/ftown-env-cli.js",
     "ftown-sessions": "bin/ftown-sessions",
-    "ftown-workflows": "dist/workflow-runner-cli.js",
     "ftown-mcp": "dist/mcp-cli.js"
   },
   "files": [
@@ -23,7 +22,7 @@
     "skills"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
     "test": "node --import tsx --test \"src/**/*.test.ts\"",
     "prepublishOnly": "npm run build",
     "start": "tsx src/index.ts",

package/pi-extension/API.md

@@ -64,3 +64,7 @@ The tool schemas ship with `ftown-bridge` and follow its semantic version. Addin
 ## Consumer walkthrough
 
 An agent can call `ftown_sessions.list`, use the returned session ID with `ftown_sessions.get` or `usage`, and then send context with `ftown_mail.send`. To delegate, it can create a child with `ftown_session_create`, retain the returned ID, inspect its output, and later rename, reparent, stop, remove, or revive it.
+
+The ftown extension is installed by explicit `ftown setup`; use
+`ftown setup --repair` after installing a new optional harness. Structured creates
+use ordinary task and parent inputs. Legacy orchestrator booleans are ignored.

package/pi-extension/ftown.js

@@ -526,7 +526,7 @@ export function registerFtownPiExtension(pi, options = {}) {
         parent: { type: 'boolean', description: 'Make the current Pi session the parent.' },
         parentId: { type: 'string', description: 'Explicit ftown parent session id.' },
         createWorkdir: { type: 'boolean' },
-        orchestrator: { type: 'boolean' },
+        orchestrator: { type: 'boolean', description: 'Deprecated compatibility input; ignored.' },
       },
       required: ['prompt'],
       additionalProperties: false,
@@ -544,7 +544,6 @@ export function registerFtownPiExtension(pi, options = {}) {
               ? { parentSessionId: params.parentId }
               : params.parent ? { parentSessionId: true } : {}),
             ...(params.createWorkdir ? { createMissingWorkingDir: true } : {}),
-            ...(params.orchestrator ? { orchestrator: true } : {}),
           };
           const extraHeaders = ftownSessionId
             ? { 'x-ftown-session-id': ftownSessionId }

package/skills/ftown/SKILL.md

@@ -1,33 +1,85 @@
 ---
 name: ftown
 description: >-
-  Control ftown from inside agent sessions: create/list/read/drive sibling
-  sessions, send ftown mail, and coordinate worker agent sessions. Use when a task
-  mentions ftown, ftown sessions, bridge sessions, child/sibling agents, mail/inbox,
-  orchestration, or fan-out.
+  Control ftown sessions: create/list/read/drive sibling sessions, send ftown
+  mail, and coordinate worker agents. Use for ftown sessions, child/sibling
+  agents, bridge mail/inbox, or explicitly requested orchestration.
 ---
 
 # ftown
 
-Use the local bridge CLIs installed under `~/.ftown`. They read
-`~/.ftown/bridge.json`; anyone who can read that file can control the bridge's
-sessions.
+Use `ftown sessions`, `ftown harness`, and `ftown env`. Run `ftown --help`
+for command discovery; if it is missing from PATH, use `~/.ftown/ftown`.
+The bridge installs this skill at `~/.ftown/skills/ftown`, linked from the agent
+skill directories. Startup checks setup readiness and never rewrites global
+integrations. Before the installed command exists, run setup from the package:
 
-## Pick The Reference
+```bash
+npm exec --yes --package ftown-bridge -- ftown setup
+```
+
+For upgrades, use the exact new version named by the startup readiness hint:
+
+```bash
+npm exec --yes --package ftown-bridge@<new-version> -- ftown setup
+```
+
+The installed alias uses its copied version and does not discover newer packages.
+Use `ftown setup --repair` to repair that current copied version or detect new
+optional harnesses. If the copied runtime is incomplete, use the matching package
+entrypoint with `--repair`.
+
+## Commands and references
+
+```bash
+ftown sessions list
+ftown sessions create --prompt "Review the auth module" --workdir "$PWD" --parent
+ftown sessions screen <session-id> --limit 200
+ftown harness mail send <session-id> --type task "review the API client"
+ftown harness mail read
+ftown env --help
+ftown setup --help
+```
+
+Read `references/sessions.md` for the session, mail and terminal command
+reference. Read `references/orchestrator.md` for practical worker coordination
+examples. Each command group also has `--help`.
+
+## Identity and reporting
+
+Your id is `$FTOWN_SESSION_ID`; children also receive `$FTOWN_PARENT_SESSION_ID`.
+A child's initial briefing identifies it and its parent and explains reporting:
+
+```bash
+ftown harness mail send --parent --type result "Done; checks passed"
+ftown harness mail send --parent --type escalation "Blocked: need the API contract"
+```
+
+Mail arrives as `[ftown mail]` context through harness hooks/extensions where
+available. Cursor and shell sessions receive an idle nudge to read their inbox.
+Prefer mail for agent communication; use terminal key injection only when the
+task needs it. Inspect peers with `ftown sessions list` and
+`ftown sessions screen <id> --limit 100`.
 
-- Session control, mail, terminal output, archive/revive, or local API:
-  read `references/sessions.md`.
-- Ad-hoc multi-agent coordination from an orchestrator session:
-  read `references/orchestrator.md`.
+## Cleanup
 
-## Quick Commands
+Session cleanup is an explicit user or orchestrator action. Reporting a result
+does not remove a child automatically. Keep sessions available for follow-up
+until cleanup is requested or the coordinating task calls for it.
 
 ```bash
-# Sessions
-~/.ftown/ftown-sessions list
-~/.ftown/ftown-sessions create --prompt "Run tests" --workdir "$PWD" --parent
-~/.ftown/ftown-sessions screen <session-id> --limit 200
-~/.ftown/ftown-sessions tell <session-id> --type task "continue with the API client"
+ftown sessions remove <finished-session-id>
+ftown sessions archive
+ftown sessions revive <archived-session-id>
 ```
 
-Use orchestrator guidance for ad-hoc multi-agent coordination.
+Removal archives the session; revival creates a new session id and resumes its
+agent conversation when supported. Preserve useful results before cleanup.
+
+## Connection and compatibility
+
+The commands read `~/.ftown/bridge.json`. Anyone who can read that file can
+control the bridge's sessions. Existing `ftown-sessions`, `ftown-harness`, and
+`ftown-env` launchers remain compatible; use the grouped commands above in new
+instructions. ftown does not install a ticket system or provide a workflow
+runner. Independently installed coordination tools remain yours to manage.