toolroll 0.9.3 → 0.9.4

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.9.4 — 2026-10-01
+
+- **Flow steps act exactly once.** However many workers advance a
+  project's flows at the same time, a card files its task, runs its script
+  and posts its update once; a retried card takes the same guarded path.
+- **Pull requests from the terminal.** `toolroll task complete <id>
+  --pull-request` completes a result and opens its pull request, and
+  `toolroll task merge <id>` merges it once checks pass, behind your password.
+
 ## 0.9.3 — 2026-10-01
 
 - **Flows never get stuck on a long step output.** A research or build step's

package/dist/flow-engine.js

@@ -241,21 +241,32 @@ function workStage(store, flow, stage, card, now, options, outcome, onward) {
             wait(`${stage.title}'s instructions are too long for a task. Open the flow and shorten them.`);
             return;
         }
-        const filed = fileTaskProposal(store, {
-            title: (report ? `${stage.title}: ${card.title}` : card.title).slice(0, 200),
-            repo: flow.repo,
-            goal,
-            filedVia: `flow:${flow.id}`, filedBy: filerFor(card.createdBy), // who made the card asked for the work (an owner can be reassigned by anyone)
-            deliverable: report ? "report" : "branch",
-            planning: report ? "skip" : stage.planning ?? "auto",
-            acceptance: report ? ACCEPTANCE.report : ACCEPTANCE.task,
-            admittedRepos: [flow.repo],
-        }, now);
+        // Filed exactly once however many passes advance this project: the card is claimed (still this entry, in this zone,
+        // with no task) in the same transaction that files its task, so another pass finds it claimed and leaves it.
+        const filed = store.transact(() => {
+            const fresh = store.getFlowCard(card.id);
+            if (fresh === null || fresh.state !== "active" || fresh.entry !== card.entry || fresh.stage !== stage.id || fresh.task !== null)
+                return null;
+            const made = fileTaskProposal(store, {
+                title: (report ? `${stage.title}: ${card.title}` : card.title).slice(0, 200),
+                repo: flow.repo,
+                goal,
+                filedVia: `flow:${flow.id}`, filedBy: filerFor(card.createdBy), // who made the card asked for the work (an owner can be reassigned by anyone)
+                deliverable: report ? "report" : "branch",
+                planning: report ? "skip" : stage.planning ?? "auto",
+                acceptance: report ? ACCEPTANCE.report : ACCEPTANCE.task,
+                admittedRepos: [flow.repo],
+            }, now);
+            if (made.ok)
+                store.updateFlowCard(card.id, { task: made.id, ...(report || fresh.primaryTask !== null ? {} : { primaryTask: made.id }), waiting: "Filed as a task" }, now);
+            return made;
+        });
+        if (filed === null)
+            return;
         if (!filed.ok) {
             wait(/[.!?]$/.test(filed.message) ? filed.message : `${filed.message}.`);
             return;
         }
-        store.updateFlowCard(card.id, { task: filed.id, ...(report || card.primaryTask !== null ? {} : { primaryTask: filed.id }), waiting: "Filed as a task" }, now);
         outcome.filed.push(filed.id);
         return;
     }

package/dist/flow-steps.js

@@ -137,7 +137,7 @@ export async function runFlowSteps(store, repo, now, io) {
                 store.updateFlowCard(card.id, { waiting }, now);
             continue;
         }
-        if (!store.claimFlowStep({ card: card.id, entry: card.entry, stage: stage.id, kind: stage.kind, script: script?.name ?? null, scriptVersion: script?.version ?? null }, now))
+        if (!claimStep(store, card, { stage: stage.id, kind: stage.kind, script: script?.name ?? null, scriptVersion: script?.version ?? null }, now))
             continue;
         pass.ran++;
         store.updateFlowCard(card.id, { waiting: { check: "Running its check…", sort: "Sorting…", draft: "Writing the draft…", request: "Calling the address…", email: "Sending the email…", tool: "Using the tool…" }[stage.kind] ?? "Updating the issue…" }, now);
@@ -164,6 +164,16 @@ export async function runFlowSteps(store, repo, now, io) {
     }
     return pass;
 }
+/** Claim this card's visit to its step zone, only while the card is still there on that visit: a pass that read the card
+ * before another pass (or a person) moved it never runs the step for a visit that's over. */
+function claimStep(store, card, step, now) {
+    return store.transact(() => {
+        const fresh = store.getFlowCard(card.id);
+        if (fresh === null || fresh.state !== "active" || fresh.entry !== card.entry || fresh.stage !== step.stage)
+            return false;
+        return store.claimFlowStep({ card: card.id, entry: card.entry, ...step }, now);
+    });
+}
 /** One teammate turn, when one is due for this card: claimed like any step, retried on failure, and waiting while its question is open. */
 async function teammateStep(store, flow, definition, stage, card, now, io, pass) {
     // v102: on a protected project an AI teammate never decides an approval; the engine asks the person.
@@ -183,7 +193,7 @@ async function teammateStep(store, flow, definition, stage, card, now, io, pass)
     // Waiting on a person: its own question, or (v94) a tool call they approve first.
     if (store.openTeammateQuestionOn(card.id, card.entry) !== null)
         return true;
-    if (!store.claimFlowStep({ card: card.id, entry: card.entry, stage: stage.id, kind: "teammate", script: null, scriptVersion: null }, now))
+    if (!claimStep(store, card, { stage: stage.id, kind: "teammate", script: null, scriptVersion: null }, now))
         return true;
     pass.ran++;
     const started = Date.now();

package/dist/guides.js

@@ -79,6 +79,23 @@ ${AUTHORITY_LINE}
     detail says why; \`toolroll sync\` refreshes trackers.
   - \`contest-open\`: a tournament is running on the task; a person picks.
 
+## Complete, pull request, merge
+
+The console's Complete and Merge, from a terminal. Both are a person's
+acts behind their sign-in (\`--as <you> --token <t>\`, or the remembered
+login); run them only when the person asked for exactly that.
+
+- \`task complete <id> --digest <receipt> --pull-request\` marks the exact
+  inspected result complete and opens its pull request from that commit
+  under the project's publishing setup. \`pull-requests-off\` names the
+  setup command (\`publish setup --repo <path> --yes\`).
+- CI is watched on GitHub. \`task show <id> --json\` carries
+  \`pullRequest\`: \`prUrl\`, \`state\` (opening, waiting, running, ready,
+  failing, merged, closed, failed) and \`mergeCommit\`.
+- \`task merge <id>\` merges it once checks pass, by the project's method
+  (squash by default), deletes the branch and records who merged.
+  \`checks\` means they are running or failing; the message says which.
+
 ## Flows
 
 A flow is a process cards move through, drawn as zones. The terminal

package/dist/operate.d.ts

@@ -91,7 +91,7 @@ type Args = {
  * exports are behavior, not commentary — and the declared command guide
  * (surface.ts) is tested for exact equality against them.
  */
-export declare const TASK_ACTIONS: readonly ["add", "list", "show", "wait", "state", "block", "unblock", "next", "steer", "assign", "reopen", "scope", "approve", "hold", "unhold", "require", "requeue", "regate", "plan", "review", "accept", "repair", "route", "stop", "resume", "complete", "revise"];
+export declare const TASK_ACTIONS: readonly ["add", "list", "show", "wait", "state", "block", "unblock", "next", "steer", "assign", "reopen", "scope", "approve", "hold", "unhold", "require", "requeue", "regate", "plan", "review", "accept", "repair", "route", "stop", "resume", "complete", "revise", "merge"];
 export declare const PUBLISH_ACTIONS: readonly ["setup", "grant", "revoke", "status", "unblock", "rearm", "merge", "refire"];
 export declare const CONFIG_ACTIONS: readonly ["show", "set", "clear"];
 export declare const APPROVER_ACTIONS: readonly ["list", "add"];

package/dist/operate.js

@@ -40,7 +40,7 @@ import { runKnowledgeCommand } from "./knowledge-cli.js";
 import { FLOWS_VALUE_FLAGS, runFlowsCommand } from "./flows-cli.js";
 import { runAssignmentCommand } from "./assignment-adapters.js";
 import { applyProjectProfile, runProjectCommand } from "./project-cli.js";
-import { runTaskOutcomeCommand } from "./task-outcome-cli.js";
+import { pullRequestLines, runTaskMergeCommand, runTaskOutcomeCommand } from "./task-outcome-cli.js";
 /**
  * The commands that actually move work: authoring tasks, and the claim loop.
  *
@@ -138,7 +138,7 @@ import { verifyApproverByPassword } from "./principal.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";
-import { checkPublishing, publishingOf, savePublishing, followPullRequests } from "./pull-request-flow.js";
+import { checkPublishing, publishingOf, savePublishing, followPullRequests, newestPullRequestOf } from "./pull-request-flow.js";
 import { starterOf, startersFor, switchOnStarter } from "./flow-starters.js";
 import { acquire, acquireFallback, acquireIfReady, completeFenced, finalizeFailureFenced, finalizeMalformedFenced, finalizeParkFenced, finalizePlanFenced, finalizePlanFailureFenced, finalizeScoutFenced, finalizeScoutFailureFenced, heartbeat, release, reap, currentClaim, DEFAULT_LEASE_MS, SYNC_MAX_AGE_MS, acquireContinuation, } from "./claim.js";
 import { disposeBuildOutcome, holdStaleApproval, regateTask } from "./dispose.js";
@@ -235,7 +235,10 @@ export const OPERATE_HELP = `toolroll — operating the queue
   toolroll ledger checkpoint         record the chain's head to copy off this machine (instance operator)
   toolroll ledger export --from <YYYY-MM-DD> --to <YYYY-MM-DD> [--out <file>]
                                         every sealed entry in the range, with an evidence pack per task
-  toolroll task complete <id>        mark the current result complete (--digest for JSON/agents)
+  toolroll task complete <id>        mark the current result complete (--digest for JSON/agents);
+      [--pull-request]                  --pull-request also opens its pull request
+  toolroll task merge <id> --as <you> --token <t>
+                                        merge the task's pull request once checks pass
   toolroll task revise <id> --feedback "requested change"
   toolroll assignment show <task>    root, current work and exact handoff
   toolroll assignment updates        durable updates (--after <cursor>)
@@ -554,7 +557,7 @@ Exit codes
 export const TASK_ACTIONS = [
     "add", "list", "show", "wait", "state", "block", "unblock", "next", "steer", "assign",
     "reopen", "scope", "approve", "hold", "unhold", "require", "requeue", "regate", "plan",
-    "review", "accept", "repair", "route", "stop", "resume", "complete", "revise",
+    "review", "accept", "repair", "route", "stop", "resume", "complete", "revise", "merge",
 ];
 export const PUBLISH_ACTIONS = ["setup", "grant", "revoke", "status", "unblock", "rearm", "merge", "refire"];
 export const CONFIG_ACTIONS = ["show", "set", "clear"];
@@ -607,6 +610,8 @@ export const OPERATE_BOOLEAN_FLAGS = new Set([
     "zip",
     // Settings → Integrations: the last checks, without checking again.
     "saved",
+    // task complete: also open the result's pull request.
+    "pull-request",
 ]);
 export function parseOperateArgs(argv, ownValues = new Set()) {
     const positional = [];
@@ -9325,6 +9330,9 @@ function taskCommand(positional, flags, context) {
                     const authenticated = verifyApproverByPassword(context.store, acting.name, acting.token, context.store.knownRepos().filter(repo => context.store.accountCanAccess(acting.name, repo)));
                     return authenticated.ok ? authenticated.who : null;
                 } });
+        case "merge":
+            return runTaskMergeCommand(rest, flags, { store: context.store, json: context.json, write: context.write, clock: context.clock,
+                demo: context.store.isDemo(), credentials: () => askCredentials(flags, context), ...(context.publishExec === undefined ? {} : { exec: context.publishExec }) });
         case "add":
             return addTask(rest, flags, context);
         case "list":
@@ -9744,6 +9752,8 @@ function showTask(positional, context) {
         // Paused (resume), or the review-retry door — and every stop on record.
         control: taskControlOf(store, ref.id, now),
         stops: store.stopsForTask(ref.id),
+        // The pull request Complete opened (any version), with its CI state and merge commit — the console's view.
+        pullRequest: newestPullRequestOf(store, store.taskFamilyOf(id, null, true)?.versions.map(one => one.id) ?? [id]),
     };
     return succeed(write, json, "task show", detail, () => [
         `${task.id}  ${task.state}${ref.deliverable === "report" ? "  (scout — delivers a report)" : ""}`,
@@ -9772,6 +9782,7 @@ function showTask(positional, context) {
                     ...detail.report.report.followUps.map((one, index) => `    follow-up ${index + 1}: ${one.title}`),
                 ]
                 : [`  report: ${detail.report.problem} (run ${detail.report.run})`]),
+        ...pullRequestLines(detail.pullRequest),
         ...(detail.blockedBy.length > 0 ? [`  waits for ${detail.blockedBy.join(", ")}`] : []),
         ...(detail.position === null
             ? []

package/dist/pull-request-flow.d.ts

@@ -169,4 +169,6 @@ export type PullRequestView = {
 };
 /** The pull request a result opened through Complete, in plain words; null when it opened none. */
 export declare function pullRequestViewOf(store: Store, runId: number): PullRequestView | null;
+/** The newest pull request any version of a task opened through Complete (versions oldest first), or null. */
+export declare function newestPullRequestOf(store: Store, versions: readonly string[]): PullRequestView | null;
 export {};

package/dist/pull-request-flow.js

@@ -473,3 +473,17 @@ export function pullRequestViewOf(store, runId) {
             return { ...base, state: "waiting", label: "Waiting for checks", detail: "No CI checks have reported on GitHub yet." };
     }
 }
+/** The newest pull request any version of a task opened through Complete (versions oldest first), or null. */
+export function newestPullRequestOf(store, versions) {
+    for (const id of [...versions].reverse()) {
+        const ref = store.lookupRef(id);
+        if (ref === null)
+            continue;
+        for (const run of store.runsFor(ref.id)) {
+            const view = pullRequestViewOf(store, run.id);
+            if (view !== null)
+                return view;
+        }
+    }
+    return null;
+}

package/dist/serve.js

@@ -59,7 +59,7 @@ import { workIndexPage, workCountsByProject, WorkIndexCursorError } from "./work
 import { openWorkDecisionOf } from "./work-summary.js";
 import { assignmentOf, checkAssignmentAsOperator } from './assignment.js';
 import { pullRequestSettingsHtml, PULL_REQUEST_SETTINGS_CSS } from './pull-request-ui.js';
-import { checkPublishing, completeAndOpenPullRequest, mergeAsPerson, pullRequestBlocker, pullRequestViewOf, publishingOf, saveMergeSettings, savePublishing, MERGE_METHODS } from './pull-request-flow.js';
+import { checkPublishing, completeAndOpenPullRequest, mergeAsPerson, pullRequestBlocker, publishingOf, saveMergeSettings, savePublishing, newestPullRequestOf, MERGE_METHODS } from './pull-request-flow.js';
 import { leadBriefHtml, LEAD_CONTEXT_CSS } from './lead-context.js';
 import { assignmentCatchUp } from './assignment-brief.js';
 import { assignmentCardOf, assignmentStatusOf, assignmentSummaryHtml, assignmentWithEvidence, ASSIGNMENT_CSS } from './assignment-ui.js';
@@ -5433,20 +5433,12 @@ export function createDecisionServer(options) {
     function taskPullRequestOf(taskId, who) {
         const family = familyOf(taskId);
         const rootId = family?.root.id ?? taskId;
-        const ids = family === null ? [taskId] : [...family.versions.map(one => one.id)].reverse();
         const repo = store.lookupRef(taskId)?.repo ?? null;
         const publishing = publishingOf(store, repo);
         const target = publishing.on ? publishing.base : null;
-        for (const id of ids) {
-            const ref = store.lookupRef(id);
-            if (ref === null)
-                continue;
-            for (const run of store.runsFor(ref.id)) {
-                const view = pullRequestViewOf(store, run.id);
-                if (view !== null)
-                    return { taskId: rootId, view: { ...view, canMerge: view.canMerge && who.role === "approver" && who.via === "cookie" }, offer: null, target };
-            }
-        }
+        const view = newestPullRequestOf(store, family === null ? [taskId] : family.versions.map(one => one.id));
+        if (view !== null)
+            return { taskId: rootId, view: { ...view, canMerge: view.canMerge && who.role === "approver" && who.via === "cookie" }, offer: null, target };
         if (!publishing.on || who.via !== "cookie" || who.role !== "approver")
             return null;
         const assignment = assignmentOf(store, taskId, clock(), { principal: "operator", repos: admissionList(), includeUnplaced: visible(null) }, evidenceRoot);

package/dist/store.d.ts

@@ -6188,6 +6188,7 @@ export declare class Store {
         historyNote?: string;
     }, now: Date): boolean;
     /** What a card's current zone is doing: its task, the card's main work, what it waits on, what zones reported. */
+    /** Read and written in one transaction, so a pass changing one field never writes back another pass's older task or waiting. */
     updateFlowCard(id: number, change: {
         task?: string | null;
         primaryTask?: string;

package/dist/store.js

@@ -18795,11 +18795,14 @@ export class Store {
         });
     }
     /** What a card's current zone is doing: its task, the card's main work, what it waits on, what zones reported. */
+    /** Read and written in one transaction, so a pass changing one field never writes back another pass's older task or waiting. */
     updateFlowCard(id, change, now) {
-        const card = this.getFlowCard(id);
-        if (card === null)
-            return;
-        this.db.prepare("UPDATE flow_card SET task = ?, primary_task = ?, waiting = ?, outputs_json = ?, state = ?, updated_at = ? WHERE id = ?").run(change.task === undefined ? card.task : change.task, change.primaryTask ?? card.primaryTask, change.waiting === undefined ? card.waiting : change.waiting, JSON.stringify(change.outputs ?? card.outputs), change.state ?? card.state, now.toISOString(), id);
+        this.transact(() => {
+            const card = this.getFlowCard(id);
+            if (card === null)
+                return;
+            this.db.prepare("UPDATE flow_card SET task = ?, primary_task = ?, waiting = ?, outputs_json = ?, state = ?, updated_at = ? WHERE id = ?").run(change.task === undefined ? card.task : change.task, change.primaryTask ?? card.primaryTask, change.waiting === undefined ? card.waiting : change.waiting, JSON.stringify(change.outputs ?? card.outputs), change.state ?? card.state, now.toISOString(), id);
+        });
     }
     flowEvents(card) {
         return this.db.prepare("SELECT * FROM flow_event WHERE card = ? ORDER BY id").all(card).map(row => ({

package/dist/surface.js

@@ -160,10 +160,16 @@ export const COMMAND_GUIDE = [
         flags: [jsonFlag, dbFlag,
             { name: 'token-env', takesValue: true, meaning: 'scoped coordinator credential environment variable' },
             { name: 'token-file', takesValue: true, meaning: 'scoped coordinator credential file; defaults to selected project reference' },
-            ...(action === 'complete' ? [{ name: 'digest', takesValue: true, meaning: 'exact receipt from assignment show; required for JSON or scoped agents' }]
+            ...(action === 'complete' ? [{ name: 'digest', takesValue: true, meaning: 'exact receipt from assignment show; required for JSON or scoped agents' },
+                { name: 'pull-request', takesValue: false, meaning: "also open the result's pull request from that commit, as the console's Complete does; an approver's sign-in (--as/--token), never a scoped credential; refuses with pull-requests-off and the setup command" }]
                 : [{ name: 'feedback', takesValue: true, meaning: 'specific requested change' }, { name: 'run', takesValue: true, meaning: 'exact result run; defaults to current result' }, { name: 'source', takesValue: true, meaning: 'exact scope digest; defaults to current terms' }, { name: 'key', takesValue: true, meaning: '32 hexadecimal characters for exact replay; defaults to a stable feedback identity' }]),
         ],
     })),
+    { invocation: "task merge", synopsis: "merge the task's pull request once its checks pass — the console's Merge, behind the approver's password; the project's method (squash by default), branch deleted, recorded in the ledger",
+        audience: "operator", agentMayInvoke: false, mutation: "identity-idempotent",
+        positionals: [{ name: "task", required: true, meaning: "any version of the task" }],
+        flags: [jsonFlag, dbFlag, { name: "as", takesValue: true, meaning: "the approver merging" }, { name: "token", takesValue: true, meaning: "their password" }],
+        notableReasons: ["usage", "not-an-approver"] },
     ...["show", "updates", "claim", "check", "brief", "inbox", "ack"].map(action => ({
         invocation: `assignment ${action}`,
         synopsis: action === "show" ? "read the root, current work, owner and exact receipt"

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

@@ -1,4 +1,6 @@
 import { type VerifiedApprover } from './principal.js';
+import { type PullRequestView } from './pull-request-flow.js';
+import type { PublishExec } from './publish.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;
@@ -8,3 +10,19 @@ export declare function runTaskOutcomeCommand(action: 'complete' | 'revise', pos
     now: Date;
     operator: () => Promise<VerifiedApprover | null>;
 }): Promise<number>;
+/** `task merge <task>`: the console's Merge — the newest pull request any version of the task opened through
+ * Complete, merged behind the approver's password once a fresh read shows its checks passing. */
+export declare function runTaskMergeCommand(positional: readonly string[], flags: Map<string, string | true>, context: {
+    store: Store;
+    json: boolean;
+    write: (line: string) => void;
+    clock: () => Date;
+    exec?: PublishExec;
+    demo: boolean;
+    credentials: () => Promise<{
+        name: string;
+        token: string;
+    } | null>;
+}): Promise<number>;
+/** The lines `task show` prints for a task's pull request. */
+export declare function pullRequestLines(view: PullRequestView | null): string[];

package/dist/task-outcome-cli.js

@@ -4,9 +4,11 @@ import { assignmentOf, checkAssignmentAsOperator } from './assignment.js';
 import { assignmentForCoordinator, coordinatorToken } from './assignment-adapters.js';
 import { authenticateCoordinator } from './coordinator.js';
 import { reproveApprover } from './principal.js';
+import { authenticateApprover } from './scope.js';
 import { requestResultChanges } from './result-actions.js';
 import { commentSourceKey, revisionSourceOf } from './result-review.js';
 import { envelopeJson } from './envelope.js';
+import { completeAndOpenPullRequest, mergeAsPerson, newestPullRequestOf, publishingOf, pullRequestViewOf } from './pull-request-flow.js';
 export async function runTaskOutcomeCommand(action, positional, flags, context) {
     const command = `task ${action}`;
     const emit = (result, lines) => {
@@ -14,18 +16,21 @@ export async function runTaskOutcomeCommand(action, positional, flags, context)
         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'])]);
+    const allowed = new Set(['json', 'db', 'as', 'token', 'token-env', 'token-file', ...(action === 'complete' ? ['digest', 'pull-request'] : ['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"'}.`);
+        return fail('usage', `Use task ${action} <task>${action === 'complete' ? ' --digest <receipt> [--pull-request]' : ' --feedback "requested change"'}.`);
+    const pullRequest = flags.has('pull-request');
     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.');
+    if (credential.token !== null && pullRequest)
+        return fail('unauthenticated', 'Opening a pull request is an approver\'s act. Use your operator sign-in (--as and --token), not a scoped credential.');
     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.');
@@ -49,6 +54,28 @@ export async function runTaskOutcomeCommand(action, positional, flags, context)
             const digest = typeof supplied === 'string' ? supplied : current.receipt?.digest;
             if (!digest)
                 return fail('not-ready', 'This task has no finished result to mark complete.');
+            if (pullRequest) {
+                // The console's "Complete and open a pull request": the same exact-receipt completion and owed PR, one transaction.
+                const repo = store.lookupRef(current.activeTaskId)?.repo ?? null;
+                const publishing = publishingOf(store, repo);
+                if (!publishing.on)
+                    return fail('pull-requests-off', `Pull requests aren't set up for this project. Turn them on with: toolroll publish setup --repo ${repo ?? '<path>'} --yes`);
+                if (publishing.legacy)
+                    return fail('pull-requests-off', 'This project opens a pull request for every build. Complete without --pull-request.');
+                const runId = current.receipt?.runId;
+                if (runId === undefined)
+                    return fail('not-ready', 'This task has no finished result to mark complete.');
+                const opened = completeAndOpenPullRequest(store, { taskId: task, digest, runId, who: operator, root: evidenceRoot }, now);
+                if (!opened.ok)
+                    return emit(opened);
+                const link = opened.publication.prUrl;
+                return emit({ ok: true, result: assignmentOf(store, task, now, { principal: 'operator', repos }, evidenceRoot), pullRequest: pullRequestViewOf(store, runId) }, [
+                    `${current.rootId} · Complete`,
+                    `Result: ${current.activeTaskId} · run ${runId} · ${opened.publication.headSha}`,
+                    link === null ? `Pull request: opening from ${opened.publication.headSha.slice(0, 12)} into ${publishing.githubRepo} ${publishing.base}. toolroll task show ${current.rootId} prints its link.` : `Pull request: ${link}`,
+                    `Next: CI is watched on GitHub. Merge when green: toolroll task merge ${current.rootId}`,
+                ]);
+            }
             const changed = credential.token !== null
                 ? assignmentForCoordinator(store, credential.token, 'check', { ref: task, digest }, now, evidenceRoot)
                 : checkAssignmentAsOperator(store, task, digest, operator, now, evidenceRoot);
@@ -90,3 +117,49 @@ export async function runTaskOutcomeCommand(action, positional, flags, context)
         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.']);
     });
 }
+/** `task merge <task>`: the console's Merge — the newest pull request any version of the task opened through
+ * Complete, merged behind the approver's password once a fresh read shows its checks passing. */
+export async function runTaskMergeCommand(positional, flags, context) {
+    const command = 'task merge';
+    const emit = (result, lines) => {
+        context.write(context.json ? envelopeJson({ ...result, command }) : result.ok ? (lines ?? []).join('\n') : result.message ?? 'The merge 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']);
+    for (const key of flags.keys())
+        if (!allowed.has(key))
+            return fail('usage', `--${key} is not a task merge option.`);
+    const task = positional[0];
+    if (positional.length !== 1 || !task || task.length > 64 || /[\x00-\x1f]/.test(task))
+        return fail('usage', 'Use task merge <task> --as <you> --token <password>.');
+    if (context.demo)
+        return fail('demo', 'The demo merges nothing.');
+    const acting = await context.credentials();
+    if (acting === null)
+        return fail('unauthenticated', 'Merging takes your password: --as <you> --token <password>.');
+    const { store } = context;
+    if (!authenticateApprover(store, acting.name, acting.token).ok)
+        return fail('not-an-approver', 'That password didn\'t work, or you can\'t merge.');
+    const family = store.taskFamilyOf(task, store.knownRepos().filter(repo => store.accountCanAccess(acting.name, repo)), false);
+    if (family === null)
+        return fail('not-found', 'That task is unavailable in your projects.');
+    const view = newestPullRequestOf(store, family.versions.map(one => one.id));
+    if (view === null)
+        return fail('no-pr', 'This task has no pull request. Open one with task complete --pull-request.');
+    const merged = await mergeAsPerson(store, { runId: view.runId, name: acting.name, password: acting.token, ...(context.exec === undefined ? {} : { exec: context.exec }), clock: context.clock });
+    if (!merged.ok)
+        return emit({ ...merged, reason: merged.reason === 'password' ? 'not-an-approver' : merged.reason, pullRequest: view });
+    const after = newestPullRequestOf(store, family.versions.map(one => one.id));
+    return emit({ ok: true, pullRequest: after }, [
+        `${family.root.id} · Merged`,
+        `Pull request: ${after?.prUrl ?? view.prUrl ?? `#${view.prNumber}`}`,
+        `Merge commit: ${merged.commit ?? 'recorded by GitHub'} (${after?.mergeMethod ?? view.mergeMethod}, branch deleted)`,
+    ]);
+}
+/** The lines `task show` prints for a task's pull request. */
+export function pullRequestLines(view) {
+    if (view === null)
+        return [];
+    return [`  pull request: ${view.prUrl ?? 'opening'} · ${view.label}`, `    ${view.detail}`, ...(view.mergeCommit === null ? [] : [`    merge commit: ${view.mergeCommit}`])];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolroll",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"