@popoverinstall/cli 0.8.0 → 0.9.0

package/dist/vaults.js

@@ -0,0 +1,1224 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { gzipSync } from "node:zlib";
+import { MAX_TRANSCRIPT_BYTES, SNAPSHOT_FORMAT_VERSION, VAULT_FORMAT_VERSION, VaultDescriptionSchema, VaultIndexSchema, collectPathRoots, defaultApiUrl, isVaultName, loadCredentials, normalizeVaultName, parseTranscript, sanitizeTranscript, } from "@popoverinstall/shared";
+import { askDaemon } from "./ipc-client.js";
+import { findTranscript, lastTimestamp, readRepo, readTitle, settle } from "./snapshot.js";
+import { bad, c, dim, info, ok, warn } from "./ui.js";
+/**
+ * `popover vault` — a conversation frozen for the team, and asked later.
+ *
+ * The design is docs/vaults.md; this file is the terminal half of it. What matters when
+ * reading it is which of the three "copy of a conversation" things it is:
+ *
+ *   - `popover fork` hands one conversation to one named person, keyed by a code the server
+ *     never sees, and they carry it on as their own live session. It expires in 24 hours.
+ *   - a vault is published to a *team*, never expires, and is never carried on. It is only
+ *     ever asked, and the answer comes back attributed rather than as fact.
+ *
+ * Three consequences run through everything below.
+ *
+ * **The agent authors the description.** `--title` and `--answers` are written by the model,
+ * not prompted for, because the one moment anybody knows what a conversation is authoritative
+ * about is while they are still inside it (docs/vaults.md §3). So `create` validates the
+ * description properly and refuses a bad one with a sentence a model can act on, rather than
+ * relaying a constraint violation from Postgres.
+ *
+ * **Looking is free and asking is not.** `list` is stage one — a string comparison, no model
+ * call — and `ask` is stage two, which resumes a whole conversation and bills for it at
+ * roughly the cold-ask numbers in `fork.ts` ($0.46, 97s). They are separate verbs and
+ * separate IPC arms precisely so that an agent that cannot do the first without the second
+ * does not end up doing the second by default (§6).
+ *
+ * **A vault is readable by the service, and `popover fork` is not.** Anyone who has
+ * internalized the fork's promise will assume this one makes it too. §1 requires the publish
+ * confirmation to say otherwise out loud, so `create` prints it every time and reports
+ * `readable_by_service` in its JSON.
+ *
+ * There is deliberately no edit verb. A vault is archived, never rewritten; a correction is a
+ * `note`, which sits beside the original rather than replacing it (§2, §5). What a vault
+ * originally claimed is evidence about what the team believed at the time.
+ */
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+export async function vaultCommand(rest) {
+    const sub = rest[0] ?? "help";
+    const args = rest.slice(1);
+    switch (sub) {
+        case "create":
+            return create(args);
+        case "list":
+            return list(args);
+        case "ask":
+            return ask(args);
+        case "note":
+            return note(args);
+        case "archive":
+            return archive(args);
+        default:
+            if (sub !== "help")
+                bad(`Unknown vault command: ${sub}`);
+            vaultUsage();
+            return sub === "help" ? 0 : 1;
+    }
+}
+function vaultUsage() {
+    console.log(`
+${c.bold("popover vault")} — freeze a conversation for your team, and ask it later
+
+  ${c.bold("popover vault create")}         Publish this conversation, with a title and the questions it answers
+  ${c.bold("popover vault list")} [query]   Search your team's vaults. Free — no model runs.
+  ${c.bold("popover vault ask")} <v> "…"    Ask one vault. Loads a whole conversation, and costs money.
+  ${c.bold("popover vault note")} <v> "…"   Append a correction. Notes are added, never revised.
+  ${c.bold("popover vault archive")} <v>    Retire a vault without deleting the record that it existed.
+
+  ${c.bold("list")} before ${c.bold("ask")}, always: the first is a string comparison and the second is a
+  full context load on this machine. There is no edit — see ${c.bold("note")}.
+
+  A vault does not expire and is readable by the popover service, which is the one way
+  it differs from ${c.cyan("/popover:fork")}. ${c.bold("popover vault create")} says so again before it uploads.
+`);
+}
+// ---------------------------------------------------------------------------
+// The decisions, separated from the I/O so they can be tested
+// ---------------------------------------------------------------------------
+/**
+ * Flags that consume the token after them.
+ *
+ * Needed because a vault command's payload is free text — a question, a note — and is
+ * collected as "everything that is not a flag". Without this list, `popover vault ask v
+ * --timeout 300 why did we...` would splice `300` into the question.
+ */
+const VALUE_FLAGS = [
+    "--session",
+    "--name",
+    "--title",
+    "--answers",
+    "--repo",
+    "--limit",
+    "--timeout",
+];
+/** Everything that is not a flag and not a flag's value, in the order it was typed. */
+export function positionals(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (VALUE_FLAGS.includes(arg)) {
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--"))
+            continue;
+        out.push(arg);
+    }
+    return out;
+}
+function flag(args, name) {
+    const idx = args.indexOf(name);
+    return idx === -1 ? undefined : args[idx + 1];
+}
+/** Every occurrence of a repeatable flag. `--answers` is the only one, and it is the point. */
+export function flagAll(args, name) {
+    const out = [];
+    for (let i = 0; i < args.length; i += 1) {
+        if (args[i] === name && args[i + 1] !== undefined)
+            out.push(args[i + 1]);
+    }
+    return out;
+}
+/**
+ * Read `--answers`, which an agent may pass either repeatably or as one JSON array.
+ *
+ * Both forms exist because both are natural to generate: a shell-shaped caller repeats the
+ * flag, and a model writing a single argument writes JSON. What must not happen is the third
+ * outcome — a JSON array that fails to parse being stored verbatim as one long question, which
+ * would upload a vault whose entire retrieval surface is the string `["why did we...`. So
+ * anything that opens with `[` is committed to being JSON, and is refused rather than
+ * salvaged if it is not.
+ */
+export function parseAnswers(raw) {
+    const clean = (values) => values.map((v) => v.trim()).filter(Boolean);
+    const only = raw.length === 1 ? raw[0].trim() : undefined;
+    if (only !== undefined && only.startsWith("[")) {
+        let parsed;
+        try {
+            parsed = JSON.parse(only);
+        }
+        catch {
+            return {
+                ok: false,
+                message: "--answers starts with `[` but is not valid JSON.",
+                hints: [
+                    "Either pass a JSON array of strings, or repeat --answers once per question.",
+                    "It was not stored as-is: a vault whose only searchable question is a broken array",
+                    "would never be found again.",
+                ],
+            };
+        }
+        if (!Array.isArray(parsed) || parsed.some((a) => typeof a !== "string")) {
+            return {
+                ok: false,
+                message: "--answers as JSON has to be an array of strings.",
+                hints: ['Like: --answers \'["Why is the repo key not used for vaults?"]\''],
+            };
+        }
+        return { ok: true, answers: clean(parsed) };
+    }
+    return { ok: true, answers: clean(raw) };
+}
+/**
+ * Decide what this vault is called and whether it is describable at all, before anything is
+ * read off the network.
+ *
+ * The name is checked here rather than left to the server for two reasons. The unique index
+ * is on `lower(name)`, so `normalizeVaultName` can produce the same collision locally and say
+ * something better than a constraint violation; and a name that normalizes to nothing —
+ * a title of "???" — would otherwise reach the route as an empty string and come back as a
+ * 400 that reads like a bug in popover rather than a title worth rewriting.
+ *
+ * `answers` is the one that matters most and is the one an agent is most likely to skip.
+ * It holds *questions this conversation can answer*, not a summary, because the incoming
+ * query at retrieval time is a question and matching question against summary retrieves
+ * badly (§6). Refusing an empty list is the only moment anybody is in a position to enforce
+ * that.
+ */
+export function planVault(input) {
+    const title = (input.title ?? "").trim();
+    const answers = input.answers.map((a) => a.trim()).filter(Boolean);
+    if (!title) {
+        return {
+            ok: false,
+            code: "no_title",
+            message: "A vault needs a title.",
+            hints: [
+                "Pass one with --title. Inside Claude Code the session's own title is used when you",
+                "do not, but a session that has not been titled yet has nothing to fall back on.",
+            ],
+        };
+    }
+    if (answers.length === 0) {
+        return {
+            ok: false,
+            code: "no_answers",
+            message: "A vault needs at least one question it can answer.",
+            hints: [
+                "Pass them with --answers, repeated or as a JSON array. These are questions, not a",
+                "summary: the query that finds this vault later will be a question, and matching a",
+                "question against a summary retrieves badly. See docs/vaults.md §6.",
+            ],
+        };
+    }
+    const described = VaultDescriptionSchema.safeParse({ title, answers });
+    if (!described.success) {
+        const issue = described.error.issues[0];
+        return {
+            ok: false,
+            code: "bad_description",
+            message: `That description cannot be published: ${issue?.path.join(".") ?? "description"} ${issue?.message ?? "is invalid"}.`,
+            hints: [
+                "A title is 3 to 120 characters; each answer is 8 to 200, and there can be at most 12.",
+            ],
+        };
+    }
+    const typed = input.name?.trim();
+    const name = normalizeVaultName(typed && typed.length > 0 ? typed : described.data.title);
+    if (!isVaultName(name)) {
+        const source = typed ? `\`${typed}\`` : `the title "${described.data.title}"`;
+        return {
+            ok: false,
+            code: "bad_name",
+            message: name.length === 0
+                ? `${source} leaves nothing usable as a vault name.`
+                : `\`${name}\`, from ${source}, is not a usable vault name.`,
+            hints: [
+                "Names are lowercase letters, digits and hyphens, 3 to 64 characters — they end up in",
+                "URLs and in the command your teammates type. Pass one directly with --name.",
+            ],
+        };
+    }
+    return { ok: true, name, title: described.data.title, answers: described.data.answers };
+}
+/**
+ * Which vault a typed reference means: by id, then exact name, then unique prefix.
+ *
+ * Every match is returned rather than the first, and the same widening `resolveTeam` does is
+ * used, for the same reason: two names sharing a prefix is a real arrangement, and asking the
+ * wrong vault costs a dollar and produces a confident answer about the wrong subsystem, which
+ * is the failure nobody notices.
+ */
+export function resolveVaultRef(vaults, typed) {
+    const needle = typed.trim().toLowerCase();
+    if (!needle)
+        return { kind: "none" };
+    const byId = vaults.filter((v) => v.id.toLowerCase() === needle);
+    if (byId.length === 1)
+        return { kind: "one", vault: byId[0] };
+    const exact = vaults.filter((v) => v.name.toLowerCase() === needle);
+    if (exact.length === 1)
+        return { kind: "one", vault: exact[0] };
+    // Unique per team, not globally, so a person on two teams can genuinely see two.
+    if (exact.length > 1)
+        return { kind: "many", matches: exact };
+    const prefix = vaults.filter((v) => v.name.toLowerCase().startsWith(needle));
+    if (prefix.length === 1)
+        return { kind: "one", vault: prefix[0] };
+    if (prefix.length > 1)
+        return { kind: "many", matches: prefix };
+    return { kind: "none" };
+}
+/**
+ * Whether a reference is already an id, so no lookup is needed to use it.
+ *
+ * The full UUID shape rather than "has hyphens", because vault names have hyphens in them by
+ * construction — `repo-key-gating` is the example the spec itself uses. Treating one as an id
+ * would POST a note to `/api/vaults/repo-key-gating/notes` and report the 404 as a missing
+ * vault, when the vault is right there under a name we simply never resolved.
+ */
+export function looksLikeVaultId(ref) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(ref.trim());
+}
+/**
+ * The freeze date, in the form §4 writes it: `15 Aug 2026`.
+ *
+ * The locale is pinned rather than left to the machine because this string is part of an
+ * attribution that gets pasted into other conversations and read by other models, so
+ * `8/15/2026` on one laptop and `15/08/2026` on the next is an ambiguity with no upside.
+ */
+export function freezeDate(iso) {
+    const when = Date.parse(iso);
+    if (Number.isNaN(when))
+        return iso;
+    return new Date(when).toLocaleDateString("en-GB", {
+        day: "numeric",
+        month: "short",
+        year: "numeric",
+    });
+}
+/**
+ * The sentence a vault's answer is always wrapped in.
+ *
+ * Never optional, and never assembled by the caller. A human reading an answer supplies the
+ * skepticism unprompted; an agent will not unless the format forces it, and a vault can hold
+ * a hypothesis the team later disproved. So the title and the freeze date travel on
+ * `VaultAnswer` itself and this turns them into the one line that must precede the answer —
+ * including in `--json`, where the assembled string is a field rather than a suggestion.
+ */
+export function attribution(answer) {
+    const at = answer.gitSha ? ` at ${answer.gitSha.slice(0, 7)}` : "";
+    return `The ${answer.title} vault, frozen ${freezeDate(answer.frozenAt)}${at}, says:`;
+}
+/**
+ * How a staleness score reads to a person.
+ *
+ * Words rather than the number, because the number is a ratio of paths and nobody ranks
+ * vaults by reading ratios. A vault that recorded no paths at all scores 0 the same way an
+ * untouched one does — `stalenessScore` deliberately does not punish absent evidence — so
+ * "nothing it touched has changed" is only claimed when the server sent a score at all.
+ */
+export function stalenessNote(staleness) {
+    if (staleness === undefined)
+        return "";
+    if (staleness === 0)
+        return "nothing it touched has changed";
+    if (staleness >= 0.5)
+        return "most of what it touched has changed";
+    return "some of what it touched has changed";
+}
+/** One vault as a person reads it in a list: a heading, a byline, and its questions. */
+export function summaryLines(v) {
+    const facts = [
+        v.authorLabel,
+        `frozen ${freezeDate(v.frozenAt)}`,
+        v.repoLabel ?? "",
+        v.noteCount === 0 ? "" : `${v.noteCount} note${v.noteCount === 1 ? "" : "s"}`,
+        stalenessNote(v.staleness),
+    ].filter(Boolean);
+    return [`${v.name}  ${v.title}`, facts.join(" · "), ...v.answers.map((a) => `? ${a}`)];
+}
+/**
+ * One vault as a script reads it.
+ *
+ * Absent values are `null` rather than missing, because the consumer is usually a model
+ * deciding whether to spend a dollar on stage two, and a key that is sometimes there reads as
+ * a key it forgot to look at.
+ */
+export function summaryJson(v) {
+    return {
+        id: v.id,
+        name: v.name,
+        title: v.title,
+        answers: v.answers,
+        author_label: v.authorLabel,
+        repo_label: v.repoLabel ?? null,
+        frozen_at: v.frozenAt,
+        note_count: v.noteCount,
+        staleness: v.staleness ?? null,
+    };
+}
+/**
+ * Read a listing from the HTTP route, accepting either spelling of its fields.
+ *
+ * The IPC path parses `VaultSummarySchema` and gets camelCase by construction. The HTTP route
+ * is written in another package against §10, which names those same columns `author_label`,
+ * `created_at` and `note_count` — so both spellings are plausible and neither is worth a
+ * cross-package coordination round to settle. Accepting both here costs a few lines and means
+ * `note` and `archive` cannot be broken by a naming choice made in `apps/web`.
+ *
+ * Returns null for a body that is not a listing at all, which is what an SSO proxy or a
+ * protected preview answers with — see `ApiFailure.malformed`.
+ */
+export function readSummaries(body) {
+    const rows = body?.vaults;
+    if (!Array.isArray(rows))
+        return null;
+    const out = [];
+    for (const raw of rows) {
+        if (typeof raw !== "object" || raw === null)
+            return null;
+        const r = raw;
+        const str = (camel, snake) => {
+            const value = r[camel] ?? r[snake];
+            return typeof value === "string" ? value : undefined;
+        };
+        const num = (camel, snake) => {
+            const value = r[camel] ?? r[snake];
+            return typeof value === "number" ? value : undefined;
+        };
+        const id = str("id", "id");
+        const name = str("name", "name");
+        const title = str("title", "title");
+        if (id === undefined || name === undefined || title === undefined)
+            return null;
+        out.push({
+            id,
+            name,
+            title,
+            answers: Array.isArray(r["answers"])
+                ? r["answers"].filter((a) => typeof a === "string")
+                : [],
+            authorLabel: str("authorLabel", "author_label") ?? "",
+            repoLabel: str("repoLabel", "repo_label"),
+            frozenAt: str("frozenAt", "frozen_at") ?? "",
+            noteCount: num("noteCount", "note_count") ?? 0,
+        });
+    }
+    return out;
+}
+/**
+ * Keep `--limit` inside what the daemon's schema will accept.
+ *
+ * Clamped rather than relayed, because `VaultSearchRequestSchema` caps it at 50 and floors it
+ * at 1, and a rejected request comes back as a generic `bad_request` from the daemon that
+ * says nothing about the number somebody typed.
+ */
+export function clampLimit(raw, fallback = 20) {
+    const n = Number(raw);
+    if (raw === undefined || raw === "" || !Number.isFinite(n))
+        return fallback;
+    return Math.min(50, Math.max(1, Math.trunc(n)));
+}
+/** Same clamp, for `--timeout`, whose schema window is 5 to 600 seconds. */
+export function clampTimeout(raw, fallback = 90) {
+    const n = Number(raw);
+    if (raw === undefined || raw === "" || !Number.isFinite(n))
+        return fallback;
+    return Math.min(600, Math.max(5, Math.trunc(n)));
+}
+/**
+ * Tools whose input names a file this conversation's reasoning rests on.
+ *
+ * Reads are in the set, and that is the point rather than an oversight. What a conversation
+ * concluded depends on what it *read* at least as much as on what it changed — an archaeology
+ * vault ("why is the backoff 400ms") typically writes nothing at all — and those are exactly
+ * the vaults worth keeping, so they must be able to go stale like any other.
+ */
+const PATH_TOOLS = new Set(["Read", "Edit", "Write", "MultiEdit", "NotebookEdit"]);
+/**
+ * The files this conversation read or wrote, from the transcript itself.
+ *
+ * This is the primary source for `touched_paths`, and the working tree is the secondary one,
+ * which is the opposite of how it first looked. `touched_paths` exists to answer "does this
+ * conversation's reasoning depend on files that have since changed", and `git status` answers
+ * a narrower question: what was uncommitted at the moment somebody vaulted. Two ordinary
+ * cases fall through that gap — a conversation that committed its work before vaulting, and a
+ * read-only conversation that changed nothing — and both land on an empty list.
+ *
+ * Empty is not neutral. `stalenessScore` deliberately returns 0 for a vault that recorded no
+ * paths, on the correct reasoning that absence of evidence is not churn; so a vault with an
+ * empty list ranks as permanently current and never decays. The two behaviours are each right
+ * and together wrong, and the read-heavy vaults they hit hardest are the valuable ones.
+ *
+ * Paths that do not fall under any of `roots` are dropped rather than stored absolute. They
+ * could never match a path from `git status`, so keeping them would only pad the denominator
+ * of `hits / touchedPaths.length` and make every vault look more current than it is.
+ */
+export function collectToolPaths(entries, roots, cap = 500) {
+    // Matched in the order given, first hit winning, because the caller puts the repo root
+    // first: `git status --porcelain` prints paths relative to the repo root regardless of
+    // config, so stripping a deeper cwd instead would produce paths that can never line up.
+    const prepared = roots.map(normalizeSlashes).filter(Boolean);
+    const out = [];
+    for (const entry of entries) {
+        const content = entry["message"]?.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (typeof block !== "object" || block === null)
+                continue;
+            const b = block;
+            if (b.type !== "tool_use")
+                continue;
+            if (typeof b.name !== "string" || !PATH_TOOLS.has(b.name))
+                continue;
+            const input = b.input;
+            for (const key of ["file_path", "notebook_path"]) {
+                const raw = input?.[key];
+                if (typeof raw !== "string" || !raw)
+                    continue;
+                const rel = relativizePath(raw, prepared);
+                if (rel && !isUncomparable(rel) && !out.includes(rel))
+                    out.push(rel);
+            }
+        }
+    }
+    return out.slice(0, cap);
+}
+function normalizeSlashes(p) {
+    return p.trim().replace(/\\/g, "/").replace(/\/+$/, "");
+}
+/**
+ * Paths inside the repo that git will still never report as changed.
+ *
+ * The same dilution problem as an out-of-root path, arrived at from the other side: reading a
+ * dependency's type definitions is a real thing a conversation did, but `node_modules` is
+ * ignored everywhere, so that path can never appear in `git status` and can only ever pad the
+ * denominator of `hits / touchedPaths.length`. Seen in practice — a single 15MB transcript
+ * contributed one — and a handful of them is enough to drag a churned vault back down toward
+ * looking current.
+ */
+function isUncomparable(rel) {
+    return /(^|\/)(node_modules|\.git)\//.test(rel);
+}
+function isAbsolutePath(p) {
+    return p.startsWith("/") || /^[a-zA-Z]:\//.test(p);
+}
+/**
+ * A tool's path as `git status` would spell it, or null if the two can never be compared.
+ *
+ * Case-insensitive, because Windows and macOS both hand back a path whose case need not match
+ * what git prints, and a false negative here silently understates churn.
+ */
+function relativizePath(raw, roots) {
+    const p = normalizeSlashes(raw);
+    if (!p)
+        return null;
+    for (const root of roots) {
+        if (p.length > root.length + 1 && p.toLowerCase().startsWith(`${root.toLowerCase()}/`)) {
+            return p.slice(root.length + 1);
+        }
+    }
+    // A tool call that already used a repo-relative path needs no rewriting; an absolute one
+    // outside every root belongs to another repository or to the user's home.
+    return isAbsolutePath(p) ? null : p.replace(/^\.\//, "");
+}
+/**
+ * The two sources, deduped and capped once.
+ *
+ * The transcript comes first so that it survives truncation: if a conversation named more
+ * than the cap on its own, what it read and wrote is a better description of what it depended
+ * on than whatever happened to be dirty in the tree at the time.
+ */
+export function unionPaths(primary, secondary, cap = 500) {
+    const out = [];
+    for (const p of [...primary, ...secondary]) {
+        if (p && !out.includes(p))
+            out.push(p);
+    }
+    return out.slice(0, cap);
+}
+/**
+ * The uncommitted half, from `git status --porcelain`.
+ *
+ * Unioned with `collectToolPaths` rather than replaced by it, because work that a conversation
+ * left dirty is genuine evidence about what it touched — it is only insufficient on its own.
+ *
+ * Renames are recorded at their destination: `R  old -> new` is churn in `new`, and ranking a
+ * vault against a path that no longer exists would make every renamed file look permanently
+ * untouched. Quoted paths are unescaped because `core.quotePath` is on by default and a
+ * filename with an accent in it would otherwise be stored complete with its surrounding
+ * quotes and never match anything.
+ *
+ * The cap is `VaultIndexSchema`'s 500. A conversation that dirtied more than that is a
+ * generated-file situation where the first 500 are as good a signal as any.
+ */
+export function parseTouchedPaths(porcelain, cap = 500) {
+    const paths = [];
+    for (const line of porcelain.split("\n")) {
+        if (line.length < 4)
+            continue;
+        let rest = line.slice(3);
+        const arrow = rest.indexOf(" -> ");
+        if (arrow !== -1)
+            rest = rest.slice(arrow + 4);
+        const path = unquotePath(rest.trim());
+        if (path && !paths.includes(path))
+            paths.push(path);
+    }
+    return paths.slice(0, cap);
+}
+const SIMPLE_ESCAPES = { n: 10, t: 9, r: 13, b: 8, f: 12, a: 7, v: 11 };
+/**
+ * Undo git's C-style quoting.
+ *
+ * The escapes are *octal bytes*, not characters: `café.ts` comes back as
+ * `"caf\303\251.ts"`, which is the two UTF-8 bytes of `é` written one escape each. Stripping
+ * backslashes the obvious way turns that into `caf303251.ts` — a path that exists nowhere, so
+ * the vault ranks as untouched against a file it actually changed. So the escapes are decoded
+ * to bytes and the bytes are decoded as UTF-8, in that order.
+ */
+function unquotePath(raw) {
+    if (raw.length < 2 || !raw.startsWith('"') || !raw.endsWith('"'))
+        return raw;
+    const inner = raw.slice(1, -1);
+    const bytes = [];
+    for (let i = 0; i < inner.length; i += 1) {
+        const ch = inner[i];
+        if (ch !== "\\") {
+            bytes.push(...Buffer.from(ch, "utf8"));
+            continue;
+        }
+        const next = inner[i + 1];
+        if (next === undefined)
+            break;
+        const octal = inner.slice(i + 1, i + 4);
+        if (/^[0-7]{3}$/.test(octal)) {
+            bytes.push(parseInt(octal, 8));
+            i += 3;
+            continue;
+        }
+        bytes.push(SIMPLE_ESCAPES[next] ?? Buffer.from(next, "utf8")[0]);
+        i += 1;
+    }
+    return Buffer.from(bytes).toString("utf8");
+}
+/**
+ * A commit sha, or nothing.
+ *
+ * `git rev-parse HEAD` in a repository with no commits prints the literal string `HEAD` and
+ * exits nonzero on some versions and zero on others. `VaultIndexSchema.gitSha` is a hex regex,
+ * so letting that through turns a first-commit-pending repo into a 400 from the create route
+ * that reads as a popover bug rather than as "there is no commit yet".
+ */
+export function cleanSha(raw) {
+    const sha = raw?.trim().toLowerCase();
+    return sha && /^[0-9a-f]{7,40}$/.test(sha) ? sha : undefined;
+}
+/**
+ * The transcript, compressed, as one opaque string.
+ *
+ * Deliberately **not** `sealSnapshot`. That derives its AES key from the fork code, and a
+ * vault has no code — team membership is the whole credential, which is exactly the decision
+ * §1 records and the reason the server can read a vault at all. Encrypting here with a key
+ * stored beside the ciphertext would be worse than not encrypting: a promise that reads as
+ * strong and is not. The real protection is at-rest encryption under a key held outside the
+ * database, which is the server's to do.
+ *
+ * gzip + base64 anyway, because `body` is one opaque column by design (§2) so a later
+ * end-to-end version can wrap a per-vault key around this without moving anything else, and
+ * because a transcript compresses about 10:1.
+ */
+export function packBody(envelope) {
+    return gzipSync(Buffer.from(JSON.stringify(envelope), "utf8")).toString("base64");
+}
+// ---------------------------------------------------------------------------
+// popover vault create
+// ---------------------------------------------------------------------------
+async function create(args) {
+    const asJson = args.includes("--json");
+    const sessionId = flag(args, "--session") ??
+        process.env["CLAUDE_SESSION_ID"] ??
+        process.env["CLAUDE_CODE_SESSION_ID"];
+    if (!sessionId) {
+        return fail(asJson, "no_session", "There is no session here to vault.", [
+            "Run /popover:vault create inside Claude Code, which knows which session you are in,",
+            "or pass one explicitly with --session <id>.",
+        ]);
+    }
+    const credentials = loadCredentials();
+    if (!credentials) {
+        return fail(asJson, "not_signed_in", "This machine is not signed in.", [
+            "Run `popover login` first. A vault is published to a team, so it needs an account.",
+        ]);
+    }
+    const transcriptPath = findTranscript(sessionId);
+    if (!transcriptPath) {
+        return fail(asJson, "no_transcript", "That session has no transcript on disk.", [
+            "A brand-new session may not have been written yet, and CLAUDE_CODE_SKIP_PROMPT_HISTORY",
+            "turns transcript writing off entirely. There is nothing to freeze either way.",
+        ]);
+    }
+    // The transcript lags the live conversation, so wait for it to stop moving. `frozenAt`
+    // below is what says where the cut actually landed.
+    await settle(transcriptPath);
+    const size = statSync(transcriptPath).size;
+    if (size > MAX_TRANSCRIPT_BYTES) {
+        return fail(asJson, "too_large", `That conversation is ${mb(size)} MB, over the ${mb(MAX_TRANSCRIPT_BYTES)} MB limit.`, ["Run /compact first, then vault the compacted session."]);
+    }
+    const parsed = parseTranscript(readFileSync(transcriptPath, "utf8"));
+    // Sanitizing matters more here than for a fork. Attachments carry the author's hooks, skill
+    // listing and agent roster, and a vault is read months later, by which time those are not
+    // merely stale — they describe a machine that no longer exists. docs/vaults.md §3.
+    const { entries, dropped } = sanitizeTranscript(parsed);
+    if (entries.length === 0) {
+        return fail(asJson, "empty", "There is nothing in this conversation to vault yet.", []);
+    }
+    const answers = parseAnswers(flagAll(args, "--answers"));
+    if (!answers.ok)
+        return fail(asJson, "bad_answers", answers.message, answers.hints);
+    const plan = planVault({
+        name: flag(args, "--name"),
+        title: flag(args, "--title") ?? readTitle(parsed),
+        answers: answers.answers,
+    });
+    if (!plan.ok)
+        return fail(asJson, plan.code, plan.message, plan.hints);
+    const cwd = process.cwd();
+    const repo = readRepo(cwd);
+    // The normalized remote rather than the directory name: `repo_label` is used to filter a
+    // list several people are looking at, and a directory name is whatever each of them happened
+    // to call their clone. It is display and filtering only and must never reach a policy (§8).
+    const repoLabel = repo.keys[0] ?? repo.name;
+    const gitSha = cleanSha(git(cwd, ["rev-parse", "HEAD"]));
+    // Repo root first: porcelain output is relative to it, so that is the spelling the two
+    // sources have to agree on before they can be unioned.
+    const pathRoots = [repo.root, ...collectPathRoots(entries), cwd].filter((r) => typeof r === "string" && r.length > 0);
+    const touchedPaths = unionPaths(collectToolPaths(entries, pathRoots), parseTouchedPaths(git(cwd, ["status", "--porcelain"]) ?? ""));
+    const transcript = entries.map((e) => JSON.stringify(e)).join("\n") + "\n";
+    // The envelope's last turn, not the upload time. What a reader cares about is when the
+    // conversation stopped, not when somebody got around to publishing it (§2).
+    const frozenAt = lastTimestamp(entries) ?? new Date().toISOString();
+    const index = VaultIndexSchema.safeParse({
+        formatVersion: VAULT_FORMAT_VERSION,
+        name: plan.name,
+        title: plan.title,
+        answers: plan.answers,
+        repoLabel,
+        gitSha,
+        touchedPaths,
+        entryCount: entries.length,
+        byteSize: Buffer.byteLength(transcript, "utf8"),
+        frozenAt,
+    });
+    if (!index.success) {
+        return fail(asJson, "bad_description", "That vault is not something the index will accept.", index.error.issues.map((i) => `${i.path.join(".") || "index"}: ${i.message}`));
+    }
+    const envelope = {
+        formatVersion: SNAPSHOT_FORMAT_VERSION,
+        createdAt: new Date().toISOString(),
+        entryCount: entries.length,
+        transcript,
+        repoRemotes: repo.keys,
+        // Collected from the transcript as well as from git, because the two spell the same
+        // directory differently whenever a symlink is involved.
+        pathRoots: [...new Set([...collectPathRoots(entries), ...(repo.root ? [repo.root] : []), cwd])],
+        lastTurnAt: frozenAt,
+        title: plan.title,
+        repoName: repo.name,
+        gitBranch: repo.branch,
+        repoRoot: repo.root,
+        cwd,
+    };
+    const result = await request(credentials.device_token, "POST", `${apiBase()}/api/vaults`, { ...index.data, body: packBody(envelope) });
+    if (!result.ok) {
+        if (result.status === 409 && result.ours) {
+            return fail(asJson, "name_taken", `Your team already has a vault called \`${plan.name}\`.`, [
+                "Names are unique per team, case-insensitively, and a vault is never edited or",
+                "replaced. Pick another with --name, or add to the existing one with `popover vault",
+                `note ${plan.name} "…"\`.`,
+            ]);
+        }
+        return reportApiFailure(result, asJson, "Publishing this vault");
+    }
+    const id = typeof result.body.id === "string" ? result.body.id : null;
+    const name = typeof result.body.name === "string" ? result.body.name : plan.name;
+    if (asJson) {
+        console.log(JSON.stringify({
+            ok: true,
+            id,
+            name,
+            title: plan.title,
+            answers: plan.answers,
+            entry_count: entries.length,
+            dropped,
+            byte_size: index.data.byteSize,
+            frozen_at: frozenAt,
+            git_sha: gitSha ?? null,
+            repo_label: repoLabel ?? null,
+            touched_paths: touchedPaths,
+            // Stated structurally, not only in prose, because the caller is usually the agent
+            // that decided to vault and it is the one fact about a vault that differs from a
+            // fork. docs/vaults.md §1.
+            readable_by_service: true,
+            ask_command: `popover vault ask ${name} "<question>"`,
+        }));
+        return 0;
+    }
+    console.log("");
+    ok(`Vaulted ${entries.length} messages as ${c.bold(c.cyan(name))}.`);
+    console.log("");
+    info(`${plan.title}`);
+    for (const answer of plan.answers)
+        dim(`? ${answer}`);
+    console.log("");
+    info("Anyone on your team can ask it, on their own machine and at their own cost:");
+    dim(`  popover vault ask ${name} "…"`);
+    console.log("");
+    dim(`Frozen at the last completed turn (${freezeDate(frozenAt)}). Nothing said from here is included.`);
+    dim("It does not expire. `popover vault archive` retires it without erasing the record.");
+    console.log("");
+    // Said every time, in the same register the fork confirmation uses. Anyone who has
+    // internalized `/popover:fork` being end-to-end will assume this is too, and it is not.
+    warn("A vault is readable by the popover service. `popover fork` is not — this differs.");
+    dim("It is encrypted at rest, but not end-to-end. Publish accordingly.");
+    console.log("");
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// popover vault list — stage one
+// ---------------------------------------------------------------------------
+/**
+ * Stage one, through the daemon rather than straight to HTTP.
+ *
+ * The daemon is the same path the MCP tool takes, so a person typing this and an agent
+ * calling `vaults` get the same ranking — including the staleness half, which needs the
+ * caller's working directory to diff against and so cannot be computed by the server (§6).
+ * Going direct would produce two search implementations that drift.
+ */
+async function list(args) {
+    const asJson = args.includes("--json");
+    const query = positionals(args).join(" ").trim();
+    const repo = flag(args, "--repo");
+    const limit = clampLimit(flag(args, "--limit"));
+    const reply = await askDaemon({
+        t: "vaults",
+        id: "vault-list",
+        req: { query: query || undefined, repo, limit },
+        cwd: process.cwd(),
+    }, 20_000);
+    if (!reply)
+        return daemonSilent(asJson);
+    if (reply.t === "error")
+        return fail(asJson, reply.code, reply.message, []);
+    if (reply.t !== "vaults.ok")
+        return unexpectedReply(asJson);
+    const { vaults } = reply;
+    if (asJson) {
+        console.log(JSON.stringify({
+            ok: true,
+            query: query || null,
+            repo: repo ?? null,
+            count: vaults.length,
+            vaults: vaults.map(summaryJson),
+        }));
+        return 0;
+    }
+    if (vaults.length === 0) {
+        warn(query ? `No vaults match ${JSON.stringify(query)}.` : "Your team has no vaults yet.");
+        dim(query
+            ? "Stage one is lexical, so try the words the conversation itself would have used."
+            : "Vault one with `popover vault create` — or let your agent decide to.");
+        return 0;
+    }
+    console.log("");
+    for (const vault of vaults) {
+        // The heading is rebuilt here rather than taken from `summaryLines`, which is the plain
+        // form the tests pin; only the colour of the name differs.
+        const [, facts, ...questions] = summaryLines(vault);
+        console.log(`  ${c.bold(c.cyan(vault.name))}  ${vault.title}`);
+        if (facts)
+            dim(facts);
+        for (const question of questions)
+            dim(`  ${question}`);
+        console.log("");
+    }
+    dim(`Asking one loads its whole conversation on this machine: popover vault ask <name> "…"`);
+    console.log("");
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// popover vault ask — stage two
+// ---------------------------------------------------------------------------
+async function ask(args) {
+    const asJson = args.includes("--json");
+    const words = positionals(args);
+    const ref = words[0];
+    const question = words.slice(1).join(" ").trim();
+    if (!ref || !question) {
+        return fail(asJson, "bad_request", "Asking a vault takes a vault and a question.", [
+            'Usage: popover vault ask <name|id> "<question>"',
+            "Run `popover vault list` first — searching is free and this is not.",
+        ]);
+    }
+    const timeoutSeconds = clampTimeout(flag(args, "--timeout"));
+    // Resolved through the daemon's own search rather than a separate lookup, so a name and an
+    // id reach the same vault and the caller never has to know which one they have.
+    const vaultId = looksLikeVaultId(ref) ? ref : await resolveThroughDaemon(ref, asJson);
+    if (typeof vaultId !== "string")
+        return vaultId;
+    const reply = await askDaemon({
+        t: "vaultAsk",
+        id: "vault-ask",
+        req: { vaultId, question, timeoutSeconds },
+        cwd: process.cwd(),
+    }, 
+    // Past the ask's own deadline, so a vault that times out reports as a timeout rather
+    // than as a daemon that stopped answering.
+    timeoutSeconds * 1000 + 15_000);
+    if (!reply)
+        return daemonSilent(asJson);
+    if (reply.t === "error")
+        return fail(asJson, reply.code, reply.message, hintsForCode(reply.code));
+    if (reply.t !== "vaultAsk.ok")
+        return unexpectedReply(asJson);
+    return renderAnswer(reply.answer, asJson);
+}
+function renderAnswer(answer, asJson) {
+    const line = attribution(answer);
+    if (answer.status !== "answered" || !answer.answer) {
+        return fail(asJson, answer.status === "timeout" ? "timeout" : "vault_ask_failed", answer.status === "timeout"
+            ? `${answer.title} did not finish answering in time.`
+            : `${answer.title} could not answer that.`, [
+            answer.error ?? "The vault was loaded but produced no answer.",
+            answer.status === "timeout"
+                ? "A cold vault takes about 90 seconds. Raise it with --timeout <seconds>."
+                : "Nothing was charged for a failed load beyond what it managed to run.",
+        ]);
+    }
+    if (asJson) {
+        console.log(JSON.stringify({
+            ok: true,
+            vault_id: answer.vaultId,
+            title: answer.title,
+            frozen_at: answer.frozenAt,
+            git_sha: answer.gitSha ?? null,
+            status: answer.status,
+            // The assembled sentence, not just its parts. A caller that has to build the
+            // attribution is a caller that can forget to, and this answer may be a hypothesis
+            // the team has since disproved. docs/vaults.md §4.
+            attribution: line,
+            answer: answer.answer,
+            duration_ms: answer.durationMs ?? null,
+            cost_usd: answer.costUsd ?? null,
+        }));
+        return 0;
+    }
+    console.log("");
+    info(c.bold(line));
+    console.log("");
+    console.log(answer.answer);
+    console.log("");
+    dim("Frozen: it is authoritative about what was decided, not about the code as it is now.");
+    if (answer.costUsd !== undefined || answer.durationMs !== undefined) {
+        const cost = answer.costUsd === undefined ? "" : `$${answer.costUsd.toFixed(2)}`;
+        const secs = answer.durationMs === undefined ? "" : `${Math.round(answer.durationMs / 1000)}s`;
+        dim([cost, secs].filter(Boolean).join(" · ") + ", on this machine.");
+    }
+    console.log("");
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// popover vault note
+// ---------------------------------------------------------------------------
+/**
+ * Append a note. There is no verb that edits one, and there is not going to be.
+ *
+ * The motivating case is a vault that confidently explains a decision later reversed. Editing
+ * the description would erase what the team believed at the time, which is the evidence the
+ * archive exists to hold; a note records both, dated and attributed, beside the original (§5).
+ * Notes are searched alongside `answers`, so a correction is frequently the thing that decides
+ * whether a vault is worth the stage-two spend at all.
+ */
+async function note(args) {
+    const asJson = args.includes("--json");
+    const words = positionals(args);
+    const ref = words[0];
+    const body = words.slice(1).join(" ").trim();
+    if (!ref || !body) {
+        return fail(asJson, "bad_request", "Adding a note takes a vault and the note.", [
+            'Usage: popover vault note <name|id> "<what changed>"',
+            "A note is appended, never edited in, and never replaces what the vault already says.",
+        ]);
+    }
+    const credentials = loadCredentials();
+    if (!credentials) {
+        return fail(asJson, "not_signed_in", "This machine is not signed in.", [
+            "Run `popover login` first.",
+        ]);
+    }
+    const target = await resolveThroughApi(credentials.device_token, ref, asJson);
+    if (typeof target !== "object")
+        return target;
+    const result = await request(credentials.device_token, "POST", `${apiBase()}/api/vaults/${encodeURIComponent(target.id)}/notes`, { body });
+    if (!result.ok)
+        return reportApiFailure(result, asJson, "Adding a note");
+    const createdAt = typeof result.body.created_at === "string" ? result.body.created_at : new Date().toISOString();
+    if (asJson) {
+        console.log(JSON.stringify({
+            ok: true,
+            id: typeof result.body.id === "string" ? result.body.id : null,
+            vault_id: target.id,
+            vault_name: target.name,
+            body,
+            created_at: createdAt,
+        }));
+        return 0;
+    }
+    ok(`Noted on ${c.bold(target.name)}.`);
+    dim("It sits beside what the vault already said, which is unchanged. Notes are searched too.");
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// popover vault archive
+// ---------------------------------------------------------------------------
+async function archive(args) {
+    const asJson = args.includes("--json");
+    const ref = positionals(args)[0];
+    if (!ref) {
+        return fail(asJson, "bad_request", "Archiving takes a vault.", [
+            "Usage: popover vault archive <name|id>",
+        ]);
+    }
+    const credentials = loadCredentials();
+    if (!credentials) {
+        return fail(asJson, "not_signed_in", "This machine is not signed in.", [
+            "Run `popover login` first.",
+        ]);
+    }
+    const target = await resolveThroughApi(credentials.device_token, ref, asJson);
+    if (typeof target !== "object")
+        return target;
+    const result = await request(credentials.device_token, "POST", `${apiBase()}/api/vaults/${encodeURIComponent(target.id)}/archive`);
+    if (!result.ok)
+        return reportApiFailure(result, asJson, "Archiving this vault");
+    if (asJson) {
+        console.log(JSON.stringify({
+            ok: true,
+            id: target.id,
+            name: target.name,
+            archived_at: new Date().toISOString(),
+        }));
+        return 0;
+    }
+    ok(`Archived ${c.bold(target.name)}.`);
+    // `archived_at` exists partly so that a vault the agent should not have made can be retired
+    // without deleting the evidence that it was made — which is how the §3 bet gets audited.
+    dim("It drops out of search. The record that it existed, and who made it, does not.");
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// Resolving a name to an id
+// ---------------------------------------------------------------------------
+/** A vault id on success; an exit code on failure, already reported. */
+async function resolveThroughDaemon(ref, asJson) {
+    const reply = await askDaemon({ t: "vaults", id: "vault-resolve", req: { query: ref, limit: 50 }, cwd: process.cwd() }, 20_000);
+    if (!reply)
+        return daemonSilent(asJson);
+    if (reply.t === "error")
+        return fail(asJson, reply.code, reply.message, []);
+    if (reply.t !== "vaults.ok")
+        return unexpectedReply(asJson);
+    const match = resolveVaultRef(reply.vaults, ref);
+    if (match.kind === "one")
+        return match.vault.id;
+    return reportNoMatch(match, ref, asJson);
+}
+async function resolveThroughApi(deviceToken, ref, asJson) {
+    // An id needs no listing at all, which also means these two verbs keep working against a
+    // vault that has fallen off the end of a truncated list.
+    if (looksLikeVaultId(ref))
+        return { id: ref, name: ref };
+    const result = await request(deviceToken, "GET", `${apiBase()}/api/vaults?query=${encodeURIComponent(ref)}`);
+    if (!result.ok)
+        return reportApiFailure(result, asJson, "Looking up that vault");
+    const vaults = readSummaries(result.body);
+    if (!vaults) {
+        return fail(asJson, "unexpected_response", `${apiBase()} answered, but not with vaults.`, [
+            "Either something is standing in front of the API — an SSO proxy or a protected preview",
+            "answers a signed-out request with a login page rather than a refusal — or this backend",
+            "predates vaults. Check POPOVER_API_URL, then run `popover update`.",
+        ]);
+    }
+    const match = resolveVaultRef(vaults, ref);
+    if (match.kind === "one")
+        return { id: match.vault.id, name: match.vault.name };
+    return reportNoMatch(match, ref, asJson);
+}
+function reportNoMatch(match, ref, asJson) {
+    if (match.kind === "many") {
+        return fail(asJson, "ambiguous_vault", `\`${ref}\` matches ${match.matches.length} vaults.`, [
+            `Name one of them exactly: ${match.matches.map((v) => v.name).join(", ")}`,
+            "Or pass the id, which `popover vault list --json` prints.",
+        ]);
+    }
+    return fail(asJson, "vault_not_found", `No vault your team can see is called \`${ref}\`.`, [
+        "Run `popover vault list` to see what there is. A vault is visible to its whole team and",
+        "to nobody else, regardless of which repo you are standing in.",
+    ]);
+}
+// ---------------------------------------------------------------------------
+// Talking to the daemon
+// ---------------------------------------------------------------------------
+function daemonSilent(asJson) {
+    return fail(asJson, "daemon_unreachable", "The popover daemon is not responding.", [
+        "Start it with `popover daemon start`, or check `popover doctor`.",
+    ]);
+}
+function unexpectedReply(asJson) {
+    return fail(asJson, "unexpected_response", "Unexpected response from the daemon.", [
+        "The daemon may be older than this CLI. Run `popover update`.",
+    ]);
+}
+function hintsForCode(code) {
+    if (code === "vault_not_found") {
+        return ["It may have been archived since you listed it. Run `popover vault list` again."];
+    }
+    if (code === "not_authenticated")
+        return ["Run `popover login` to reconnect this machine."];
+    if (code === "cloud_unreachable")
+        return ["Check the network, then try again."];
+    return [];
+}
+/**
+ * The device token, on every vault route.
+ *
+ * `Authorization: Bearer` rather than the token-in-body scheme `/api/fork/*` uses, and pinned
+ * that way in docs/vaults.md §10 for the reason already written at `repos.ts:799`: one of
+ * these routes is a GET with no body to put a token in, and splitting the scheme across
+ * methods is worse than moving it for all of them.
+ */
+function authHeaders(deviceToken) {
+    return { authorization: `Bearer ${deviceToken}`, "content-type": "application/json" };
+}
+async function request(deviceToken, method, url, body) {
+    let res;
+    try {
+        res = await fetch(url, {
+            method,
+            headers: authHeaders(deviceToken),
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            signal: AbortSignal.timeout(20_000),
+        });
+    }
+    catch (err) {
+        // Reported as a status of 0, which nothing else can produce, so `httpHeadline` can say
+        // "could not reach" rather than inventing a code.
+        return { ok: false, status: 0, ours: false, error: String(err) };
+    }
+    if (res.ok) {
+        // A 201 with no body is legal, and `json()` on an empty body throws. Throwing on success
+        // would report a vault that was published as one that was not.
+        const parsed = await res.json().catch(() => ({}));
+        return { ok: true, body: parsed };
+    }
+    const parsed = (await res.json().catch(() => null));
+    return {
+        ok: false,
+        status: res.status,
+        ...(typeof parsed?.error === "string" ? { error: parsed.error } : {}),
+        ...(typeof parsed?.message === "string" ? { message: parsed.message } : {}),
+        ours: typeof parsed?.error === "string",
+    };
+}
+function httpHeadline(result, what) {
+    if (result.status === 0)
+        return `Could not reach ${apiBase()}.`;
+    if (result.malformed)
+        return `${apiBase()} answered, but not with vaults.`;
+    if (result.status === 401 && result.ours)
+        return "This machine's credentials were refused.";
+    if (result.status === 401 || result.status === 403) {
+        return `Something between here and ${apiBase()} refused the request (${result.status}).`;
+    }
+    if (result.status === 404)
+        return `${what} is not something this backend knows how to do.`;
+    if (result.status === 429)
+        return "Too many requests. Wait a minute and try again.";
+    if (result.status >= 500)
+        return `${apiBase()} could not complete the request.`;
+    // Anything else our API took the trouble to write a sentence about is relayed rather than
+    // replaced by a code: a backend newer than this build knows things this file does not.
+    if (result.ours && result.message)
+        return result.message;
+    return `${what} failed (${result.status}${result.error ? `: ${result.error}` : ""}).`;
+}
+function httpHints(result) {
+    if (result.status === 0)
+        return ["Check the network, then try again."];
+    if (result.status === 401 && result.ours) {
+        return ["Run `popover login` to reconnect this machine."];
+    }
+    if (result.status === 401 || result.status === 403) {
+        return [
+            "The refusal did not come from popover — an SSO proxy or a protected preview",
+            "deployment answers this way. Signing in again would not help.",
+        ];
+    }
+    if (result.status === 404 && !result.ours) {
+        return [
+            "Vaults need a backend that has them. If you are pointed at a preview deployment,",
+            "check POPOVER_API_URL; otherwise run `popover update`.",
+        ];
+    }
+    if (result.status === 404) {
+        return ["It may have been archived. Run `popover vault list` to see what there is."];
+    }
+    if (result.status >= 500)
+        return ["Nothing was published. Try again in a moment."];
+    return [];
+}
+function reportApiFailure(result, asJson, what) {
+    return fail(asJson, result.malformed ? "unexpected_response" : (result.error ?? `http_${result.status}`), httpHeadline(result, what), httpHints(result));
+}
+// ---------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------
+/**
+ * The origin to talk to.
+ *
+ * `defaultApiUrl()` rather than `credentials.api_url` directly, so `POPOVER_API_URL` points
+ * this at a dev checkout or a preview the same way it does `popover fork` and `popover repos`.
+ */
+function apiBase() {
+    return defaultApiUrl().replace(/\/+$/, "");
+}
+function git(cwd, args) {
+    try {
+        return execFileSync("git", ["-C", cwd, ...args], {
+            encoding: "utf8",
+            timeout: 5000,
+            windowsHide: true,
+            maxBuffer: 8 * 1024 * 1024,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+    }
+    catch {
+        // Not a repo, no git, or no commits. All three mean "no signal", and none of them are a
+        // reason to refuse to vault a conversation.
+        return undefined;
+    }
+}
+function fail(asJson, code, message, hints) {
+    if (asJson) {
+        console.log(JSON.stringify({ ok: false, error: code, message, hints }));
+        return 1;
+    }
+    bad(message);
+    for (const hint of hints)
+        dim(hint);
+    return 1;
+}
+function mb(bytes) {
+    return (bytes / (1024 * 1024)).toFixed(1);
+}
+//# sourceMappingURL=vaults.js.map