@hanamorilabs/tab 0.1.14 → 0.1.16

package/dist/observability-queue.js

@@ -0,0 +1,194 @@
+import { randomUUID } from "node:crypto";
+import { linkSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+export const QUEUE_LIMIT = 512;
+const localLocks = new Map();
+export class ObservationLockTimeout extends Error {
+}
+function readOwner(file) {
+    try {
+        const owner = JSON.parse(readFileSync(file, "utf8"));
+        return Number.isInteger(owner.pid) && owner.pid > 0 && typeof owner.token === "string" ? owner : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+function releaseOwned(file, token) {
+    if (readOwner(file)?.token === token)
+        rmSync(file, { force: true });
+}
+function reclaimDeadOwner(lock) {
+    // Serialize reapers. An unknown/legacy lock is never stolen based on age alone.
+    const reaper = `${lock}.reaping`;
+    try {
+        mkdirSync(reaper);
+    }
+    catch {
+        return;
+    }
+    try {
+        const owner = readOwner(lock);
+        if (owner && !alive(owner.pid))
+            releaseOwned(lock, owner.token);
+    }
+    finally {
+        rmSync(reaper, { recursive: true, force: true });
+    }
+}
+export async function withObservationLock(dir, action) {
+    // Sibling calls wait their turn before starting the cross-process deadline.
+    const previous = localLocks.get(dir) ?? Promise.resolve();
+    let done;
+    const current = new Promise((resolve) => { done = resolve; });
+    localLocks.set(dir, current);
+    await previous;
+    const lock = path.join(dir, ".lock");
+    const token = randomUUID();
+    const candidate = path.join(dir, `.owner-${token}`);
+    let acquired = false;
+    try {
+        writeFileSync(candidate, JSON.stringify({ pid: process.pid, token }), { mode: 0o600, flag: "wx" });
+        const deadline = Date.now() + 750;
+        for (;;) {
+            try {
+                linkSync(candidate, lock);
+                acquired = true;
+                break;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                reclaimDeadOwner(lock);
+                if (Date.now() >= deadline)
+                    throw new ObservationLockTimeout("Observability queue is busy");
+                await new Promise((resolve) => setTimeout(resolve, 10));
+            }
+        }
+        return await action();
+    }
+    finally {
+        try {
+            if (acquired)
+                releaseOwned(lock, token);
+            rmSync(candidate, { force: true });
+        }
+        finally {
+            done();
+            if (localLocks.get(dir) === current)
+                localLocks.delete(dir);
+        }
+    }
+}
+const isEventFile = (file) => /^[a-zA-Z0-9-]+\.json$/.test(file) && file !== "run.json";
+const eventFiles = async (dir) => (await readdir(dir)).filter(isEventFile);
+function contentionGap(dir) {
+    const gap = { id: randomUUID(), kind: "gap", sessionId: "collector", occurredAt: new Date().toISOString(), droppedCount: 1 };
+    // Coalesce a contention episode into one lower-bound gap; no unbounded side queue.
+    const candidate = path.join(dir, `.gap-${gap.id}`);
+    try {
+        writeFileSync(candidate, JSON.stringify(gap), { mode: 0o600, flag: "wx" });
+        try {
+            linkSync(candidate, path.join(dir, "contention-gap.json"));
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    finally {
+        rmSync(candidate, { force: true });
+    }
+}
+export async function enqueueEvent(dir, event, limit = QUEUE_LIMIT) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        await withObservationLock(dir, () => {
+            const files = readdirSync(dir).filter(isEventFile);
+            const name = `${event.id}.json`;
+            if (files.includes(name))
+                return;
+            if (files.length >= limit) {
+                const file = path.join(dir, "dropped");
+                let dropped = 0;
+                try {
+                    dropped = Number(readFileSync(file, "utf8")) || 0;
+                }
+                catch { /* First overflow. */ }
+                writeFileSync(file, String(Math.min(1_000_000, dropped + 1)), { mode: 0o600 });
+                return;
+            }
+            const temp = path.join(dir, `${event.id}.tmp`);
+            writeFileSync(temp, JSON.stringify(event), { mode: 0o600 });
+            renameSync(temp, path.join(dir, name));
+        });
+    }
+    catch (error) {
+        if (!(error instanceof ObservationLockTimeout))
+            throw error;
+        contentionGap(dir);
+    }
+}
+/** Network runs outside the hook and lock. Files disappear only after acknowledgment. */
+export async function flushQueue(dir, run, send) {
+    await withObservationLock(dir, () => {
+        const file = path.join(dir, "dropped");
+        let dropped = 0;
+        try {
+            dropped = Number(readFileSync(file, "utf8")) || 0;
+        }
+        catch { /* No overflow. */ }
+        if (dropped > 0 && !readdirSync(dir).includes("gap.json")) {
+            const gap = { id: randomUUID(), kind: "gap", sessionId: `collector:${run.id}`, occurredAt: new Date().toISOString(), droppedCount: Math.min(1_000_000, dropped) };
+            writeFileSync(path.join(dir, "gap.json"), JSON.stringify(gap), { mode: 0o600 });
+            rmSync(file, { force: true });
+        }
+    });
+    const files = (await eventFiles(dir)).sort().slice(0, 100);
+    const events = [];
+    const included = [];
+    for (const file of files) {
+        const text = await readFile(path.join(dir, file), "utf8").catch(() => "");
+        if (!text || Buffer.byteLength(text) > 4096)
+            continue;
+        try {
+            const event = JSON.parse(text);
+            if (Buffer.byteLength(JSON.stringify({ version: 1, run, events: [...events, event] })) > 120_000)
+                break;
+            events.push(event);
+            included.push({ file, id: event.id });
+        }
+        catch { /* Partial files are not acknowledged. */ }
+    }
+    // Registration accompanies the first event batch; idle or untrusted hooks send nothing.
+    if (events.length === 0)
+        return true;
+    if (!(await send({ version: 1, run, events }).catch(() => false)))
+        return false;
+    await withObservationLock(dir, () => {
+        // Other uploaders can replace reusable gap filenames while this request is in flight.
+        for (const { file, id } of included) {
+            const target = path.join(dir, file);
+            let saved;
+            try {
+                saved = JSON.parse(readFileSync(target, "utf8"));
+            }
+            catch {
+                continue;
+            }
+            if (saved.id === id)
+                rmSync(target, { force: true });
+        }
+    });
+    return true;
+}

package/dist/observability.js

@@ -0,0 +1,249 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { link, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CODEX_SEND_TOOLS, identifier } from "./observability-events.js";
+import { flushQueue, withObservationLock } from "./observability-queue.js";
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+async function isActive(dir) {
+    const pid = Number(await readFile(path.join(dir, "owner.pid"), "utf8").catch(() => "0"));
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function queueIsEmpty(dir) {
+    const files = await readdir(dir).catch((error) => { if (error.code === "ENOENT")
+        return []; throw error; });
+    return !files.some((f) => (f.endsWith(".json") && f !== "run.json") || f === "dropped");
+}
+export function observationHooks(harness, command) {
+    const group = (matcher) => [{ ...(matcher ? { matcher } : {}), hooks: [{ type: "command", command, timeout: 2 }] }];
+    const hooks = {
+        SessionStart: group(), SessionEnd: group(), SubagentStart: group(), SubagentStop: group(),
+        PostToolUse: group(harness === "claude" ? "^(SendMessage|SubagentHandback)$" : `^(${CODEX_SEND_TOOLS.map((s) => s.replaceAll(".", "\\.")).join("|")})$`),
+    };
+    if (harness === "claude")
+        hooks.PostToolUseFailure = group("^(SendMessage|SubagentHandback)$");
+    return hooks;
+}
+function toml(value) {
+    if (Array.isArray(value))
+        return `[${value.map(toml).join(",")}]`;
+    if (value !== null && typeof value === "object")
+        return `{${Object.entries(value).map(([k, v]) => `${JSON.stringify(k)}=${toml(v)}`).join(",")}}`;
+    return JSON.stringify(value);
+}
+/** Session config is a separate hook source: Codex merges hook sources across layers. */
+export function codexObservationArgs(hooks) {
+    return Object.entries(hooks).flatMap(([event, groups]) => ["-c", `hooks.${event}=${toml(groups)}`]);
+}
+async function installedVersion(command, env) {
+    return new Promise((resolve) => execFile(command, ["--version"], { env, timeout: 3000, maxBuffer: 4096 }, (error, stdout) => resolve(error ? "unknown" : (stdout.match(/\b\d+\.\d+\.\d+\b/)?.[0] ?? "unknown"))));
+}
+export function supportedObservationVersion(harness, version) {
+    // Explicitly tested schema families; future minor lines need a compatibility review.
+    const [major, minor, patch] = version.split(".").map(Number);
+    return harness === "claude" ? major === 2 && minor === 1 && patch >= 278 : major === 0 && minor === 155 && patch >= 1;
+}
+async function installationId(root) {
+    const file = path.join(root, "installation-id");
+    const temp = path.join(root, `.installation-${randomUUID()}`);
+    await writeFile(temp, randomUUID(), { flag: "wx", mode: 0o600 });
+    try {
+        // A hard link publishes a complete file without replacing a concurrent winner.
+        await link(temp, file).catch((error) => { if (error.code !== "EEXIST")
+            throw error; });
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+    const saved = await readFile(file, "utf8");
+    if (!/^[a-f0-9-]{36}$/.test(saved))
+        throw new Error("Invalid observability installation identity");
+    return saved;
+}
+const publishedRunCount = async (runs) => (await readdir(runs)).filter((name) => /^[a-f0-9-]{36}$/.test(name)).length;
+/** At capacity, try other queues without making an observed launch wait for a serial backlog. */
+export async function recoverObservationCapacity(input) {
+    const controller = new AbortController();
+    const pending = [...input.oldRuns];
+    let available = false;
+    const expired = new Promise((resolve) => controller.signal.addEventListener("abort", () => resolve(), { once: true }));
+    const timer = setTimeout(() => controller.abort(), input.timeoutMs ?? 2000);
+    const recover = async () => {
+        while (!controller.signal.aborted && !available) {
+            const old = pending.shift();
+            if (!old)
+                return;
+            try {
+                const ok = await flushQueue(old.dir, old.run, (batch) => input.send(batch, controller.signal));
+                if (controller.signal.aborted)
+                    return;
+                if (ok) {
+                    if (await queueIsEmpty(old.dir))
+                        await rm(old.dir, { recursive: true, force: true });
+                    // One batch may not empty a queue. Retry successful progress within the same deadline.
+                    else
+                        pending.push(old);
+                }
+                if (await publishedRunCount(input.runs) < (input.limit ?? 32))
+                    available = true;
+            }
+            catch { /* Keep unacknowledged metadata; another queue may be recoverable. */ }
+        }
+    };
+    try {
+        await Promise.race([Promise.all([recover(), recover()]), expired]);
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
+    }
+    return available;
+}
+/** Independent deadlines keep a failed backlog from dominating current collection or its peers. */
+export function createObservationUploader(input) {
+    const now = input.now ?? Date.now;
+    const oldRuns = input.oldRuns.map((old) => ({ ...old, failures: 0, retryAt: 0 }));
+    let active;
+    let failures = 0;
+    let retryAt = 0;
+    const flush = (forceCurrent = false) => {
+        if (active)
+            return active;
+        active = (async () => {
+            if (forceCurrent || now() >= retryAt) {
+                const ok = await flushQueue(input.current.dir, input.current.run, input.send).catch(() => false);
+                failures = ok ? 0 : Math.min(failures + 1, 5);
+                retryAt = now() + 2000 * 2 ** failures;
+            }
+            const index = oldRuns.findIndex((old) => now() >= old.retryAt);
+            if (index < 0)
+                return;
+            const [old] = oldRuns.splice(index, 1);
+            if (!old)
+                return;
+            let ok = false;
+            let complete = false;
+            try {
+                ok = await flushQueue(old.dir, old.run, input.send).catch((error) => error.code === "ENOENT");
+                if (ok && await queueIsEmpty(old.dir)) {
+                    await rm(old.dir, { recursive: true, force: true });
+                    complete = true;
+                }
+            }
+            finally {
+                if (!complete) {
+                    old.failures = ok ? 0 : Math.min(old.failures + 1, 5);
+                    old.retryAt = now() + 2000 * 2 ** old.failures;
+                    oldRuns.push(old);
+                }
+            }
+        })().catch(() => undefined).finally(() => { active = undefined; });
+        return active;
+    };
+    return { flush, finish: async () => { await active; await flush(true); } };
+}
+/** Called only after explicit --observe. Writes only beneath tab's private directory. */
+export async function prepareObservation(input) {
+    if (!identifier(input.agentId))
+        throw new Error("Observability needs a named Agent; run tab use. Continuing without collection.");
+    if (!input.config.token || !input.config.consoleUrl)
+        throw new Error("Observability needs tab login (machine session)");
+    if (process.platform === "win32")
+        throw new Error("Observability hooks currently support macOS and Linux");
+    const version = await installedVersion(input.command, input.env);
+    if (!supportedObservationVersion(input.harness, version))
+        throw new Error(`Observability does not support ${input.harness} ${version}; tested families: Claude 2.1.278+, Codex 0.155.1+`);
+    const root = path.join(input.root, "observability");
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const runs = path.join(root, "runs");
+    await mkdir(runs, { recursive: true, mode: 0o700 });
+    // Never grow indefinitely when offline. Only expired, inactive collector-owned runs are removed.
+    const oldRuns = [];
+    for (const name of await readdir(runs)) {
+        const staging = /^\.initializing-[a-f0-9-]{36}$/.test(name);
+        if (!staging && !/^[a-f0-9-]{36}$/.test(name))
+            continue;
+        const dir = path.join(runs, name);
+        if (await isActive(dir))
+            continue;
+        const age = await stat(dir).then((s) => Date.now() - s.mtimeMs, () => 0);
+        if (staging) {
+            if (age > 7 * 86400_000)
+                await rm(dir, { recursive: true, force: true });
+            continue;
+        }
+        // Complete published runs can recover immediately. Only unknown/empty directories need grace.
+        if (age > 7 * 86400_000 || (age >= 60_000 && await queueIsEmpty(dir))) {
+            await rm(dir, { recursive: true, force: true });
+            continue;
+        }
+        try {
+            const run = JSON.parse(await readFile(path.join(dir, "run.json"), "utf8"));
+            if (run.agentId === input.agentId)
+                oldRuns.push({ dir, run });
+        }
+        catch { /* A concurrent launch may still be writing its run metadata. */ }
+    }
+    const url = `${input.config.consoleUrl.replace(/\/$/, "")}/api/cli/observability`;
+    const send = async (body, signal) => {
+        const timeout = AbortSignal.timeout(2000);
+        const response = await fetch(url, { method: "POST", headers: { authorization: `Bearer ${input.config.token}`, "content-type": "application/json" }, body: JSON.stringify(body), signal: signal ? AbortSignal.any([timeout, signal]) : timeout, redirect: "error" });
+        await response.body?.cancel();
+        return response.ok;
+    };
+    const runCount = () => publishedRunCount(runs);
+    if (await runCount() >= 32) {
+        const recovered = await recoverObservationCapacity({ runs, oldRuns, send });
+        if (!recovered && await runCount() >= 32)
+            throw new Error("Observability queue is full; retry when the console is reachable");
+    }
+    const run = { id: randomUUID(), agentId: input.agentId, installationId: await installationId(root), harness: input.harness, harnessVersion: version };
+    const dir = path.join(runs, run.id);
+    // Cleanup only considers UUID directories. Publish after ownership and plugin files are complete.
+    const staging = path.join(runs, `.initializing-${run.id}`);
+    await mkdir(staging, { mode: 0o700 });
+    const script = fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "./observability-hook.ts" : "./observability-hook.js", import.meta.url));
+    const command = `${quote(process.execPath)} ${quote(script)}`;
+    const hooks = observationHooks(input.harness, command);
+    let args = codexObservationArgs(hooks);
+    try {
+        await writeFile(path.join(staging, "run.json"), JSON.stringify(run), { mode: 0o600 });
+        await writeFile(path.join(staging, "owner.pid"), String(process.pid), { mode: 0o600 });
+        if (input.harness === "claude") {
+            const plugin = path.join(staging, "claude-plugin");
+            await mkdir(path.join(plugin, ".claude-plugin"), { recursive: true, mode: 0o700 });
+            await mkdir(path.join(plugin, "hooks"), { recursive: true, mode: 0o700 });
+            await writeFile(path.join(plugin, ".claude-plugin", "plugin.json"), JSON.stringify({ name: "flocktab-observability", version: "1.0.0" }), { mode: 0o600 });
+            await writeFile(path.join(plugin, "hooks", "hooks.json"), JSON.stringify({ hooks }), { mode: 0o600 });
+            args = ["--plugin-dir", path.join(dir, "claude-plugin")];
+        }
+        await withObservationLock(runs, async () => {
+            if (await runCount() >= 32)
+                throw new Error("Observability queue is full; retry when the console is reachable");
+            await rename(staging, dir);
+        });
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+    const uploader = createObservationUploader({ current: { dir, run }, oldRuns, send });
+    void uploader.flush();
+    const timer = setInterval(() => { void uploader.flush(); }, 2000);
+    timer.unref();
+    return { args, env: { FLOCKTAB_OBSERVE_DIR: dir, FLOCKTAB_OBSERVE_HARNESS: input.harness }, stop: async () => {
+            clearInterval(timer);
+            await uploader.finish();
+            await rm(path.join(dir, "owner.pid"), { force: true });
+            if (await queueIsEmpty(dir))
+                await rm(dir, { recursive: true, force: true });
+        } };
+}

package/dist/project.js

@@ -16,6 +16,7 @@ export function projectFileName(env = process.env) {
     const name = env.FLOCKTAB_PROJECT_FILE?.trim();
     return name && /^\.[A-Za-z0-9._-]{1,40}$/.test(name) ? name : PROJECT_FILE;
 }
+const SLUG = /^[a-z0-9][a-z0-9-]*$/;
 async function exists(file) {
     try {
         await access(file);
@@ -40,19 +41,49 @@ export async function findProjectFile(cwd) {
         dir = parent;
     }
 }
-export async function readProject(cwd) {
+/** The whole file, cleaned: only valid slugs survive. */
+export async function readProjectConfig(cwd) {
     const file = await findProjectFile(cwd);
     if (!file)
         return undefined;
     try {
         const parsed = JSON.parse(await readFile(file, "utf8"));
-        const agent = parsed && typeof parsed === "object" ? parsed.agent : undefined;
-        if (typeof agent === "string" && /^[a-z0-9][a-z0-9-]*$/.test(agent))
-            return { file, agent };
+        if (!parsed || typeof parsed !== "object")
+            return { file, config: {} };
+        const raw = parsed;
+        const config = {};
+        if (typeof raw.agent === "string" && SLUG.test(raw.agent))
+            config.agent = raw.agent;
+        if (raw.agents && typeof raw.agents === "object") {
+            const agents = {};
+            for (const [harness, slug] of Object.entries(raw.agents)) {
+                if (typeof slug === "string" && SLUG.test(slug) && /^[a-z]{1,16}$/.test(harness))
+                    agents[harness] = slug;
+            }
+            if (Object.keys(agents).length > 0)
+                config.agents = agents;
+        }
+        return { file, config };
     }
     catch {
         // Unreadable: treat as absent and ask again.
+        return undefined;
     }
+}
+/**
+ * The Agent this folder runs `harness` as: its own entry, else the file's
+ * single `agent` (an older file, or a folder that made one Agent for
+ * everything before harnesses were told apart).
+ */
+export async function readProject(cwd, harness = "any") {
+    const found = await readProjectConfig(cwd);
+    if (!found)
+        return undefined;
+    const own = found.config.agents?.[harness];
+    if (own)
+        return { file: found.file, agent: own, own: true };
+    if (found.config.agent)
+        return { file: found.file, agent: found.config.agent, own: false };
     return undefined;
 }
 /** Where a new `.flocktab` goes: the git root above `cwd` when there is one, else `cwd`. */
@@ -72,6 +103,17 @@ export async function writeProject(dir, config) {
     await writeFile(file, `${JSON.stringify(config)}\n`);
     return file;
 }
+/** Set which Agent this folder runs `harness` as, keeping the rest of the file. */
+export async function assignProjectAgent(dir, harness, slug) {
+    const existing = (await readProjectConfig(dir))?.config ?? {};
+    const agents = { ...(existing.agents ?? {}) };
+    if (harness === "any") {
+        // The folder's default: also what older files meant by `agent`.
+        return writeProject(dir, { agent: slug, ...(Object.keys(agents).length > 0 ? { agents } : {}) });
+    }
+    agents[harness] = slug;
+    return writeProject(dir, { ...(existing.agent ? { agent: existing.agent } : {}), agents });
+}
 /** A default Agent name for a folder: its basename, kebab-cased. */
 export function agentNameFor(dir) {
     return path

package/dist/proxy-bin.js

@@ -13,7 +13,7 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { configDir } from "./config.js";
 /** The proxy release `tab up` fetches. Bump with each proxy tag. */
-export const PROXY_VERSION = "0.1.9";
+export const PROXY_VERSION = "0.1.12";
 export const RELEASES = "https://github.com/joseairosa/flocktab/releases/download";
 export function targetFor(platform = process.platform, arch = process.arch) {
     if (platform === "darwin")

package/dist/statusline.js

@@ -0,0 +1,114 @@
+/**
+ * `tab statusline`: one line for a harness's status bar. Which Agent this
+ * folder runs the harness as, and either the tab (spent of cap) or, on a
+ * subscription, the plan's windows as the vendor last reported them. Read
+ * from the console with a short cache, so a status bar that polls every
+ * few seconds costs one request a minute.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { configDir } from "./config.js";
+import { readProject } from "./project.js";
+import { api } from "./manage.js";
+const CACHE_MS = 60_000;
+function windowMinutes(window) {
+    const m = /^(\d+)([mhd])$/.exec(window);
+    return m ? Number(m[1]) * (m[2] === "d" ? 1440 : m[2] === "h" ? 60 : 1) : Number.MAX_SAFE_INTEGER;
+}
+function money(cents) {
+    const n = BigInt(cents);
+    return `$${n / 100n}.${(n % 100n).toString().padStart(2, "0")}`;
+}
+/** "5h 36% · 7d 29%", shortest window first; nothing when the vendor said nothing yet. */
+export function planLine(accounts, now = new Date()) {
+    // The account most recently seen with quota: the login in use.
+    const withQuota = accounts.filter((a) => a.quota.length > 0);
+    const account = withQuota[0];
+    if (!account)
+        return undefined;
+    const windows = [...account.quota]
+        .filter((w) => !w.resetsAt || new Date(w.resetsAt).getTime() > now.getTime())
+        .sort((a, b) => windowMinutes(a.window) - windowMinutes(b.window));
+    const who = account.email ?? `account ${account.externalId.slice(0, 8)}`;
+    return `${who} · ${windows.length === 0 ? "windows reset" : windows.map((w) => `${w.window} ${Math.round(w.usedPct)}%`).join(" · ")}`;
+}
+/** The line itself, from what the console said. */
+export function statusText(info, now = new Date()) {
+    const { tab } = info;
+    const closed = tab.state !== "open";
+    const head = `${tab.name}${closed ? " CLOSED" : ""}`;
+    if (tab.kind === "subscription") {
+        return `${head} · ${planLine(info.accounts ?? [], now) ?? "no call yet"}`;
+    }
+    const spent = BigInt(tab.spentCents);
+    const cap = BigInt(tab.capCents);
+    const pct = cap > 0n ? Number((spent * 100n) / cap) : 0;
+    return `${head} · ${money(tab.spentCents)} of ${money(tab.capCents)} / ${tab.window} (${pct}%)`;
+}
+/** The tab of this folder's Agent for `harness`, from a one-minute cache, else the console. */
+export async function statusline(config, harness, cwd = process.cwd(), env = process.env) {
+    const project = await readProject(cwd, harness);
+    if (!project)
+        return "FlockTab · no Agent here (tab use)";
+    const login = config.agents?.[project.agent];
+    const cacheFile = path.join(configDir(env), "cache", `status-${project.agent}.json`);
+    try {
+        const cached = JSON.parse(await readFile(cacheFile, "utf8"));
+        if (Date.now() - cached.at < CACHE_MS)
+            return cached.text;
+    }
+    catch {
+        // No cache yet.
+    }
+    let text;
+    try {
+        const info = await api(config)("GET", `/api/cli/tabs/${encodeURIComponent(project.agent)}`);
+        text = `FlockTab · ${statusText(info)}`;
+    }
+    catch {
+        return `FlockTab · ${login?.agentName ?? project.agent} · console unreachable`;
+    }
+    try {
+        await mkdir(path.dirname(cacheFile), { recursive: true, mode: 0o700 });
+        await writeFile(cacheFile, JSON.stringify({ at: Date.now(), text }), { mode: 0o600 });
+    }
+    catch {
+        // A missing cache only costs a request.
+    }
+    return text;
+}
+/**
+ * How each harness is told to run `tab statusline`. Claude Code takes it on
+ * the command line, so every `tab claude` has it. Grok Build and Kimi Code
+ * read it only from a config file in their home: written into a pool
+ * member's home (which tab owns), and into the person's own home only by
+ * `tab statusline install`, which asks.
+ */
+export function claudeSettingsArg(harness, tabBin = "tab") {
+    return ["--settings", JSON.stringify({ statusLine: { type: "command", command: `${tabBin} statusline ${harness}`, padding: 0 } })];
+}
+/** The lines Grok Build's config.toml needs; appended when `[ui.status_line]` is absent. */
+export function grokStatusToml(tabBin = "tab") {
+    return `\n[ui.status_line]\ntype = "command"\ncommand = "${tabBin} statusline grok"\n`;
+}
+/** Kimi Code's tui.toml block; appended when `[status_line]` is absent. */
+export function kimiStatusToml(tabBin = "tab") {
+    return `\n[status_line]\ncommand = "${tabBin} statusline kimi"\n`;
+}
+/** Add the status line to a harness home that does not have one. Returns what was done. */
+export async function installStatusLine(vendor, home, tabBin = "tab") {
+    const file = vendor === "xai" ? path.join(home, "config.toml") : path.join(home, "tui.toml");
+    const marker = vendor === "xai" ? "[ui.status_line]" : "[status_line]";
+    let current = "";
+    try {
+        current = await readFile(file, "utf8");
+    }
+    catch {
+        // No file yet.
+    }
+    if (current.includes(marker))
+        return "already";
+    await mkdir(home, { recursive: true, mode: 0o700 });
+    await writeFile(file, `${current.replace(/\s*$/, "\n")}${vendor === "xai" ? grokStatusToml(tabBin) : kimiStatusToml(tabBin)}`);
+    return "written";
+}

package/dist/tab-docs-shared.js

@@ -0,0 +1,9 @@
+/**
+ * The harness vocabulary, the same as `@flocktab/shared`'s. `tab` ships to
+ * npm alone, so it carries a copy rather than the dependency.
+ */
+export const HARNESSES = ["claude", "codex", "grok", "kimi", "any"];
+/** `dash-f4f` + `claude` -> `dash-f4f-claude`; `any` keeps the folder's name. */
+export function agentNameFor(project, harness) {
+    return harness === "any" ? project : `${project}-${harness}`;
+}