toolroll 0.5.0

package/dist/surface.js

@@ -0,0 +1,352 @@
+import { KNOWLEDGE_DESCRIPTORS } from "./knowledge-cli.js";
+import { MEMORY_DESCRIPTORS } from "./memory-cli.js";
+import { MODELS_DESCRIPTORS } from "./models-cli.js";
+/**
+ * The declared command guide (arc 5): the agent-facing surface as data,
+ * dumped by `contract --commands`. This is DOCUMENTATION with a stable
+ * shape, not authority — legacy verbs do not execute from it,
+ * and the runtime envelope remains the truth. Its honest limits ride the
+ * envelope itself as SURFACE_NOTES, because a source comment is invisible
+ * to consumers (arc-5 review, finding 1).
+ *
+ * What the tests DO hold to the code: every root here is a routed verb
+ * and every routed verb appears here; every declared flag lives in the
+ * parser's global vocabulary with the declared arity; the subcommand
+ * inventories for task/publish/config/approver/routine/contest match the
+ * exported action lists their dispatchers consult; keyed mutations
+ * declare --key; notableReasons come from DOCUMENTED_REASONS. What they
+ * CANNOT prove — that a given flag is read by a given handler — is why
+ * SURFACE_NOTES.flags says "intended".
+ */
+import { SESSION_DESCRIPTORS } from './session-contract.js';
+import { sessionCliFlags } from './session-cli.js';
+/** The guide's limits, stated machine-readably in every dump. */
+export const SURFACE_NOTES = {
+    authority: "documentation is not permission; session descriptors also drive parser and request validation; legacy entries remain advisory",
+    flags: "session flags are exact per operation; legacy flags are intended per command and may use a global parser vocabulary",
+    reasons: "curated, not exhaustive — the runtime `reason` field is the truth; ignore tokens you do not recognize",
+    database: "local database commands wait up to 15 seconds for another writer; an exhausted wait returns database-busy and names the selected file",
+};
+export const SURFACE_SCHEMA_VERSION = 1;
+const jsonFlag = { name: "json", takesValue: false, meaning: "answer with one machine envelope on stdout" };
+const keyFlag = { name: "key", takesValue: true, meaning: "idempotency key — retry with the same key to get the first answer back" };
+const dbFlag = { name: "db", takesValue: true, meaning: "path to the database file (defaults to the installation's)" };
+const repoFlag = { name: "repo", takesValue: true, meaning: "which repository (repeatable where a command watches several)" };
+const operator = (invocation, synopsis) => ({
+    invocation,
+    synopsis,
+    audience: "operator",
+    agentMayInvoke: false,
+    mutation: "unkeyed",
+});
+const operatorRead = (invocation, synopsis) => ({
+    invocation,
+    synopsis,
+    audience: "operator",
+    agentMayInvoke: false,
+    mutation: "none",
+});
+export const COMMAND_GUIDE = [
+    // ---- reports (reads) ----
+    {
+        invocation: "",
+        envelopeCommand: "scan",
+        synopsis: "report what is in flight (the no-verb default; scans below the working directory or the connected repositories)",
+        audience: "agent",
+        agentMayInvoke: true,
+        mutation: "none",
+        positionals: [{ name: "path", required: false, meaning: "directories to scan instead of the connected set" }],
+        flags: [jsonFlag,
+            { name: "all", takesValue: false, meaning: "ignore connected repos; scan everything discoverable" },
+            { name: "local", takesValue: false, meaning: "branches only — no network" }],
+    },
+    { invocation: "pulls", synopsis: "report what is waiting on a person", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag] },
+    { invocation: "graph", synopsis: "report which work graph is already here", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag] },
+    { invocation: "repos", synopsis: "list connected repositories", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag] },
+    operator("proposals", "what coordinators proposed over the MCP gateway — list, confirm <id> [--yes], dismiss <id>; confirming runs the plane's own door under your password"),
+    operator("chat", "with a saved profile, --lead <id> --conversation <id> opens central chat; --say sends one message, --follow only reads updates, --authorize --terms-digest enables the displayed paid terms; --local uses the existing local coordinator, where --follow enables crew updates and --no-follow pauses them; proposals keep their approval requirements"),
+    operator('connect', 'save an authenticated central HTTPS profile with --as and --token-stdin or --token-file; --local-login explicitly uses the existing private local sign-in; secrets never belong in arguments or URLs'),
+    operatorRead('lead list', 'list central leads available to the signed-in account; --profile selects a saved connection'),
+    operator('lead create', 'create a central lead with --name, --instructions and repeatable --project paths admitted by the server'),
+    operator('lead update', 'change --name, --instructions or --status for --lead at --revision; projects remain fixed'),
+    operator('lead member', 'set --account membership on --lead with --role, --active true|false and the current --revision'),
+    operator('lead transfer', 'move ownership of --task to --lead at --revision; existing execution authority remains unchanged'),
+    operatorRead('conversation list', 'list admitted conversations, optionally within --lead; attachment never starts model work'),
+    operator('conversation create', 'create a conversation with --lead, --title, --visibility private|team and repeatable --project paths'),
+    operatorRead('conversation show', 'read --conversation messages and saved work; no model call or read-marker mutation'),
+    operator('conversation member', 'set --account membership on --conversation with --role, --active true|false and the current --revision; lead membership must already permit the role'),
+    operator('conversation edit', 'edit your queued --message in --conversation at --revision using --text; running messages cannot be edited'),
+    operator('conversation withdraw', 'withdraw your queued --message in --conversation at --revision; an active turn requires stop'),
+    operator('conversation read', 'explicitly record your read position at --message within --conversation'),
+    operator('conversation follow', 'enable or pause automatic lead summaries with --conversation and --enabled true|false, within the existing paid chat authorization; passive chat --follow only reads updates'),
+    operator('conversation stop', 'request stopping the exact --message in --conversation; retain uncertain work until its owner settles it'),
+    operator("repos add", "connect a repository to the installation"),
+    operator("repos remove", "disconnect a repository"),
+    operator("repos add-from-github", "preview, clone from GitHub, and connect - the console onboarding ceremony as a CLI verb"),
+    { invocation: "contract", synopsis: "the machine contract: envelope version + capability tokens; --commands dumps this guide", audience: "agent", agentMayInvoke: true, mutation: "none",
+        flags: [jsonFlag, { name: "commands", takesValue: false, meaning: "dump the declared command guide" }] },
+    { invocation: "skills list", synopsis: "name the guides this exact binary serves", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag] },
+    { invocation: "skills get", synopsis: "print one guide's markdown (raw on stdout; --json wraps it)", audience: "agent", agentMayInvoke: true, mutation: "none",
+        positionals: [{ name: "name", required: true, meaning: "a guide name from `skills list`" }],
+        flags: [jsonFlag], notableReasons: ["unknown-skill", "usage"] },
+    {
+        invocation: "skills install",
+        synopsis: "install or refresh this binary's Toolroll guides for Claude Code; without --claude-code, write the repository-local Agent Skills entry",
+        audience: "operator",
+        agentMayInvoke: false,
+        mutation: "identity-idempotent",
+        flags: [jsonFlag,
+            { name: "claude-code", takesValue: false, meaning: "install the user-level Claude Code skill" },
+            { name: "dir", takesValue: true, meaning: "skill directory (default: ~/.claude/skills/toolroll)" },
+            { name: "yes", takesValue: false, meaning: "write the previewed files" },
+            { name: "repo", takesValue: true, meaning: "repository for the existing project-local install" },
+            { name: "write-context", takesValue: false, meaning: "also add the managed AGENTS.md block for a project-local install" }],
+        notableReasons: ["unconfirmed", "foreign-file", "usage"],
+    },
+    operator("link", "put toolroll on PATH"),
+    operator("unlink", "take it off PATH"),
+    operator("demo", "a seeded throwaway sandbox"),
+    { invocation: 'session capabilities', synopsis: 'Show executable session schemas and operator authority requirements; no credentials needed', audience: 'agent', agentMayInvoke: true, mutation: 'none', flags: [jsonFlag] },
+    ...SESSION_DESCRIPTORS.map(spec => ({
+        invocation: `session ${spec.operation}`, synopsis: spec.synopsis, audience: spec.audience, agentMayInvoke: spec.agentMayInvoke,
+        mutation: spec.mutation ? 'keyed' : 'none', inputSchema: spec.inputSchema,
+        flags: Object.entries(sessionCliFlags(spec)).map(([name, arity]) => ({ name, takesValue: arity === 'value', meaning: name === 'key' ? 'keep the same key when reconciling; inspect after unknown delivery, never blind-retry' : `see session ${spec.operation} --help` })),
+    })),
+    ...KNOWLEDGE_DESCRIPTORS.map(spec => ({ invocation: `knowledge ${spec.action}`, synopsis: spec.synopsis, audience: "agent", agentMayInvoke: true, mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "query", required: true, meaning: "search text or source file for impact" }] } : {}) })),
+    ...MEMORY_DESCRIPTORS.map(spec => ({ invocation: `memory ${spec.action}`, synopsis: spec.synopsis, audience: "agent", agentMayInvoke: true, mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "query", required: true, meaning: "search text, a decision id, or the decision sentence" }] } : {}) })),
+    ...MODELS_DESCRIPTORS.map(spec => ({ invocation: `models ${spec.action}`, synopsis: spec.synopsis, audience: "agent", agentMayInvoke: true, mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "target", required: true, meaning: "the CLI to update, or on/off" }] } : {}) })),
+    // ---- the queue (agent surface) ----
+    { invocation: "status", synopsis: "running work, queued reasons, results to review, the latest release check and plan windows", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "ready", synopsis: "what could be dispatched right now (rows carry reservedFor)", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "brief", synopsis: "with a saved central profile, --lead <id> --conversation <id> reads messages, proposals and saved work; --request-id inspects your saved receipt without resending; --local uses local DB catch-up, where --history selects the older operational report", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "gaps", synopsis: "requirement gaps blocking dispatch", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag, repoFlag] },
+    { invocation: "grants", synopsis: "list authority grants", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "sync", synopsis: "refresh external-tracker mirrors and deliver write-backs — safe to run; fails closed", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
+        flags: [jsonFlag, dbFlag, repoFlag], notableReasons: ["no-op", "external"] },
+    { invocation: "task add", synopsis: "queue work", audience: "agent", agentMayInvoke: true, mutation: "keyed",
+        positionals: [{ name: "title", required: true, meaning: "one line of what to do" }],
+        flags: [jsonFlag, dbFlag, keyFlag,
+            { name: "id", takesValue: true, meaning: "choose the task id" },
+            { name: "repo", takesValue: true, meaning: "which repository the task belongs to" },
+            { name: "report", takesValue: false, meaning: "a scout task: the deliverable is a report, never a branch" }],
+        notableReasons: ["duplicate", "usage"] },
+    { invocation: "task list", synopsis: "a page of saved task status", audience: "agent", agentMayInvoke: true, mutation: "none",
+        flags: [jsonFlag, dbFlag, { name: "state", takesValue: true, meaning: "queued|running|done|failed|cancelled" },
+            { name: "view", takesValue: true, meaning: "all|needs-you|running|completed" },
+            { name: "limit", takesValue: true, meaning: "page size, 1–100; default 40" },
+            { name: "cursor", takesValue: true, meaning: "nextCursor from the previous response" },
+            { name: "repo", takesValue: true, meaning: "filter to one project" }] },
+    { invocation: "task show", synopsis: "one task in full", audience: "agent", agentMayInvoke: true, mutation: "none",
+        positionals: [{ name: "id", required: true, meaning: "the task" }], flags: [jsonFlag, dbFlag], notableReasons: ["unknown-task"] },
+    { invocation: "check-progress", synopsis: "current or final approved check progress", audience: "agent", agentMayInvoke: true, mutation: "none",
+        positionals: [{ name: "run", required: true, meaning: "the build run" }], flags: [jsonFlag, dbFlag], notableReasons: ["unknown-run", "no-progress"] },
+    { invocation: "task wait", synopsis: "wait for the current attempt to finish or need a person", audience: "agent", agentMayInvoke: true, mutation: "none",
+        positionals: [{ name: "id", required: true, meaning: "the task" }], flags: [jsonFlag, dbFlag,
+            { name: "timeout", takesValue: true, meaning: "stop waiting after this many seconds" }], notableReasons: ["unknown-task", "timeout", "failed", "needs-person"] },
+    { invocation: "project show", synopsis: "show the saved local project and optional credential-file reference", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "project use", synopsis: "select an exact saved checkout; grants no project or execution authority", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
+        positionals: [{ name: "path", required: true, meaning: "exact saved project checkout path" }], flags: [jsonFlag, dbFlag, { name: "token-file", takesValue: true, meaning: "optional existing scoped coordinator credential file; saves only its path" }] },
+    ...['complete', 'revise'].map(action => ({
+        invocation: `task ${action}`, synopsis: action === 'complete' ? 'mark the exact inspected result complete; checks and permissions remain unchanged' : 'request a same-task revision using explicit feedback; existing approval terms apply',
+        audience: 'agent', agentMayInvoke: true, mutation: 'identity-idempotent',
+        positionals: [{ name: 'task', required: true, meaning: 'task or assignment id' }],
+        flags: [jsonFlag, dbFlag,
+            { name: 'token-env', takesValue: true, meaning: 'scoped coordinator credential environment variable' },
+            { name: 'token-file', takesValue: true, meaning: 'scoped coordinator credential file; defaults to selected project reference' },
+            ...(action === 'complete' ? [{ name: 'digest', takesValue: true, meaning: 'exact receipt from assignment show; required for JSON or scoped agents' }]
+                : [{ name: 'feedback', takesValue: true, meaning: 'specific requested change' }, { name: 'run', takesValue: true, meaning: 'exact result run; defaults to current result' }, { name: 'source', takesValue: true, meaning: 'exact scope digest; defaults to current terms' }, { name: 'key', takesValue: true, meaning: '32 hexadecimal characters for exact replay; defaults to a stable feedback identity' }]),
+        ],
+    })),
+    ...["show", "updates", "claim", "check", "brief", "inbox", "ack"].map(action => ({
+        invocation: `assignment ${action}`,
+        synopsis: action === "show" ? "read the root, current work, owner and exact receipt"
+            : action === "updates" ? "read durable updates after a cursor; save nextCursor after processing"
+                : action === "claim" ? "record coordinator lead ownership; grants no approval or execution authority"
+                    : action === "brief" ? "catch up from current assignments and project knowledge in the local database"
+                        : action === "inbox" ? "receive or replay a saved batch of lead status updates"
+                            : action === "ack" ? "acknowledge delivery of an inbox batch; leaves task completion unchanged"
+                                : "acknowledge the exact ready receipt as its lead; accepts no proof and deploys nothing",
+        audience: "agent", agentMayInvoke: true,
+        mutation: action === "claim" || action === "check" || action === "inbox" || action === "ack" ? "identity-idempotent" : "none",
+        ...(["show", "claim", "check"].includes(action) ? { positionals: [{ name: "task", required: true, meaning: "any task in the assignment's existing correction chain" }] } : {}),
+        flags: [jsonFlag, dbFlag,
+            { name: "token-env", takesValue: true, meaning: "explicit environment variable containing a coordinator token; required for claim/check/inbox/ack unless token-file is used" },
+            { name: "token-file", takesValue: true, meaning: "explicit coordinator token file; cannot be combined with token-env" },
+            ...(action === "updates" ? [{ name: "after", takesValue: true, meaning: "last processed admitted update cursor; defaults to 0" }, { name: "limit", takesValue: true, meaning: "page size from 1 to 100; defaults to 50" }] : []),
+            ...(action === "check" ? [{ name: "digest", takesValue: true, meaning: "exact current receipt digest from assignment show" }] : []),
+            ...(action === "brief" ? [{ name: "repo", takesValue: true, meaning: "project to include within the credential's access" }, { name: "limit", takesValue: true, meaning: "assignment count from 1 to 25; defaults to 10" }] : []),
+            ...(action === "inbox" || action === "ack" ? [{ name: "consumer", takesValue: true, meaning: "stable lowercase name for this lead's delivery cursor" }] : []),
+            ...(action === "inbox" ? [{ name: "limit", takesValue: true, meaning: "batch size from 1 to 100; defaults to 10" }] : []),
+            ...(action === "ack" ? [{ name: "batch", takesValue: true, meaning: "exact batch ID returned by assignment inbox" }] : []),
+        ],
+    })),
+    operator("task state", "set a task's state by hand — an operator correction, not a workflow step"),
+    { invocation: "task block", synopsis: "make one task wait for another", audience: "agent", agentMayInvoke: true, mutation: "keyed",
+        positionals: [{ name: "id", required: true, meaning: "the waiting task" }],
+        flags: [jsonFlag, dbFlag, keyFlag, { name: "on", takesValue: true, meaning: "the blocker's id" }],
+        notableReasons: ["unknown-task", "contest-open"] },
+    { invocation: "task unblock", synopsis: "stop waiting", audience: "agent", agentMayInvoke: true, mutation: "keyed",
+        positionals: [{ name: "id", required: true, meaning: "the waiting task" }],
+        flags: [jsonFlag, dbFlag, keyFlag, { name: "on", takesValue: true, meaning: "the blocker's id" }],
+        notableReasons: ["unknown-task"] },
+    { invocation: "task next", synopsis: "move a task to the front of ITS queue (scheduling only; approval still required)", audience: "agent", agentMayInvoke: true, mutation: "keyed",
+        positionals: [{ name: "id", required: true, meaning: "the task" }],
+        flags: [jsonFlag, dbFlag, keyFlag, { name: "undo", takesValue: false, meaning: "back to filing order" }],
+        notableReasons: ["unknown-task", "claimed", "contest-open"] },
+    operator("task steer", "one credentialed note read before the task's next attempt — steering speaks with the operator's voice"),
+    { invocation: "task assign", synopsis: "reserve a task for one worker, or return it to the shared queue", audience: "agent", agentMayInvoke: true, mutation: "keyed",
+        positionals: [{ name: "id", required: true, meaning: "the task" }],
+        flags: [jsonFlag, dbFlag, keyFlag,
+            { name: "runner", takesValue: true, meaning: "the worker to reserve for" },
+            { name: "anyone", takesValue: false, meaning: "back to the shared queue" }],
+        notableReasons: ["unknown-task", "claimed"] },
+    { invocation: "task scope", synopsis: "state what success is; approval binds to this exact statement", audience: "agent", agentMayInvoke: true, mutation: "keyed",
+        positionals: [{ name: "id", required: true, meaning: "the task" }],
+        flags: [jsonFlag, dbFlag, keyFlag,
+            { name: "goal", takesValue: true, meaning: "what success is" },
+            { name: "not", takesValue: true, meaning: "explicitly out of scope" },
+            { name: "touches", takesValue: true, meaning: "comma-separated paths this may change" },
+            { name: "budget-usd", takesValue: true, meaning: "spend ceiling for the build" },
+            { name: "risk", takesValue: true, meaning: "declared risk: routine, elevated, or high — the route reads it" }],
+        notableReasons: ["unknown-task", "contest-open"] },
+    { invocation: "task plan", synopsis: "ask for a plan document (a planning session drafts; a person approves)", audience: "agent", agentMayInvoke: true, mutation: "keyed",
+        positionals: [{ name: "id", required: true, meaning: "the task" }],
+        flags: [jsonFlag, dbFlag, keyFlag,
+            { name: "provider", takesValue: true, meaning: "pin which provider plans THIS task (plan phase only)" },
+            { name: "model", takesValue: true, meaning: "the pinned plan model, riding --provider" }],
+        notableReasons: ["unknown-task"] },
+    { invocation: "task hold", synopsis: "park a task with a reason", audience: "agent", agentMayInvoke: true, mutation: "keyed",
+        positionals: [{ name: "id", required: true, meaning: "the task" }],
+        flags: [jsonFlag, dbFlag, keyFlag,
+            { name: "reason", takesValue: true, meaning: "why it waits" },
+            { name: "until", takesValue: true, meaning: "ISO time to resurface" }],
+        notableReasons: ["unknown-task", "held"] },
+    { invocation: "task unhold", synopsis: "release a hold", audience: "agent", agentMayInvoke: true, mutation: "keyed",
+        positionals: [{ name: "id", required: true, meaning: "the task" }],
+        flags: [jsonFlag, dbFlag, keyFlag], notableReasons: ["unknown-task", "not-yours"] },
+    { invocation: "task require", synopsis: "name the capabilities a task needs before dispatch", audience: "agent", agentMayInvoke: true, mutation: "keyed",
+        positionals: [{ name: "id", required: true, meaning: "the task" }],
+        flags: [jsonFlag, dbFlag, keyFlag, { name: "require", takesValue: true, meaning: "comma-separated capability keys" }],
+        notableReasons: ["unknown-task"] },
+    operator("task approve", "the yes — nothing builds without one; binds to the scope digest"),
+    operator("task requeue", "exit a stall: incidents resolved, strikes cleared, queued again"),
+    operator("task regate", "explicitly rerun the approved check on the last exact commit — no agent or automatic retry"),
+    operator("task review", "retired compatibility command; inspect the saved result and explicitly complete or revise it"),
+    operator("task accept", "record an explicit acceptance with limitations; does not change checks or prove deployment"),
+    operator("task repair", "inspect or approve an existing historical repair draft; use task revise for new feedback"),
+    operator("task route", "which configured agents plan, build and repair this task; phase and risk changes require renewed approval"),
+    operator("task reopen", "resume external work its tracker closed and has been SEEN open again"),
+    operator("task stop", "stop ONE exact live attempt (--run <id>): durable before any process is signalled, answers 'stopping' until its own processes are established gone; work, branch, and evidence preserved; no strike, no retry"),
+    operator("task resume", "resume the exact stopped attempt (--run <id>): refuses until it is quiescent, lifts only that stop's hold, approves nothing — the next pass re-proves the scope and inherits the draft with fresh proof"),
+    // ---- leases (runner surface) ----
+    { invocation: "claim", synopsis: "take one ready, approved task; answers with a lease", audience: "agent", agentMayInvoke: true, mutation: "keyed",
+        positionals: [{ name: "id", required: true, meaning: "the task" }],
+        flags: [jsonFlag, dbFlag, keyFlag,
+            { name: "runner", takesValue: true, meaning: "your registered worker name" },
+            { name: "token", takesValue: true, meaning: "the worker's token" },
+            { name: "ttl", takesValue: true, meaning: "lease seconds" }],
+        notableReasons: ["held", "fenced", "unapproved", "reserved", "external", "contest-open", "claimed", "not-ready"] },
+    { invocation: "heartbeat", synopsis: "still working; extends the lease", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
+        positionals: [{ name: "lease", required: true, meaning: "the lease id" }],
+        flags: [jsonFlag, dbFlag], notableReasons: ["not-leased", "fenced"] },
+    { invocation: "release", synopsis: "done with it; fenced if superseded", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
+        positionals: [{ name: "lease", required: true, meaning: "the lease id" }],
+        flags: [jsonFlag, dbFlag], notableReasons: ["not-leased", "fenced"] },
+    { invocation: "reap", synopsis: "release every lease that ran out", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent", flags: [jsonFlag, dbFlag] },
+    { invocation: "tick", synopsis: "one unattended pass: claim, build in a leased worktree, commit to a branch — never pushes", audience: "agent", agentMayInvoke: true, mutation: "unkeyed",
+        flags: [jsonFlag, dbFlag, repoFlag,
+            { name: "runner", takesValue: true, meaning: "your registered worker name" },
+            { name: "token", takesValue: true, meaning: "the worker's token" },
+            { name: "max", takesValue: true, meaning: "tasks this pass (default 1)" },
+            { name: "base", takesValue: true, meaning: "base ref for first attempts" }],
+        notableReasons: ["empty", "fenced"] },
+    { invocation: "build", synopsis: "build one claimed task directly (the piece tick automates)", audience: "agent", agentMayInvoke: true, mutation: "unkeyed",
+        positionals: [{ name: "id", required: true, meaning: "the task" }],
+        flags: [jsonFlag, dbFlag, repoFlag], notableReasons: ["not-leased", "unapproved"] },
+    { invocation: "reconcile", synopsis: "recover what the last stretch left behind — safe to repeat", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent", flags: [jsonFlag, dbFlag, repoFlag] },
+    // ---- reads over shared machinery ----
+    { invocation: "runner list", synopsis: "registered workers", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "coordinator list", synopsis: "MCP filing credentials and their limits", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "approver list", synopsis: "who can say yes (names only)", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "cap list", synopsis: "recorded capabilities", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag, repoFlag] },
+    { invocation: "outbox list", synopsis: "queued notifications", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "incident list", synopsis: "open incidents", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "routine list", synopsis: "scheduled routines", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "routine show", synopsis: "one routine in full", audience: "agent", agentMayInvoke: true, mutation: "none",
+        positionals: [{ name: "id", required: true, meaning: "the routine" }], flags: [jsonFlag, dbFlag] },
+    { invocation: "config show", synopsis: "phase and spend configuration", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag, repoFlag] },
+    { invocation: "setup show", synopsis: "installation setup", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "verify show", synopsis: "the repository's approved verification command, if one exists", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag, repoFlag] },
+    { invocation: "intake show", synopsis: "intake configuration", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "providers", synopsis: "which agent providers this binary can drive, and their transports; --report records this machine's readiness under its runner", audience: "agent", agentMayInvoke: true, mutation: "none",
+        flags: [jsonFlag,
+            { name: "report", takesValue: false, meaning: "record readiness observations under --runner" },
+            { name: "runner", takesValue: true, meaning: "the registered worker name reporting" },
+            { name: "token", takesValue: true, meaning: "that worker's token" }] },
+    { invocation: "template list", synopsis: "routine templates", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "template show", synopsis: "one template", audience: "agent", agentMayInvoke: true, mutation: "none",
+        positionals: [{ name: "name", required: true, meaning: "the template" }], flags: [jsonFlag, dbFlag] },
+    { invocation: "contest show", synopsis: "a tournament's state and results", audience: "agent", agentMayInvoke: true, mutation: "none",
+        positionals: [{ name: "id", required: true, meaning: "the contest" }], flags: [jsonFlag, dbFlag] },
+    { invocation: "webhook status", synopsis: "connected messaging services", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "publish status", synopsis: "publication and merge-grant state", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    // ---- operator ceremonies and infrastructure (listed, detail-free) ----
+    operator("approver add", "mint the credential that lets a person say yes"),
+    operator("runner register", "register a worker bound to its repositories; its token is shown once"),
+    operator("runner retire", "retire a worker"),
+    operator("runner bind", "replace which repositories a worker may build in"),
+    operator("runner capacity", "set how many tasks a worker runs at once; running work carries on, the new number applies at the next claim"),
+    operator("coordinator mint", "mint the MCP filing credential — repo-bound, rate-limited, token shown once"),
+    operator("coordinator revoke", "revoke an MCP filing credential"),
+    operator("mcp", "serve the MCP gateway over stdio — the coordinator credential is the only key it accepts"),
+    operator("cap add", "record a capability"),
+    operator("outbox deliver", "deliver queued notifications"),
+    operator("peek", "watch live agents in the terminal — one pane per open run; --tmux opens a window per run"),
+    operator("incident resolve", "resolve an incident"),
+    operator("decide", "read and ANSWER parked decisions — answering is a person's act"),
+    operator("routine add", "file a standing order"),
+    operator("routine approve", "approve a standing order"),
+    operator("routine refresh", "re-resolve the agents a standing order freezes from today's configuration — approves nothing; approve it again afterwards"),
+    operator("routine pause", "pause a standing order"),
+    operator("routine resume", "resume a standing order"),
+    operator("routine run-now", "run a standing order immediately"),
+    operatorRead("keys status", "which provider API keys are stored — never the values"),
+    operator("keys set", "store a provider's API key as a private file — piped or --key-file, never on the command line"),
+    operator("keys clear", "remove a stored provider key (kept only as a fallback; a subscription-mode provider is unaffected)"),
+    operatorRead("keys verify", "check a stored key against its provider live — spends no tokens"),
+    operator("keys auth", "choose subscription vs API key for a provider (subscription is the default; the key is kept as fallback)"),
+    operatorRead("people list", "everyone who can sign in, their standing, and the open invites"),
+    operator("people invite", "mint a single-use sign-in link for one person — their powers are pinned when you mint, never after"),
+    operator("people projects", "set a person's project access — selected project, all projects, or no projects"),
+    operator("people revoke", "end a person's access — their sessions, invites, and signed modes end with them; history stays"),
+    operatorRead("mode show", "the repository's operating mode, in full — or 'locked' when none is signed"),
+    operator("mode set", "sign a per-repository operating mode (password ceremony; standard or hands-off, always expiring)"),
+    operator("publish merge", "say yes to ONE waiting merge — it fires only when CI is seen green on the exact commit you authorized"),
+    operator("publish refire", "recover a merge whose issued call went silent — re-enters the full merge road, never auto-retried"),
+    operator("mode revoke", "revoke a repository's mode — one click, every act it covered falls back to its own ceremony"),
+    operator("config set", "set phase or spend configuration"),
+    operator("config clear", "clear phase or spend configuration"),
+    operator("setup clear", "clear installation setup"),
+    operator("verify set", "approve the one shell command the plane re-runs after every future commit; --self-heal binds one approved-setup replay when a required project executable is missing"),
+    operator("verify clear", "revoke a repository's approved verification command"),
+    operator("intake grant", "grant an intake source"),
+    operator("intake run", "run intake now"),
+    operator("intake preview", "preview what intake would file"),
+    operator("intake pr-comments", "intake review comments from a pull request"),
+    operator("intake clear", "clear intake configuration"),
+    operator("contest exclude", "exclude a contestant from a tournament"),
+    operator("webhook primary", "choose which service receives alerts"),
+    operator("webhook test", "send a test message"),
+    operator("bridge", "the Telegram bridge (pairing, tokens, the follower)"),
+    operator("enroll", "grant a repository authority (backends, dispatch) — its own explicit yes"),
+    operator("revoke", "take an authority grant back"),
+    operator("publish", "the publication pass: push built branches, open pull requests, sweep merges"),
+    operator("publish grant", "grant publication or auto-merge authority"),
+    operator("publish revoke", "take a publication grant back"),
+    operator("publish unblock", "lift a repair's merge hold"),
+    operator("publish rearm", "re-arm a refused merge after fixing the named cause"),
+    operator("serve", "the operations console (HTTP)"),
+    operator("watch", "the unattended loop, kept running"),
+    operator("up", "console + worker + browser, one command"),
+    operator("daemon", "install the loop under the OS service manager"),
+];

package/dist/sync.d.ts

@@ -0,0 +1,94 @@
+/**
+ * External dispatch's sync pass (v20; five review rounds are the spec).
+ *
+ * What this does: pulls a tracker's nominated work into the overlay as
+ * ORDINARY local tasks (mirrors), refreshes every known mirror's remote
+ * state, verifies the plane marker, and delivers pending write-back
+ * intents — all at daemon cadence, zero tokens.
+ *
+ * What this never does: touch claims or runs (the latch is a write to the
+ * mirror row; admission and completion enforce it), import issue BODIES
+ * (titles only, through the canonical proposal validator — a tracker
+ * anyone can write to is a prompt-injection surface), or treat absence
+ * from a capped listing as closure (every known mirror is fetched
+ * INDIVIDUALLY; only a COMPLETE pass advances freshness).
+ *
+ * The plane marker is detection, never a distributed lease: a fixed-name
+ * repository label carries this plane's id in its description. A 404 is
+ * semantic "missing" only AFTER an authenticated access proof on the
+ * repository itself — GitHub 404s private resources the caller cannot
+ * see, and that must read as an OPERATIONAL block, fail closed.
+ */
+import type { Runner } from "./backend.js";
+import type { BackendGrant } from "./grant.js";
+import type { Store } from "./store.js";
+export declare const SYNC_TIMEOUT_MS = 20000;
+export declare const MARKER_LABEL = "standing-orders-plane";
+/** Bounded forward scan: pages of 100, at most this many pages per pass. */
+export declare const MAX_FORWARD_PAGES = 10;
+export type RemoteIssue = {
+    number: number;
+    title: string;
+    state: "open" | "closed";
+};
+type Operational = {
+    ok: false;
+    kind: "operational";
+    message: string;
+};
+/** The gh surface the pass needs, injectable for tests. */
+export type DispatchAdapter = {
+    /** Authenticated access proof: 200 + push permission, or operational. */
+    repoAccess(remoteRepo: string): Promise<{
+        ok: true;
+        push: boolean;
+    } | Operational>;
+    /** Complete forward listing — complete=false when the page cap cut it. */
+    listAllOpen(remoteRepo: string): Promise<{
+        ok: true;
+        issues: RemoteIssue[];
+        complete: boolean;
+    } | Operational>;
+    /** One issue, individually — the reverse sweep's only evidence. */
+    getIssue(remoteRepo: string, number: string): Promise<{
+        ok: true;
+        found: RemoteIssue | null;
+    } | Operational>;
+    readMarker(remoteRepo: string): Promise<{
+        ok: true;
+        plane: string | null;
+        malformed: boolean;
+    } | Operational>;
+    writeMarker(remoteRepo: string, planeId: string): Promise<{
+        ok: true;
+    } | Operational>;
+    deleteMarker(remoteRepo: string): Promise<{
+        ok: true;
+    } | Operational>;
+    comment(remoteRepo: string, number: string, body: string): Promise<{
+        ok: true;
+    } | Operational>;
+    close(remoteRepo: string, number: string): Promise<{
+        ok: true;
+    } | Operational>;
+};
+export declare function ghDispatchAdapter(runner?: Runner, timeoutMs?: number): DispatchAdapter;
+/** ghi-<owner>-<name>-<n>-<hash8>: collision-resistant across long slugs. */
+export declare function mirrorTaskId(remoteRepo: string, remoteId: string): string;
+export type SyncReport = {
+    remoteRepo: string;
+    outcome: "complete" | "capped" | "failed" | "blocked";
+    detail: string | null;
+    candidates: number;
+    mirrored: number;
+    latched: number;
+    delivered: number;
+};
+/**
+ * One pass over one dispatch grant. Order is the spec's: access proof →
+ * marker verdict → forward scan → reverse sweep (every known mirror,
+ * individually) → intent delivery → ledger close. Only a pass in which
+ * EVERY step succeeded closes `complete` and advances freshness.
+ */
+export declare function syncPass(store: Store, grant: BackendGrant, adapter: DispatchAdapter, now: () => Date): Promise<SyncReport>;
+export {};