@oxygen-agent/cli 1.1014.135 → 1.1014.618

package/dist/command-support.js

@@ -0,0 +1,1610 @@
+import { emitCliFailure, writeJson } from "./cli-output.js";
+import { cliProfileSource } from "./cli-profile-context.js";
+import { parseJsonObject, readNonNegativeInt, readPositiveInt, readRecordString } from "./cli-values.js";
+import { clearCredentials, listCredentialProfiles, loadCredentials, pickProfileNameForIdentity, pickProfileNameForUserSession, resolveActiveProfile, updateActiveOrganizationForProfile } from "./credentials.js";
+import { requestOxygen } from "./http-client.js";
+import { acquireMirrorLock, deletePageFile, emptyMirrorState, findMirrorSlugByPageId, isFileDirty, purgeMirror, resetMirrorForFullResync, quarantineDirtyFile, readMirrorState, releaseMirrorLock, resolveDefaultConfigDir, resolveMirrorDir, writeGeneratedIndexFile, writeGeneratedLogFile, writeMirrorState, writePageFile } from "./knowledge-mirror.js";
+import { waitForCliRun } from "./run-wait.js";
+import { redactTranscriptSecrets } from "./transcript.js";
+import { isRecord, readOption } from "./util.js";
+import { formatCellForDisplay } from "@oxygen/shared/cell-format";
+import { OxygenError, success } from "@oxygen/shared/cli-result";
+import { COLLAB_SUBJECT_KINDS, SUBJECT_PATH_FORMS_PROSE, formatSubjectPath, parseSubjectPath, parseSubjectRef } from "@oxygen/shared/collab";
+import { tableRunSummary } from "@oxygen/shared/table-run-summary";
+import { describeWorkflowStatusChange, parseWorkflowStatusChange } from "@oxygen/shared/workflow-status-change";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { stdout as output } from "node:process";
+// --- Collaboration: comments + approvals (Control layer) ---------------------
+//
+// EVERY enumeration below is mapped over a shared total map in
+// @oxygen/shared/collab.ts — never typed out here. A blind-user eval found
+// `tags --help` advertising 7 of the 13 taggable kinds because the prose sat
+// beside a hand-maintained marker map and drifted; six kinds were invisible
+// from the one place a user looks. The collab maps are total over their key
+// type, so adding a subject kind or a gate is a compile error until it is
+// glossed, and the moment it compiles it is already in this help text.
+/** `--on` / `--path` help, shared by every command that addresses a subject. */
+export const COLLAB_SUBJECT_REF_HELP = `Subject as "<kind>:<id>" — e.g. sequence:9f1c2b7e. Kinds: ${COLLAB_SUBJECT_KINDS.join(", ")}.`;
+export const COLLAB_SUBJECT_PATH_HELP = `Narrow to a sub-object: ${SUBJECT_PATH_FORMS_PROSE}.`;
+/**
+ * Both group descriptions end with this, because a surface that is one release
+ * old should say so where a user meets it. Beta here means exactly what it means
+ * for Agents, the Knowledge Graph, and Recipes: WEB NAV VISIBILITY. Nothing
+ * about the gate, the client role, or credit rules is softened by the toggle,
+ * and this command group is reachable at either setting — which is what keeps a
+ * gate armed from the terminal answerable from the terminal.
+ */
+export const COLLAB_BETA_NOTE = "BETA: the /collab entry appears in the web sidebar once a workspace enables Settings -> Beta features; "
+    + "these commands, the gate, and the client role behave identically either way.";
+/**
+ * Parse `--on <kind>:<id>`. Client-side so a typo costs no round trip and the
+ * error can list every legal kind — `parseSubjectRef` already throws a typed
+ * `invalid_subject_ref` (exit 2) carrying `details.valid_kinds`.
+ */
+export function requireCollabSubject(value) {
+    const raw = readOption(value);
+    if (!raw) {
+        throw new OxygenError("invalid_subject_ref", `--on is required. ${COLLAB_SUBJECT_REF_HELP}`, {
+            details: { valid_kinds: [...COLLAB_SUBJECT_KINDS] },
+            exitCode: 2,
+        });
+    }
+    return parseSubjectRef(raw);
+}
+/** Validate and canonicalize `--path`; undefined when the flag was not passed. */
+export function readCollabPath(value) {
+    const raw = readOption(value);
+    return raw ? formatSubjectPath(parseSubjectPath(raw)) : undefined;
+}
+// One cadence vocabulary across every scheduled surface (column refresh, table
+// feed): `translateScheduleEvery` in apps/web resolves all four forms, so this
+// string is the single place the CLI spells them out.
+export const CADENCE_FLAG_DESCRIPTION = "Shorthand schedule: hourly, every_6h, daily@<hour>, or weekly@<day><hour> (e.g. weekly@mon9). Hours 0-23 UTC.";
+const OXYGEN_WORDMARK = [
+    "   ___  __  __ __   __  ___  _____ _   _",
+    "  / _ \\ \\ \\/ / \\ \\ / / / __|| ____| \\ | |",
+    " | | | | \\  /   \\ V / | |  _|  _| |  \\| |",
+    " | |_| | /  \\    | |  | |_| | |___| |\\  |",
+    "  \\___/ /_/\\_\\   |_|   \\____|_____|_| \\_|",
+].join("\n");
+const TABLE_ACTION_RUN_WAIT_DEFAULT_TIMEOUT_SECONDS = 600;
+const TABLE_ACTION_RUN_WAIT_DEFAULT_INTERVAL_SECONDS = 5;
+export const TABLE_INGESTION_WAIT_DEFAULT_TIMEOUT_SECONDS = 600;
+export const TABLE_INGESTION_WAIT_DEFAULT_INTERVAL_SECONDS = 5;
+// A disabled workflow is a customer's automation at zero, and `status:
+// "disabled"` alone never said who did that or why (OXY-4124). Mirror the
+// recorded transition as one stderr line per disabled workflow, so `workflows
+// list` / `workflows get` answer "who turned this off?" in the terminal without
+// polluting the machine-read stdout envelope (which carries `statusChange` in
+// full). Sourced from the same shared sentence the web banner renders.
+export function formatDisabledWorkflowNotices(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return [];
+    const block = data;
+    const candidates = Array.isArray(block.workflows)
+        ? block.workflows
+        : [block.workflow];
+    const notices = [];
+    for (const candidate of candidates) {
+        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+            continue;
+        const workflow = candidate;
+        if (workflow.status !== "disabled")
+            continue;
+        const slug = typeof workflow.slug === "string" ? workflow.slug : "workflow";
+        const change = parseWorkflowStatusChange(workflow.statusChange);
+        // A workflow disabled before the record shipped has no actor to name. Say
+        // that plainly rather than inventing one.
+        notices.push(change
+            ? `${slug}: ${describeWorkflowStatusChange(change)}`
+            : `${slug}: disabled — no actor was recorded (disabled before Oxygen tracked this).`);
+    }
+    return notices;
+}
+// Discovery lists are windowed by default (200 rows, max 1000) so the cost of
+// asking "what is in this workspace?" does not scale with how much the customer
+// has built. A window nobody can see is indistinguishable from a complete
+// answer, so say it on stderr — same treatment the observability console's
+// per-source cap already gets. Machine-read stdout carries `capped`, `returned`
+// and `limit` either way.
+export function writeListCapNotice(data, noun, hint) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const record = data;
+    if (record.capped !== true)
+        return;
+    const returned = typeof record.returned === "number" ? record.returned : null;
+    const total = typeof record.total === "number" ? ` of ${record.total}` : "";
+    process.stderr.write(`note: showing ${returned === null ? "a window of" : returned}${total} ${noun}; more exist — raise --limit (max 1000) or pass --all${hint ? `; ${hint}` : ""}.\n`);
+}
+export function parseJsonArray(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (error) {
+        throw new OxygenError("invalid_json", "Input must be valid JSON.", {
+            details: { reason: error instanceof Error ? error.message : "unknown" },
+            exitCode: 1,
+        });
+    }
+    if (!Array.isArray(parsed)) {
+        throw new OxygenError("invalid_json", "Input JSON must be an array.", {
+            exitCode: 1,
+        });
+    }
+    return parsed;
+}
+/**
+ * Parse a JSON command-input value, mapping `JSON.parse` syntax failures to a
+ * typed `invalid_json` envelope. A raw `JSON.parse` throw is an ordinary `Error`,
+ * which `@oxygen/shared`'s `toFailure` flattens to a machine-hostile
+ * `unexpected_error`; routing through here keeps malformed user JSON actionable.
+ * Shape validation, where a caller needs it, stays with the caller. `inputName`
+ * is the user-facing flag or source label, e.g. "--steps-file".
+ */
+export function parseJsonValue(value, inputName) {
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        throw new OxygenError("invalid_json", `${inputName} must be valid JSON.`, {
+            details: { reason: error instanceof Error ? error.message : "unknown" },
+            exitCode: 1,
+        });
+    }
+}
+/**
+ * Read a local file and parse it as JSON command input, surfacing syntax
+ * failures as a typed `invalid_json` envelope tagged with `inputName`. File-read
+ * errors (missing/unreadable path) propagate unchanged — they are not JSON.
+ */
+export function readJsonFileValue(path, inputName) {
+    return parseJsonValue(readFileSync(path, "utf8"), inputName);
+}
+export function readFileIfPresent(value) {
+    // Help text across these options promises "JSON or @file/path"; a leading
+    // `@` names a file too (2026-09-25 blind eval: `--filters-json @f.json` was
+    // parsed as JSON). An `@…` value that names no file stays literal text.
+    if (value.startsWith("@") && value.length > 1) {
+        const fromAt = readFileIfPresent(value.slice(1));
+        if (fromAt !== value.slice(1))
+            return fromAt;
+    }
+    const candidate = resolve(value);
+    try {
+        return readFileSync(candidate, "utf8");
+    }
+    catch (error) {
+        const code = error && typeof error === "object" && "code" in error
+            ? String(error.code)
+            : "";
+        if (code === "ENOENT" || code === "ENAMETOOLONG" || code === "ENOTDIR")
+            return value;
+        throw error;
+    }
+}
+export function readPublishingPostText(options, required) {
+    const inlineText = readOption(options.text);
+    const textFile = readOption(options.textFile);
+    if (inlineText && textFile) {
+        throw new OxygenError("conflicting_flags", "Pass either --text or --text-file, not both.", { exitCode: 1 });
+    }
+    const text = textFile ? readPublishingTextFile(textFile) : inlineText;
+    if (text?.trim())
+        return text;
+    if (!required)
+        return null;
+    throw new OxygenError("invalid_request", "Pass --text or --text-file.", { exitCode: 1 });
+}
+// Read a file-backed flag, sanitizing the OS error so a missing/unreadable file
+// reports only the basename the user passed — never the resolved absolute filesystem
+// path Node's ENOENT would otherwise leak into the CLI error output. `flag` names the
+// option in the error so --source-file doesn't report itself as --text-file.
+export function readPublishingTextFile(textFile, flag = "--text-file") {
+    try {
+        return readFileSync(resolve(textFile), "utf8").trimEnd();
+    }
+    catch {
+        throw new OxygenError("text_file_unreadable", `Couldn't read ${flag} '${basename(textFile)}'. Check the path exists and is readable.`, { exitCode: 1 });
+    }
+}
+export function splitCommaList(value) {
+    const raw = readOption(value);
+    if (!raw)
+        return [];
+    return raw.split(",").map((entry) => entry.trim()).filter(Boolean);
+}
+export function buildCrmSignalRecordBody(options) {
+    const event = readOption(options.event);
+    if (!event) {
+        throw new OxygenError("invalid_request", "--event is required.", { exitCode: 1 });
+    }
+    const sessionId = readOption(options.sessionId);
+    // The redelivery/idempotency guard: an explicit id, else derived from the
+    // provider session id so a repeat reveal still dedupes.
+    const externalEventId = readOption(options.externalEventId) ?? (sessionId ? `signal:${sessionId}` : null);
+    if (!externalEventId) {
+        throw new OxygenError("invalid_request", "--external-event-id is required (or pass --session-id to derive it).", { exitCode: 1 });
+    }
+    const payload = {};
+    const email = readOption(options.email);
+    if (email)
+        payload.email = email;
+    const linkedinUrl = readOption(options.linkedinUrl);
+    if (linkedinUrl)
+        payload.linkedin_url = linkedinUrl;
+    const companyDomain = readOption(options.companyDomain);
+    if (companyDomain)
+        payload.company_domain = companyDomain;
+    const companyName = readOption(options.companyName);
+    if (companyName)
+        payload.company_name = companyName;
+    const firstName = readOption(options.firstName);
+    if (firstName)
+        payload.first_name = firstName;
+    const lastName = readOption(options.lastName);
+    if (lastName)
+        payload.last_name = lastName;
+    const pageUrl = readOption(options.pageUrl);
+    if (pageUrl)
+        payload.page_url = pageUrl;
+    if (sessionId)
+        payload.session_id = sessionId;
+    // An explicit --payload-json wins over the convenience flags above.
+    if (options.payloadJson)
+        Object.assign(payload, parseJsonObject(options.payloadJson));
+    return { event, external_event_id: externalEventId, payload };
+}
+export function buildCrmLeadsTodayPath(options) {
+    const params = new URLSearchParams();
+    if (options.limit)
+        params.set("limit", options.limit);
+    if (options.withinDays)
+        params.set("within_days", options.withinDays);
+    const query = params.toString();
+    return query ? `/api/cli/crm/signals/leads-today?${query}` : "/api/cli/crm/signals/leads-today";
+}
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isUuid(value) {
+    return UUID_PATTERN.test(value);
+}
+export function tableWebhookDeliveriesPath(options) {
+    const params = new URLSearchParams();
+    const endpointId = readOption(options.endpointId);
+    const table = readOption(options.table);
+    const status = readOption(options.status);
+    const autoRunStatus = readOption(options.autoRunStatus);
+    const limit = readPositiveInt(options.limit);
+    if (endpointId)
+        params.set("endpoint_id", endpointId);
+    if (table)
+        params.set("table", table);
+    if (status)
+        params.set("status", status);
+    if (autoRunStatus)
+        params.set("auto_run_status", autoRunStatus);
+    if (limit)
+        params.set("limit", String(limit));
+    const query = params.toString();
+    return `/api/cli/tables/webhooks/deliveries${query ? `?${query}` : ""}`;
+}
+export function tableRunsListPath(options) {
+    const table = readOption(options.table);
+    if (!table) {
+        throw new OxygenError("invalid_table_run", "Pass --table <table>.", {
+            exitCode: 1,
+        });
+    }
+    const query = new URLSearchParams({ table });
+    const status = readOption(options.status);
+    const limit = readPositiveInt(options.limit);
+    if (status)
+        query.set("status", status);
+    if (limit)
+        query.set("limit", String(limit));
+    if (options.traceId)
+        query.set("trace_id", options.traceId);
+    return `/api/cli/table-action-runs?${query.toString()}`;
+}
+// Range flags accept "20-200" -> { min, max }, "500+" -> { min }, "-50" -> { max },
+// and a bare "200" -> { min, max } (exact value).
+export function readRangeOption(value, flag) {
+    const raw = readOption(value);
+    if (!raw)
+        return null;
+    if (/^\d+\+$/.test(raw)) {
+        return { min: readRangeNumber(raw.slice(0, -1), flag, raw) };
+    }
+    if (/^-\d+$/.test(raw)) {
+        return { max: readRangeNumber(raw.slice(1), flag, raw) };
+    }
+    if (/^\d+-\d+$/.test(raw)) {
+        const [minRaw, maxRaw] = raw.split("-");
+        const min = readRangeNumber(minRaw, flag, raw);
+        const max = readRangeNumber(maxRaw, flag, raw);
+        if (min > max) {
+            throw new OxygenError("invalid_range", `${flag} min must not exceed max.`, {
+                details: { flag, value: raw },
+                exitCode: 1,
+            });
+        }
+        return { min, max };
+    }
+    if (/^\d+$/.test(raw)) {
+        const bound = readRangeNumber(raw, flag, raw);
+        return { min: bound, max: bound };
+    }
+    throw new OxygenError("invalid_range", `${flag} expects a range like 20-200, 500+, or -50.`, {
+        details: { flag, value: raw },
+        exitCode: 1,
+    });
+}
+function readRangeNumber(value, flag, raw) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new OxygenError("invalid_range", `${flag} bounds must be non-negative integers.`, {
+            details: { flag, value: raw },
+            exitCode: 1,
+        });
+    }
+    return parsed;
+}
+// The id a `search plan` envelope prints (search_plan_…, company_search_plan_…,
+// signal_search_plan_…). `--plan` takes the plan itself, not its id; a blind
+// acceptance run on 2026-10-04 passed the id and got only "Input must be valid
+// JSON" with no way forward.
+const SEARCH_PLAN_ID_PATTERN = /^[a-z_]*search_plan_[A-Za-z0-9]+$/;
+export function readSearchPlanJson(value) {
+    const raw = readFileIfPresent(value);
+    if (raw === value && SEARCH_PLAN_ID_PATTERN.test(value.trim())) {
+        throw new OxygenError("invalid_json", `--plan takes the plan JSON returned by the plan command, not its id ${value.trim()}.`, {
+            details: {
+                plan_id: value.trim(),
+                next_step: "Re-run the plan command with --json and save its output to a file (for example plan.json), then pass --plan plan.json.",
+            },
+            exitCode: 1,
+        });
+    }
+    const parsed = parseJsonObject(raw);
+    const data = parsed.data;
+    return data && typeof data === "object" && !Array.isArray(data)
+        ? data
+        : parsed;
+}
+export function readFilterSelectionOption(value) {
+    const filters = readFilterJsonOption(value);
+    return filters ? { mode: "filter", filters } : undefined;
+}
+export function readFilterJsonOption(value) {
+    const raw = readOption(value);
+    if (!raw)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new OxygenError("invalid_filter", "--filter-json must be valid JSON.", {
+            details: { reason: error instanceof Error ? error.message : String(error) },
+            exitCode: 1,
+        });
+    }
+    const filters = Array.isArray(parsed) ? parsed : [parsed];
+    if (filters.length === 0
+        || filters.some((entry) => !entry || typeof entry !== "object" || Array.isArray(entry))) {
+        throw new OxygenError("invalid_filter", "--filter-json must be a filter object or non-empty array of filter objects.", {
+            exitCode: 1,
+        });
+    }
+    return filters;
+}
+export function readFormulaValuesOption(value) {
+    const raw = readOption(value);
+    if (raw === null)
+        return null;
+    if (raw !== "materialized") {
+        throw new OxygenError("invalid_filter", "--formula-values must be 'materialized' when provided.", { details: { formula_values: raw }, exitCode: 1 });
+    }
+    return raw;
+}
+export function buildGetSurfaceRunWaitConfig(params) {
+    return {
+        runId: params.runId,
+        requestedTimeoutSeconds: params.requestedTimeoutSeconds,
+        requestedIntervalSeconds: params.requestedIntervalSeconds,
+        defaultTimeoutSeconds: params.defaultTimeoutSeconds,
+        defaultIntervalSeconds: params.defaultIntervalSeconds,
+        retryTransientNetworkErrors: params.retryTransientNetworkErrors === true,
+        fetchRun: (signal) => requestOxygen(`${params.endpoint}/${encodeURIComponent(params.runId)}${params.view ? `?view=${params.view}` : ""}`, signal ? { signal } : {}),
+        isTerminal: params.isTerminal,
+        shapeTerminal: (run, status, polls, elapsedMs) => {
+            const webUrl = readRecordString(run, "web_url");
+            return {
+                [params.runKey]: params.view === "summary" ? tableRunSummary(run) : run,
+                [params.runIdKey]: readRecordString(run, "id") ?? params.runId,
+                status,
+                terminal: true,
+                polls,
+                elapsedMs,
+                ...(webUrl ? { web_url: webUrl } : {}),
+            };
+        },
+        timeoutCode: params.timeoutCode,
+        timeoutMessage: params.timeoutMessage,
+        timeoutDetailIdKey: params.timeoutDetailIdKey,
+    };
+}
+export function waitForTableActionRun(runId, options) {
+    return waitForCliRun(buildGetSurfaceRunWaitConfig({
+        runId,
+        endpoint: "/api/cli/table-action-runs",
+        view: options.full ? "full" : "summary",
+        requestedTimeoutSeconds: options.timeoutSeconds,
+        requestedIntervalSeconds: options.intervalSeconds,
+        defaultTimeoutSeconds: TABLE_ACTION_RUN_WAIT_DEFAULT_TIMEOUT_SECONDS,
+        defaultIntervalSeconds: TABLE_ACTION_RUN_WAIT_DEFAULT_INTERVAL_SECONDS,
+        isTerminal: isTerminalTableActionRunStatus,
+        runKey: "actionRun",
+        runIdKey: "actionRunId",
+        timeoutCode: "table_action_run_wait_timeout",
+        timeoutMessage: "Timed out waiting for table action run to finish.",
+        timeoutDetailIdKey: "action_run_id",
+    }));
+}
+export function normalizeExportRowsFormat(value) {
+    const normalized = value?.trim().toLowerCase() || "json";
+    if (normalized === "json"
+        || normalized === "jsonl"
+        || normalized === "csv"
+        || normalized === "table")
+        return normalized;
+    throw new OxygenError("invalid_format", "Export format must be json, jsonl, csv, or table.", {
+        details: { format: value },
+        exitCode: 1,
+    });
+}
+export function formatRows(rows, format, columns) {
+    if (format === "json") {
+        return { content: `${JSON.stringify(rows, null, 2)}\n`, rescuedCount: 0 };
+    }
+    if (format === "jsonl") {
+        return {
+            content: `${rows.map((row) => JSON.stringify(row)).join("\n")}\n`,
+            rescuedCount: 0,
+        };
+    } // skipcq: JS-0246
+    const keys = [
+        "_row_id",
+        "_created_at",
+        "_updated_at",
+        ...(columns?.map((column) => column.key) ?? []),
+        ...rows.flatMap((row) => Object.keys(row)),
+    ].filter((key, index, all) => all.indexOf(key) === index && rows.some((row) => key in row));
+    if (format === "csv") {
+        const csvBody = [
+            keys.map(escapeCsvField).join(","),
+            ...rows.map((row) => keys.map((key) => escapeCsvField(row[key])).join(",")),
+        ].join("\n");
+        return {
+            content: `${csvBody}\n`,
+            rescuedCount: 0,
+        };
+    }
+    // "table": render with type-aware formatting and a Markdown-style frame.
+    const columnByKey = new Map(columns?.map((column) => [column.key, column]) ?? []);
+    let rescuedCount = 0;
+    const headers = keys.map((key) => columnByKey.get(key)?.label ?? key);
+    const formattedRows = rows.map((row) => keys.map((key) => {
+        const column = columnByKey.get(key) ?? null;
+        const formatted = formatCellForDisplay(row[key], column, {
+            surface: "cli",
+            onRescued: () => {
+                rescuedCount += 1;
+            },
+        });
+        // Pipe and any line-break char are the row/cell delimiters of the
+        // Markdown frame — raw values containing them would corrupt the layout.
+        // Match on the line-break class (not just `\r?\n`) so a standalone `\r`
+        // doesn't slip through and split the row visually.
+        return formatted.replace(/[\r\n]+/g, " ↵ ").replace(/\|/g, "\\|");
+    }));
+    const widths = headers.map((header, columnIndex) => {
+        let max = header.length;
+        for (const row of formattedRows) {
+            const cell = row[columnIndex] ?? "";
+            if (cell.length > max)
+                max = cell.length;
+        }
+        return Math.min(max, 60);
+    });
+    const renderRow = (cells) => {
+        const padded = cells.map((cell, i) => {
+            const width = widths[i] ?? 0;
+            return clipCell(cell, width).padEnd(width);
+        });
+        return `| ${padded.join(" | ")} |`;
+    };
+    const separator = `|${widths.map((width) => "-".repeat(width + 2)).join("|")}|`;
+    const lines = [renderRow(headers), separator, ...formattedRows.map(renderRow)];
+    if (rescuedCount > 0) {
+        lines.push("");
+        lines.push(`# Note: reformatted ${rescuedCount} cell${rescuedCount === 1 ? "" : "s"} that look numeric in text columns. Run \`oxygen columns retype <table> <column> --data-type numeric\` to make this permanent.`);
+    }
+    return { content: `${lines.join("\n")}\n`, rescuedCount };
+}
+export function clipCell(value, width) {
+    if (value.length <= width)
+        return value;
+    if (width <= 1)
+        return value.slice(0, width);
+    return `${value.slice(0, width - 1)}…`;
+}
+function escapeCsvField(value) {
+    const text = value === null || value === undefined
+        ? ""
+        : typeof value === "object"
+            ? JSON.stringify(value)
+            : String(value);
+    return /[",\n\r]/.test(text) ? `"${text.replace(/"/g, "\"\"")}"` : text;
+}
+export function readCount(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+/**
+ * Content type from the file extension — a hint only. It picks the presigned
+ * URL's type and the stored key's extension; the server sniffs the real bytes
+ * before it will publish a URL, so a wrong guess here fails loudly rather than
+ * hosting something mislabelled.
+ */
+function imageContentTypeForPath(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".jpg") || lower.endsWith(".jpeg"))
+        return "image/jpeg";
+    if (lower.endsWith(".webp"))
+        return "image/webp";
+    if (lower.endsWith(".png"))
+        return "image/png";
+    throw new OxygenError("unsupported_image", "Profile pictures must be a .png, .jpg, or .webp file.", { details: { path }, exitCode: 2 });
+}
+/**
+ * Hops one and two of the avatar upload: presign, then PUT the raw bytes straight
+ * to Oxygen object storage. Returns the storage key the caller confirms with.
+ *
+ * Shared because two commands stage the same bytes in the same bucket and then
+ * diverge: `managed-inboxes upload-avatar` confirms against the avatars route to
+ * get a public URL to paste into an order, while `senders profiles set-photo`
+ * hands the key to the profile writer as `avatar_upload_key`, which re-checks org
+ * ownership and re-sniffs the bytes itself. Copying the two hops into the second
+ * caller would have duplicated the abort timeout and the failure taxonomy, and
+ * the copy is exactly where they drift.
+ */
+export async function putAvatarBytesToStorage(path) {
+    const resolved = resolve(path);
+    const bytes = readFileSync(resolved);
+    const contentType = imageContentTypeForPath(resolved);
+    const ticket = await requestOxygen("/api/cli/managed-inboxes/avatars", {
+        method: "POST",
+        body: { content_type: contentType, content_length: bytes.byteLength },
+    });
+    const upload = readRecord(ticket, "upload");
+    const uploadUrl = readRecordString(upload, "url");
+    const storageKey = readRecordString(ticket, "storage_key");
+    if (!uploadUrl || !storageKey) {
+        throw new OxygenError("invalid_response", "Oxygen API response is missing the avatar upload URL.", { exitCode: 1 });
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 120_000);
+    let putResponse;
+    try {
+        putResponse = await fetch(uploadUrl, {
+            method: "PUT",
+            body: new Uint8Array(bytes),
+            headers: { "content-type": contentType },
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!putResponse.ok) {
+        throw new OxygenError("avatar_upload_failed", `Uploading the photo to object storage failed (HTTP ${putResponse.status}).`, { details: { status: putResponse.status }, exitCode: 1 });
+    }
+    return storageKey;
+}
+export function readRecord(value, key) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const entry = value[key];
+    return isRecord(entry) ? entry : null;
+}
+export function isTerminalTableIngestionStatus(status) {
+    return status === "completed"
+        || status === "completed_with_errors"
+        || status === "failed"
+        || status === "canceled";
+}
+function isTerminalTableActionRunStatus(status) {
+    return status === "completed"
+        || status === "completed_with_errors"
+        || status === "failed"
+        || status === "canceled";
+}
+export async function resolveActiveProfileWithSource() {
+    const resolution = await resolveActiveProfile();
+    return { resolution, source: cliProfileSource(resolution.source) };
+}
+/**
+ * Write a completed org selection back onto the stored profile.
+ *
+ * Shared by `orgs use` and `oxygen login --org` so the two-step (log in, then
+ * switch) and the one-step collapse cannot drift apart.
+ *
+ * Gated on the credential being one that can actually carry a selection: an
+ * org-bound key's active workspace is a property of the key, not of the profile,
+ * so persisting a different one would only produce a profile that lies about
+ * where its commands land.
+ */
+export async function persistOrganizationSelection(input) {
+    const { profile, credentials, organization } = input;
+    if (!profile || !credentials || !organization)
+        return false;
+    if (credentials.authKind !== "user_session" && !credentials.token.startsWith("oxy_user_")) {
+        return false;
+    }
+    await updateActiveOrganizationForProfile(profile, storedOrganizationFromOption(organization));
+    return true;
+}
+export function shellQuote(value) {
+    if (/^[A-Za-z0-9_.\-:/@%+=]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+export async function handleLogoutAction(options) {
+    try {
+        const clearOptions = {};
+        if (options.profile !== undefined)
+            clearOptions.profile = options.profile;
+        if (options.all !== undefined)
+            clearOptions.all = options.all;
+        const result = await clearCredentials(process.env, clearOptions);
+        if (options.json) {
+            writeJson(success("logout", {
+                logged_out: true,
+                removed_profile: result.removedProfile,
+                remaining_profiles: result.remainingProfiles,
+            }));
+            return;
+        }
+        process.stdout.write(formatLogoutSuccess(result));
+    }
+    catch (error) {
+        emitCliFailure("logout", error);
+    }
+}
+export async function resolveLoginIdentity(token, apiUrl) {
+    if (isUserSessionToken(token)) {
+        const credentials = {
+            token,
+            apiUrl,
+            authKind: "user_session",
+        };
+        const orgs = await requestOxygen("/api/cli/orgs", { credentials });
+        const activeOrganization = orgs.currentOrganization
+            ? storedOrganizationFromOption(orgs.currentOrganization)
+            : null;
+        credentials.activeOrganization = activeOrganization;
+        credentials.identity = identityFromUserAndOrganization(orgs.user, activeOrganization);
+        return {
+            credentials,
+            whoami: null,
+            user: orgs.user,
+            activeOrganization,
+            organizations: orgs.organizations,
+            selectionRequired: Boolean(orgs.selectionRequired),
+        };
+    }
+    const credentials = {
+        token,
+        apiUrl,
+    };
+    if (token.startsWith("oxy_live_"))
+        credentials.authKind = "org_api_key";
+    const identity = await requestOxygen("/api/cli/whoami", {
+        credentials,
+    });
+    const activeOrganization = storedOrganizationFromOption(identity.organization);
+    credentials.authKind = identity.authType === "user_session" ? "user_session" : "org_api_key";
+    credentials.activeOrganization = activeOrganization;
+    credentials.identity = identityFromWhoami(identity);
+    return {
+        credentials,
+        whoami: identity,
+        user: identity.user,
+        activeOrganization,
+        organizations: [{ ...identity.organization, selected: true }],
+        selectionRequired: false,
+    };
+}
+export function pickProfileForLogin(loginIdentity) {
+    const apiUrl = loginIdentity.credentials.apiUrl;
+    if (loginIdentity.credentials.authKind === "user_session") {
+        const seed = loginIdentity.activeOrganization?.slug
+            ?? loginIdentity.user.email
+            ?? loginIdentity.user.id;
+        return pickProfileNameForUserSession(loginIdentity.user.id, seed, apiUrl);
+    }
+    const organization = loginIdentity.activeOrganization;
+    if (!organization) {
+        return pickProfileNameForUserSession(loginIdentity.user.id, loginIdentity.user.email ?? loginIdentity.user.id, apiUrl);
+    }
+    const seed = organization.slug?.trim() || organization.id;
+    return pickProfileNameForIdentity(organization.id, seed, apiUrl);
+}
+export function readEnvProfileName() {
+    const value = process.env.OXYGEN_PROFILE?.trim();
+    return value ? value : null;
+}
+export function identityFromWhoami(response) {
+    return {
+        organization: storedOrganizationFromOption(response.organization),
+        user: {
+            id: response.user.id,
+            email: response.user.email ?? null,
+        },
+        capturedAt: new Date().toISOString(),
+    };
+}
+function identityFromUserAndOrganization(user, organization) {
+    return {
+        organization,
+        user: {
+            id: user.id,
+            email: user.email ?? null,
+        },
+        capturedAt: new Date().toISOString(),
+    };
+}
+export function storedOrganizationFromOption(organization) {
+    return {
+        id: organization.id,
+        name: organization.name,
+        slug: organization.slug ?? null,
+    };
+}
+function isUserSessionToken(token) {
+    return token.startsWith("oxy_user_");
+}
+export async function buildPostLoginHint(activeProfile) {
+    const plain = output.isTTY !== true || Boolean(process.env.NO_COLOR);
+    const styles = ansi(!plain);
+    const label = (text) => (plain ? text : styles.dim(text));
+    const command = (text) => (plain ? text : styles.bold(text));
+    const state = await listCredentialProfiles().catch(() => null);
+    const lines = [];
+    // The pin hint only makes sense with more than one stored profile.
+    if (state && state.profiles.length >= 2) {
+        lines.push(`  ${label("Pin this terminal:")}  ${command(`eval "$(oxygen profiles env ${activeProfile})"`)}`);
+    }
+    // Mirror every reachable workspace into local markdown so agents can read/grep
+    // the wiki offline; --if-stale keeps a large multi-workspace loop cheap.
+    lines.push(`  ${label("Mirror your wikis:")}  ${command("oxygen knowledge sync --all --if-stale")}`);
+    return `\n${lines.join("\n")}\n\n`;
+}
+export function formatLoginSuccessForResolved(loginIdentity, profile, options = {}) {
+    if (loginIdentity.whoami) {
+        return formatLoginSuccess(loginIdentity.whoami, loginIdentity.credentials, profile, options);
+    }
+    if (loginIdentity.activeOrganization) {
+        return formatLoginSuccess({
+            user: loginIdentity.user,
+            organization: loginIdentity.activeOrganization,
+            apiKey: {
+                id: "user_session",
+                name: "CLI user session",
+                tokenPrefix: loginIdentity.credentials.token.slice(0, 17),
+                tokenSuffix: loginIdentity.credentials.token.slice(-4),
+                kind: "user_session",
+            },
+            authType: "user_session",
+        }, loginIdentity.credentials, profile, options);
+    }
+    const styles = ansi(output.isTTY === true && !process.env.NO_COLOR);
+    const email = loginIdentity.user.email ?? loginIdentity.user.id;
+    const fingerprint = createHash("sha256")
+        .update(`oxygen-cli:${loginIdentity.credentials.token}`)
+        .digest("hex");
+    const profileLabel = options.renamed
+        ? `${profile} ${styles.dim("(auto-renamed to avoid collision)")}`
+        : profile;
+    const rows = [
+        ["Account", email],
+        ["Organization", "not selected"],
+        ["Profile", profileLabel],
+        ["API", loginIdentity.credentials.apiUrl],
+        ["Token", `${loginIdentity.credentials.token.slice(0, 17)}...${loginIdentity.credentials.token.slice(-4)}`],
+        ["Fingerprint", formatFingerprint(fingerprint)],
+    ];
+    const labelWidth = Math.max(...rows.map(([label]) => label.length));
+    const wordmark = renderBox([
+        "",
+        ...OXYGEN_WORDMARK.split("\n").map(line => styles.green(line)),
+        "",
+    ]);
+    const orgLines = loginIdentity.organizations.length > 0
+        ? [
+            "",
+            "Available organizations:",
+            ...loginIdentity.organizations.map((organization) => `  - ${organization.name}${organization.slug ? ` (${organization.slug})` : ""}`),
+            "",
+            `Select one: ${styles.bold("oxygen orgs use <organization>")}`,
+        ]
+        : [];
+    return [
+        "",
+        wordmark,
+        "",
+        `${styles.green("[OK]")} ${styles.bold("CLI connected")}`,
+        "",
+        ...rows.map(([label, value]) => `  ${styles.dim(label.padEnd(labelWidth))}   ${value}`),
+        ...orgLines,
+        "",
+        ...formatAutomaticSkillsInstallStatusLines(options.skillsInstall),
+    ].join("\n");
+}
+function formatLoginSuccess(identity, credentials, profile, options = {}) {
+    const email = identity.user.email ?? identity.user.id;
+    const orgName = identity.organization.name || identity.organization.slug || identity.organization.id;
+    const orgSlug = identity.organization.slug ?? null;
+    const org = orgSlug && orgSlug !== orgName ? `${orgName} (${orgSlug})` : orgName;
+    const key = identity.apiKey
+        ? `${identity.apiKey.tokenPrefix}...${identity.apiKey.tokenSuffix}`
+        : "stored";
+    const fingerprint = createHash("sha256")
+        .update(`oxygen-cli:${credentials.token}`)
+        .digest("hex");
+    const styles = ansi(output.isTTY === true && !process.env.NO_COLOR);
+    const profileLabel = options.renamed
+        ? `${profile} ${styles.dim("(auto-renamed to avoid collision)")}`
+        : profile;
+    // skipcq: JS-0820 — not a React component; rule misfire on array of tuples
+    const rows = [
+        ["Account", email],
+        ["Organization", org],
+        ["Profile", profileLabel],
+        ["API", credentials.apiUrl],
+        ["Token", key],
+        ["Fingerprint", formatFingerprint(fingerprint)],
+    ];
+    const labelWidth = Math.max(...rows.map(([label]) => label.length));
+    const wordmark = renderBox([
+        "",
+        ...OXYGEN_WORDMARK.split("\n").map(line => styles.green(line)),
+        "",
+    ]);
+    return [
+        "",
+        wordmark,
+        "",
+        `${styles.green("[OK]")} ${styles.bold("CLI connected")}`,
+        "",
+        ...rows.map(([label, value]) => `  ${styles.dim(label.padEnd(labelWidth))}   ${value}`),
+        "",
+        ...formatAutomaticSkillsInstallStatusLines(options.skillsInstall),
+    ].join("\n");
+}
+export function formatFingerprint(hex) {
+    return hex.slice(0, 20).match(/.{1,4}/g)?.join(":") ?? hex.slice(0, 20);
+}
+export function createCredentialFingerprint(token) {
+    return createHash("sha256")
+        .update(`oxygen-cli:${token}`)
+        .digest("hex");
+}
+/** Column-aligned plain-text table, two-space indented. Shared by the sequence-variant lenses and the collaboration lists. */
+export function renderTextTable(headers, rows) {
+    const widths = headers.map((header, columnIndex) => {
+        let max = header.length;
+        for (const row of rows) {
+            const cell = row[columnIndex] ?? "";
+            if (cell.length > max)
+                max = cell.length;
+        }
+        return max;
+    });
+    const renderRow = (cells) => `  ${cells.map((cell, i) => cell.padEnd(widths[i] ?? 0)).join("  ")}`.replace(/\s+$/, "");
+    const separator = `  ${widths.map((width) => "-".repeat(width)).join("  ")}`;
+    return [renderRow(headers), separator, ...rows.map(renderRow)];
+}
+/** A read command that prints a readable block instead of the raw envelope.
+ *  `--json` still emits the untouched API envelope, so the lens is presentation
+ *  only and never becomes a second contract. Used by the sequencer lenses and by
+ *  `crm objects`. */
+export async function handleReadActionWithLens(command, options, action, render) {
+    try {
+        const data = await action();
+        if (options.json) {
+            writeJson(success(command, data));
+            return;
+        }
+        process.stdout.write(isRecord(data) ? render(data) : `${JSON.stringify(data, null, 2)}\n`);
+    }
+    catch (error) {
+        emitCliFailure(command, error);
+    }
+}
+// --- Collaboration output ----------------------------------------------------
+//
+// Comments and approvals are read by two very different audiences: the agency's
+// operator in a terminal, and an agent parsing --json. So these commands render
+// a compact human view by default and the stable envelope under --json — the
+// same split `sequences variants` uses. Every renderer ends with the deep-link
+// the API returned, because the client who has to decide is usually the one
+// person NOT in the terminal.
+export async function handleCollabAction(command, options, action, render) {
+    try {
+        const data = await action();
+        if (options.json) {
+            writeJson(success(command, data));
+            return;
+        }
+        process.stdout.write(isRecord(data) ? render(data) : `${JSON.stringify(data, null, 2)}\n`);
+    }
+    catch (error) {
+        emitCliFailure(command, error);
+    }
+}
+export function collabStyles() {
+    return ansi(output.isTTY === true && !process.env.NO_COLOR);
+}
+export function collabText(value, fallback = "—") {
+    return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+export function collabLink(data) {
+    if (typeof data.web_url === "string")
+        return data.web_url;
+    return typeof data.deepLink === "string" ? data.deepLink : null;
+}
+/** Coarse age for a list column: seconds, minutes, hours, then days. */
+export function formatCollabAge(value) {
+    if (typeof value !== "string")
+        return "—";
+    const at = Date.parse(value);
+    if (!Number.isFinite(at))
+        return "—";
+    const seconds = Math.max(0, Math.round((Date.now() - at) / 1000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}
+/** First line of a body, clipped — a thread's subject line in one cell. */
+export function collabSnippet(value, width = 56) {
+    if (typeof value !== "string")
+        return "";
+    const firstLine = value.split("\n").find((line) => line.trim()) ?? "";
+    return clipCell(firstLine.trim(), width);
+}
+/** Trailer every collab render shares: what to do next, then the deep-link. */
+export function collabTrailer(data) {
+    const styles = collabStyles();
+    const lines = [];
+    const nextStep = typeof data.next_step === "string" ? data.next_step.trim() : "";
+    if (nextStep)
+        lines.push("", `  ${styles.dim("Next")}   ${nextStep}`);
+    const link = collabLink(data);
+    if (link)
+        lines.push(`  ${styles.dim("Link")}   ${link}`);
+    return lines;
+}
+/**
+ * Generic confirmation for a write whose payload is one object. The API already
+ * writes a `next_step` sentence for each of these, so the renderer's only job is
+ * to say what changed and keep the deep-link visible.
+ */
+export function formatCollabWriteResult(data) {
+    const styles = collabStyles();
+    const lines = [""];
+    const headline = collabWriteHeadline(data);
+    lines.push(`  ${styles.green("[OK]")} ${headline}`);
+    if (data.already === true) {
+        lines.push(`  ${styles.dim("Already in that state; nothing changed.")}`);
+    }
+    const notified = Array.isArray(data.notified_emails)
+        ? data.notified_emails.filter((value) => typeof value === "string")
+        : [];
+    if (notified.length > 0)
+        lines.push(`  ${styles.dim("Notified")}  ${notified.join(", ")}`);
+    const unresolved = Array.isArray(data.unresolved_mentions)
+        ? data.unresolved_mentions.filter((value) => typeof value === "string")
+        : [];
+    if (unresolved.length > 0) {
+        lines.push(`  ${styles.yellow("Not a workspace member, so not notified:")} ${unresolved.join(", ")}`);
+    }
+    const note = collabText(data.note, "");
+    if (note)
+        lines.push(`  ${styles.dim(note)}`);
+    lines.push(...collabTrailer(data));
+    lines.push("");
+    return lines.join("\n");
+}
+/** One line naming what changed, matched to each write endpoint's payload shape. */
+function collabWriteHeadline(data) {
+    // A thread write (`comments add`, `comments resolve`) serializes the thread
+    // itself at the top level.
+    if (typeof data.status === "string" && typeof data.subject === "string") {
+        return `${collabText(data.subject)} — thread ${collabText(data.id)} is ${data.status}.`;
+    }
+    if (isRecord(data.comment)) {
+        return data.comment.deleted === true ? "Comment retracted." : "Comment updated.";
+    }
+    if (isRecord(data.request)) {
+        return `Approval request ${collabText(data.request.id)} is ${collabText(data.request.status)}.`;
+    }
+    // `orgs member-role` — the Clerk workspace role, not the Oxygen overlay. It
+    // must be checked BEFORE the overlay branch below: both write payloads are
+    // flat and both carry `email`, so falling through would report a promotion as
+    // "back to full workspace access".
+    if (typeof data.email === "string" && typeof data.workspace_role_choice === "string") {
+        return data.workspace_role_choice === "admin"
+            ? `${data.email} is now a workspace admin.`
+            : `${data.email} is now a workspace member.`;
+    }
+    // The member-role write returns the membership fields flat, not nested.
+    if (typeof data.email === "string") {
+        // Granting on a PENDING INVITATION changes nobody's access yet. Saying "is
+        // now a client-role member" would tell an agency the client is restricted
+        // while that client has not accepted and holds no membership at all.
+        if (data.pending_invitation === true) {
+            return data.granted === true
+                ? `${data.email} has not joined yet — they will land restricted to the client role.`
+                : `${data.email} has not joined yet — they will land with full workspace access.`;
+        }
+        return data.granted === true
+            ? `${data.email} is now a client-role member of this workspace.`
+            : `${data.email} is back to full workspace access.`;
+    }
+    return "Done.";
+}
+export function describeProfileSource(source) {
+    switch (source) {
+        case "flag": return "from --profile flag";
+        case "env": return "from OXYGEN_PROFILE";
+        case "file": return "from stored active profile";
+        default: return "default fallback";
+    }
+}
+function formatLogoutSuccess(result) {
+    const styles = ansi(output.isTTY === true && !process.env.NO_COLOR);
+    const removed = result.removedProfile
+        ? `profile "${result.removedProfile}" removed`
+        : "removed";
+    return [
+        "",
+        `${styles.green("[OK]")} ${styles.bold("CLI logged out")}`,
+        "",
+        `  ${styles.dim("Credentials")}   ${removed}`,
+        `  ${styles.dim("Profiles left")}  ${String(result.remainingProfiles)}`, // skipcq: JS-C1002
+        "",
+    ].join("\n");
+}
+export function formatAutomaticSkillsInstallStatusLines(result) {
+    if (!result)
+        return [];
+    const styles = ansi(output.isTTY === true && !process.env.NO_COLOR);
+    if (!result.attempted) {
+        if (result.reason === "dry_run")
+            return [];
+        return [
+            `${styles.dim("Skills")}      skipped (${result.reason ?? "not attempted"})`,
+            "",
+        ];
+    }
+    if (result.ok) {
+        return [
+            `${styles.green("[OK]")} ${styles.bold("Oxygen skills installed")}`,
+            "",
+        ];
+    }
+    return [
+        `${styles.yellow("[WARN]")} Oxygen skills could not be installed; the CLI command still completed.`,
+        `  ${styles.dim("Check")} ${"oxygen skills doctor --json"}`,
+        `  ${styles.dim("Retry")} ${result.command}`,
+        "",
+    ];
+}
+function renderBox(lines) {
+    const width = Math.max(...lines.map(visibleLength), 0);
+    const border = `+${"-".repeat(width + 2)}+`;
+    const body = lines.map((line) => `| ${line}${" ".repeat(width - visibleLength(line))} |`);
+    return [border, ...body, border].join("\n");
+}
+function visibleLength(value) {
+    // skipcq: JS-0004, JS-W1035 — ESC (\x1b) is the ANSI CSI introducer; the literal escape is required to strip color codes
+    return value.replace(/\x1b\[[0-9;]*m/gu, "").length;
+}
+export function ansi(enabled) {
+    const wrap = (open, close) => enabled
+        ? (text) => `\x1b[${open}m${text}\x1b[${close}m`
+        : (text) => text;
+    return {
+        bold: wrap(1, 22), // skipcq: JS-0117  // skipcq: JS-W1035
+        dim: wrap(2, 22),
+        green: wrap(32, 39),
+        yellow: wrap(33, 39),
+    };
+}
+// Commander collector for a repeatable option (e.g. --attach <url> --attach <url>):
+// accumulates each value into an array.
+export function collectRepeatable(value, previous) {
+    return [...previous, value];
+}
+export function readSelectedTranscriptExcerpt(text) {
+    const excerpt = text.trim();
+    if (!excerpt || Buffer.byteLength(excerpt, "utf8") > 200_000) {
+        throw new OxygenError("invalid_transcript", "Transcript excerpt must be between 1 and 200,000 bytes.", { exitCode: 1 });
+    }
+    return redactTranscriptSecrets(excerpt);
+}
+export function readCsvOption(value) {
+    const option = readOption(value);
+    if (!option)
+        return [];
+    return option
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+// Assemble the directory listing profile payload shared by `directory update`
+// and `admin directory enable`. --profile-json provides the base object (and
+// the only way to null-clear fields); explicit flags override it.
+export async function buildDirectoryProfileBody(options) {
+    const profile = options.profileJson
+        ? parseJsonObject(options.profileJson)
+        : {};
+    const stringFlags = [
+        [options.name, "name"],
+        [options.slug, "slug"],
+        [options.logoUrl, "logo_url"],
+        [options.tagline, "tagline"],
+        [options.description, "description"],
+        [options.website, "website_url"],
+        [options.companyLinkedin, "linkedin_company_url"],
+        [options.bookingUrl, "booking_url"],
+        [options.contactEmail, "contact_email"],
+    ];
+    for (const [value, key] of stringFlags) {
+        const normalized = readOption(value);
+        if (normalized)
+            profile[key] = normalized;
+    }
+    if (!profile.description) {
+        const path = readOption(options.descriptionFile);
+        if (path) {
+            const fs = await import("node:fs/promises");
+            profile.description = await fs.readFile(path, "utf8");
+        }
+    }
+    if (readOption(options.foundersJson)) {
+        const founders = parseJsonValue(options.foundersJson ?? "[]", "founders-json");
+        if (!Array.isArray(founders)) {
+            throw new OxygenError("invalid_request", "--founders-json must be a JSON array of {name, title, linkedin_url} objects.", { exitCode: 1 });
+        }
+        profile.founders = founders;
+    }
+    const csvFlags = [
+        [options.services, "services"],
+        [options.regions, "regions"],
+    ];
+    for (const [value, key] of csvFlags) {
+        if (readOption(value))
+            profile[key] = readCsvOption(value);
+    }
+    return profile;
+}
+export function collectMultiple(value, previous) {
+    return [...previous, value];
+}
+export function buildContextResolveBody(options) {
+    const assetTypes = readCsvOption(options.assetType);
+    const tags = readCsvOption(options.tags);
+    const maxAssets = readNonNegativeInt(options.maxAssets);
+    return {
+        ...(readOption(options.purpose) ? { purpose: readOption(options.purpose) } : {}),
+        ...(assetTypes.length > 0 ? { asset_types: assetTypes } : {}),
+        ...(readOption(options.assetStatus) ? { asset_status: readOption(options.assetStatus) } : {}),
+        ...(tags.length > 0 ? { tags } : {}),
+        ...(options.includeArchived ? { include_archived: true } : {}),
+        ...(maxAssets !== undefined ? { max_assets: maxAssets } : {}),
+        ...(options.requireReady ? { require_ready: true } : {}),
+    };
+}
+// ── Knowledge mirror (local wiki clone) ─────────────────────────────────────────
+// `oxygen knowledge sync` maintains <configDir>/knowledge/<api-host>/<org-id>/ with
+// SERVER-rendered page markdown written verbatim — the server hashes those exact
+// bytes (content_sha256) and the client never re-renders, so renderer drift can't
+// mass-quarantine mirrors. Pure directory mechanics live in knowledge-mirror.ts.
+export const KNOWLEDGE_SYNC_DEFAULT_TTL_MINUTES = 15;
+// 500 batches × the server's 100-page default is far above any v1 wiki; the cap
+// only exists so a misbehaving server can never wedge the CLI in a loop.
+const KNOWLEDGE_SYNC_MAX_BATCHES = 500;
+const KNOWLEDGE_SYNC_CATALOG_MAX_BATCHES = 500;
+// Envelope error codes meaning this org can no longer be read with the stored
+// token (revoked membership, expired key, org mismatch). The mirror is a local
+// cache of tenant data and must not outlive access to it.
+const KNOWLEDGE_SYNC_ACCESS_REVOKED_CODES = new Set([
+    "unauthorized",
+    "forbidden",
+    "forbidden_origin",
+    "organization_not_found",
+    "organization_mismatch",
+]);
+export function knowledgeMirrorTargetFor(apiUrl, orgId) {
+    const apiHost = new URL(apiUrl).host;
+    return {
+        dir: resolveMirrorDir({ configDir: resolveDefaultConfigDir(), apiHost, orgId }),
+        apiHost,
+        orgId,
+        webUrl: `${apiUrl.replace(/\/$/, "")}/knowledge`,
+    };
+}
+// The org id every other command resolves implicitly (X-Oxygen-Organization from
+// OXYGEN_ORG / the stored profile) must be pinned explicitly here because it names
+// the mirror directory. Null when the cached identity can't answer for the
+// selected org — e.g. env-token logins or an OXYGEN_ORG/--org override.
+function knowledgeMirrorTargetFromCredentials(credentials) {
+    const cached = credentials.activeOrganization ?? credentials.identity?.organization ?? null;
+    if (!cached)
+        return null;
+    const selected = process.env.OXYGEN_ORG?.trim();
+    if (selected && selected !== cached.id && selected !== cached.slug)
+        return null;
+    return knowledgeMirrorTargetFor(credentials.apiUrl, cached.id);
+}
+export async function resolveKnowledgeMirrorTarget() {
+    const credentials = await loadCredentials();
+    if (!credentials) {
+        throw new OxygenError("not_logged_in", "Run `oxygen login` before using CLI commands.", {
+            exitCode: 1,
+        });
+    }
+    const local = knowledgeMirrorTargetFromCredentials(credentials);
+    if (local)
+        return local;
+    const identity = await requestOxygen("/api/cli/whoami", {
+        enforceMinimumCliVersion: false,
+    });
+    return knowledgeMirrorTargetFor(credentials.apiUrl, identity.organization.id);
+}
+function knowledgeSyncSummary(target, state, extra) {
+    return {
+        synced: 0,
+        deleted: 0,
+        quarantined: 0,
+        pages_total: state ? Object.keys(state.pages).length : 0,
+        cursor: state?.cursor ?? null,
+        last_sync_at: state?.last_sync_at ?? null,
+        mirror_path: target.dir,
+        web_url: target.webUrl,
+        ...extra,
+    };
+}
+function removeOwnedKnowledgeMirrorPage(dir, state, slug, counters) {
+    // Archive and rename remove a server-owned path, but must preserve edits we
+    // did not write. Check against its recorded bytes before losing the identity.
+    const recordedSha = state.pages[slug]?.content_sha256;
+    if (recordedSha !== undefined && isFileDirty(dir, slug, recordedSha)) {
+        if (quarantineDirtyFile(dir, slug))
+            counters.quarantined += 1;
+    }
+    deletePageFile(dir, slug);
+    delete state.pages[slug];
+    counters.deleted += 1;
+}
+function applyKnowledgeSyncPage(dir, state, page, counters) {
+    if (page.rendered_markdown === undefined || page.content_sha256 === undefined || !page.slug) {
+        // Tombstone (archived or slug-less): delete the file this page owns locally,
+        // matching by slug first and falling back to the page id (slug re-use).
+        const localSlug = page.slug && state.pages[page.slug]?.id === page.id
+            ? page.slug
+            : findMirrorSlugByPageId(state, page.id);
+        if (localSlug) {
+            removeOwnedKnowledgeMirrorPage(dir, state, localSlug, counters);
+        }
+        return;
+    }
+    // Slug renames: drop the file this page previously owned under its old slug.
+    const previousSlug = findMirrorSlugByPageId(state, page.id);
+    if (previousSlug && previousSlug !== page.slug) {
+        removeOwnedKnowledgeMirrorPage(dir, state, previousSlug, counters);
+    }
+    // Quarantine only bytes WE didn't write (differ from the manifest's recorded
+    // sha) that this write would destroy (differ from the incoming server bytes).
+    const recordedSha = state.pages[page.slug]?.content_sha256;
+    if (isFileDirty(dir, page.slug, recordedSha ?? page.content_sha256)
+        && isFileDirty(dir, page.slug, page.content_sha256)) {
+        quarantineDirtyFile(dir, page.slug);
+        counters.quarantined += 1;
+    }
+    writePageFile(dir, page.slug, page.rendered_markdown);
+    state.pages[page.slug] = {
+        id: page.id,
+        revision: page.revision,
+        content_sha256: page.content_sha256,
+    };
+    counters.synced += 1;
+}
+async function readKnowledgeMirrorCatalog(requestOrg, mirrorPath) {
+    let cursor = null;
+    const seenCursors = new Set();
+    const pages = new Map();
+    for (let batch = 0; batch < KNOWLEDGE_SYNC_CATALOG_MAX_BATCHES; batch += 1) {
+        const query = new URLSearchParams({ max_chars: "48000", limit: "1000", ...(cursor ? { cursor } : {}) });
+        const window = await requestOxygen(`/api/cli/knowledge/index?${query}`, requestOrg);
+        if (typeof window.has_more !== "boolean" || !Number.isInteger(window.max_chars) || window.max_chars < 2000 || window.max_chars > 48000 ||
+            !Array.isArray(window.index?.pages) || window.index.capped !== window.has_more ||
+            (window.next_cursor !== null && typeof window.next_cursor !== "string") || (!window.has_more && window.next_cursor !== null)) {
+            throw new OxygenError("knowledge_sync_catalog_invalid", "The knowledge catalog did not return a complete bounded continuation receipt. The generated index was left unchanged.", {
+                details: { catalog_cursor: cursor, mirror_path: mirrorPath }, exitCode: 1,
+            });
+        }
+        for (const page of window.index.pages) {
+            if (!page || typeof page.slug !== "string" || !page.slug || pages.has(page.slug)) {
+                throw new OxygenError("knowledge_sync_catalog_changed", "The catalog repeated or omitted a page slug during live traversal. Retry sync to restart the catalog; the generated index was left unchanged.", {
+                    details: { catalog_cursor: cursor, mirror_path: mirrorPath }, exitCode: 1,
+                });
+            }
+            pages.set(page.slug, page);
+        }
+        if (!window.has_more) {
+            return { ...window, index: { ...window.index, pages: [...pages.values()] } };
+        }
+        if (!window.next_cursor || seenCursors.has(window.next_cursor)) {
+            throw new OxygenError("knowledge_sync_catalog_stalled", "The catalog cursor did not advance; the generated index was left unchanged. Retry sync to restart the catalog from the preserved page watermark.", {
+                details: { catalog_cursor: cursor, next_cursor: window.next_cursor, mirror_path: mirrorPath }, exitCode: 1,
+            });
+        }
+        cursor = window.next_cursor;
+        seenCursors.add(cursor);
+    }
+    throw new OxygenError("knowledge_sync_catalog_incomplete", "The catalog batch cap was reached before its terminal receipt. The generated index was left unchanged; retry sync to restart the catalog from the preserved page watermark.", {
+        details: { catalog_cursor: cursor, mirror_path: mirrorPath, batch_cap: KNOWLEDGE_SYNC_CATALOG_MAX_BATCHES }, exitCode: 1,
+    });
+}
+// `orgOverride` targets a specific org (used by `sync --all`): it names the mirror
+// directory explicitly and pins X-Oxygen-Organization on every request in the
+// loop, so each workspace clones into its own mirror regardless of the cached
+// active org. Absent (the default single-org path), behavior is unchanged.
+export async function runKnowledgeMirrorSync(// skipcq: JS-R1005 -- one linear sync pipeline: staleness gate, lock, delta loop, generated files.
+options, orgOverride) {
+    const requestOrg = orgOverride ? { selectedOrganization: orgOverride.selector } : {};
+    let target;
+    if (orgOverride) {
+        const credentials = await loadCredentials();
+        if (!credentials) {
+            throw new OxygenError("not_logged_in", "Run `oxygen login` before using CLI commands.", { exitCode: 1 });
+        }
+        target = knowledgeMirrorTargetFor(credentials.apiUrl, orgOverride.orgId);
+    }
+    else {
+        target = await resolveKnowledgeMirrorTarget();
+    }
+    const ttlMinutes = readPositiveInt(options.ttl) ?? KNOWLEDGE_SYNC_DEFAULT_TTL_MINUTES;
+    if (options.ifStale && !options.full) {
+        const state = readMirrorState(target.dir);
+        const lastSyncMs = state?.last_sync_at ? Date.parse(state.last_sync_at) : Number.NaN;
+        if (Number.isFinite(lastSyncMs) && Date.now() - lastSyncMs < ttlMinutes * 60_000) {
+            return knowledgeSyncSummary(target, state, { skipped: true, reason: "fresh" });
+        }
+    }
+    if (!acquireMirrorLock(target.dir)) {
+        if (options.ifStale) {
+            return knowledgeSyncSummary(target, readMirrorState(target.dir), { skipped: true, reason: "locked" });
+        }
+        throw new OxygenError("knowledge_sync_locked", "Another knowledge sync is already running for this mirror. Retry shortly; a crashed sync's lock self-clears after 10 minutes.", {
+            details: { mirror_path: target.dir },
+            exitCode: 1,
+        });
+    }
+    try {
+        // --full re-clones from scratch but keeps the never-silently-clobber promise:
+        // dirty local files are quarantined into .oxygen/conflicts/ (which survives)
+        // first. Done AFTER acquiring the mirror lock above so a concurrent --full
+        // can't delete files out from under another running sync before locking.
+        const fullResetQuarantined = options.full
+            ? resetMirrorForFullResync(target.dir).quarantined
+            : 0;
+        const state = readMirrorState(target.dir)
+            ?? emptyMirrorState({ apiHost: target.apiHost, orgId: target.orgId });
+        const counters = { synced: 0, deleted: 0, quarantined: fullResetQuarantined };
+        let webUrl = target.webUrl;
+        let cursor = state.cursor;
+        let lastSeen = null;
+        let completed = false;
+        for (let batch = 0; batch < KNOWLEDGE_SYNC_MAX_BATCHES; batch += 1) {
+            const delta = await requestOxygen("/api/cli/knowledge/sync/delta", {
+                method: "POST",
+                body: cursor ? { cursor } : {},
+                ...requestOrg,
+            });
+            if (delta.web_url)
+                webUrl = delta.web_url;
+            for (const page of delta.pages) {
+                applyKnowledgeSyncPage(target.dir, state, page, counters);
+                lastSeen = { updated_at: page.updated_at, id: page.id };
+            }
+            if (!delta.has_more) {
+                // The native SQL watermark retains timestamp precision that the public
+                // updated_at Date can lose. Older servers lack last_cursor; retain their
+                // compatibility fallback without claiming it preserves SQL precision.
+                if (delta.last_cursor)
+                    state.cursor = delta.last_cursor;
+                else if (lastSeen)
+                    state.cursor = `${lastSeen.updated_at}|${lastSeen.id}`;
+                completed = true;
+                break;
+            }
+            if (!delta.next_cursor || delta.next_cursor === cursor) {
+                throw new OxygenError("knowledge_sync_stalled", "The sync cursor did not advance between batches; aborting to avoid a loop.", {
+                    details: { cursor, mirror_path: target.dir },
+                    exitCode: 1,
+                });
+            }
+            cursor = delta.next_cursor;
+            // Persist per batch so an interrupted clone resumes exactly where it stopped.
+            state.cursor = cursor;
+            writeMirrorState(target.dir, state);
+        }
+        if (!completed) {
+            throw new OxygenError("knowledge_sync_incomplete", "The sync batch cap was reached before the wiki finished; re-run `knowledge sync` to resume from the stored cursor.", {
+                details: { cursor: state.cursor, mirror_path: target.dir, batch_cap: KNOWLEDGE_SYNC_MAX_BATCHES },
+                exitCode: 1,
+            });
+        }
+        // Save page progress before summary reads so a failed catalog can resume its
+        // delta without declaring a fresh, fully completed mirror.
+        state.last_sync_at = null;
+        writeMirrorState(target.dir, state);
+        // Traverse every native catalog window, including shared-only continuations.
+        // Its scope excludes archived/proposal pages; it is a live keyset, not a
+        // snapshot of every cloned page. Real `index`/`log` page bytes take priority.
+        const index = state.pages.index ? null : await readKnowledgeMirrorCatalog(requestOrg, target.dir);
+        const logPage = state.pages.log ? null : await requestOxygen("/api/cli/knowledge/log", requestOrg);
+        if (index)
+            writeGeneratedIndexFile(target.dir, index.index);
+        if (logPage)
+            writeGeneratedLogFile(target.dir, logPage.entries);
+        state.last_sync_at = new Date().toISOString();
+        writeMirrorState(target.dir, state);
+        return knowledgeSyncSummary(target, state, { ...counters, ...(options.full ? { full: true } : {}), web_url: webUrl });
+    }
+    catch (error) {
+        if (error instanceof OxygenError && KNOWLEDGE_SYNC_ACCESS_REVOKED_CODES.has(error.code)) {
+            purgeMirror(target.dir);
+            throw new OxygenError("knowledge_mirror_access_revoked", "This organization can no longer be read with the stored credentials (membership revoked or token expired). The local knowledge mirror was purged.", {
+                details: { org_id: target.orgId, mirror_path: target.dir, cause: error.code },
+                exitCode: 1,
+            });
+        }
+        throw error;
+    }
+    finally {
+        releaseMirrorLock(target.dir);
+    }
+}
+// `knowledge sync --all` — mirror every workspace the credential can reach, each
+// into its own org-id-keyed mirror directory. Loops the same `/api/cli/orgs` list
+// the `orgs` command reads and syncs each org via `runKnowledgeMirrorSync` with an
+// explicit org override. One org's failure (including a revoked membership, which
+// purges just that org's mirror) is recorded and never aborts the rest. Pair with
+// `--if-stale` so a large fleet loop stays cheap (each org honors its own TTL).
+export async function runKnowledgeMirrorSyncAll(options) {
+    const credentials = await loadCredentials();
+    if (!credentials) {
+        throw new OxygenError("not_logged_in", "Run `oxygen login` before using CLI commands.", { exitCode: 1 });
+    }
+    const orgs = await requestOxygen("/api/cli/orgs", { credentials });
+    const results = [];
+    for (const org of orgs.organizations) {
+        const selector = org.slug ?? org.id;
+        try {
+            const summary = await runKnowledgeMirrorSync({ ...options, all: false }, { orgId: org.id, selector });
+            results.push({
+                org_id: org.id,
+                slug: org.slug ?? null,
+                status: summary.skipped ? "skipped" : "synced",
+                ...summary,
+            });
+        }
+        catch (error) {
+            results.push({
+                org_id: org.id,
+                slug: org.slug ?? null,
+                status: "failed",
+                error: error instanceof OxygenError
+                    ? { code: error.code, message: error.message }
+                    : { code: "unknown", message: error instanceof Error ? error.message : "Unknown error." },
+            });
+        }
+    }
+    return {
+        orgs: results,
+        count: results.length,
+        synced: results.filter((result) => result.status === "synced").length,
+        skipped: results.filter((result) => result.status === "skipped").length,
+        failed: results.filter((result) => result.status === "failed").length,
+        web_url: `${credentials.apiUrl.replace(/\/$/, "")}/knowledge`,
+    };
+}
+export function readPositiveNumber(value, nextStep) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new OxygenError("invalid_number", "Expected a positive number.", {
+            details: { value, ...(nextStep ? { next_step: nextStep } : {}) },
+            exitCode: 1,
+        });
+    }
+    return parsed;
+}
+/**
+ * A spend ceiling where ZERO IS VALID and meaningful: `find company
+ * --max-credits 0` asks for the lanes that cost nothing (crustdata's identify
+ * lane resolves domain↔LinkedIn for 0 credits) and skips every priced one.
+ * readPositiveNumber rejected it client-side, so the free lanes were
+ * unreachable from the CLI at all (Plain T-111). Fractional ceilings stay legal
+ * — lane estimates are fractional — so this is not the whole-number reader.
+ */
+export function readCreditCeilingOrZero(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new OxygenError("invalid_number", "Expected a number of 0 or more.", {
+            details: { value },
+            exitCode: 1,
+        });
+    }
+    return parsed;
+}
+/**
+ * A whole count (days, rows, windows). Its positive-number sibling accepts 2.5,
+ * which for a scan bound is always a typo — rejected here so it costs no round trip,
+ * and rejected rather than rounded so a bound nobody asked for is never scanned.
+ */
+export function readPositiveInteger(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new OxygenError("invalid_number", "Expected a positive whole number.", {
+            details: { value },
+            exitCode: 1,
+        });
+    }
+    return parsed;
+}
+export function readNonNegativeNumber(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new OxygenError("invalid_number", "Expected a non-negative number.", {
+            details: { value },
+            exitCode: 1,
+        });
+    }
+    return parsed;
+}