@hanamorilabs/tab 0.1.15 → 0.1.17

package/dist/cli.js

@@ -24,7 +24,7 @@
  */
 import { spawn } from "node:child_process";
 import { mkdir } from "node:fs/promises";
-import { hostname } from "node:os";
+import { homedir, hostname } from "node:os";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
@@ -34,6 +34,7 @@ import { describeLogin, localLogin } from "./logins.js";
 import { prepareCodexHome } from "./codex-home.js";
 import { addMember, loadPool, memberEnv, memberHome, POOL_VENDORS, poolVendorFor, prepareClaudeMember, prepareSharedSessions, limitsFor, removeMember, savePool, setGuard, setThreshold, thresholdFor, usage as quotaUsage } from "./pool.js";
 import { runPooled } from "./pool-run.js";
+import { claudeSettingsArg, installStatusLine, statusline } from "./statusline.js";
 import { renderPool } from "./pool-view.js";
 import { renderHelp } from "./help.js";
 import { findTabCommand } from "./tab-docs.js";
@@ -49,6 +50,8 @@ import { HARNESSES, agentNameFor as harnessAgentName } from "./tab-docs-shared.j
 import { downloadProxy, hasProxyEnv, packagedBinPath, proxyBinPath, proxyEnvPath, proxyInstalled, proxyLogPath, hasProxyLog, PROXY_VERSION, startProxy, stopProxy, tailProxyLog, writeProxyEnv, } from "./proxy-bin.js";
 import { proxyHealth, waitHealthy } from "./selfhost.js";
 import { TAB_VERSION } from "./version.js";
+import { takeObserveFlag } from "./observability-events.js";
+import { prepareObservation } from "./observability.js";
 const say = (text) => console.error(text);
 const ok = (text) => say(line("ok", text));
 const warn = (text) => say(line("warn", text));
@@ -337,9 +340,12 @@ async function resolveAgent(config, opts = {}) {
         return agents.env;
     const cwd = process.cwd();
     const project = opts.pick ? undefined : await readProject(cwd, harness);
-    if (project && agents[project.agent])
-        return agents[project.agent];
+    // The key this machine holds for the folder's Agent. It is not proof the Agent still exists: the
+    // console may have archived it since, so the console is asked before anything launches on it.
+    const cached = project ? agents[project.agent] : undefined;
     if (!config.token || !config.consoleUrl) {
+        if (cached)
+            return cached;
         fail(`This machine is not logged in. Run ${bold("tab login")}.`);
         return undefined;
     }
@@ -348,6 +354,9 @@ async function resolveAgent(config, opts = {}) {
         listed = await listAgents(config.consoleUrl, config.token);
     }
     catch (err) {
+        // The console cannot answer; the key on hand still runs, and the proxy refuses on its own if the Agent is gone.
+        if (cached)
+            return cached;
         fail(err instanceof ConsoleApiError && err.status === 401 ? `Session expired. Run ${bold("tab login")}.` : String(err instanceof Error ? err.message : err));
         return undefined;
     }
@@ -356,13 +365,17 @@ async function resolveAgent(config, opts = {}) {
     let created;
     if (project) {
         chosen = byName.get(project.agent);
+        if (chosen && cached)
+            return cached;
         if (!chosen) {
-            warn(`${project.file} names Agent ${bold(project.agent)}, which ${listed.flock.name} no longer has.`);
+            warn(`${project.file} names Agent ${bold(project.agent)}, which ${listed.flock.name} no longer has (archived or deleted). Pick the Agent this folder runs as now.`);
         }
     }
     if (!chosen) {
         const root = await projectRoot(cwd);
-        const suggested = harnessAgentName(agentNameFor(root), harness);
+        // The Agent is named after the project; the harness is a property, shown by its mark. The slug
+        // (unique, permanent) carries the harness so a project's Claude and Codex Agents are told apart.
+        const suggested = agentNameFor(root);
         say(heading(harness === "any" ? "Which Agent does this folder run as?" : `Which Agent does this folder run ${harness} as?`));
         say(dim(`${root}  ·  flock ${listed.flock.name}${harness === "any" ? "" : `  ·  one harness per Agent: this one is for ${harness}`}`));
         // Only Agents of this harness, plus untied ones (made before harnesses were told apart) that can be tied now.
@@ -372,7 +385,7 @@ async function resolveAgent(config, opts = {}) {
                 `${bold(String(i + 1))}  ${a.name}`,
                 `${a.state === "open" ? green("open") : yellow(a.state)}  ${a.kind === "subscription" ? yellow("subscription") : dim("api")}  ${dim(a.harness && a.harness !== "any" ? a.harness : "untied")}${a.kind === "api" ? dim(`  $${(Number(a.capCents) / 100).toFixed(2)} cap`) : ""}${agents[a.slug] ? dim("  keyed here") : a.hasKey ? dim("  keyed elsewhere") : ""}`,
             ]),
-            [`${bold("n")}  New Agent`, dim(`named ${suggested}, $50.00 cap`)],
+            [`${bold("n")}  New Agent`, dim(`named ${suggested}${harness === "any" ? "" : ` (${harness})`}, $50.00 cap`)],
         ]));
         const answer = await ask(`Choose 1-${options.length} or ${bold("n")} ${dim("[n]")}: `);
         if (answer === "" || answer.toLowerCase() === "n") {
@@ -382,7 +395,7 @@ async function resolveAgent(config, opts = {}) {
                 [`${bold("2")}  Subscription`, dim("your own Claude Max / ChatGPT / SuperGrok / Kimi logins; gated and recorded, never charged")],
             ]));
             const which = await ask(`Which kind? ${bold("1")} or ${bold("2")} ${dim("[1]")}: `);
-            created = { name, kind: which.trim() === "2" ? "subscription" : "api", harness };
+            created = { name, slug: harnessAgentName(name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""), harness), kind: which.trim() === "2" ? "subscription" : "api", harness };
         }
         else {
             const index = Number.parseInt(answer, 10);
@@ -396,7 +409,7 @@ async function resolveAgent(config, opts = {}) {
     let issued;
     try {
         if (created) {
-            issued = await createAgent(config.consoleUrl, config.token, { name: created.name, kind: created.kind, harness: created.harness });
+            issued = await createAgent(config.consoleUrl, config.token, { name: created.name, slug: created.slug, kind: created.kind, harness: created.harness });
             ok(`Created ${created.kind === "subscription" ? "subscription" : "API-key"} ${created.harness === "any" ? "" : `${created.harness} `}Agent ${bold(issued.agent.name)}${created.kind === "api" ? " with a $50.00 cap. Change it in the console." : "."}`);
         }
         else if (chosen) {
@@ -568,7 +581,12 @@ async function poolIdle(config, vendor, agentName) {
     return !(await flockAccounts(config)).some((a) => a.provider === vendor && new Date(a.lastSeenAt).getTime() > recent);
 }
 async function runAgent(name, argv) {
-    const { args, noPool, asked, pinned } = takePoolFlags(argv);
+    const observationFlags = takeObserveFlag(argv);
+    const { args, noPool, asked, pinned } = takePoolFlags(observationFlags.args);
+    if (observationFlags.observe && name !== "claude" && name !== "codex") {
+        fail("--observe supports Claude Code and Codex only.");
+        return 2;
+    }
     const config = await ensureLogin();
     if (!config)
         return 2;
@@ -644,8 +662,17 @@ async function runAgent(name, argv) {
             auth,
         });
     }
+    // Claude Code shows the tab in its status bar, from the command line so no file of the person's is touched.
+    const tabBin = process.env.FLOCKTAB_DEV ? "tabdev" : "tab";
+    const statusArgs = name === "claude" && !args.includes("--settings") && !args.includes("-p") && !args.includes("--print") ? claudeSettingsArg("claude", tabBin) : [];
+    const observation = observationFlags.observe
+        ? await prepareObservation({ root: configDir(), harness: name, command: spec.command, agentId: agent.agentId, config, env })
+            .catch((error) => { warn(error instanceof Error ? error.message : "Observability unavailable; continuing without collection."); return undefined; })
+        : undefined;
+    if (observation)
+        say(dim("Observability: metadata only. Review the FlockTab hooks in your harness; skipped hooks mean unavailable coverage."));
     const launch = (launchArgs, launchEnv) => {
-        const child = spawn(spec.command, [...(spec.args ?? []), ...launchArgs], { stdio: "inherit", env: launchEnv });
+        const child = spawn(spec.command, [...(spec.args ?? []), ...statusArgs, ...(observation?.args ?? []), ...launchArgs], { stdio: "inherit", env: { ...launchEnv, ...observation?.env } });
         const done = new Promise((resolve) => {
             child.on("error", (err) => {
                 if (err.code === "ENOENT") {
@@ -663,11 +690,15 @@ async function runAgent(name, argv) {
         return { done, stop: () => void child.kill("SIGTERM") };
     };
     if (!pooled || !poolVendor || !pool)
-        return launch(args, env).done;
+        return launch(args, env).done.finally(() => observation?.stop().catch(() => undefined));
     // Codex members each need their own home written before the first launch;
     // Codex, Grok and Kimi members share one conversations folder.
     for (const member of members)
         await prepareSharedSessions(poolVendor, member);
+    if (poolVendor === "xai" || poolVendor === "kimi") {
+        for (const member of members)
+            await installStatusLine(poolVendor, memberHome(poolVendor, member), tabBin).catch(() => undefined);
+    }
     void registerPoolLogins(config, pool);
     if (poolVendor === "openai") {
         for (const member of members) {
@@ -690,7 +721,7 @@ async function runAgent(name, argv) {
             });
         }),
         say: (text) => say(dim(text)),
-    });
+    }).finally(() => observation?.stop().catch(() => undefined));
 }
 /**
  * `tab pool`: several logins of one vendor on this machine. Each member is
@@ -888,6 +919,26 @@ function pathHint() {
     say(`  ${bold(pathLine())}`);
     return 0;
 }
+/**
+ * `tab statusline install grok|kimi`: put `tab statusline` into the harness's
+ * own config, in the person's home. Asks first; that file is theirs.
+ */
+async function statuslineInstall(args) {
+    const word = args[0];
+    const vendor = word === "grok" ? "xai" : word === "kimi" ? "kimi" : undefined;
+    if (!vendor) {
+        fail(`tab statusline install grok|kimi. ${dim("Claude Code gets it on every tab claude; Codex shows its own limits and takes no command.")}`);
+        return 2;
+    }
+    const home = vendor === "xai" ? path.join(homedir(), ".grok") : path.join(homedir(), ".kimi-code");
+    const file = path.join(home, vendor === "xai" ? "config.toml" : "tui.toml");
+    const go = await ask(`Add a status line running ${bold("tab statusline " + word)} to ${dim(file)}? ${dim("[y/N]")}: `);
+    if (!/^y(es)?$/i.test(go))
+        return 1;
+    const done = await installStatusLine(vendor, home, process.env.FLOCKTAB_DEV ? "tabdev" : "tab");
+    ok(done === "already" ? `${file} already has a status line; left as it is.` : `Added. It shows on the next ${word} launch.`);
+    return 0;
+}
 /** `tab use [claude|codex|grok|kimi]`: pick or change the Agent this folder runs a harness as; bare, the folder's default. */
 async function use(args) {
     const config = await ensureLogin();
@@ -1120,6 +1171,17 @@ async function main(argv) {
             return poolCommand(rest);
         case "status":
             return status();
+        case "statusline": {
+            if (rest[0] === "install")
+                return statuslineInstall(rest.slice(1));
+            const config = await loadConfig();
+            if (!config) {
+                console.log("FlockTab · not logged in");
+                return 0;
+            }
+            console.log(await statusline(config, rest[0] && harnessOf(rest[0]) !== "any" ? harnessOf(rest[0]) : "any"));
+            return 0;
+        }
         case "log":
             if (rest.includes("--proxy"))
                 return logs(rest.filter((a) => a !== "--proxy"));

package/dist/codex-home.js

@@ -30,8 +30,17 @@ export function codexSubscriptionToml(proxyUrl, presentedKey, model) {
     const lines = [
         `preferred_auth_method = "chatgpt"`,
         `chatgpt_base_url = ${JSON.stringify(`${passthroughBase(proxyUrl, presentedKey, "openai")}/backend-api/`)}`,
+        // Codex 0.155+ sends the model calls of a ChatGPT login to `openai_base_url` (fixed to
+        // chatgpt.com/backend-api/codex unless set); `chatgpt_base_url` only covers the rest.
+        `openai_base_url = ${JSON.stringify(`${passthroughBase(proxyUrl, presentedKey, "openai")}/backend-api/codex`)}`,
         ...(model ? [`model = ${JSON.stringify(model)}`] : []),
         ``,
+        // Codex 0.155+ opens a WebSocket for responses on the ChatGPT provider. The tab is plain HTTP
+        // (no upgrade on either proxy), so with it on the first prompt hangs. Off, Codex uses HTTP streaming.
+        `[features]`,
+        `responses_websockets = false`,
+        `responses_websockets_v2 = false`,
+        ``,
     ];
     return lines.join("\n");
 }

package/dist/manage.js

@@ -221,7 +221,7 @@ export async function accounts(config, flags) {
             String(a.calls),
             a.quota.length === 0 ? dim("-") : a.quota.map((q) => `${q.window} ${left(q)}`).join("  "),
             a.agents.join(", "),
-        ]), { right: [3, 4, 5] }) + `\n${dim("Set a price or label in the console, Control, Accounts.")}`;
+        ]), { right: [3, 4, 5] }) + `\n${dim("Set a price or label in the console, Control, Subscriptions.")}`;
     });
     return 0;
 }
@@ -407,19 +407,19 @@ export async function ledger(config, flags) {
     const { rows: list, timezone } = await call("GET", `/api/cli/ledger?${params}`);
     emit(flags.json, { timezone, rows: list }, () => list.length === 0
         ? dim("No decisions yet.")
-        : table(["time", "agent", "action", "amount", "status", "reason"], list.map((r) => {
+        : table(["time", "agent", "action", "model", "amount", "status", "reason"], list.map((r) => {
             // A subscription call is recorded at list price; nothing was held, so there is no "of".
             const shadow = r.status === "shadow";
             const status = shadow ? "SUBSCRIPTION" : (r.status ?? r.decision).toUpperCase();
             const paint = status === "BLOCKED" || status === "CLOSED" ? red : status === "PENDING" ? yellow : green;
             const held = !shadow && r.reservedCents && r.reservedCents !== r.cents ? dim(` of ${money(r.reservedCents)}`) : "";
-            return [r.at, r.agent, r.action.length > 28 ? `${r.action.slice(0, 27)}…` : r.action, `${money(r.cents)}${held}`, paint(status), r.reason];
+            return [r.at, r.agent, r.action.length > 28 ? `${r.action.slice(0, 27)}…` : r.action, r.model ? `${r.model}${r.effort ? dim(` ${r.effort}`) : ""}${r.tier ? yellow(` ${r.tier}`) : ""}` : dim("-"), `${money(r.cents)}${held}`, paint(status), r.reason];
         }), { right: [3] }) + `\n${dim(`times in ${timezone}`)}`);
     return 0;
 }
 export async function spend(config, flags) {
     const call = api(config);
-    const by = flags.opts.by ?? (flags.args[0] === "day" || flags.args[0] === "project" || flags.args[0] === "agent" ? flags.args[0] : "agent");
+    const by = flags.opts.by ?? (["day", "project", "agent", "model", "models"].includes(flags.args[0] ?? "") ? flags.args[0].replace(/s$/, "") : "agent");
     const params = new URLSearchParams({ by });
     if (flags.opts.since)
         params.set("since", flags.opts.since);
@@ -433,6 +433,25 @@ export async function spend(config, flags) {
                 ? dim("Nothing settled in the window.")
                 : table(["day", "calls", "settled", "in", "out"], days.map((d) => [d.day, String(d.calls), money(d.settledCents), d.promptTokens, d.completionTokens]), { right: [1, 2, 3, 4] });
         }
+        if (by === "model") {
+            const ms = data.models;
+            if (ms.length === 0)
+                return dim("No settled calls in the window.");
+            const total = ms.reduce((sum, m) => sum + BigInt(m.cents), 0n);
+            // Charged on a tab, or priced at list on a plan: two different dollars, told apart per row.
+            return `${table(["model", "effort", "tier", "harness", "paid by", "calls", "cost", "in", "out", "share"], ms.map((m) => [
+                m.model,
+                m.effort ?? dim("-"),
+                m.tier ? yellow(m.tier) : dim("-"),
+                m.harness === "any" ? dim("any") : m.harness,
+                m.kind === "shadow" ? yellow("plan (list)") : "tab",
+                String(m.calls),
+                money(m.cents),
+                m.promptTokens,
+                m.completionTokens,
+                total > 0n ? `${(Number((BigInt(m.cents) * 1000n) / total) / 10).toFixed(1)}%` : "-",
+            ]), { right: [5, 6, 7, 8, 9] })}\n${dim(`${money(total)} in the window (${data.since}); tab spend and list price on plans added together. --since 7d, --agent <agent>.`)}`;
+        }
         if (by === "project") {
             const ps = data.projects;
             const lines = table(["project", "agents", "meter", "outside", "total"], ps.map((p) => [p.name, String(p.agents), money(p.meterCents), money(p.outsideCents), money(BigInt(p.meterCents) + BigInt(p.outsideCents))]), { right: [1, 2, 3, 4] });

package/dist/observability-events.js

@@ -0,0 +1,80 @@
+import { createHash, randomUUID } from "node:crypto";
+export function takeObserveFlag(argv) {
+    let observe = false;
+    let passthrough = false;
+    const args = argv.filter((arg) => {
+        if (arg === "--")
+            passthrough = true;
+        if (!passthrough && arg === "--observe") {
+            observe = true;
+            return false;
+        }
+        return true;
+    });
+    return { observe, args };
+}
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
+// Do not truncate identifiers: doing so can merge distinct runtime identities.
+export const identifier = (v) => typeof v === "string" && /^[A-Za-z0-9_./:@-]{1,128}$/.test(v) ? v : undefined;
+const label = (v) => typeof v === "string" && /^[\p{L}\p{N}_./:@ \[\]-]{1,120}$/u.test(v) ? v : undefined;
+const lifecycle = { SessionStart: "session_start", SessionEnd: "session_end", SubagentStart: "worker_start", SubagentStop: "worker_stop" };
+export const CODEX_SEND_TOOLS = ["send_input", "send_message", "followup_task", "collaboration.send_message", "collaboration.followup_task"];
+/** Input is never persisted. Only documented native identifiers cross this boundary. */
+export function sanitizeHookEvent(raw, harness, now = new Date()) {
+    const data = object(raw);
+    const sessionId = identifier(data.session_id);
+    if (!sessionId || typeof data.hook_event_name !== "string")
+        return undefined;
+    const hook = data.hook_event_name;
+    const input = object(data.tool_input);
+    const workerId = identifier(data.agent_id);
+    const toolCallId = identifier(data.tool_use_id);
+    let kind = lifecycle[hook];
+    let recipientSessionId;
+    let recipientLabel;
+    let outcome;
+    if (!kind) {
+        if (hook !== "PostToolUse" && hook !== "PostToolUseFailure")
+            return undefined;
+        if (harness === "claude" && data.tool_name === "SendMessage") {
+            // A notify_when_idle-only subscription is not an inter-agent message.
+            if (!(typeof input.content === "string" && input.content.length > 0) && !(typeof input.message === "string" && input.message.length > 0))
+                return undefined;
+            // Current native schema is to/message; older versions use recipient/content.
+            if (input.message !== undefined && typeof input.message !== "string")
+                return undefined;
+            if (input.type !== undefined && input.type !== "message" && input.type !== "broadcast")
+                return undefined;
+            kind = "send";
+            recipientLabel = label(input.to ?? input.recipient);
+        }
+        else if (harness === "claude" && data.tool_name === "SubagentHandback" && workerId) {
+            // A nested worker can report to another worker; session_id alone cannot identify that parent.
+            kind = "report";
+            recipientLabel = "parent";
+        }
+        else if (harness === "codex" && typeof data.tool_name === "string" && CODEX_SEND_TOOLS.includes(data.tool_name)) {
+            kind = "send";
+            // send_input's id is a native thread id. Named collaboration targets are labels.
+            if (data.tool_name === "send_input")
+                recipientSessionId = identifier(input.id);
+            else
+                recipientLabel = label(input.target);
+        }
+        else
+            return undefined;
+        if (!toolCallId)
+            return undefined;
+        const response = object(data.tool_response);
+        const failed = hook === "PostToolUseFailure" || (harness === "claude" && (response.success === false || object(response.data).success === false));
+        outcome = failed ? "failed" : harness === "claude" ? "succeeded" : "observed";
+    }
+    if ((kind === "worker_start" || kind === "worker_stop") && !workerId)
+        return undefined;
+    // Native tool ids dedupe retries; lifecycle events can recur on resume and get fresh ids.
+    const id = toolCallId && (kind === "send" || kind === "report")
+        ? createHash("sha256").update(JSON.stringify([sessionId, workerId, toolCallId, kind, outcome])).digest("hex") : randomUUID();
+    return { id, kind, occurredAt: now.toISOString(), sessionId,
+        ...(workerId ? { workerId } : {}), ...(toolCallId && outcome ? { toolCallId } : {}),
+        ...(recipientSessionId ? { recipientSessionId } : {}), ...(recipientLabel ? { recipientLabel } : {}), ...(outcome ? { outcome } : {}) };
+}

package/dist/observability-hook.js

@@ -0,0 +1,36 @@
+/** Internal hook executable. No credentials, network calls, logs, or raw-payload files. */
+import { sanitizeHookEvent } from "./observability-events.js";
+import { enqueueEvent } from "./observability-queue.js";
+import { randomUUID } from "node:crypto";
+async function recordGap() {
+    const dir = process.env.FLOCKTAB_OBSERVE_DIR;
+    if (!dir)
+        return;
+    await enqueueEvent(dir, { id: randomUUID(), kind: "gap", sessionId: "collector", occurredAt: new Date().toISOString(), droppedCount: 1 });
+}
+async function collect() {
+    const dir = process.env.FLOCKTAB_OBSERVE_DIR;
+    const harness = process.env.FLOCKTAB_OBSERVE_HARNESS;
+    if (!dir || (harness !== "claude" && harness !== "codex"))
+        return;
+    let size = 0;
+    const parts = [];
+    for await (const chunk of process.stdin) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.length;
+        if (size > 1024 * 1024) {
+            await recordGap();
+            return;
+        }
+        parts.push(bytes);
+    }
+    const event = sanitizeHookEvent(JSON.parse(Buffer.concat(parts).toString("utf8")), harness);
+    if (event)
+        await enqueueEvent(dir, event);
+}
+// Telemetry failure must never block or steer a tool. No payload-derived error text.
+const timeout = setTimeout(() => { process.stdout.write("{}\n"); process.exit(0); }, 1500);
+void collect().catch(() => recordGap().catch(() => undefined)).finally(() => {
+    clearTimeout(timeout);
+    process.stdout.write("{}\n");
+});

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/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.10";
+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.js

@@ -38,7 +38,7 @@ export const TAB_COMMANDS = [
         usage: ["use", "use claude|codex|grok|kimi"],
         summary: "Pick or change the Agent this folder runs a harness as.",
         details: [
-            "An Agent is one harness on one project. tab claude and tab codex in the same folder are two Agents (that is what the plan counts), each asked for once: the first run of a harness in a folder lists the flock's Agents of that harness (and untied ones it can tie), or makes a new one named <folder>-<harness> and asks its kind. The choice goes into .flocktab at the git root, one entry per harness, and a key for that Agent is minted and kept on this machine.",
+            "An Agent is one harness on one project. tab claude and tab codex in the same folder are two Agents (that is what the plan counts), each asked for once: the first run of a harness in a folder lists the flock's Agents of that harness (and untied ones it can tie), or makes a new one named after the folder (its slug is <folder>-<harness>, since a project's Claude and Codex Agents are two) and asks its kind. The choice goes into .flocktab at the git root, one entry per harness, and a key for that Agent is minted and kept on this machine.",
             "tab use codex changes the answer for one harness; bare tab use sets the folder's default, which every other command (tab python …) runs as. An older .flocktab with a single Agent applies to every harness until one is set apart.",
             "An Agent that already holds a key on another machine can be used here too, but minting a key here replaces the one there. tab asks before doing it.",
         ],
@@ -50,18 +50,20 @@ export const TAB_COMMANDS = [
         aliases: ["codex", "grok", "kimi", "gemini", "aider", "cursor", "<command>"],
         group: "run",
         usage: ["claude [args]", "codex [args]", "grok [args]", "kimi [args]", "<any command> [args]"],
-        summary: "Run an agent on this folder's tab. Everything after the name goes to the agent untouched.",
+        summary: "Run an agent on this folder's tab. Harness arguments pass through after tab's run options.",
         details: [
             "tab sets the environment that agent reads (its base URL and key, or for Codex a home folder of its own) and starts it. It does not wrap or parse the agent's traffic; the proxy does the gating.",
             "On an API-key Agent the agent presents the tab's key, the flock's provider key pays, and every call is held, settled and charged to the cap. A call that would pass the cap is refused before the provider with 402 tab_closed.",
             "On a Subscription Agent the agent keeps its own login (Claude Max, ChatGPT, SuperGrok, Kimi). The tab key rides in the base URL, the same kill switch and policies apply before the vendor is reached, the call is recorded at list price under the account the vendor names, and nothing is charged to the cap.",
             "Any other command works too: tab points both the OpenAI and the Anthropic variables at the proxy and runs it. An agent with no consumer plan on a Subscription Agent runs metered on the flock's key, and tab says so.",
             "With logins in the pool for that vendor, a Subscription Agent runs as the login with most room. See tab pool.",
+            "Opt in with tab claude --observe or tab codex --observe to show native sessions, workers and observed messages in Observability. Review and trust the added hooks in the harness normally; collection is unavailable if hooks are skipped. Only identifiers, timestamps and tool outcomes leave the machine, never prompts, message bodies or transcripts. A successful send is not a read receipt. Collection is experimental: Claude 2.1.278+ in the 2.1 family and Codex 0.155.1+ in the 0.155 family, on macOS/Linux. Offline metadata is bounded and retried on another observed launch of the same Agent; inactive queues older than seven days are removed on the next observed launch, and overflow is counted as a coverage gap.",
         ],
         options: [
             { flag: "--as <login>", what: "run as one pool login and never move off it" },
             { flag: "--no-pool", what: "ignore the pool and use the agent's usual login" },
             { flag: "--pool", what: "require the pool; fail rather than fall back when it cannot be used" },
+            { flag: "--observe", what: "opt in to metadata-only native communication hooks for this Claude/Codex launch; put before --" },
         ],
         examples: [
             { cmd: "tab claude", what: "Claude Code on this folder's tab" },
@@ -209,7 +211,10 @@ export const TAB_COMMANDS = [
         group: "agents",
         usage: ["archive [agent]"],
         summary: "Close an Agent for good and take it off the bill. Its history stays.",
-        details: ["The tab closes for good, the Agent leaves the lists and stops counting towards the plan's Agents. Its ledger rows stay."],
+        details: [
+            "The tab closes for good, the Agent leaves the lists and stops counting towards the plan's Agents. Its ledger rows stay.",
+            "Its keys stop working everywhere (the proxies answer key_revoked). A folder still bound to it asks for an Agent again on the next launch.",
+        ],
         options: [{ flag: "--yes", what: "do not ask" }],
     },
     {
@@ -220,7 +225,7 @@ export const TAB_COMMANDS = [
         summary: "Every plan login your Subscription Agents were seen on, and how used it is.",
         details: [
             "Accounts are discovered, never typed in: the vendor names the login on every reply, and FlockTab files the call under it. Each row shows the plan, the seat price taken from the plan tier, what the last 30 days would have cost at list price, the number of calls, and the usage the vendor last reported per window.",
-            "The console shows the same under Spend, Subscriptions; a label or a seat price of your own is set under Control, Accounts.",
+            "The console shows the same under Control, Subscriptions, where a label or a seat price of your own is set.",
         ],
         see: ["pool", "agent"],
     },
@@ -268,6 +273,22 @@ export const TAB_COMMANDS = [
         details: ["The first thing to run when something is off. Exit code 0 only when the machine is logged in, the folder has an Agent with a key here, and the proxy is healthy."],
         see: ["login", "use", "up"],
     },
+    {
+        name: "statusline",
+        overview: "statusline [harness]",
+        group: "watch",
+        usage: ["statusline [claude|codex|grok|kimi]", "statusline install grok|kimi"],
+        summary: "One line for a harness's status bar: the Agent and its tab, or the plan's windows.",
+        details: [
+            "Prints what this folder runs the harness as, then either spent of cap for an API-key Agent or, for a subscription, the login in use and each window's usage as the vendor last reported it (5h 36% · 7d 29%). Read from the console at most once a minute, so a status bar that refreshes every few seconds costs nothing.",
+            "Claude Code shows it on every tab claude, passed on the command line so no file of yours is touched (your own --settings wins). Grok Build and Kimi Code read a status line only from their config; a pool member gets it (that home is tab's), and tab statusline install grok|kimi adds it to your own config after asking. Codex takes no command and already shows its own limits.",
+        ],
+        examples: [
+            { cmd: "tab statusline claude", what: "the line, as Claude Code's status bar would show it" },
+            { cmd: "tab statusline install grok", what: "add it to ~/.grok/config.toml" },
+        ],
+        see: ["status", "accounts"],
+    },
     {
         name: "log",
         overview: "log [-f] | log --proxy",
@@ -304,14 +325,18 @@ export const TAB_COMMANDS = [
     {
         name: "spend",
         group: "watch",
-        usage: ["spend [agent|project|day]"],
-        summary: "What was spent through the tab, and outside it, grouped.",
-        details: ["Meter spend is what went through FlockTab. Outside spend is what the connected billing sources report (Team plan and up), so the two can be told apart."],
+        usage: ["spend [agent|project|day|model]"],
+        summary: "What was spent through the tab, and outside it, grouped: by Agent, project, day, or model and effort.",
+        details: [
+            "Meter spend is what went through FlockTab. Outside spend is what the connected billing sources report (Team plan and up), so the two can be told apart.",
+            "tab spend model lists each model with the reasoning effort the requests asked for (OpenAI's reasoning effort, Anthropic's effort or thinking budget) and the speed tier (fast, priority, flex), how many calls, what they cost and how they were paid: charged to a tab, or priced at list on a plan. The console shows the same under Spend, Models.",
+        ],
         options: [
-            { flag: "--by agent|project|day", what: "how to group" },
+            { flag: "--by agent|project|day|model", what: "how to group" },
             { flag: "--since 7d", what: "how far back" },
             { flag: "--agent <agent>", what: "only one Agent" },
         ],
+        examples: [{ cmd: "tab spend model --since 30d", what: "a month per model and effort" }],
         see: ["outside", "ledger"],
     },
     {
@@ -407,9 +432,11 @@ export const TAB_GLOSSARY = [
     { term: "Pool", meaning: "Several logins of one vendor on one machine, and tab choosing between them by reported usage. Each member is a folder the agent signs in to itself." },
     { term: "Threshold", meaning: "In the pool: the share of the short window at which a login gives way to one with more room. 80% unless set, per vendor if you like." },
     { term: "Weekly guard", meaning: "In the pool: the share of the long window from which a login gives way whatever its short window says. 95% unless set. Below it the weekly window is ignored." },
-    { term: "Account switch", meaning: "An Agent's call landing on a different account of the same vendor than its previous one: a new login mid-session, another machine, or the pool moving. Shown on the Agent's page and under Accounts." },
+    { term: "Account switch", meaning: "An Agent's call landing on a different account of the same vendor than its previous one: a new login mid-session, another machine, or the pool moving. Shown on the Agent's page and under Control, Subscriptions." },
     { term: "Project", meaning: "A label grouping Agents for chargeback on FlockTab's own meter, optionally linked to a GitHub repository. Team plan and up." },
     { term: "Outside spend", meaning: "Money that did not go through a tab, read from provider admin APIs and cloud billing, so it can be told apart from metered spend. Team plan and up." },
+    { term: "Tier", also: ["service tier", "fast mode", "speed"], meaning: "A speed the request asked for, in the request's own words: OpenAI's and xAI's service_tier (fast, priority, flex), Anthropic's speed (fast). Vendors price these apart, so it is kept on every call and shown beside the model on the ledger and under Spend, Models." },
+    { term: "Effort", also: ["reasoning effort", "thinking budget"], meaning: "How hard a request asked the model to think, in the request's own words: OpenAI's reasoning effort (low, medium, high, xhigh), Anthropic's effort or a thinking budget in tokens. Kept on every call, shown on the ledger and under Spend, Models, because it is where the money goes." },
     { term: "Ledger", meaning: "Every decision, one row per call: allowed, settled, refunded, blocked and why. Money is whole cents, never a fraction. If the ledger cannot be reached, no call goes out." },
     { term: "Fail closed", meaning: "When FlockTab cannot be sure a call fits (the ledger is down, the key is unknown, the unlock is missing) the call is refused rather than let through." },
     { term: ".flocktab", meaning: "A one-line file at a project's root naming the Agent that folder runs as. Safe to commit: it holds no key." },

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Written by scripts/write-version.mjs from package.json at build; `tab version` prints it. */
-export const TAB_VERSION = "0.1.15";
+export const TAB_VERSION = "0.1.17";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanamorilabs/tab",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Run any AI agent on a FlockTab tab: tab claude, tab codex, tab <command>.",
   "license": "MIT",
   "type": "module",
@@ -22,11 +22,11 @@
     "prepublishOnly": "pnpm build"
   },
   "optionalDependencies": {
-    "@hanamorilabs/flocktab-proxy-darwin-arm64": "0.1.10",
-    "@hanamorilabs/flocktab-proxy-darwin-x64": "0.1.10",
-    "@hanamorilabs/flocktab-proxy-linux-x64": "0.1.10",
-    "@hanamorilabs/flocktab-proxy-linux-arm64": "0.1.10",
-    "@hanamorilabs/flocktab-proxy-win-x64": "0.1.10"
+    "@hanamorilabs/flocktab-proxy-darwin-arm64": "0.1.12",
+    "@hanamorilabs/flocktab-proxy-darwin-x64": "0.1.12",
+    "@hanamorilabs/flocktab-proxy-linux-x64": "0.1.12",
+    "@hanamorilabs/flocktab-proxy-linux-arm64": "0.1.12",
+    "@hanamorilabs/flocktab-proxy-win-x64": "0.1.12"
   },
   "devDependencies": {
     "@types/node": "^22.18.6",