shadok-ai 0.13.5 → 0.13.7

package/README.md

@@ -87,11 +87,20 @@ Enter to skip; you can add it later from the web UI).
   (e.g. forbid `git commit`), model, and which secrets to inject. Applied at
   spawn, remembered across resume.
 - **A model per agent** — the creation form picks the model this one agent runs
-  on (Opus, Sonnet, Haiku, Fable), overriding its profile's, with a **long
-  context (1M)** tick beside it. Leave it on *profile default* and nothing
-  changes: no flag is sent at all. The choice is stored on the agent, so a
-  resume or a restart keeps it, and the quota gauge meters it against the
-  window it actually asked for. Eight roles ship with it: a lead that
+  on, overriding its profile's, with a **long context (1M)** tick beside it.
+  Pick a family (Opus, Sonnet, Haiku, Fable) and it follows Claude Code's
+  releases, or fold out **Pin an exact version** — that list is read from the
+  installed `claude` binary, so a model Anthropic ships appears on its own at
+  the next Claude Code update, with nothing to maintain here. Leave it on
+  *profile default* and nothing changes: no flag is sent at all. The choice is
+  stored on the agent, so a resume or a restart keeps it, and the quota gauge
+  meters it against the window it actually asked for.
+- **A default model for the machine** — ⋯ → the version menu → *Default model*,
+  beside the permission mode. It writes Claude Code's own `settings.json`, which
+  is already the last step of the resolution chain (**agent → profile →
+  machine**), and applies at each agent's next spawn. Agents that carry no model
+  of their own simply follow Claude Code's default, which tracks the newest
+  model — so this is for **pinning** one, not for getting the latest. Eight roles ship with it: a lead that
   delegates, a dev, a QA agent that writes the failing test and cannot fix the
   code it covers, a release agent that prepares a deployment and leaves the
   trigger to you, a product agent that writes the spec instead of the change,
@@ -131,6 +140,15 @@ Enter to skip; you can add it later from the web UI).
 - **Engine room** — the raw TUI screen, live, with clickable keys, for anything
   the chat can't express. With tmux there is also an **experimental real
   terminal** (xterm.js over the pane's byte stream) when a snapshot isn't enough.
+- **Files an agent hands you** — when an agent's result IS a file (a report, an
+  export, a screenshot, an archive) it arrives as a download card in the chat,
+  inline if it is an image, and as an upload in the Telegram topic. It goes
+  through shadok's own `shadok-files` skill rather than depending on the
+  harness's file tool, which is **not on every agent**: a long-lived agent keeps
+  the Claude Code binary it started with, so one older than that tool would
+  otherwise just print a local path you cannot open. **Artifacts are denied**
+  cockpit-wide for the same reason — a page on claude.ai is not the file you
+  asked for (`SHADOK_ALLOW_ARTIFACTS=1` lifts it).
 - **Diff panel** — what an agent actually changed, against its base.
 - **What an agent left running, on its tab** — a turning ⏳ for background
   shells, a still 👁 for monitors, each with its count past one. Claude Code

package/context/files-skill/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: shadok-files
+description: Hand a file to the person you are talking to — a report, an export, a screenshot, a built artifact. Use whenever your result IS a file. They are in a browser or on Telegram, NOT on this machine, so a local path is a string they cannot open.
+---
+
+# shadok-files
+
+The person reading you is in a web cockpit or on Telegram. **They are not on
+this machine.** Printing `/workspace/report.pdf` gives them a string they cannot
+click, cannot open and cannot save. Hand the file over instead:
+
+```bash
+node ~/.claude/skills/shadok-files/scripts/send.mjs /abs/path/report.pdf
+node ~/.claude/skills/shadok-files/scripts/send.mjs a.png b.png --caption "before / after"
+```
+
+It appears in the chat as a download card — inline if it is an image — and is
+uploaded into the Telegram topic when the agent is mirrored.
+
+## When to use it, and when not
+
+**Use it when the file IS the deliverable**: a report you generated, an export,
+a screenshot, a diagram, an archive, a built binary.
+
+**Do not use it for a path you are merely citing.** `src/server.ts:412` in a
+review is a reference, not a deliverable — attaching the file there is noise.
+
+**Do not publish an artifact instead.** An artifact is a page on claude.ai; the
+person asked for a file. Several shipped roles deny the tool outright.
+
+**Do not send the same file again** unless it has meaningfully changed. Each
+call renders a card, and a row of cards for one file is noise.
+
+## Paths
+
+Give an **absolute** path. The server's working directory is its launch
+directory and never yours, so a relative path would resolve somewhere else —
+the script resolves it against your cwd before sending, but being explicit
+costs nothing and removes the question.
+
+## If something is missing
+
+If this skill is not installed, or the call fails, **say so plainly and stop**.
+Do not invent a replacement convention — a `fichier: /path/to/x` line of your
+own making looks like a feature to the person reading it, and is not one. Ask
+them to check the cockpit instead.
+
+## Authenticating a direct API call
+
+The command above does this for you. If you call the cockpit's API yourself,
+send your session key — it is in your environment and it does not expire:
+
+```bash
+curl -sS -X POST -H "content-type: application/json" \
+  -H "x-shadok-session-key: $SHADOK_SESSION_KEY" \
+  -d '{"paths":["/abs/path/report.pdf"],"caption":"the report"}' \
+  "http://127.0.0.1:$SHADOK_PORT/files"
+```
+
+`$SHADOK_AUTH` (a cookie) is still accepted elsewhere, but it was frozen into
+this process's environment at spawn and expires after a week, so never rely on
+it alone. A `401` or `403` means that header is missing — or that you were
+started before this existed, in which case nothing you hold can authenticate
+any more and only a human can fix it: ask them for *Reload agent* on your ⋯
+menu.

package/context/files-skill/scripts/send.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Hand a file to the person driving this cockpit.
+//
+// Deliberately a script and not the harness's SendUserFile tool: a tmux agent
+// keeps the Claude Code binary it was spawned with, so an agent older than that
+// tool never sees it — and the whole fleet runs pre-upgrade binaries by design.
+// An HTTP call works on every build, including the ones already running.
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const die = (m) => { console.error(m); process.exit(1); };
+
+let caption;
+const paths = [];
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--caption" || args[i] === "-c") caption = args[++i];
+  else if (args[i] === "--help" || args[i] === "-h")
+    die("usage: send.mjs <file...> [--caption \"…\"]");
+  else paths.push(args[i]);
+}
+if (!paths.length) die("usage: send.mjs <file...> [--caption \"…\"]");
+
+const port = process.env.SHADOK_PORT;
+const key = process.env.SHADOK_SESSION_KEY;
+if (!port) die("Not inside a shadok-ai agent (SHADOK_PORT unset).");
+// Said plainly rather than worked around: an agent that cannot authenticate
+// must tell the human, not invent its own way of surfacing a file.
+if (!key) die("SHADOK_SESSION_KEY is unset — ask the human to reload this agent.");
+
+// Resolved HERE, where the cwd is the agent's. The server's cwd is its launch
+// directory and never this one, so a relative path sent as-is would point
+// somewhere else and only ever work by coincidence.
+const abs = paths.map((p) => path.resolve(p));
+
+let res;
+try {
+  res = await fetch(`http://127.0.0.1:${port}/files`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-shadok-session-key": key },
+    body: JSON.stringify({ paths: abs, ...(caption ? { caption } : {}) }),
+    signal: AbortSignal.timeout(30_000),
+  });
+} catch (e) {
+  die(`The cockpit did not answer (${e?.message ?? e}). It may be restarting — say so rather than working around it.`);
+}
+
+const body = await res.json().catch(() => ({}));
+if (!res.ok) die(`Refused (${res.status}): ${body.error ?? "no reason given"}`);
+for (const f of body.sent ?? []) console.log(`sent: ${f.name} (${f.size} bytes)`);
+// A partial success is reported, never swallowed: the agent has to know WHICH
+// file did not make it.
+for (const r of body.refused ?? []) console.error(`not sent: ${r}`);

package/context/pilot-prompt.md

@@ -23,6 +23,17 @@ Claude Code sessions in parallel. A human pilots you from a browser chat
   Avoid very wide previews in the options.
 - The user may be on a phone: conclusion first, compact responses, no long
   tables where a list would do.
+- **Handing over a file.** The person reading you is in a browser or on
+  Telegram — **not on this machine**. A local path is a string they cannot open,
+  so when your result IS a file (a report, an export, a screenshot, an archive)
+  hand it over: `node ~/.claude/skills/shadok-files/scripts/send.mjs <abs path>`.
+  It becomes a download card in the chat and an upload in the Telegram topic.
+  Citing a path stays right when the path is the point (`src/foo.ts:12` in a
+  review); attach when the file is the deliverable. **Do not publish an artifact
+  instead** — that is a page on claude.ai, not the file they asked for, and
+  several roles deny the tool outright. And if a capability is missing, say so
+  and stop: do not invent a replacement convention, because a `fichier: /path`
+  line of your own making looks like a feature to the reader and is not one.
 - **Saying nothing.** You always have to reply *something*, but a scheduled
   run that found no signal should not ping anyone. Reply with exactly
   `NOTHING TO SHOW` (the whole message, nothing else) and the cockpit drops

package/dist/claude-home.d.ts

@@ -64,3 +64,22 @@ export declare function ensureClaudeHome(): void;
  * for every agent, therefore a brand-new trust dialog every time.
  */
 export declare function ensureProjectTrusted(cwd: string): void;
+/**
+ * The machine-wide default model, read from and written to the SAME
+ * `~/.claude/settings.json` this module already owns.
+ *
+ * Deliberately here and not in a module of its own: `seedSettings` already
+ * writes that file, and two writers on one JSON file is how a `tui` seeded at
+ * boot and a model written from the GUI would eventually erase each other. One
+ * owner, one atomic write.
+ *
+ * Verified 2026-09-25 against claude 2.1.282, because the whole feature rests
+ * on it: with `model` in that file and NO `--model` flag, the run used
+ * `claude-haiku-4-5-20251001`; and it is still honoured when shadok also passes
+ * `--settings` for a profile's guardrails, so the flag MERGES rather than
+ * replacing the file. Without that second check the setting would have been
+ * silently inert for every agent that carries a profile.
+ */
+export declare function getDefaultModel(): string | null;
+/** Write (or clear, with null) that default. Returns false if it could not. */
+export declare function setDefaultModel(model: string | null): boolean;

package/dist/claude-home.js

@@ -210,4 +210,58 @@ function seedSettings() {
 export function ensureProjectTrusted(cwd) {
     seed(cwd);
 }
+/**
+ * The machine-wide default model, read from and written to the SAME
+ * `~/.claude/settings.json` this module already owns.
+ *
+ * Deliberately here and not in a module of its own: `seedSettings` already
+ * writes that file, and two writers on one JSON file is how a `tui` seeded at
+ * boot and a model written from the GUI would eventually erase each other. One
+ * owner, one atomic write.
+ *
+ * Verified 2026-09-25 against claude 2.1.282, because the whole feature rests
+ * on it: with `model` in that file and NO `--model` flag, the run used
+ * `claude-haiku-4-5-20251001`; and it is still honoured when shadok also passes
+ * `--settings` for a profile's guardrails, so the flag MERGES rather than
+ * replacing the file. Without that second check the setting would have been
+ * silently inert for every agent that carries a profile.
+ */
+export function getDefaultModel() {
+    try {
+        const raw = fs.readFileSync(settingsFile(), "utf8");
+        const m = JSON.parse(raw)?.model;
+        return typeof m === "string" && m.trim() ? m.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Write (or clear, with null) that default. Returns false if it could not. */
+export function setDefaultModel(model) {
+    try {
+        const file = settingsFile();
+        let existing = {};
+        if (fs.existsSync(file)) {
+            const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+            // Hand-edited into invalid JSON, or not an object: leave it ALONE rather
+            // than "repair" it — same rule as `seed`, and for the same reason.
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return false;
+            existing = parsed;
+        }
+        const next = { ...existing };
+        if (model?.trim())
+            next.model = model.trim();
+        else
+            delete next.model;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.shadok-${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(next, null, 2));
+        fs.renameSync(tmp, file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 //# sourceMappingURL=claude-home.js.map

package/dist/claude-home.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude-home.js","sourceRoot":"","sources":["../src/claude-home.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"claude-home.js","sourceRoot":"","sources":["../src/claude-home.ts"],"names":[],"mappings":"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"}

package/dist/claude-models.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Which models THIS Claude Code build supports, read out of the binary.
+ *
+ * The alternative was a hardcoded list, and it is the alternative that rots:
+ * the profile panel still suggests `claude-opus-4-8`, current the day it was
+ * written and stale now, and `claude-opus-5-5` shipped without shadok noticing.
+ * The CLI has no command that enumerates models (`claude models` is not a
+ * subcommand — it is taken as a PROMPT and answered, which is its own trap), so
+ * the names are taken from where they actually live: the binary's own strings.
+ *
+ * Read, never executed, and never trusted blindly — see `parseModelNames`.
+ */
+/** Families the CLI accepts as aliases. An alias is always offered, scan or no scan. */
+export declare const MODEL_FAMILIES: readonly ["opus", "sonnet", "haiku", "fable"];
+/**
+ * Pure: the model names in a blob of binary strings, conservatively.
+ *
+ * DELIBERATELY NARROW, and the narrowness is the point. A `strings` dump glues
+ * adjacent bytes together, which mints plausible-looking rubbish: this binary
+ * contains `claude-haiku-3-55` (a `3-5` with the next byte stuck to it) and
+ * `claude-fable-5-mythos-5`. Offering those as choices would produce an agent
+ * that dies at spawn on a model nobody can find. So only a plain
+ * `claude-<family>-<major>[-<minor>]` is kept, with a single-digit minor.
+ *
+ * Dropped on purpose:
+ *  - `-v1` suffixes and 8-digit dated forms (`claude-opus-4-5-20251101`): the
+ *    same model spelled longer, and three spellings of one model in a picker is
+ *    noise, not choice.
+ *  - anything with a non-numeric segment, which is where the glue artifacts are.
+ *
+ * KNOWN LIMIT, written down rather than discovered later: a two-digit minor
+ * (`claude-opus-5-10`) would be skipped, because admitting two digits is what
+ * lets `3-55` back in. The family row (`opus`, `sonnet`…) never depends on this
+ * scan, so a missed name costs discoverability, never the ability to run it.
+ */
+export declare function parseModelNames(text: string): string[];
+/** Pure: family, then newest version first — the order a picker should show. */
+export declare function rankModels(names: readonly string[]): string[];
+export interface ModelCache {
+    /** Identity of the binary these names came from. */
+    bin: string;
+    size: number;
+    mtimeMs: number;
+    models: string[];
+}
+/** Pure: is a cache entry still about the binary on disk right now? */
+export declare function cacheIsFresh(cache: ModelCache | null, stat: {
+    size: number;
+    mtimeMs: number;
+} | null, bin: string): boolean;
+/**
+ * Scan the binary. Returns [] on ANY failure — a mid-upgrade binary is the
+ * normal case here, not the exception (invariant 32): the launcher is unlinked
+ * and relinked on every claude-code update, so a scan can meet ETXTBSY, a
+ * 500-byte placeholder, or nothing at all. An empty result is never cached, so
+ * the next boot simply tries again.
+ */
+export declare function scanModels(bin: string): string[];
+/**
+ * The models this build supports, cached per binary identity.
+ *
+ * One scan per claude-code upgrade, not per call: the cache key is the
+ * binary's path, size and mtime, exactly the trio that changes when it is
+ * replaced. `force` re-reads without touching the memo's contract.
+ */
+export declare function availableModels(bin: string, force?: boolean): string[];
+/** Test seam: forget the in-process memo. */
+export declare function resetModelMemo(): void;

package/dist/claude-models.js

@@ -0,0 +1,181 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Which models THIS Claude Code build supports, read out of the binary.
+ *
+ * The alternative was a hardcoded list, and it is the alternative that rots:
+ * the profile panel still suggests `claude-opus-4-8`, current the day it was
+ * written and stale now, and `claude-opus-5-5` shipped without shadok noticing.
+ * The CLI has no command that enumerates models (`claude models` is not a
+ * subcommand — it is taken as a PROMPT and answered, which is its own trap), so
+ * the names are taken from where they actually live: the binary's own strings.
+ *
+ * Read, never executed, and never trusted blindly — see `parseModelNames`.
+ */
+/** Families the CLI accepts as aliases. An alias is always offered, scan or no scan. */
+export const MODEL_FAMILIES = ["opus", "sonnet", "haiku", "fable"];
+/**
+ * Pure: the model names in a blob of binary strings, conservatively.
+ *
+ * DELIBERATELY NARROW, and the narrowness is the point. A `strings` dump glues
+ * adjacent bytes together, which mints plausible-looking rubbish: this binary
+ * contains `claude-haiku-3-55` (a `3-5` with the next byte stuck to it) and
+ * `claude-fable-5-mythos-5`. Offering those as choices would produce an agent
+ * that dies at spawn on a model nobody can find. So only a plain
+ * `claude-<family>-<major>[-<minor>]` is kept, with a single-digit minor.
+ *
+ * Dropped on purpose:
+ *  - `-v1` suffixes and 8-digit dated forms (`claude-opus-4-5-20251101`): the
+ *    same model spelled longer, and three spellings of one model in a picker is
+ *    noise, not choice.
+ *  - anything with a non-numeric segment, which is where the glue artifacts are.
+ *
+ * KNOWN LIMIT, written down rather than discovered later: a two-digit minor
+ * (`claude-opus-5-10`) would be skipped, because admitting two digits is what
+ * lets `3-55` back in. The family row (`opus`, `sonnet`…) never depends on this
+ * scan, so a missed name costs discoverability, never the ability to run it.
+ */
+export function parseModelNames(text) {
+    const fam = MODEL_FAMILIES.join("|");
+    const re = new RegExp(`claude-(?:${fam})-\\d{1,2}(?:-\\d)?(?![\\w-])`, "g");
+    return [...new Set(text.match(re) ?? [])];
+}
+/** Pure: family, then newest version first — the order a picker should show. */
+export function rankModels(names) {
+    const key = (n) => {
+        const m = /^claude-([a-z]+)-(\d{1,2})(?:-(\d))?$/.exec(n);
+        if (!m)
+            return null;
+        return { family: m[1], major: Number(m[2]), minor: m[3] ? Number(m[3]) : 0 };
+    };
+    return [...names]
+        .filter((n) => key(n))
+        .sort((a, b) => {
+        const x = key(a), y = key(b);
+        const fx = MODEL_FAMILIES.indexOf(x.family);
+        const fy = MODEL_FAMILIES.indexOf(y.family);
+        if (fx !== fy)
+            return fx - fy;
+        if (x.major !== y.major)
+            return y.major - x.major;
+        return y.minor - x.minor;
+    });
+}
+/** Pure: is a cache entry still about the binary on disk right now? */
+export function cacheIsFresh(cache, stat, bin) {
+    if (!cache || !stat)
+        return false;
+    return cache.bin === bin && cache.size === stat.size && cache.mtimeMs === stat.mtimeMs;
+}
+const cacheFile = () => path.join(os.homedir(), ".shadok-ai", "models.json");
+/** How much of a ~240MB binary we are willing to read in one pass. */
+const CHUNK = 1 << 22;
+/** Names can straddle a chunk boundary; carry this much across. */
+const OVERLAP = 64;
+/**
+ * Scan the binary. Returns [] on ANY failure — a mid-upgrade binary is the
+ * normal case here, not the exception (invariant 32): the launcher is unlinked
+ * and relinked on every claude-code update, so a scan can meet ETXTBSY, a
+ * 500-byte placeholder, or nothing at all. An empty result is never cached, so
+ * the next boot simply tries again.
+ */
+export function scanModels(bin) {
+    let fd = null;
+    try {
+        fd = fs.openSync(bin, "r");
+        const buf = Buffer.allocUnsafe(CHUNK);
+        let carry = "";
+        const found = new Set();
+        for (;;) {
+            const n = fs.readSync(fd, buf, 0, CHUNK, null);
+            if (n <= 0)
+                break;
+            // latin1: every byte maps to one char, so offsets stay sane and an
+            // invalid UTF-8 run cannot swallow a name next to it.
+            const text = carry + buf.toString("latin1", 0, n);
+            for (const m of parseModelNames(text))
+                found.add(m);
+            carry = text.slice(-OVERLAP);
+        }
+        return rankModels([...found]);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (fd !== null)
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* already gone */ }
+    }
+}
+function readCache() {
+    try {
+        const j = JSON.parse(fs.readFileSync(cacheFile(), "utf8"));
+        return Array.isArray(j?.models) ? j : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(c) {
+    try {
+        const f = cacheFile();
+        fs.mkdirSync(path.dirname(f), { recursive: true });
+        const tmp = `${f}.shadok-${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(c, null, 2));
+        fs.renameSync(tmp, f);
+    }
+    catch {
+        /* a cache we cannot write just means we scan again next boot */
+    }
+}
+let memo = null;
+/**
+ * The models this build supports, cached per binary identity.
+ *
+ * One scan per claude-code upgrade, not per call: the cache key is the
+ * binary's path, size and mtime, exactly the trio that changes when it is
+ * replaced. `force` re-reads without touching the memo's contract.
+ */
+export function availableModels(bin, force = false) {
+    // `memo.length`, NOT `memo`: an empty array is truthy, so memoising a failed
+    // scan would freeze the picker family-only for the life of the process — and
+    // a failed scan is the NORMAL case here, since the binary is unlinked and
+    // relinked on every claude-code upgrade (invariant 32). Same rule as the
+    // file cache below: an empty result is a "could not look", never an answer.
+    if (memo?.length && !force)
+        return memo;
+    let stat = null;
+    try {
+        const s = fs.statSync(bin);
+        stat = { size: s.size, mtimeMs: s.mtimeMs };
+    }
+    catch {
+        stat = null;
+    }
+    const cached = readCache();
+    if (!force && cacheIsFresh(cached, stat, bin))
+        return (memo = cached.models);
+    const models = scanModels(bin);
+    // NEVER cache an empty result: that is what a mid-upgrade binary produces,
+    // and freezing it would leave the picker permanently family-only.
+    if (models.length && stat)
+        writeCache({ bin, ...stat, models });
+    // Falling back to the cache is what carries the picker through an upgrade
+    // window — but only for the SAME binary. Without the path check, an entry
+    // written for one launcher answered a question about another, which is a
+    // cache bleeding across identities rather than a stale-but-useful answer.
+    const stale = cached && cached.bin === bin ? cached.models : [];
+    memo = models.length ? models : stale;
+    // `memo` may legitimately be [] here; the `memo?.length` guard above is what
+    // stops that from hardening into a permanent answer.
+    return memo;
+}
+/** Test seam: forget the in-process memo. */
+export function resetModelMemo() {
+    memo = null;
+}
+//# sourceMappingURL=claude-models.js.map

package/dist/claude-models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-models.js","sourceRoot":"","sources":["../src/claude-models.ts"],"names":[],"mappings":"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"}

package/dist/files.d.ts

@@ -0,0 +1,95 @@
+import { type FileCard } from "./download.js";
+/**
+ * Files an agent OFFERS the user through shadok's own path, rather than through
+ * the harness's `SendUserFile` tool.
+ *
+ * Why this exists next to a tool that already does it: a tmux agent keeps the
+ * Claude Code binary it was spawned with — that is what lets it survive an
+ * auto-update — so an agent older than the tool never sees it, and the whole
+ * fleet runs pre-upgrade binaries by design (measured: 67 panes of 67). One
+ * instance answered "cet outil n'existe pas dans ma session" and invented a
+ * `fichier: /path` line of its own, which looks like a feature without being
+ * one. A skill calling this endpoint works on any build, including the ones
+ * already running.
+ *
+ * This is a registry of OFFERS, not a copy: the bytes stay where the agent
+ * wrote them, and the row records that this session chose to hand them over.
+ *
+ * See docs/superpowers/specs/2026-09-25-file-handover-design.md.
+ */
+/**
+ * The `stream-tool` name a shadok-side delivery travels under.
+ *
+ * Deliberately NOT "SendUserFile": the two reach the same card, but one is a
+ * harness tool call recorded in the transcript and the other is an HTTP offer,
+ * and spelling them alike would make every later `grep SendUserFile` lie about
+ * where a file came from. The consumers accept both names; nothing else about
+ * the message differs, which is why no new client or Telegram rendering was
+ * needed for this feature.
+ */
+export declare const OFFER_TOOL = "ShadokFile";
+export interface OfferedFile {
+    sessionId: string;
+    path: string;
+    name: string;
+    size: number;
+    /** ms epoch of the offer. */
+    at: number;
+    caption?: string;
+}
+/** Biggest file we will register. Beyond this the agent is told, not ignored. */
+export declare const MAX_OFFER_BYTES: number;
+/** How many offers we keep per instance — a bound, like the ledger's. */
+export declare const MAX_OFFERS = 500;
+export type OfferRefusal = {
+    ok: false;
+    reason: "not-absolute" | "missing" | "not-a-file" | "too-big" | "unreadable";
+    path: string;
+    detail?: string;
+};
+export type OfferVerdict = {
+    ok: true;
+    file: OfferedFile;
+} | OfferRefusal;
+/**
+ * Pure: may this path be offered, given what the filesystem says about it?
+ *
+ * `stat` is injected so the decision is testable without touching a disk — the
+ * same shape as `classifyBin` and `readGround`. "missing" and "unreadable" are
+ * kept APART rather than collapsed into one failure: they send the agent to
+ * different places (it wrote the wrong path, versus the server cannot see a
+ * path that is really there), and telling it the wrong one costs a round trip.
+ * Invariant 27's discipline applied to a much smaller thing.
+ */
+export type OfferStat = {
+    isFile: boolean;
+    size: number;
+} | "missing" | "unreadable";
+export declare function offerVerdict(sessionId: string, p: string, stat: OfferStat, now: number, caption?: string): OfferVerdict;
+/**
+ * Pure: the table after an offer, newest last, bounded and de-duplicated.
+ *
+ * Re-offering the same path from the same session REPLACES the row rather than
+ * appending one: an agent that regenerates a report and sends it again should
+ * leave one card's worth of state, not a log. Same "supersede, not append" rule
+ * the ledger learned the hard way.
+ */
+export declare function withOffer(rows: readonly OfferedFile[], f: OfferedFile): OfferedFile[];
+/**
+ * Pure: every path this SESSION has offered.
+ *
+ * The read-side gate, and the twin of `sentFilePaths`: `GET /download` serves a
+ * path only when it is in one of the two, so the endpoint still cannot be walked
+ * into an arbitrary file — it serves back exactly what an agent chose to hand
+ * over, and only to that agent's own channel.
+ */
+export declare function offeredPaths(rows: readonly OfferedFile[], sessionId: string): Set<string>;
+/** Pure: the cards for an offer, the shape the client and Telegram already take. */
+export declare function offerCards(files: readonly OfferedFile[]): FileCard[];
+/** Pure: a refusal, worded for the agent that will read it. */
+export declare function refusalMessage(r: OfferRefusal): string;
+export declare const filesFileFor: (cwd: string) => string;
+export declare function loadOffers(file: string): OfferedFile[];
+export declare function saveOffers(file: string, rows: readonly OfferedFile[]): void;
+/** Stat for `offerVerdict`, keeping absent and unreadable apart. */
+export declare function statForOffer(p: string): OfferStat;