@astrosheep/square 0.3.4 → 0.3.6

package/dist/square.js

@@ -1,1366 +1,9 @@
 #!/usr/bin/env node
-// square.ts — multi-agent brainstorming through a shared file
-import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { SquareError, formatHardCap, parseParticipantList, sameName, validateParticipantName, } from './model.js';
-import { commandPrefix, participantCommandPrefix, quoteShell, renderActivitiesView, renderGrepActivitiesView, renderDoctorClean, renderDoctorProblems, renderDoctorRepaired, renderDoctorUnfixable, renderEventCli, renderVisibleEvent, withJoinNextOutput, renderPublicTail, withPathOutput, } from './presentation.js';
-import { formatRelativeTime, formatTimestamp, parseTimeOrRelative } from './time.js';
-import { cmdListSquares } from './list.js';
-import { cmdActivity } from './activity.js';
-import { cmdCompact } from './compact.js';
-import { cmdWatch } from './watch.js';
-import { cmdStream, cmdStreamNdjson } from './stream.js';
-import { diagnoseSquare, loadSquare, renderSquare, saveRuntimeSidecar, emptyRuntimeState } from './artifact.js';
-import { doctorDeliveryHealth, findStalePendingMentions, reconcileDeliveryBacklog, } from './delivery-health.js';
-import { dispatchActNotifications } from './notifications.js';
-import { hasAutomaticDeliveryIdentity, recordLocalJoin, recordLocalDone } from './registry.js';
-import { sessionInbox } from './inbox.js';
-import { runClaudeHook, runCodexHook } from './claude-hook.js';
-import { doctorCodexPlugin, installClaudePlugin, installCodexPlugin, uninstallCodexPlugin, } from './harness.js';
-import { actId, appendAct, inSquareCount, isCurrentlyJoined, nowMs, resolveRosterName, sayNumberFor, withSquareLock, writeSquareDoc } from './runtime.js';
-import { planRepair } from './doctor.js';
-import { commandUsageHint, helpRequest as parseHelpRequest, renderGlobalHelp, renderSubcommandHelp as renderScopedHelp, } from './help.js';
-import { decideJoin, coreDone, coreHold, coreResume, coreStatus, coreParticipants, coreActivities, } from './decisions.js';
-const DEFAULT_SQUARE_PATH = '.square/SQUARE.md';
-function readStdinSync() {
-    try {
-        return fs.readFileSync(0, 'utf8');
-    }
-    catch {
-        return '';
-    }
-}
-function resolveBody(arg) {
-    return arg === '-' ? readStdinSync() : arg;
-}
-// When no body argument is given and stdin is piped (not a TTY), read it to EOF
-// and use it as the body if non-empty. Returns undefined if stdin is a TTY or
-// the piped content is blank, so callers fall back to their "missing body" path.
-function readPipedBodyFallback() {
-    if (process.stdin.isTTY)
-        return undefined;
-    const content = readStdinSync();
-    return content.trim() === '' ? undefined : content;
-}
-function requireValue(args, index, flag) {
-    const value = args[index + 1];
-    if (value === undefined || value.startsWith('--')) {
-        process.stderr.write(`Missing value for ${flag}.\n`);
-        process.exit(2);
-    }
-    return value;
-}
-function parseDurationMs(value, flag) {
-    const match = value.match(/^([1-9]\d*)(ms|s|m|h)$/);
-    if (!match) {
-        process.stderr.write(`Invalid ${flag}: expected a positive duration with unit ms, s, m, or h (for example 500ms, 30s, 3m, 1h).\n`);
-        process.exit(2);
-    }
-    const amount = parseInt(match[1], 10);
-    const unit = match[2];
-    const multipliers = { ms: 1, s: 1000, m: 60000, h: 3600000 };
-    const ms = amount * multipliers[unit];
-    if (!Number.isSafeInteger(ms)) {
-        process.stderr.write(`Invalid ${flag}: duration is too large.\n`);
-        process.exit(2);
-    }
-    return ms;
-}
-function parsePositiveIntegerOption(value, flag) {
-    if (!/^[1-9]\d*$/.test(value)) {
-        process.stderr.write(`Invalid ${flag}: expected a positive integer.\n`);
-        process.exit(2);
-    }
-    const parsed = Number(value);
-    if (!Number.isSafeInteger(parsed)) {
-        process.stderr.write(`Invalid ${flag}: value is too large.\n`);
-        process.exit(2);
-    }
-    return parsed;
-}
-function parseNonNegativeIntegerOption(value, flag) {
-    if (!/^\d+$/.test(value)) {
-        process.stderr.write(`Invalid ${flag}: expected a non-negative integer.\n`);
-        process.exit(2);
-    }
-    const parsed = Number(value);
-    if (!Number.isSafeInteger(parsed)) {
-        process.stderr.write(`Invalid ${flag}: value is too large.\n`);
-        process.exit(2);
-    }
-    return parsed;
-}
-function parseHardCap(value) {
-    if (value === '-1')
-        return null;
-    const hardCap = parseInt(value, 10);
-    if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(hardCap)) {
-        process.stderr.write('Invalid build option: --cap must be a positive integer or -1.\n');
-        process.exit(2);
-    }
-    return hardCap;
-}
-function parseNameListOption(value, flag) {
-    const names = parseParticipantList(value);
-    if (names.length === 0) {
-        process.stderr.write(`Invalid ${flag}: expected at least one participant name.\n`);
-        process.exit(2);
-    }
-    for (const name of names)
-        validateParticipantName(name);
-    return names;
-}
-function requireNameFlag(name) {
-    if (!name) {
-        process.stderr.write('Missing required option: --as <name>.\n');
-        process.exit(2);
-    }
-    validateParticipantName(name);
-    return name;
-}
-function resolveDefaultSquarePath() {
-    const dir = path.join(process.cwd(), '.square');
-    let entries;
-    try {
-        entries = fs.readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return { path: DEFAULT_SQUARE_PATH, multiple: false };
-    }
-    const candidates = [];
-    for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.endsWith('.md'))
-            continue;
-        const fullPath = path.join(dir, entry.name);
-        let at;
-        try {
-            const doc = loadSquare(fullPath);
-            const latestAct = doc.acts.at(-1);
-            at = latestAct?.at ?? fs.statSync(fullPath).mtimeMs;
-        }
-        catch {
-            continue;
-        }
-        candidates.push({ relPath: path.relative(process.cwd(), fullPath), at });
-    }
-    candidates.sort((a, b) => b.at - a.at);
-    return { path: candidates[0]?.relPath ?? DEFAULT_SQUARE_PATH, multiple: candidates.length > 1 };
-}
-function parseGlobalArgs(rawArgs) {
-    const args = [...rawArgs];
-    let squarePath;
-    let name;
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === '--square-path') {
-            squarePath = requireValue(args, i, args[i]);
-            args.splice(i, 2);
-            i -= 1;
-        }
-        else if (args[i] === '--as') {
-            name = requireValue(args, i, args[i]);
-            args.splice(i, 2);
-            i -= 1;
-        }
-    }
-    if (name !== undefined)
-        validateParticipantName(name);
-    const explicitSquarePath = squarePath !== undefined;
-    const command = args[0];
-    const needsDefaultSquare = !explicitSquarePath && command !== 'ls' && command !== 'list' && command !== 'version';
-    const resolved = needsDefaultSquare
-        ? resolveDefaultSquarePath()
-        : { path: squarePath ?? DEFAULT_SQUARE_PATH, multiple: false };
-    return {
-        squarePath: resolved.path,
-        explicitSquarePath,
-        multipleSquares: resolved.multiple,
-        name,
-        args,
-    };
-}
-function parseBuildOptions(args) {
-    const opts = {
-        force: false,
-    };
-    for (let i = 0; i < args.length; i++) {
-        const flag = args[i];
-        switch (flag) {
-            case '--cap':
-                opts.hardCap = parseHardCap(requireValue(args, i, flag));
-                i++;
-                break;
-            case '--template':
-                opts.template = requireValue(args, i, flag);
-                i++;
-                break;
-            case '--throttle':
-            case '--throttle-per-minute':
-                opts.throttlePerMinute = parsePositiveIntegerOption(requireValue(args, i, flag), flag);
-                i++;
-                break;
-            case '--force':
-            case '-f':
-                opts.force = true;
-                break;
-            default:
-                process.stderr.write(`Unknown build option: ${flag}\n`);
-                process.exit(2);
-        }
-    }
-    if (opts.template && !/^[a-zA-Z0-9-]+$/.test(opts.template)) {
-        process.stderr.write('Invalid template name: only letters, digits, and hyphens allowed.\n');
-        process.exit(2);
-    }
-    if (opts.hardCap === undefined) {
-        process.stderr.write('Missing required build option: --cap must be a positive integer or -1.\n');
-        process.exit(2);
-    }
-    if (opts.throttlePerMinute !== undefined &&
-        (!Number.isInteger(opts.throttlePerMinute) || opts.throttlePerMinute <= 0)) {
-        process.stderr.write('Invalid build option: --throttle must be a positive integer.\n');
-        process.exit(2);
-    }
-    return opts;
-}
-async function cmdBuild(squarePath, args) {
-    const opts = parseBuildOptions(args);
-    const snippet = readStdinSync();
-    if (snippet.trim() === '') {
-        process.stderr.write('Missing Markdown body snippet on stdin.\n');
-        process.exit(2);
-    }
-    try {
-        fs.mkdirSync(path.dirname(squarePath), { recursive: true });
-        await withSquareLock(squarePath, () => {
-            if (fs.existsSync(squarePath) && !opts.force) {
-                throw new SquareError('conflict', `Refusing to overwrite existing square: ${squarePath}\nPass -f to overwrite.`);
-            }
-            fs.writeFileSync(squarePath, renderSquare(opts, snippet));
-            saveRuntimeSidecar(squarePath, emptyRuntimeState(0));
-        });
-        const capText = formatHardCap(opts.hardCap) === '-1' ? 'unlimited' : formatHardCap(opts.hardCap);
-        const throttleText = opts.throttlePerMinute !== undefined ? `throttle ${opts.throttlePerMinute}/min` : '';
-        const summary = ['✓ built', `  · cap ${capText}`, ...(throttleText ? [`  · ${throttleText.trim()}`] : []), '  · participants (none seeded — first join adds names)'].join('\n');
-        process.stdout.write(withPathOutput(squarePath, summary, { participantCount: 0 }));
-    }
-    catch (err) {
-        if (err instanceof SquareError) {
-            process.stderr.write(err.message + '\n');
-            process.exit(2);
-        }
-        throw err;
-    }
-}
-function parseJoinOptions(args) {
-    let lastN = 10;
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === '--last') {
-            lastN = parsePositiveIntegerOption(requireValue(args, i, args[i]), args[i]);
-            i++;
-        }
-        else if (args[i] === '--all') {
-            lastN = null;
-        }
-        else {
-            usage();
-        }
-    }
-    return { lastN };
-}
-async function cmdJoin(squarePath, name, opts = { lastN: 10 }) {
-    validateParticipantName(name);
-    try {
-        let joinedName;
-        let context;
-        let allActs;
-        let isRejoin;
-        let sent;
-        await withSquareLock(squarePath, () => {
-            const doc = loadSquare(squarePath);
-            const decision = decideJoin(doc, name, nowMs());
-            joinedName = decision.joinedName;
-            isRejoin = doc.acts.some((e) => e.kind === 'join' && e.actor === decision.joinedName);
-            const appended = appendAct(squarePath, doc, decision.joinAct);
-            sent = { act: appended, index: appended.index };
-            context = doc.preamble.at(-1) === '---' ? doc.preamble.slice(0, -1) : doc.preamble;
-            allActs = doc.acts;
-        });
-        if (sent)
-            await dispatchActNotifications(squarePath, sent);
-        recordLocalJoin(joinedName, squarePath);
-        const now = nowMs();
-        const activities = renderPublicTail(allActs, opts.lastN, now, joinedName);
-        const contextText = context.join('\n').trim();
-        const fallbackCatch = hasAutomaticDeliveryIdentity()
-            ? []
-            : [
-                '',
-                `» ${participantCommandPrefix(squarePath, joinedName)} catch --idle 30m`,
-                '  no session delivery detected — keep this catch open for new activity',
-            ];
-        const out = [
-            `● ${joinedName} stepped into the square`,
-            ...(isRejoin || contextText === '' ? [] : ['', 'context', contextText]),
-            ...(activities === '' ? [] : ['', 'recent activity', activities]),
-            ...(isRejoin ? [] : ['', `» ${participantCommandPrefix(squarePath, joinedName)} warmup`]),
-            ...fallbackCatch,
-        ].join('\n');
-        process.stdout.write(withJoinNextOutput(squarePath, out, { participantCount: inSquareCount(loadSquare(squarePath)) }));
-    }
-    catch (err) {
-        if (err instanceof SquareError && err.code === 'conflict') {
-            const doc = loadSquare(squarePath);
-            const joinedName = resolveRosterName(doc, name);
-            if (joinedName === undefined || !isCurrentlyJoined(doc.acts, joinedName))
-                throw err;
-            recordLocalJoin(joinedName, squarePath);
-            const fallbackCatch = hasAutomaticDeliveryIdentity()
-                ? ''
-                : `\n» ${participantCommandPrefix(squarePath, joinedName)} catch --idle 30m\n  no session delivery detected — keep this catch open for new activity`;
-            process.stdout.write(withJoinNextOutput(squarePath, `● ${joinedName} is already in the square${fallbackCatch}`, {
-                participantCount: inSquareCount(doc),
-            }));
-            return;
-        }
-        handleSquareError(err);
-    }
-}
-function parseActOptions(args) {
-    let force = false;
-    let noWait = false;
-    let beside;
-    let bell = false;
-    const activityArgs = [];
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg === '-f' || arg === '--force') {
-            force = true;
-        }
-        else if (arg === '--no-wait') {
-            noWait = true;
-        }
-        else if (arg === '--beside') {
-            beside = requireValue(args, i, arg);
-            i++;
-        }
-        else if (arg === '--bell') {
-            bell = true;
-        }
-        else {
-            activityArgs.push(arg);
-        }
-    }
-    if (bell && beside !== undefined) {
-        process.stderr.write('Invalid act options: --beside and --bell are mutually exclusive.\n');
-        process.exit(2);
-    }
-    const reach = bell ? 'bell' : beside !== undefined ? { beside } : undefined;
-    if (activityArgs.length !== 1) {
-        if (activityArgs.length === 0) {
-            const piped = readPipedBodyFallback();
-            if (piped !== undefined) {
-                return { activity: piped, force, noWait, reach };
-            }
-        }
-        process.stderr.write("act requires a body argument (a quoted string or '-' with piped stdin)\n");
-        process.exit(2);
-    }
-    return { activity: activityArgs[0], force, noWait, reach };
-}
-function forceActCommand(squarePath, name, reach) {
-    const reachArg = reach === 'bell' ? ' --bell' : reach !== undefined ? ` --beside ${quoteShell(reach.beside)}` : '';
-    return `${participantCommandPrefix(squarePath, name)} act --force${reachArg} -`;
-}
-function parseDoneOptions(args) {
-    if (args.length > 1)
-        usage();
-    if (args.length === 1)
-        return args[0];
-    return readPipedBodyFallback();
-}
-async function cmdDone(squarePath, name, final) {
-    const body = String(resolveBody(final ?? '') ?? '').replace(/\r\n/g, '\n').trim();
-    try {
-        let resolvedName;
-        let sent;
-        await withSquareLock(squarePath, () => {
-            const doc = loadSquare(squarePath);
-            const act = coreDone(doc, name, body, nowMs());
-            resolvedName = act.actor;
-            const appended = appendAct(squarePath, doc, act);
-            sent = { act: appended, index: appended.index };
-        });
-        if (sent)
-            await dispatchActNotifications(squarePath, sent);
-        recordLocalDone(resolvedName, squarePath);
-        const doc = loadSquare(squarePath);
-        process.stdout.write(withPathOutput(squarePath, `× ${resolvedName} steps out of the square — done · just now`, { participantCount: inSquareCount(doc) }));
-    }
-    catch (err) {
-        handleSquareError(err);
-    }
-}
-async function cmdHold(squarePath, actor, reason) {
-    const body = String(resolveBody(reason ?? '') ?? '').replace(/\r\n/g, '\n').trim();
-    try {
-        let confirmation;
-        let sent;
-        await withSquareLock(squarePath, () => {
-            const doc = loadSquare(squarePath);
-            const appended = appendAct(squarePath, doc, coreHold(doc, actor, body, nowMs()));
-            sent = { act: appended, index: appended.index };
-            confirmation = renderEventCli(appended);
-        });
-        if (sent)
-            await dispatchActNotifications(squarePath, sent);
-        const doc = loadSquare(squarePath);
-        process.stdout.write(withPathOutput(squarePath, confirmation, { participantCount: inSquareCount(doc), held: true }));
-    }
-    catch (err) {
-        handleSquareError(err);
-    }
-}
-async function cmdResume(squarePath, actor) {
-    try {
-        let confirmation;
-        let sent;
-        await withSquareLock(squarePath, () => {
-            const doc = loadSquare(squarePath);
-            const appended = appendAct(squarePath, doc, coreResume(doc, actor, nowMs()));
-            sent = { act: appended, index: appended.index };
-            confirmation = renderEventCli(appended);
-        });
-        if (sent)
-            await dispatchActNotifications(squarePath, sent);
-        const doc = loadSquare(squarePath);
-        process.stdout.write(withPathOutput(squarePath, confirmation, { participantCount: inSquareCount(doc) }));
-    }
-    catch (err) {
-        handleSquareError(err);
-    }
-}
-function parseHarnessInstallOptions(args) {
-    let force = false;
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === '-f' || args[i] === '--force') {
-            force = true;
-        }
-        else {
-            usage();
-        }
-    }
-    return { force };
-}
-function lstatMaybe(target) {
-    try {
-        return fs.lstatSync(target);
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return null;
-        throw error;
-    }
-}
-const HARNESS_SKILL_NAMES = ['square', 'brainstorm'];
-function skillLinksFor(root, homeDir = os.homedir()) {
-    return HARNESS_SKILL_NAMES.map((name) => ({
-        source: fileURLToPath(new URL(`../skills/${name}/`, import.meta.url)),
-        target: path.join(homeDir, root, 'skills', name),
-        kind: 'skill',
-    }));
-}
-function skillLinks(homeDir = os.homedir()) {
-    return [...skillLinksFor('.claude', homeDir), ...skillLinksFor('.agents', homeDir)];
-}
-function piExtensionLink(homeDir = os.homedir()) {
-    return {
-        source: fileURLToPath(new URL('../extensions/square-pi.js', import.meta.url)),
-        target: path.join(homeDir, '.pi', 'agent', 'extensions', 'square.js'),
-        kind: 'extension',
-    };
-}
-function opencodeExtensionLink(homeDir = os.homedir()) {
-    const configHome = process.env['XDG_CONFIG_HOME']?.trim() || path.join(homeDir, '.config');
-    return {
-        source: fileURLToPath(new URL('../extensions/square-opencode.js', import.meta.url)),
-        target: path.join(configHome, 'opencode', 'plugins', 'square.js'),
-        kind: 'extension',
-    };
-}
-function doctorOpenCode(homeDir = os.homedir()) {
-    const extension = opencodeExtensionLink(homeDir);
-    let linked = false;
-    try {
-        linked = fs.realpathSync(extension.target) === fs.realpathSync(extension.source);
-    }
-    catch { }
-    const skill = path.join(homeDir, '.agents', 'skills', 'square', 'SKILL.md');
-    const lines = [
-        linked ? `✓ OpenCode Square plugin ${extension.target}` : `✕ OpenCode Square plugin missing ${extension.target}`,
-        fs.existsSync(skill) ? `✓ OpenCode Square skill ${skill}` : `✕ OpenCode Square skill missing ${skill}`,
-    ];
-    if (!linked)
-        return lines;
-    const runtime = spawnSync(process.env['SQUARE_OPENCODE_BIN'] || 'opencode', ['debug', 'config'], {
-        encoding: 'utf8',
-        env: { ...process.env, HOME: homeDir },
-        maxBuffer: 4 * 1024 * 1024,
-        timeout: 30_000,
-    });
-    try {
-        const config = JSON.parse(runtime.stdout || '');
-        const expected = pathToFileURL(extension.target).href;
-        lines.push(runtime.status === 0 && config.plugin?.includes(expected)
-            ? '✓ OpenCode loaded the Square plugin'
-            : '✕ OpenCode did not load the Square plugin');
-    }
-    catch {
-        lines.push(`✕ OpenCode plugin runtime unavailable${runtime.stderr?.trim() ? ` (${runtime.stderr.trim()})` : ''}`);
-    }
-    return lines;
-}
-function installLinks(links, force) {
-    const existing = links.filter(({ target }) => lstatMaybe(target) !== null);
-    if (existing.length > 0 && !force) {
-        for (const { target, kind } of existing) {
-            process.stderr.write(`Refusing to overwrite existing ${kind} link: ${target}\n`);
-        }
-        process.stderr.write('Pass -f to replace it.\n');
-        process.exit(1);
-    }
-    for (const { source, target } of links) {
-        fs.mkdirSync(path.dirname(target), { recursive: true });
-        if (lstatMaybe(target) !== null)
-            fs.rmSync(target, { recursive: true, force: true });
-        const symlinkType = os.platform() === 'win32' && fs.statSync(source).isDirectory() ? 'junction' : 'file';
-        fs.symlinkSync(source, target, symlinkType);
-    }
-    return links.map(({ target }) => target);
-}
-async function cmdHarness(args, squarePath) {
-    const action = args[0];
-    if (action !== 'install' && action !== 'uninstall' && action !== 'doctor')
-        usage();
-    const rest = args.slice(1);
-    const target = rest.find((arg) => !arg.startsWith('-'));
-    const force = rest.includes('-f') || rest.includes('--force');
-    if (action === 'doctor') {
-        if (target && target !== 'codex' && target !== 'opencode' && target !== 'delivery')
-            usage();
-        const lines = [];
-        if (!target || target === 'codex')
-            lines.push(...(await doctorCodexPlugin(os.homedir())));
-        if (!target || target === 'opencode')
-            lines.push(...doctorOpenCode(os.homedir()));
-        if (!target || target === 'delivery') {
-            if (squarePath) {
-                try {
-                    lines.push(...doctorDeliveryHealth(squarePath));
-                }
-                catch {
-                    lines.push(`○ delivery health skipped (unreadable square at ${squarePath})`);
-                }
-            }
-            else {
-                lines.push('○ delivery health skipped (no square path)');
-            }
-        }
-        process.stdout.write(lines.join('\n') + '\n');
-        return;
-    }
-    if (!target) {
-        process.stderr.write('harness install/uninstall requires an explicit target: skills | claude | codex | opencode | pi\n');
-        process.exit(2);
-    }
-    if (action === 'uninstall') {
-        if (target !== 'codex') {
-            process.stderr.write(`harness uninstall currently supports only codex (got ${target})\n`);
-            process.exit(2);
-        }
-        const result = uninstallCodexPlugin(os.homedir());
-        for (const note of result.notes)
-            process.stderr.write(`${note}\n`);
-        process.stdout.write(result.paths.join('\n') + '\n');
-        return;
-    }
-    if (target === 'skills') {
-        process.stdout.write(installLinks(skillLinks(), force).join('\n') + '\n');
-        return;
-    }
-    if (target === 'claude') {
-        const claude = installClaudePlugin(os.homedir());
-        process.stdout.write(`${claude.marketplaceRoot}\n${claude.pluginRoot}\n`);
-        return;
-    }
-    if (target === 'pi') {
-        process.stdout.write(installLinks([piExtensionLink()], force).join('\n') + '\n');
-        return;
-    }
-    if (target === 'opencode') {
-        process.stdout.write(installLinks([opencodeExtensionLink(), ...skillLinksFor('.agents')], force).join('\n') + '\n');
-        return;
-    }
-    if (target === 'codex') {
-        const codex = await installCodexPlugin(os.homedir());
-        for (const note of codex.notes)
-            process.stderr.write(`${note}\n`);
-        process.stdout.write([codex.configPath, codex.marketplaceRoot, codex.pluginRoot, codex.installedPath]
-            .filter((item) => item !== undefined)
-            .join('\n') + '\n');
-        return;
-    }
-    usage();
-}
-function handleSquareError(err) {
-    if (err instanceof SquareError) {
-        process.stderr.write(err.message + '\n');
-        process.exit(err.code === 'not_found' ? 1 : 2);
-    }
-    throw err;
-}
-function cmdWarmup(squarePath) {
-    try {
-        const doc = loadSquare(squarePath);
-        process.stdout.write(withPathOutput(squarePath, doc.warmup.join('\n'), { participantCount: inSquareCount(doc) }));
-    }
-    catch (err) {
-        handleSquareError(err);
-    }
-}
-function cmdStatus(squarePath, viewer) {
-    try {
-        const doc = loadSquare(squarePath);
-        const result = coreStatus(doc, nowMs());
-        const { now } = result;
-        const activeParticipants = result.participants
-            .filter((participant) => participant.state === 'active')
-            .sort((a, b) => {
-            if (viewer !== undefined) {
-                const aIsViewer = sameName(a.name, viewer);
-                const bIsViewer = sameName(b.name, viewer);
-                if (aIsViewer !== bIsViewer)
-                    return aIsViewer ? -1 : 1;
-            }
-            return (b.lastActiveAt ?? -Infinity) - (a.lastActiveAt ?? -Infinity) || a.name.localeCompare(b.name);
-        });
-        const participantLines = activeParticipants.length === 0
-            ? ['  ○ nobody in the square']
-            : activeParticipants.map((p) => {
-                const glyph = p.presence === 'watching' ? '◎' : p.activityCount > 0 ? '●' : '○';
-                const summary = p.activityCount > 0
-                    ? `${p.activityCount} act${p.activityCount === 1 ? '' : 's'} · ${p.lastActiveAt === undefined ? 'just now' : formatRelativeTime(p.lastActiveAt, now)}`
-                    : `quiet · ${p.lastActiveAt === undefined ? '—' : formatRelativeTime(p.lastActiveAt, now)}`;
-                const isViewer = viewer !== undefined && sameName(p.name, viewer);
-                const showAttention = viewer === undefined || isViewer;
-                const attention = !showAttention
-                    ? ''
-                    : p.pendingMentionCount > 0
-                        ? `${p.pendingMentionCount} mention${p.pendingMentionCount === 1 ? '' : 's'} waiting`
-                        : p.unreadActivityCount > 0
-                            ? `${p.unreadActivityCount} change${p.unreadActivityCount === 1 ? '' : 's'} waiting`
-                            : 'caught up';
-                return `  ${glyph} ${p.name} · ${summary}${attention === '' ? '' : ` · ${attention}`}`;
-            });
-        const capText = formatHardCap(result.hardCap) === '-1' ? 'unlimited' : formatHardCap(result.hardCap);
-        const holdText = result.holdActive
-            ? `· ${result.holdActor ?? 'someone'} raised a hand${result.holdReason ? ` — ${result.holdReason}` : ''} · ${result.holdAt === undefined ? 'just now' : formatRelativeTime(result.holdAt, now)}`
-            : undefined;
-        const counts = `${result.activeCount} active · ${result.doneCount} done · cap ${capText} · throttle ${result.throttlePerMinute === undefined ? 'none' : `${result.throttlePerMinute}/min`}`;
-        const latestRendered = result.latestAct === undefined
-            ? ''
-            : renderVisibleEvent(doc.acts, result.latestAct, viewer ?? '', {
-                now,
-                preview: 200,
-                actNumber: result.latestAct.kind === 'say' ? sayNumberFor(doc.acts, result.latestAct) : undefined,
-            });
-        const latestLines = latestRendered === ''
-            ? [result.latestAct === undefined ? '  ○ no public activity yet' : '  · latest activity is private to another participant']
-            : [`  ${latestRendered.replace(/\n/g, '\n  ')}`];
-        if (latestRendered.includes('more chars') && result.latestAct !== undefined) {
-            const readPrefix = viewer === undefined ? commandPrefix(squarePath) : participantCommandPrefix(squarePath, viewer);
-            latestLines.push(`» ${readPrefix} echo --at ${actId(result.latestAct)} -C 2 --full`);
-        }
-        const out = [
-            counts,
-            ...(holdText ? ['', holdText] : []),
-            '',
-            'around the square',
-            ...participantLines,
-            '',
-            'latest',
-            ...latestLines,
-        ].join('\n');
-        process.stdout.write(withPathOutput(squarePath, out, { participantCount: result.activeCount, held: result.holdActive }));
-    }
-    catch (err) {
-        handleSquareError(err);
-    }
-}
-function cmdParticipants(squarePath) {
-    try {
-        const doc = loadSquare(squarePath);
-        const result = coreParticipants(doc, nowMs());
-        const { now } = result;
-        const lines = result.participants.map((p) => {
-            const glyph = p.state === 'done' ? '×' : p.presence === 'watching' ? '◎' : p.activityCount > 0 ? '●' : '○';
-            const state = p.state === 'done' ? 'done' : p.presence === 'watching' ? 'catching' : p.state;
-            const last = p.lastActiveAt === undefined ? '—' : formatRelativeTime(p.lastActiveAt, now);
-            return `  ${glyph} ${p.name} · ${state} · ${p.activityCount} act${p.activityCount === 1 ? '' : 's'} · ${last}`;
-        });
-        const out = ['participants', ...lines].join('\n');
-        process.stdout.write(withPathOutput(squarePath, out, { participantCount: result.participants.filter((p) => p.state === 'active').length }));
-    }
-    catch (err) {
-        handleSquareError(err);
-    }
-}
-function parseActRef(value, flag) {
-    const match = value.trim().match(/^(?:act_)?(\d+)$/i);
-    if (!match) {
-        process.stderr.write(`Invalid ${flag}: expected act id like act_12 or 12.\n`);
-        process.exit(2);
-    }
-    return Number(match[1]);
-}
-function parseActRefList(value, flag) {
-    return value
-        .split(',')
-        .map((part) => part.trim())
-        .filter(Boolean)
-        .map((part) => parseActRef(part, flag));
-}
-function formatActivityFields(doc, item, fields) {
-    const values = fields.map((field) => {
-        switch (field) {
-            case 'id':
-                return actId(item.index);
-            case 'author':
-            case 'actor':
-                return item.act.actor ?? '';
-            case 'ts':
-            case 'at':
-                return formatTimestamp(item.act.at);
-            case 'kind':
-                return item.act.kind;
-            case 'body':
-                return 'body' in item.act && typeof item.act.body === 'string'
-                    ? item.act.body.replace(/\s+/g, ' ').trim()
-                    : '';
-            case 'number':
-                return item.act.kind === 'say' ? String(sayNumberFor(doc.acts, item.act)) : '';
-            default:
-                return '';
-        }
-    });
-    return values.join('\t');
-}
-function activityJsonLine(doc, item) {
-    const act = item.act;
-    return JSON.stringify({
-        id: actId(item.index),
-        index: item.index,
-        kind: act.kind,
-        author: act.actor ?? null,
-        at: act.at,
-        ts: formatTimestamp(act.at),
-        body: 'body' in act && typeof act.body === 'string' ? act.body : '',
-        number: act.kind === 'say' ? sayNumberFor(doc.acts, act) : null,
-        reach: act.kind === 'say' ? act.reach ?? null : null,
-    });
-}
-function cmdActivities(squarePath, opts = {}) {
-    try {
-        const doc = loadSquare(squarePath);
-        let events = coreActivities(doc, opts);
-        const searching = opts.grep !== undefined || opts.fixed !== undefined;
-        const totalMatches = searching ? events.length : 0;
-        if (opts.lastN != null) {
-            events = opts.order === 'desc' ? events.slice(0, opts.lastN) : events.slice(-opts.lastN);
-        }
-        if (opts.countOnly) {
-            process.stdout.write(`${searching ? totalMatches : events.length}\n`);
-            return;
-        }
-        if (opts.json) {
-            process.stdout.write(events.map((item) => activityJsonLine(doc, item)).join('\n') + (events.length > 0 ? '\n' : ''));
-            return;
-        }
-        if (opts.format !== undefined && opts.format.length > 0) {
-            process.stdout.write(events.map((item) => formatActivityFields(doc, item, opts.format)).join('\n') + (events.length > 0 ? '\n' : ''));
-            return;
-        }
-        const pattern = opts.grep ?? opts.fixed;
-        const out = pattern !== undefined && pattern !== ''
-            ? renderGrepActivitiesView(events, totalMatches, opts.full, squarePath, pattern, opts.fixed !== undefined)
-            : renderActivitiesView(doc, events, null, opts.full, squarePath, opts.viewer ?? '');
-        if (out === '') {
-            process.stdout.write(withPathOutput(squarePath, '', { participantCount: inSquareCount(doc) }));
-            return;
-        }
-        process.stdout.write(withPathOutput(squarePath, out, { participantCount: inSquareCount(doc) }));
-    }
-    catch (err) {
-        handleSquareError(err);
-    }
-}
-function parseTimestampOption(value, flag) {
-    const ms = parseTimeOrRelative(value, nowMs());
-    if (!Number.isFinite(ms)) {
-        process.stderr.write(`Invalid ${flag} timestamp: ${value}\n`);
-        process.exit(2);
-    }
-    return ms;
-}
-function parseActivitiesOptions(args, viewer) {
-    let lastN = 10;
-    let lastNExplicit = false;
-    let before;
-    let after;
-    let afterIndex;
-    let atIndex;
-    let beforeContext;
-    let afterContext;
-    let mention;
-    let mentionsViewer = false;
-    let pending = false;
-    let full = false;
-    let grep;
-    let fixed;
-    let ids;
-    let order;
-    let format;
-    let countOnly = false;
-    let json = false;
-    const participants = [];
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg === '--last' || arg === '--limit') {
-            lastN = parsePositiveIntegerOption(requireValue(args, i, arg), arg);
-            lastNExplicit = true;
-            i++;
-        }
-        else if (arg === '--all') {
-            lastN = null;
-            lastNExplicit = true;
-        }
-        else if (arg === '--by' || arg === '--from') {
-            participants.push(...parseNameListOption(requireValue(args, i, arg), arg));
-            i++;
-        }
-        else if (arg === '--before' || arg === '--until') {
-            before = parseTimestampOption(requireValue(args, i, arg), arg);
-            i++;
-        }
-        else if (arg === '--since') {
-            after = parseTimestampOption(requireValue(args, i, arg), arg);
-            i++;
-        }
-        else if (arg === '--after') {
-            afterIndex = parseActRef(requireValue(args, i, arg), arg);
-            i++;
-        }
-        else if (arg === '--at') {
-            atIndex = parseActRef(requireValue(args, i, arg), arg);
-            i++;
-        }
-        else if (arg === '-B') {
-            beforeContext = parseNonNegativeIntegerOption(requireValue(args, i, arg), arg);
-            i++;
-        }
-        else if (arg === '-A') {
-            afterContext = parseNonNegativeIntegerOption(requireValue(args, i, arg), arg);
-            i++;
-        }
-        else if (arg === '-C') {
-            const n = parseNonNegativeIntegerOption(requireValue(args, i, arg), arg);
-            beforeContext = n;
-            afterContext = n;
-            i++;
-        }
-        else if (arg === '--full') {
-            full = true;
-        }
-        else if (arg === '--mention') {
-            mention = requireValue(args, i, arg);
-            i++;
-        }
-        else if (arg === '--mentions') {
-            const value = requireValue(args, i, arg);
-            if (value !== 'me') {
-                process.stderr.write(`Invalid --mentions: only 'me' is supported (got ${value}).\n`);
-                process.exit(2);
-            }
-            mentionsViewer = true;
-            i++;
-        }
-        else if (arg === '--pending') {
-            pending = true;
-        }
-        else if (arg === '--grep') {
-            grep = requireValue(args, i, arg);
-            i++;
-        }
-        else if (arg === '--fixed') {
-            fixed = requireValue(args, i, arg);
-            i++;
-        }
-        else if (arg === '--ids') {
-            ids = parseActRefList(requireValue(args, i, arg), arg);
-            i++;
-        }
-        else if (arg === '--order') {
-            const value = requireValue(args, i, arg);
-            if (value !== 'asc' && value !== 'desc') {
-                process.stderr.write(`Invalid --order: expected asc or desc.\n`);
-                process.exit(2);
-            }
-            order = value;
-            i++;
-        }
-        else if (arg === '--format') {
-            format = requireValue(args, i, arg)
-                .split(',')
-                .map((part) => part.trim())
-                .filter(Boolean);
-            i++;
-        }
-        else if (arg === '--count') {
-            countOnly = true;
-        }
-        else if (arg === '--json') {
-            json = true;
-        }
-        else {
-            usage();
-        }
-    }
-    if ((mentionsViewer || pending) && (viewer === undefined || viewer === '')) {
-        process.stderr.write(`--mentions me / --pending require --as <name>.\n`);
-        process.exit(2);
-    }
-    if (grep !== undefined && fixed !== undefined) {
-        process.stderr.write('--grep and --fixed cannot be combined.\n');
-        process.exit(2);
-    }
-    if (grep === '' || fixed === '') {
-        process.stderr.write('--grep and --fixed require non-empty text.\n');
-        process.exit(2);
-    }
-    // Context windows and exact id lists should not be silently clipped by the default --last 10.
-    if (!lastNExplicit && (atIndex !== undefined || ids !== undefined || pending)) {
-        lastN = null;
-    }
-    return {
-        lastN,
-        participants,
-        before,
-        after,
-        afterIndex,
-        atIndex,
-        beforeContext,
-        afterContext,
-        mention,
-        mentionsViewer,
-        pending,
-        viewer,
-        full,
-        grep,
-        fixed,
-        ids,
-        order,
-        format,
-        countOnly,
-        json,
-    };
-}
-function parseWatchOptions(args, name) {
-    let activityCount = 1;
-    let idleMs;
-    let mention;
-    let force = false;
-    let now = false;
-    let follow = false;
-    const participants = [];
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === '--count') {
-            activityCount = parsePositiveIntegerOption(requireValue(args, i, args[i]), args[i]);
-            i++;
-        }
-        else if (args[i] === '--by') {
-            participants.push(...parseNameListOption(requireValue(args, i, args[i]), args[i]));
-            i++;
-        }
-        else if (args[i] === '--idle') {
-            idleMs = parseDurationMs(requireValue(args, i, args[i]), args[i]);
-            i++;
-        }
-        else if (args[i] === '--mention') {
-            const value = args[i + 1];
-            if (value !== undefined && !value.startsWith('--')) {
-                mention = value;
-                i++;
-            }
-            else {
-                mention = name;
-            }
-        }
-        else if (args[i] === '-f' || args[i] === '--force') {
-            force = true;
-        }
-        else if (args[i] === '--now') {
-            now = true;
-        }
-        else if (args[i] === '--follow') {
-            follow = true;
-        }
-        else {
-            usage();
-        }
-    }
-    if (now && follow) {
-        process.stderr.write('--follow cannot be combined with --now\n');
-        process.exit(2);
-    }
-    return {
-        activityCount,
-        ...(participants.length > 0 ? { participants } : {}),
-        ...(mention !== undefined ? { mention } : {}),
-        ...(idleMs !== undefined ? { idleMs } : {}),
-        ...(force ? { force } : {}),
-        ...(now ? { now } : {}),
-        ...(follow ? { follow } : {}),
-    };
-}
-function parseCompactOptions(args) {
-    let keep = 50;
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === '--keep') {
-            keep = parsePositiveIntegerOption(requireValue(args, i, args[i]), args[i]);
-            i++;
-        }
-        else {
-            usage();
-        }
-    }
-    return { keep };
-}
-function parseDoctorOptions(args) {
-    let fix = false;
-    let reconcileBacklog = false;
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg === '--fix') {
-            fix = true;
-        }
-        else if (arg === 'reconcile-backlog') {
-            reconcileBacklog = true;
-        }
-        else if (arg === '--before') {
-            // Optional timestamp accepted for operator clarity; reconcile always uses lookback partition.
-            i++;
-            if (args[i] === undefined)
-                usage();
-        }
-        else {
-            usage();
-        }
-    }
-    if (reconcileBacklog && !fix) {
-        process.stderr.write('doctor reconcile-backlog requires --fix.\n');
-        process.exit(2);
-    }
-    return { fix, reconcileBacklog };
-}
-function quarantinePath(squarePath) {
-    return squarePath.replace(/\.md$/, '') + '.quarantine.md';
-}
-function readSquareText(squarePath) {
-    try {
-        return fs.readFileSync(squarePath, 'utf8');
-    }
-    catch (err) {
-        if (err.code === 'ENOENT') {
-            throw new SquareError('not_found', `square file not found: ${squarePath}`);
-        }
-        throw err;
-    }
-}
-async function cmdDoctor(squarePath, opts) {
-    try {
-        if (!opts.fix) {
-            const diagnosis = diagnoseSquare(readSquareText(squarePath));
-            if (diagnosis.unfixable) {
-                process.stdout.write(withPathOutput(squarePath, renderDoctorUnfixable(diagnosis.unfixable), { participantCount: inSquareCount(loadSquare(squarePath)) }));
-                process.exit(2);
-            }
-            const out = diagnosis.problems.length === 0 ? renderDoctorClean() : renderDoctorProblems(diagnosis.problems);
-            const delivery = doctorDeliveryHealth(squarePath).join('\n');
-            process.stdout.write(withPathOutput(squarePath, `${out}\n\n${delivery}`, { participantCount: inSquareCount(loadSquare(squarePath)) }));
-            const recentStale = findStalePendingMentions(squarePath);
-            process.exit(diagnosis.problems.length === 0 && recentStale.length === 0 ? 0 : 1);
-        }
-        if (opts.reconcileBacklog) {
-            const result = await withSquareLock(squarePath, () => reconcileDeliveryBacklog(squarePath));
-            const delivery = doctorDeliveryHealth(squarePath).join('\n');
-            process.stdout.write(withPathOutput(squarePath, [
-                `✓ reconciled ${result.reconciled} backlog receipt(s) as delivered(reason=reconciled)`,
-                result.skippedRecent > 0
-                    ? `· left ${result.skippedRecent} recent liveness failure(s) untouched`
-                    : '· no recent liveness failures present',
-                '',
-                delivery,
-            ].join('\n'), { participantCount: inSquareCount(loadSquare(squarePath)) }));
-            process.exit(result.skippedRecent > 0 ? 1 : 0);
-        }
-        const sidecar = quarantinePath(squarePath);
-        let plan;
-        await withSquareLock(squarePath, () => {
-            plan = planRepair(readSquareText(squarePath));
-            if (plan.diagnosis.unfixable || plan.repaired === undefined)
-                return;
-            if (plan.repaired.quarantinedBlocks.length > 0) {
-                const sidecarExists = fs.existsSync(sidecar);
-                const block = plan.repaired.quarantinedBlocks.join('\n\n');
-                fs.appendFileSync(sidecar, (sidecarExists ? '\n' : '') + block + '\n');
-            }
-            writeSquareDoc(squarePath, plan.repaired.doc);
-        });
-        if (plan.diagnosis.unfixable) {
-            process.stdout.write(withPathOutput(squarePath, renderDoctorUnfixable(plan.diagnosis.unfixable), { participantCount: inSquareCount(loadSquare(squarePath)) }));
-            process.exit(2);
-        }
-        const repaired = plan.repaired;
-        process.stdout.write(withPathOutput(squarePath, renderDoctorRepaired(repaired.actions, repaired.quarantinedBlocks.length, repaired.quarantinedBlocks.length > 0 ? sidecar : undefined), { participantCount: inSquareCount(loadSquare(squarePath)) }));
-    }
-    catch (err) {
-        handleSquareError(err);
-    }
-}
-let usageCommand;
-function usage() {
-    process.stderr.write(`✕ invalid arguments${usageCommand === undefined ? '' : ` for ${usageCommand}`}\n`);
-    process.stderr.write(commandUsageHint(usageCommand));
-    process.exit(2);
-}
-function cmdHelp() {
-    process.stdout.write(renderGlobalHelp());
-}
-function cmdSubcommandHelp(command) {
-    const rendered = renderScopedHelp(command);
-    if (rendered === undefined) {
-        process.stderr.write(`unknown command: ${command}\nrun 'square help' to list every command\n`);
-        process.exit(2);
-    }
-    process.stdout.write(rendered);
-}
-function cmdVersion() {
-    const packageJsonPath = fileURLToPath(new URL('../package.json', import.meta.url));
-    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-    process.stdout.write(`${packageJson.version ?? 'unknown'}\n`);
-}
-function cmdInbox(args) {
-    let sessionId;
-    let json = false;
-    for (let index = 0; index < args.length; index++) {
-        if (args[index] === '--for-session') {
-            sessionId = requireValue(args, index, args[index]);
-            index++;
-        }
-        else if (args[index] === '--json') {
-            json = true;
-        }
-        else {
-            usage();
-        }
-    }
-    if (!sessionId) {
-        process.stderr.write('inbox requires --for-session <session-id>.\n');
-        process.exit(2);
-    }
-    const inbox = sessionInbox(sessionId);
-    if (json) {
-        process.stdout.write(`${JSON.stringify(inbox)}\n`);
-        return;
-    }
-    for (const membership of inbox) {
-        process.stdout.write(`${membership.name}\t${membership.squarePath}\t${membership.notifications.length}\n`);
-    }
-}
-function cmdClaudeHook(args) {
-    if (args.length > 0)
-        usage();
-    process.stdout.write(runClaudeHook(readStdinSync()));
-}
-function cmdCodexHook(args) {
-    if (args.length > 0)
-        usage();
-    process.stdout.write(runCodexHook(readStdinSync()));
-}
-function refreshLocalRegistration(squarePath, name) {
-    if (!name)
-        return;
-    try {
-        const doc = loadSquare(squarePath);
-        const known = resolveRosterName(doc, name);
-        if (known !== undefined && isCurrentlyJoined(doc.acts, known)) {
-            recordLocalJoin(known, squarePath);
-        }
-    }
-    catch {
-        // Registration is a best-effort machine-local discovery cache.
-    }
-}
+import { runCli } from './cli/program.js';
 try {
-    const rawArgs = process.argv.slice(2);
-    const requestedHelp = parseHelpRequest(rawArgs);
-    if (requestedHelp !== undefined) {
-        if (requestedHelp.command === undefined)
-            cmdHelp();
-        else
-            cmdSubcommandHelp(requestedHelp.command);
-        process.exit(0);
-    }
-    const { squarePath: defaultSquarePath, explicitSquarePath, multipleSquares, name: defaultName, args } = parseGlobalArgs(rawArgs);
-    if (args.length === 0) {
-        cmdHelp();
-        process.exit(0);
-    }
-    if (args[0] === 'help') {
-        process.stderr.write('Usage: square help [command]\n');
-        process.exit(2);
-    }
-    if (args[0] === '--help' || args[0] === '-h') {
-        cmdHelp();
-        process.exit(0);
-    }
-    if (args[0] === 'version' || args[0] === '--version' || args[0] === '-v') {
-        cmdVersion();
-        process.exit(0);
-    }
-    const cmd = args[0];
-    usageCommand = cmd;
-    const mutatingDoctor = cmd === 'doctor' && args.slice(1).some((arg) => arg === '--fix' || arg === 'reconcile-backlog');
-    if (!explicitSquarePath && multipleSquares && (['build', 'join', 'catch', 'act', 'done', 'hold', 'resume', 'compact'].includes(cmd) || mutatingDoctor)) {
-        process.stderr.write('✕ more than one square is active here; choose the path before changing or consuming activity.\n» square ls\n');
-        process.exit(2);
-    }
-    const participantActionCommands = new Set(['act', 'catch', 'done', 'hold', 'resume']);
-    if (participantActionCommands.has(cmd))
-        refreshLocalRegistration(defaultSquarePath, defaultName);
-    switch (cmd) {
-        case 'build':
-            await cmdBuild(defaultSquarePath, args.slice(1));
-            break;
-        case 'ls':
-        case 'list':
-            cmdListSquares(args.slice(1), usage);
-            break;
-        case 'join': {
-            const name = requireNameFlag(defaultName);
-            await cmdJoin(defaultSquarePath, name, parseJoinOptions(args.slice(1)));
-            break;
-        }
-        case 'stream': {
-            let ndjson = false;
-            let forName;
-            for (let i = 1; i < args.length; i++) {
-                if (args[i] === '--ndjson')
-                    ndjson = true;
-                else if (args[i] === '--for' && i + 1 < args.length)
-                    forName = args[++i];
-                else
-                    usage();
-            }
-            if (ndjson) {
-                await cmdStreamNdjson(defaultSquarePath, forName);
-            }
-            else {
-                if (forName)
-                    usage();
-                await cmdStream(defaultSquarePath);
-            }
-            break;
-        }
-        case 'inbox':
-            cmdInbox(args.slice(1));
-            break;
-        case 'claude-hook':
-            cmdClaudeHook(args.slice(1));
-            break;
-        case 'codex-hook':
-            cmdCodexHook(args.slice(1));
-            break;
-        case 'catch': {
-            const name = requireNameFlag(defaultName);
-            await cmdWatch(defaultSquarePath, name, parseWatchOptions(args.slice(1), name));
-            break;
-        }
-        case 'act': {
-            const name = requireNameFlag(defaultName);
-            const opts = parseActOptions(args.slice(1));
-            await cmdActivity(defaultSquarePath, name, opts.activity, resolveBody, {
-                force: opts.force,
-                noWait: opts.noWait,
-                forceCommand: forceActCommand(defaultSquarePath, name, opts.reach),
-                reach: opts.reach,
-            });
-            break;
-        }
-        case 'done': {
-            const name = requireNameFlag(defaultName);
-            await cmdDone(defaultSquarePath, name, parseDoneOptions(args.slice(1)));
-            break;
-        }
-        case 'hold':
-            if (args.length > 2)
-                usage();
-            await cmdHold(defaultSquarePath, requireNameFlag(defaultName), args[1]);
-            break;
-        case 'resume':
-            if (args.length > 1)
-                usage();
-            await cmdResume(defaultSquarePath, requireNameFlag(defaultName));
-            break;
-        case 'harness':
-            await cmdHarness(args.slice(1), defaultSquarePath);
-            break;
-        case 'compact': {
-            const opts = parseCompactOptions(args.slice(1));
-            await cmdCompact(defaultSquarePath, { keep: opts.keep });
-            break;
-        }
-        case 'doctor': {
-            const opts = parseDoctorOptions(args.slice(1));
-            await cmdDoctor(defaultSquarePath, { fix: opts.fix, reconcileBacklog: opts.reconcileBacklog });
-            break;
-        }
-        case 'echo': {
-            cmdActivities(defaultSquarePath, parseActivitiesOptions(args.slice(1), defaultName));
-            break;
-        }
-        case 'warmup':
-            if (args.length > 1)
-                usage();
-            cmdWarmup(defaultSquarePath);
-            break;
-        case 'status':
-            if (args.length > 1)
-                usage();
-            cmdStatus(defaultSquarePath, defaultName);
-            break;
-        case 'participants':
-            if (args.length > 1)
-                usage();
-            cmdParticipants(defaultSquarePath);
-            break;
-        default:
-            process.stderr.write(`unknown command: ${cmd}\nrun 'square' for usage\n`);
-            process.exit(2);
-    }
+    await runCli();
 }
-catch (err) {
-    handleSquareError(err);
+catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
 }