@bli-cockpit/cli 0.2.292 → 0.2.293

package/dist/adapters/raw-evidence-transcript-file.js

@@ -56,11 +56,27 @@ export async function collectOneEvidenceFile(collection, options) {
     }
     // BLI-3936: stat BEFORE the read. The same stamp, taken again after the work, proves the file
     // did not move underneath it; only then is the result remembered.
-    const stamp = await statSourceForMemo(options.filePath);
+    const stamp = options.sourceProvider ? null : await statSourceForMemo(options.filePath);
     const recipe = prepareRecipe({ imageMode: collection.budget.images?.mode, kind: options.kind });
     if (await reuseUnchangedTranscript(collection, options, names, stamp, recipe))
         return true;
-    const read = await readEvidenceFileWithinCap(options.filePath, options.maxFileBytes, streamMinBytesFor(collection, options.kind));
+    let read;
+    try {
+        read = options.sourceProvider
+            ? { status: "ok", ...await options.sourceProvider() }
+            : await readEvidenceFileWithinCap(options.filePath, options.maxFileBytes, streamMinBytesFor(collection, options.kind));
+    }
+    catch (error) {
+        if (error instanceof TranscriptTooLargeError) {
+            markCapApplied(collection, options.kind, "max_file_bytes");
+            return skip("file_too_large");
+        }
+        const reason = error instanceof TranscriptReadError ? `file_read_failed:${error.stage}` : "file_read_failed";
+        console.error("[raw-evidence] revision source unavailable", JSON.stringify({ reason, ...describeError(error) }));
+        return skip(reason);
+    }
+    if (read.status === "ok" && options.maxFileBytes && read.byteLength > options.maxFileBytes)
+        read = { status: "too_large" };
     if (read.status === "read_failed")
         return skip("file_read_failed");
     if (read.status === "too_large") {
@@ -80,8 +96,15 @@ export async function collectOneEvidenceFile(collection, options) {
     }
     catch (error) {
         // BLI-23317: a streamed or fallback read that fails ends exactly as a whole-file read that failed.
-        if (error instanceof TranscriptReadError)
-            return skip("file_read_failed");
+        if (error instanceof TranscriptReadError) {
+            const deferred = error.stage === "composite_staging_declined" && error.underlying instanceof Error ? error.underlying.message : null;
+            if (deferred && /^(deferred_(byte|object)_budget|staging_deferred:[a-z_]+)$/.test(deferred)) {
+                markBudgetCapApplied(collection, deferred);
+                return skip(deferred);
+            }
+            const detail = options.sourceProvider ? `:${error.stage}` : "";
+            return skip(`file_read_failed${detail}`);
+        }
         if (error instanceof TranscriptTooLargeError) {
             markCapApplied(collection, options.kind, "max_file_bytes");
             return skip("file_too_large");

package/dist/adapters/raw-evidence-transcript-stream.js

@@ -12,6 +12,8 @@
  *    read gives (`file_read_failed`, `file_too_large`), never a shorter file.
  */
 import fs from "node:fs/promises";
+import { copyLinesStream } from "../slim/keep-line-copy.js";
+import { openStagedOutput } from "./staged-output.js";
 import { modeDropsImages } from "@bli-cockpit/telemetry-core";
 import { describeError } from "../health-detail.js";
 import { TranscriptNotStreamable, TranscriptReadError, TranscriptTooLargeError, } from "./transcript-text-stream.js";
@@ -32,11 +34,13 @@ export function volatilityOf(mode, prepared) {
 }
 export async function streamTranscriptBody(session, agent, file) {
     if (!session?.prepareTranscriptFile || !agent) {
+        if (file.openSource)
+            return streamCompositeWithoutImages(file);
         console.error(TAG + " streamed read not available, reading the transcript whole", JSON.stringify({ reason: "stream_unavailable", kind: file.kind }));
         return null;
     }
     try {
-        const prepared = await session.prepareTranscriptFile({ filePath: file.filePath, source: agent, sessionId: file.sessionId, maxFileBytes: file.maxFileBytes, stageDir: file.stageDir, omitText: file.stageDir !== undefined, ...(file.provenance ? { provenance: file.provenance } : {}) });
+        const prepared = await session.prepareTranscriptFile({ filePath: file.filePath, ...(file.openSource ? { openSource: file.openSource } : {}), source: agent, sessionId: file.sessionId, maxFileBytes: file.maxFileBytes, stageDir: file.stageDir, omitText: file.stageDir !== undefined, ...(file.provenance ? { provenance: file.provenance } : {}) });
         const { volatile, pendingImages } = volatilityOf(session.mode, prepared);
         console.error(TAG + " transcript streamed through image swap and slim", JSON.stringify({ kind: file.kind, mode: session.mode, byte_size: prepared.readBytes, changed: prepared.changed, images: prepared.imageCount, volatile, staged_bytes: prepared.staged?.byteLength ?? null }));
         // BLI-23344: with a spool the text is not read back; the sanitizer reads the spool line by line.
@@ -45,12 +49,18 @@ export async function streamTranscriptBody(session, agent, file) {
     catch (error) {
         if (error instanceof TranscriptReadError || error instanceof TranscriptTooLargeError)
             throw error;
+        if (file.openSource) {
+            console.error(TAG + " composite revision remains pending", JSON.stringify({ reason: "composite_prepare_failed", kind: file.kind, ...describeError(error) }));
+            throw new TranscriptReadError(error instanceof TranscriptNotStreamable ? error.reason : "composite_prepare_failed", error);
+        }
         console.error(TAG + " streamed read set aside, reading the transcript whole", JSON.stringify({ reason: error instanceof TranscriptNotStreamable ? error.reason : "stream_step_failed", kind: file.kind, ...(error instanceof TranscriptNotStreamable ? {} : describeError(error)) }));
         return null;
     }
 }
 /** The whole-file read the streamed path falls back to: same failures, same labels, as the reader that did not stream. */
 export async function readTranscriptWhole(file) {
+    if (file.openSource)
+        throw new TranscriptReadError("composite_buffering_refused", new Error("composite_buffering_refused"));
     let bytes;
     try {
         bytes = await fs.readFile(file.filePath);
@@ -62,4 +72,26 @@ export async function readTranscriptWhole(file) {
     if (file.maxFileBytes && bytes.byteLength > file.maxFileBytes)
         throw new TranscriptTooLargeError(file.maxFileBytes);
     return bytes;
+}
+/** Keep mode when image preparation is unavailable: same spool/mask/ack, no representative read or whole buffer. */
+async function streamCompositeWithoutImages(file) {
+    if (!file.stageDir)
+        throw new TranscriptReadError("composite_staging_unavailable", new Error("composite_staging_unavailable"));
+    const source = await file.openSource();
+    let writer;
+    try {
+        writer = await openStagedOutput(file.stageDir);
+        await copyLinesStream(source.lines(), writer);
+        await source.verifyUnchanged();
+        const staged = await writer.finish();
+        console.error(TAG + " composite revision kept without image preparation", JSON.stringify({ reason: "composite_images_unavailable_kept", kind: file.kind, byte_size: source.length }));
+        return { held: { text: null, exactBytes: null, staged }, volatile: true, pendingImages: null, readBytes: source.length };
+    }
+    catch (error) {
+        await writer?.abandon();
+        throw new TranscriptReadError(error instanceof TranscriptNotStreamable ? error.reason : "composite_prepare_failed", error);
+    }
+    finally {
+        await source.close();
+    }
 }

package/dist/collection-scope.js

@@ -146,6 +146,8 @@ export function cwdInsideRoots(cwd, roots) {
  * it cannot be proven inside, so it is withheld.
  */
 export function sessionInsideRoots(result, roots) {
+    if (result.local_cwds)
+        return result.local_cwds.length > 0 && result.local_cwds.every(cwd => cwdInsideRoots(cwd, roots) || Boolean(result.worktree && cwdInsideRoots(cwd, [result.worktree.repo_root])));
     if (cwdInsideRoots(result.local_cwd, roots))
         return true;
     return Boolean(result.worktree && cwdInsideRoots(result.local_cwd, [result.worktree.repo_root]));

package/dist/commands/backfill-checkpoint.js

@@ -37,7 +37,8 @@ export async function recordBackfillDurableSessionPointers(options) {
             // delivery, so a real pointer replaces it and the mark clears.
             // BLI-11119: an entry the cursor itself knows is `stubbed` counts too.
             const replacesStub = Boolean(prior?.stub_reoffer || prior?.stubbed) && prior?.uploaded_object_key !== objectKey;
-            if (!objectKey || !prior || (prior.uploaded_object_key && !replacesStub))
+            const replacesRevision = candidate.source === "codex" && prior?.uploaded_source_revision !== candidate.content_hash_sha256;
+            if (!objectKey || (prior?.uploaded_object_key && !replacesStub && !replacesRevision))
                 continue;
             if (replacesStub && !isRedactionStubObjectKey(objectKey))
                 stubsReplaced += 1;
@@ -61,6 +62,7 @@ function deliveredCursorEntry(prior, candidate, objectKey, now) {
     const entry = {
         ...prior,
         file_hash_sha256: candidate.content_hash_sha256,
+        uploaded_source_revision: isRedactionStubObjectKey(objectKey) ? prior?.uploaded_source_revision ?? null : candidate.content_hash_sha256,
         file_mtime_ms: candidate.session_file_mtime_ms,
         byte_size: candidate.byte_size,
         // The whole file was delivered, so the incremental reader starts at its end.

package/dist/commands/backfill-history-scan.js

@@ -0,0 +1,38 @@
+/** Keep complete-history rescans separate from candidate selection and cursor policy. */
+import { scanAndAttributeCodexSessions } from "../adapters/codex-attribution.js";
+import { scanAndAttributeClaudeSessions } from "../adapters/claude-attribution.js";
+/**
+ * The adapter's own limit is a memory guard, not permission to silently leave
+ * history undiscovered. When it fires, re-scan the exact discovered population
+ * so a user-facing `--max-files` cap can resume from a truthful ordering.
+ */
+export async function scanCodexHistory(request, sessionsDirs, scanLimit) {
+    const scan = (limit) => scanAndAttributeCodexSessions({
+        sessionsDirs,
+        worktrees: request.worktrees,
+        now: request.now,
+        sinceMinutes: request.window.since_minutes,
+        limit,
+        collectionRoots: request.collectionRoots,
+    });
+    const firstPass = await scan(scanLimit);
+    if (!firstPass.session_limit_applied)
+        return firstPass;
+    return scan(Math.max(scanLimit + 1, firstPass.discovered_file_count));
+}
+/** Same rule for the Claude store: a capped first pass is rescanned in full. */
+export async function scanClaudeHistory(request, projectsDirs, scanLimit) {
+    const scan = (limit) => scanAndAttributeClaudeSessions({
+        projectsDir: projectsDirs[0],
+        projectsDirs,
+        worktrees: request.worktrees,
+        now: request.now,
+        sinceMinutes: request.window.since_minutes,
+        limit,
+        collectionRoots: request.collectionRoots,
+    });
+    const firstPass = await scan(scanLimit);
+    if (!firstPass.session_limit_applied)
+        return firstPass;
+    return scan(Math.max(scanLimit + 1, firstPass.discovered_session_count));
+}

package/dist/commands/backfill-issues.js

@@ -29,36 +29,33 @@ import { candidateCursorKey } from "./backfill-candidates.js";
 export async function backfillScanIssues(options) {
     const issues = [];
     if (options.codexAttribution) {
-        await addCodexStoreScanIssues(issues, options.codexAttribution, options.codexSessionDirs);
+        await addCodexStoreScanIssues(issues, options.codexAttribution);
     }
     if (options.claudeAttribution) {
-        await addClaudeStoreScanIssues(issues, options.claudeAttribution, options.claudeProjectsDir, options.candidates);
+        await addClaudeStoreScanIssues(issues, options.claudeAttribution, options.candidates);
     }
     addCandidateScanIssues(issues, options.candidates, options.omittedCandidateCount);
     sortScanIssuesByPriority(issues);
     return issues;
 }
 /** What the archived Codex store could not tell us — every one of these hides history. */
-async function addCodexStoreScanIssues(issues, codexAttribution, codexSessionDirs) {
+async function addCodexStoreScanIssues(issues, codexAttribution) {
     countScanIssue(issues, "codex_session_limit_applied", codexAttribution.session_limit_applied
         ? Math.max(1, codexAttribution.discovered_file_count -
             codexAttribution.scanned_file_count)
         : 0, "global");
-    // A session directory that simply does not exist on this machine is not a
-    // read failure; subtract those before reporting one.
-    const missingTopLevelDirs = (await Promise.all(codexSessionDirs.map(isMissingPath))).filter(Boolean).length;
-    countScanIssue(issues, "codex_directory_read_failed", Math.max(0, codexAttribution.directory_read_failed_count - missingTopLevelDirs), "global");
+    // The reader already excludes ENOENT. Subtracting absent default roots
+    // here would erase a failure in another configured home or T3 discovery.
+    countScanIssue(issues, "codex_directory_read_failed", codexAttribution.directory_read_failed_count, "global");
     countScanIssue(issues, "codex_session_stat_failed", codexAttribution.stat_failed_count, "global");
 }
 /** The same census for the Claude store, which also has sidecars to account for. */
-async function addClaudeStoreScanIssues(issues, claudeAttribution, claudeProjectsDir, candidates) {
+async function addClaudeStoreScanIssues(issues, claudeAttribution, candidates) {
     countScanIssue(issues, "claude_session_limit_applied", claudeAttribution.session_limit_applied
         ? Math.max(1, claudeAttribution.discovered_session_count -
             claudeAttribution.scanned_session_count)
         : 0, "global");
-    const projectsDirMissing = await isMissingPath(claudeProjectsDir);
-    countScanIssue(issues, "claude_project_dir_read_failed", Math.max(0, claudeAttribution.project_dir_read_failed_count -
-        (projectsDirMissing ? 1 : 0)), "global");
+    countScanIssue(issues, "claude_project_dir_read_failed", claudeAttribution.project_dir_read_failed_count, "global");
     countScanIssue(issues, "claude_session_stat_failed", claudeAttribution.session_stat_failed_count, "global");
     countScanIssue(issues, "claude_sidecar_stat_failed", claudeAttribution.sidecar_stat_failed_count, "global");
     countScanIssue(issues, "claude_sidecar_dir_read_failed", await countUnreadableClaudeSidecarDirs(candidates), "global");
@@ -151,15 +148,6 @@ async function countUnreadableClaudeSidecarDirs(candidates) {
     }
     return unreadable;
 }
-async function isMissingPath(filePath) {
-    try {
-        await fs.stat(filePath);
-        return false;
-    }
-    catch (error) {
-        return isMissingFsError(error);
-    }
-}
 function isMissingFsError(error) {
     if (!error || typeof error !== "object")
         return false;

package/dist/commands/backfill-scan.js

@@ -1,3 +1,5 @@
+import { scanCodexHistory, scanClaudeHistory } from "./backfill-history-scan.js";
+import { nativeSessionRoots } from "../native-session-roots.js";
 /**
  * SCAN: read both archived session stores and turn them into the candidates
  * this run will consider, then census what could not be accounted for.
@@ -9,9 +11,6 @@
  * on what was missed before what merely arrived.
  */
 import os from "node:os";
-import path from "node:path";
-import { scanAndAttributeClaudeSessions, } from "../adapters/claude-attribution.js";
-import { defaultCodexSessionDirs, scanAndAttributeCodexSessions, } from "../adapters/codex-attribution.js";
 import { emptyBackfillCursorState, prepareBackfillCursorForScope, readBackfillCursor, } from "../cursors/backfill-cursor.js";
 import { CLAUDE_CURSOR_FILENAME, readRawEvidenceCursor, } from "../cursors/raw-evidence-cursor.js";
 import { liveWindowMsFor, scopeBackfillCandidates } from "./backfill-live-window.js";
@@ -136,10 +135,15 @@ async function auditScannedCandidates(scan, discoveryIncompleteReasons) {
  */
 async function scanBackfillSessions(options) {
     const scanLimit = options.command.maxFiles ?? 10_000;
-    const codexSessionDirs = defaultCodexSessionDirs(options.homeDir);
-    const claudeProjectsDir = path.join(options.homeDir, ".claude", "projects");
+    const { codex: codexSessionDirs, claudeProjects: claudeProjectsDir, claudeProjectDirs, discoveryFailed } = nativeSessionRoots(options.homeDir);
     const codexScanned = options.sources.includes("codex") ? await scanCodexHistory(options, codexSessionDirs, scanLimit) : null;
-    const claudeScanned = options.sources.includes("claude_code") ? await scanClaudeHistory(options, claudeProjectsDir, scanLimit) : null;
+    const claudeScanned = options.sources.includes("claude_code") ? await scanClaudeHistory(options, claudeProjectDirs, scanLimit) : null;
+    if (discoveryFailed) {
+        if (codexScanned)
+            codexScanned.directory_read_failed_count += 1;
+        if (claudeScanned)
+            claudeScanned.project_dir_read_failed_count += 1;
+    }
     // BLI-23590 withholds sessions outside the approved roots first; BLI-23478 then keeps drawer sessions home.
     const scoped = scopeHistoryScans(options, codexScanned, claudeScanned);
     const { codexAttribution, claudeAttribution } = shelveBackfillScan(scoped.codex, scoped.claude, options.shelfDecision);
@@ -155,6 +159,13 @@ async function scanBackfillSessions(options) {
         sinceMinutes: options.window.since_minutes,
     });
     const liveWindowMs = liveWindowMsFor(options.command);
+    const durableCodex = await readRawEvidenceCursor(getCollectorRuntimePaths(options.homeDir));
+    for (const c of scanned) {
+        const prior = durableCodex.sessions[c.session_id];
+        if (c.source === "codex" && (c.segment_paths || prior?.uploaded_source_revision) &&
+            prior?.uploaded_source_revision !== c.content_hash_sha256)
+            options.pointerlessTerminalSessions.codex.add(c.session_id);
+    }
     const selection = selectBackfillCandidates({
         scanned,
         cursor: options.cursor,
@@ -188,40 +199,6 @@ async function scanBackfillSessions(options) {
         live_window_ms: liveWindowMs,
     };
 }
-/**
- * The adapter's own limit is a memory guard, not permission to silently leave
- * history undiscovered. When it fires, re-scan the exact discovered population
- * so a user-facing `--max-files` cap can resume from a truthful ordering.
- */
-async function scanCodexHistory(request, sessionsDirs, scanLimit) {
-    const scan = (limit) => scanAndAttributeCodexSessions({
-        sessionsDirs,
-        worktrees: request.worktrees,
-        now: request.now,
-        sinceMinutes: request.window.since_minutes,
-        limit,
-        collectionRoots: request.collectionRoots,
-    });
-    const firstPass = await scan(scanLimit);
-    if (!firstPass.session_limit_applied)
-        return firstPass;
-    return scan(Math.max(scanLimit + 1, firstPass.discovered_file_count));
-}
-/** Same rule for the Claude store: a capped first pass is rescanned in full. */
-async function scanClaudeHistory(request, projectsDir, scanLimit) {
-    const scan = (limit) => scanAndAttributeClaudeSessions({
-        projectsDir,
-        worktrees: request.worktrees,
-        now: request.now,
-        sinceMinutes: request.window.since_minutes,
-        limit,
-        collectionRoots: request.collectionRoots,
-    });
-    const firstPass = await scan(scanLimit);
-    if (!firstPass.session_limit_applied)
-        return firstPass;
-    return scan(Math.max(scanLimit + 1, firstPass.discovered_session_count));
-}
 /**
  * Which scanned sessions this run will actually work on. A session is in play
  * if the cursor has not passed it, or if it is a terminal session that never
@@ -291,6 +268,7 @@ function normalizeCodexCandidate(result) {
     return {
         source: "codex",
         session_id: result.codex_session_id,
+        ...(result.segment_paths ? { segment_paths: result.segment_paths } : {}),
         session_id_source: result.session_id_source,
         file_path: result.file_path,
         state: result.state,

package/dist/commands/backfill-upload.js

@@ -231,6 +231,7 @@ function backfillBatchSyncOptions(options) {
             .map((candidate) => ({
             local_path: candidate.file_path,
             codex_session_id: candidate.session_id,
+            ...(candidate.segment_paths ? { segment_paths: candidate.segment_paths, revision_hash: candidate.content_hash_sha256 ?? undefined, revision_bytes: candidate.byte_size } : {}),
         })),
         codexAttributionScan: options.codexAttribution ?? undefined,
         claudeSessionFiles: options.batch.candidates

package/dist/commands/codex-revision-facts.js

@@ -0,0 +1,64 @@
+/** Compare a composite revision with the SAME line/slim/redaction rules as upload. No raw bundle or network. */
+import { createHash } from "node:crypto";
+import { findEmbeddedImages, modeDropsImages, replaceImagesWithMarkers } from "@bli-cockpit/telemetry-core";
+import { imageStateKey } from "../image-description-state.js";
+import { openCodexSessionRevision } from "../adapters/codex-session-revision.js";
+import { createSlimmer } from "../slim/slim-transcript.js";
+import { scanLines, decideLinePlan, writeLinePlan } from "../adapters/raw-evidence-sanitize-lines.js";
+export function codexRevisionFacts(paths, mode, describedKeys, slimAware) {
+    const form = async (drop) => {
+        const source = await openCodexSessionRevision(paths);
+        try {
+            const lines = { async *lines() {
+                    const slimmer = createSlimmer("codex");
+                    for await (const line of source.lines()) {
+                        if (line.start === source.length)
+                            continue;
+                        let text = new TextDecoder("utf-8", { fatal: true }).decode(line.bytes);
+                        if (drop) {
+                            const images = findEmbeddedImages(text);
+                            text = replaceImagesWithMarkers(text, images, image => describedKeys.has(imageStateKey(image.sha256))).text;
+                            text = slimmer.slimLine(text);
+                        }
+                        yield text + "\n";
+                    }
+                } };
+            const options = { redactedFields: ["codex_jsonl.body"], secretLikeFileName: false };
+            const plan = decideLinePlan(await scanLines(lines, options), options);
+            if (plan.kind === "whole_mask" || plan.kind === "guard_line")
+                return null;
+            const hash = createHash("sha256");
+            let byte_size = 0;
+            const write = async (text) => { hash.update(text); byte_size += Buffer.byteLength(text); };
+            if (plan.kind === "clean") {
+                for await (const line of lines.lines())
+                    await write(line);
+            }
+            else
+                await writeLinePlan(lines, plan, options, write);
+            await source.verifyUnchanged();
+            return { sha256: hash.digest("hex"), byte_size };
+        }
+        finally {
+            await source.close();
+        }
+    };
+    let full, slim;
+    return {
+        slimAware,
+        async rawSha256() { const source = await openCodexSessionRevision(paths); try {
+            return source.sha256;
+        }
+        finally {
+            await source.close();
+        } },
+        wholeForm: () => full ??= form(false),
+        sanitized: () => modeDropsImages(mode) ? slim ??= form(true) : full ??= form(false),
+        async slimSplit() {
+            if (!slimAware)
+                return null;
+            const [a, b] = await Promise.all([full ??= form(false), slim ??= form(true)]);
+            return a && b && a.sha256 !== b.sha256 ? { full: a, slim: b } : null;
+        },
+    };
+}

package/dist/commands/local-args-notes-targets.js

@@ -0,0 +1,35 @@
+/**
+ * The `--to` readers of `cockpit notes`: `move --to "<shelf>"` and, since BLI-24437,
+ * `correct <id> --from "<misheard>" --to "<right>" [--transcript]`. Sibling of
+ * `local-args-tower-notes.ts`, which calls both; split out so that file stays a table of contents.
+ */
+import { optionalNonEmpty } from "./local-arg-values.js";
+export function readNotesShelfTarget(action, values) {
+    const to = optionalNonEmpty(values.flags.get("--to"));
+    const clearShelf = values.booleans.has("--clear-shelf");
+    if (action !== "move")
+        return { to, clearShelf };
+    if (to && clearShelf) {
+        throw new Error("notes move accepts either --to or --clear-shelf, not both.");
+    }
+    if (!to && !clearShelf && !values.flags.get("--folder")) {
+        throw new Error('notes move needs --to "<shelf>", --clear-shelf, or --folder "<path>".');
+    }
+    return { to, clearShelf };
+}
+/** BLI-24437: `correct` needs both terms; `--from` and `--transcript` mean nothing on any other verb. */
+export function readNotesCorrection(action, values) {
+    const from = optionalNonEmpty(values.flags.get("--from"));
+    const transcript = values.booleans.has("--transcript");
+    if (action !== "correct") {
+        if (from !== undefined)
+            throw new Error("--from belongs to `cockpit notes correct <note-id> --from <term> --to <term>`.");
+        if (transcript)
+            throw new Error("--transcript belongs to `cockpit notes correct <note-id> --from <term> --to <term> --transcript`.");
+        return {};
+    }
+    if (!from || !optionalNonEmpty(values.flags.get("--to"))) {
+        throw new Error('notes correct needs --from "<misheard term>" and --to "<right term>".');
+    }
+    return { from, ...(transcript ? { transcript: true } : {}) };
+}

package/dist/commands/local-args-tower-notes.js

@@ -7,6 +7,7 @@
  * address they have always had.
  */
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
+import { readNotesCorrection, readNotesShelfTarget } from "./local-args-notes-targets.js";
 /**
  * The notetakers `cockpit notes connect` will actually seal a key for
  * (BLI-4391). It mirrors `CONNECTABLE_NOTES_PROVIDERS` in the dashboard, and
@@ -34,7 +35,7 @@ const NOTES_ACTIONS = new Set([
     "upload",
     "paste",
     "share",
-    "unshare",
+    "unshare", "correct",
     "summarize",
     "move",
     "place",
@@ -61,7 +62,7 @@ const NOTES_ACTIONS = new Set([
 const NOTES_ACTIONS_NEEDING_A_NOTE = new Set([
     "show",
     "share",
-    "unshare",
+    "unshare", "correct",
     "summarize",
     "move",
     "place",
@@ -82,7 +83,7 @@ const NOTES_ALLOWED_FLAGS = [
     "--file",
     "--name",
     "--exclude",
-    "--to",
+    "--to", "--from", "--transcript", // BLI-24437: `correct <id> --from <term> --to <term> [--transcript]`
     "--folder",
     "--clear-shelf",
     "--apply",
@@ -122,7 +123,7 @@ const NOTES_VALUE_FLAGS = [
     "--file",
     "--name",
     "--exclude",
-    "--to",
+    "--to", "--from",
     "--folder",
     "--series",
     "--kind",
@@ -180,6 +181,7 @@ export function parseNotesArgs(args) {
         exclude: optionalNonEmpty(values.flags.get("--exclude")),
         ...(to ? { to } : {}),
         ...(clearShelf ? { clearShelf } : {}),
+        ...readNotesCorrection(action, values),
         // BLI-4058. `place` says where a note belongs; only `--apply` moves it.
         ...(values.booleans.has("--apply") ? { apply: true } : {}),
         series: optionalNonEmpty(values.flags.get("--series")),
@@ -201,7 +203,7 @@ function readNotesAction(first) {
     // almost always wants — same reasoning as bare `cockpit` running convergence.
     const action = (first === undefined ? "list" : first);
     if (!NOTES_ACTIONS.has(action)) {
-        throw new Error(`Unknown notes command: ${first}. Try list, show, shelf, shelves, upload, paste, share, unshare, summarize, move, place, accounts, connect, detach, sync, sync-status, recordings, recording, webhook, granola-status, transcription-stats, or review (and record start|stop|status|cancel, app install|uninstall|status).`);
+        throw new Error(`Unknown notes command: ${first}. Try list, show, shelf, shelves, upload, paste, share, unshare, correct, summarize, move, place, accounts, connect, detach, sync, sync-status, recordings, recording, webhook, granola-status, transcription-stats, or review (and record start|stop|status|cancel, app install|uninstall|status).`);
     }
     return action;
 }
@@ -368,19 +370,6 @@ function readNotesPaths(action, rest) {
     }
     return undefined;
 }
-function readNotesShelfTarget(action, values) {
-    const to = optionalNonEmpty(values.flags.get("--to"));
-    const clearShelf = values.booleans.has("--clear-shelf");
-    if (action !== "move")
-        return { to, clearShelf };
-    if (to && clearShelf) {
-        throw new Error("notes move accepts either --to or --clear-shelf, not both.");
-    }
-    if (!to && !clearShelf && !values.flags.get("--folder")) {
-        throw new Error('notes move needs --to "<shelf>", --clear-shelf, or --folder "<path>".');
-    }
-    return { to, clearShelf };
-}
 function readNotesMonth(action, values) {
     const month = optionalNonEmpty(values.flags.get("--month"));
     if (month === undefined)

package/dist/commands/local-help-commands-tower.js

@@ -112,7 +112,7 @@ export const TOWER_COMMAND_HELP = [
             "dm <email> [<email>...] — with several addresses, opens (or re-opens) the group message with exactly those people plus you; the same set always resolves to the same channel. channel <channel> [--json] — the channel's details: name, description, kind, archived, audience (a public channel is everyone in the org, not a member count), source workspace label (where it came from; it grants no access), whether you can manage it, and whether you hid it. channel <channel> --rename <name> | --describe <text> | --archive | --unarchive — changes it (one update; --rename and --describe can go together). Only the person who made the channel, its owners and its moderators can; anyone else is refused channel_manage_refused, a name in use channel_name_taken, a direct message dm_not_editable. Archiving keeps every message and link and stops new posts (channel_archived); unarchive restores posting. members <channel> [--json] — who is in a private channel or a direct message; a public channel says everyone in the org can read it. members <channel> --add <email> | --remove <email> — private channels only, by the same people who can manage it; a removed person's next read is refused. A direct message keeps the people it started with (dm_not_editable): start a new group with `msg dm a@x b@y`. hide <channel> / unhide <channel> — drops a PUBLIC channel from your own sidebar, or puts it back; it changes nothing for anyone else and nothing about reading, search, mentions or notifications. A private channel or direct message is refused hide_not_public.",
             "read <channel> [--limit <n>] [--thread <id>] [--mark-read] — the channel's most recent top-level messages, oldest first; --thread <id> reads one thread's replies instead. The first page also says where the messages come from (for an imported Slack channel: how long ago the archive was checked, or that it is unknown) and where YOUR read line stands. Reading never moves the read line; --mark-read moves it to the newest message shown, and says plainly if that failed.",
             "unread <channel> --from <message-id> — marks that message and everything after it unread, so the web sidebar badge and the NEW MESSAGES line start there. Opening or reading a channel never clears unseen history.",
-            "send <channel> [--thread <id>] [--request-id <uuid>] — posts a message. The content is never accepted on the command line: pipe it in, e.g. `echo \"hello\" | cockpit msg send general`. Every send carries a request id (minted when you give none); retry a send whose answer was lost with the SAME --request-id and the same text and it posts once. The same id with different text is refused request_id_reused, not applied as an edit. send <channel> --file <id> [--file <id>...] — attaches up to 10 ready files (from `msg file upload`) to the message. The text is optional with a file; it is read from stdin only when something is piped in. file upload <channel> <path|-> [--name <name>] — uploads a file of 1 byte to 25 MB straight to storage (reserve, PUT, finalize) and prints its id and state; `-` reads stdin and needs --name. A file is ready, not sent: attach it with `msg send <channel> --file <id>`. file show <id> — the descriptor (state reserved, ready, attached, cancelled or abandoned). file download <id> [--out <path>] — saves the bytes (60-second signed link; never overwrites). file cancel <id> — ends an unattached file and removes its bytes. file list <channel> — your own unsent uploads there, with coverage. A file is readable only by readers of its channel, and only once attached to a live message. Refusals keep the door's reason: file_too_large, file_not_found_or_unreadable, file_not_uploaded, file_not_ready, file_already_attached, file_wrong_channel, storage_unreachable.",
+            "send <channel> [--thread <id>] [--request-id <uuid>] — posts a message. The content is never accepted on the command line: pipe it in, e.g. `echo \"hello\" | cockpit msg send general`. Every send carries a request id (minted when you give none); retry a send whose answer was lost with the SAME --request-id and the same text and it posts once. The same id with different text is refused request_id_reused, not applied as an edit. send <channel> --file <id> [--file <id>...] — attaches up to 10 ready files (from `msg file upload`) to the message. The text is optional with a file; it is read from stdin only when something is piped in. file upload <channel> <path|-> [--name <name>] — uploads a file of 1 byte to 25 MB straight to storage (reserve, PUT, finalize) and prints its id and state; `-` reads stdin and needs --name. A file is ready, not sent: attach it with `msg send <channel> --file <id>`. file show <id> — the descriptor (state reserved, ready, attached, cancelled or abandoned). file download <id> [--out <path>] — saves the bytes (60-second signed link; never overwrites). file cancel <id> — ends an unattached file and removes its bytes. file list <channel> — your own unsent uploads there, with coverage. A file is readable only by readers of its channel, and only once attached to a live message. Refusals keep the door's reason: file_too_large, file_not_found_or_unreadable, file_not_uploaded, file_not_ready, file_already_attached, file_wrong_channel, storage_unreachable (no answer: try again), storage_refused (storage said no: retrying will not help; the sentence names the step, HTTP status and class).",
             "edit <message-id> [--expected-revision <n>] [--request-id <uuid>] — replaces your own message's text (piped in). With --expected-revision, an edit of a message that has moved on is refused revision_conflict and nothing is saved over it; the current revision is printed. A message you did not write, or one that was deleted, is refused by name. delete <message-id> [--expected-revision <n>] [--request-id <uuid>] — deletes by tombstone: the text is cleared and every surface reads \"This message was deleted\", but the row stays so its thread, replies and reply count survive. Search and unread counts ignore it. A repeat answers already_deleted. outcome <request-uuid> — your own write receipt for a send, edit or delete: committed, not_committed (with the reason) or unknown_check_again. Run it after a timeout before retrying. draft [list|show|save|discard|restore|send] <channel> [--thread <id>] [--expected-revision <n>] [--request-id <uuid>] — the text you have not sent yet, one draft per channel and thread, the same drafts the browser autosaves. list shows all your unsent drafts (newest first, with coverage); show prints one; save takes the body on stdin (`echo \"half a thought\" | cockpit msg draft save general`) and with --expected-revision refuses draft_revision_conflict, naming the stored revision, instead of overwriting; discard keeps the text (state discarded) and restore brings it back; send posts the stored draft with a fresh request id (--request-id to retry the same send) and its revision, prints the receipt, and marks the draft sent only if it did not change meanwhile. Only you can read or change your drafts.",
             "thread <id> --channel <channel> [--before <cursor>] [--limit <n>] — one thread's replies by the parent message's id.",
             "show <message-id> — exact message, thread root and bounded neighbors. read/thread --before takes the preceding nextCursor; repeat until hasMore is false. activity [--mentions|--threads] [--unread] [--before <cursor>] [--limit <n>] [--mark-read] — your Mentions (messages that mention you) and Threads (replies in threads you follow: you started it, replied natively or followed it by hand), newest first, with unread counts and coverage; items whose message you can no longer read are left out and counted as dropped. Nothing is marked read by looking; --mark-read marks the unread items just printed, and the web marks one when its message is shown. Activity covers native Tower messages only, so the Slack import adds none. follow <message-id> / unfollow <message-id> — the id is the thread's top-level message; an explicit unfollow wins over a later auto follow, and earlier items stay. react <message-id> <emoji> [--remove] — adds or takes off your reaction (idempotent). Refusals: thread_root_not_found_or_unreadable, not_a_thread_root, reaction_not_found. notify — your message notification settings (the same ones the web header menu and Settings change): the default level (all, mentions or none; mentions is the default and covers direct messages, @mentions and replies in threads you follow), quiet hours and per-channel overrides. notify set --level <all|mentions|none> changes the default; add --channel <id|name> for one channel, with --mute / --unmute, or --clear to remove the override. notify quiet <HH:MM-HH:MM> [--timezone <zone>] sets quiet hours (24-hour, may wrap midnight; the zone defaults to this machine's) and notify quiet --off removes them. notify receipts [--message <id>] [--before <cursor>] [--limit <n>] lists what was delivered, suppressed or blocked and why (never message text): outcome shown means Tower told a browser tab to show a banner; push_accepted means the push service took the phone push, not that a phone showed it. Quiet hours and levels hold back banners and phone pushes, never the message or its unread badge. Refusals: invalid_notification_level, invalid_quiet_hours, invalid_timezone. search [words] [--from <email|me>]... [--in <channel>] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--timezone <IANA>] [--replies|--top-level] [--has-file] [--before <cursor>] [--limit <n>] — message search on your own access, newest first (not ranked; `cockpit search --kind msg` is the ranked bar). Each hit prints its id, channel, author, time and snippet, then `more: --before <cursor>` or `complete`; repeat with the cursor until complete. --from takes an email, a user id or me and repeats; --in takes a channel id or #name (exact after case folding, an ambiguous name is refused); --since and --until are whole local days in --timezone, both inclusive (this machine's zone when you give none). The words may be left out when a filter is set, so `msg search --has-file` finds attachment-only messages. Inline operators work in the words as in the web box: from:<email|me> in:#name after:<day> before:<day> (exclusive) on:<day> has:file is:reply is:root. Recognised but unsupported operators (has:link, has:pin, has:reaction, is:saved, is:dm, to:, with:, during:) are refused unsupported_search_operator, naming the operator; a bad day, zone, person or channel is refused invalid_search_filter. Messages imported from Slack carry no file links, so has:file does not find them. Deleted messages, channels you cannot read and files you cannot read never appear.",

package/dist/commands/local-help-notes.js

@@ -3,7 +3,7 @@ export const NOTES_HELP = [
     [
         "notes",
         [
-            "Usage: cockpit notes [list|show <id>|shelf|shelves|folders|mkdir <path>|rmdir <path>|rename <path>|upload <paths...> [--wait]|paste|share <id>|unshare <id>|summarize <id>|move <id>|accounts|connect|detach <id>|sync <id>|sync-status [<id>]|recordings <note-id>|recording <id>|record start|stop|status|cancel|app install|uninstall|status|review [<note-id>] [--submit|--accept-all]] [flags]",
+            "Usage: cockpit notes [list|show <id>|shelf|shelves|folders|mkdir <path>|rmdir <path>|rename <path>|upload <paths...> [--wait]|paste|share <id>|unshare <id>|correct <id> --from <term> --to <term>|summarize <id>|move <id>|accounts|connect|detach <id>|sync <id>|sync-status [<id>]|recordings <note-id>|recording <id>|record start|stop|status|cancel|app install|uninstall|status|review [<note-id>] [--submit|--accept-all]] [flags]",
             "Audio uploads: MP3, M4A, WAV, WebM and OGG, up to 1 GB. Over 4 MB (a whole meeting) the file goes straight to storage and is transcribed in the background; --wait then polls for up to 4 hours and prints progress, otherwise for at most 330 seconds.",
             "",
             "record start|stop [<session-id>]|status|cancel — record a meeting in a room from this machine's microphone (Apple Silicon macOS and Windows; Linux says it is not supported). On Windows the microphone needs Settings > Privacy & security > Microphone on, including Let desktop apps access your microphone. Nothing leaves the machine while recording; the recorder stops by itself after 8 hours (under the 1 GB upload limit). `stop` uploads the whole original recording, silence included, and Tower writes a note with Speaker 1, Speaker 2... lines, or says no speech was detected (add --wait to watch the transcription). `cancel` stops and KEEPS the file; `status` lists what is recording and every session waiting for upload (`needs_upload`); `stop <session-id>` uploads a cancelled, crashed or auto-stopped session. The BLI Notetaker app uploads waiting sessions by itself. The recording also stays on this machine.",
@@ -24,6 +24,7 @@ export const NOTES_HELP = [
             "share <id> [--yes] — let everyone signed in read the statements that are safe to share. Asks first in a terminal; --yes is required without one, and --json implies --yes.",
             "summarize <id> — write a new summary (decisions, action items, key points) where every claim cites the speaker, timestamp and segment id (s12) it came from; claims the transcript does not support are dropped. Takes up to a minute; earlier summaries are kept. `show <id>` prints the newest one.",
             "unshare <id> — take it back. Never asks: it only ever narrows who can read.",
+            "correct <id> --from \"<misheard>\" --to \"<right>\" [--transcript] — fix a misheard term: every whole-word mention in the note's notes and summary in one write, the previous text kept. The transcript stays as recorded unless you pass --transcript, and then each fix is marked beside the words as heard. Owner or admin only. Then `cockpit glossary add` makes future transcripts and incoming notes spell it right.",
             "move <id> (--to \"<shelf>\"|--clear-shelf) — put it on a different shelf, or take the shelf off.",
             "place <id> [--apply] — say which shelf this note belongs on and why, from the meeting it is part of, who was in the room and its own name. Moves nothing without --apply, and never overrules a shelf somebody typed.",
             "",

package/dist/commands/notes-writes.js

@@ -223,6 +223,30 @@ export async function shareNote(command, door) {
     sayUpload(door, body);
     return 0;
 }
+/**
+ * `cockpit notes correct <note-id> --from <term> --to <term> [--transcript]` (BLI-24437): one call to
+ * `POST /api/notes/correct`, the door the browser, MCP and JARVIS use. The server counts; this prints its sentences.
+ * A refusal, including "nothing_to_correct" (no mention found, nothing changed), prints the server's sentence and exits 1.
+ */
+export async function correctNote(command, door) {
+    const scope = command.transcript ? "notes_and_transcript" : "notes";
+    const answer = await ask(door, {
+        path: "/api/notes/correct",
+        method: "POST",
+        label: "notes correct",
+        timeoutMs: READ_DEADLINE_MS,
+        body: { note_id: command.noteId, from: command.from, to: command.to, scope },
+    });
+    if (!answer.ok) {
+        return fail(door, answer.reason, answer.detail);
+    }
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} corrected ${JSON.stringify({ note_id: command.noteId ?? null, scope, notes: body.counts?.notes ?? null, transcript: body.counts?.transcript ?? null, summary: body.counts?.summary ?? null })}`);
+    if (door.json)
+        return emit(door, body);
+    sayUpload(door, body);
+    return 0;
+}
 /** A summary run is two model calls over a long transcript: give it room (BLI-20882). */
 const SUMMARIZE_DEADLINE_MS = 330_000;
 /**