ftown 0.26.0 → 0.28.0

package/dist/worktrees.js

@@ -0,0 +1,292 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, realpath } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { WorktreeError, } from './coordination/contract-b.js';
+export { WorktreeError, };
+const execFileAsync = promisify(execFile);
+const GIT_TIMEOUT_MS = 30_000;
+const GIT_MAX_BUFFER = 10 * 1024 * 1024;
+const SLUG_MAX_LENGTH = 48;
+export function slugifyWorktreeName(name) {
+    const cleaned = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, SLUG_MAX_LENGTH)
+        .replace(/-+$/g, '');
+    return cleaned || 'session';
+}
+async function runGit(cwd, args) {
+    const { stdout, stderr } = await execFileAsync('git', [...args], {
+        cwd,
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: GIT_MAX_BUFFER,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+    return { stdout, stderr };
+}
+function errorMessage(err) {
+    if (err && typeof err === 'object') {
+        const stderr = err.stderr;
+        if (typeof stderr === 'string' && stderr.trim().length > 0) {
+            return stderr.trim();
+        }
+        const message = err.message;
+        if (typeof message === 'string' && message.trim().length > 0) {
+            return message.trim();
+        }
+    }
+    return String(err);
+}
+export class GitWorktrees {
+    constructor(_options = {}) { }
+    async create(req) {
+        const fromDir = req.fromDir;
+        if (!fromDir || !existsSync(fromDir)) {
+            throw new WorktreeError('not_a_repo', `Directory does not exist: ${fromDir}`);
+        }
+        let topLevelRaw;
+        let gitDirRaw;
+        let commonDirRaw;
+        try {
+            topLevelRaw = (await runGit(fromDir, ['rev-parse', '--show-toplevel'])).stdout.trim();
+            gitDirRaw = (await runGit(fromDir, ['rev-parse', '--git-dir'])).stdout.trim();
+            commonDirRaw = (await runGit(fromDir, ['rev-parse', '--git-common-dir'])).stdout.trim();
+        }
+        catch (err) {
+            throw new WorktreeError('not_a_repo', `Not a git repository (${fromDir}): ${errorMessage(err)}`);
+        }
+        const topLevel = await realpath(resolve(fromDir, topLevelRaw));
+        const gitDir = await realpath(resolve(fromDir, gitDirRaw));
+        const commonDir = await realpath(resolve(fromDir, commonDirRaw));
+        // When fromDir is itself a linked worktree, gitDir !== commonDir; use the main worktree's root (commonDir parent).
+        const repoRoot = gitDir !== commonDir ? await realpath(dirname(commonDir)) : topLevel;
+        let base;
+        if (req.base !== undefined && req.base.trim().length > 0) {
+            base = req.base.trim();
+            if (base.startsWith('-')) {
+                throw new WorktreeError('git_failed', `Invalid base ref: ${base}`);
+            }
+            try {
+                await runGit(fromDir, ['rev-parse', '--verify', `${base}^{commit}`]);
+            }
+            catch (err) {
+                throw new WorktreeError('git_failed', `Unknown base ref '${base}': ${errorMessage(err)}`);
+            }
+        }
+        else {
+            try {
+                base = (await runGit(fromDir, ['symbolic-ref', '--short', 'HEAD'])).stdout.trim();
+            }
+            catch {
+                throw new WorktreeError('detached_head', 'detached HEAD; pass --base');
+            }
+            if (!base) {
+                throw new WorktreeError('detached_head', 'detached HEAD; pass --base');
+            }
+        }
+        const slug = slugifyWorktreeName(req.name);
+        const rawBranch = req.branch !== undefined ? req.branch.trim() : `ftown/${slug}`;
+        if (!rawBranch || rawBranch.startsWith('-') || rawBranch.includes('@{')) {
+            throw new WorktreeError('bad_branch', `Invalid branch name: ${req.branch ?? ''}`);
+        }
+        try {
+            const checked = (await runGit(repoRoot, ['check-ref-format', '--branch', rawBranch])).stdout.trim();
+            if (checked !== rawBranch) {
+                throw new WorktreeError('bad_branch', `Invalid branch name '${rawBranch}'`);
+            }
+        }
+        catch (err) {
+            if (err instanceof WorktreeError)
+                throw err;
+            throw new WorktreeError('bad_branch', `Invalid branch name '${rawBranch}': ${errorMessage(err)}`);
+        }
+        const branch = rawBranch;
+        const worktreePath = join(repoRoot, '.claude', 'worktrees', slug);
+        if (existsSync(worktreePath)) {
+            throw new WorktreeError('exists', `Worktree path already exists: ${worktreePath}`);
+        }
+        try {
+            await runGit(repoRoot, ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`]);
+            throw new WorktreeError('exists', `Branch already exists: ${branch}`);
+        }
+        catch (err) {
+            if (err instanceof WorktreeError)
+                throw err;
+        }
+        await mkdir(dirname(worktreePath), { recursive: true });
+        try {
+            await runGit(repoRoot, ['worktree', 'add', '-b', branch, worktreePath, base]);
+        }
+        catch (err) {
+            const msg = errorMessage(err);
+            if (/already exists|already checked out/i.test(msg)) {
+                throw new WorktreeError('exists', msg);
+            }
+            throw new WorktreeError('git_failed', msg);
+        }
+        const realWorktreePath = await realpath(worktreePath);
+        return {
+            repoRoot,
+            path: realWorktreePath,
+            branch,
+            base,
+            createdByBridge: true,
+        };
+    }
+    async status(wt) {
+        if (!existsSync(wt.path)) {
+            return {
+                path: wt.path,
+                branch: wt.branch,
+                base: wt.base,
+                exists: false,
+                dirty: false,
+                ahead: 0,
+                unpushed: null,
+                mergedIntoBase: false,
+            };
+        }
+        let realWtPath;
+        let topLevel;
+        try {
+            realWtPath = await realpath(wt.path);
+            const topOut = (await runGit(realWtPath, ['rev-parse', '--show-toplevel'])).stdout.trim();
+            topLevel = await realpath(resolve(realWtPath, topOut));
+        }
+        catch (err) {
+            throw new WorktreeError('git_failed', `Failed to resolve worktree root (${wt.path}): ${errorMessage(err)}`);
+        }
+        if (topLevel !== realWtPath) {
+            throw new WorktreeError('git_failed', `Worktree path '${wt.path}' is not a standalone worktree toplevel (resolved to '${topLevel}')`);
+        }
+        let dirty;
+        try {
+            const porcelain = (await runGit(realWtPath, ['status', '--porcelain'])).stdout;
+            dirty = porcelain.trim().length > 0;
+        }
+        catch (err) {
+            throw new WorktreeError('git_failed', `Failed to read worktree status: ${errorMessage(err)}`);
+        }
+        let ahead;
+        try {
+            const countRaw = (await runGit(realWtPath, ['rev-list', '--count', `${wt.base}..${wt.branch}`])).stdout.trim();
+            const parsed = Number.parseInt(countRaw, 10);
+            if (!Number.isFinite(parsed) || parsed < 0) {
+                throw new Error(`Unexpected rev-list count: ${countRaw}`);
+            }
+            ahead = parsed;
+        }
+        catch (err) {
+            throw new WorktreeError('git_failed', `Failed to count commits ahead of base: ${errorMessage(err)}`);
+        }
+        let unpushed = null;
+        let upstreamRef;
+        try {
+            upstreamRef = (await runGit(realWtPath, ['for-each-ref', '--format=%(upstream:short)', `refs/heads/${wt.branch}`])).stdout.trim();
+        }
+        catch (err) {
+            throw new WorktreeError('git_failed', `Failed to inspect branch upstream: ${errorMessage(err)}`);
+        }
+        if (upstreamRef.length > 0) {
+            try {
+                const countRaw = (await runGit(realWtPath, ['rev-list', '--count', `${wt.branch}@{u}..${wt.branch}`])).stdout.trim();
+                const parsed = Number.parseInt(countRaw, 10);
+                if (!Number.isFinite(parsed) || parsed < 0) {
+                    throw new Error(`Unexpected unpushed count: ${countRaw}`);
+                }
+                unpushed = parsed;
+            }
+            catch (err) {
+                throw new WorktreeError('git_failed', `Failed to count unpushed commits: ${errorMessage(err)}`);
+            }
+        }
+        let mergedIntoBase = false;
+        try {
+            await runGit(realWtPath, ['merge-base', '--is-ancestor', wt.branch, wt.base]);
+            mergedIntoBase = true;
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code === 1) {
+                mergedIntoBase = false;
+            }
+            else {
+                throw new WorktreeError('git_failed', `Failed to check merge status: ${errorMessage(err)}`);
+            }
+        }
+        return {
+            path: wt.path,
+            branch: wt.branch,
+            base: wt.base,
+            exists: true,
+            dirty,
+            ahead,
+            unpushed,
+            mergedIntoBase,
+        };
+    }
+    decide(status) {
+        if (!status.exists) {
+            return { action: 'retain', reason: 'worktree missing' };
+        }
+        if (status.dirty) {
+            return { action: 'retain', reason: 'uncommitted changes' };
+        }
+        if (status.mergedIntoBase) {
+            return { action: 'remove', deleteBranch: true };
+        }
+        if (status.unpushed === 0) {
+            return { action: 'remove', deleteBranch: false };
+        }
+        if (status.unpushed !== null && status.unpushed > 0) {
+            return {
+                action: 'retain',
+                reason: `${status.unpushed} unpushed commit${status.unpushed === 1 ? '' : 's'}`,
+            };
+        }
+        if (status.ahead > 0) {
+            return {
+                action: 'retain',
+                reason: `${status.ahead} unmerged commit${status.ahead === 1 ? '' : 's'}`,
+            };
+        }
+        return { action: 'retain', reason: 'unmerged branch' };
+    }
+    async remove(wt, opts) {
+        const removeArgs = ['worktree', 'remove', ...(opts.force ? ['--force'] : []), wt.path];
+        try {
+            await runGit(wt.repoRoot, removeArgs);
+        }
+        catch (err) {
+            throw new WorktreeError('git_failed', errorMessage(err));
+        }
+        if (opts.deleteBranch) {
+            let merged = false;
+            try {
+                await runGit(wt.repoRoot, ['merge-base', '--is-ancestor', wt.branch, wt.base]);
+                merged = true;
+            }
+            catch (err) {
+                const code = err?.code;
+                if (code !== 1) {
+                    console.warn(`[GitWorktrees] Failed to verify merge status for branch '${wt.branch}': ${errorMessage(err)}`);
+                }
+                merged = false;
+            }
+            if (!merged) {
+                console.warn(`[GitWorktrees] Refusing to delete unmerged branch '${wt.branch}'`);
+                return;
+            }
+            try {
+                await runGit(wt.repoRoot, ['branch', '-d', wt.branch]);
+            }
+            catch (err) {
+                console.warn(`[GitWorktrees] Failed to delete branch '${wt.branch}': ${errorMessage(err)}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=worktrees.js.map

package/dist/worktrees.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktrees.js","sourceRoot":"","sources":["../src/worktrees.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EACL,aAAa,GAMd,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,aAAa,GAMd,CAAC;AAEF,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAC1C,MAAM,cAAc,GAAG,MAAM,CAAC;AAC9B,MAAM,cAAc,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACxC,MAAM,eAAe,GAAG,EAAE,CAAC;AAM3B,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,OAAO,GAAG,IAAI;SACjB,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC;SACzB,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACvB,OAAO,OAAO,IAAI,SAAS,CAAC;AAC9B,CAAC;AAOD,KAAK,UAAU,MAAM,CAAC,GAAW,EAAE,IAAuB;IACxD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE;QAC/D,GAAG;QACH,OAAO,EAAE,cAAc;QACvB,SAAS,EAAE,cAAc;QACzB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,mBAAmB,EAAE,GAAG,EAAE;KAClD,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC;AAED,SAAS,YAAY,CAAC,GAAY;IAChC,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACnC,MAAM,MAAM,GAAI,GAA4B,CAAC,MAAM,CAAC;QACpD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3D,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;QACvB,CAAC;QACD,MAAM,OAAO,GAAI,GAA6B,CAAC,OAAO,CAAC;QACvD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7D,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED,MAAM,OAAO,YAAY;IACvB,YAAY,WAAgC,EAAE,IAAG,CAAC;IAElD,KAAK,CAAC,MAAM,CAAC,GAA0B;QACrC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,6BAA6B,OAAO,EAAE,CAAC,CAAC;QAChF,CAAC;QAED,IAAI,WAAmB,CAAC;QACxB,IAAI,SAAiB,CAAC;QACtB,IAAI,YAAoB,CAAC;QACzB,IAAI,CAAC;YACH,WAAW,GAAG,CAAC,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACtF,SAAS,GAAG,CAAC,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YAC9E,YAAY,GAAG,CAAC,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC1F,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,yBAAyB,OAAO,MAAM,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnG,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC;QAC/D,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;QAC3D,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;QACjE,mHAAmH;QACnH,MAAM,QAAQ,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QAEtF,IAAI,IAAY,CAAC;QACjB,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzD,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACvB,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzB,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,qBAAqB,IAAI,EAAE,CAAC,CAAC;YACrE,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC;YACvE,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,qBAAqB,IAAI,MAAM,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC5F,CAAC;QACH,CAAC;aAAM,CAAC;YACN,IAAI,CAAC;gBACH,IAAI,GAAG,CAAC,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC,cAAc,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACpF,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,IAAI,aAAa,CAAC,eAAe,EAAE,4BAA4B,CAAC,CAAC;YACzE,CAAC;YACD,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,aAAa,CAAC,eAAe,EAAE,4BAA4B,CAAC,CAAC;YACzE,CAAC;QACH,CAAC;QAED,MAAM,IAAI,GAAG,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3C,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC;QACjF,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACxE,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,wBAAwB,GAAG,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC,CAAC;QACpF,CAAC;QAED,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,CAAC,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC,kBAAkB,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACpG,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,wBAAwB,SAAS,GAAG,CAAC,CAAC;YAC9E,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,aAAa;gBAAE,MAAM,GAAG,CAAC;YAC5C,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,wBAAwB,SAAS,MAAM,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpG,CAAC;QACD,MAAM,MAAM,GAAG,SAAS,CAAC;QAEzB,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;QAClE,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,aAAa,CAAC,QAAQ,EAAE,iCAAiC,YAAY,EAAE,CAAC,CAAC;QACrF,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,MAAM,EAAE,CAAC,CAAC,CAAC;YACpF,MAAM,IAAI,aAAa,CAAC,QAAQ,EAAE,0BAA0B,MAAM,EAAE,CAAC,CAAC;QACxE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,aAAa;gBAAE,MAAM,GAAG,CAAC;QAC9C,CAAC;QAED,MAAM,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAExD,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC,CAAC;QAChF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;YAC9B,IAAI,qCAAqC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpD,MAAM,IAAI,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;YACzC,CAAC;YACD,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;QAC7C,CAAC;QAED,MAAM,gBAAgB,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC;QACtD,OAAO;YACL,QAAQ;YACR,IAAI,EAAE,gBAAgB;YACtB,MAAM;YACN,IAAI;YACJ,eAAe,EAAE,IAAI;SACtB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,EAAmB;QAC9B,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,OAAO;gBACL,IAAI,EAAE,EAAE,CAAC,IAAI;gBACb,MAAM,EAAE,EAAE,CAAC,MAAM;gBACjB,IAAI,EAAE,EAAE,CAAC,IAAI;gBACb,MAAM,EAAE,KAAK;gBACb,KAAK,EAAE,KAAK;gBACZ,KAAK,EAAE,CAAC;gBACR,QAAQ,EAAE,IAAI;gBACd,cAAc,EAAE,KAAK;aACtB,CAAC;QACJ,CAAC;QAED,IAAI,UAAkB,CAAC;QACvB,IAAI,QAAgB,CAAC;QACrB,IAAI,CAAC;YACH,UAAU,GAAG,MAAM,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YACrC,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YAC1F,QAAQ,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;QACzD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,oCAAoC,EAAE,CAAC,IAAI,MAAM,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9G,CAAC;QAED,IAAI,QAAQ,KAAK,UAAU,EAAE,CAAC;YAC5B,MAAM,IAAI,aAAa,CACrB,YAAY,EACZ,kBAAkB,EAAE,CAAC,IAAI,yDAAyD,QAAQ,IAAI,CAC/F,CAAC;QACJ,CAAC;QAED,IAAI,KAAc,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,CAAC,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YAC/E,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,mCAAmC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChG,CAAC;QAED,IAAI,KAAa,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YAC/G,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YAC7C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC3C,MAAM,IAAI,KAAK,CAAC,8BAA8B,QAAQ,EAAE,CAAC,CAAC;YAC5D,CAAC;YACD,KAAK,GAAG,MAAM,CAAC;QACjB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,0CAA0C,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvG,CAAC;QAED,IAAI,QAAQ,GAAkB,IAAI,CAAC;QACnC,IAAI,WAAmB,CAAC;QACxB,IAAI,CAAC;YACH,WAAW,GAAG,CACZ,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC,cAAc,EAAE,4BAA4B,EAAE,cAAc,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CACpG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAClB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,sCAAsC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnG,CAAC;QAED,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,MAAM,SAAS,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;gBACrH,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;gBAC7C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC3C,MAAM,IAAI,KAAK,CAAC,8BAA8B,QAAQ,EAAE,CAAC,CAAC;gBAC5D,CAAC;gBACD,QAAQ,GAAG,MAAM,CAAC;YACpB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,qCAAqC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAClG,CAAC;QACH,CAAC;QAED,IAAI,cAAc,GAAG,KAAK,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;YAC9E,cAAc,GAAG,IAAI,CAAC;QACxB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,GAAI,GAA0B,EAAE,IAAI,CAAC;YAC/C,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;gBACf,cAAc,GAAG,KAAK,CAAC;YACzB,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,iCAAiC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC9F,CAAC;QACH,CAAC;QAED,OAAO;YACL,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,MAAM,EAAE,EAAE,CAAC,MAAM;YACjB,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,MAAM,EAAE,IAAI;YACZ,KAAK;YACL,KAAK;YACL,QAAQ;YACR,cAAc;SACf,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,MAAsB;QAC3B,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACnB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;QAC1D,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;QAC7D,CAAC;QACD,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;YAC1B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QAClD,CAAC;QACD,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;QACnD,CAAC;QACD,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,IAAI,MAAM,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;YACpD,OAAO;gBACL,MAAM,EAAE,QAAQ;gBAChB,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,mBAAmB,MAAM,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE;aAChF,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YACrB,OAAO;gBACL,MAAM,EAAE,QAAQ;gBAChB,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,mBAAmB,MAAM,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE;aAC1E,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,EAAmB,EAAE,IAA+C;QAC/E,MAAM,UAAU,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QACvF,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3D,CAAC;QAED,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,IAAI,MAAM,GAAG,KAAK,CAAC;YACnB,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC/E,MAAM,GAAG,IAAI,CAAC;YAChB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,IAAI,GAAI,GAA0B,EAAE,IAAI,CAAC;gBAC/C,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;oBACf,OAAO,CAAC,IAAI,CAAC,4DAA4D,EAAE,CAAC,MAAM,MAAM,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC/G,CAAC;gBACD,MAAM,GAAG,KAAK,CAAC;YACjB,CAAC;YACD,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO,CAAC,IAAI,CAAC,sDAAsD,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;gBACjF,OAAO;YACT,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;YACzD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,IAAI,CAAC,2CAA2C,EAAE,CAAC,MAAM,MAAM,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC9F,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/hooks/ftown-antigravity-hook.sh

@@ -3,9 +3,11 @@
 # ~/.ftown/antigravity-hook.sh and registered in ~/.gemini/config/hooks.json.
 # Translates agy's camelCase hook payload (stdin) to the bridge /hook wire format and POSTs it.
 # On a turn-end Stop it drains this session's ftown inbox FIRST: with mail it
-# prints {"decision":"continue","reason":"<mail>"} and posts nothing (the agent
-# keeps working); without mail it posts Stop. On terminationReason
-# MAX_FORCED_INVOCATIONS / USER_CANCELED / ERROR it never drains, only posts Stop.
+# prints {"decision":"continue","reason":"<mail>"} (the agent keeps working) and
+# still POSTs Stop so the bridge clears the busy marker (the drain marks the
+# mail delivered, so that Stop finds an empty inbox); without mail it posts
+# Stop. On terminationReason MAX_FORCED_INVOCATIONS / USER_CANCELED / ERROR it
+# never drains, only posts Stop.
 #
 # Always exits 0, also on HUP/INT/TERM/PIPE (a non-zero or signalled PreToolUse
 # hook makes agy BLOCK the tool), and writes nothing to stdout except that one
@@ -15,7 +17,7 @@
 # Worst-case runtime: ~6s inside agy's 10s hook timeout. The POST tries at most
 # 2 endpoint candidates x curl --max-time 2 (4s); on Stop the inbox read through
 # `ftown security proxy` uses a 2s request timeout and happens before the POST,
-# and when it delivers mail no POST follows.
+# and the POST also follows when the drain delivers mail (busy-marker clear).
 #
 # bash 3.2 compatible (macOS /bin/bash). No set -e on purpose; no temp files.
 # The hook's working directory is agy's hooks.json folder, so pwd is never used.
@@ -160,9 +162,13 @@ drain_mail() {
 
 MAIL_OUT=""
 if drain_mail; then
-  # Mail delivered: the agent continues, so the session stays busy (no POST).
-  # stderr is silenced so a reader that closed the pipe cannot see "Broken pipe".
+  # Mail delivered: the agent continues on the decision line, but the Stop is
+  # still POSTed so the bridge clears the busy marker (this hook posts no other
+  # Stop while the mail turn runs). The decision line goes out first; the POST
+  # is fire-and-forget and silenced. stderr is silenced so a reader that closed
+  # the pipe cannot see "Broken pipe".
   printf '%s\n' "$MAIL_OUT" 2>/dev/null
+  post_hook "$PAYLOAD" >/dev/null 2>&1 || true
   exit 0
 fi
 post_hook "$PAYLOAD"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ftown",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "CLI bridge for ftown — generic PTY-over-Centrifugo relay",
   "type": "module",
   "main": "dist/index.js",
@@ -73,5 +73,5 @@
   "overrides": {
     "qs": "6.16.1"
   },
-  "gitHead": "033b06c892db214c1104779f68ef4f36e3c567f8"
+  "gitHead": "1fee3d0e20fd50368c0e0ac1774eb47c184149ce"
 }

package/skills/ftown/SKILL.md

@@ -53,6 +53,12 @@ ftown sessions preview --clear
 ftown sessions preview-reply --message "The preview is ready."
 ftown status set --state working --headline "Reviewing the API client" --progress 0/1
 ftown board
+ftown plan
+ftown plan add "Review the API client" --after p1 --priority 1
+ftown sessions create --parent --plan-item p2 --prompt "Review the API client"
+ftown brief set --file brief.md
+ftown attention list
+ftown worktrees list
 ftown harness mail send <session-id> --type task "review the API client"
 ftown harness mail read
 ftown env --help
@@ -125,6 +131,60 @@ ftown board --wait --until any-done --timeout 300
 ftown events --wait
 ```
 
+Plain `ftown board` appends a `planned` section with up to 5 ready plan
+items (`→ <id> <title>`, then `+N more`). `ftown board --all` also shows
+retired (archived) children after the live ones, suffixed `(retired)`.
+Tree events include the `plan` kind for plan changes and `removed` when a
+child is removed or archived while not already exited.
+
+## Plan list
+
+Keep the plan on the manager: `ftown plan` defaults to your own session
+(`$FTOWN_SESSION_ID`, the manager), and `--session-id <id>` targets another
+session's plan. This is the manager's plan, not a ticket system — it is a
+short ordered todo list the manager keeps for its own coordination. Add
+items, order them with precedence, and link each child to one item:
+
+```bash
+ftown plan [--json] [--session-id <id>]
+ftown plan add <title...> [--note <t>] [--after <id,id>] [--priority 1|2|3]
+ftown plan start <id> --session <child-id>
+ftown plan done <id>
+ftown plan drop <id>
+ftown plan todo <id>
+ftown plan edit <id> [--title <t>] [--note <t>|--no-note] [--after <ids>|--no-after] [--priority n]
+ftown plan rm <id>
+ftown sessions create --parent --plan-item <id> --prompt "<task>"
+```
+
+Precedence comes from `--after <id,id>` and `--priority 1|2|3` (1 is
+highest). An item is ready when it is `todo` and every item in its `after`
+list is `done` or `dropped`; the list shows `→` ready, `·` waiting, `▸`
+started, `✓` done and `✗` dropped. Creating a child with `--plan-item <id>`
+requires a parent, fails before creating anything when the item is unknown
+or not `todo`, and otherwise marks the item `started` with that child
+linked. When the linked child's card becomes `done`, its item becomes
+`done` too; a `failed` card leaves the item `started` for the manager to
+decide. `ftown plan start <id> --session <child-id>` links an existing
+child by hand, and `done`/`drop`/`todo` set the state directly. Every plan
+change emits one `plan` tree event (`<id> <state>: <title>`, plus
+` → ready: …` when items become ready). Exit codes: 0 ok, 1 error, 2 usage.
+
+**Delegating work.** Delegate implementation to ftown child sessions (`ftown sessions create --parent ...`) rather than in-process subagents — only sessions appear on the board and dashboard (cards, events, digests, parent-first questions).
+A child session may use its own subagents for reviews and lookups. Pick the CLI and model with `ftown quota --json` (see `references/quota.md`).
+
+## Manager brief
+
+If you coordinate children, set a brief at the start and add a note at each
+milestone. The dashboard overview renders the brief and your children
+automatically; you do not build a status page yourself.
+
+```bash
+ftown brief set --file brief.md
+ftown brief note "All workers spawned; waiting on the first results"
+ftown brief show
+```
+
 ## Human attention and pull requests
 
 Use `ftown sessions attention --message "..."` when you need human input. It
@@ -134,6 +194,18 @@ remains opt-in and requires a supported hosted session. Repeating an unresolved
 request updates its occurrence count; after an uncertain result, inspect the
 existing request before retrying.
 
+If you have a parent, your request goes to your parent first, not the human:
+the parent receives one waking escalation mail with the question and the
+commands to answer or escalate it, and the human sees it greyed as "with
+parent" (and may still answer). The parent answers with
+`ftown attention answer <child-id> <event-id> --option <n>` (or
+`--text "<reply>"`) only from facts it holds — the plan, the agreed contract,
+earlier human answers — and escalates preferences and irreversible choices
+with `ftown attention escalate <child-id> <event-id> --note "<context>"`.
+Only the parent raises a parent-routed question to the human. Use
+`ftown sessions attention ... --to human` for things only the human can
+provide, such as credentials or approvals.
+
 ### Questions with answers
 
 Add `--option <label>` (repeatable) to ask a question the human answers in the
@@ -145,7 +217,8 @@ not cancel the question; check later with
 event ID.
 
 Delivery: a live waiter receives the answer; otherwise it arrives as ftown mail
-from "You" starting with `[ftown attention answer id=...]`.
+from "You" starting with `[ftown attention answer id=...]`. When the parent
+answers, the same delivery applies but the mail sender is the parent session.
 
 Claude Code `AskUserQuestion` calls inside an FTown session are answered from
 the same inbox, and the terminal picker appears only after "Answer in terminal"
@@ -176,12 +249,14 @@ created or updated, before the completion notice: use `ftown sessions pr <URL>`.
 Omit this step for tasks without a PR; never invent a PR or guess a session
 identity.
 
-Once the task is complete, request user attention **once per completed task**,
-before the final handoff, using `ftown sessions attention --title 'Work complete'
+Once the task is complete, a top-level session requests user attention **once
+per completed task**, before the final handoff, using
+`ftown sessions attention --title 'Work complete'
 --message "<truthful outcome, checks and PR summary>"`.
 Do not send a completion notice every turn; retain the uncertain-result guidance
-above. Children must still report their result to the parent as assigned; user
-attention does not replace that reporting. See the completion example in
+above. If you have a parent, do not raise "Work complete": set your card to
+`done` and report your result to the parent as assigned; the parent raises one
+completion notice for the whole job. See the completion example in
 `references/sessions.md`.
 
 ## Cleanup
@@ -199,6 +274,14 @@ ftown sessions revive <archived-session-id>
 Removal archives the session; revival creates a new session id and resumes its
 agent conversation when supported. Preserve useful results before cleanup.
 
+For children that write code, create them with their own worktree:
+`ftown sessions create --parent --worktree [--branch <b>] [--base <ref>]`.
+`ftown sessions remove <id>` retires a bridge-created worktree when it is
+clean and merged or pushed; otherwise it keeps the worktree and says why.
+`--keep-worktree` always keeps it, `--force-worktree` forces removal.
+Inspect or clean up archived worktrees with `ftown worktrees list` and
+`ftown worktrees prune`.
+
 ## Connection and compatibility
 
 The commands read `~/.ftown/bridge.json`. Anyone who can read that file can

package/skills/ftown/references/orchestrator.md

@@ -1,40 +1,43 @@
 # Worker coordination examples
 
-Read `../SKILL.md` for identity, reporting and cleanup behavior, and
-`sessions.md` for the command reference. These examples add only coordination
-steps. Use an ordinary session with the requested task and parent link; no
-special orchestrator mode is needed.
+Read `../SKILL.md` for identity, reporting and cleanup, and
+`sessions.md` for the command reference. No special orchestrator mode is needed.
 
 List existing sessions before creating another worker. Give each worker a
-bounded task, clear writable files and acceptance checks; save the returned
-`session.id` for follow-up. Omit `--shell` to inherit your current harness, or
-set it when the task calls for a different harness. Provider flavors require a
-bridge-host token configured with `ftown env set <flavor>`.
+bounded task, clear writable files and checks; save the returned
+`session.id`. Omit `--shell` to inherit your harness. Before picking a CLI,
+model and effort, run `ftown quota --json` and follow `quota.md` (owner
+tiers first); never route to `exhausted`.
 
-Before picking a CLI, model and effort for delegated work, run `ftown quota --json`
-and follow the decision procedure in `quota.md` (owner tiers first). Pass the
-choice as `--shell <provider>`; add `--model <id>` only with an id from that
-harness's model list. Never route to `exhausted`.
+Keep the plan on the manager — the manager's plan, not a ticket system.
+Add steps with `ftown plan add` (`--after`/`--priority` set precedence;
+ready = every `after` done or dropped) and create each child with
+`--plan-item`, so its item starts and completes with the child:
 
 ```bash
-ftown sessions list
-ftown sessions create --parent --workdir /path/to/repo --name review-auth \
-  --prompt "Review auth; read-only. Report concrete findings and validation."
+ftown brief set --file brief.md
+ftown plan add "Fix the auth bug" --priority 1
+ftown sessions create --parent --plan-item p1 --worktree --workdir /path/to/repo --name fix-auth --prompt "Fix auth; run checks."
 ftown board --wait --until any-done --timeout 300
-ftown board
-ftown harness mail send <worker-id> --type task "Check the expired-token case too"
+ftown attention list
+ftown harness mail send <worker-id> --type task "Check the expired-token case"
 ```
 
-Coordinate in a loop: spawn children, wait with
-`ftown board --wait --until any-done --timeout 300` (or `any-blocked`,
-`any-ready`, `all-done`; `ftown events --wait` waits for the next event), act
-on the board and mail, then repeat until every child is done. Children keep
-their cards current; progress goes on the card, never as mail. Use
-`ftown sessions screen <worker-id> --limit 100` only to investigate terminal
-detail. Mail handles directed instructions, results and escalations; read it
-with `ftown harness mail read`. Each new batch nudges the recipient at most
-once, and a nudge may append a one-line digest of child status. Parallel tasks
-need disjoint write ownership and serialized shared resources.
+Loop: keep the plan on the manager, create children with `--plan-item`,
+`ftown board --wait --until any-done` (or `any-blocked`/`any-ready`/
+`all-done`), act, repeat until all are done. Children keep cards current;
+progress goes on the card, never as mail. A child's question comes to you
+first: answer from facts you hold with `ftown attention answer`, or
+escalate preferences and irreversible choices
+with `ftown attention escalate --note`. Mail is for directed
+instructions, results and escalations; read it with
+`ftown harness mail read`. Each mail batch nudges at most once (a digest
+may be appended). Use `ftown sessions screen <worker-id> --limit 100`
+only to investigate. Parallel tasks need disjoint write
+ownership and serialized shared resources. Children set their card to
+done and report to the parent; you raise one "Work complete" notice
+for the whole job.
 
-After accepting a worker's result, request any concrete follow-up before
-explicit cleanup with `ftown sessions remove <worker-id>`.
+After accepting a result, clean up with
+`ftown sessions remove <worker-id>`, which retires a clean, merged or pushed
+worktree and otherwise keeps it and says why.