seatmesh 1.1.4 → 1.2.0

package/dist/main.js

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
 import { findDotSmConfig } from "@seat-mesh/core";
-import { loadProfile, profilePaths, loadRoleIndex, renderRoleIndex, validateRoleIndex, runStackPassthrough, roleAllows, isCoordKind, isManagerKind, managerColumnIds, addBaseColumn, removeBaseColumn, listBaseColumns, chatRoomConfigForLoaded, clearAckEndedSync, } from "@seat-mesh/core";
+import { loadProfile, profilePaths, loadRoleIndex, renderRoleIndex, validateRoleIndex, runStackPassthrough, roleAllows, isCoordKind, isManagerKind, managerColumnIds, addBaseColumn, removeBaseColumn, listBaseColumns, chatRoomConfigForLoaded, clearAckEndedSync, resolveAckRedirectDefaults, } from "@seat-mesh/core";
 import { snapshotConnectivity, formatStatus } from "@seat-mesh/connectivity";
 import { createRegistryForProfile } from "@seat-mesh/providers";
-import { printWhoami, whoamiJson, whoamiJsonWithValidate, validateWhoamiRoleIndex, printAgentCard, printAgentContext, printAgentContextAllRoles, runWhoami, roleKindFromWhoami, requireCoordRole, requireInboxLifecycleRole, assertAgentDispatch, printAgentUnauthorized, stripAgentFromArgv, AGENT_META, capturePaneSnapshot, listSessionPanes, sessionAttach, sessionUp, sessionDown, sessionStatus, sessionSync, tmuxHasSession, relayoutMeshSession, realignAllLayouts, reloadMesh, ensureMeshInbox, startMeshInbox, stopMeshInbox, restartMeshInbox, meshInboxEverConfigured, meshInboxPort, printMeshInboxStatus, waitForMeshInbox, printInboxMeta, tailInboxLog, listInboxInstances, parseInboxStatusFlags, inboxStatusArgv, listInbox, resolveInbox, secretaryLaunch, secretaryRestart, secretaryDispatch, secretaryCollect, secretaryMeshWatch, secretarySupervise, secretaryStatus, printMiniList, miniSpawn, miniPrompt, miniDone, miniSpawnAll, runMeshSmoke, printSmokeResults, launchSession, printLaunchResults, enqueuePrompt, injectPromptDirect, printPeerVerify, runPeerVerify, runRemind, printRemindResults, runNight, runContinue, printContinueResults, runSlotAdvice, verifyMeshSession, printVerify, labelMeshSession, liveMeshSession, ensureBaseLayout, realignBaseLayout, applyMeshSessionBorders, runFlush, printFlushResults, runSwitch, runSet, runTag, setPaneTitle, setPaneStatus, printSeatContexts, runPeek, runPaneKind, runPaneMeta, runPpa, runToSlot, runToMini, runPeer, parseRemotePeerTarget, runRemotePeer, applyMeshState, saveMeshSession, saveMeshSessionDetailed, assertSaveAllowed, formatSaveSummary, submitPaneOp, clearPaneOpsQueue, printPaneOpsList, printRelayoutPlan, assertRelayoutSafe, buildFullColdStartBrief, enqueueColdStart, runSeatInit, applyAgentContractBundle, balanceLeadCommand, } from "@seat-mesh/tmux";
+import { printWhoami, whoamiJson, whoamiJsonWithValidate, validateWhoamiRoleIndex, printAgentCard, printAgentContext, printAgentContextAllRoles, runWhoami, roleKindFromWhoami, requireCoordRole, requireInboxLifecycleRole, assertAgentDispatch, printAgentUnauthorized, stripAgentFromArgv, AGENT_META, capturePaneSnapshot, listSessionPanes, sessionAttach, sessionUp, sessionDown, sessionStatus, sessionSync, tmuxHasSession, relayoutMeshSession, realignAllLayouts, reloadMesh, ensureMeshInbox, startMeshInbox, stopMeshInbox, restartMeshInbox, meshInboxEverConfigured, meshInboxPort, printMeshInboxStatus, waitForMeshInbox, printInboxMeta, tailInboxLog, listInboxInstances, parseInboxStatusFlags, inboxStatusArgv, listInbox, resolveInbox, secretaryLaunch, secretaryDispatch, secretaryCollect, secretaryMeshWatch, secretarySupervise, secretaryStatus, printMiniList, miniSpawn, miniPrompt, miniDone, miniSpawnAll, runMeshSmoke, printSmokeResults, launchSession, printLaunchResults, defaultHarnessTypeForSeat, enqueuePrompt, injectPromptDirect, printPeerVerify, runPeerVerify, runRemind, printRemindResults, runNight, runContinue, printContinueResults, runSlotAdvice, verifyMeshSession, printVerify, labelMeshSession, liveMeshSession, ensureBaseLayout, realignBaseLayout, applyMeshSessionBorders, runFlush, printFlushResults, runSwitch, runPaneResume, runSeatSwap, runSet, runTag, setPaneTitle, setPaneStatus, printSeatContexts, runAgentHub, runPeek, runPaneKind, runPaneMeta, runPpa, runToSlot, runToMini, runPeer, parseRemotePeerTarget, runRemotePeer, applyMeshState, saveMeshSession, saveMeshSessionDetailed, assertSaveAllowed, formatSaveSummary, submitPaneOp, clearPaneOpsQueue, printPaneOpsList, printRelayoutPlan, assertRelayoutSafe, buildFullColdStartBrief, enqueueColdStart, runSeatInit, applyAgentContractBundle, balanceLeadCommand, } from "@seat-mesh/tmux";
 import { parseAgentApplyArgs } from "@seat-mesh/core";
 import { buildChatCommands } from "./commands/chat-cli.js";
 import { buildCheckbackCommands } from "./commands/checkback-cli.js";
 import { buildTargetCommands } from "./commands/target-cli.js";
 import { buildAckCommands } from "./commands/ack-cli.js";
+import { resolvePeerEndedAckId, shouldAutoAckReply, } from "./commands/ack-reply.js";
 import { buildLimitCommands } from "./commands/limit-cli.js";
 import { buildRolesCommands } from "./commands/roles-cli.js";
 import { buildNotifyCommand } from "./commands/notify-cli.js";
@@ -18,11 +19,13 @@ import { buildContractLockCommands } from "./commands/contract-lock-cli.js";
 import { buildRoomCommands } from "./commands/room-cli.js";
 import { runInit } from "./setup/init.js";
 import { runAgentContextInit } from "./setup/agent-context-init.js";
+import { printSessionCheck, printSessionRepair, runSessionCheck, runSessionRepair, } from "./setup/session-health.js";
 import { runSeatCommand } from "./commands/seat-cli.js";
 import { coordCommand } from "./commands/coord-cli.js";
 function parseArgs(argv) {
     const profileFlag = [];
     const rest = [];
+    let agentsHelp = false;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--profile" || a === "-p") {
@@ -32,31 +35,91 @@ function parseArgs(argv) {
             profileFlag.push(v);
             continue;
         }
+        if (a === "--agents" || a === "--agent-help") {
+            agentsHelp = true;
+            continue;
+        }
         rest.push(a);
     }
-    return { profile: profileFlag[0], rest };
+    return { profile: profileFlag[0], rest, agentsHelp };
 }
 /** Profile yaml + mesh-agents.json layout overrides (yaml is fallback only). */
 function meshLoaded(profileArg) {
     return applyMeshState(loadProfile(profileArg));
 }
+/** Operator-facing help — human/session verbs only (default `seatmesh help`). */
+function usageHuman(loaded) {
+    const prof = loaded ? `profile=${loaded.profile.name}` : "";
+    console.log(`seatmesh${prof ? ` (${prof})` : ""} — operator CLI (human surface)
+
+  Docs: README.md + docs/QUICKSTART.md · full agent+human list: seatmesh --agents help
+
+Setup
+  start | run | init | install | update | version
+  session attach|up|down|status|sync|init <sm-name>
+  sessions [list|attach|forget|register]
+
+Put an agent on a pane
+  help human          ← cheat sheet (aliases: put-agent | panes)
+  switch <target> <opencode|oc-proxy|claude|agent|kiro|empty>
+  launch <target|all>
+  kind <target>
+
+Work / status
+  todo give <target> "…" | todo <target> "…" | assign <target> "…"
+  todo list [target] | todo check <target> "…"
+  target add|list|done|triage
+  report | verify | test | save|auto | inbox […] | labels
+
+Session shape
+  reload [--layout] | layout […] | realign | ops list|clear
+
+Agent panes use the gateway (not listed here by default):
+  seatmesh agent …          · seatmesh agent help
+  seatmesh --agents help    · show human + agent + shared verbs
+
+  --profile <dir|yaml>   optional; default walk-up .sm/
+`);
+}
+/** Full help — human + agent + shared (`seatmesh --agents help`). */
 function usage(loaded) {
     const prof = loaded ? `profile=${loaded.profile.name}` : "";
     console.log(`seatmesh${prof ? ` (${prof})` : ""} — profile-driven tmux multi-agent CLI
 
   Docs: README.md + docs/ONE-PATH.md + docs/QUICKSTART.md
   Cold start: bin/seatmesh auto-runs npm install + build when dist is stale
+  Default operator help (human-only): seatmesh help   ·  this list: seatmesh --agents help
 
 Setup (run once per project, by a human)
   start               ONE command: init if needed + create-or-attach session (fresh or existing)
+  run                 logs-window left pane: status line → interactive $SHELL (npx seatmesh run)
   init [--force] [--seats-root PATH] [--name NAME]   create .sm/ dotdir only
   session init <sm-name> [--force] [--name NAME]   create .sm-<name>/ (multi-config)
   sessions [list|attach|forget|register] [--json]   global registry + TUI picker (all meshes)
+  install [--bin DIR] [--force]       symlink tracked bin/sm + seatmesh → ~/.local/bin
   update [--dry-run] [--migrate] [--no-restart-inbox]
-                                        refresh _vendor (file-by-file) + role-pack migrate + paths.json
+                                        1) npm i -g seatmesh@latest  2) refresh .sm/_vendor
+  config check | config upgrade         validate yaml · how to bump CLI (npm i -g)
+  web status|open|url | open-web        operator hub :3190 (parity with packages/web)
   roles status|migrate [--to VER]|steps   locked role-pack up/down (1.1.x)
   version [--json] [--check-registry]   CLI vs npm latest vs profile .seatmesh-version
 
+Put an agent on a pane (human — most common)
+  help human          ← full cheat sheet (aliases: put-agent | panes)
+  switch <target> <opencode|oc-proxy|claude|agent|kiro>   empty shell → agent CLI
+  switch <target> empty                          agent → plain shell
+  launch <target|all>                            resume configured CLI (no type pick)
+  pane resume [target]                           autodetect session id → resume/relaunch
+  kind <target>                                  agent vs terminal?
+  Examples: switch slot-1 opencode · switch secretary oc-proxy · pane resume here
+
+Give a seat a todo (human or base agent — contracts optional)
+  todo give <target> "…"     ← FOCUS+TASK+inject+CB≥20m  (preferred)
+  todo <target> "…"          ← same shorthand
+  assign <target> "…"        ← same engine
+  todo list [target] | todo check <target> "…"
+  Examples: todo give slot-1 "fix login" · agent todo mini-2 "draft README"
+
 Status / diagnostics
   report [--json] [--verbose]   stack status (one line default; --verbose = full section dump)
   verify              layout + labels health
@@ -78,35 +141,48 @@ Agent runtime (pane — always via gateway)
   agent                     scoped can/cannot for this pane
   agent <cmd> …             run <cmd> if allowed; else UNAUTHORIZED
   agent context [roles|init]  registered read_first/files; init scaffolds .sm
-  agent apply|preflight …   contract apply
+  agent contract [status|on|off|open]   simple locks (prefer over apply)
+  agent apply|preflight …   legacy multi-clause DSL
 
   Shared/operator (outside agent — humans + session ops)
-  session | update | init | report | test | layout | save | inbox restart | target …
+  run | session | update | init | report | test | layout | save | inbox restart | target …
 
-  Examples: agent whoami | agent kind slot-1 | agent peer <t> "<msg>" | agent ack <id> "<note>" | agent cb list
+  Examples: switch slot-1 opencode | agent whoami | agent help peer | agent hub | agent kind slot-1
+  Discover: help human  # put agent on pane · help <cmd> · agent help <cmd> · <cmd> --help
+  Tab complete: eval "$(seatmesh completion zsh)"  # or bash|fish; see: completion install
   Operator EOD: target add "finish s13 tickets" [--deadline eod|6h] · target list · target done <id> · target triage <id>
 
   --profile <dir|yaml>   optional; default walk-up .sm/; multi-config: --profile .sm-<name>
+  --agents               with help: show this full human+agent surface (default help is human-only)
 `);
 }
-function printPlainUsage(profileArg) {
+function printPlainUsage(profileArg, agentsHelp = false) {
+    const print = agentsHelp ? usage : usageHuman;
     if (profileArg) {
         try {
-            usage(meshLoaded(profileArg));
+            print(meshLoaded(profileArg));
             return;
         }
         catch {
             /* fall through — plain help without profile load */
         }
     }
-    usage();
+    print();
 }
 async function main() {
-    const { profile: profileArg, rest } = parseArgs(process.argv.slice(2));
+    const { profile: profileArg, rest, agentsHelp } = parseArgs(process.argv.slice(2));
     const [cmd, sub, ...tail] = rest;
     // Bare `npx seatmesh` / help: logo+version once per terminal; later invocations plain usage.
+    // `help <cmd>` → per-command usage (agents: `agent help <cmd>`).
+    // Default help = human-only; `--agents help` = full human+agent surface.
     const helpCmd = cmd === "-h" || cmd === "--help" || cmd === "help";
     const blankCmd = !cmd || (cmd.startsWith("-") && !helpCmd);
+    if (helpCmd && cmd === "help" && sub && sub !== "--agents") {
+        const { printCmdHelp } = await import("./commands/help-text.js");
+        if (!printCmdHelp(sub))
+            process.exit(2);
+        return;
+    }
     if (blankCmd || helpCmd) {
         const { printSeatmeshBanner } = await import("./ui/banner.js");
         const { formatHelpVersionBlock, installKindLabel, readInstalledCliVersion, resolveLatestRegistryVersion, } = await import("./ui/version-nudge.js");
@@ -119,17 +195,63 @@ async function main() {
             }
             console.log("");
         }
-        printPlainUsage(profileArg);
+        printPlainUsage(profileArg, agentsHelp);
+        const { printGlobalHelpHint } = await import("./commands/help-text.js");
+        printGlobalHelpHint(agentsHelp);
         return;
     }
+    // Per-command --help / `cmd help` — never execute the verb (no launch/reload/whoami side effects).
+    if (cmd !== "agent") {
+        const { wantsCmdHelp, printCmdHelp } = await import("./commands/help-text.js");
+        if (wantsCmdHelp(rest)) {
+            if (!printCmdHelp(cmd))
+                process.exit(2);
+            return;
+        }
+    }
+    // Universal shorthands (all agents): ask/msg/tell → peer; ackmsg → peer --ack; reply → ack reply
+    if (cmd === "ask" ||
+        cmd === "msg" ||
+        cmd === "tell" ||
+        cmd === "ackmsg" ||
+        cmd === "answered" ||
+        cmd === "reply") {
+        const { expandAgentShorthand } = await import("./commands/agent-shorthand.js");
+        const args = [sub, ...tail].filter((a) => a != null && a !== "");
+        try {
+            const { argvRest, label } = expandAgentShorthand(cmd, args);
+            console.error(`shorthand: ${label}`);
+            const bin = process.argv[0];
+            const script = process.argv[1];
+            // Preserve --profile if present in original argv
+            const profileIdx = process.argv.indexOf("--profile");
+            const profileArgs = profileIdx >= 0 && process.argv[profileIdx + 1]
+                ? ["--profile", process.argv[profileIdx + 1]]
+                : process.argv.some((a) => a.startsWith("--profile="))
+                    ? [process.argv.find((a) => a.startsWith("--profile="))]
+                    : [];
+            process.argv = [bin, script, ...profileArgs, ...argvRest];
+            return main();
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exit(2);
+        }
+    }
     const { maybePrintVersionNudge } = await import("./ui/version-nudge.js");
     // Attach/session picker must not wait on npm view — operator is trying to get into tmux.
     const skipNudge = process.env.SEATMESH_SKIP_VERSION_CHECK === "1" ||
         cmd === "session" ||
         cmd === "sessions" ||
-        cmd === "start";
+        cmd === "start" ||
+        cmd === "completion";
     if (!skipNudge)
         maybePrintVersionNudge();
+    if (cmd === "completion") {
+        const { runCompletionCommand } = await import("./commands/completion.js");
+        runCompletionCommand([sub, ...tail].filter((a) => a != null));
+        return;
+    }
     if (cmd === "version") {
         const { printVersionInfo } = await import("./ui/version-nudge.js");
         let profileDir;
@@ -146,6 +268,20 @@ async function main() {
         });
         return;
     }
+    if (cmd === "install") {
+        const { runInstall, defaultInstallBinDir } = await import("./setup/install.js");
+        let binDir = defaultInstallBinDir();
+        const force = rest.includes("--force");
+        for (let i = 0; i < rest.length; i++) {
+            if (rest[i] === "--bin" && rest[i + 1]) {
+                binDir = rest[++i];
+            }
+        }
+        const r = runInstall({ binDir, force });
+        console.log(`OK: install ${r.created ? "linked" : "already linked"} ${r.link} -> ${r.target}`);
+        console.log(`  bin dir: ${r.binDir} (ensure it is on PATH)`);
+        return;
+    }
     if (cmd === "update") {
         const { runUpdate } = await import("./setup/update.js");
         const { formatInstallStatusLine, isNpxEphemeralInstall, readInstalledCliVersion, resolveLatestRegistryVersion, semverLess, } = await import("./ui/version-nudge.js");
@@ -154,9 +290,20 @@ async function main() {
         const noRestartInbox = rest.includes("--no-restart-inbox");
         const installed = readInstalledCliVersion();
         const npmLatest = resolveLatestRegistryVersion(true);
+        // Lead with CLI upgrade — most users think "update" means bump the package.
+        console.log("seatmesh update — two steps");
+        console.log("  1) CLI package (do this first if you want npm latest):");
+        console.log("       npm install -g seatmesh@latest");
+        console.log("       # or: npx seatmesh@latest update");
+        console.log("  2) This command: refresh .sm/_vendor + config merge from the CLI you ran");
+        console.log("     (see also: seatmesh config upgrade)");
+        console.log("");
         console.log(formatInstallStatusLine(installed, npmLatest));
+        if (npmLatest && semverLess(installed, npmLatest)) {
+            console.error(`  WARN: CLI ${installed} < npm ${npmLatest} — step 1 first, then re-run update`);
+        }
         const r = runUpdate({ profileArg, dryRun, migrate });
-        console.log(`OK: update dryRun=${dryRun} migrate=${migrate}`);
+        console.log(`OK: profile update dryRun=${dryRun} migrate=${migrate}`);
         console.log(`  CLI running: ${r.packageVersion}`);
         if (r.previousVersion != null) {
             console.log(`  profile .seatmesh-version: ${r.previousVersion} (last profile update — not npm "installed")`);
@@ -166,9 +313,6 @@ async function main() {
         }
         if (npmLatest)
             console.log(`  npm latest: ${npmLatest}`);
-        if (npmLatest && semverLess(installed, npmLatest)) {
-            console.error(`  WARN: CLI ${installed} < npm ${npmLatest} — upgrade: npm install -g seatmesh@latest  or  npx seatmesh@latest update`);
-        }
         console.log(`  paths: ${r.pathsManifest}`);
         for (const line of r.refreshed)
             console.log(`  refreshed: ${line}`);
@@ -184,8 +328,12 @@ async function main() {
             console.log(`  role-pack: ${r.rolePack.direction} ${r.rolePack.from ?? "none"} → ${r.rolePack.to}` +
                 (r.rolePack.steps.length ? ` [${r.rolePack.steps.join(",")}]` : ""));
         }
+        if (r.configMerge?.added.length) {
+            console.log(`  config-merge: ${r.configMerge.added.join(", ")}` +
+                (dryRun ? " (dry-run)" : ""));
+        }
         if (isNpxEphemeralInstall()) {
-            console.log("  note: npx cache CLI — profile vendor updated only; npm package is re-fetched each npx run");
+            console.log("  note: npx cache CLI — profile vendor updated only; use npm i -g seatmesh@latest to pin a global bin");
         }
         if (!dryRun && !noRestartInbox) {
             const loaded = meshLoaded(profileArg);
@@ -261,6 +409,20 @@ async function main() {
         sessionAttach(loaded);
         return;
     }
+    if (cmd === "run") {
+        // Logs window left pane: one-liner status, then plain interactive shell.
+        const loaded = meshLoaded(profileArg);
+        const port = meshInboxPort(loaded);
+        console.log(`seatmesh run · session=${loaded.sessionName} · workspace=${loaded.workspace} · inbox=:${port}`);
+        console.log(`tips: seatmesh agent · seatmesh report · seatmesh inbox · seatmesh help`);
+        const shell = process.env.SHELL || "/bin/bash";
+        const r = spawnSync(shell, ["-l"], {
+            cwd: loaded.workspace,
+            stdio: "inherit",
+            env: process.env,
+        });
+        process.exit(typeof r.status === "number" ? r.status : 1);
+    }
     if (cmd === "init") {
         const force = rest.includes("--force");
         const seatsIdx = rest.indexOf("--seats-root");
@@ -284,9 +446,65 @@ async function main() {
         return;
     }
     if (cmd === "sessions") {
-        const { runSessionsCommand } = await import("./commands/sessions-cli.js");
+        const { runSessionsCommand, printAgentSessionsList } = await import("./commands/sessions-cli.js");
+        // After `agent sessions` strip: only list/json — never attach/pick/forget/register.
+        const fromAgent = process.env.SEATMESH_AGENT_GATEWAY === "1";
+        if (fromAgent) {
+            const action = (sub ?? "list").toLowerCase();
+            if (["attach", "forget", "register", "pick", "add"].includes(action)) {
+                console.error(`UNAUTHORIZED: sessions ${action} is operator-only — run without agent: seatmesh sessions ${action} …`);
+                console.error("hint: seatmesh agent sessions   # list other meshes");
+                console.error('hint: seatmesh agent peer @pia:secretary "…"  # cross-mesh');
+                process.exit(2);
+            }
+            const loaded = meshLoaded(profileArg);
+            await printAgentSessionsList(loaded, { json: rest.includes("--json") || tail.includes("--json") });
+            return;
+        }
         process.exit(await runSessionsCommand(sub, tail, profileArg));
     }
+    if (cmd === "remote" || cmd === "meshes") {
+        const loaded = meshLoaded(profileArg);
+        const { printAgentSessionsList } = await import("./commands/sessions-cli.js");
+        const json = rest.includes("--json") || sub === "--json";
+        // bare / list / --json → discover
+        if (!sub || sub === "list" || sub === "--json" || sub === "-h" || sub === "--help") {
+            if (sub === "-h" || sub === "--help") {
+                const { printCmdHelp } = await import("./commands/help-text.js");
+                printCmdHelp("remote");
+                return;
+            }
+            await printAgentSessionsList(loaded, { json });
+            return;
+        }
+        // remote @alias:seat <msg...>
+        const atTarget = parseRemotePeerTarget(sub);
+        if (atTarget) {
+            const rawMsg = [...tail].join(" ").trim();
+            if (!rawMsg) {
+                console.error('usage: remote @alias:seat "<msg>"');
+                process.exit(2);
+            }
+            runRemotePeer(loaded, atTarget.alias, atTarget.seat, rawMsg);
+            return;
+        }
+        // remote <alias> <seat> <msg...>
+        const alias = sub.replace(/^@/, "");
+        const seat = tail[0];
+        const rawMsg = tail.slice(1).join(" ").trim();
+        if (!seat || !rawMsg) {
+            console.error('usage: remote <alias> <seat> "<msg>"');
+            console.error('   or: remote @alias:seat "<msg>"');
+            console.error("   or: remote [--json]   # list meshes");
+            process.exit(2);
+        }
+        if (!/^[a-z][a-z0-9-]{0,31}$/i.test(alias) || !/^[a-z][a-z0-9-]{0,31}$/i.test(seat)) {
+            console.error(`bad remote target: ${alias} ${seat} (want alias seat, e.g. pia secretary)`);
+            process.exit(2);
+        }
+        runRemotePeer(loaded, alias.toLowerCase(), seat.toLowerCase(), rawMsg);
+        return;
+    }
     if (cmd === "profile" && sub === "show") {
         const loaded = meshLoaded(profileArg);
         const paths = profilePaths(loaded);
@@ -372,9 +590,52 @@ async function main() {
             sessionStatus(loaded);
             return;
         }
-        console.error("usage: session attach|up|down|status|sync|init <sm-name>");
+        if (sub === "check") {
+            const r = runSessionCheck(loaded);
+            printSessionCheck(r);
+            process.exit(r.ok ? 0 : 1);
+        }
+        if (sub === "repair") {
+            const noSync = tail.includes("--no-sync");
+            const skipInbox = tail.includes("--no-inbox");
+            const r = runSessionRepair(loaded, { sync: !noSync, skipInbox });
+            printSessionRepair(r);
+            process.exit(r.check.ok ? 0 : 1);
+        }
+        console.error("usage: session attach|up|down|status|sync|check|repair|init <sm-name>");
         process.exit(2);
     }
+    if (cmd === "config") {
+        const { runConfigCheck, printConfigHelp, printConfigUpgradeGuide } = await import("./commands/config-cli.js");
+        const json = rest.includes("--json") || sub === "--json" || tail.includes("--json");
+        if (!sub || sub === "help" || sub === "-h" || sub === "--help") {
+            printConfigHelp();
+            return;
+        }
+        if (sub === "check") {
+            process.exit(runConfigCheck(profileArg, { json }));
+        }
+        if (sub === "upgrade" || sub === "up") {
+            printConfigUpgradeGuide();
+            return;
+        }
+        console.error("usage: config check [--json] | config upgrade");
+        process.exit(2);
+    }
+    if (cmd === "tp") {
+        const loaded = meshLoaded(profileArg);
+        const { runTpCommand } = await import("./commands/tp-cli.js");
+        await runTpCommand(loaded, sub, tail);
+        return;
+    }
+    if (cmd === "web" || cmd === "open-web") {
+        const loaded = meshLoaded(profileArg);
+        const { runWebCommand, runWebOpen } = await import("./commands/web-cli.js");
+        if (cmd === "open-web") {
+            process.exit(runWebOpen(sub));
+        }
+        process.exit(await runWebCommand(loaded, sub, tail));
+    }
     if (cmd === "verify") {
         const loaded = meshLoaded(profileArg);
         ensureMeshInbox(loaded, { quiet: true });
@@ -620,12 +881,13 @@ async function main() {
     }
     if (cmd === "peer") {
         const loaded = meshLoaded(profileArg);
+        const redirDefaults = resolveAckRedirectDefaults(loaded);
         let direct = false;
         let endedId;
         let redirectFrom;
-        let redirectBlock = "*managers";
-        let redirectTo = "secretary";
-        let redirectTtlMin = 45;
+        let redirectBlock = redirDefaults.block;
+        let redirectTo = redirDefaults.rewriteTo;
+        let redirectTtlMin = redirDefaults.ttlMin;
         const args = [];
         const rawArgs = [sub, ...tail].filter((x) => x != null && x !== "");
         for (let i = 0; i < rawArgs.length; i++) {
@@ -637,8 +899,9 @@ async function main() {
             if (a === "--ended" || a === "--ack") {
                 const id = rawArgs[i + 1];
                 if (!id || id.startsWith("-")) {
-                    console.error("usage: peer … --ended <ack-id>");
-                    process.exit(2);
+                    // Bare --ack / --ended: auto-pick open ACK for this peer target.
+                    endedId = "__auto__";
+                    continue;
                 }
                 endedId = id;
                 i++;
@@ -682,7 +945,7 @@ async function main() {
                     console.error("usage: peer … --redirect-ttl <minutes>");
                     process.exit(2);
                 }
-                redirectTtlMin = Number(v) || 45;
+                redirectTtlMin = Number(v) || redirDefaults.ttlMin;
                 i++;
                 continue;
             }
@@ -700,9 +963,32 @@ async function main() {
         const [target, ...textParts] = args;
         const rawMsg = textParts.join(" ").trim();
         if (!target || !rawMsg) {
-            console.error("usage: peer verify [target] | peer [--direct] [--ended <ack-id>] [--redirect-from <seat>] <manager|secretary|slot-N|mini-N|@alias:seat|pane> <msg...>");
+            console.error("usage: peer verify [target] | peer [--direct] [--ended|--ack [ack-id]] [--redirect-from <seat>] <target> <msg...>\n" +
+                "  --ack / --ended [id]  close open ask (id optional = auto-match from target)\n" +
+                "  ack-class msg (ACK/FYI/PASS) auto-closes matching open ask\n" +
+                "  or: agent ack reply <id> [msg]  (peer back + close in one shot)");
             process.exit(2);
         }
+        if (shouldAutoAckReply(rawMsg, endedId)) {
+            endedId = "__auto__";
+        }
+        try {
+            const resolvedEnded = await resolvePeerEndedAckId(loaded, target, endedId);
+            endedId = resolvedEnded;
+        }
+        catch (e) {
+            if (endedId === "__auto__") {
+                console.error(`WARN: --ack auto: ${e.message}`);
+                endedId = undefined;
+            }
+            else {
+                throw e;
+            }
+        }
+        if (endedId === "__auto__") {
+            console.error(`WARN: --ack auto: no open ask matching ${target} — peer sent without close`);
+            endedId = undefined;
+        }
         const armRedirect = async (fromSeat, reason) => {
             const cfg = chatRoomConfigForLoaded(loaded);
             try {
@@ -905,6 +1191,7 @@ async function main() {
                 "claude",
                 "kiro",
                 "opencode",
+                "oc-proxy",
                 "cursor-agent",
                 "oc",
                 "cursor",
@@ -936,7 +1223,10 @@ async function main() {
                 saveMeshSession(loaded, reg);
                 return;
             }
-            secretaryRestart(loaded, reg, typeArg, fresh);
+            runSwitch(loaded, reg, "secretary", typeArg ?? defaultHarnessTypeForSeat(loaded, "secretary"), {
+                fresh,
+                reason: fresh ? "restart-fresh" : "restart",
+            });
             saveMeshSession(loaded, reg);
             return;
         }
@@ -1035,16 +1325,59 @@ async function main() {
         }
         return;
     }
+    if (cmd === "pane") {
+        const loaded = meshLoaded(profileArg);
+        const reg = createRegistryForProfile(loaded.profile);
+        const action = sub ?? "help";
+        if (action === "help" || action === "-h" || action === "--help") {
+            console.log(`pane — pane helpers (operator)
+
+  pane resume [target]     autodetect session id on pane → resume / relaunch
+  Targets: here (default) | secretary | manager | slot-N | mini-N
+
+  Live OpenCode: pastes resume [ses_…]
+  Shell / dead OC: relaunches oc-proxy|opencode|claude with that session`);
+            return;
+        }
+        if (action === "resume") {
+            requireCoordRole(loaded, "pane resume");
+            const target = tail.find((t) => !t.startsWith("-")) ?? "here";
+            try {
+                const r = runPaneResume(loaded, reg, target);
+                if (!r.ok) {
+                    console.error(`FAIL: pane resume ${r.target} pane=${r.paneId}: ${r.detail}`);
+                    process.exit(1);
+                }
+                console.log(`OK: pane resume ${r.mode} ${r.target} pane=${r.paneId} session=${r.sessionId} ${r.harnessType} — ${r.detail}`);
+                if (r.mode === "relaunch")
+                    saveMeshSession(loaded, reg);
+            }
+            catch (e) {
+                console.error(e.message);
+                process.exit(1);
+            }
+            return;
+        }
+        console.error(`usage: pane resume [target]\n  unknown: pane ${action}`);
+        process.exit(2);
+    }
     if (cmd === "ppa") {
         const loaded = meshLoaded(profileArg);
         const reg = createRegistryForProfile(loaded.profile);
-        const ppaSub = sub ?? "perf-index";
-        if (ppaSub !== "perf-index" && ppaSub !== "index") {
-            console.error("usage: ppa [perf-index]");
-            process.exit(2);
+        const args = [sub, ...tail].filter((a) => Boolean(a));
+        const raw = args.includes("--raw") || args.includes("perf-index") || args.includes("index");
+        const idleIdx = args.findIndex((a) => a === "--idle" || a === "--idle-sec");
+        const idleSec = idleIdx >= 0 && args[idleIdx + 1] ? Number.parseInt(args[idleIdx + 1], 10) : undefined;
+        if (args.some((a) => a === "-h" || a === "--help" || a === "help")) {
+            const { printCmdHelp } = await import("./commands/help-text.js");
+            printCmdHelp("ppa");
+            return;
         }
         try {
-            runPpa(loaded, reg);
+            runPpa(loaded, reg, {
+                raw,
+                idleSec: idleSec != null && Number.isFinite(idleSec) ? idleSec : undefined,
+            });
         }
         catch (e) {
             console.error(e.message);
@@ -1057,6 +1390,19 @@ async function main() {
         printSeatContexts(loaded, rest.includes("--json"));
         return;
     }
+    if (cmd === "hub" || cmd === "get") {
+        const loaded = meshLoaded(profileArg);
+        await runAgentHub(loaded, [sub, ...tail].filter((x) => x != null && x !== ""));
+        return;
+    }
+    // Discoverable aliases — no literal "read-history" existed; map to chat + room tip.
+    if (cmd === "read-history" || cmd === "history" || cmd === "readhistory") {
+        const loaded = meshLoaded(profileArg);
+        const extra = [sub, ...tail].filter((x) => x != null && x !== "");
+        await runAgentHub(loaded, ["chat", ...extra]);
+        console.log("also: seatmesh agent room tail [-r slug] [-n N]  ·  hub room");
+        return;
+    }
     if (cmd === "cold-start" || cmd === "coldstart") {
         const loaded = meshLoaded(profileArg);
         const inject = rest.includes("--inject");
@@ -1093,6 +1439,11 @@ async function main() {
         runSeatCommand(loaded, [sub, ...tail]);
         return;
     }
+    if (cmd === "todo" || cmd === "todos") {
+        const loaded = meshLoaded(profileArg);
+        runSeatCommand(loaded, ["task", ...(sub ? [sub, ...tail] : tail)]);
+        return;
+    }
     if (cmd === "test") {
         const loaded = meshLoaded(profileArg);
         ensureMeshInbox(loaded, { quiet: true });
@@ -1161,6 +1512,7 @@ async function main() {
             manager,
         });
         console.log(`SENT: prompt -> ${targetLabel} pane=${paneId} token=${token ?? "-"} via=${via ?? "pane-row"}`);
+        console.log('hint: prefer `todo give` (work) or `ask`/`msg`/`peer` (comms) over bare `prompt`');
         return;
     }
     if (cmd === "remind") {
@@ -1306,6 +1658,28 @@ async function main() {
         }
         return;
     }
+    if (cmd === "swap") {
+        const loaded = meshLoaded(profileArg);
+        requireCoordRole(loaded, "swap");
+        const a = sub;
+        const b = tail.find((t) => !t.startsWith("-"));
+        if (!a || !b) {
+            console.error("usage: swap <slot-A|mini-A> <slot-B|mini-B> [--identity]\n" +
+                "  default: visual tmux swap-pane (session data stays with each agent)\n" +
+                "  --identity: exchange numbers + seat dirs + mesh-agents (peer addresses swap)");
+            process.exit(2);
+        }
+        const identity = tail.includes("--identity");
+        try {
+            const result = runSeatSwap(loaded, a, b, { identity });
+            console.log(`OK: swap ${result.mode} ${result.a} ↔ ${result.b} (${result.paneA} ↔ ${result.paneB})`);
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exit(1);
+        }
+        return;
+    }
     if (cmd === "report") {
         const loaded = meshLoaded(profileArg);
         const { printStatusReport } = await import("./report/status-report.js");
@@ -1374,7 +1748,35 @@ async function main() {
     if (cmd === "agent") {
         const loaded = meshLoaded(profileArg);
         const reg = createRegistryForProfile(loaded.profile);
+        // agent help / agent --help — never UNAUTHORIZED; teach the card + per-cmd usage.
+        if (!sub ||
+            sub === "help" ||
+            sub === "-h" ||
+            sub === "--help") {
+            if (sub === "help" && tail[0] && !tail[0].startsWith("-")) {
+                const { printCmdHelp } = await import("./commands/help-text.js");
+                if (!printCmdHelp(tail[0]))
+                    process.exit(2);
+                return;
+            }
+            if (sub === "help" || sub === "-h" || sub === "--help") {
+                const { printAgentHelpIndex } = await import("./commands/help-text.js");
+                printAgentHelpIndex();
+                const w = runWhoami(loaded, "here");
+                printAgentCard(w);
+                return;
+            }
+            // bare `agent` — card only (+ one help hint)
+            const w = runWhoami(loaded, "here");
+            printAgentCard(w);
+            console.log("help=seatmesh agent help <cmd>  # usage for one verb");
+            return;
+        }
         if (sub && AGENT_META.has(sub)) {
+            if (sub === "forum" || sub === "golf") {
+                console.log("agent forum/golf — see docs/cli/forum.md (not bundled in this build)");
+                return;
+            }
             if (sub === "apply") {
                 const { bundle, opts } = parseAgentApplyArgs(tail);
                 applyAgentContractBundle(loaded, reg, bundle, opts);
@@ -1409,6 +1811,7 @@ async function main() {
                 printAgentUnauthorized(decision);
                 process.exit(2);
             }
+            process.env.SEATMESH_AGENT_GATEWAY = "1";
             process.argv = stripAgentFromArgv(process.argv);
             return main();
         }
@@ -1645,6 +2048,19 @@ async function main() {
             : cmd === "contract"
                 ? buildContractLockCommands(getLoaded)
                 : buildChatCommands(getLoaded);
+        // contract with no sub → status (simple agent path)
+        if (!sub && cmd === "contract") {
+            try {
+                await branch.parseAsync(["status"], { from: "user" });
+            }
+            catch (e) {
+                const err = e;
+                if (err.code === "commander.helpDisplayed" || err.code === "commander.version")
+                    return;
+                throw e;
+            }
+            return;
+        }
         if (!sub) {
             branch.outputHelp();
             return;
@@ -1783,7 +2199,7 @@ async function main() {
         return;
     }
     console.error(`unknown command: ${cmd}`);
-    usage();
+    console.error("hint: seatmesh help · seatmesh help human · seatmesh --agents help");
     process.exit(2);
 }
 main().catch((e) => {