@lumoai/cli 1.38.0 → 1.39.0

package/assets/skill/SKILL.md

@@ -82,6 +82,7 @@ The command catalog below is a **map**: it lists every command grouped by domain
 - `lumo verify [task] [--timeout <seconds>]` — run every MACHINE criterion's checkpointer locally, report one structured PASS/FAIL verdict per criterion to the server, print next actions. Defaults to the session-bound task. Round cap 3: an all-pass round moves the task to IN_REVIEW (agent stops there); a round-3 fail escalates to a human (stop retrying). **Run this before claiming a task is done.**
 - `lumo task status [task] [--json]` — read-only acceptance self-check (no LLM, milliseconds): the contract with each criterion's latest verdict (REVIEW_ADDED provenance visible), verification history, current round, last round's failure reasons, a per-criterion **send-back lifecycle** line when applicable (`↳ send-back (rN) resolved in rM · PR #K` / `… open` — LUM-511 Phase 5), `nextActions` = the unmet criteria (the declarative "what's next" — no separate plan), and any OPEN (undispositioned) boundary crossings (count + per crossing category/severity/detail + a read-only attribution line `↳ by model=…·agent=…·session=…` naming who/what crossed, `unknown` when unresolved — LUM-469; `--json` adds an `openCrossings` field, each entry carrying an `attribution` object) — read-only awareness, disposition stays web + human-only (LUM-448). The crossings check fails closed (LUM-480): if the read errors, the block prints `⚠ Boundary-crossing check failed` instead of staying silent, and `--json` sets `openCrossings: null` (distinct from `[]` = a successful read with zero open — treat `null` as "could not confirm", not "safe"). Defaults to the session-bound task; `--json` emits a versioned payload (`version` field). **Run it first when resuming a task in a new session or after a verification round was rejected.**
 - `lumo verdict [task] --pass | --fail` — acceptance verdicts (LUM-422). `--pass` opens the browser to the human verdict bar focused on Pass (a deep link — **records nothing**; a passing data row is only ever a human's own click). `--fail --reason <enum> [--note <text>] [--criterion <id>…]` records an **AGENT send-back** (verifierType=AGENT, verdict hard-coded FAIL) and bounces the task to IN_PROGRESS. Defaults to the session-bound task. **An unresolved send-back (machine/AGENT/human FAIL) blocks the agent/CLI DONE transition with 409** — clear it (re-verify) before `task update --status done`.
+- `lumo crossing explain <id> --note "<text>"` — append an agent self-explanation ("申辩") to a boundary crossing (LUM-542). The **inverse** of dispositioning: this is the agent/CLI path (bearer-only; a clerk/human caller is refused), but it can **only append** an append-only note — it **never clears the crossing or unblocks Done** (disposition stays web + human-only, LUM-448). The note is shown to the human reviewer at disposition time and kept for later review, explicitly labeled _agent self-report · unverified_. Scope: `<id>` must be a crossing on the **session-bound task** (resolved from `$CLAUDE_CODE_SESSION_ID`; cross-task targets and unbound/mismatched sessions are rejected). Earlier explanations are immutable — a correction is a new note. **When to suggest:** after `lumo task status` (or the next pre-tool-use hook's one-time reminder) surfaces an OPEN crossing you believe is a false positive or want to leave a rationale for — record it here; it's a review aid, not a way to self-clear the gate.
 
 **Cost (per-operation token read-out)** — see [task-context.md](references/task-context.md)
 

package/dist/cli/src/commands/crossing-explain.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.crossingExplain = crossingExplain;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const sanitize_1 = require("../lib/sanitize");
+/**
+ * `lumo crossing explain <id> --note "…"` — append an agent self-explanation
+ * ("申辩") to a boundary crossing (LUM-542).
+ *
+ * This is the AGENT side of the boundary-crossing review loop and the deliberate
+ * inverse of dispositioning: it can only ADD an append-only note for the human
+ * reviewer to weigh — it never clears the crossing or unblocks Done (a human
+ * dispositions that, in the web acceptance panel). The crossing must belong to
+ * the task this session is bound to; the binding is how the target task is
+ * resolved, so run it inside a session attached via `lumo session attach`.
+ */
+async function crossingExplain(crossingId, options = {}) {
+    if (!crossingId || crossingId.trim() === '') {
+        console.error('Error: a crossing id is required: lumo crossing explain <id> --note "…"');
+        return 1;
+    }
+    const note = options.note?.trim();
+    if (!note) {
+        console.error('Error: --note "<text>" is required (the explanation to record).');
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    const base = (0, api_1.trimTrailingSlash)((0, api_1.resolveAuthedApiUrl)(creds.apiUrl));
+    const headers = {
+        Authorization: `Bearer ${creds.token}`,
+    };
+    const sessionId = process.env.CLAUDE_CODE_SESSION_ID;
+    if (sessionId)
+        headers['X-Lumo-Session-Id'] = sessionId;
+    // The crossing is addressed by id, but the route is task-scoped — resolve the
+    // bound task from the session so the server can verify the crossing is on it.
+    if (!sessionId) {
+        console.error('Error: $CLAUDE_CODE_SESSION_ID is not set — run inside a session bound via `lumo session attach <LUM-N>`.');
+        return 1;
+    }
+    let bound;
+    try {
+        const res = await fetch(`${base}/api/sessions/${encodeURIComponent(sessionId)}`, { headers });
+        bound = res.ok
+            ? (await res.json())
+            : null;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API (${msg})`);
+        return 1;
+    }
+    if (!bound?.taskIdentifier) {
+        console.error('Error: this session is not bound to a task. Run `lumo session attach <LUM-N>` first.');
+        return 1;
+    }
+    const taskId = bound.taskIdentifier;
+    let res;
+    try {
+        res = await fetch(`${base}/api/tasks/${encodeURIComponent(taskId)}/boundary-crossings/${encodeURIComponent(crossingId)}/explain`, {
+            method: 'POST',
+            headers: { ...headers, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ note }),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API (${msg})`);
+        return 1;
+    }
+    if (res.status === 401) {
+        console.error('Error: API key invalid or revoked. Run `lumo auth login`.');
+        return 1;
+    }
+    if (!res.ok) {
+        const errBody = (await res.json().catch(() => null));
+        const detail = errBody && typeof errBody.error === 'string'
+            ? (0, sanitize_1.sanitizeField)(errBody.error)
+            : '';
+        console.error(`Error: explanation rejected (HTTP ${res.status})${detail ? ` — ${detail}` : ''}`);
+        return 1;
+    }
+    const outcome = (await res.json());
+    process.stdout.write(`✓ Recorded an explanation on crossing ${(0, sanitize_1.sanitizeField)(outcome.crossingId)}.\n` +
+        '  This is an append-only note for the human reviewer — it does not clear ' +
+        'the crossing or unblock Done.\n');
+    return;
+}

package/dist/cli/src/index.js

@@ -50,6 +50,7 @@ const next_1 = require("./commands/next");
 const cost_1 = require("./commands/cost");
 const verify_1 = require("./commands/verify");
 const verdict_1 = require("./commands/verdict");
+const crossing_explain_1 = require("./commands/crossing-explain");
 const task_context_1 = require("./commands/task-context");
 const task_create_1 = require("./commands/task-create");
 const task_update_1 = require("./commands/task-update");
@@ -230,6 +231,14 @@ program
     .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');
+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)));
 program
     .command('next')
     .description('Recommend the next task(s) to work on, ranked by priority, active sprint, and due date. Prints top N (default 3); pick one and run `session attach` + `task context`.')

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

@@ -79,9 +79,17 @@ _now = new Date()) {
     if (path === 'pre-tool-use') {
         if (responseBody == null || typeof responseBody !== 'object')
             return [];
-        const warning = responseBody
-            .collisionWarning;
-        if (typeof warning !== 'string' || warning === '')
+        const body = responseBody;
+        // Two independent PreToolUse signals (LUM-150 collision, LUM-542 crossing
+        // reminder) share one additionalContext block when both are present.
+        const parts = [];
+        if (typeof body.collisionWarning === 'string' &&
+            body.collisionWarning !== '')
+            parts.push(body.collisionWarning);
+        if (typeof body.crossingReminder === 'string' &&
+            body.crossingReminder !== '')
+            parts.push(body.crossingReminder);
+        if (parts.length === 0)
             return [];
         return [
             JSON.stringify({
@@ -89,7 +97,7 @@ _now = new Date()) {
                     hookEventName: 'PreToolUse',
                     // Server-built text routed back to stdout — sanitize untrusted free
                     // text before Claude Code consumes it (ANSI/control-char injection).
-                    additionalContext: (0, sanitize_1.sanitizeField)(warning),
+                    additionalContext: (0, sanitize_1.sanitizeField)(parts.join('\n\n')),
                 },
             }),
         ];

package/package.json

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