@bli-cockpit/cli 0.2.286 → 0.2.288

package/dist/commands/backfill-scan.js

@@ -18,12 +18,14 @@ import { liveWindowMsFor, scopeBackfillCandidates } from "./backfill-live-window
 import { getCollectorRuntimePaths } from "../local-state.js";
 import { candidateCursorKey, compareBackfillCandidates, isAfterCursor, } from "./backfill-candidates.js";
 import { addReadOnlyGuardIssues, addRepoDiscoveryIssues, backfillScanIssues, countReadOnlyGuards, deterministicSkipCandidateKeys, oversizedBackfillCandidateKeys, retryableCandidateKeys, sortScanIssuesByPriority, } from "./backfill-issues.js";
-import { labelOutsideRootCandidates, outsideRootsWorkspace, } from "./backfill-outside-roots.js";
+import { labelOutsideRootCandidates, outsideRootsWorkspace } from "./backfill-outside-roots.js";
 import { reasonCountsFor } from "./backfill-reasons.js";
 import { blockedBackfillResult } from "./backfill-result.js";
 import { emptyStubReofferPlan, loadStubReofferPlan, reopenStubbedSessions, } from "./backfill-stub-reoffer.js";
 import { loadStubCursorHashes, locateStubbedSessions } from "./backfill-stub-locate.js";
 import { resolveBackfillScope } from "./backfill-scope.js";
+import { scopeHistoryScans } from "../collection-scope.js";
+import { decideShelfMode, OWNER_CHECK_UNAVAILABLE, shelveBackfillScan, teamWorktreesOnly } from "./session-sync-shelf.js";
 /**
  * SCAN: is this machine paired, what roots/sources/window apply, and what did
  * the archived Codex + Claude session stores actually contain. Returns either
@@ -44,14 +46,18 @@ export async function scanBackfillRun(command, io, now) {
         };
     }
     const { collectionRoots, sources, worktreeDiscovery } = scope;
+    const shelfDecision = await decideShelfMode({ homeDir: command.homeDir, dashboardUrl: scope.dashboardUrl, fetchImpl: io.fetch }); // BLI-23478
+    if (shelfDecision.mode === "hold")
+        return { kind: "blocked", result: blockedBackfillResult(command, { now, dashboardUrl: scope.dashboardUrl, reason: OWNER_CHECK_UNAVAILABLE, cursor: await readBackfillCursor(paths) }) };
+    const worktrees = teamWorktreesOnly(worktreeDiscovery.worktrees, shelfDecision);
     const { scopedCursor, cursor, pointerlessTerminalSessions, stubReoffer, stubCursorHashes } = await reopenUndeliveredHistory(command, io, paths, scope);
     const scan = await scanBackfillSessions({
         command,
-        homeDir: command.homeDir ?? os.homedir(),
-        worktrees: worktreeDiscovery.worktrees,
+        homeDir: command.homeDir ?? os.homedir(), shelfDecision,
+        worktrees,
         collectionRoots,
         sources,
-        window: scope.window,
+        window: scope.window, collectionScope: scope.collectionScope,
         cursor,
         pointerlessTerminalSessions,
         stubReoffer,
@@ -67,7 +73,7 @@ export async function scanBackfillRun(command, io, now) {
         sources,
         window: scope.window,
         collectionRoots,
-        worktrees: worktreeDiscovery.worktrees,
+        worktrees,
         retryCommand: scope.retryCommand,
         scopedCursor,
         cursor,
@@ -132,12 +138,11 @@ 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 codexAttribution = options.sources.includes("codex")
-        ? await scanCodexHistory(options, codexSessionDirs, scanLimit)
-        : null;
-    const claudeAttribution = options.sources.includes("claude_code")
-        ? await scanClaudeHistory(options, claudeProjectsDir, scanLimit)
-        : null;
+    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;
+    // 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);
     // BLI-11119: a stubbed session is found by the id in its content or by the
     // file hash its cursor entry recorded, across every root the scan walked.
     const scanned = locateStubbedSessions({

package/dist/commands/backfill-scope.js

@@ -4,7 +4,9 @@
  * which stores and how far back was it asked for, and can it reach the
  * dashboard at all. Nothing here opens a transcript.
  */
-import { resolveSourceSwitches } from "../source-opt-out.js";
+import { settleCollectionScope } from "../collection-scope.js";
+import { configOptOutLabels, resolveSourceSwitches } from "../source-opt-out.js";
+import { liveStandingForDecision } from "../live-founder-memo.js";
 import path from "node:path";
 import { readLocalCollectorConfig, readLocalCollectorSessionFile, readLocalSessionReference, } from "../local-state.js";
 import { DEFAULT_DISCOVERY_MAX_DEPTH, DEFAULT_DISCOVERY_MAX_REPOS, collectionRootPathAliases, discoverGitWorktreesInRootsWithStatus, } from "../repo-identity.js";
@@ -45,8 +47,11 @@ export async function resolveBackfillScope(command, io, now, paths) {
         collectionRoots,
         worktreeDiscovery,
         retryCommand: backfillDiscoveryRetryCommand(command, worktreeDiscovery),
-        sources: honourSourceOptOuts(selectedSources(command.source), config),
+        sources: honourSourceOptOuts(selectedSources(command.source), config, 
+        // Tower's live word, asked only when the config holds an opt-out (BLI-22640).
+        configOptOutLabels(config).length > 0 ? (await liveStandingForDecision(paths, { fetch: io.fetch, dashboardUrl })).standing : "unknown"),
         window,
+        collectionScope: await settleCollectionScope(paths.state_dir, config.collection_scope),
     };
 }
 /**
@@ -58,8 +63,15 @@ export async function resolveBackfillScope(command, io, now, paths) {
  * Backfill never reads the store of a source the machine said no to, and logs
  * the reason label (ticket 22557).
  */
-function honourSourceOptOuts(sources, config) {
-    const switches = resolveSourceSwitches(config);
+function honourSourceOptOuts(sources, config, standing) {
+    // Founders only (BLI-22640): a non-founder's opt-out is ignored and named here.
+    const switches = resolveSourceSwitches(config, standing);
+    if (switches.ignored.length > 0) {
+        console.error("[backfill] opt-out ignored; only a founder's opt-out is obeyed, so these sessions upload", JSON.stringify({ reason: switches.verdict, ignored: switches.ignored }));
+    }
+    if (switches.held) {
+        console.error("[backfill] opt-out held; Tower could not say whether this person is a founder, so the sources it names send nothing", JSON.stringify({ reason: switches.verdict, held: configOptOutLabels(config) }));
+    }
     const kept = sources.filter((source) => (source === "codex" ? switches.codex : switches.claude));
     if (kept.length === sources.length)
         return sources;

package/dist/commands/backfill-session-report.js

@@ -83,6 +83,8 @@ function sessionAttributionRow(candidate, uploads, now) {
         path_score: candidate.path_score,
         // BLI-11091: the same inside/outside label the sync path writes (PR 1453).
         root_scope: rootScopeForReason(candidate.reason),
+        // BLI-23478: a team-shelf row; a drawer session never becomes a backfill candidate (`backfill-scan.ts`).
+        shelf: "team",
         signals: candidate.signals,
         ...(candidate.content_hash_sha256
             ? { session_file_hash_sha256: candidate.content_hash_sha256 }

package/dist/commands/books-files.js

@@ -0,0 +1,159 @@
+/**
+ * `cockpit books export|import` (BLI-23711, PR A): a book as a folder, `<dir>/<collection>/<doc_id>.json`, each file
+ * the record's data only, pretty JSON with a trailing newline. That is the layout the Claude artifact export already
+ * writes, so the scripts that read a book's export read Tower's the same way.
+ *
+ * Export walks every collection through the list door (keyset pages of 500). Import reads the same layout and writes
+ * through the batch door, 50 writes (and at most ~3 MB) per batch, keeping doc ids and data unchanged, then prints what
+ * it wrote per collection. A doc id holding a character a file name cannot (`<>:"/\|?*%`, control characters, a
+ * trailing dot or space) is written with that character as %XX, and import decodes it back.
+ */
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+export const BOOK_COLLECTIONS = ["meta", "timeline", "actions", "documents", "meetings", "conversations", "workstreams", "sources", "syncs"];
+const BATCH_WRITES = 50;
+const BATCH_CHARS = 3_000_000;
+const TAG = "[books cli]";
+/** One door call; a refusal keeps the door's own reason and message. */
+export async function booksRequest(door, method, path, label, body) {
+    return askAgentDoor(door, { path, method, label: `books ${label}`, timeoutMs: 60_000, ...(body === undefined ? {} : { body }) });
+}
+// eslint-disable-next-line no-control-regex
+const UNSAFE = /[<>:"/\\|?*%\u0000-\u001f]|[. ]$/g;
+/** A doc id as a file name (without `.json`). Reversible: `%` itself is encoded. */
+export function fileNameFor(docId) {
+    return docId.replace(UNSAFE, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
+}
+export function docIdFor(fileName) {
+    return fileName.replace(/%([0-9A-F]{2})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+}
+/** Keys in a stable order, so two exports of the same book are byte-identical. Values are untouched. */
+function sorted(value) {
+    if (Array.isArray(value))
+        return value.map(sorted);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sorted(value[key])]));
+    }
+    return value;
+}
+async function isEmptyOrMissing(dir) {
+    try {
+        return (await readdir(dir)).length === 0;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return true;
+        throw error;
+    }
+}
+export async function exportBook(door, book, dir) {
+    if (!(await isEmptyOrMissing(dir)))
+        return failAgentDoor(door, TAG, "export_dir_not_empty", `${dir} is not empty. Export into a new or empty folder so no old record is mixed in.`);
+    const counts = {};
+    for (const collection of BOOK_COLLECTIONS) {
+        counts[collection] = 0;
+        let after = null;
+        do {
+            const query = new URLSearchParams({ collection, limit: "500" });
+            if (after !== null)
+                query.set("after", after);
+            const answer = await booksRequest(door, "GET", `/api/books/${encodeURIComponent(book)}/records?${query}`, "export");
+            if (!answer.ok)
+                return failAgentDoor(door, TAG, answer.reason, answer.detail, { collection, written: counts });
+            const page = answer.body;
+            if (page.records.length > 0)
+                await mkdir(join(dir, collection), { recursive: true });
+            for (const record of page.records) {
+                await writeFile(join(dir, collection, `${fileNameFor(record.doc_id)}.json`), `${JSON.stringify(sorted(record.data), null, 2)}\n`, "utf8");
+                counts[collection] += 1;
+            }
+            after = page.next_cursor;
+        } while (after !== null);
+    }
+    const total = Object.values(counts).reduce((sum, n) => sum + n, 0);
+    console.error(`${TAG} exported ${JSON.stringify({ book, total })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, book, dir, counts, total });
+    for (const collection of BOOK_COLLECTIONS)
+        writeLine(door.io.stdout, `${collection}\t${counts[collection]}`);
+    writeLine(door.io.stdout, `Exported ${total} records of ${book} to ${dir}.`);
+    return 0;
+}
+async function readLayout(dir) {
+    const writes = [];
+    const skipped = [];
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !BOOK_COLLECTIONS.includes(entry.name)) {
+            skipped.push(entry.name);
+            continue;
+        }
+        for (const file of (await readdir(join(dir, entry.name))).sort()) {
+            if (!file.endsWith(".json")) {
+                skipped.push(`${entry.name}/${file}`);
+                continue;
+            }
+            const text = (await readFile(join(dir, entry.name, file), "utf8")).replace(/^/, "");
+            let data;
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                throw new Error(`${entry.name}/${file} is not valid JSON.`);
+            }
+            writes.push({ op: "put", collection: entry.name, doc_id: docIdFor(file.slice(0, -".json".length)), data, merge: false });
+        }
+    }
+    return { writes, skipped };
+}
+/** Batches of at most 50 writes and ~3 MB, in file order. */
+export function batchesOf(writes) {
+    const batches = [];
+    let current = [];
+    let chars = 0;
+    for (const write of writes) {
+        const size = JSON.stringify(write).length;
+        if (current.length > 0 && (current.length >= BATCH_WRITES || chars + size > BATCH_CHARS)) {
+            batches.push(current);
+            current = [];
+            chars = 0;
+        }
+        current.push(write);
+        chars += size;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
+export async function importBook(door, book, dir) {
+    let layout;
+    try {
+        layout = await readLayout(dir);
+    }
+    catch (error) {
+        return failAgentDoor(door, TAG, "import_read_failed", error.message);
+    }
+    const counts = Object.fromEntries(BOOK_COLLECTIONS.map((c) => [c, 0]));
+    const batches = batchesOf(layout.writes);
+    for (const [index, batch] of batches.entries()) {
+        const answer = await booksRequest(door, "POST", `/api/books/${encodeURIComponent(book)}/batch`, "import", { writes: batch });
+        if (!answer.ok) {
+            const failed = answer.body?.index;
+            const at = typeof failed === "number" ? batch[failed] : undefined;
+            return failAgentDoor(door, TAG, answer.reason, `${answer.detail} Batch ${index + 1} of ${batches.length} was not written; earlier batches were.`, { written: counts, ...(at ? { record: `${at.collection}/${at.doc_id}` } : {}) });
+        }
+        for (const write of batch)
+            counts[write.collection] = (counts[write.collection] ?? 0) + 1;
+    }
+    const total = layout.writes.length;
+    console.error(`${TAG} imported ${JSON.stringify({ book, total, batches: batches.length, skipped: layout.skipped.length })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, book, counts, total, batches: batches.length, skipped: layout.skipped });
+    for (const collection of BOOK_COLLECTIONS)
+        writeLine(door.io.stdout, `${collection}\t${counts[collection]}`);
+    if (layout.skipped.length)
+        writeLine(door.io.stdout, `Skipped (not a collection or not .json): ${layout.skipped.join(", ")}`);
+    writeLine(door.io.stdout, `Imported ${total} records into ${book} in ${batches.length} batches.`);
+    return 0;
+}

package/dist/commands/books-usage.js

@@ -0,0 +1,14 @@
+/** `cockpit books` usage text (BLI-23711), in its own module so the help table can print it without loading the command. */
+export const BOOKS_USAGE = [
+    "Usage: cockpit books list [--json]",
+    "       cockpit books create <book> --title \"<title>\" [--json]                      (founders)",
+    "       cockpit books members list|add|remove <book> [<email or user id>] [--edit] [--json]   (founders)",
+    "       cockpit books ls <book> <collection> [--after <doc_id>] [--limit <1-500>] [--deleted] [--json]",
+    "       cockpit books get <book> <collection> <doc_id> [--deleted] [--json]",
+    "       cockpit books put <book> <collection> <doc_id> [--merge] [--version <n>] [--data '<json>'] [--json]   (data on stdin if no --data)",
+    "       cockpit books delete <book> <collection> <doc_id> [--version <n>] [--json]   (soft: the record is kept)",
+    "       cockpit books batch <book> [--json]                       ({\"writes\": [...]} on stdin, 1 to 50 writes, all or nothing)",
+    "       cockpit books export <book> <dir> [--json]                (<dir>/<collection>/<doc_id>.json)",
+    "       cockpit books import <book> <dir> [--json]                (the export layout, through the batch door)",
+    "Collections: meta, timeline, actions, documents, meetings, conversations, workstreams, sources, syncs.",
+].join("\n");

package/dist/commands/books.js

@@ -0,0 +1,214 @@
+import { emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
+import { booksRequest, exportBook, importBook } from "./books-files.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { BOOKS_USAGE } from "./books-usage.js";
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+export { BOOKS_USAGE };
+const ACTIONS = ["list", "create", "members", "ls", "get", "put", "delete", "batch", "export", "import"];
+const BODY_MAX_CHARS = 4_000_000;
+function usage() {
+    throw new Error(BOOKS_USAGE);
+}
+function wholeNumber(raw, min, max) {
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw))
+        usage();
+    const n = Number(raw);
+    if (n < min || n > max)
+        usage();
+    return n;
+}
+export function parseBooksArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--title", "--edit", "--after", "--limit", "--deleted", "--merge", "--version", "--data", "--json", "--home", "--dashboard-url"],
+        valueFlags: ["--title", "--after", "--limit", "--version", "--data", "--home", "--dashboard-url"],
+    });
+    const [action, ...rest] = values.positionals;
+    if (!ACTIONS.includes(action ?? ""))
+        usage();
+    const flags = values.flags;
+    const has = (flag) => flags.has(flag) || values.booleans.has(flag);
+    const allowOnly = (...allowed) => {
+        for (const flag of ["--title", "--edit", "--after", "--limit", "--deleted", "--merge", "--version", "--data"])
+            if (has(flag) && !allowed.includes(flag))
+                usage();
+    };
+    const command = {
+        kind: "books",
+        action: action,
+        json: values.booleans.has("--json"),
+        homeDir: optionalNonEmpty(flags.get("--home")),
+        dashboardUrl: optionalUrl(flags.get("--dashboard-url")),
+    };
+    switch (command.action) {
+        case "list":
+            if (rest.length)
+                usage();
+            allowOnly();
+            return command;
+        case "create": {
+            const title = optionalNonEmpty(flags.get("--title"));
+            if (rest.length !== 1 || !title)
+                usage();
+            allowOnly("--title");
+            return { ...command, book: rest[0], title };
+        }
+        case "members": {
+            const [sub, book, member, ...extra] = rest;
+            if (extra.length || !book || (sub !== "list" && sub !== "add" && sub !== "remove"))
+                usage();
+            if (sub === "list" ? member !== undefined : member === undefined)
+                usage();
+            allowOnly(...(sub === "add" ? ["--edit"] : []));
+            return { ...command, membersAction: sub, book, ...(member === undefined ? {} : { member }), ...(sub === "add" ? { canEdit: values.booleans.has("--edit") } : {}) };
+        }
+        case "ls": {
+            if (rest.length !== 2)
+                usage();
+            allowOnly("--after", "--limit", "--deleted");
+            const limit = wholeNumber(flags.get("--limit"), 1, 500);
+            const after = optionalNonEmpty(flags.get("--after"));
+            return { ...command, book: rest[0], collection: rest[1], ...(after === undefined ? {} : { after }), ...(limit === undefined ? {} : { limit }), deleted: values.booleans.has("--deleted") };
+        }
+        case "get":
+            if (rest.length !== 3)
+                usage();
+            allowOnly("--deleted");
+            return { ...command, book: rest[0], collection: rest[1], docId: rest[2], deleted: values.booleans.has("--deleted") };
+        case "put": {
+            if (rest.length !== 3)
+                usage();
+            allowOnly("--merge", "--version", "--data");
+            const version = wholeNumber(flags.get("--version"), 0, 2_147_483_647);
+            const data = flags.get("--data");
+            return { ...command, book: rest[0], collection: rest[1], docId: rest[2], merge: values.booleans.has("--merge"), ...(version === undefined ? {} : { version }), ...(data === undefined ? {} : { data }) };
+        }
+        case "delete": {
+            if (rest.length !== 3)
+                usage();
+            allowOnly("--version");
+            const version = wholeNumber(flags.get("--version"), 0, 2_147_483_647);
+            return { ...command, book: rest[0], collection: rest[1], docId: rest[2], ...(version === undefined ? {} : { version }) };
+        }
+        case "batch":
+            if (rest.length !== 1)
+                usage();
+            allowOnly();
+            return { ...command, book: rest[0] };
+        case "export":
+        case "import":
+            if (rest.length !== 2)
+                usage();
+            allowOnly();
+            return { ...command, book: rest[0], dir: rest[1] };
+    }
+}
+const seg = (value) => encodeURIComponent(value ?? "");
+async function readJsonInput(io, inline, what) {
+    let text = inline;
+    if (text === undefined) {
+        if (isInteractiveStdin(io))
+            return { ok: false, detail: `Pipe the ${what} as JSON on stdin (or pass --data '<json>').` };
+        text = await readPipedText(io.stdin, { maxChars: BODY_MAX_CHARS, overflowMessage: `The JSON on stdin is limited to ${BODY_MAX_CHARS} characters.` });
+    }
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch {
+        return { ok: false, detail: `The ${what} is not valid JSON.` };
+    }
+}
+const TAG = "[books cli]";
+export async function runBooks(command, io) {
+    const door = await openAgentDoor("books", command, io);
+    const book = seg(command.book);
+    const record = `/api/books/${book}/records/${seg(command.collection)}/${seg(command.docId)}`;
+    if (command.action === "export")
+        return exportBook(door, command.book, command.dir);
+    if (command.action === "import")
+        return importBook(door, command.book, command.dir);
+    let answer;
+    switch (command.action) {
+        case "list":
+            answer = await booksRequest(door, "GET", "/api/books", "list");
+            if (answer.ok && !command.json) {
+                const books = answer.body.books;
+                if (books.length === 0)
+                    writeLine(io.stdout, "No books you can open.");
+                for (const b of books)
+                    writeLine(io.stdout, `${b.id}\t${b.access}${b.founder ? " (founder)" : ""}\t${b.title}`);
+                return 0;
+            }
+            break;
+        case "create":
+            answer = await booksRequest(door, "POST", "/api/books", "create", { id: command.book, title: command.title });
+            break;
+        case "members":
+            if (command.membersAction === "list") {
+                answer = await booksRequest(door, "GET", `/api/books/${book}/members`, "members list");
+                if (answer.ok && !command.json) {
+                    for (const m of answer.body.members) {
+                        writeLine(io.stdout, `${m.email ?? m.user_id}\t${m.can_edit ? "edit" : "read"}`);
+                    }
+                    return 0;
+                }
+            }
+            else if (command.membersAction === "add") {
+                answer = await booksRequest(door, "POST", `/api/books/${book}/members`, "members add", { member: command.member, can_edit: command.canEdit === true });
+            }
+            else {
+                answer = await booksRequest(door, "DELETE", `/api/books/${book}/members?member=${seg(command.member)}`, "members remove");
+            }
+            break;
+        case "ls": {
+            const query = new URLSearchParams({ collection: command.collection ?? "" });
+            if (command.after !== undefined)
+                query.set("after", command.after);
+            if (command.limit !== undefined)
+                query.set("limit", String(command.limit));
+            if (command.deleted)
+                query.set("include_deleted", "1");
+            answer = await booksRequest(door, "GET", `/api/books/${book}/records?${query}`, "ls");
+            if (answer.ok && !command.json) {
+                const page = answer.body;
+                for (const r of page.records)
+                    writeLine(io.stdout, `${r.doc_id}\tv${r.version}\t${r.updated_at}${r.deleted_at ? "\tdeleted" : ""}`);
+                if (page.next_cursor)
+                    writeLine(io.stdout, `More: --after ${page.next_cursor}`);
+                return 0;
+            }
+            break;
+        }
+        case "get":
+            answer = await booksRequest(door, "GET", `${record}${command.deleted ? "?include_deleted=1" : ""}`, "get");
+            if (answer.ok && !command.json) {
+                writeLine(io.stdout, JSON.stringify(answer.body.record.data, null, 2));
+                return 0;
+            }
+            break;
+        case "put": {
+            const data = await readJsonInput(io, command.data, "record data");
+            if (!data.ok)
+                return failAgentDoor(door, TAG, "invalid_data", data.detail);
+            answer = await booksRequest(door, "PUT", record, "put", { data: data.value, merge: command.merge === true, ...(command.version === undefined ? {} : { expected_version: command.version }) });
+            break;
+        }
+        case "delete":
+            answer = await booksRequest(door, "DELETE", `${record}${command.version === undefined ? "" : `?expected_version=${command.version}`}`, "delete");
+            break;
+        case "batch": {
+            const body = await readJsonInput(io, undefined, "batch");
+            if (!body.ok)
+                return failAgentDoor(door, TAG, "invalid_batch", body.detail);
+            // A bare array is accepted as the writes list.
+            answer = await booksRequest(door, "POST", `/api/books/${book}/batch`, "batch", Array.isArray(body.value) ? { writes: body.value } : body.value);
+            break;
+        }
+    }
+    if (!answer.ok) {
+        const extra = answer.body && typeof answer.body === "object" ? Object.fromEntries(Object.entries(answer.body).filter(([key]) => key === "current_version" || key === "index")) : {};
+        return failAgentDoor(door, TAG, answer.reason, answer.detail, extra);
+    }
+    return emitAgentDoor(door, answer.body);
+}

package/dist/commands/cli-io.js

@@ -24,9 +24,7 @@ export function writeFragment(stream, text) {
         return;
     stream.write(text);
 }
-export function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
+export { errorMessage } from "../error-message.js";
 // ------------------------------------------------------------------- styling
 const SGR_DIM = "\x1b[2m";
 const SGR_RESET = "\x1b[0m";

package/dist/commands/docs-share.js

@@ -1,13 +1,13 @@
 /**
- * `cockpit docs share` and `cockpit docs access` — named page editors from a terminal (BLI-21313).
+ * `cockpit docs share` and `cockpit docs access` — the named people on a page, from a terminal (BLI-21313, BLI-23558).
  * A sibling of `docs.ts`, like `docs-notion.ts`.
  *
- * `access <id|slug>`                      → `GET    /api/docs/documents/[id]/grants`
- * `share <id|slug> --add <email>`         → `POST   /api/docs/documents/[id]/grants`
- * `share <id|slug> --remove <email>`      → `DELETE /api/docs/documents/[id]/grants`
+ * `access <id|slug>`                                    → `GET    /api/docs/documents/[id]/grants`
+ * `share <id|slug> --add <email> [--role viewer|editor]` → `POST   /api/docs/documents/[id]/grants`
+ * `share <id|slug> --remove <email>`                    → `DELETE /api/docs/documents/[id]/grants`
  *
  * The door answers with the shared permission explanation, and every refusal keeps its own reason
- * label verbatim (`private_page_grant_needs_decision`, `not_grant_manager`, `person_not_found`, ...).
+ * label verbatim (`not_grant_manager`, `person_not_found`, `grantee_is_author`, ...).
  * A person is an exact email; the server resolves it, so this file never guesses who someone is.
  */
 import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
@@ -31,6 +31,8 @@ function printPermission(door, permission) {
         writeLine(door.io.stdout, line);
     for (const editor of permission.editors)
         writeLine(door.io.stdout, `  editor: ${editor.display_name}${editor.email ? ` <${editor.email}>` : ""}`);
+    for (const viewer of permission.viewers ?? [])
+        writeLine(door.io.stdout, `  viewer: ${viewer.display_name}${viewer.email ? ` <${viewer.email}>` : ""}`);
 }
 export async function accessDocs(command, door) {
     const target = await resolveOrFail(command, door);
@@ -45,12 +47,12 @@ export async function accessDocs(command, door) {
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
     const body = answer.body;
-    writeLine(door.io.stderr, `${TAG} access ${JSON.stringify({ document_id: target.id, role: body.permission.role, editors: body.permission.editors.length })}`);
+    writeLine(door.io.stderr, `${TAG} access ${JSON.stringify({ document_id: target.id, role: body.permission.role, editors: body.permission.editors.length, viewers: (body.permission.viewers ?? []).length })}`);
     if (door.json)
         return emitAgentDoor(door, { ok: true, ...body });
     printPermission(door, body.permission);
     for (const event of body.events ?? []) {
-        writeLine(door.io.stdout, `  ${event.created_at}: ${event.actor_name} ${event.action === "granted" ? "added" : "removed"} ${event.grantee_name}`);
+        writeLine(door.io.stdout, `  ${event.created_at}: ${event.actor_name} ${event.action === "granted" ? "added" : "removed"} ${event.grantee_name}${event.role ? ` (${event.role})` : ""}`);
     }
     return 0;
 }
@@ -64,18 +66,26 @@ export async function shareDocs(command, door) {
         method: adding ? "POST" : "DELETE",
         label: adding ? "docs share add" : "docs share remove",
         timeoutMs: WRITE_DEADLINE_MS,
-        body: { person: adding ? command.addPerson : command.removePerson, ...(command.reason ? { reason: command.reason } : {}) },
+        body: {
+            person: adding ? command.addPerson : command.removePerson,
+            ...(adding && command.shareRole ? { role: command.shareRole } : {}),
+            ...(command.reason ? { reason: command.reason } : {}),
+        },
     });
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
     const body = answer.body;
-    writeLine(door.io.stderr, `${TAG} share ${JSON.stringify({ document_id: target.id, action: adding ? "add" : "remove", outcome: body.outcome, reason: body.reason, request_id: body.request_id })}`);
+    writeLine(door.io.stderr, `${TAG} share ${JSON.stringify({ document_id: target.id, action: adding ? "add" : "remove", outcome: body.outcome, reason: body.reason, role: body.role ?? null, request_id: body.request_id })}`);
     if (door.json)
         return emitAgentDoor(door, { ok: true, ...body });
     const person = adding ? command.addPerson : command.removePerson;
+    const role = body.role ?? command.shareRole ?? "editor";
+    const aRole = `${role === "editor" ? "an" : "a"} ${role}`;
     writeLine(door.io.stdout, body.outcome === "unchanged"
-        ? `Nothing changed: ${person} ${adding ? "is already an editor" : "was not an editor"}.`
-        : `${adding ? "Added" : "Removed"} ${person} ${adding ? "as an editor of" : "from the editors of"} ${target.id}.`);
+        ? `Nothing changed: ${person} ${adding ? `is already ${aRole}` : "was not named on this page"}.`
+        : body.reason === "role_changed"
+            ? `Changed ${person} to ${role} on ${target.id}.`
+            : `${adding ? "Added" : "Removed"} ${person} ${adding ? `as ${aRole} of` : "from"} ${target.id}.`);
     printPermission(door, body.permission);
     return 0;
 }

package/dist/commands/doctor-access.js

@@ -1,6 +1,7 @@
 import os from "node:os";
 import { readRootWorkScan, outsideWorkDirectories, rootsAddCommand, sessionCoverageLine } from "../root-work.js";
 import { scanWorkDirectories } from "./local-discovery.js";
+import { settleCollectionScope } from "../collection-scope.js";
 import { sendCollectorHeartbeatBestEffort } from "./heartbeat.js";
 import { isInteractiveDoctorFix } from "./doctor-report.js";
 import { describeError } from "../health-detail.js";
@@ -175,6 +176,12 @@ function shellQuote(value) {
 export async function readRootsCoverWork(context) {
     const homeDir = context.command.homeDir ?? os.homedir();
     const paths = getCollectorRuntimePaths(homeDir);
+    // BLI-23590: under `roots_only` (Tower cleared this person) a session outside the roots is deliberately not
+    // collected. That is a choice, so the row is ok and says so; it never counts the withheld sessions as a gap.
+    const scope = await settleCollectionScope(paths.state_dir, (await readLocalCollectorConfig(paths).catch(() => null))?.collection_scope);
+    if (scope.scope === "roots_only") {
+        return ok("roots-cover-work", "work_outside_roots_deliberately_withheld", `Collection scope is roots only (${scope.source === "server" ? "set in Tower" : "your local setting, confirmed by Tower"}): sessions whose working folder is outside your approved roots are deliberately not read or uploaded, and only a count reaches Tower. This is a choice, not a gap; nothing needs fixing. To add a folder to what is collected: cockpit roots add <dir>`);
+    }
     const scan = await readRootWorkScan(paths) ?? await scanWorkDirectories(homeDir, false);
     const outside = outsideWorkDirectories(scan, (await readLocalCollectorConfig(paths))?.default_repo_paths ?? []);
     const outsideCount = outside.reduce((sum, entry) => sum + entry.count, 0);