toolroll 0.9.43 → 0.9.45

package/dist/remote-exec.js

@@ -0,0 +1,241 @@
+/**
+ * Remote CLI, the client half (Phase 1). With an API token saved by `toolroll connect`, a command whose contract row
+ * says `remote: "yes"` is sent to the central server's `POST /api/cli` and runs there as you; its stdout, stderr and
+ * exit code come back byte for byte. `remote: "no"` runs on this computer exactly as before, and `remote: "step-up"`
+ * (approvals, people and policy) is refused here: those stay in the console or chat.
+ *
+ * Nothing here opens the local database or reads a saved owner login; it never prompts, and an uncertain answer to
+ * a mutation is never retried.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { envelopeJson } from './envelope.js';
+import { COMMAND_GUIDE } from './surface.js';
+import { centralProfile, UsageError } from './team-cli.js';
+import { CLI_FILES_BYTES, CLI_WAIT_SECONDS } from './cli-http.js';
+import { contractRow, fileArguments, STEP_UP_MESSAGE } from './remote-command.js';
+export { contractRow, STEP_UP_MESSAGE } from './remote-command.js';
+const EXIT = { ok: 0, failed: 1, usage: 2, refused: 3 };
+/** Team commands own their own central path (team-cli.ts). */
+const TEAM_COMMANDS = new Set(['connect', 'lead', 'conversation', 'chat', 'brief']);
+const RESPONSE_BYTES = 16 * 1024 * 1024;
+const REQUEST_TIMEOUT_MS = (CLI_WAIT_SECONDS + 35) * 1_000;
+async function bounded(response) {
+    if (!response.body)
+        throw new Error('empty');
+    const reader = response.body.getReader(), chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            size += chunk.value.byteLength;
+            if (size > RESPONSE_BYTES) {
+                await reader.cancel();
+                throw new Error('too-large');
+            }
+            chunks.push(chunk.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+}
+/** One request, never retried. */
+async function post(origin, token, request, options) {
+    try {
+        const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+        const response = await (options.fetch ?? fetch)(`${origin}/api/cli`, {
+            method: 'POST', redirect: 'manual', credentials: 'omit', signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout,
+            headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json', accept: 'application/json' }, body: JSON.stringify(request),
+        });
+        if (response.status >= 300 && response.status < 400) {
+            await response.body?.cancel();
+            return { kind: 'unconfirmed' };
+        }
+        const payload = await bounded(response);
+        if (payload === null || typeof payload !== 'object' || Array.isArray(payload))
+            return { kind: 'unconfirmed' };
+        if (response.status === 200 && Number.isInteger(payload.exitCode) && Number(payload.exitCode) >= 0 && Number(payload.exitCode) <= 255 && typeof payload.stdout === 'string' && typeof payload.stderr === 'string') {
+            return { kind: 'answer', answer: { exitCode: Number(payload.exitCode), stdout: payload.stdout, stderr: payload.stderr } };
+        }
+        if (response.status >= 400 && payload.ok === false && typeof payload.code === 'string' && typeof payload.message === 'string') {
+            return { kind: 'refused', status: response.status, code: payload.code, message: payload.message.replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '') };
+        }
+        return { kind: 'unconfirmed' };
+    }
+    catch {
+        return { kind: 'unconfirmed' };
+    }
+}
+/** The declared file arguments' contents, keyed by the argument exactly as typed. argv is never rewritten. */
+function inlineFiles(argv, row, cwd) {
+    const paths = fileArguments(argv, row);
+    if ('problem' in paths)
+        throw new UsageError(paths.problem);
+    const files = Object.create(null);
+    let size = 0;
+    for (const value of paths) {
+        if (Object.hasOwn(files, value))
+            continue;
+        const path = resolve(cwd, value);
+        let isFile = false;
+        try {
+            isFile = statSync(path).isFile();
+        }
+        catch {
+            isFile = false;
+        }
+        if (!isFile)
+            throw new UsageError('A remote input must be a readable file.');
+        let content;
+        try {
+            content = new TextDecoder('utf-8', { fatal: true }).decode(readFileSync(path));
+        }
+        catch {
+            throw new UsageError('A remote input must be a readable UTF-8 file.');
+        }
+        size += Buffer.byteLength(content);
+        if (size > CLI_FILES_BYTES)
+            throw new UsageError('Files sent with a remote command are limited to 256 KiB in total. Use --local to run it here.');
+        files[value] = content;
+    }
+    return files;
+}
+/**
+ * null: run locally with argv unchanged. `{ local }`: run locally with this argv (`--local` removed).
+ * A number: the command ran remotely (or was refused before sending) and this is its exit code.
+ */
+export async function maybeRunRemoteCommand(argv, options = {}) {
+    const first = argv[0];
+    if (first === undefined || first.startsWith('-') || TEAM_COMMANDS.has(first) || first === 'help')
+        return null;
+    const out = options.stdout ?? (chunk => { process.stdout.write(chunk); });
+    const err = options.stderr ?? (chunk => { process.stderr.write(chunk); });
+    const json = argv.includes('--json');
+    const lookup = options.modeOf ?? contractRow;
+    const row = lookup(argv);
+    const command = row?.invocation ?? first;
+    const refuse = (reason, message, code) => {
+        if (json)
+            out(`${envelopeJson({ ok: false, command, reason, message })}\n`);
+        else
+            err(`${message}\n`);
+        return code;
+    };
+    const profileAt = argv.indexOf('--profile');
+    const mode = row?.mode ?? 'no';
+    const explicit = profileAt >= 0;
+    // Local commands never read the profile, and their own flags (the scan's --local) stay exactly as typed.
+    if (mode === 'no' && !explicit)
+        return null;
+    if (argv.includes('--local')) {
+        if (explicit)
+            return refuse('usage', '--local cannot be combined with --profile.', EXIT.usage);
+        // A row declaring --local keeps its own meaning; elsewhere it only means "run here".
+        const declared = COMMAND_GUIDE.find(one => one.invocation === row?.invocation)?.flags?.some(flag => flag.name === 'local') ?? false;
+        return { local: declared ? [...argv] : argv.filter(one => one !== '--local') };
+    }
+    let profile;
+    try {
+        if (profileAt >= 0 && (argv.filter(one => one === '--profile').length > 1 || !argv[profileAt + 1] || argv[profileAt + 1].startsWith('-')))
+            throw new UsageError('Use --profile <name> once.');
+        profile = centralProfile(options, profileAt >= 0 ? argv[profileAt + 1] : undefined);
+    }
+    catch (error) {
+        return refuse('usage', error instanceof UsageError ? error.message : 'The remote profile cannot be read.', EXIT.usage);
+    }
+    // No saved token: today's local behaviour. A profile saved with a password serves chat only.
+    if (profile === null || !profile.apiToken) {
+        if (!explicit)
+            return null;
+        return refuse('usage', 'This profile has no API token. Connect again with your so_ token (toolroll connect <origin> --token-stdin).', EXIT.usage);
+    }
+    if (row === null || mode === 'no') {
+        return refuse('usage', `${command} runs only on this computer. Drop --profile to run it here.`, EXIT.usage);
+    }
+    if (mode === 'step-up')
+        return refuse('step-up', STEP_UP_MESSAGE, EXIT.refused);
+    const sent = explicit ? argv.filter((_one, index) => index !== profileAt && index !== profileAt + 1) : [...argv];
+    let files;
+    try {
+        files = inlineFiles(sent, row, options.cwd ?? process.cwd());
+    }
+    catch (error) {
+        return refuse('usage', error instanceof UsageError ? error.message : 'A file could not be read.', EXIT.usage);
+    }
+    const deliver = (outcome) => {
+        if (outcome.kind === 'answer') {
+            // Byte for byte. --json answers are also captured so -o writes the same envelope a local run would.
+            if (json) {
+                try {
+                    const parsed = JSON.parse(outcome.answer.stdout);
+                    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                        envelopeJson(parsed);
+                }
+                catch { /* not one envelope */ }
+            }
+            if (outcome.answer.stdout)
+                out(outcome.answer.stdout);
+            if (outcome.answer.stderr)
+                err(outcome.answer.stderr);
+            return outcome.answer.exitCode;
+        }
+        if (outcome.kind === 'refused')
+            return refuse(outcome.code, outcome.message, outcome.status === 401 || outcome.status === 403 || outcome.status === 501 ? EXIT.refused : outcome.status < 500 ? EXIT.usage : EXIT.failed);
+        return refuse('unconfirmed', row?.mutation === 'none'
+            ? `${profile.origin} could not be reached or answered unexpectedly.`
+            : `The answer from ${profile.origin} could not be confirmed. Check the task's state before running this again; it was not retried.`, EXIT.failed);
+    };
+    if (row?.invocation === 'task wait')
+        return waitRemotely(sent, files, profile, options, deliver);
+    return deliver(await post(profile.origin, profile.token, { argv: sent, files }, options));
+}
+/**
+ * `task wait` holds the server for at most CLI_WAIT_SECONDS per request; the client keeps asking within the caller's
+ * own --timeout (none: until the task settles or the wait is interrupted). The final answer is the server's own.
+ */
+async function waitRemotely(argv, files, profile, options, deliver) {
+    const at = argv.indexOf('--timeout');
+    const given = at < 0 ? null : Number(argv[at + 1]);
+    const base = at < 0 ? argv : argv.filter((_one, index) => index !== at && index !== at + 1);
+    if (given !== null && (!Number.isFinite(given) || given < 0))
+        return deliver(await post(profile.origin, profile.token, { argv, files }, options));
+    const json = base.includes('--json');
+    const probe = json ? base : [...base, '--json'];
+    const started = Date.now();
+    const sleep = options.sleep ?? ((ms, signal) => delay(ms, undefined, { signal }));
+    const signal = options.signal ?? new AbortController().signal;
+    while (true) {
+        const remaining = given === null ? CLI_WAIT_SECONDS : Math.max(0, given - (Date.now() - started) / 1_000);
+        const slice = Math.min(CLI_WAIT_SECONDS, Math.floor(remaining * 1_000) / 1_000);
+        const outcome = await post(profile.origin, profile.token, { argv: [...probe, '--timeout', String(slice)], files }, options);
+        if (outcome.kind !== 'answer')
+            return deliver(outcome);
+        let reason;
+        try {
+            reason = JSON.parse(outcome.answer.stdout).reason;
+        }
+        catch {
+            return deliver(outcome);
+        }
+        const timedOut = reason === 'timeout';
+        if (!timedOut || slice <= 0 || given !== null && remaining - slice <= 0) {
+            if (json)
+                return deliver(outcome);
+            // Settled (or out of time): the server renders the final answer in the person's own format.
+            return deliver(await post(profile.origin, profile.token, { argv: [...base, '--timeout', '0'], files }, options));
+        }
+        if (signal.aborted)
+            return deliver(outcome);
+        try {
+            await sleep(250, signal);
+        }
+        catch {
+            return deliver(outcome);
+        }
+    }
+}

package/dist/remote-run.d.ts

@@ -0,0 +1,20 @@
+/** A principal re-proved against the store for one remote run. */
+export type RemoteRun = {
+    readonly account: string;
+    readonly scope: "read" | "act";
+    readonly tokenName: string;
+    readonly source: "api" | "mcp";
+    /** What credential lookups hand back for this person in place of a password: unguessable, this run only. */
+    readonly secret: string;
+    /** Whether the person may use `repo` now (their token's projects and their account's current access). */
+    readonly allows: (repo: string | null) => boolean;
+    /** The projects listings and task references may disclose (remoteLensOf); null shows every project. */
+    readonly lens: readonly string[] | null;
+    /** Called with the task a remote `task add` filed (or replayed), so its action history names it. */
+    readonly noteTask: (taskId: string) => void;
+    /** Files the caller sent, keyed by the argument that names them. Nothing else is read for input. */
+    readonly files: Readonly<Record<string, string>>;
+};
+/** The remote run this code is inside, or null for every local command. */
+export declare function activeRemote(): RemoteRun | null;
+export declare function withRemote<T>(run: RemoteRun, fn: () => T): T;

package/dist/remote-run.js

@@ -0,0 +1,13 @@
+/**
+ * The remote run this code is inside (runOperateAs in operate.ts), if any. A leaf module so the credential
+ * checks every command reaches (scope.ts) can honour it without importing the command table.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const running = new AsyncLocalStorage();
+/** The remote run this code is inside, or null for every local command. */
+export function activeRemote() {
+    return running.getStore() ?? null;
+}
+export function withRemote(run, fn) {
+    return running.run(run, fn);
+}

package/dist/scope.js

@@ -4,6 +4,7 @@ import { passwordGuardOf } from "./sign-in-guard.js";
 import { validateScopeText } from "./task-text.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { projectAuthority } from "./project-access.js";
+import { activeRemote } from "./remote-run.js";
 import { claimActor, currentActor, parseLeadToken } from "./actor.js";
 /**
  * What a task is allowed to become, agreed before anything builds it.
@@ -707,6 +708,15 @@ password) {
 export function authenticateAccount(store, by, secret) {
     if (store.listApprovers().length === 0)
         return { ok: false, reason: "no-approvers" };
+    // A remote run (runOperateAs) is its token's person: only that run's own credential names them, no password is
+    // checked or counted, and a read token stands as a viewer.
+    const remote = activeRemote();
+    if (remote !== null) {
+        const account = by === remote.account && secret === remote.secret ? store.accountOf(by) : null;
+        if (account === null || account.revokedAt !== null)
+            return { ok: false, reason: "unknown" };
+        return { ok: true, role: remote.scope === "act" ? account.role : "viewer", generation: account.generation };
+    }
     // A lead token signs in as its owner, only inside a command the lead runs with it (never a console sign-in).
     const acting = currentActor();
     if (acting?.lead === true && parseLeadToken(secret) !== null) {

package/dist/serve.d.ts

@@ -3,6 +3,7 @@ import { CodingWorkspace } from './coding-workspace.js';
 import { type FetchLike } from "./flow-share.js";
 import { type MailSender } from "./flow-actions.js";
 import { type TriggerIo } from "./flow-triggers.js";
+import { type CliHttpOptions, type RunOperateAs } from './cli-http.js';
 import { type AssignmentSnapshot } from './assignment.js';
 import type { PublishExec } from './publish.js';
 import { type TaskStatus } from './task-status.js';
@@ -24,6 +25,8 @@ import type { RevisionLineage } from "./store.js";
 import type { SubscriptionMateRunner } from "./subscription-chat.js";
 import { type InstallMethod } from "./install-method.js";
 export type ServeOptions = {
+    /** Tests: runs a person's command for the HTTP MCP gateway instead of operate.ts's. */
+    runOperateAs?: import("./mcp-person.js").RunOperateAs;
     /** `toolroll demo`: the scripted lead that answers Chat instead of a model. */
     demoLead?: import("./demo.js").DemoLead;
     /** Tests: the bin whose real path says how Toolroll was installed (Settings → Updates' command). */
@@ -41,6 +44,10 @@ export type ServeOptions = {
      * install/push cards light up. X-Forwarded-* is never consulted.
      */
     publicUrl?: string;
+    /** Tests: the shared command boundary `POST /api/cli` runs (default: operate.ts's runOperateAs). */
+    cliRunner?: RunOperateAs;
+    /** Tests: remote command metadata until the shared contract declares it. */
+    cliModeOf?: CliHttpOptions['modeOf'];
     /** Where repos.json lives — every enrollment locks exactly this file. */
     registryPath?: string;
     /** This console fronts an `up` process: onboarding copy says how to watch. */

package/dist/serve.js

@@ -67,6 +67,7 @@ import { learningHtml } from "./workspace-ui.js";
 import { acceptWithChecksOf, resultActsOf } from "./result-acts.js";
 import { createSessionEndpoint } from './session-server.js';
 import { handleTeamHttp } from './team-http.js';
+import { handleCliHttp } from './cli-http.js';
 import { teamWorkspaceHtml } from './team-ui.js';
 import { createTeamRuntime } from './team-runtime.js';
 import { prepareWorkspaceRevision, WorkspaceValidatorCache } from "./workspace-revision.js";
@@ -262,6 +263,7 @@ import { budgetHoldWords, budgetLabel, budgetStates, monthNamed, monthOf, spendI
 import { targetOf } from "./monitoring.js";
 import { SSO_CSS, ssoSettingsHtml } from "./sso-ui.js";
 import { mintApiToken, parseApiToken, secretMatches, TOKEN_DAYS } from "./api-tokens.js";
+import { createMcpHttp } from "./mcp-http.js";
 import { CREDENTIALS_CSS, credentialsHtml, tokenShownHtml } from "./credentials-ui.js";
 import { logEvent } from "./log.js";
 import { modeTermsFromJson, modeWords, presetTerms, modeTermsJson, modeDigestOf, MODE_MAX_DAYS } from "./modes.js";
@@ -795,6 +797,21 @@ export function createDecisionServer(options) {
             return who?.via === 'cookie' ? teamBrowserReply(reply, actor, who.session.csrf) : reply;
         }, cursor: team.cursor, streams: teamStreams,
     });
+    // Remote CLI: one live API token names the person; the shared command boundary decides everything else.
+    const cliEndpoint = (request, response) => handleCliHttp(request, response, {
+        authenticate: request => {
+            const who = identify(request, false);
+            const id = parseApiToken(/^Bearer (so_\S+)$/.exec(request.headers.authorization ?? "")?.[1] ?? "")?.id;
+            const row = id === undefined ? undefined : store.apiTokenSecret(id)?.row;
+            const account = who === null ? null : store.accountOf(who.name);
+            if (who?.via !== "bearer" || who.token === undefined || row === undefined || row.account !== who.name || account === null || account.revokedAt !== null)
+                return null;
+            return { kind: "person", account: who.name, generation: account.generation, scope: row.access, tokenId: row.id, projects: account.projects === null ? null : [...account.projects] };
+        },
+        run: async () => options.cliRunner ?? (await import("./operate.js")).runOperateAs ?? null,
+        modeOf: options.cliModeOf,
+        store,
+    });
     const sessionEndpoint = createSessionEndpoint({ store, workspace: coding, projects: codingProjects, projectAllowed: repo => rowVisible(liveCeiling(), repo) });
     /** The enumerable admission list for roll-up SQL: repos-only ceilings
      * enumerate themselves; root ceilings enumerate the STORED repos that
@@ -1226,6 +1243,9 @@ export function createDecisionServer(options) {
         if (url.searchParams.has("token")) {
             return respond(response, 400, "text/plain; charset=utf-8", "credentials never travel in URLs");
         }
+        // The MCP gateway over HTTP (mcp-http.ts): coordinators and people's own API tokens, after the Host check.
+        if (url.pathname === "/mcp")
+            return mcpHttp(request, response);
         // Back from Google's consent screen (v89). The session cookie is SameSite=Strict and stays behind on
         // a return from another site: the visit's one-time state (made by a signed-in approver) is the proof.
         if (url.pathname === GOOGLE_CALLBACK && request.method === "GET")
@@ -1237,6 +1257,8 @@ export function createDecisionServer(options) {
             return;
         if (await teamEndpoint(request, response))
             return;
+        if (await cliEndpoint(request, response))
+            return;
         if (options.configDir !== undefined && await handleTeamsHttp(request, response, { store, dir: options.configDir, ...(options.teamsFetcher ? { fetcher: options.teamsFetcher } : {}), clock }))
             return;
         if (serveBrowserAsset(request, response, url.pathname))
@@ -11758,6 +11780,8 @@ export function createDecisionServer(options) {
             approved: (() => { const scope = store.getScope(taskId); return scope !== null && approvalOf(scope).approved; })(),
         }));
     }
+    const mcpHttp = createMcpHttp({ store, clock, evidenceRoot, signedIn: request => identify(request) !== null,
+        enrolled: () => [...new Set([...managedRepos(), ...store.listProjects().map(project => project.path)])], ...(options.runOperateAs === undefined ? {} : { runAs: options.runOperateAs }) });
     // ---- identity ------------------------------------------------------------
     function identify(request, touch = true) {
         // v101: an API token. Wrong ones spend the address's tries like a wrong password; expired or revoked ones, and a removed account's, name no one.

package/dist/store.d.ts

@@ -145,7 +145,21 @@ export type SealedLedgerEntry = LedgerEntry & {
         hash: string;
     } | null;
 };
-export declare const SCHEMA_VERSION = 109;
+export declare const SCHEMA_VERSION = 110;
+/**
+ * The migrations `toolroll update` may carry a database through in place: each
+ * one only adds (a table, a column, an accepted value) and leaves every saved row
+ * as it was, so the updater's rehearsal on a copy (same history, integrity ok)
+ * proves it and the verified backup undoes it. Any migration not listed here
+ * needs the separate verified migration procedure. The desktop update never
+ * migrates and does not read this list.
+ *
+ * v110 rebuilds action_ledger only to widen its source check ('api', 'mcp'):
+ * every row, id and hash-chain link is copied unchanged.
+ */
+export declare const UPDATE_SAFE_MIGRATIONS: readonly number[];
+/** Whether a database settled at `version` reaches this build's schema through update-safe migrations alone. */
+export declare function updateSafeSchema(version: number | null): boolean;
 export type ApiTokenRow = {
     id: string;
     account: string;

package/dist/store.js

@@ -64,7 +64,7 @@ import { authenticate as runnerAuthenticate } from "./runner.js";
 import { stampNewProjectLevel } from "./check-levels.js";
 import { parseCheckProgressSnapshot } from "./check-progress.js";
 import { normalizeProjectAccess, projectAccessAllows, readProjectAccess } from "./project-access.js";
-import { LEDGER_SCHEMA, LEDGER_TABLE, LEDGER_V54_COLUMNS, LEDGER_V54_TABLE, installLedgerTriggers } from "./action-ledger.js";
+import { LEDGER_SCHEMA, LEDGER_TABLE, LEDGER_V54_COLUMNS, LEDGER_V54_TABLE, LEDGER_V99_TABLE, installLedgerTriggers } from "./action-ledger.js";
 import { PLAN_AUTO_SCHEMA } from "./plan-auto.js";
 import { RECIPE_SCHEMA } from "./recipes.js";
 import { POLICY_SCHEMA, agentRefusal, approvalRefusal, attendedRefusal, policyParts, readPolicy, underCeiling, sessionCeilingRefusal } from "./policy.js";
@@ -563,7 +563,29 @@ const REGISTERED_AT_FILING = "again, as it was filed";
 // v107 keeps a check's progress and result in one record (run_check absorbs check_progress).
 // v108 keeps sign-in pauses: one incident per provider whose sign-in stopped working (provider_auth_pause).
 // v109 remembers which sign-in pause parked a task (task_ref.auth_wait_pause), so reviews and other runs outside the tick wait for it too.
-export const SCHEMA_VERSION = 109;
+// v110 lets the action ledger record commands a person ran on this server with their API token (source 'api', or 'mcp' from their agent).
+export const SCHEMA_VERSION = 110;
+/**
+ * The migrations `toolroll update` may carry a database through in place: each
+ * one only adds (a table, a column, an accepted value) and leaves every saved row
+ * as it was, so the updater's rehearsal on a copy (same history, integrity ok)
+ * proves it and the verified backup undoes it. Any migration not listed here
+ * needs the separate verified migration procedure. The desktop update never
+ * migrates and does not read this list.
+ *
+ * v110 rebuilds action_ledger only to widen its source check ('api', 'mcp'):
+ * every row, id and hash-chain link is copied unchanged.
+ */
+export const UPDATE_SAFE_MIGRATIONS = Object.freeze([110]);
+/** Whether a database settled at `version` reaches this build's schema through update-safe migrations alone. */
+export function updateSafeSchema(version) {
+    if (version === null || !Number.isSafeInteger(version) || version <= 0 || version > SCHEMA_VERSION)
+        return false;
+    for (let next = version + 1; next <= SCHEMA_VERSION; next++)
+        if (!UPDATE_SAFE_MIGRATIONS.includes(next))
+            return false;
+    return true;
+}
 /** v102: a project's approval rules, and each person's approval of an exact scope (two are needed for protected work). */
 const APPROVAL_SCHEMA = `
 CREATE TABLE IF NOT EXISTS approval_policy (
@@ -5212,8 +5234,8 @@ function migrate(db, origin) {
        tool_call     INTEGER REFERENCES teammate_call(id),
        suggestion    INTEGER REFERENCES teammate_suggestion(id)
      )`, ["id", "teammate", "card", "entry", "question", "options_json", "asked_of", "state", "choice", "answer", "answered_by", "answered_via", "answered_at", "created_at", "tool_call", "suggestion"]);
-    // v99: the action ledger admits sign-in and policy events, each with a short detail.
-    rebuildLedgerForV99(db);
+    // v99: the action ledger admits sign-in and policy events, each with a short detail; v110: and remote commands ('api', 'mcp').
+    rebuildLedger(db);
     // v101: a coordinator credential's expiry (null: made before expiry existed, until renewed).
     addColumn(db, "coordinator_credential", "expires_at", "TEXT");
     // v102: who filed a task (a person, or the person a coordinator acts for; null when no person is known) and what kind of filer.
@@ -5534,19 +5556,24 @@ function readWebSession(row) {
 }
 /**
  * v99: the ledger's source admits 'sign-in' and 'policy', and each row may
- * carry a short detail. The work triggers on other tables write into the
+ * carry a short detail. v110: it admits 'api' and 'mcp' too, from either
+ * earlier shape; rows, ids and the counter are carried whole, so the v103
+ * seals over them still hold. The work triggers on other tables write into the
  * ledger, and a rename refuses while a trigger points at a table that's gone,
  * so every trigger naming it is dropped first; openStore puts them back
  * (LEDGER_SCHEMA and installLedgerTriggers run after migration).
  */
-function rebuildLedgerForV99(db) {
+function rebuildLedger(db) {
     const row = db.prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'action_ledger'").get();
     if (row === undefined || canonicalDdl(String(row["sql"])) === canonicalDdl(LEDGER_TABLE("action_ledger")))
         return;
     for (const trigger of db.prepare("SELECT name FROM sqlite_master WHERE type = 'trigger' AND sql LIKE '%action_ledger%'").all()) {
         db.exec(`DROP TRIGGER IF EXISTS "${String(trigger["name"]).replace(/"/g, '""')}"`);
     }
-    rebuildExact(db, "action_ledger", LEDGER_V54_TABLE, LEDGER_TABLE, LEDGER_V54_COLUMNS);
+    if (canonicalDdl(String(row["sql"])) === canonicalDdl(LEDGER_V54_TABLE("action_ledger")))
+        rebuildExact(db, "action_ledger", LEDGER_V54_TABLE, LEDGER_TABLE, LEDGER_V54_COLUMNS);
+    else
+        rebuildExact(db, "action_ledger", LEDGER_V99_TABLE, LEDGER_TABLE, [...LEDGER_V54_COLUMNS, "detail"]);
 }
 /** v34: artifact.kind admits 'report'. A table already rebuilt to the v38
  * shape (migrate() runs unconditionally on every open, including a fresh

package/dist/surface.d.ts

@@ -1,6 +1,6 @@
-import { type CommandFlag, type CommandRow } from './contracts/cli.js';
+import { type CommandFlag, type CommandRow, type RemotePolicy } from './contracts/cli.js';
 /** A guide row and its flags are derived from their schemas in src/contracts/cli.ts. */
-export type { CommandFlag, CommandRow };
+export type { CommandFlag, CommandRow, RemotePolicy };
 /** The guide's limits, stated machine-readably in every dump. */
 export declare const SURFACE_NOTES: {
     readonly authority: "documentation is not permission; session descriptors also drive parser and request validation; legacy entries remain advisory";
@@ -9,7 +9,14 @@ export declare const SURFACE_NOTES: {
     readonly database: "local database commands wait up to 15 seconds for another writer; an exhausted wait returns database-busy and names the selected file";
 };
 export declare const SURFACE_SCHEMA_VERSION = 1;
-/** Every declared command, in guide order, paired with the schema of its `--json` answer (src/contracts/cli.ts). */
+/** Every row's remote policy, by invocation. Exported for the contract test, which holds it to the guide exactly. */
+export declare const REMOTE_POLICY: ReadonlyMap<string, RemotePolicy>;
+/** How many times each invocation was classified — the contract test refuses a row stated twice. */
+export declare const REMOTE_POLICY_COUNT: number;
+/** Every declared command, in guide order, paired with the schema of its `--json` answer (src/contracts/cli.ts).
+ * An unclassified row is "no": nothing runs remotely by omission. */
 export declare const COMMAND_ENTRIES: readonly import("./contracts/cli.js").CommandEntry[];
+/** The invocations the guide states, for the contract test (a classification naming none of them is stale). */
+export declare const GUIDE_INVOCATIONS: readonly string[];
 /** The guide `contract --commands` dumps: each declared command's row, projected from COMMAND_ENTRIES. */
 export declare const COMMAND_GUIDE: readonly CommandRow[];

package/dist/surface.js

@@ -416,7 +416,72 @@ const GUIDE_ROWS = [
     operator("onboard", "add this repository, report signed-in agents, install or --remove the operator skill (--yes), offer the starter flows (--starter <ids>), and print the handoff"),
     operator("daemon", "install the loop under the OS service manager"),
 ];
-/** Every declared command, in guide order, paired with the schema of its `--json` answer (src/contracts/cli.ts). */
-export const COMMAND_ENTRIES = commandEntries(GUIDE_ROWS);
+/**
+ * Whether each row may run on a central server for a person signed in with their own API token (`runOperateAs` in
+ * operate.ts), stated for every row by name. "no" is this machine's own infrastructure, credentials, files and the
+ * commands that only make sense beside a checkout (or that the local CLI answers itself); "step-up" is approvals,
+ * people and policy, which stay in the console and chat; "yes" runs as the person, within their token's scope and
+ * project access. A row missing here fails the contract test, and runs nowhere remotely meanwhile.
+ */
+const REMOTE_NO = [
+    // Answered by the local CLI, or a client of a central server itself.
+    "", "pulls", "graph", "repos", "repos add", "repos remove", "repos add-from-github", "contract", "skills list", "skills get", "skills install",
+    "link", "unlink", "update", "demo", "chat", "connect", "lead list", "lead create", "lead update", "lead member", "lead transfer",
+    "conversation list", "conversation create", "conversation show", "conversation member", "conversation edit", "conversation withdraw",
+    "conversation read", "conversation follow", "conversation stop",
+    "session capabilities", "session list", "session show", "session changes", "session start", "session send", "session stop", "session resume", "session recover",
+    // This machine's checkout, saved profile, credentials and catch-up.
+    "project show", "project use", "brief", "lead token", "lead say",
+    "assignment show", "assignment updates", "assignment claim", "assignment check", "assignment brief", "assignment inbox", "assignment ack",
+    // Workers, the loop and the services that run here.
+    "claim", "heartbeat", "release", "reap", "tick", "build", "reconcile",
+    "runner register", "runner retire", "runner bind", "runner capacity", "coordinator mint", "coordinator revoke", "mcp", "outbox deliver", "peek",
+    "serve", "watch", "up", "onboard", "daemon", "bridge", "setup show", "setup clear",
+    // Provider keys and model tools on this machine.
+    "providers", "keys status", "keys set", "keys clear", "keys verify", "keys auth", "models check", "models update", "models watch",
+    // Publication and release.
+    "publish", "publish status", "publish merge", "publish refire", "publish unblock", "publish rearm", "publish grant", "publish revoke",
+    // A repository's authority grants on this machine.
+    "enroll", "revoke",
+    // Flow steps that fetch addresses or run checks and scripts here.
+    "flows import", "flows trigger check", "flows script save",
+    // Reads this machine owner's own Claude and Codex session files (~/.claude, ~/.codex).
+    "memory propose",
+];
+const REMOTE_STEP_UP = [
+    "proposals", "decide", "task regate", "task approve", "task accept", "task merge", "run settle", "routine approve", "knowledge apply", "memory apply",
+    "flows card approve", "flows card send-back", "flows script approve",
+    "approver list", "approver add", "people list", "people invite", "people projects", "people revoke",
+    "mode show", "mode set", "mode revoke", "chat-approval on", "review on", "review off", "config set", "config clear",
+    "verify set", "verify clear", "verify level", "project checks", "project concurrency", "intake grant", "intake clear", "webhook primary",
+];
+const REMOTE_YES = [
+    "status", "integrations", "ready", "gaps", "grants", "sync",
+    "task add", "task ask", "task checks", "task add-tests", "task list", "task show", "check-progress", "task wait", "task complete", "task revise",
+    "task state", "task block", "task unblock", "task next", "task steer", "task assign", "task scope", "task plan", "task hold", "task unhold", "task require",
+    "task requeue", "task review", "task repair", "task route", "task reopen", "task stop", "task resume",
+    "runner list", "coordinator list", "cap list", "cap add", "outbox list", "incident list", "incident resolve",
+    "routine list", "routine show", "routine add", "routine refresh", "routine pause", "routine resume", "routine run-now",
+    "config show", "verify show", "intake show", "intake run", "intake preview", "intake pr-comments", "template list", "template show",
+    "contest show", "contest exclude", "webhook status", "webhook test", "review show", "chat-approval show", "chat-approval off",
+    "knowledge search", "knowledge impact", "knowledge refresh",
+    "memory search", "memory decisions", "memory show", "memory decide", "memory retire", "memory review", "memory status",
+    "flows list", "flows show", "flows export", "flows create", "flows edit", "flows trigger add", "flows trigger pause", "flows trigger resume",
+    "flows trigger remove", "flows card add", "flows archive",
+    "models status", "models list",
+];
+/** Every row's remote policy, by invocation. Exported for the contract test, which holds it to the guide exactly. */
+export const REMOTE_POLICY = new Map([
+    ...REMOTE_NO.map(invocation => [invocation, "no"]),
+    ...REMOTE_STEP_UP.map(invocation => [invocation, "step-up"]),
+    ...REMOTE_YES.map(invocation => [invocation, "yes"]),
+]);
+/** How many times each invocation was classified — the contract test refuses a row stated twice. */
+export const REMOTE_POLICY_COUNT = REMOTE_NO.length + REMOTE_STEP_UP.length + REMOTE_YES.length;
+/** Every declared command, in guide order, paired with the schema of its `--json` answer (src/contracts/cli.ts).
+ * An unclassified row is "no": nothing runs remotely by omission. */
+export const COMMAND_ENTRIES = commandEntries(GUIDE_ROWS.map(row => ({ ...row, remote: REMOTE_POLICY.get(row.invocation) ?? "no" })));
+/** The invocations the guide states, for the contract test (a classification naming none of them is stale). */
+export const GUIDE_INVOCATIONS = GUIDE_ROWS.map(row => row.invocation);
 /** The guide `contract --commands` dumps: each declared command's row, projected from COMMAND_ENTRIES. */
 export const COMMAND_GUIDE = COMMAND_ENTRIES.map(entry => entry.guide);

package/dist/team-cli.d.ts

@@ -11,5 +11,24 @@ export type TeamCliOptions = {
     sleep?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
 };
 export declare const TEAM_CLI_ACTIONS: readonly ['connect', 'lead list', 'lead create', 'lead update', 'lead member', 'lead transfer', 'conversation list', 'conversation create', 'conversation show', 'conversation member', 'conversation edit', 'conversation withdraw', 'conversation read', 'conversation follow', 'conversation stop'];
+export declare class UsageError extends Error {
+}
+type Profile = {
+    origin: string;
+    account: string;
+    token: string;
+};
+/** An API token (so_…) is sent bare; an older saved sign-in keeps its account:secret form. */
+export declare const bearerOf: (profile: Profile) => string;
+/** The saved central profile remote commands use: the named one (or the active one), and whether it holds an API token.
+ * null when nothing is saved. Reads only the private profile file — never a local login or the database. */
+export declare function centralProfile(options: TeamCliOptions, name?: string): {
+    name: string;
+    origin: string;
+    account: string;
+    token: string;
+    apiToken: boolean;
+} | null;
 /** null means preserve the existing local command path. Nothing here opens a database. */
 export declare function maybeRunTeamCommand(argv: readonly string[], write: (line: string) => void, options?: TeamCliOptions): Promise<number | null>;
+export {};