toolroll 0.9.56 → 0.9.58

package/dist/session-cli.js

@@ -1,19 +1,100 @@
 import { open } from 'node:fs/promises';
 import { envelopeJson } from './envelope.js';
-import { SESSION_DESCRIPTORS, SESSION_PROMPT_BYTES, SESSION_RESPONSE_BYTES, isSessionResponse, sessionCapabilities, sessionDescriptor, validateSessionRequest, } from './session-contract.js';
-const commonFlags = { url: 'value', as: 'value', 'token-env': 'value', 'token-file': 'value', json: 'flag', help: 'flag' };
+import { SESSION_DESCRIPTORS, SESSION_PROMPT_BYTES, isSessionResponse, sessionCapabilities, sessionDescriptor, validateSessionRequest, } from './session-contract.js';
+import { centralProfile, UsageError } from './team-cli.js';
+import { postCli } from './remote-exec.js';
+import { TOKEN_REPLACEMENT } from './password-bearer.js';
+/** The files key the prompt travels under: the server reads no paths, only what the request carries. */
+export const SESSION_PROMPT_FILE = 'prompt';
 export const SESSION_CLI_ACTIONS = ['capabilities', ...SESSION_DESCRIPTORS.map(one => one.operation)];
-export function sessionCliFlags(spec) {
-    return { ...commonFlags, ...Object.fromEntries(Object.keys(spec.flags).map(name => [name, 'value'])), ...(spec.operation === 'start' || spec.operation === 'send' ? { file: 'value', stdin: 'flag' } : {}) };
+/** Before D7 the session client signed in with an operator password on every request. */
+const RETIRED_FLAGS = new Set(['url', 'as', 'token-env', 'token-file']);
+export const SESSION_TOKEN_REQUIRED = `Session commands use your saved API token. ${TOKEN_REPLACEMENT}, then save it with \`toolroll connect <origin> --as <account> --token-stdin\`.`;
+/** The flags an operation takes: on this computer (where the prompt may come from a file or stdin, and a saved
+ * profile is chosen), or on the server (where the prompt is only ever the request's own file). */
+export function sessionCliFlags(spec, side = 'client') {
+    const prompt = spec.operation === 'start' || spec.operation === 'send';
+    return { json: 'flag', help: 'flag', ...(side === 'client' ? { profile: 'value' } : {}),
+        ...Object.fromEntries(Object.keys(spec.flags).map(name => [name, 'value'])),
+        ...(prompt ? { file: 'value', ...(side === 'client' ? { stdin: 'flag' } : {}) } : {}) };
 }
 function help(spec) {
     if (!spec)
-        return `toolroll session <operation>\n\n${SESSION_DESCRIPTORS.map(one => `  ${one.operation.padEnd(12)} ${one.synopsis}`).join('\n')}\n  capabilities  Show this client's schemas and authority requirements\n\nUse session <operation> --help for required flags. Session controls require operator credentials. Chat is the separate coordinator conversation.`;
+        return `toolroll session <operation>\n\n${SESSION_DESCRIPTORS.map(one => `  ${one.operation.padEnd(12)} ${one.synopsis}`).join('\n')}\n  capabilities  Show this client's schemas and authority requirements\n\nUse session <operation> --help for required flags. Sessions run on the server you connected to with your API token (toolroll connect); they need instance operator access.`;
     const fields = spec.inputSchema.required.filter(one => !['version', 'sessionId', 'prompt'].includes(one));
     const required = fields.map(field => Object.entries(spec.flags).find(([, value]) => value.field === field)?.[0]).filter(Boolean);
-    return `toolroll session ${spec.operation}${'sessionId' in spec.inputSchema.properties ? ' <session-id>' : ''}\n${spec.synopsis}.\n\nRequired: --url <service-origin> --as <operator>\n  --token-env <variable-name> or --token-file <path>\n${required.map(name => `  --${name} <value>`).join('\n')}${'prompt' in spec.inputSchema.properties ? '\n  --file <path> or --stdin (complete prompt, up to 64 KB)' : ''}\n${'expectedRevision' in spec.inputSchema.properties ? '\nUse the revision, nativeThreadId and turnId from session show. Use none for a null thread or turn.\n' : ''}\nOptions: ${Object.keys(sessionCliFlags(spec)).map(name => `--${name}`).join(' ')}\nCredentials are sent only to the named HTTPS service or loopback HTTP. Redirects and automatic mutation retries are disabled.`;
+    return `toolroll session ${spec.operation}${'sessionId' in spec.inputSchema.properties ? ' <session-id>' : ''}\n${spec.synopsis}.\n\n${required.length > 0 ? `Required:\n${required.map(name => `  --${name} <value>`).join('\n')}\n` : ''}${'prompt' in spec.inputSchema.properties ? '  --file <path> or --stdin (complete prompt, up to 64 KB)\n' : ''}${'expectedRevision' in spec.inputSchema.properties ? '\nUse the revision, nativeThreadId and turnId from session show. Use none for a null thread or turn.\n' : ''}\nOptions: ${Object.keys(sessionCliFlags(spec)).map(name => `--${name}`).join(' ')}\nRuns on the saved connection (or --profile <name>) over /api/cli with your API token. Mutations are never retried automatically.`;
 }
-class UsageError extends Error {
+/** One parser for both sides of /api/cli: `<operation> [<session-id>] --flag value …`. */
+export function parseSessionArguments(argv, side) {
+    const operation = argv[0] ?? '';
+    const spec = sessionDescriptor(operation);
+    if (!spec)
+        return { problem: `Unknown session operation. Use: ${SESSION_CLI_ACTIONS.join(', ')}.` };
+    const allowed = sessionCliFlags(spec, side);
+    const flags = {};
+    const positionals = [];
+    for (let index = 1; index < argv.length; index++) {
+        const argument = argv[index];
+        if (!argument.startsWith('-')) {
+            positionals.push(argument);
+            continue;
+        }
+        const name = argument === '-h' ? 'help' : argument.startsWith('--') ? argument.slice(2) : '';
+        if (side === 'client' && RETIRED_FLAGS.has(name))
+            return { problem: SESSION_TOKEN_REQUIRED };
+        if (!Object.hasOwn(allowed, name))
+            return { problem: `Unknown option ${argument} for session ${operation}.` };
+        if (Object.hasOwn(flags, name))
+            return { problem: `Option --${name} was repeated.` };
+        if (allowed[name] === 'flag')
+            flags[name] = true;
+        else {
+            const value = argv[++index];
+            if (!value || value.startsWith('-'))
+                return { problem: `--${name} requires a value.` };
+            flags[name] = value;
+        }
+    }
+    return { spec, flags, positionals };
+}
+/** The validated request the parsed arguments and prompt spell. */
+export function sessionRequestOf({ spec, flags, positionals }, prompt) {
+    const request = { version: 1 };
+    if ('sessionId' in spec.inputSchema.properties) {
+        if (positionals.length !== 1)
+            return { ok: false, message: 'Name exactly one session ID.' };
+        request['sessionId'] = positionals[0];
+    }
+    else if (positionals.length)
+        return { ok: false, message: 'This operation takes no positional arguments.' };
+    for (const [name, field] of Object.entries(spec.flags)) {
+        const raw = flags[name];
+        if (typeof raw !== 'string')
+            continue;
+        if (field.kind === 'integer' && !/^\d+$/.test(raw))
+            return { ok: false, message: `--${name} must be a whole number.` };
+        request[field.field] = field.kind === 'integer' ? Number(raw) : field.kind === 'nullable-id' && raw === 'none' ? null : raw;
+    }
+    if (prompt !== undefined)
+        request['prompt'] = prompt;
+    return validateSessionRequest(spec.operation, request);
+}
+/** The exact argv the server runs for a validated request: always --json, the prompt as the request's one file. */
+export function sessionArgv(spec, request) {
+    const fields = request;
+    const argv = ['session', spec.operation];
+    if (typeof fields['sessionId'] === 'string')
+        argv.push(fields['sessionId']);
+    for (const [name, field] of Object.entries(spec.flags)) {
+        const value = fields[field.field];
+        if (value !== undefined)
+            argv.push(`--${name}`, value === null ? 'none' : String(value));
+    }
+    if (typeof fields['prompt'] === 'string')
+        argv.push('--file', SESSION_PROMPT_FILE);
+    argv.push('--json');
+    return argv;
 }
 async function readBoundedFile(path, limit, label) {
     let file;
@@ -60,90 +141,6 @@ async function readStdin() {
         throw new UsageError('The prompt must be UTF-8 text.');
     }
 }
-/** Credentials are never sent to a URL with embedded authority, an API path,
- * query, fragment or an insecure remote host. Fetch cannot follow redirects. */
-export function sessionServiceOrigin(raw) {
-    let url;
-    try {
-        url = new URL(raw);
-    }
-    catch {
-        throw new UsageError('--url must be an HTTPS or loopback HTTP service origin.');
-    }
-    if (url.username || url.password || url.search || url.hash || url.pathname !== '/')
-        throw new UsageError('--url must contain only the service origin, with no credentials, path, query or fragment.');
-    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname)))
-        throw new UsageError('--url requires HTTPS except for loopback HTTP.');
-    return url.origin;
-}
-async function parseRequest(spec, flags, positionals, options) {
-    const value = (name) => typeof flags[name] === 'string' ? flags[name] : '';
-    const url = sessionServiceOrigin(value('url'));
-    const account = value('as');
-    if (!account || account.length > 200 || /[\s:\x00-\x1f\x7f]/.test(account))
-        throw new UsageError('--as must name the operator account.');
-    if (Boolean(flags['token-env']) === Boolean(flags['token-file']))
-        throw new UsageError('Choose exactly one credential source: --token-env <variable-name> or --token-file <path>.');
-    let token;
-    if (flags['token-env']) {
-        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value('token-env')))
-            throw new UsageError('--token-env must name an environment variable.');
-        token = (options.env ?? process.env)[value('token-env')] ?? '';
-    }
-    else
-        token = (await readBoundedFile(value('token-file'), 8192, 'The token file')).trim();
-    if (!token || token.length > 8192 || /[\s\x00-\x1f\x7f]/.test(token))
-        throw new UsageError('The selected credential is empty or invalid. Set the named variable or token file.');
-    const request = { version: 1 };
-    if ('sessionId' in spec.inputSchema.properties) {
-        if (positionals.length !== 1)
-            throw new UsageError('Name exactly one session ID.');
-        request['sessionId'] = positionals[0];
-    }
-    else if (positionals.length)
-        throw new UsageError('This operation takes no positional arguments.');
-    for (const [name, field] of Object.entries(spec.flags)) {
-        if (flags[name] === undefined)
-            continue;
-        const raw = value(name);
-        if (field.kind === 'integer' && !/^\d+$/.test(raw))
-            throw new UsageError(`--${name} must be a whole number.`);
-        request[field.field] = field.kind === 'integer' ? Number(raw) : field.kind === 'nullable-id' && raw === 'none' ? null : raw;
-    }
-    if ('prompt' in spec.inputSchema.properties) {
-        if (Boolean(flags['file']) === Boolean(flags['stdin']))
-            throw new UsageError('Choose exactly one prompt source: --file <path> or --stdin.');
-        request['prompt'] = flags['file'] ? await readBoundedFile(value('file'), SESSION_PROMPT_BYTES, 'The prompt file') : await (options.readStdin ?? readStdin)();
-    }
-    const validated = validateSessionRequest(spec.operation, request);
-    if (!validated.ok)
-        throw new UsageError(validated.message);
-    return { spec, request: validated.request, url, account, token };
-}
-async function readResponse(response) {
-    if (!response.body)
-        throw new Error('Missing response body');
-    const reader = response.body.getReader();
-    const chunks = [];
-    let bytes = 0;
-    try {
-        while (true) {
-            const chunk = await reader.read();
-            if (chunk.done)
-                break;
-            bytes += chunk.value.byteLength;
-            if (bytes > SESSION_RESPONSE_BYTES) {
-                await reader.cancel();
-                throw new Error('Response limit');
-            }
-            chunks.push(chunk.value);
-        }
-    }
-    finally {
-        reader.releaseLock();
-    }
-    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
-}
 function unconfirmed(spec, request) {
     const sessionId = 'sessionId' in request ? request.sessionId : undefined;
     return { version: 1, operation: spec.operation, ok: false, status: spec.mutation ? 'uncertain' : 'rejected',
@@ -152,42 +149,39 @@ function unconfirmed(spec, request) {
         message: spec.mutation ? 'The service response could not be confirmed. Inspect the saved session before continuing; the request was not retried.' : 'The service response could not be read. Check the service address and connection.',
         nextActions: [{ operation: sessionId ? 'show' : 'list', label: sessionId ? 'Inspect session' : 'List sessions', ...(sessionId ? { sessionId } : {}) }] };
 }
-async function perform(parsed, options) {
-    const { spec, request, url, account, token } = parsed;
-    try {
-        const response = await (options.fetch ?? fetch)(`${url}/api/sessions/${spec.operation}`, {
-            method: 'POST', redirect: 'manual', credentials: 'omit', signal: AbortSignal.timeout(60_000),
-            headers: { authorization: `Bearer ${account}:${token}`, 'content-type': 'application/json', accept: 'application/json' }, body: JSON.stringify(request),
-        });
-        if (response.status >= 300 && response.status < 400) {
-            await response.body?.cancel();
-            return unconfirmed(spec, request);
-        }
-        // This marker belongs to the owner boundary. A bare gateway 503 or 404
-        // cannot prove that an upstream mutation was never accepted.
-        if ([401, 403, 404, 503].includes(response.status) && response.headers.get('x-standing-orders-session-delivery') === 'not-sent') {
-            await response.body?.cancel();
-            const reason = response.status === 401 ? 'unauthenticated' : response.status === 403 ? 'forbidden' : response.status === 404 ? 'session-unsupported' : 'session-unavailable';
-            return { version: 1, operation: spec.operation, ok: false, status: 'rejected', delivery: 'not-sent', retry: spec.mutation ? 'never' : 'safe-read', reason,
-                message: response.status === 401 || response.status === 403 ? 'The service refused these operator credentials. Check the account and its access.' : 'This service does not currently support the requested session operation. Check its installed build and readiness.', nextActions: [] };
-        }
-        const payload = await readResponse(response);
-        if (!isSessionResponse(payload, spec.operation) || (payload.ok && !response.ok))
-            return unconfirmed(spec, request);
-        if ('sessionId' in request && payload.result?.session && payload.result.session.id !== request.sessionId)
-            return unconfirmed(spec, request);
-        if (payload.ok && 'key' in request && payload.result?.receipt?.key !== request.key)
-            return unconfirmed(spec, request);
-        if (payload.ok && 'expectedThreadId' in request && request.expectedThreadId !== null && payload.result?.session?.nativeThreadId !== request.expectedThreadId)
+/** One request over /api/cli, never retried. Only an answer whose identity matches the request counts as delivered. */
+async function perform(spec, request, profile, options) {
+    const files = typeof request.prompt === 'string' ? { [SESSION_PROMPT_FILE]: request.prompt } : {};
+    const outcome = await postCli(profile.origin, profile.token, { argv: sessionArgv(spec, request), files }, options);
+    if (outcome.kind === 'unconfirmed')
+        return unconfirmed(spec, request);
+    if (outcome.kind === 'refused') {
+        // /api/cli refuses before it runs anything, except a command that stopped on the server: that one may have acted.
+        if (outcome.status >= 500 && outcome.status !== 501 && outcome.status !== 503)
             return unconfirmed(spec, request);
-        return payload;
+        return { version: 1, operation: spec.operation, ok: false, status: 'rejected', delivery: 'not-sent', retry: spec.mutation ? 'never' : 'safe-read',
+            reason: /^[a-z][a-z0-9-]*$/.test(outcome.code) ? outcome.code : 'refused', message: outcome.message, nextActions: [] };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(outcome.answer.stdout);
     }
     catch {
         return unconfirmed(spec, request);
     }
+    if (!isSessionResponse(payload, spec.operation))
+        return unconfirmed(spec, request);
+    if ('sessionId' in request && payload.result?.session && payload.result.session.id !== request.sessionId)
+        return unconfirmed(spec, request);
+    if (payload.ok && 'key' in request && payload.result?.receipt?.key !== request.key)
+        return unconfirmed(spec, request);
+    if (payload.ok && 'expectedThreadId' in request && request.expectedThreadId !== null && payload.result?.session?.nativeThreadId !== request.expectedThreadId)
+        return unconfirmed(spec, request);
+    return payload;
 }
 const terminalText = (value) => value.replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
-function render(response) {
+/** The plain-text answer, the same on either side of the transport. */
+export function renderSessionResponse(response) {
     const result = response.result;
     const lines = response.ok && response.operation === 'show' && result?.brief ? [] : [response.message];
     for (const session of result?.sessions ?? [])
@@ -210,6 +204,8 @@ function render(response) {
         lines.push(`${action.label}: ${action.operation === 'open-ui' ? 'open the coding workspace' : `toolroll session ${action.operation}${action.sessionId ? ` ${action.sessionId}` : ''}`}`);
     return terminalText(lines.join('\n'));
 }
+/** 0 delivered · 1 unknown (inspect first) · 3 refused. */
+export const sessionExitCode = (response) => response.ok ? 0 : response.status === 'uncertain' || response.reason === 'service-unavailable' ? 1 : 3;
 export async function runSessionCommand(argv, write, options = {}) {
     const json = argv.includes('--json');
     const stderr = options.stderr ?? (line => process.stderr.write(`${line}\n`));
@@ -236,49 +232,40 @@ export async function runSessionCommand(argv, write, options = {}) {
         write(json ? envelopeJson({ ok: true, command, ...sessionCapabilities() }) : help());
         return 0;
     }
-    const spec = sessionDescriptor(operation);
-    if (!spec)
-        return fail(`Unknown session operation. Use: ${SESSION_CLI_ACTIONS.join(', ')}.`);
-    const allowed = sessionCliFlags(spec);
-    const flags = {};
-    const positionals = [];
-    for (let index = 1; index < argv.length; index++) {
-        const argument = argv[index];
-        if (!argument.startsWith('-')) {
-            positionals.push(argument);
-            continue;
-        }
-        const name = argument === '-h' ? 'help' : argument.startsWith('--') ? argument.slice(2) : '';
-        if (!Object.hasOwn(allowed, name))
-            return fail(`Unknown option ${argument} for session ${operation}.`);
-        if (Object.hasOwn(flags, name))
-            return fail(`Option --${name} was repeated.`);
-        if (allowed[name] === 'flag')
-            flags[name] = true;
-        else {
-            const value = argv[++index];
-            if (!value || value.startsWith('-'))
-                return fail(`--${name} requires a value.`);
-            flags[name] = value;
-        }
-    }
+    const parsed = parseSessionArguments(argv, 'client');
+    if ('problem' in parsed)
+        return fail(parsed.problem);
+    const { spec, flags } = parsed;
     if (flags['help']) {
         write(json ? envelopeJson({ ok: true, command, descriptor: spec, help: help(spec) }) : help(spec));
         return 0;
     }
-    let parsed;
+    let request;
+    let profile;
     try {
-        parsed = await parseRequest(spec, flags, positionals, options);
+        let prompt;
+        if ('prompt' in spec.inputSchema.properties) {
+            if (Boolean(flags['file']) === Boolean(flags['stdin']))
+                throw new UsageError('Choose exactly one prompt source: --file <path> or --stdin.');
+            prompt = typeof flags['file'] === 'string' ? await readBoundedFile(flags['file'], SESSION_PROMPT_BYTES, 'The prompt file') : await (options.readStdin ?? readStdin)();
+        }
+        const validated = sessionRequestOf(parsed, prompt);
+        if (!validated.ok)
+            throw new UsageError(validated.message);
+        request = validated.request;
+        profile = centralProfile(options, typeof flags['profile'] === 'string' ? flags['profile'] : undefined);
     }
     catch (error) {
-        return fail(error instanceof UsageError ? error.message : 'The session request could not be prepared. Check the prompt and credential source.');
+        return fail(error instanceof UsageError ? error.message : 'The session request could not be prepared. Check the prompt and saved connection.');
     }
-    const response = await perform(parsed, options);
+    if (profile === null || !profile.apiToken)
+        return fail(SESSION_TOKEN_REQUIRED);
+    const response = await perform(spec, request, profile, options);
     if (json)
-        write(envelopeJson({ ...response, command, ...('key' in parsed.request ? { key: parsed.request.key } : {}) }));
+        write(envelopeJson({ ...response, command, ...('key' in request ? { key: request.key } : {}) }));
     else if (response.ok)
-        write(render(response));
+        write(renderSessionResponse(response));
     else
-        stderr(render(response));
-    return response.ok ? 0 : response.status === 'uncertain' || response.reason === 'service-unavailable' ? 1 : 3;
+        stderr(renderSessionResponse(response));
+    return sessionExitCode(response);
 }

package/dist/session-contract.js

@@ -114,8 +114,8 @@ export function isSessionResponse(value, operation) {
     return true;
 }
 export function sessionCapabilities() {
-    return { version: SESSION_PROTOCOL_VERSION, transport: 'POST /api/sessions/<operation>', authentication: 'operator account: Authorization Bearer name:token',
-        authority: 'Operator credentials are required for session reads and controls. External coordinator credentials have no session access.',
+    return { version: SESSION_PROTOCOL_VERSION, transport: 'POST /api/cli with argv session <operation> (the prompt travels as the request\'s one file)', authentication: 'API token: Authorization Bearer so_… (toolroll tokens create, saved by toolroll connect)',
+        authority: 'An instance operator\'s API token without a project limit reads sessions; changing one needs an act token. Lead and coordinator credentials have no session access.',
         operations: SESSION_DESCRIPTORS, brief: { supported: true, operation: 'show', defaultView: 'brief', source: 'Saved state and labeled agent reports, pinned to a revision; no additional model call.' },
         unsupported: ['events', 'review', 'continue'], limits: { promptBytes: SESSION_PROMPT_BYTES, requestBytes: SESSION_REQUEST_BYTES, responseBytes: SESSION_RESPONSE_BYTES },
         retry: 'Never automatically retry a mutation. Inspect saved state after a lost response; keep the original key.' };

package/dist/session-remote.d.ts

@@ -0,0 +1,19 @@
+import type { Store } from './store.js';
+import type { CodingWorkspace } from './coding-workspace.js';
+import { type Principal } from './operate-remote.js';
+/**
+ * The server half of `toolroll session …` over `POST /api/cli` (D7, replacing the separate /api/sessions transport and
+ * its password sign-in). /api/cli has already proved the API token and charged its budget; this binds the token's
+ * person to the existing session owner, which rechecks the account and project on every operation. Native sessions
+ * stay installation-wide operator authority: only an instance operator's act token, limited to no projects, may
+ * change one. Every request is in the action ledger like any remote command, and every answer is one session
+ * envelope: a mutation whose outcome is unknown says so, and is never retried here.
+ */
+export type SessionRunner = (principal: Principal, argv: readonly string[], files: Readonly<Record<string, string>>, write: (line: string) => void) => Promise<number>;
+export declare function createSessionRunner(options: {
+    store: Store;
+    workspace: CodingWorkspace | null;
+    projects: () => readonly string[];
+    projectAllowed: (repo: string) => boolean;
+    clock?: () => Date;
+}): SessionRunner;

package/dist/session-remote.js

@@ -0,0 +1,86 @@
+import { realpathSync } from 'node:fs';
+import { envelopeJson } from './envelope.js';
+import { REMOTE_MESSAGES, reproveRemote } from './operate-remote.js';
+import { SESSION_RESPONSE_BYTES, isSessionResponse } from './session-contract.js';
+import { parseSessionArguments, renderSessionResponse, sessionExitCode, sessionRequestOf } from './session-cli.js';
+import { SessionService } from './session-service.js';
+export function createSessionRunner(options) {
+    const { store } = options;
+    const clock = options.clock ?? (() => new Date());
+    const authorized = (actor, repo) => {
+        const account = store.accountOf(actor.name);
+        return account !== null && account.revokedAt === null && account.generation === actor.generation && store.isInstanceOperator(actor.name)
+            && (repo === undefined || (options.projectAllowed(repo) && options.projects().includes(repo)));
+    };
+    const service = options.workspace === null || store.isDemo() ? null : new SessionService({ workspace: options.workspace, authorized,
+        project: (actor, input) => {
+            const path = realpathSync(input);
+            if (!authorized(actor, path) || !options.projects().includes(path))
+                throw Error('Choose a project already admitted to this installation.');
+            return path;
+        },
+    });
+    return async (principal, argv, files, write) => {
+        const json = argv.includes('--json');
+        const parsed = parseSessionArguments(argv.slice(1), 'server');
+        const operation = 'problem' in parsed ? null : parsed.spec.operation;
+        const command = `session ${operation ?? '(unknown)'}`;
+        let tokenName = null;
+        const record = (outcome, repo, why) => {
+            store.recordAction({ at: clock().toISOString(), actor: principal.account, repo, taskId: null, runId: null, action: `remote command: ${command}`, outcome, source: 'api',
+                detail: `token ${tokenName ?? principal.tokenId}${why === null ? '' : ` · ${why}`}` });
+        };
+        const answer = (response) => {
+            write(json ? envelopeJson({ ...response, command }) : renderSessionResponse(response));
+            return sessionExitCode(response);
+        };
+        const refuse = (spec, reason, message) => {
+            record('refused', null, reason);
+            if (spec === null) {
+                write(json ? envelopeJson({ ok: false, command, reason, message }) : message);
+                return 2;
+            }
+            return answer({ version: 1, operation: spec.operation, ok: false, status: 'rejected', delivery: 'not-sent', retry: spec.mutation ? 'never' : 'safe-read', reason, message, nextActions: [] });
+        };
+        const proved = reproveRemote(store, principal, clock());
+        if (!proved.ok)
+            return refuse('problem' in parsed ? null : parsed.spec, 'unauthenticated', REMOTE_MESSAGES.stale);
+        tokenName = proved.tokenName;
+        if ('problem' in parsed)
+            return refuse(null, 'usage', parsed.problem);
+        const { spec } = parsed;
+        if (spec.mutation && proved.scope !== 'act')
+            return refuse(spec, 'read-only', REMOTE_MESSAGES.read);
+        // A session reaches every project this installation admits: a project-limited token never stands for that.
+        if (principal.projects !== null || !store.isInstanceOperator(principal.account))
+            return refuse(spec, 'all-projects', 'Native sessions need instance operator access to every project. Use a token without a project limit.');
+        const file = parsed.flags['file'];
+        if (file !== undefined && (typeof file !== 'string' || !Object.hasOwn(files, file)))
+            return refuse(spec, 'usage', REMOTE_MESSAGES.files);
+        const validated = sessionRequestOf(parsed, typeof file === 'string' ? files[file] : undefined);
+        if (!validated.ok)
+            return refuse(spec, 'invalid-request', validated.message);
+        if (service === null)
+            return refuse(spec, 'session-unavailable', 'The session owner is not ready.');
+        const repo = 'project' in validated.request && spec.operation === 'start' ? validated.request.project : null;
+        record('requested', repo, null);
+        const uncertain = (reason, message) => {
+            const sessionId = 'sessionId' in validated.request ? validated.request.sessionId : undefined;
+            return { version: 1, operation: spec.operation, ok: false, status: 'uncertain', delivery: 'unknown', retry: 'inspect-first', reason, message,
+                nextActions: [{ operation: sessionId ? 'show' : 'list', label: sessionId ? 'Inspect session' : 'Inspect saved sessions', ...(sessionId ? { sessionId } : {}) }] };
+        };
+        let reply;
+        try {
+            reply = await service.execute({ name: principal.account, generation: principal.generation }, spec.operation, validated.request);
+            if (!isSessionResponse(reply, spec.operation))
+                throw new Error('Invalid owner response');
+            if (Buffer.byteLength(JSON.stringify(reply)) > SESSION_RESPONSE_BYTES)
+                reply = uncertain('response-too-large', 'The owner response is too large to deliver. Inspect saved activity before continuing; this request was not retried.');
+        }
+        catch {
+            reply = uncertain('unconfirmed-response', 'The owner response could not be confirmed. Inspect saved activity before continuing; this request was not retried.');
+        }
+        record(reply.ok ? 'done' : reply.status === 'uncertain' ? 'failed' : 'refused', repo, reply.ok ? null : reply.reason ?? null);
+        return answer(reply);
+    };
+}

package/dist/store.d.ts

@@ -7,7 +7,7 @@ import { type SavedToolAction, type SavedToolRule } from "./contracts/store-json
 import type { FlowCardChange, FlowCardFields } from "./contracts/flow-card.js";
 import { type Actor } from "./actor.js";
 import { type LiveActivityKind } from "./live.js";
-import { type TokenPurpose } from "./api-tokens.js";
+import { type CredentialKind, type TokenPurpose } from "./api-tokens.js";
 import { type CriterionMatrixRow, type CriterionJudgementWord } from "./proof.js";
 import { type ExecutionProfile, type UnattendedPermissionMode, type AcceptanceCriterion } from "./scope.js";
 import { type ProviderRoom, type CandidateTier, type TaskSize, type TaskSizing, type PhaseRoute, type PublicationAuthority, type RouteStamp, type ReadinessLookup, type ReadinessObservation, type RouteOverride } from "./phase-routing.js";
@@ -152,13 +152,24 @@ export type SealedLedgerEntry = LedgerEntry & {
         hash: string;
     } | null;
 };
-export declare const SCHEMA_VERSION = 117;
+export declare const SCHEMA_VERSION = 118;
+/** v118: the tables merged into `credential`, in the order they move (a person's API tokens keep their ids first). */
+export declare const V118_MERGED_TABLES: Readonly<Record<string, CredentialKind>>;
+/**
+ * v118 (D7): one credential table for every machine credential. `id` is the canonical identity every reference holds;
+ * `public_id` is the id the secret presents (so_<id>_…, lt_<id>_…) or a coordinator's cid, unique per kind. They are
+ * equal unless the merge found two kinds sharing an id. `account` is the person a token acts as (a lead's owner; for
+ * a coordinator, who minted it); `projects_json` the project limit (a coordinator's projects); `generation` which
+ * issue it is (1, then one more per rotation, per lead token for the same owner, per coordinator of the same name).
+ * Lead tokens never expire; a coordinator made before v101 has no expiry.
+ */
+export declare const CREDENTIAL_TABLE = "\nCREATE TABLE IF NOT EXISTS credential (\n  id            TEXT PRIMARY KEY,\n  kind          TEXT NOT NULL CHECK (kind IN ('person','lead','coordinator')),\n  public_id     TEXT NOT NULL,\n  account       TEXT NOT NULL,\n  name          TEXT NOT NULL,\n  secret_hash   TEXT NOT NULL,\n  access        TEXT NOT NULL CHECK (access IN ('read','act')),\n  projects_json TEXT,\n  per_hour      INTEGER,\n  purpose       TEXT NOT NULL DEFAULT 'api' CHECK (purpose IN ('api','mcp')),\n  generation    INTEGER NOT NULL DEFAULT 1 CHECK (generation >= 1),\n  created_at    TEXT NOT NULL,\n  created_by    TEXT NOT NULL,\n  expires_at    TEXT,\n  last_used_at  TEXT,\n  revoked_at    TEXT,\n  revoked_by    TEXT,\n  replaces      TEXT,\n  replaced_by   TEXT,\n  overlap_until TEXT,\n  UNIQUE (kind, public_id)\n);\n";
 /** v117: each table renamed, by its old name. Rows, ids, foreign keys and indexes go with it (renameForV117). */
 export declare const V117_RENAMED_TABLES: Readonly<Record<string, string>>;
 /** v117: the columns renamed with them (by the table's new name): a subagent's rows name it `subagent`. */
 export declare const V117_RENAMED_COLUMNS: readonly (readonly [table: string, from: string, to: string])[];
-/** A row `PRAGMA foreign_key_check` reports, by today's table names: a row already pointing nowhere before v117 is the
- * same row after it, though RENAME now reports it (and what it points at) under the new names. */
+/** A row `PRAGMA foreign_key_check` reports, by today's table names: a row already pointing nowhere before v117 (or
+ * v118) is the same row after it, though RENAME (or the credential merge) now reports what it points at by the new names. */
 export declare function orphanKey(row: Record<string, unknown>): string;
 /** v115: the tables migrateToV115 drops. */
 export declare const V115_DROPPED_TABLES: readonly string[];
@@ -194,7 +205,9 @@ export declare const V115_DROPPED_TABLES: readonly string[];
  * transaction that checks each count before the old tables are dropped; the
  * rehearsal checks each moved table's rows arrived (HISTORY_RULES). v117 renames the mate's tables to the lead's and the
  * teammates' to its subagents' (SQLite's RENAME, every row, id and link carried), renames their teammate column, and rewrites four internal kinds from 'teammate' to 'subagent' in place; the rehearsal checks
- * each renamed table's rows arrived under its new name.
+ * each renamed table's rows arrived under its new name. v118 (D7) is checked the same way: every row of api_token,
+ * coordinator_credential and lead_credential moves into credential under its kind in one transaction that counts them
+ * before the old tables drop, and the references that named them name credential in place, their rows untouched.
  */
 export declare const UPDATE_SAFE_MIGRATIONS: readonly number[];
 /** Whether a database settled at `version` reaches this build's schema through update-safe migrations alone. */
@@ -2358,7 +2371,16 @@ export declare class Store {
     };
     /** v111: record the end of each replaced token whose overlap has passed (it already signs no one in). */
     endRotatedApiTokens(now: Date): number;
-    /** A token by id with its kept hash (for the check), or null. */
+    /**
+     * D7: the one check every machine credential takes. The credential a presented secret is (its kind and id), when
+     * its kept hash matches in constant time; null otherwise. Whether it is live, and what its kind may do, stays with
+     * each caller's own policy (a person's API token, a lead token, a coordinator).
+     */
+    presentedCredential(presented: string): {
+        kind: CredentialKind;
+        id: string;
+    } | null;
+    /** A person's API token by id with its kept hash (for the check), or null. */
     apiTokenSecret(id: string): {
         row: ApiTokenRow;
         secretHash: string;
@@ -3018,7 +3040,7 @@ export declare class Store {
      * transaction can never commit half a seal). A brief FILE whose seal
      * failed is an orphan on disk, not authority — no artifact row points at
      * it. Two concurrent seals race on the comment consumption count, the
-     * deterministic child id, or the repair chain's `source_run UNIQUE`, and
+     * family's next version id, or the repair chain's `source_run UNIQUE`, and
      * exactly one wins; the loser refuses in words with zero rows.
      *
      * The child is filed UNAPPROVED, always: this method never stamps an
@@ -3044,10 +3066,9 @@ export declare class Store {
             bytes: number;
             capture: string;
         };
-        /** The child's own words: an optional deterministic id, its title,
-         * and the explicitly described repair appended to the SOURCE goal. */
+        /** The child's own words: its title and the explicitly described repair
+         * appended to the SOURCE goal. Its id is the family's next version. */
         child: {
-            id?: string;
             title: string;
             repair: string;
         };
@@ -3169,7 +3190,6 @@ export declare class Store {
             capture: string;
         };
         child: {
-            id: string;
             title: string;
             repair: string;
         };