@lumoai/cli 1.58.0 → 1.59.0

package/dist/cli/src/index.js

@@ -64,9 +64,7 @@ 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 outcome_1 = require("./commands/outcome");
 const task_context_1 = require("./commands/task-context");
@@ -194,6 +192,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,17 +270,8 @@ 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');
@@ -278,18 +282,11 @@ crossing
     .action(wrap((id, options) => (0, crossing_explain_1.crossingExplain)(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 +429,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 +462,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 +557,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 +643,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 +693,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 +755,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 +868,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 +880,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 +975,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 +996,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 +1039,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 +1060,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,178 @@
+"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 by
+ * design there is no CLI path to clear them (the interested party may not
+ * adjudicate itself). 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 or
+ * the append-only `crossing explain` — never a flag or command that would let
+ * the agent clear its own blocker.
+ */
+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). A human dispositions each crossing (false positive / confirmed) at ${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}`),
+        `  Disposition (human-only): ${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/confirmation.js

@@ -0,0 +1,89 @@
+"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, `'\\''`)}'`;
+}
+/**
+ * Rebuild the invocation the user ran, plus `--confirm` (and any
+ * `extraFlags`). Flags already present in argv are never duplicated, and
+ * `--confirm` always lands last so the command reads as "…, approved".
+ */
+function buildConfirmCommand(argv = process.argv.slice(2), extraFlags = []) {
+    const kept = argv.filter(a => a !== '--confirm');
+    const parts = ['lumo', ...kept.map(shellQuote)];
+    for (const flag of extraFlags) {
+        if (!kept.includes(flag))
+            parts.push(flag);
+    }
+    parts.push('--confirm');
+    return parts.join(' ');
+}
+function buildEnvelope(input) {
+    return {
+        status: 'confirmation_required',
+        command: input.command,
+        changes: input.changes,
+        confirmCommand: buildConfirmCommand(input.argv, input.extraFlags),
+    };
+}
+/** 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}`),
+        'Re-run with --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;
+}

package/dist/cli/src/lib/hook-runner.js

@@ -68,8 +68,11 @@ function readStdin() {
  *
  * For 'pre-tool-use' the array contains:
  *   [0] (optional) a PreToolUse hookSpecificOutput JSON carrying the parallel-
- *       edit collision warning as additionalContext, when the server returned a
- *       `collisionWarning` (LUM-150 step ③). Empty otherwise.
+ *       edit collision warning (LUM-150 step ③), the one-shot boundary-
+ *       crossing reminder (LUM-542), and the one-shot PR security-scan
+ *       reminder (LUM-737) as additionalContext, when the server returned any
+ *       of `collisionWarning`, `crossingReminder`, `securityReminder`. Empty
+ *       otherwise.
  *
  * The JSON lines conform to Claude Code's hookSpecificOutput envelope so the
  * runtime injects additionalContext into the conversation automatically.
@@ -83,8 +86,9 @@ _now = new Date()) {
         if (responseBody == null || typeof responseBody !== 'object')
             return [];
         const body = responseBody;
-        // Two independent PreToolUse signals (LUM-150 collision, LUM-542 crossing
-        // reminder) share one additionalContext block when both are present.
+        // Three independent PreToolUse signals (LUM-150 collision, LUM-542
+        // crossing reminder, LUM-737 security reminder) share one
+        // additionalContext block when more than one is present.
         const parts = [];
         if (typeof body.collisionWarning === 'string' &&
             body.collisionWarning !== '')
@@ -92,6 +96,9 @@ _now = new Date()) {
         if (typeof body.crossingReminder === 'string' &&
             body.crossingReminder !== '')
             parts.push(body.crossingReminder);
+        if (typeof body.securityReminder === 'string' &&
+            body.securityReminder !== '')
+            parts.push(body.securityReminder);
         if (parts.length === 0)
             return [];
         return [
@@ -121,13 +128,14 @@ _now = new Date()) {
     else if (tb && tb.bound === false) {
         lines.push(unboundPromptLine(sessionId));
     }
-    // Blocker warning + criteria + progress + memory + linked resources +
-    // PR-review todos share one additionalContext block so Claude Code injects a
-    // single coherent context payload at session start. The dependency blocker
-    // warning (LUM-172) slots in first so it stays prominent — it can preempt the
-    // session's work entirely. Then the progressive-disclosure tiers (LUM-500):
-    // Tier-0 acceptance contract → Tier-1 prior-session progress → Tier-2 memory
-    // index → linked resources.
+    // Blocker warning + security findings + criteria + progress + memory +
+    // linked resources + PR-review todos share one additionalContext block so
+    // Claude Code injects a single coherent context payload at session start.
+    // The dependency blocker warning (LUM-172) slots in first so it stays
+    // prominent — it can preempt the session's work entirely. The undispositioned
+    // security findings warning (LUM-737) follows next. Then the
+    // progressive-disclosure tiers (LUM-500): Tier-0 acceptance contract →
+    // Tier-1 prior-session progress → Tier-2 memory index → linked resources.
     //
     // LUM-500: the prior-session recovery is now the server-rendered Tier-1
     // `progressSection`, which REPLACES the CLI-rendered recovery card so progress
@@ -137,6 +145,10 @@ _now = new Date()) {
         // Blocker warning first: it can preempt the session's work entirely (wait
         // for the blocker instead of starting) — LUM-172.
         body.blockerWarningSection,
+        // LUM-737: undispositioned security findings — second, before the
+        // contract: it changes what "done" needs (fix + push, or a human
+        // disposition) but unlike a blocker does not preempt the session.
+        body.securityFindingsSection,
         // Tier-0 acceptance contract: what the session's work is judged against
         // (LUM-342).
         body.criteriaSection,

package/dist/shared/src/referent-kind.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REFERENT_KIND_DECLARABLE = void 0;
+exports.TASK_REFERENT_KIND_DECLARABLE = exports.REFERENT_KIND_DECLARABLE = void 0;
 exports.classifyCheckpointerGrounding = classifyCheckpointerGrounding;
 exports.effectiveReferentKind = effectiveReferentKind;
+exports.deriveReferentKind = deriveReferentKind;
 /**
  * referentKind (LUM-602): what a criterion anchors — the only dimension that
  * determines independence. Dependency-light (no @prisma/client) so both the
@@ -14,6 +15,15 @@ exports.REFERENT_KIND_DECLARABLE = [
     'AGENT_CONSTRUCTED_STATE',
     'PENDING_OUTCOME',
 ];
+/**
+ * LUM-733: the kinds a TASK criterion may still carry. PENDING_OUTCOME is no
+ * longer accepted on task criteria (it had no check and no reader); it remains
+ * declarable on milestone exit criteria only.
+ */
+exports.TASK_REFERENT_KIND_DECLARABLE = [
+    'EXTERNAL_FACT',
+    'AGENT_CONSTRUCTED_STATE',
+];
 /** Tools whose output the agent cannot author — external facts. */
 const EXTERNAL_TOOLS = [
     'git',
@@ -319,3 +329,23 @@ function effectiveReferentKind(args) {
     }
     return declared;
 }
+/**
+ * LUM-733: the referent kind is DERIVED by the system, not declared by the
+ * agent. A MACHINE criterion's kind follows its checkpointer — EXTERNAL_FACT
+ * only when the check actually consumes an external tool (git/gh/curl/psql/…),
+ * AGENT_CONSTRUCTED_STATE otherwise — so any declaration on a MACHINE criterion
+ * is ignored (there is nothing to mis-declare and nothing to catch). A HUMAN
+ * criterion has no checkpointer to read, so an optional declaration is kept
+ * as-is; absent, it stays null (unclassified).
+ */
+function deriveReferentKind(args) {
+    const { verifierType, checkpointer, declared } = args;
+    if (verifierType === 'MACHINE') {
+        return classifyCheckpointerGrounding(checkpointer) === 'EXTERNAL'
+            ? 'EXTERNAL_FACT'
+            : 'AGENT_CONSTRUCTED_STATE';
+    }
+    return declared === 'EXTERNAL_FACT' || declared === 'AGENT_CONSTRUCTED_STATE'
+        ? declared
+        : null;
+}

package/dist/shared/src/security-scan.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXTERNAL_ERROR_PREFIX = void 0;
+exports.externalFailureReason = externalFailureReason;
+/**
+ * PR security scan — the one `PrSecurityScan.error` shape that may be shown
+ * as an external-scanner reason (spec P8). Shared by the web panel, the PR
+ * summary (both via `lib/security-scan/stages.ts`, which re-exports this)
+ * and the CLI (`cli/src/commands/task-status.ts`), so the three renderers
+ * cannot drift apart (LUM-756).
+ *
+ * The column has two writers: the ingest / managed-scan workflow, which
+ * scrubs its reason and stamps this prefix on it (the prefix is the proof of
+ * provenance), and stage A's own catch-all, which writes a RAW, unscrubbed
+ * `error.message` with no prefix. Renderers therefore check the prefix first
+ * and print only what follows it; unprefixed text is never published.
+ */
+exports.EXTERNAL_ERROR_PREFIX = 'external: ';
+/**
+ * The scanner's reason, or null when there is none to show: a missing /
+ * empty error, an unprefixed (stage A raw) error, or a prefix with nothing
+ * after it.
+ */
+function externalFailureReason(error) {
+    if (!error || !error.startsWith(exports.EXTERNAL_ERROR_PREFIX))
+        return null;
+    const reason = error.slice(exports.EXTERNAL_ERROR_PREFIX.length);
+    return reason.length > 0 ? reason : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumoai/cli",
-  "version": "1.58.0",
+  "version": "1.59.0",
   "description": "Lumo CLI — manage tasks and sessions from the terminal",
   "license": "MIT",
   "author": "cli@uselumo.ai",