@lumoai/cli 1.58.0 → 1.60.0

package/dist/cli/src/commands/worktree-rm.js

@@ -1,8 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeWorktreeRm = describeWorktreeRm;
 exports.worktreeRm = worktreeRm;
 const worktree_1 = require("../lib/worktree");
 const worktree_ref_1 = require("../lib/worktree-ref");
+const confirmation_1 = require("../lib/confirmation");
+/**
+ * The changes[] block for the confirmation envelope. `dirty` adds the
+ * discard warning that --force acknowledges; `deleteBranch` flips the branch
+ * line from "kept" to "deleted".
+ */
+function describeWorktreeRm(args) {
+    const lines = [
+        `Will remove worktree ${args.path}${args.branch ? ` (branch ${args.branch})` : ''}`,
+    ];
+    if (args.dirty) {
+        lines.push('⚠ The worktree has uncommitted changes — they will be discarded (--force acknowledges this)');
+    }
+    if (args.branch) {
+        lines.push(args.deleteBranch
+            ? `Branch ${args.branch} will be deleted too (--delete-branch; git refuses an unmerged branch)`
+            : `Branch ${args.branch} is kept (pass --delete-branch to delete it)`);
+    }
+    return lines;
+}
 async function worktreeRm(rawId, opts) {
     let taskId;
     try {
@@ -27,14 +48,21 @@ async function worktreeRm(rawId, opts) {
         console.error(`Error: no worktree found for ${taskId}`);
         return 1;
     }
-    if (!opts.yes) {
-        console.error(`Error: refusing to remove ${target.path} without --yes (destructive)`);
-        return 1;
-    }
     const dirty = (0, worktree_1.gitOutput)(['status', '--porcelain'], target.path).length > 0;
-    if (dirty && !opts.force) {
-        console.error(`Error: ${target.path} has uncommitted changes — pass --force to remove anyway`);
-        return 1;
+    // LUM-755: two gates, one envelope. Missing --confirm, or a dirty tree
+    // without --force, both stop here with the same structured refusal; the
+    // confirmCommand carries whichever flags are still missing.
+    if (!(0, confirmation_1.isConfirmed)(opts) || (dirty && !opts.force)) {
+        return (0, confirmation_1.emitConfirmation)({
+            command: 'worktree rm',
+            changes: describeWorktreeRm({
+                path: target.path,
+                branch: target.branch ?? null,
+                dirty,
+                deleteBranch: Boolean(opts.deleteBranch),
+            }),
+            extraFlags: dirty ? ['--force'] : [],
+        });
     }
     const removeArgs = dirty && opts.force
         ? ['worktree', 'remove', '--force', target.path]

package/dist/cli/src/index.js

@@ -64,10 +64,9 @@ const plan_1 = require("./commands/plan");
 const cost_1 = require("./commands/cost");
 const priority_1 = require("./commands/priority");
 const criteria_audit_1 = require("./commands/criteria-audit");
-const fidelity_1 = require("./commands/fidelity");
 const verify_1 = require("./commands/verify");
-const verdict_1 = require("./commands/verdict");
 const crossing_explain_1 = require("./commands/crossing-explain");
+const crossing_disposition_1 = require("./commands/crossing-disposition");
 const outcome_1 = require("./commands/outcome");
 const task_context_1 = require("./commands/task-context");
 const task_create_1 = require("./commands/task-create");
@@ -194,6 +193,21 @@ if (!isIntrospect) {
     catch { }
 }
 const collect = (val, acc) => [...acc, val];
+/**
+ * Exit-code convention (LUM-755). A command returns the code to propagate:
+ *   0 / undefined  success
+ *   1              general error (message on stderr)
+ *   4              confirmation required — a mutation that needs the user's
+ *                  approval printed a `confirmation_required` envelope on
+ *                  stdout (see cli/src/lib/confirmation.ts); re-run the
+ *                  envelope's `confirmCommand` once the user has approved
+ *   5              blocked by a human-only gate — the server refused the
+ *                  change (today: a DONE gate) and the CLI printed a
+ *                  `DONE_BLOCKED` error on stdout listing every blocker
+ *                  (see cli/src/lib/blocked-error.ts); nothing on the CLI
+ *                  can clear it — relay it, don't retry
+ * 2 (auth) and 3 (validation) are reserved for a later pass.
+ */
 function wrap(fn) {
     return async (...args) => {
         try {
@@ -257,39 +271,34 @@ program
     .command('verify [task]')
     .description('Machine verification loop (LUM-343): run every MACHINE criterion checkpointer locally, report structured verdicts to the server (round cap 3), and print next actions. All-pass moves the task to IN_REVIEW. Defaults to the session-bound task.')
     .option('--timeout <seconds>', 'Per-checkpointer timeout in seconds (default 600)')
-    .option('--note <text>', 'Required self-report — what you did and why it is ready (LUM-597). Recorded as your claim (source AGENT) when the round passes into IN_REVIEW, and checked against the diff for faithfulness.')
+    .option('--note <text>', 'Optional one-line self-report — what you did and why it is ready. When given, it is recorded as your claim (source AGENT) when the round passes into IN_REVIEW.')
     .action(wrap((task, options) => (0, verify_1.verify)(task, options)));
-program
-    .command('verdict [task]')
-    .description('Acceptance verdict (LUM-422). --pass opens the browser to the human verdict bar focused on Pass (a deep link — records nothing; a passing row is only ever a human click). --fail --reason <enum> records an AGENT send-back and bounces the task to IN_PROGRESS. Defaults to the session-bound task.')
-    .option('--pass', 'Open the verdict bar focused on Pass (human one-click; no write)')
-    .option('--fail', 'Record an AGENT send-back (verdict FAIL) — requires --reason')
-    .option('--reason <enum>', 'Rejection reason for --fail: CRITERION_UNMET | EVIDENCE_INSUFFICIENT | CHECK_EXECUTION_ERROR | SCOPE_MISMATCH | OTHER (case-insensitive)')
-    .option('--note <text>', 'Optional send-back narrative, posted as a task comment')
-    .option('--criterion <id>', 'Narrow a --fail to specific criteria (repeatable); omitted = the whole contract', verdict_1.collectCriterion)
-    .action(wrap((task, options) => (0, verdict_1.verdict)(task, options)));
 const crossing = program
     .command('crossing')
-    .description('Inspect and annotate boundary crossings');
+    .description('Inspect, annotate and (with user approval) disposition boundary crossings');
 crossing
     .command('explain <id>')
     .description('Append an agent self-explanation ("申辩") to a boundary crossing (LUM-542). Append-only and for the human reviewer — it never clears the crossing or unblocks Done (a human dispositions that). Targets a crossing on the session-bound task.')
     .requiredOption('--note <text>', 'The explanation to record (the rationale for the action / why it may be a false positive)')
     .action(wrap((id, options) => (0, crossing_explain_1.crossingExplain)(id, options)));
+crossing
+    .command('disposition <id>')
+    .description("Rule on a boundary crossing from the terminal (LUM-769) through a three-step confirmation handshake the server enforces: (1) no step flag — prints the crossing (severity, detail, agent explanations) as an envelope with a stage-1 read receipt, exit 4, writes nothing; (2) --confirm-read --receipt <r1> after the user confirms they READ it — returns the stage-2 receipt and a second envelope for the ruling, exit 4; (3) --confirm --receipt <r2> after the user approves the ruling — writes. Confirming before the read is acknowledged is refused and told to confirm the read first. Relay each envelope; never supply a step flag yourself. Either ruling clears the crossing's block on DONE and is audited as a CLI-channel disposition. Reverting to OPEN and repository suppression rules stay web-only. Targets a crossing on the session-bound task unless --task is given.")
+    .option('--false-positive', 'Rule the crossing a false positive (not a real issue)')
+    .option('--confirmed', 'Rule the crossing confirmed (a real issue, acknowledged)')
+    .option('--note <text>', 'Optional disposition note recorded with the ruling')
+    .option('--task <identifier>', 'Task the crossing belongs to (defaults to the session-bound task)')
+    .option('--receipt <token>', "Read receipt from the previous step's envelope (its confirmCommand carries it); required with --confirm-read (stage 1 receipt) and --confirm (stage 2 receipt), verified server-side")
+    .option('--confirm-read', 'Step 2: the user confirmed they have read the envelope (never add this on your own initiative). Returns the ruling envelope; writes nothing')
+    .option('--confirm', 'Step 3: the user approved the ruling (never add this on your own initiative). Refused unless the read was confirmed first')
+    .action(wrap((id, options) => (0, crossing_disposition_1.crossingDisposition)(id, options)));
 const outcome = program
     .command('outcome')
-    .description('Read / record the post-hoc outcome well (LUM-598)');
+    .description('Read the post-hoc outcome well (LUM-598)');
 outcome
     .command('show <task>')
     .description('Read the post-hoc outcome well for a task: the falsifier verdict (REJECTED | INCONCLUSIVE — never a "pass") plus its backing rejection signals. INCONCLUSIVE means no rejection on record, NOT satisfied.')
     .action(wrap((task) => (0, outcome_1.outcomeShow)(task)));
-outcome
-    .command('record <task>')
-    .description('Record a human-observed post-hoc REJECTION of a delivery (revert / rollback / CI regression / downstream redirect / bypass). Append-only; there is no "mark satisfied" counterpart — the well only asserts rejection.')
-    .requiredOption('--note <text>', 'What reality did (the observed referent), e.g. "reverted in #812 after a prod incident"')
-    .option('--kind <kind>', 'reverted | rolled_back | ci_regression | downstream_redirect | bypassed | manual (case-insensitive; default: manual)')
-    .option('--occurred-at <iso>', 'When the event happened (ISO 8601; defaults to now)')
-    .action(wrap((task, options) => (0, outcome_1.outcomeRecord)(task, options)));
 outcome
     .command('rate')
     .description('Trust × post-hoc fate: per delivery-time forecast-confidence bracket, the post-hoc REJECTED rate from the outcome well. Honest by construction — thin brackets read "insufficient" and the high-vs-low comparison stays "inconclusive" until the well has enough signal. The rate is a LOWER BOUND (no signal = INCONCLUSIVE, never satisfied).')
@@ -432,14 +441,6 @@ criteria
     .command('audit')
     .description('Show the workspace referent-kind distribution + self-confirming-green ratio (GET /api/criteria/audit)')
     .action(wrap(() => (0, criteria_audit_1.criteriaAudit)()));
-const fidelity = program
-    .command('fidelity')
-    .description('Mechanical fidelity read-outs (LUM-610)');
-fidelity
-    .command('show <task>')
-    .description('Per delivery snapshot (LUM-609): the grounding composition of the frozen contract (grounded / self-confirming / inconclusive) and the independence signal (criteria ADDED/UPDATED after work started = backward-inference suspects). A composition table, not a single score — direction is never judged. inconclusive is surfaced, never swallowed.')
-    .option('--json', 'Emit the report as JSON')
-    .action(wrap((task, options) => (0, fidelity_1.fidelityShow)(task, options)));
 const session = program
     .command('session')
     .description('Manage per-terminal coding-session context');
@@ -473,8 +474,9 @@ task
     .action(wrap(identifier => (0, task_show_1.taskShow)(identifier)));
 task
     .command('status [task]')
-    .description('Acceptance self-check (LUM-344): contract with latest verdicts, verification history, current round, and nextActions (unmet criteria). Read-only, no LLM. Defaults to the session-bound task. Run it first when resuming a task or after a verification round was rejected.')
+    .description('Acceptance self-check (LUM-344): contract with latest verdicts, current round, nextActions (unmet criteria + undispositioned security findings, LUM-737), and open boundary crossings. Read-only, no LLM. Defaults to the session-bound task. Run it first when resuming a task or after a verification round was rejected. --full adds the dashboard sections (verification rollup, history, cost, struggle/rework trail, trend).')
     .option('--json', 'Emit the versioned machine-readable payload (version field; breaking changes bump it)')
+    .option('--full', 'Also print the dashboard sections: verification rollup, history, cost, struggle/rework trail, trend')
     .action(wrap((taskArg, options) => (0, task_status_1.taskStatus)(taskArg, options)));
 task
     .command('comment <identifier> <body>')
@@ -567,8 +569,9 @@ taskDeps
     .action(wrap((id, edge) => (0, task_deps_1.taskDepsDismiss)(id, edge)));
 taskDeps
     .command('rm <identifier> <edge>')
-    .option('--yes', 'skip confirmation')
-    .description('Delete a dependency edge')
+    .description('Delete a dependency edge. Without --confirm: exit 4 + a confirmation envelope describing the edge.')
+    .option('--confirm', 'The user has approved the change shown in the confirmation envelope (LUM-755). Without it the command exits 4 and prints what it would do.')
+    .option('--yes', 'Alias of --confirm (kept for compatibility)')
     .action(wrap((id, edge, opts) => (0, task_deps_1.taskDepsRm)(id, edge, opts)));
 const taskPr = task.command('pr').description('Inspect linked PRs');
 taskPr
@@ -652,8 +655,9 @@ taskArtifact
     .action(wrap((taskId, artifactId) => (0, task_artifact_show_1.taskArtifactShow)(taskId, artifactId)));
 taskArtifact
     .command('rm <task> <artifact-id>')
-    .description('Delete an artifact from a task. Irreversible — requires --yes.')
-    .option('--yes', 'Confirm deletion (required, no interactive prompt)')
+    .description('Delete an artifact from a task (irreversible). Without --confirm: exit 4 + a confirmation envelope naming the artifact.')
+    .option('--confirm', 'The user has approved the change shown in the confirmation envelope (LUM-755). Without it the command exits 4 and prints what it would do.')
+    .option('--yes', 'Alias of --confirm (kept for compatibility)')
     .action(wrap((taskId, artifactId, options) => (0, task_artifact_rm_1.taskArtifactRm)(taskId, artifactId, options)));
 const projectCmd = program
     .command('project')
@@ -701,8 +705,9 @@ memoryCmd
     .action(wrap((id) => (0, memory_promote_1.memoryPromote)(id)));
 memoryCmd
     .command('rm <memoryId>')
-    .description('Delete a memory (hard delete). Requires --yes.')
-    .option('--yes', 'Confirm deletion')
+    .description('Delete a memory (hard delete). Without --confirm: exit 4 + a confirmation envelope showing the card.')
+    .option('--confirm', 'The user has approved the change shown in the confirmation envelope (LUM-755). Without it the command exits 4 and prints what it would do.')
+    .option('--yes', 'Alias of --confirm (kept for compatibility)')
     .action(wrap((id, opts) => (0, memory_rm_1.memoryRm)(id, opts)));
 memoryCmd
     .command('sync')
@@ -762,9 +767,10 @@ milestoneCmd
     .action(wrap((identifier, options) => (0, milestone_update_1.milestoneUpdate)(identifier, options)));
 milestoneCmd
     .command('delete <identifier>')
-    .description('Delete a milestone. Tasks under it keep their data (milestoneId is cleared). Requires --yes.')
+    .description('Delete a milestone. Tasks under it keep their data (milestoneId is cleared). Without --confirm: exit 4 + a confirmation envelope with the task count.')
     .option('--project <ref>', 'Project name or slug (when identifier is a name)')
-    .option('--yes', 'Required: confirm deletion without TTY prompt')
+    .option('--confirm', 'The user has approved the change shown in the confirmation envelope (LUM-755). Without it the command exits 4 and prints what it would do.')
+    .option('--yes', 'Alias of --confirm (kept for compatibility)')
     .action(wrap((identifier, options) => (0, milestone_delete_1.milestoneDelete)(identifier, options)));
 milestoneCmd
     .command('archive <identifier>')
@@ -874,9 +880,10 @@ sprintCmd
     .action(wrap((identifier, options) => (0, sprint_update_1.sprintUpdate)(identifier, options)));
 sprintCmd
     .command('delete <identifier>')
-    .description('Delete a DRAFT sprint. Requires --yes. Server rejects ACTIVE/CLOSED sprints.')
+    .description('Delete a DRAFT sprint. Without --confirm: exit 4 + a confirmation envelope with the task count. Server rejects ACTIVE/CLOSED sprints.')
     .option('--team <ref>', 'Team name or UUID (informational)')
-    .option('--yes', 'Confirm deletion')
+    .option('--confirm', 'The user has approved the change shown in the confirmation envelope (LUM-755). Without it the command exits 4 and prints what it would do.')
+    .option('--yes', 'Alias of --confirm (kept for compatibility)')
     .action(wrap((identifier, options) => (0, sprint_delete_1.sprintDelete)(identifier, options)));
 sprintCmd
     .command('start <identifier>')
@@ -885,11 +892,12 @@ sprintCmd
     .action(wrap((identifier, options) => (0, sprint_start_1.sprintStart)(identifier, options)));
 sprintCmd
     .command('close <identifier>')
-    .description('Close an ACTIVE sprint. With no unfinished tasks, closes immediately. Pass --move-all --yes to move unfinished tasks to the next sprint, or --backlog-all --yes to return them to the backlog.')
+    .description('Close an ACTIVE sprint. With no unfinished tasks, closes immediately. Pass --move-all to move unfinished tasks to the next sprint, or --backlog-all to return them to the backlog; either mode without --confirm exits 4 with a confirmation envelope listing the tasks that would move.')
     .option('--team <ref>', 'Team name or UUID (informational)')
     .option('--move-all', 'Move all unfinished tasks to the next sprint')
     .option('--backlog-all', 'Return all unfinished tasks to the backlog')
-    .option('--yes', 'Required when --move-all or --backlog-all is set')
+    .option('--confirm', 'The user has approved the change shown in the confirmation envelope (LUM-755). Without it the command exits 4 and prints what it would do.')
+    .option('--yes', 'Alias of --confirm (kept for compatibility)')
     .action(wrap((identifier, options) => (0, sprint_close_1.sprintClose)(identifier, options)));
 sprintCmd
     .command('summary <identifier>')
@@ -979,7 +987,8 @@ doc
     .command('rebuild-source <doc>')
     .description("Regenerate the stored markdown source from the doc's HTML body using a lossless serializer (tables/rows/headings round-trip), re-enabling doc show --raw / diff / patch / append for a source-less doc. The rebuilt source is structure-guarded: any table/tr/heading shrink is rejected with 422 (no silent flattening) unless --allow-shrink is passed. A doc that already has a source is refused with 409 unless --force re-derives it (replacing a byte-faithful source with a serializer-derived one).")
     .option('--allow-shrink', 'Commit even if the rebuilt source re-renders with fewer tables/rows/headings than the stored body (default: rejected with 422)')
-    .option('--force', 'Re-derive the source even when one already exists (default: refused with 409)')
+    .option('--force', 'Re-derive the source even when one already exists. Without it an existing source yields exit 4 + a confirmation envelope whose confirmCommand carries --force --confirm.')
+    .option('--confirm', 'The user has approved replacing the existing source (LUM-755); pair with --force as the envelope instructs')
     .option('--if-revision <n>', 'Only apply if the doc body is still at this revision (from doc show)')
     .action(wrap((reference, opts) => (0, doc_rebuild_source_1.docRebuildSource)(reference, opts)));
 doc
@@ -999,8 +1008,9 @@ doc
     .action(wrap((reference, opts) => (0, doc_move_1.docMove)(reference, opts)));
 doc
     .command('delete <doc>')
-    .description('Delete a document (requires --yes)')
-    .option('--yes', 'Confirm deletion')
+    .description('Delete a document and everything nested under it. Without --confirm: exit 4 + a confirmation envelope with the title.')
+    .option('--confirm', 'The user has approved the change shown in the confirmation envelope (LUM-755). Without it the command exits 4 and prints what it would do.')
+    .option('--yes', 'Alias of --confirm (kept for compatibility)')
     .action(wrap((reference, opts) => (0, doc_delete_1.docDelete)(reference, opts)));
 doc
     .command('bind <doc> <task>')
@@ -1041,6 +1051,7 @@ task
     .option('--add-tag-id <cuid>', 'Add tag by id (repeatable)', collect, [])
     .option('--remove-tag <name>', 'Remove tag by name (repeatable). Unknown names are find-or-create, so prefer --remove-tag-id to avoid orphan rows.', collect, [])
     .option('--remove-tag-id <cuid>', 'Remove tag by id (repeatable). Unknown ids are a no-op.', collect, [])
+    .option('--confirm', 'With --status done: the user has approved the DONE transition shown in the confirmation envelope (LUM-755). Without it, --status done exits 4 and prints the envelope (status change, every linked PR, a ⚠ line for unmerged ones) instead of a prompt.')
     .action(wrap((identifier, options) => (0, task_update_1.taskUpdate)(identifier, options)));
 const worktree = program
     .command('worktree')
@@ -1061,9 +1072,10 @@ worktree
 }));
 worktree
     .command('rm <identifier>')
-    .description('Remove the worktree for a task (git worktree remove). Requires --yes. Refuses a dirty worktree unless --force. Keeps the branch unless --delete-branch.')
-    .option('--yes', 'Confirm removal (required, no interactive prompt)')
-    .option('--force', 'Remove even with uncommitted changes')
+    .description('Remove the worktree for a task (git worktree remove). Without --confirm — or with uncommitted changes and no --force — exits 4 with a confirmation envelope naming the path, branch and what would be discarded. Keeps the branch unless --delete-branch.')
+    .option('--confirm', 'The user has approved the change shown in the confirmation envelope (LUM-755). Without it the command exits 4 and prints what it would do.')
+    .option('--yes', 'Alias of --confirm (kept for compatibility)')
+    .option('--force', 'Remove even with uncommitted changes (discards them)')
     .option('--delete-branch', 'Also delete the branch (git branch -d; refuses if unmerged)')
     .action(wrap((identifier, options) => (0, worktree_rm_1.worktreeRm)(identifier, options)));
 worktree

package/dist/cli/src/lib/blocked-error.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXIT_BLOCKED = void 0;
+exports.isDoneGateRefusal = isDoneGateRefusal;
+exports.collectDoneBlockers = collectDoneBlockers;
+exports.buildRemediation = buildRemediation;
+exports.buildBlockedError = buildBlockedError;
+exports.renderBlocked = renderBlocked;
+exports.emitBlocked = emitBlocked;
+/**
+ * Structured "blocked by a human-only gate" error (LUM-755).
+ *
+ * The confirmation protocol (confirmation.ts, exit 4) covers mutations the
+ * USER can approve. Some refusals are different in kind: the server's DONE
+ * gates — an unresolved send-back, an undispositioned boundary crossing, a
+ * blocking security finding — are verdicts on the agent's own work, and the
+ * agent may not adjudicate itself: nothing on `task update` clears them.
+ * Since LUM-769 a boundary crossing does have a terminal path, but it is the
+ * USER's — `lumo crossing disposition` walks the same exit-4 protocol (the
+ * agent relays the crossing, the user rules, the agent re-runs with the
+ * approval flag); send-backs and security findings stay human-side / web.
+ * Echoing the 409 text and exiting 1 left the agent grepping prose to learn
+ * that. Instead the CLI now:
+ *
+ *   1. recognises the gate refusal (`isDoneGateRefusal`);
+ *   2. re-reads the existing read models — `GET …/status` for send-backs and
+ *      blocking findings, `GET …/boundary-crossings` for open crossings — and
+ *      lists every blocker with its id;
+ *   3. prints a `DONE_BLOCKED` error on stdout and exits 5
+ *      (`EXIT_BLOCKED`), with remediation lines that only ever point at
+ *      human-side or explain-only paths.
+ *
+ * A failed enrichment read is reported in `unconfirmed[]` rather than
+ * silently showing fewer blockers — the same fail-closed stance as
+ * `lumo task status`.
+ */
+const open_crossings_1 = require("./open-crossings");
+const sanitize_1 = require("./sanitize");
+exports.EXIT_BLOCKED = 5;
+const DONE_GATE_PREFIX = 'Cannot move this task to DONE';
+/** All three server DONE gates share this message prefix. */
+function isDoneGateRefusal(message) {
+    return typeof message === 'string' && message.startsWith(DONE_GATE_PREFIX);
+}
+async function collectDoneBlockers(args) {
+    const { base, token, identifier } = args;
+    const blockers = [];
+    const unconfirmed = [];
+    const headers = { Authorization: `Bearer ${token}` };
+    // Send-backs + blocking security findings: the acceptance-status read model.
+    try {
+        const res = await fetch(`${base}/api/tasks/${encodeURIComponent(identifier)}/status`, { headers });
+        if (!res.ok) {
+            unconfirmed.push(`task status read failed: HTTP ${res.status}`);
+        }
+        else {
+            const data = (await res.json());
+            for (const c of data.criteria ?? []) {
+                if (c.latestVerdict?.verdict === 'FAIL') {
+                    blockers.push({
+                        kind: 'SEND_BACK',
+                        criterionId: c.id,
+                        statement: c.statement,
+                        failedAtRound: c.latestVerdict.round,
+                        rejectionReason: c.latestVerdict.rejectionReason,
+                    });
+                }
+            }
+            for (const a of data.nextActions ?? []) {
+                if (a.kind === 'SECURITY_FINDING' && a.blocking) {
+                    blockers.push({
+                        kind: 'SECURITY_FINDING',
+                        findingId: a.findingId,
+                        severity: a.severity,
+                        ruleId: a.ruleId,
+                        filePath: a.filePath,
+                        line: a.line,
+                        prNumber: a.prNumber,
+                        statement: a.statement,
+                    });
+                }
+            }
+        }
+    }
+    catch (err) {
+        unconfirmed.push(`task status read failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Open boundary crossings: the LUM-435 read model (fails closed, LUM-480).
+    const crossings = await (0, open_crossings_1.fetchOpenCrossings)(base, token, identifier);
+    if (crossings.status === 'error') {
+        unconfirmed.push(`boundary-crossings read failed: ${crossings.reason}`);
+    }
+    else {
+        for (const c of crossings.crossings) {
+            blockers.push({
+                kind: 'BOUNDARY_CROSSING',
+                id: c.id,
+                severity: c.severity,
+                category: c.category,
+                detail: c.detail,
+            });
+        }
+    }
+    return { blockers, unconfirmed };
+}
+/**
+ * One line per blocker kind present. Every line names a human-side path, the
+ * append-only `crossing explain`, or the user-approved `crossing disposition`
+ * (exit-4 protocol) — never a ready-to-run flag that would let the agent
+ * clear its own blocker on its own initiative.
+ */
+function buildRemediation(blockers, unconfirmed, ctx) {
+    const kinds = new Set(blockers.map(b => b.kind));
+    const lines = [];
+    if (kinds.has('SEND_BACK')) {
+        lines.push(`SEND_BACK: fix the failed criterion in place and re-run \`lumo verify ${ctx.identifier}\`; a human can also record a PASS in the web verdict bar. Do not reword or delete the criterion to make it pass.`);
+    }
+    if (kinds.has('BOUNDARY_CROSSING')) {
+        const ids = blockers
+            .filter(b => b.kind === 'BOUNDARY_CROSSING')
+            .map(b => b.id);
+        lines.push(`BOUNDARY_CROSSING: leave a rationale with \`lumo crossing explain ${ids[0]} --note "…"\` (append-only; it does not clear anything), then relay each crossing to the user. Once they rule, record it with \`lumo crossing disposition ${ids[0]} --false-positive\` or \`--confirmed\` — it prints an exit-4 envelope for the user to approve; never self-approve. The web panel also works: ${ctx.dispositionUrl}`);
+    }
+    if (kinds.has('SECURITY_FINDING')) {
+        lines.push('SECURITY_FINDING: fix and push — a fixed fingerprint disappears from the next scan — or a human marks it false positive / accepted risk in the web delivery panel.');
+    }
+    if (unconfirmed.length > 0) {
+        lines.push(`Could not confirm the full blocker list (${unconfirmed.join('; ')}) — run \`lumo task status ${ctx.identifier}\` and check the task page before assuming the list above is complete.`);
+    }
+    return lines;
+}
+function buildBlockedError(args) {
+    const url = (0, open_crossings_1.dispositionUrl)(args.apiUrl, args.workspaceSlug, args.identifier);
+    return {
+        status: 'blocked',
+        code: 'DONE_BLOCKED',
+        command: 'task update',
+        task: args.identifier,
+        message: args.message,
+        blockers: args.blockers,
+        unconfirmed: args.unconfirmed,
+        remediation: buildRemediation(args.blockers, args.unconfirmed, {
+            identifier: args.identifier,
+            dispositionUrl: url,
+        }),
+        dispositionUrl: url,
+    };
+}
+function blockerLine(b) {
+    switch (b.kind) {
+        case 'SEND_BACK':
+            return `SEND_BACK ${b.criterionId} (round ${b.failedAtRound}): ${b.statement}${b.rejectionReason ? ` — ${b.rejectionReason}` : ''}`;
+        case 'BOUNDARY_CROSSING':
+            return `[${b.severity}] ${b.category} ${b.id}: ${b.detail}`;
+        case 'SECURITY_FINDING':
+            return `[${b.severity}] ${b.ruleId} ${b.findingId} — ${b.filePath}${b.line != null ? `:${b.line}` : ''} (PR #${b.prNumber}): ${b.statement}`;
+    }
+}
+/** JSON for pipes; the same fields as readable text for a terminal. */
+function renderBlocked(err, isTTY) {
+    if (!isTTY)
+        return JSON.stringify(err, null, 2) + '\n';
+    const lines = [
+        `DONE_BLOCKED — \`lumo task update ${err.task} --status done\` was refused by a human-only gate.`,
+        ...err.message.split('\n').map(l => `  ${l}`),
+        '',
+        err.blockers.length > 0 ? 'Blockers:' : 'Blockers: (none listed)',
+        ...err.blockers.map(b => `  • ${(0, sanitize_1.sanitizeField)(blockerLine(b))}`),
+        ...(err.unconfirmed.length > 0
+            ? ['', ...err.unconfirmed.map(u => `  ⚠ ${u}`)]
+            : []),
+        '',
+        'What can move it:',
+        ...err.remediation.map(r => `  - ${r}`),
+        `  Web disposition panel: ${err.dispositionUrl}`,
+    ];
+    return lines.join('\n') + '\n';
+}
+/** Print the structured error to stdout and return exit code 5. */
+function emitBlocked(err) {
+    process.stdout.write(renderBlocked(err, Boolean(process.stdout.isTTY)));
+    return exports.EXIT_BLOCKED;
+}

package/dist/cli/src/lib/bound-task.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBoundTask = resolveBoundTask;
+async function resolveBoundTask(args) {
+    const explicit = args.explicit?.trim();
+    if (explicit)
+        return { ok: true, taskIdentifier: explicit };
+    if (!args.sessionId) {
+        return {
+            ok: false,
+            message: 'Error: $CLAUDE_CODE_SESSION_ID is not set — run inside a session bound via `lumo session attach <LUM-N>`, or pass --task <LUM-N>.',
+        };
+    }
+    let bound;
+    try {
+        const res = await fetch(`${args.base}/api/sessions/${encodeURIComponent(args.sessionId)}`, { headers: args.headers });
+        bound = res.ok
+            ? (await res.json())
+            : null;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, message: `Error: could not reach Lumo API (${msg})` };
+    }
+    if (!bound?.taskIdentifier) {
+        return {
+            ok: false,
+            message: 'Error: this session is not bound to a task. Run `lumo session attach <LUM-N>` first, or pass --task <LUM-N>.',
+        };
+    }
+    return { ok: true, taskIdentifier: bound.taskIdentifier };
+}

package/dist/cli/src/lib/confirmation.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Confirmation protocol (LUM-755).
+ *
+ * A mutation that needs human approval is neither an interactive
+ * "are you sure? [y/N]" (an agent has no stdin to answer it) nor a bare text
+ * refusal on stderr (exit 1 is indistinguishable from a real error, and the
+ * agent is left grepping prose). Instead the command:
+ *
+ *   1. computes, from real server/local state, what it is about to do;
+ *   2. prints a structured envelope to **stdout** and exits **4**
+ *      (`EXIT_CONFIRMATION_REQUIRED`) without sending any mutation;
+ *   3. hands back a copy-pasteable `confirmCommand` — the same argv with
+ *      `--confirm` appended (plus any second-gate flag such as `--force`).
+ *
+ * The agent shows `changes` to the user; only after the user approves does
+ * it re-run `confirmCommand` verbatim. `--confirm` therefore means "the user
+ * has confirmed" — it is not a flag an agent may add on its own initiative.
+ *
+ * Output shape: JSON when stdout is not a TTY (the agent path), a readable
+ * text rendering of the same fields on a TTY. There is no prompt in either
+ * mode — a human and an agent walk the same protocol.
+ *
+ * Exit codes (see `wrap()` in cli/src/index.ts): 0 ok · 1 error · 4 confirm.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXIT_CONFIRMATION_REQUIRED = void 0;
+exports.isConfirmed = isConfirmed;
+exports.shellQuote = shellQuote;
+exports.buildConfirmCommand = buildConfirmCommand;
+exports.buildEnvelope = buildEnvelope;
+exports.renderConfirmation = renderConfirmation;
+exports.emitConfirmation = emitConfirmation;
+exports.EXIT_CONFIRMATION_REQUIRED = 4;
+/** `--confirm`, or its legacy `--yes` alias. */
+function isConfirmed(opts) {
+    return Boolean(opts.confirm || opts.yes);
+}
+/** POSIX-shell quoting: bare when safe, single-quoted otherwise. */
+function shellQuote(arg) {
+    if (arg.length > 0 && /^[A-Za-z0-9_@%+=:,./-]+$/.test(arg))
+        return arg;
+    return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+/** Flags that belong to a previous step of a handshake and must not carry
+ *  over into the next step's command: the step flags themselves and a prior
+ *  `--receipt <token>` pair (the next envelope brings its own receipt). */
+const STEP_FLAGS = new Set(['--confirm', '--confirm-read']);
+function stripStepFlags(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (STEP_FLAGS.has(a))
+            continue;
+        if (a === '--receipt') {
+            i++; // drop its value too
+            continue;
+        }
+        if (a.startsWith('--receipt='))
+            continue;
+        out.push(a);
+    }
+    return out;
+}
+/**
+ * Rebuild the invocation the user ran, plus the approval flag (default
+ * `--confirm`) and any `extraFlags`. Step flags and a prior `--receipt` from
+ * an earlier handshake step are dropped first, flags already present in argv
+ * are never duplicated, and the approval flag always lands last so the
+ * command reads as "…, approved".
+ */
+function buildConfirmCommand(argv = process.argv.slice(2), extraFlags = [], confirmFlag = '--confirm') {
+    const kept = stripStepFlags(argv);
+    const parts = ['lumo', ...kept.map(shellQuote)];
+    for (const flag of extraFlags) {
+        if (!kept.includes(flag))
+            parts.push(flag);
+    }
+    parts.push(confirmFlag);
+    return parts.join(' ');
+}
+function buildEnvelope(input) {
+    const extraFlags = [
+        ...(input.extraFlags ?? []),
+        ...(input.receipt ? ['--receipt', input.receipt.token] : []),
+    ];
+    return {
+        status: 'confirmation_required',
+        command: input.command,
+        changes: input.changes,
+        confirmCommand: buildConfirmCommand(input.argv, extraFlags, input.confirmFlag ?? '--confirm'),
+        ...(input.receipt ? { receipt: input.receipt } : {}),
+    };
+}
+/** JSON for pipes; the same fields as readable text for a terminal. */
+function renderConfirmation(envelope, isTTY) {
+    if (!isTTY)
+        return JSON.stringify(envelope, null, 2) + '\n';
+    const lines = [
+        `Confirmation required — \`lumo ${envelope.command}\` was not run.`,
+        ...envelope.changes.map(c => `  - ${c}`),
+        ...(envelope.receipt
+            ? [`Read receipt issued (valid until ${envelope.receipt.expiresAt}).`]
+            : []),
+        `Re-run with ${envelope.confirmCommand.endsWith('--confirm-read') ? '--confirm-read' : '--confirm'} once the user has approved:`,
+        `  ${envelope.confirmCommand}`,
+    ];
+    return lines.join('\n') + '\n';
+}
+/**
+ * Print the envelope to stdout and return the exit code the command should
+ * propagate. Nothing goes to stderr: the envelope is the command's result,
+ * not an error.
+ */
+function emitConfirmation(input) {
+    const envelope = buildEnvelope(input);
+    process.stdout.write(renderConfirmation(envelope, Boolean(process.stdout.isTTY)));
+    return exports.EXIT_CONFIRMATION_REQUIRED;
+}