@hanamorilabs/tab 0.1.14 → 0.1.16

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,20 +34,24 @@ 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";
-import { ConsoleApiError, createAgent, issueAgentKey, listAgents } from "./console-api.js";
+import { ConsoleApiError, createAgent, issueAgentKey, listAgents, setAgentHarness } from "./console-api.js";
 import { consoleUrlFor, DeviceLoginError, startDeviceLogin, waitForApproval } from "./device-login.js";
 import { clearConfig, configDir, configPath, HOSTED_PROXY, isLocalProxy, loadConfig, LOCAL_PROXY, normalizeProxyUrl, presentedKey, saveConfig, } from "./config.js";
 import { reportFolder } from "./folder.js";
 import { whoami } from "./proxy-identity.js";
 import { listAliases, pathLine, pathWithoutShims, removeAlias, shimDir, shimDirOnPath, validAliasName, writeAlias } from "./alias.js";
 import * as manage from "./manage.js";
-import { agentNameFor, projectRoot, readProject, writeProject } from "./project.js";
+import { agentNameFor, assignProjectAgent, projectRoot, readProject } from "./project.js";
+import { HARNESSES, agentNameFor as harnessAgentName } from "./tab-docs-shared.js";
 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));
@@ -319,13 +323,23 @@ async function bringUp(proxyUrl) {
  * holds its key. Missing either: ask (or, with `.flocktab` present, mint the
  * key silently for this machine), save both, carry on.
  */
+/** `claude`, `codex`, `grok`, `kimi`, else `any`: the harness a command is. */
+function harnessOf(command) {
+    return HARNESSES.includes(command) && command !== "any" ? command : "any";
+}
+/**
+ * The Agent this folder runs `harness` as. One harness on one project is
+ * one Agent, so `tab claude` and `tab codex` in a folder are two Agents
+ * (that is what the plan counts), each asked for once.
+ */
 async function resolveAgent(config, opts = {}) {
     const agents = config.agents ?? {};
+    const harness = opts.harness ?? "any";
     // CI and scripts: FLOCKTAB_KEY is the Agent, no folder involved.
     if (agents.env && !opts.pick)
         return agents.env;
     const cwd = process.cwd();
-    const project = opts.pick ? undefined : await readProject(cwd);
+    const project = opts.pick ? undefined : await readProject(cwd, harness);
     if (project && agents[project.agent])
         return agents[project.agent];
     if (!config.token || !config.consoleUrl) {
@@ -351,16 +365,19 @@ async function resolveAgent(config, opts = {}) {
     }
     if (!chosen) {
         const root = await projectRoot(cwd);
+        // 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(`Which Agent does this folder run as?`));
-        say(dim(`${root}  ·  flock ${listed.flock.name}`));
-        const options = listed.agents;
+        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.
+        const options = listed.agents.filter((a) => harness === "any" ? (a.harness ?? "any") === "any" : (a.harness ?? "any") === harness || (a.harness ?? "any") === "any");
         say(rows([
             ...options.map((a, i) => [
                 `${bold(String(i + 1))}  ${a.name}`,
-                `${a.state === "open" ? green("open") : yellow(a.state)}  ${a.kind === "subscription" ? yellow("subscription") : dim("api")}  ${dim(`$${(Number(a.capCents) / 100).toFixed(2)} cap`)}${agents[a.slug] ? dim("  keyed here") : a.hasKey ? dim("  keyed elsewhere") : ""}`,
+                `${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") {
@@ -370,7 +387,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" };
+            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);
@@ -384,8 +401,8 @@ async function resolveAgent(config, opts = {}) {
     let issued;
     try {
         if (created) {
-            issued = await createAgent(config.consoleUrl, config.token, { name: created.name, kind: created.kind });
-            ok(`Created ${created.kind === "subscription" ? "subscription" : "API-key"} Agent ${bold(issued.agent.name)} with a $50.00 cap. Change it in the console.`);
+            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) {
             if (chosen.hasKey && !agents[chosen.slug]) {
@@ -395,6 +412,11 @@ async function resolveAgent(config, opts = {}) {
                     return undefined;
             }
             issued = await issueAgentKey(config.consoleUrl, config.token, chosen.id);
+            // An untied Agent chosen for a harness is tied to it from now on, so the proxies enforce it.
+            if (harness !== "any" && (chosen.harness ?? "any") === "any") {
+                await setAgentHarness(config.consoleUrl, config.token, chosen.slug, harness);
+                say(dim(`${chosen.name} is now a ${harness} Agent.`));
+            }
         }
         else {
             return undefined;
@@ -415,8 +437,8 @@ async function resolveAgent(config, opts = {}) {
     config.agents = next.agents ?? {};
     if (next.unlock)
         config.unlock = next.unlock;
-    const file = await writeProject(await projectRoot(cwd), { agent: issued.agent.slug });
-    ok(`This folder runs as ${bold(issued.agent.name)} ${dim(`(${file})`)}`);
+    const file = await assignProjectAgent(await projectRoot(cwd), harness, issued.agent.slug);
+    ok(`This folder runs ${harness === "any" ? "" : `${harness} `}as ${bold(issued.agent.name)} ${dim(`(${file})`)}`);
     return login;
 }
 /** `tab version`: this CLI, and the proxy it would run (packaged, downloaded, or neither). */
@@ -551,14 +573,19 @@ 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;
     // Hosted whoami below proves readiness and current Agent kind in one round trip.
     if (config.mode === "self-hosted" && !(await ensureProxy(config)))
         return 1;
-    const agent = await resolveAgent(config);
+    const agent = await resolveAgent(config, { harness: harnessOf(name) });
     if (!agent)
         return 1;
     // The Agent's kind decides: a subscription Agent's harness brings its own
@@ -627,8 +654,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") {
@@ -646,11 +682,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) {
@@ -673,7 +713,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
@@ -871,14 +911,39 @@ function pathHint() {
     say(`  ${bold(pathLine())}`);
     return 0;
 }
-/** `tab use`: pick or change the Agent for this folder. */
-async function use() {
+/**
+ * `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();
     if (!config)
         return 2;
     if (!(await ensureProxy(config)))
         return 1;
-    const agent = await resolveAgent(config, { pick: true });
+    const word = args[0];
+    if (word && harnessOf(word) === "any") {
+        fail(`tab use [claude|codex|grok|kimi]: which harness to pick an Agent for; bare for the folder's default.`);
+        return 2;
+    }
+    const agent = await resolveAgent(config, { pick: true, harness: word ? harnessOf(word) : "any" });
     return agent ? 0 : 1;
 }
 /**
@@ -1065,7 +1130,7 @@ async function main(argv) {
             ok("Forgot the session and keys on this machine.");
             return 0;
         case "use":
-            return use();
+            return use(rest);
         case "alias":
             return alias(rest);
         case "unalias":
@@ -1098,6 +1163,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/console-api.js

@@ -32,3 +32,7 @@ export async function createAgent(consoleUrl, token, input, fetchImpl = fetch) {
 export async function issueAgentKey(consoleUrl, token, agentId, fetchImpl = fetch) {
     return call(consoleUrl, token, `/api/cli/agents/${encodeURIComponent(agentId)}/key`, { method: "POST" }, fetchImpl);
 }
+/** Tie an untied Agent to a harness (or change it): `tab agent harness <agent> codex`. */
+export async function setAgentHarness(consoleUrl, token, slug, harness, fetchImpl = fetch) {
+    return call(consoleUrl, token, `/api/cli/tabs/${encodeURIComponent(slug)}`, { method: "PATCH", body: JSON.stringify({ harness }) }, fetchImpl);
+}

package/dist/manage.js

@@ -61,6 +61,10 @@ export function parseFlags(argv) {
     return flags;
 }
 const kindOf = (t) => (t.kind === "subscription" ? yellow("subscription") : "api");
+const harnessOf = (t) => (t.harness && t.harness !== "any" ? t.harness : dim("any"));
+// A subscription never touches its cap: nothing to show but the kill switch.
+const capOf = (t) => (t.kind === "subscription" ? dim("-") : money(t.capCents));
+const usedOf = (t) => (t.kind === "subscription" ? dim("-") : pct(t.spentCents, t.capCents));
 async function tabsOf(call) {
     return (await call("GET", "/api/cli/tabs")).tabs;
 }
@@ -94,7 +98,7 @@ export async function list(config, flags) {
     const tabs = await tabsOf(api(config));
     emit(flags.json, { tabs }, () => tabs.length === 0
         ? dim("No Agents yet. Run tab claude or tab codex in a project folder.")
-        : table(["agent", "kind", "state", "spent", "cap", "used", "window", "project"], tabs.map((t) => [t.name === t.slug ? t.slug : `${t.name} ${dim(t.slug)}`, kindOf(t), state(t.state), money(t.spentCents), money(t.capCents), pct(t.spentCents, t.capCents), t.window, t.projectName ?? dim("-")]), { right: [3, 4, 5] }));
+        : table(["agent", "harness", "kind", "state", "spent", "cap", "used", "window", "project"], tabs.map((t) => [t.name === t.slug ? t.slug : `${t.name} ${dim(t.slug)}`, harnessOf(t), kindOf(t), state(t.state), t.kind === "subscription" ? dim("-") : money(t.spentCents), capOf(t), usedOf(t), t.window, t.projectName ?? dim("-")]), { right: [3, 4, 5] }));
     return 0;
 }
 export async function setState(config, flags, next) {
@@ -156,7 +160,7 @@ export async function agent(config, flags) {
         if (!name)
             throw new ManageError('tab agent create <name> [--subscription|--api] [--cap 50]');
         const kind = flags.opts.subscription !== undefined ? "subscription" : "api";
-        const body = { name, kind };
+        const body = { name, kind, ...(flags.opts.harness ? { harness: flags.opts.harness.toLowerCase() } : {}) };
         if (flags.opts.cap)
             body.capDollars = flags.opts.cap.replace(/^\$/, "");
         const made = await call("POST", "/api/cli/agents", body);
@@ -169,6 +173,18 @@ export async function agent(config, flags) {
                 : "Its calls use the flock's provider key and are metered against the cap. tab use picks it for a folder."));
         return 0;
     }
+    if (verb === "harness") {
+        const [given, wanted] = rest;
+        const harness = (wanted ?? "").toLowerCase();
+        if (!given || !["claude", "codex", "grok", "kimi", "any"].includes(harness))
+            throw new ManageError("tab agent harness <agent> claude|codex|grok|kimi|any");
+        const slug = await resolveSlug(call, given);
+        const { tab } = await call("PATCH", `/api/cli/tabs/${encodeURIComponent(slug)}`, { harness });
+        emit(flags.json, { tab }, () => harness === "any"
+            ? `${bold(tab.name)} is tied to no harness: it is metered on the tab and cannot pass a login through.`
+            : `${bold(tab.name)} is a ${bold(harness)} Agent. A ${harness} login passes through it; any other harness is refused before the vendor.`);
+        return 0;
+    }
     if (verb === "kind" || verb === "type") {
         const [given, wanted] = rest;
         if (!given || !wanted)
@@ -178,7 +194,7 @@ export async function agent(config, flags) {
         emit(flags.json, { tab }, () => `${bold(tab.name)} is now ${tab.kind === "subscription" ? bold("a subscription Agent") + dim(": its harnesses use your own logins from the next run") : bold("an API-key Agent") + dim(": metered with the flock's key from the next run")}.`);
         return 0;
     }
-    throw new ManageError("tab agent create <name> [--subscription|--api] | tab agent kind <agent> api|subscription");
+    throw new ManageError("tab agent create <name> [--subscription|--api] [--harness claude|codex|grok|kimi] | tab agent kind <agent> api|subscription | tab agent harness <agent> claude|codex|grok|kimi|any");
 }
 /**
  * `tab accounts` (also `tab quota`): every account the flock's subscription
@@ -205,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;
 }
@@ -391,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);
@@ -417,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");
+});