toolroll 0.9.43 → 0.9.45

package/dist/operate.js

@@ -84,7 +84,7 @@ import { homedir, hostname, tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { releaseStalledUpdate, waitingUpdate } from "./toolroll-update.js";
 import { openStore, openStoreNoMigrate, CONCURRENT_WRITER_WAIT_MS, isDatabaseBusy, databasePath, BUILT_IN, DEFAULT_ACTOR, parseCapabilityKey, verifiedAuthor, contestantProfileOf, isDigestTime, RESULT_SCREENSHOTS, } from "./store.js";
-import { randomBytes, randomInt, randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomInt, randomUUID } from "node:crypto";
 import { authorizePlanUnderMode } from "./plan-auto.js";
 import { ghDispatchAdapter, mirrorTaskId, syncPass } from "./sync.js";
 import { sweepLiveLogs } from "./live.js";
@@ -150,10 +150,12 @@ import { daemonLaunchCommand, daemonStatus, installReplacingLegacy, installedLeg
 import { bridgePass, clearBotToken, createTransport, followBridge, hashPairingCode, loadBotToken, mintPairingCode, networkFence, networkFenceLine, redactToken, saveBotToken, PAIRING_TTL_MS, TOKEN_ENV, telegramHookSecret, telegramPushUrl, } from "./telegram.js";
 import { scanRepo } from "./capscan.js";
 import { computeGaps, describeCapability } from "./gaps.js";
-import { ask, askHidden, confirm, interactive, underAgent } from "./prompt.js";
+import { ask as promptAsk, askHidden as promptHidden, confirm as promptConfirm, interactive as promptInteractive, underAgent } from "./prompt.js";
 import { runMateCli, answerContextLines } from "./mate-cli.js";
 import { confirmCoordinatorProposal, dismissCoordinatorProposal } from "./mate-doors.js";
-import { verifyApproverByPassword } from "./principal.js";
+import { verifyApproverByPassword as approverByPassword } from "./principal.js";
+import { activeRemote, REMOTE_MESSAGES, REMOTE_REFUSED_FLAGS, REMOTE_SCOPES, RemoteRefusal, remoteAllows, remoteLensOf, remoteProjectOf, remoteRowOf, remoteSecret, reproveRemote, withRemote } from "./operate-remote.js";
+import { projectAuthority } from "./project-access.js";
 import { authorizedProject, canonicalProject, projectName, resolveCeiling } from "./project.js";
 import { tally, spendLine } from "./summary.js";
 import { bodyHashOf, describePublicationGrant, observeChecks, publicationBody, publishPass, sweepMerges, } from "./publish.js";
@@ -169,7 +171,7 @@ import { register, authenticate, heartbeat as heartbeatRunner, isAlive, recoverD
 import { mintCoordinator, revokeCoordinator, listCoordinators } from "./coordinator.js";
 import { serveMcp } from "./mcp.js";
 import { createInterface } from "node:readline";
-import { propose, approve, addApprover, authenticateAccount, authenticateApprover, describeScope, approvalOf, hashToken as hashApproverToken, profileFromJson, fileAndSealUnderMode, modeFilingCoverage, acceptanceLinesToInput, parseAcceptanceCriteria, splitAcceptanceRubric, rubricIsPlaceholder, isCommitSha } from "./scope.js";
+import { propose, approve, addApprover, authenticateAccount, authenticateApprover as passwordApprover, describeScope, approvalOf, hashToken as hashApproverToken, profileFromJson, fileAndSealUnderMode, modeFilingCoverage, acceptanceLinesToInput, parseAcceptanceCriteria, splitAcceptanceRubric, rubricIsPlaceholder, isCommitSha } from "./scope.js";
 import { presetTerms, modeTermsJson, modeDigestOf, modeTermsFromJson, modeWords, MODE_MAX_DAYS } from "./modes.js";
 import { WorktreePool } from "./worktree.js";
 import { requestTaskStop, resumeTaskStop, taskControlOf } from "./task-control.js";
@@ -823,6 +825,20 @@ export async function runOperate(command, argv, write, options = {}) {
             flags.delete("token");
         actor = { account: lead.owner, lead: true };
     }
+    try {
+        return await dispatchOn(command, positional, flags, parsed.repoList, { store, write, json, file, now, ...(actor === null ? {} : { leadToken: presented }) }, options, run => LEAD_COMMANDS.has(command) ? withActor(actor, run) : run());
+    }
+    finally {
+        store.close();
+    }
+}
+/**
+ * Run one command against an open store: the dispatcher both roads share. The caller owns the store (runOperate
+ * opens and closes its own; runOperateAs uses the server's and leaves it open) and says what the command runs
+ * inside (`enter`: the actor, and for a remote run its person and project).
+ */
+async function dispatchOn(command, positional, flags, repoList, base, options, enter) {
+    const { store, write, json, file, now } = base;
     // v105: a Claude turn anywhere in this command says its plan's usage windows; keep the latest.
     const dropLimitSink = pushLimitSink(reading => store.recordProviderLimits(reading, new Date()));
     // Filed tasks are sized by the owner's own fast classifier (never in tests, the demo, or with NO_TASK_CLASSIFIER).
@@ -835,11 +851,11 @@ export async function runOperate(command, argv, write, options = {}) {
     const clock = options.now === undefined ? () => new Date() : () => now;
     try {
         const run = () => dispatch(command, positional, flags, {
-            ...(actor === null ? {} : { leadToken: presented }),
+            ...(base.leadToken === undefined ? {} : { leadToken: base.leadToken }),
             store,
             write,
             json,
-            repoList: parsed.repoList,
+            repoList,
             now,
             clock,
             // Evidence lives beside the database for the same reason the database
@@ -873,10 +889,13 @@ export async function runOperate(command, argv, write, options = {}) {
             ...(options.installBin === undefined ? {} : { installBin: options.installBin }),
             ...(options.onboardSeams === undefined ? {} : { onboardSeams: options.onboardSeams }),
             ...(options.upSeams === undefined ? {} : { upSeams: options.upSeams }),
+            ...(activeRemote() === null ? {} : { principal: activeRemote() }),
         });
-        return await (LEAD_COMMANDS.has(command) ? withActor(actor, run) : run());
+        return await enter(run);
     }
     catch (error) {
+        if (error instanceof RemoteRefusal)
+            return fail(write, json, command, error.reason, error.message, EXIT.refused);
         if (isDatabaseBusy(error))
             return databaseFailure(write, json, command, file, error);
         return fail(write, json, command, "failed", describe(error), EXIT.failed);
@@ -886,9 +905,98 @@ export async function runOperate(command, argv, write, options = {}) {
         await settleSizings();
         dropSizer();
         dropLimitSink();
-        store.close();
     }
 }
+/**
+ * Run one command on this server for a person who signed in with their own API token (the transport and MCP
+ * gateway prove the `so_` token and refuse browser origins; this is everything after). The command's row in the
+ * machine contract decides first: "no" and "step-up" rows, and commands with no row, are refused before any
+ * command code runs. The principal is re-proved against the store, a read token runs only reads, and the project
+ * the command touches must be one the person may use, named by --repo where a local run would use the working
+ * directory. The command then runs as that person: every credential check resolves to them, nothing prompts, and
+ * this machine's saved login and lead token are never read. Files are only those sent in `files`, keyed by the
+ * argument that names them. Every call is in the action history as the person, from source `api` (or `mcp`),
+ * with the token's name. The store is the caller's and stays open.
+ */
+export async function runOperateAs(argv, opts) {
+    const { principal, store, write } = opts;
+    const source = opts.source === "mcp" ? "mcp" : "api";
+    const options = opts.options ?? {};
+    const now = options.now ?? new Date();
+    const [root = "", ...rest] = argv;
+    const json = rest.includes("--json");
+    let invocation = root;
+    let tokenName = null;
+    const record = (outcome, repo, taskId, why) => {
+        store.recordAction({ at: (options.now ?? new Date()).toISOString(), actor: principal.account, repo, taskId, runId: null,
+            action: `remote command: ${invocation === "" ? "(none)" : invocation}`.slice(0, 200), outcome, source,
+            detail: `token ${tokenName ?? principal.tokenId}${why === null ? "" : ` · ${why}`}` });
+    };
+    const refuse = (reason, message, repo = null, taskId = null) => {
+        record("refused", repo, taskId, reason);
+        return fail(write, json, invocation === "" ? "remote" : invocation, reason, message, EXIT.refused);
+    };
+    const proved = reproveRemote(store, principal, now);
+    if (!proved.ok)
+        return refuse("unauthenticated", REMOTE_MESSAGES.stale);
+    tokenName = proved.tokenName;
+    // The row first, from the words before any flag: a refused command is refused whatever its flags say.
+    const firstFlag = rest.findIndex(one => one.startsWith("-"));
+    const row = remoteRowOf(root, firstFlag === -1 ? rest : rest.slice(0, firstFlag));
+    if (row === null)
+        return refuse("not-remote", REMOTE_MESSAGES.unknown);
+    invocation = row.invocation;
+    if (row.remote === "step-up")
+        return refuse("step-up", REMOTE_MESSAGES["step-up"]);
+    const scope = REMOTE_SCOPES.get(row.invocation);
+    if (row.remote !== "yes" || scope === undefined)
+        return refuse("not-remote", REMOTE_MESSAGES.no);
+    const parsed = parseOperateArgs(rest, root === "flows" ? FLOWS_VALUE_FLAGS : undefined);
+    if ("error" in parsed)
+        return refuse("usage", parsed.error);
+    // The parser's positionals must spell the same row (a value flag can't hide a subcommand).
+    if (remoteRowOf(root, parsed.positional)?.invocation !== row.invocation)
+        return refuse("not-remote", REMOTE_MESSAGES.unknown);
+    if (proved.scope === "read" && row.mutation !== "none")
+        return refuse("read-only", REMOTE_MESSAGES.read);
+    if ([...parsed.flags.keys()].some(name => REMOTE_REFUSED_FLAGS.has(name)))
+        return refuse("usage", REMOTE_MESSAGES.credential);
+    const allows = (repo) => remoteAllows(store, principal, repo);
+    const project = remoteProjectOf(store, { allows }, scope, parsed.positional, parsed.repoList, row.invocation, parsed.flags, opts.files ?? {});
+    if (!project.ok)
+        return refuse(project.reason, project.message);
+    // The local mutation cache has a global key namespace. A token must not use a chosen key to read
+    // another person's/project's cached result. Revision keys already bind the actor and result in
+    // task-outcome-cli.ts, which also validates their public 32-hex format; leave those intact.
+    const key = text(parsed.flags, "key");
+    if (key !== undefined && row.invocation !== "task revise") {
+        parsed.flags.set("key", `remote:${createHash("sha256").update(JSON.stringify([principal.account, row.invocation, project.repo, project.taskId, key])).digest("hex")}`);
+    }
+    const file = store.databaseFile() ?? options.databaseFile;
+    if (file === undefined)
+        return refuse("failed", "The server's database has no file.", project.repo, project.taskId);
+    // The task a `task add` filed is only known once it runs; the final history line names it.
+    let filed = null;
+    const run = Object.freeze({ account: principal.account, scope: proved.scope, tokenName: proved.tokenName, source, secret: remoteSecret(), allows,
+        lens: remoteLensOf(store, scope, allows), noteTask: (taskId) => { filed = taskId; }, files: Object.freeze({ ...(opts.files ?? {}) }) });
+    record("requested", project.repo, project.taskId, null);
+    let code;
+    try {
+        code = await withRemote(run, () => dispatchOn(root, parsed.positional, parsed.flags, parsed.repoList, { store, write, json, file, now }, options, go => withActor({ account: principal.account, lead: false }, () => projectAuthority.run({ actor: principal.account, repo: project.repo }, go))));
+    }
+    catch (error) {
+        record("failed", project.repo, filed ?? project.taskId, null);
+        throw error;
+    }
+    record(code === EXIT.ok ? "done" : code === EXIT.refused ? "refused" : code === EXIT.usage ? "usage" : "failed", project.repo, filed ?? project.taskId, null);
+    return code;
+}
+/** A file a remote caller sent with the request, by the argument that names it; never a path on this machine. */
+function remoteFile(remote, path) {
+    if (Object.prototype.hasOwnProperty.call(remote.files, path))
+        return remote.files[path];
+    throw new RemoteRefusal("usage", REMOTE_MESSAGES.files);
+}
 /** The short commands a lead token works for, and where whoever signs in is recorded as the actor. */
 const LEAD_COMMANDS = new Set(["task", "assignment", "status", "ready", "brief", "peek", "check-progress", "notifications", "lead"]);
 /**
@@ -1158,6 +1266,9 @@ function openBackend(name, store, repo) {
 }
 /** The repository a backend command applies to, normalised like the grant is. */
 function repoFrom(flags) {
+    // The server's working directory is nobody's project: a remote caller names theirs.
+    if (activeRemote() !== null && text(flags, "repo") === undefined)
+        throw new RemoteRefusal("unknown-project", REMOTE_MESSAGES.project);
     return resolve(text(flags, "repo") ?? process.cwd());
 }
 // ---- the dispatch loop ----------------------------------------------------
@@ -1199,7 +1310,9 @@ async function readyCommand(flags, context) {
             write(`  ${task.id}  ${task.title}`);
         return EXIT.ok;
     }
-    const ready = store.listReady(now);
+    // A remote person limited to some projects (remoteLensOf) sees only theirs, counted over those alone.
+    const lens = context.principal?.lens ?? null;
+    const ready = store.listReady(now).filter(ref => lens === null || ref.repo !== null && lens.includes(ref.repo));
     const described = ready.map(ref => describeRef(store, ref, now));
     const dispatchableCount = described.filter(one => diagnosisIsDispatchable(one.dispatch)).length;
     const pauses = openAuthPauses(store);
@@ -8216,6 +8329,9 @@ export function writeLoginFileDurably(path, name, password) {
     }
 }
 function readLoginFile(path) {
+    // The owner's saved login is never anyone else's: a remote run that reaches here is a bug, and ends refused.
+    if (activeRemote() !== null)
+        throw new RemoteRefusal("unauthenticated", REMOTE_MESSAGES.credential);
     try {
         const raw = readFileSync(path, "utf8").trim();
         const cut = raw.indexOf(" ");
@@ -9986,6 +10102,13 @@ async function statusCommand(positional, flags, context) {
         return fail(context.write, context.json, command, "usage", "Use `toolroll status [--json]`.", EXIT.usage);
     // Whose lead the status line follows: the lead's own person, else the remembered login; nobody shows no lead.
     const viewer = currentActor()?.account ?? readLoginFile(join(dirname(context.databaseFile), UP_LOGIN_FILE))?.name ?? null;
+    // A remote person limited to some projects sees only those (remoteLensOf): their tasks and counts, and nothing
+    // that belongs to the installation or other projects (updates, integrations, builds by project, unsent replies).
+    const lens = context.principal?.lens ?? null;
+    if (lens !== null) {
+        const status = installationStatus(context.store, context.clock(), viewer, lens);
+        return succeed(context.write, context.json, command, { ...status, projects: [] }, () => renderInstallationStatus(status, true));
+    }
     const status = installationStatus(context.store, context.clock(), viewer);
     // One line, only when a newer Toolroll exists; offline or switched off says nothing.
     const current = PACKAGE_VERSION;
@@ -10283,7 +10406,8 @@ async function addTask(positional, flags, context) {
             ...(mirrored === null ? [] : [`Mirrored locally as ${mirrored} — scope and approve it, and this plane builds it.`]),
         ]);
     }
-    const id = text(flags, "id") ?? slug(title, now);
+    // Remote creation cannot probe global IDs, including predictable title/time collisions.
+    const id = text(flags, "id") ?? (activeRemote() === null ? slug(title, now) : `task-${randomBytes(16).toString("hex")}`);
     // Re-filing: the new task replaces an earlier one, which is cancelled and reads "Replaced by <id>".
     const replaces = text(flags, "replaces");
     if (replaces !== undefined && (replaces === id || store.getTask(replaces) === null)) {
@@ -10306,12 +10430,22 @@ async function addTask(positional, flags, context) {
     if (!outcome.ok) {
         return fail(write, json, "task add", "exists", `\`${id}\` already exists`, EXIT.refused);
     }
-    store.stampFiledVia(store.refFor(BUILT_IN, id).id, "cli");
+    const filedId = outcome.task.id;
+    const remote = activeRemote();
+    if (remote !== null && filedId !== id) {
+        // Re-prove a replayed creation too: it may have been moved since the original filing.
+        const saved = store.lookupRef(filedId);
+        if (saved === null || saved.repo !== text(flags, "repo") || !remote.allows(saved.repo)) {
+            throw new RemoteRefusal("not-found", "Not found.");
+        }
+    }
+    remote?.noteTask(filedId);
+    store.stampFiledVia(store.refFor(BUILT_IN, filedId).id, "cli");
     // Placement is explicit, never inferred from where the command happened to
     // run: a task filed from the wrong directory would silently bind to it.
     const placedIn = text(flags, "repo");
     if (placedIn !== undefined) {
-        const placed = store.placeTask(store.refFor(BUILT_IN, id).id, canonicalProject(placedIn) ?? resolve(placedIn));
+        const placed = store.placeTask(store.refFor(BUILT_IN, filedId).id, canonicalProject(placedIn) ?? resolve(placedIn));
         if (typeof placed === "object" && !placed.ok) {
             return fail(write, json, "task add", "scoped", "this task already has a scope — placement is immutable once somebody could have approved it", EXIT.refused);
         }
@@ -10586,7 +10720,9 @@ function listTasks(flags, context) {
     }
     let page;
     try {
-        page = workIndexPage(store, now, { principal: 'operator', repos: null, includeUnplaced: true }, {
+        // A remote person limited to some projects (remoteLensOf) pages and counts only theirs.
+        const lens = context.principal?.lens ?? null;
+        page = workIndexPage(store, now, { principal: 'operator', repos: lens, includeUnplaced: lens === null }, {
             view: parseWorkView(rawView ?? null), limit, cursor: text(flags, 'cursor') ?? null,
             ...(wanted === undefined ? {} : { state: wanted }),
             ...(text(flags, 'repo') === undefined ? {} : { project: text(flags, 'repo') }),
@@ -10633,13 +10769,21 @@ function showTask(positional, context) {
     // whatever readiness this task's runners have reported.
     const routed = routeOfTask(store, id, ref, now);
     const readiness = store.readinessLookupFor(ref.repo, ref.assignedRunner, now);
+    const lens = context.principal?.lens ?? null;
+    const access = { principal: "operator", repos: lens, includeUnplaced: lens === null, dependencyRepos: lens };
+    const blockers = store.blockers(id);
+    const visibleBlockers = lens === null ? blockers : blockers.filter(blocker => {
+        const repo = store.lookupRef(blocker)?.repo;
+        return repo != null && lens.includes(repo);
+    });
     const detail = {
         task,
-        work: taskWorkSummaryOf(store, id, now, { principal: "operator", repos: null, includeUnplaced: true }),
-        assignment: assignmentBrief(assignmentOf(store, id, now, { principal: "operator", repos: null, includeUnplaced: true }, context.evidenceRoot)),
+        work: taskWorkSummaryOf(store, id, now, access),
+        assignment: assignmentBrief(assignmentOf(store, id, now, access, context.evidenceRoot)),
         ref: ref.id,
-        blockedBy: store.blockers(id),
-        position: store.queuePosition(id),
+        // One phrase for every inaccessible blocker, so even their number stays private.
+        blockedBy: visibleBlockers.length === blockers.length ? visibleBlockers : [...visibleBlockers, "a task in another project"],
+        position: lens === null ? store.queuePosition(id) : null,
         reservedFor: ref.assignedRunner,
         hold: store.activeHold(ref.id, now),
         claim: currentClaim(store, ref.id, now),
@@ -10664,7 +10808,7 @@ function showTask(positional, context) {
         // The one automatic review of the latest build: HIGH findings, suggested
         // follow-ups (MEDIUM/LOW), or why it was not reviewed.
         automaticReview: latestFinished === null ? null : buildReviewOf(store, latestFinished.id),
-        dispatch: diagnoseTaskDispatch(store, id, now),
+        dispatch: diagnoseTaskDispatch(store, id, now, lens),
         // v52: the exact-run control the console shows — Stop, Stopping,
         // Paused (resume), or the review-retry door — and every stop on record.
         control: taskControlOf(store, ref.id, now),
@@ -12020,6 +12164,10 @@ async function chatCommand(flags, context) {
  * win, and a different --as than the remembered name is not answered.
  */
 function credentialsFrom(flags, context) {
+    // A remote run is its token's person, whatever the flags or this machine's saved login say.
+    const remote = activeRemote();
+    if (remote !== null)
+        return { name: remote.account, token: remote.secret };
     // The lead signs in as its owner with its own token, never the owner's password.
     const lead = currentActor();
     if (context.leadToken !== undefined && lead?.lead === true)
@@ -12045,16 +12193,55 @@ async function askCredentials(flags, context) {
         return null;
     return { name, token };
 }
+/*
+ * Credential checks in this file. Locally they are the password checks in scope.ts and principal.ts. Inside a
+ * remote run (`runOperateAs`) the only credential is the one credentialsFrom handed out for the token's person,
+ * which scope.ts's authenticateAccount takes as that person (a viewer for a read token) and never checks as a
+ * password; these add the token's own project limit.
+ */
+function authenticateApprover(store, by, token, repo) {
+    const remote = activeRemote();
+    if (remote !== null && repo !== undefined && !remote.allows(repo))
+        return { ok: false, reason: "not-an-approver" };
+    return passwordApprover(store, by, token, repo);
+}
+function verifyApproverByPassword(store, name, token, repos) {
+    const remote = activeRemote();
+    return approverByPassword(store, name, token, remote === null ? repos : repos.filter(repo => remote.allows(repo)));
+}
+/** Prompts: never inside a remote run — there is nobody at this machine's terminal to answer for the person. */
+function interactive() {
+    return activeRemote() === null && promptInteractive();
+}
+function refusePrompt() {
+    if (activeRemote() !== null)
+        throw new RemoteRefusal("unauthenticated", REMOTE_MESSAGES.credential);
+}
+async function ask(question) {
+    refusePrompt();
+    return promptAsk(question);
+}
+async function askHidden(question) {
+    refusePrompt();
+    return promptHidden(question);
+}
+async function confirm(question) {
+    refusePrompt();
+    return promptConfirm(question);
+}
 /** `flows …`: the console's flow rules from a terminal. Writes are an approver's (--as/--token or the remembered login). */
 async function flowsCommand(positional, flags, context) {
     const { store } = context;
     const registered = await loadRepos(registryPathOf(context)).catch(() => ({ error: "unreadable" }));
-    const projects = [...new Set([...store.knownRepos(), ...store.listProjects().map(one => one.path), ...("error" in registered ? [] : registered.repos)])];
+    const remote = activeRemote();
+    // A remote person sees and changes flows only in their own projects, and sends any flow file with the request.
+    const projects = [...new Set([...store.knownRepos(), ...store.listProjects().map(one => one.path), ...("error" in registered ? [] : registered.repos)])].filter(one => remote === null || remote.allows(one));
     const writes = positional[0] !== undefined && positional[0] !== "list" && positional[0] !== "show" && positional[0] !== "export";
     const acting = writes && !flags.has("help") ? await askCredentials(flags, context) : null;
     const dir = dirname(context.databaseFile);
     return runFlowsCommand(positional, flags, {
         store, write: context.write, json: context.json, clock: context.clock, credentials: acting, projects, configDir: dir, evidenceRoot: context.evidenceRoot,
+        ...(remote === null ? {} : { readInput: (path) => remoteFile(remote, path) }),
         ...(context.flowFetch === undefined ? {} : { fetchFlow: context.flowFetch }),
         // "Check now": the same io the worker's pass checks triggers with.
         triggerIo: { gh: context.flowTriggerIo?.gh ?? run, fetch: context.flowTriggerIo?.fetch ?? fetch, dir: context.flowTriggerIo?.dir ?? dir,

package/dist/remote-command.d.ts

@@ -0,0 +1,45 @@
+import { type CommandFlag } from './surface.js';
+export type RemoteMode = 'yes' | 'no' | 'step-up';
+export type RemoteCommand = {
+    invocation: string;
+    mode: RemoteMode;
+    mutation: string;
+    flags?: readonly Pick<CommandFlag, 'name' | 'takesValue'>[];
+};
+export type RemoteCommandLookup = (argv: readonly string[]) => RemoteCommand | null;
+export declare const STEP_UP_MESSAGE = "approve in the console or chat";
+type PathPolicy = 'inline' | 'refuse';
+export type RemotePathArgument = {
+    invocation: string;
+    argument: {
+        flag: string;
+    } | {
+        position: number;
+        name: string;
+        rest?: true;
+    };
+    policy: PathPolicy;
+    literal?: 'json' | 'url';
+};
+/**
+ * Filesystem arguments audited against operate.ts, flows-cli.ts and cli.ts's local dispatchers.
+ * Keep this inventory command-specific: --file runs a project executable for scripts, but is a
+ * boolean for template apply; --to is a directory for link and a date for ledger export.
+ * Project selectors (--repo), scope globs (--touches/--paths) and saved IDs are not input files;
+ * their authority belongs to runOperateAs. Local installers' explicit destinations are refused.
+ * '*' is reserved for the credentials/database and cli.ts's output redirection, on every command.
+ */
+export declare const REMOTE_PATH_ARGUMENTS: readonly RemotePathArgument[];
+type FileProblem = {
+    problem: string;
+    code: 'local-only-flag' | 'server-path' | 'missing-file' | 'invalid-arguments';
+};
+/**
+ * Parse once using declared arity, so a flag's value cannot be mistaken for another flag or a
+ * file positional. Unknown arity fails closed. File keys and argv stay exactly as typed.
+ * All failures describe the argument slot, never a supplied path, credential or other value.
+ */
+export declare function fileArguments(argv: readonly string[], row: RemoteCommand): string[] | FileProblem;
+/** The longest declared invocation named by the leading words. Missing remote metadata means local only. */
+export declare const contractRow: RemoteCommandLookup;
+export {};

package/dist/remote-command.js

@@ -0,0 +1,124 @@
+import { COMMAND_GUIDE } from './surface.js';
+export const STEP_UP_MESSAGE = 'approve in the console or chat';
+/**
+ * Filesystem arguments audited against operate.ts, flows-cli.ts and cli.ts's local dispatchers.
+ * Keep this inventory command-specific: --file runs a project executable for scripts, but is a
+ * boolean for template apply; --to is a directory for link and a date for ledger export.
+ * Project selectors (--repo), scope globs (--touches/--paths) and saved IDs are not input files;
+ * their authority belongs to runOperateAs. Local installers' explicit destinations are refused.
+ * '*' is reserved for the credentials/database and cli.ts's output redirection, on every command.
+ */
+export const REMOTE_PATH_ARGUMENTS = [
+    ...['--token', '--token-file', '--token-env', '--db', '-o', '--output'].map(flag => ({ invocation: '*', argument: { flag }, policy: 'refuse' })),
+    { invocation: 'flows create', argument: { flag: '--steps' }, policy: 'inline', literal: 'json' },
+    { invocation: 'flows edit', argument: { flag: '--steps' }, policy: 'inline', literal: 'json' },
+    { invocation: 'flows script save', argument: { flag: '--body' }, policy: 'inline' },
+    { invocation: 'flows script save', argument: { flag: '--file' }, policy: 'refuse' },
+    { invocation: 'flows export', argument: { flag: '--out' }, policy: 'refuse' },
+    // Import stats the original path before readInput. Inlining alone cannot prevent that server read.
+    { invocation: 'flows import', argument: { position: 0, name: 'file' }, policy: 'refuse', literal: 'url' },
+    { invocation: 'flows trigger add', argument: { position: 1, name: 'trigger' }, policy: 'inline', literal: 'json' },
+    { invocation: 'task evidence', argument: { flag: '--out' }, policy: 'refuse' },
+    { invocation: 'ledger export', argument: { flag: '--out' }, policy: 'refuse' },
+    { invocation: 'export', argument: { flag: '--out' }, policy: 'refuse' },
+    { invocation: 'restore', argument: { position: 0, name: 'backup file' }, policy: 'refuse' },
+    { invocation: 'storage discard', argument: { position: 0, name: 'checkout path' }, policy: 'refuse' },
+    { invocation: 'keys set', argument: { flag: '--key-file' }, policy: 'refuse' },
+    { invocation: 'daemon', argument: { flag: '--bin' }, policy: 'refuse' },
+    ...['build', 'tick', 'reconcile', 'watch', 'serve', 'up', 'daemon', 'task resume'].map(invocation => ({ invocation, argument: { flag: '--pool' }, policy: 'refuse' })),
+    ...['serve', 'up'].map(invocation => ({ invocation, argument: { flag: '--project-root' }, policy: 'refuse' })),
+    { invocation: 'skills install', argument: { flag: '--dir' }, policy: 'refuse' },
+    { invocation: 'skills install', argument: { flag: '--repo' }, policy: 'refuse' },
+    { invocation: 'onboard', argument: { flag: '--repo' }, policy: 'refuse' },
+    { invocation: 'repos add-from-github', argument: { flag: '--root' }, policy: 'refuse' },
+    ...['link', 'unlink'].map(invocation => ({ invocation, argument: { flag: '--to' }, policy: 'refuse' })),
+    ...['repos add', 'repos remove', 'pulls', 'graph', ''].map(invocation => ({ invocation, argument: { position: 0, name: 'path', rest: true }, policy: 'refuse' })),
+    { invocation: 'project use', argument: { position: 0, name: 'checkout path' }, policy: 'refuse' },
+    // These local HTTP clients read prompts themselves; they do not consume runOperateAs's files map.
+    ...['session start', 'session send'].map(invocation => ({ invocation, argument: { flag: '--file' }, policy: 'refuse' })),
+];
+/**
+ * Parse once using declared arity, so a flag's value cannot be mistaken for another flag or a
+ * file positional. Unknown arity fails closed. File keys and argv stay exactly as typed.
+ * All failures describe the argument slot, never a supplied path, credential or other value.
+ */
+export function fileArguments(argv, row) {
+    const paths = [];
+    const rules = REMOTE_PATH_ARGUMENTS.filter(one => one.invocation === '*' || one.invocation === row.invocation);
+    const words = row.invocation === '' ? [] : row.invocation.split(' ');
+    if (!words.every((word, index) => argv[index] === word))
+        return { problem: 'The command arguments do not match its invocation.', code: 'invalid-arguments' };
+    const inspect = (rule, value) => {
+        const label = 'flag' in rule.argument ? rule.argument.flag : `${row.invocation} ${rule.argument.name} argument`;
+        if (rule.invocation === '*' && 'flag' in rule.argument && rule.argument.flag !== '-o' && rule.argument.flag !== '--output') {
+            return { problem: `${label} cannot be used remotely. Sign in with your saved API token.`, code: 'local-only-flag' };
+        }
+        if (value !== undefined && (rule.literal === 'json' && /^[{[]/.test(value.trim()) || rule.literal === 'url' && /^[a-z][a-z0-9+.-]*:\/\//i.test(value)))
+            return;
+        if (rule.policy === 'refuse')
+            return { problem: `${label} cannot use a server path remotely. Use --local to run it here.`, code: 'server-path' };
+        if (value === undefined || value === '')
+            return { problem: `${label} needs a file path.`, code: 'missing-file' };
+        // '-' would otherwise read the server's stdin (or a client file literally named '-'). Never prompt.
+        if (value === '-')
+            return { problem: `${label} needs a file instead of stdin for a remote command.`, code: 'server-path' };
+        paths.push(value);
+    };
+    let position = 0;
+    for (let index = words.length; index < argv.length; index++) {
+        const argument = argv[index], equals = argument.indexOf('=');
+        const name = equals < 0 ? argument : argument.slice(0, equals);
+        if (argument.startsWith('--') || name === '-o' || name === '-h') {
+            const rule = rules.find(one => 'flag' in one.argument && one.argument.flag === name);
+            const takesValue = rule !== undefined ? true : name === '-h' || name === '--help' || name === '--json' ? false : row.flags?.find(flag => `--${flag.name}` === name)?.takesValue;
+            if (takesValue === undefined)
+                return { problem: 'This option is not declared for remote use. Use --local to run it here.', code: 'invalid-arguments' };
+            if (!takesValue) {
+                if (equals >= 0)
+                    return { problem: 'This command switch does not take a value.', code: 'invalid-arguments' };
+                continue;
+            }
+            const next = equals < 0 ? argv[index + 1] : argument.slice(equals + 1);
+            const value = equals < 0 && next?.startsWith('--') ? undefined : next;
+            if (rule !== undefined) {
+                const problem = inspect(rule, value);
+                if (problem !== undefined)
+                    return problem;
+            }
+            if (value === undefined)
+                return { problem: 'A command option needs a value.', code: 'invalid-arguments' };
+            if (equals < 0)
+                index++;
+        }
+        else {
+            const rule = rules.find(one => 'position' in one.argument && (one.argument.position === position || one.argument.rest && position >= one.argument.position));
+            if (rule !== undefined) {
+                const problem = inspect(rule, argument);
+                if (problem !== undefined)
+                    return problem;
+            }
+            position++;
+        }
+    }
+    return paths;
+}
+/** The longest declared invocation named by the leading words. Missing remote metadata means local only. */
+export const contractRow = argv => {
+    const words = [];
+    for (const one of argv) {
+        if (one.startsWith('-'))
+            break;
+        words.push(one);
+    }
+    let best = null;
+    for (const row of COMMAND_GUIDE) {
+        const parts = row.invocation.split(' ');
+        if (parts.length > words.length || !parts.every((part, index) => words[index] === part))
+            continue;
+        if (best !== null && best.invocation.split(' ').length >= parts.length)
+            continue;
+        const remote = row.remote;
+        best = { invocation: row.invocation, mode: remote === 'yes' || remote === 'step-up' ? remote : 'no', mutation: row.mutation, flags: row.flags ?? [] };
+    }
+    return best;
+};

package/dist/remote-exec.d.ts

@@ -0,0 +1,18 @@
+import { type TeamCliOptions } from './team-cli.js';
+import { type RemoteCommandLookup } from './remote-command.js';
+export { contractRow, STEP_UP_MESSAGE, type RemoteMode } from './remote-command.js';
+export type RemoteExecOptions = TeamCliOptions & {
+    cwd?: string;
+    /** Raw output streams; remote bytes are written exactly as the server returned them. */
+    stdout?: (chunk: string) => void;
+    stderr?: (chunk: string) => void;
+    /** Injected by tests: the contract row lookup (default: COMMAND_GUIDE's `remote` field). */
+    modeOf?: RemoteCommandLookup;
+};
+/**
+ * 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 declare function maybeRunRemoteCommand(argv: readonly string[], options?: RemoteExecOptions): Promise<number | {
+    local: string[];
+} | null>;