toolroll 0.5.0

package/dist/task-control.js

@@ -0,0 +1,214 @@
+/**
+ * Safe task stop and resume (v52): the ONE domain API every surface — the
+ * CLI, the authenticated console, the focused chat — speaks, and the fences
+ * every execution road consults.
+ *
+ * The contract, in the operator's words: a stop names one exact active
+ * attempt. The first answer is "stop requested", never "stopped" — the
+ * request is durable before any process is signalled, and the attempt is
+ * SETTLED only once all owned runs ended and retained process witnesses
+ * establish exit. A dead worker can leave live subprocesses; recovery
+ * keeps that stop pending. Other tasks keep running. The task stays
+ * paused across restarts under a hold this stop owns, beside — never over —
+ * any hold that already stood. Resume names the same exact attempt, refuses
+ * until it is quiescent, lifts only that hold, approves nothing, and lets
+ * the next pass re-prove the signed scope, take a fresh claim, and inherit
+ * the preserved draft with fresh proof.
+ *
+ * Nothing here is a second engine: the stop rides the existing run, claim,
+ * hold, recovery, invocation-gateway, and held-session machinery. This
+ * module only names the door and the fence.
+ */
+import { ownedProcessCount, runOwnerTag, terminateOwnedProcesses } from "./exec.js";
+import { diagnoseTaskDispatch } from "./dispatch.js";
+/** How often a running attempt re-reads its stop row while a child runs.
+ * A stop is observed within this bound even when the console that filed
+ * it lives in another process on the same database. */
+export const STOP_WATCH_MS = 1_500;
+/**
+ * The stop fence, as a predicate: an operator stop applies to the run (its
+ * own, or an owning ancestor's), or the caller's own watch-level stop says
+ * so. Every road that used to ask `shouldStop?.()` asks this instead.
+ */
+export function stopRequestedFor(store, runId, also) {
+    if (also?.() === true)
+        return true;
+    return store.applicableStopFor(runId) !== null;
+}
+/** The words a road records when a stop wins: who asked, and where the
+ * work stays. */
+export function stopWords(store, runId, worktree, fallback) {
+    const stop = store.applicableStopFor(runId);
+    if (stop === null)
+        return fallback;
+    const where = worktree === null ? "its evidence is on record" : `the work is preserved in ${worktree}`;
+    return `stopped by ${stop.requestedBy} (run #${stop.run}) — ${where}`;
+}
+/**
+ * End every live child THIS process holds for one attempt and its owned
+ * descendants — the exact-attempt handle, never a pid read from durable
+ * state. Returns how many process groups were signalled.
+ */
+export function terminateStoppedAttempt(store, runId) {
+    let terminated = 0;
+    for (const owned of store.ownedRunsOf(runId))
+        terminated += terminateOwnedProcesses(runOwnerTag(store, owned));
+    return terminated;
+}
+/** Whether this process still tracks a live child for the attempt or any
+ * run it owns — the in-process half of "quiescent". */
+export function attemptHasLiveChildren(store, runId) {
+    return store.ownedRunsOf(runId).some(owned => ownedProcessCount(runOwnerTag(store, owned)) > 0);
+}
+/**
+ * Run a child-bearing step under the stop watch: while `body` runs, the
+ * run's stop row is re-read every `intervalMs`; the moment a stop applies
+ * the run's owned children are killed through their handles and the
+ * caller's `onStop` fires once. The body's own settlement then observes
+ * the stop through `stopRequestedFor` and seals the attempt as
+ * interrupted — this watch never writes an outcome itself.
+ */
+export async function underStopWatch(store, runId, body, options = {}) {
+    let fired = false;
+    const look = () => {
+        let applies = false;
+        try {
+            applies = store.applicableStopFor(runId) !== null;
+        }
+        catch {
+            // A read that cannot reach the database proves nothing; the next
+            // beat asks again, and settlement asks one last time.
+            return;
+        }
+        if (!applies)
+            return;
+        terminateStoppedAttempt(store, runId);
+        // A later asynchronous step may have spawned since the previous beat.
+        // Keep stopping children; only the notification is one-shot.
+        if (fired)
+            return;
+        fired = true;
+        try {
+            options.onStop?.();
+        }
+        catch {
+            // The watch's job is the kill; a listener's throw is its own.
+        }
+    };
+    look();
+    const timer = setInterval(look, options.intervalMs ?? STOP_WATCH_MS);
+    timer.unref?.();
+    try {
+        return await body();
+    }
+    finally {
+        clearInterval(timer);
+    }
+}
+/**
+ * The shared stop door. Records the durable request first (one fenced
+ * transaction: exact run, still open, this task's current claim, no
+ * tournament, no admitted publication), THEN signals every child this
+ * process holds for the attempt. A worker in another process observes the
+ * same row through its stop watch within STOP_WATCH_MS.
+ */
+export function requestTaskStop(store, request, now) {
+    const ref = store.lookupRef(request.taskId);
+    if (ref === null || store.getTask(request.taskId) === null) {
+        return { ok: false, reason: "no-task", detail: `no task \`${request.taskId}\`` };
+    }
+    const asked = store.requestRunStop({ runId: request.runId, taskRef: ref.id, by: request.by, via: request.via }, now);
+    if (!asked.ok)
+        return asked;
+    let terminated = 0;
+    const signal = () => {
+        terminated = terminateStoppedAttempt(store, request.runId);
+        if (request.held !== undefined && store.heldSessionOf(request.runId) !== null) {
+            void request.held.stop(request.runId).catch(() => {
+                // The lapse interval retries the same fence; the durable row stands.
+            });
+        }
+    };
+    if (request.deferSignal)
+        request.deferSignal(signal);
+    else
+        signal();
+    return { ok: true, stop: asked.stop, repeated: asked.repeated, terminated, taskId: request.taskId };
+}
+/**
+ * The shared resume door. Refuses in words until the exact stopped attempt
+ * is quiescent — settled, every owned run ended, no live claim, its
+ * workspace not held by any process this machine can still see — then
+ * lifts exactly this stop's hold. `gate` reports what still keeps the
+ * next pass from starting work (an approval that must be signed again, a
+ * worker that is offline), so a resume that cannot yet start is never
+ * mistaken for one that did. A stopped review is refused here and pointed
+ * at the explicit bounded review-retry door.
+ */
+export function resumeTaskStop(store, request, now) {
+    const ref = store.lookupRef(request.taskId);
+    if (ref === null || store.getTask(request.taskId) === null) {
+        return { ok: false, reason: "no-task", detail: `no task \`${request.taskId}\`` };
+    }
+    const run = store.getRun(request.runId);
+    if (run !== null && run.worktree !== null && request.occupied !== undefined) {
+        const held = request.occupied(run.worktree);
+        if (held.held) {
+            return { ok: false, reason: "occupied", detail: `run #${request.runId}'s workspace ${run.worktree} is still held by process ${String(held.by ?? "?")} — nothing resumes until it is gone` };
+        }
+    }
+    if (attemptHasLiveChildren(store, request.runId)) {
+        return { ok: false, reason: "stopping", detail: `run #${request.runId} still has a live process this worker is stopping` };
+    }
+    const resumed = store.resumeRunStop({ runId: request.runId, taskRef: ref.id, by: request.by, via: request.via }, now);
+    if (!resumed.ok)
+        return resumed;
+    const gate = diagnoseTaskDispatch(store, request.taskId, now);
+    return { ok: true, stop: resumed.stop, taskId: request.taskId, gate: gate === null || gate.condition === "running" ? null : gate };
+}
+/** The head of a lease group: a run whose parent (if any) ran under a
+ * different lease — a builder, a planner, a scout, a recovered-draft
+ * successor, a warm park resume; never a repair turn or a correction. */
+function isAttemptRoot(store, run) {
+    if (run.role === "reviewer")
+        return run.reviewAttempt !== null && run.reviewAttempt !== undefined;
+    if (run.parentRun === null)
+        return true;
+    return store.getRun(run.parentRun)?.leaseId !== run.leaseId;
+}
+export function taskControlOf(store, taskRef, now) {
+    const runs = store.runsFor(taskRef);
+    const holding = store.currentLiveLease(taskRef, now);
+    const live = runs.find(run => run.outcome === null && run.role !== "reviewer" && holding !== null && run.leaseId === holding && isAttemptRoot(store, run)) ??
+        runs.find(run => run.outcome === null && run.role === "reviewer" && isAttemptRoot(store, run)) ??
+        null;
+    if (live !== null) {
+        const stop = store.stopOf(live.id);
+        if (stop !== null && stop.settledAt === null)
+            return { kind: "stopping", run: stop.run, role: live.role, stop, unsettledRun: true };
+        if (stop === null)
+            return { kind: "stop", run: live.id, role: live.role };
+    }
+    // A stop recorded but unsettled on a run that already ended is still
+    // "stopping" — visibly needing attention, never silently paused.
+    const pending = store.stopsForTask(taskRef).find(stop => stop.settledAt === null) ?? null;
+    if (pending !== null) {
+        const run = store.getRun(pending.run);
+        return { kind: "stopping", run: pending.run, role: run?.role ?? "builder", stop: pending, unsettledRun: run?.outcome === null, detail: store.stopQuiescenceProblem(pending.run) };
+    }
+    const newest = runs.find(run => run.role !== "reviewer" && isAttemptRoot(store, run)) ?? null;
+    if (newest !== null) {
+        const stop = store.stopOf(newest.id);
+        if (stop !== null && stop.settledAt !== null && stop.resumedAt === null) {
+            return { kind: "paused", run: newest.id, role: newest.role, stop, outcome: newest.outcome, committed: newest.committed === true, worktree: newest.worktree };
+        }
+    }
+    const newestReview = runs.find(run => run.role === "reviewer" && isAttemptRoot(store, run)) ?? null;
+    if (newestReview !== null) {
+        const stop = store.stopOf(newestReview.id);
+        if (stop !== null && stop.settledAt !== null && stop.resumedAt === null) {
+            return { kind: "review-stopped", run: newestReview.id, sourceRun: newestReview.parentRun, stop };
+        }
+    }
+    return { kind: "none" };
+}

package/dist/task-outcome-cli.d.ts

@@ -0,0 +1,10 @@
+import { type VerifiedApprover } from './principal.js';
+import type { Store } from './store.js';
+export declare function runTaskOutcomeCommand(action: 'complete' | 'revise', positional: readonly string[], flags: Map<string, string | true>, context: {
+    store: Store;
+    evidenceRoot: string;
+    json: boolean;
+    write: (line: string) => void;
+    now: Date;
+    operator: () => Promise<VerifiedApprover | null>;
+}): Promise<number>;

package/dist/task-outcome-cli.js

@@ -0,0 +1,92 @@
+/** Everyday task verbs over the existing completion and revision boundaries. */
+import { createHash } from 'node:crypto';
+import { assignmentOf, checkAssignmentAsOperator } from './assignment.js';
+import { assignmentForCoordinator, coordinatorToken } from './assignment-adapters.js';
+import { authenticateCoordinator } from './coordinator.js';
+import { reproveApprover } from './principal.js';
+import { requestResultChanges } from './result-actions.js';
+import { commentSourceKey, revisionSourceOf } from './result-review.js';
+import { envelopeJson } from './envelope.js';
+export async function runTaskOutcomeCommand(action, positional, flags, context) {
+    const command = `task ${action}`;
+    const emit = (result, lines) => {
+        context.write(context.json ? envelopeJson({ ...result, command }) : result.ok ? (lines ?? []).join('\n') : result.message ?? 'The action was refused.');
+        return result.ok ? 0 : result.reason === 'usage' ? 2 : 3;
+    };
+    const fail = (reason, message) => emit({ ok: false, reason, message });
+    const allowed = new Set(['json', 'db', 'as', 'token', 'token-env', 'token-file', ...(action === 'complete' ? ['digest'] : ['feedback', 'run', 'source', 'key'])]);
+    for (const key of flags.keys())
+        if (!allowed.has(key))
+            return fail('usage', `--${key} is not a task ${action} option.`);
+    const task = positional[0];
+    if (positional.length !== 1 || !task || task.length > 64 || /[\x00-\x1f]/.test(task))
+        return fail('usage', `Use task ${action} <task>${action === 'complete' ? ' --digest <receipt>' : ' --feedback "requested change"'}.`);
+    const credential = coordinatorToken(flags, process.env);
+    if ('ok' in credential)
+        return emit(credential);
+    if (credential.token !== null && (flags.has('as') || flags.has('token')))
+        return fail('usage', 'Choose a scoped credential or your operator sign-in.');
+    const operator = credential.token === null ? await context.operator() : null;
+    if (credential.token === null && operator === null)
+        return fail('unauthenticated', 'Sign in with up, or supply --as and --token. Agents can use --token-file or --token-env with a scoped credential.');
+    const { store, now, evidenceRoot } = context;
+    return store.transact(() => {
+        const coordinator = credential.token === null ? null : authenticateCoordinator(store, credential.token);
+        if (coordinator !== null && !coordinator.ok)
+            return fail('unauthenticated', 'The scoped credential is invalid or revoked.');
+        if (operator !== null && !reproveApprover(store, operator).ok)
+            return fail('unauthenticated', 'Your sign-in is no longer valid.');
+        const repos = coordinator?.ok ? coordinator.who.repos : operator.repos;
+        const current = assignmentOf(store, task, now, { principal: coordinator === null ? 'operator' : 'coordinator', repos }, evidenceRoot);
+        if (current === null)
+            return fail('not-found', 'That task is unavailable in your projects.');
+        if (action === 'complete') {
+            const supplied = flags.get('digest');
+            if (supplied !== undefined && (typeof supplied !== 'string' || !/^[a-f0-9]{64}$/.test(supplied)))
+                return fail('usage', '--digest requires the exact receipt from assignment show.');
+            if (supplied === undefined && (context.json || coordinator !== null))
+                return fail('usage', 'Read assignment show <task>, then pass its exact --digest to mark that result complete.');
+            const digest = typeof supplied === 'string' ? supplied : current.receipt?.digest;
+            if (!digest)
+                return fail('not-ready', 'This task has no finished result to mark complete.');
+            const changed = credential.token !== null
+                ? assignmentForCoordinator(store, credential.token, 'check', { ref: task, digest }, now, evidenceRoot)
+                : checkAssignmentAsOperator(store, task, digest, operator, now, evidenceRoot);
+            if (!changed.ok)
+                return emit(changed);
+            const assignment = 'body' in changed ? changed.body : changed.assignment;
+            return emit({ ok: true, result: assignment }, [`${current.rootId} · Complete`, `Result: ${current.activeTaskId} · run ${current.receipt.runId} · ${current.receipt.head ?? 'no commit'}`, current.receipt.checks.detail]);
+        }
+        const feedback = flags.get('feedback'), runFlag = flags.get('run'), sourceFlag = flags.get('source'), keyFlag = flags.get('key');
+        if (typeof feedback !== 'string' || !feedback.trim())
+            return fail('usage', 'Describe the requested change with --feedback.');
+        if (runFlag !== undefined && (typeof runFlag !== 'string' || !/^[1-9]\d*$/.test(runFlag) || !Number.isSafeInteger(Number(runFlag))))
+            return fail('usage', '--run requires an exact run number.');
+        if (sourceFlag !== undefined && (typeof sourceFlag !== 'string' || !/^(?:[a-f0-9]{32}|none)$/.test(sourceFlag)))
+            return fail('usage', '--source requires the exact source scope digest.');
+        if (keyFlag !== undefined && (typeof keyFlag !== 'string' || !/^[a-f0-9]{32}$/.test(keyFlag)))
+            return fail('usage', '--key requires 32 lowercase hexadecimal characters.');
+        const runId = runFlag === undefined ? current.receipt?.runId : Number(runFlag);
+        const run = runId === undefined ? null : store.getRun(runId);
+        const runTask = run === null ? null : store.externalIdFor(run.taskRef);
+        const family = runTask === null ? null : store.taskFamilyOf(runTask, repos, false);
+        if (run === null || runTask === null || family?.root.id !== current.rootId || run.outcome === null)
+            return fail('not-found', 'That finished result is unavailable for this task.');
+        const source = typeof sourceFlag === 'string' ? sourceFlag : revisionSourceOf(store.getScope(runTask)?.digest ?? null);
+        const actor = coordinator?.ok ? `coordinator:${coordinator.who.cid}` : operator.name;
+        const key = typeof keyFlag === 'string' ? keyFlag : createHash('sha256').update(JSON.stringify([actor, run.id, source, feedback])).digest('hex').slice(0, 32);
+        const previous = store.diffCommentBySourceKey(commentSourceKey(actor, key));
+        if ((family.current.id !== runTask || (current.receipt !== null && current.receipt.runId !== run.id)) && previous?.consumedBy == null)
+            return fail('stale-result', 'A newer version is current. Read its result before requesting another revision.');
+        // The shared action returns exact replays before stale-family checks. An
+        // older result cannot create another child once a newer revision is current.
+        const revised = requestResultChanges(store, evidenceRoot, { run: run.id, source, actor, repos,
+            batch: '', note: feedback, path: '', line: '', request: key, allowMode: operator !== null }, now);
+        if (!revised.ok)
+            return fail(revised.status === 400 ? 'usage' : 'stale-result', revised.message);
+        const scope = store.getScope(revised.id);
+        const approved = scope?.approvedDigest != null && scope.approvedDigest === scope.digest;
+        const planning = store.lookupRef(revised.id)?.plan === 'requested';
+        return emit({ ok: true, result: { id: revised.id, rootId: current.rootId, sourceRun: run.id, source, key, approved, planning } }, [`${current.rootId} · Revision created`, `Execution: ${revised.id}`, approved ? 'Covered by your existing operating mode.' : planning ? 'Updating the plan with your notes; approve it when it is ready.' : 'The revision is waiting for approval.']);
+    });
+}

package/dist/task-text.d.ts

@@ -0,0 +1,30 @@
+export declare const TASK_TEXT_LIMITS: {
+    readonly title: 200;
+    readonly text: 2000;
+    readonly textBytes: 8000;
+};
+export declare const TASK_SCOPE_TEXT_SCHEMA: {
+    readonly type: "string";
+    readonly maxLength: 2000;
+    readonly description: "At most 2000 UTF-16 code units and 8000 UTF-8 bytes; no control or disguised text.";
+};
+export type TaskTextRefusal = {
+    ok: false;
+    reason: "bad-title" | "bad-goal";
+    message: string;
+};
+export declare function validateScopeText(fields: {
+    goal?: string;
+    outOfScope?: string | null;
+    touches?: readonly string[];
+}): {
+    ok: false;
+    reason: "bad-goal" | "bad-out-of-scope" | "bad-touches";
+    message: string;
+} | null;
+export declare function validateTaskText(fields: {
+    title: string;
+    goal?: string;
+    outOfScope?: string | null;
+    touches?: readonly string[];
+}): TaskTextRefusal | null;

package/dist/task-text.js

@@ -0,0 +1,41 @@
+/** New task text only. Historical signed terms are read by sealRevision,
+ * never re-authored through this validator. Character counts deliberately
+ * retain the existing JavaScript/HTML UTF-16 policy (2000 code units).
+ * UTF-8 byte limits remain explicit storage bounds beside that policy. */
+import { hasForbiddenControls, hasDisguisedText } from "./decision.js";
+export const TASK_TEXT_LIMITS = { title: 200, text: 2_000, textBytes: 8_000 };
+export const TASK_SCOPE_TEXT_SCHEMA = { type: "string", maxLength: TASK_TEXT_LIMITS.text,
+    description: "At most 2000 UTF-16 code units and 8000 UTF-8 bytes; no control or disguised text." };
+const dishonest = (text) => hasForbiddenControls(text) || hasDisguisedText(text);
+const overBytes = (text, cap) => Buffer.byteLength(text, "utf8") > cap;
+const BYTE_CAPS = { title: 800, text: TASK_TEXT_LIMITS.textBytes, path: 800 };
+const refuse = (reason, message) => ({ ok: false, reason, message });
+export function validateScopeText(fields) {
+    for (const [value, label, reason, required] of [
+        [fields.goal, "Goal", "bad-goal", true],
+        [fields.outOfScope, "Exclusions", "bad-out-of-scope", false],
+    ]) {
+        if (value == null)
+            continue;
+        if (required && value.trim() === "")
+            return { ok: false, reason, message: `${label} cannot be empty.` };
+        if (value.length > TASK_TEXT_LIMITS.text)
+            return { ok: false, reason, message: `${label} must be 2000 characters or fewer.` };
+        if (overBytes(value, BYTE_CAPS.text))
+            return { ok: false, reason, message: `${label} must be 8000 UTF-8 bytes or fewer.` };
+        if (dishonest(value))
+            return { ok: false, reason, message: `${label} cannot contain control or hidden characters.` };
+    }
+    const touches = fields.touches ?? [];
+    if (touches.length > 50 || touches.some(one => one.trim() === "" || one.length > 200 || overBytes(one, BYTE_CAPS.path) || dishonest(one))) {
+        return { ok: false, reason: "bad-touches", message: "Use at most 50 paths, each non-empty, at most 200 characters, with no control or hidden characters." };
+    }
+    return null;
+}
+export function validateTaskText(fields) {
+    if (fields.title.trim() === "" || fields.title.length > 200 || overBytes(fields.title, BYTE_CAPS.title) || dishonest(fields.title)) {
+        return refuse("bad-title", "a title is required, at most 200 characters, with no control or disguised text");
+    }
+    const bad = validateScopeText(fields);
+    return bad === null ? null : refuse("bad-goal", bad.message);
+}

package/dist/team-cli.d.ts

@@ -0,0 +1,15 @@
+export type TeamCliOptions = {
+    fetch?: typeof fetch;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    profileFile?: string;
+    readStdin?: () => Promise<string>;
+    readLine?: (prompt: string) => Promise<string | null>;
+    isTTY?: boolean;
+    stderr?: (line: string) => void;
+    signal?: AbortSignal;
+    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'];
+/** 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>;