@lumoai/cli 1.37.0 → 1.39.0

package/assets/skill/SKILL.md

@@ -82,10 +82,11 @@ 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)
 
-- `lumo cost [--task <id>|--session <id>|--since <date>] [--by tool|model|member|session] [--json]` — per-operation (per-tool) token cost read-out. Attributes each model step's token delta to the tool(s) it ran (per-step where POST_TOOL_BATCH data exists, per-turn fallback otherwise), output vs cache_read shown separately, plus a per-step coverage line and a "heuristic" note (parallel tools split a step's tokens evenly). Scope is mutually exclusive: `--task` (one task) / `--session` (one Claude Code session) / `--since` (workspace window); default = workspace last-30-days. `--by` only changes which grouping is the headline (the others are still printed when non-trivial). For the per-task Top-5 inline, see `lumo task lineage`.
+- `lumo cost [--task <id>|--session <id>|--since <date>] [--by tool|model|member|session] [--json]` — per-operation (per-tool) token cost read-out. Attributes each model step's token delta to the tool(s) it ran (per-step where POST_TOOL_BATCH data exists, per-turn fallback otherwise); each ranking row breaks the cost into output / input / cache_create / cache_read columns plus total, with a per-step coverage line and a "heuristic" note (parallel tools split a step's tokens evenly; output and cache_read attribute cleanly per step while input and cache_create are bursty, so per-tool figures for those two are coarse). Scope is mutually exclusive: `--task` (one task) / `--session` (one Claude Code session) / `--since` (workspace window); default = workspace last-30-days. `--by` only changes which grouping is the headline (the others are still printed when non-trivial). For the per-task Top-5 inline, see `lumo task lineage`.
 
 **Artifacts & Figma** — see [artifacts-figma.md](references/artifacts-figma.md)
 

package/assets/skill/references/task-context.md

@@ -187,8 +187,11 @@ Per-operation (per-tool) token cost read-out. Where `task lineage` answers
 token delta to the tool(s) that ran in it — **per-step** where the
 `POST_TOOL_BATCH` hook captured the tool list, **per-turn fallback** otherwise
 (a parallel-tool step splits its tokens evenly across the tools, hence the
-"heuristic" note). `output` (generation) and `cache_read` (~95%, structural —
-turns × context) are shown in separate columns.
+"heuristic" note). Each ranking row breaks the cost into four columns —
+`output` (generation), `input`, `cache_create`, `cache_read` (~95%, structural —
+turns × context) — plus `total`. `output` and `cache_read` attribute cleanly
+per step; `input` and `cache_create` are bursty (prompt + cache checkpoints), so
+their per-tool figures are coarser.
 
 ```bash
 lumo cost --task LUM-42

package/dist/cli/src/commands/cost.js

@@ -10,15 +10,19 @@ function groupThousands(value) {
         .toString()
         .replace(/\B(?=(\d{3})+(?!\d))/g, ',');
 }
+/** Render one ranking row: label + the four token categories + total, aligned. */
+function rankRow(label, output, input, cacheCreate, cacheRead, total) {
+    return `  ${label.slice(0, 20).padEnd(20)}  ${output.padStart(10)}  ${input.padStart(10)}  ${cacheCreate.padStart(12)}  ${cacheRead.padStart(12)}  ${total.padStart(12)}`;
+}
 function rankTable(title, rows) {
     if (rows.length === 0)
         return '';
     const lines = [
         title,
-        '  operation              output      cache_read       total',
+        rankRow('operation', 'output', 'input', 'cache_create', 'cache_read', 'total'),
     ];
     for (const r of rows.slice(0, 20)) {
-        lines.push(`  ${r.label.slice(0, 20).padEnd(20)}  ${groupThousands(r.output).padStart(10)}  ${groupThousands(r.cacheRead).padStart(12)}  ${groupThousands(r.total).padStart(12)}`);
+        lines.push(rankRow(r.label, groupThousands(r.output), groupThousands(r.input), groupThousands(r.cacheCreation), groupThousands(r.cacheRead), groupThousands(r.total)));
     }
     return lines.join('\n');
 }
@@ -39,7 +43,7 @@ function formatOperationCost(data, by) {
         : `${Math.round(data.coverage.perStepPct * 100)}%`;
     const out = [];
     out.push(`Per-operation cost — ${data.scope.kind} ${data.scope.label}`);
-    out.push(`Total: output ${groupThousands(data.grandTotal.output)} · cache_read ${groupThousands(data.grandTotal.cacheRead)} · all ${groupThousands(data.grandTotal.total)} tokens`);
+    out.push(`Total: output ${groupThousands(data.grandTotal.output)} · input ${groupThousands(data.grandTotal.input)} · cache_create ${groupThousands(data.grandTotal.cacheCreation)} · cache_read ${groupThousands(data.grandTotal.cacheRead)} · all ${groupThousands(data.grandTotal.total)} tokens`);
     out.push(`Per-step attribution: ${pct} of ${data.coverage.toolTurns} tool-using turns (rest fall back to per-turn split)`);
     out.push('');
     out.push(rankTable(`By ${by}:`, primary));
@@ -52,7 +56,7 @@ function formatOperationCost(data, by) {
     if (by !== 'session' && data.bySession.length > 1)
         out.push('\n' + rankTable('By session:', data.bySession));
     out.push('');
-    out.push('Note: token→tool attribution is heuristic — a model step that fires several tools in parallel splits its tokens evenly across them; cache_read (~95%) is structural (turns × context), shown alongside output (generation).');
+    out.push('Note: token→tool attribution is heuristic — a model step that fires several tools in parallel splits its tokens evenly across them. output (generation) and cache_read (~95%, structural — turns × context) attribute cleanly per step; input and cache_create are bursty (prompt + cache checkpoints) and per-tool figures for those two are coarse.');
     return out.join('\n');
 }
 async function cost(opts) {

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.37.0",
+  "version": "1.39.0",
   "description": "Lumo CLI — manage tasks and sessions from the terminal",
   "license": "MIT",
   "author": "cli@uselumo.ai",