arcroom 0.0.1-beta

package/dist/redact.js

@@ -0,0 +1,113 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+// Secret redaction: runs on every event before it is written to the local queue and again before it leaves the machine,
+// and on every request body sent to the API.
+// Two layers: this machine's own secret VALUES (sensitive environment variables, values in a project's .env files),
+// removed wherever they appear whatever their shape; then patterns for common key formats and key=value secrets.
+// ponytail: patterns don't catch every secret shape. Add them as we meet them; a generic high-entropy rule would also
+// hit commit hashes and ids, so there is none.
+const R = '[REDACTED]';
+// --- exact values -------------------------------------------------------------------------------------------------
+// auth but not GIT_AUTHOR_NAME; *_SCOPES lists permissions, not a secret
+const SECRET_NAME = /^(?!.*_SCOPES?$).*(?:key|token|secret|passw(?:or)?d|pass\b|_pass|pwd|credential|auth(?!or)|dsn|private|cookie)/i;
+// ids are not secrets, and events carry them (a session id redacted would split a run)
+const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$|^[0-9a-f]{40}$/i;
+const known = new Set();
+let longestFirst = []; // so a value that contains another known value goes whole
+const read = new Set();
+/** Keeps a value to redact: under a secret-looking name, or (in .env files, `loose`) any long value mixing letters and digits. */
+function keep(name, raw, loose) {
+    const v = raw?.trim().replace(/^(['"])(.*)\1$/, '$2');
+    if (!v || v.length < 8 || /^(?:true|false|null|\d+)$/i.test(v) || ID.test(v) || known.has(v))
+        return;
+    // a path or a URL without a login is config, not a secret (GIT_ASKPASS, KEYCHAIN_PATH, AUTH_URL)
+    if (/^(?:[.~/\\]|[a-z]:[\\/]|[a-z][\w+.-]*:\/\/[^@\s]*$)/i.test(v))
+        return;
+    const mixed = v.length >= 16 && /\d/.test(v) && /[a-z]/i.test(v);
+    if (!SECRET_NAME.test(name) && !(loose && mixed))
+        return;
+    known.add(v);
+    longestFirst = [...known].sort((a, b) => b.length - a.length);
+}
+/** This process's sensitive environment variables (the agent passes the user's shell environment to its hooks). */
+export function rememberEnv(env = process.env) {
+    for (const [k, v] of Object.entries(env))
+        keep(k, v, false);
+}
+rememberEnv();
+/** The values in a project's .env files (not .env.example and friends); each folder is read once per process. */
+export function rememberSecrets(dir) {
+    if (typeof dir !== 'string' || !dir || read.has(dir))
+        return;
+    read.add(dir);
+    try {
+        for (const f of readdirSync(dir)) {
+            if (!/^\.env(?:\.|$)/.test(f) || /\.(?:example|sample|template|dist)$/.test(f))
+                continue;
+            for (const line of readFileSync(join(dir, f), 'utf8').split(/\r?\n/)) {
+                const m = line.match(/^\s*(?:export\s+)?([\w.-]+)\s*=\s*(.*)$/);
+                if (m)
+                    keep(m[1], m[2].replace(/\s+#.*$/, ''), true);
+            }
+        }
+    }
+    catch {
+        // no folder or no access: patterns still apply
+    }
+}
+// --- patterns -----------------------------------------------------------------------------------------------------
+const TOKENS = [
+    // private keys, also when a cut-off preview lost the END line
+    /-----BEGIN [A-Z ]*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY(?: BLOCK)?-----|$)/g,
+    /\b(?:sk-ant-[\w-]{10,}|sk-[\w-]{20,}|ar[ksi]_[\w-]{20,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_\w{20,}|xox[abprs]-[\w-]{10,}|(?:AKIA|ASIA)[0-9A-Z]{16}|AIza[\w-]{35})/g,
+    /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{10,}|\bglpat-[\w-]{20,}|\bnpm_[A-Za-z0-9]{30,}|\bhf_[A-Za-z0-9]{30,}|\bya29\.[\w-]{20,}|\bSG\.[\w-]{16,}\.[\w-]{16,}/g,
+    /https:\/\/hooks\.slack\.com\/services\/[\w/]+/g,
+    // more provider formats (after gitleaks' rules): Shopify, Twilio, Mailgun, DigitalOcean, Linear, PyPI, Doppler, Postman, Databricks
+    /\bshp(?:at|ca|pa|ss)_[a-fA-F0-9]{32}\b|\bSK[0-9a-f]{32}\b|\bkey-[0-9a-f]{32}\b|\bdo[opr]_v1_[a-f0-9]{64}\b|\blin_api_[A-Za-z0-9]{40}\b/g,
+    /\bpypi-AgEIcHlwaS5vcmc[\w-]{50,}|\bdp\.(?:pt|st|sa|ct|scim|audit)\.[A-Za-z0-9]{40,}|\bPMAK-[a-f0-9]{24}-[a-f0-9]{34}\b|\bdapi[a-f0-9]{32}\b/g,
+    /\beyJ[\w-]{10,}\.[\w-]{10,}\.[\w-]{10,}/g, // JWTs, including Supabase keys
+];
+const URL_PASSWORD = /(\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@"']+:)[^\s@"']+(@)/gi;
+// NAME=value, "name": "value", also inside escaped JSON (\"password\": \"x\")
+const KEY_VALUE = /\b((?:[\w-]*(?:password|passwd|pwd|_pass|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|_key|credentials?|accountkey|signature))(?:\\?["'])?\s*[:=]\s*(?:\\?["'])?)(?:Bearer\s+)?[^\s"'\\,;&]{6,}/gi;
+const BEARER = /\b(Bearer\s+)[\w.~+/-]{10,}=*/g;
+const BASIC = /\b(Basic\s+)[A-Za-z0-9+/]{8,}=*/g;
+const COOKIE = /(\b(?:Set-)?Cookie:\s*)[^\n"'\\]+/gi;
+// secrets passed as command flags: mysql -pX, --password X, curl -u user:pass, X-Amz-Signature=…
+const FLAGS = [
+    /(\b(?:mysql|mysqldump|mariadb)\b[^\n]*?\s-p)(?!\s)[^\s"']+/g,
+    /(--(?:password|pass|token|secret|api-key)[=\s]+)[^\s"']+/gi,
+    /(\s(?:-u|--user)\s+[^\s:"']+:)[^\s"']+/g,
+    /((?:X-Amz-Signature|X-Amz-Credential|sig)=)[^&\s"']+/g,
+];
+const SENSITIVE_KEY = /(?:^|[_-])(?:password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|authorization|cookie|credentials?)$/i;
+/** Files whose contents are secrets: their reads, writes and command output are not kept at all. */
+const SENSITIVE_FILE = /(?:^|[\\/\s"'=])(?:\.env(?:\.[\w.-]+)?|[^\\/\s"']*\.(?:pem|key|p12|pfx|keystore|jks)|id_(?:rsa|dsa|ecdsa|ed25519)|\.npmrc|\.netrc|\.pgpass|credentials(?:\.json)?|secrets?\.(?:json|ya?ml|toml))(?:$|[\s"'|;&)])/i;
+export const sensitiveFile = (text) => typeof text === 'string' && SENSITIVE_FILE.test(text) && !/\.env\.example\b/i.test(text);
+export function redactText(text) {
+    let out = text;
+    for (const v of longestFirst)
+        if (out.includes(v))
+            out = out.split(v).join(R);
+    for (const re of TOKENS)
+        out = out.replace(re, R);
+    for (const re of FLAGS)
+        out = out.replace(re, `$1${R}`);
+    return out
+        .replace(URL_PASSWORD, `$1${R}$2`)
+        .replace(KEY_VALUE, `$1${R}`)
+        .replace(BEARER, `$1${R}`)
+        .replace(BASIC, `$1${R}`)
+        .replace(COOKIE, `$1${R}`);
+}
+/** Redacts every string in a JSON-like value; a string under a sensitive key (or in a list under one) is dropped whole. */
+export function redact(value, key = '') {
+    if (typeof value === 'string')
+        return (SENSITIVE_KEY.test(key) ? R : redactText(value));
+    if (Array.isArray(value))
+        return value.map((v) => redact(v, key));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redact(v, k)]));
+    }
+    return value;
+}

package/dist/route.js

@@ -0,0 +1,26 @@
+// Model router: which Claude model a (sub)task should run on.
+// A replay uses the cheapest model that already passed with these steps; a new task is routed by the kind of work.
+// ponytail: verb-based tiers; learn from outcomes (cost + done-check results per model) once enough runs exist.
+const TIERS = [
+    [/^(list|find|look ?up|fetch|read|summari[sz]e|count|check|search|scan|extract|classify|translate|format|compare)\b/, 'haiku', 'lookup or summary'],
+    [/^(write|implement|fix|patch|refactor|add|update|create|test|migrate|convert|rename|remove)\b/, 'sonnet', 'writing or changing code'],
+    [/^(plan|design|architect|decide|review|debug|investigate|split|evaluate|choose)\b/, 'opus', 'planning or judgment'],
+];
+const alias = (model) => model?.includes('haiku') ? 'haiku' : model?.includes('sonnet') ? 'sonnet' : model?.includes('opus') ? 'opus' : undefined;
+export function routeFor(intent, provenModel) {
+    const proven = alias(provenModel);
+    if (proven)
+        return { model: proven, why: 'cheapest model that did these steps before' };
+    const verb = intent.trim().toLowerCase();
+    for (const [re, model, why] of TIERS)
+        if (re.test(verb))
+            return { model, why };
+    return undefined;
+}
+/** Adds `route` to lookups that still need work (replay or new). Reuse needs no model: the answer is already there. */
+export function withRoute(r, intent) {
+    if (r?.match !== 'replay' && r?.match !== 'none')
+        return r;
+    const route = routeFor(r.intent ?? intent, r.procedure?.model);
+    return route ? { ...r, route } : r;
+}

package/dist/session.js

@@ -0,0 +1,43 @@
+import { git } from './git.js';
+import { api, loadConfig } from './home.js';
+/** Project id shared by everyone on the repo: its git remote without protocol/credentials/.git, else the folder path. */
+export function projectOf(cwd) {
+    const remote = git(['config', '--get', 'remote.origin.url'], { cwd }).stdout?.trim();
+    if (!remote)
+        return cwd.replaceAll('\\', '/').toLowerCase();
+    return remote
+        .replace(/^[a-z+]+:\/\/(?:[^@/]+@)?/i, '') // https://user:token@host/... -> host/...
+        .replace(/^[^@]+@([^:]+):/, '$1/') // git@host:owner/repo -> host/owner/repo
+        .replace(/\.git$/, '')
+        .toLowerCase();
+}
+const ago = (from, now) => {
+    const min = Math.max(0, Math.round((now.getTime() - Date.parse(from)) / 60_000));
+    return min < 60 ? `${min} min ago` : min < 48 * 60 ? `${Math.round(min / 60)} h ago` : `${Math.round(min / 1440)} days ago`;
+};
+/** The note a new session starts with: what the last run in this project asked, did, and left open. */
+export function lastRunContext(run, now = new Date()) {
+    const r = run.report ?? {};
+    const edited = (r.files ?? []).filter((f) => f.edited).map((f) => f.path.split(/[\\/]/).pop());
+    const memory = r.memory ?? {};
+    const lines = [
+        `ArcRoom: the last session in this project (${ago(run.started_at, now)}, on ${run.machine ?? 'another machine'}) ` +
+            `ended ${run.status === 'partial' ? 'PARTIAL: its done-checks were still failing' : run.status}.`,
+        `Asked: "${String(r.first_prompt ?? run.prompt ?? '').slice(0, 200)}"`,
+        edited.length ? `Edited: ${edited.slice(0, 10).join(', ')}${edited.length > 10 ? ` (+${edited.length - 10} more)` : ''}` : '',
+        `${r.tool_calls ?? 0} tool calls` +
+            (r.blocked ? `, ${r.blocked} blocked by the loop guard` : '') +
+            (memory.find ? `, memory: ${memory.find} lookups, ${memory.complete ?? 0} stored` : ''),
+        'Use this to pick up where it left off if the user continues that work; ignore it otherwise.',
+    ];
+    return lines.filter(Boolean).join('\n');
+}
+/** Fetches the last run of this project (skipping the current session); undefined when there is none or the API is slow. */
+export async function lastRunNote(session, project) {
+    const cfg = loadConfig();
+    if (!cfg.apiKey)
+        return undefined;
+    const qs = new URLSearchParams({ project, exclude: session });
+    const run = await api(cfg, `/v1/runs/last?${qs}`, undefined, 1500); // never hold up session start for long
+    return run ? lastRunContext(run) : undefined;
+}

package/dist/signs.js

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { sessionFile } from './loop.js';
+// What the user sees of ArcRoom: one short line per action (hook systemMessage) and a live status line.
+// Plain name, no glyph: hooks and the status line are text only, and a text-drawn logo did not read as the logo.
+export const MARK = 'ArcRoom';
+const EMPTY = { reused: 0, replayed: 0, saved: 0, blocked: 0, evicted: 0, tokens_saved: 0 };
+const COUNTS = ['reused', 'replayed', 'saved', 'blocked', 'evicted'];
+/** 48213 -> "48.2k" */
+export const compact = (n) => (n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${(n / 1e3).toFixed(1)}k` : String(n));
+const short = (s, n = 60) => {
+    const t = String(s ?? '').replace(/\s+/g, ' ').trim();
+    return t.length > n ? `${t.slice(0, n - 1)}…` : t;
+};
+/** The JSON an ArcRoom MCP tool returned, from Claude Code's tool_response (content blocks or text); an error string otherwise. */
+export function toolResult(response) {
+    const texts = [];
+    const walk = (v) => {
+        if (typeof v === 'string')
+            texts.push(v);
+        else if (Array.isArray(v))
+            v.forEach(walk);
+        else if (v && typeof v === 'object')
+            typeof v.text === 'string' ? texts.push(v.text) : walk(v.content);
+    };
+    walk(response);
+    for (const t of texts) {
+        try {
+            return JSON.parse(t);
+        }
+        catch {
+            if (t.startsWith('ArcRoom error'))
+                return { error: t.replace(/^ArcRoom error:\s*/, '') };
+        }
+    }
+    return undefined;
+}
+/** The line to show after an ArcRoom tool call, and which counter it bumps. */
+export function signFor(tool, input, r) {
+    if (!r)
+        return undefined;
+    if (r.error)
+        return { message: `${MARK} · ${short(r.error, 90)}` };
+    const intent = short(r.intent ?? input?.intent);
+    switch (tool) {
+        case 'find_task': {
+            const changed = r.evicted_stale?.length ? `file changed (${r.evicted_stale.join(', ')}), old answer dropped · ` : '';
+            if (r.match === 'reuse')
+                return { message: `${MARK} · ${changed}reused a team answer${r.version?.verified ? ' (verified)' : ''}: ${intent}`, stat: 'reused' };
+            if (r.match === 'replay')
+                return { message: `${MARK} · ${changed}replaying stored steps: ${intent}`, stat: 'replayed' };
+            if (r.match === 'in_flight')
+                return { message: `${MARK} · a teammate is on it (${r.claimed_by ?? 'another session'}): ${intent}` };
+            if (r.broken_procedure)
+                return { message: `${MARK} · ${changed}stored steps broke last time, re-planning: ${intent}` };
+            if (r.candidates?.length)
+                return { message: `${MARK} · ${changed}no exact match, ${r.candidates.length} similar to check` };
+            return { message: `${MARK} · ${changed}new task, nothing stored yet: ${intent}` };
+        }
+        case 'split_task': {
+            const c = r.counts ?? {};
+            const done = [c.reuse && `${c.reuse} already done`, c.replay && `${c.replay} to replay`, c.in_flight && `${c.in_flight} in progress elsewhere`, c.none && `${c.none} new`];
+            return { message: `${MARK} · split into ${r.parts?.length ?? 0} parts: ${done.filter(Boolean).join(', ')}` };
+        }
+        case 'claim_task':
+            return { message: r.claimed ? `${MARK} · claimed: ${intent}` : `${MARK} · already taken by ${r.claimed_by ?? 'someone else'}` };
+        case 'complete_task':
+            return { message: `${MARK} · saved to team memory (v${r.version})`, stat: 'saved' };
+        case 'evict_task':
+            return { message: `${MARK} · threw away ${r.evicted} answer(s)${r.cascaded ? ` + ${r.cascaded} built on them` : ''}`, stat: 'evicted' };
+        case 'fail_task':
+            return { message: `${MARK} · marked the stored steps broken (v${r.procedure_version})` };
+        case 'rollback_task':
+            return { message: `${MARK} · back to stored steps v${r.procedure_version}` };
+        case 'pin_task':
+            return { message: `${MARK} · pinned v${r.version} for ${r.for}` };
+        case 'unpin_task':
+            return { message: `${MARK} · ${r.unpinned ? 'unpinned' : 'nothing was pinned'}` };
+    }
+    return undefined;
+}
+/** The status line: ArcRoom is live, the tokens this session used and saved, then what it did. */
+export function statusText(s, used = 0) {
+    const tokens = [used && `${compact(used)} tokens used`, s.tokens_saved && `${compact(s.tokens_saved)} saved`].filter(Boolean);
+    const parts = COUNTS.filter((k) => s[k]).map((k) => `${s[k]} ${k}`);
+    return [`${MARK} · live`, ...tokens, ...parts].join(' · ');
+}
+const statsFile = (session) => sessionFile(session, '.signs');
+export function readStats(session) {
+    const file = statsFile(session);
+    return existsSync(file) ? { ...EMPTY, ...JSON.parse(readFileSync(file, 'utf8')) } : { ...EMPTY };
+}
+export function bump(session, stat, by = 1) {
+    const s = readStats(session);
+    s[stat] += by;
+    writeFileSync(statsFile(session), JSON.stringify(s));
+}

package/dist/tree.js

@@ -0,0 +1,148 @@
+import { git as runGit } from './git.js';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { branchKey, hashKey, nodeKey, repoKey } from './blind.js';
+import { blobHash } from './fresh.js';
+import { api, ARCROOM_HOME } from './home.js';
+const MAX_NODES = 20_000; // ponytail: past this only folders are sent; send files per folder on demand if big repos need them
+const git = (root, args) => {
+    const r = runGit(args, { cwd: root, timeout: 5000, maxBuffer: 64 * 1024 * 1024 });
+    return r.status === 0 ? r.stdout : undefined;
+};
+const parentOf = (p) => (p === '.' ? undefined : p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '.');
+/** Parses `git ls-tree -r -t --full-tree HEAD` output: "<mode> <type> <hash>\t<path>". */
+export function parseLsTree(out, rootHash) {
+    const tree = new Map();
+    if (rootHash)
+        tree.set('.', { kind: 'dir', hash: rootHash });
+    for (const line of out.split('\n')) {
+        const m = /^\d+ (tree|blob) ([0-9a-f]{40,64})\t(.+)$/.exec(line);
+        if (m)
+            tree.set(m[3], { kind: m[1] === 'tree' ? 'dir' : 'file', hash: m[2] });
+    }
+    return tree;
+}
+/** Applies uncommitted changes: edited files get their working hash, deleted ones go, their folders get a trailing *. */
+export function withDirty(tree, changes) {
+    const out = new Map(tree);
+    for (const c of changes) {
+        if (c.hash)
+            out.set(c.path, { kind: 'file', hash: c.hash });
+        else
+            out.delete(c.path);
+        for (let d = parentOf(c.path); d; d = parentOf(d)) {
+            const cur = out.get(d) ?? { kind: 'dir', hash: 'new' };
+            if (!cur.hash.endsWith('*'))
+                out.set(d, { kind: 'dir', hash: `${cur.hash}*` });
+            if (d === '.')
+                break;
+        }
+    }
+    return out;
+}
+/** This checkout's tree: HEAD from git, plus what is edited but not committed. */
+export function readTree(root) {
+    const head = git(root, ['rev-parse', 'HEAD^{tree}'])?.trim();
+    const tree = head ? parseLsTree(git(root, ['ls-tree', '-r', '-t', '--full-tree', 'HEAD']) ?? '', head) : new Map([['.', { kind: 'dir', hash: 'empty' }]]);
+    const changes = (git(root, ['status', '--porcelain', '-uall']) ?? '')
+        .split('\n')
+        .filter(Boolean)
+        .map((l) => l.slice(3).split(' -> ').pop().replace(/^"|"$/g, ''))
+        .map((path) => {
+        const file = join(root, path);
+        return { path, hash: existsSync(file) ? safeBlob(file) : undefined };
+    });
+    return withDirty(tree, changes);
+}
+const safeBlob = (file) => {
+    try {
+        return blobHash(readFileSync(file));
+    }
+    catch {
+        return undefined;
+    }
+};
+const short = (refs) => [...new Set((refs ?? '').split('\n').map((r) => r.trim().replace(/^origin\//, '')).filter((r) => r && r !== 'HEAD' && r !== 'origin'))];
+/** The branch this checkout is on, the team's default branch, and which branches exist and are merged into it. */
+export function branches(root) {
+    const branch = git(root, ['rev-parse', '--abbrev-ref', 'HEAD'])?.trim() || 'main';
+    const remoteHead = git(root, ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'])?.trim().replace(/^origin\//, '');
+    const has = (b) => git(root, ['rev-parse', '--verify', '--quiet', b]) !== undefined;
+    const def = remoteHead || (has('main') ? 'main' : has('master') ? 'master' : branch);
+    const ahead = branch === def ? 0 : Number(git(root, ['rev-list', '--count', `${def}..HEAD`])?.trim() ?? 0) || 0;
+    const fmt = ['--format=%(refname:short)', 'refs/heads', 'refs/remotes'];
+    return { branch, def, ahead, all: short(git(root, ['for-each-ref', ...fmt])), merged: has(def) ? short(git(root, ['for-each-ref', '--merged', def, ...fmt])) : [] };
+}
+/** The paths a branch changed since it left the default branch (plus uncommitted ones), with every folder above. */
+export function branchPaths(root, def, tree) {
+    const base = git(root, ['merge-base', 'HEAD', def])?.trim();
+    const changed = base ? (git(root, ['diff', '--name-only', base, 'HEAD']) ?? '').split('\n').filter(Boolean) : [];
+    const out = new Set();
+    const add = (p) => {
+        for (let d = p; d && !out.has(d); d = parentOf(d))
+            out.add(d);
+    };
+    for (const p of changed)
+        if (tree.has(p))
+            add(p);
+    // uncommitted: their folders carry a *, and the files in those folders go along
+    for (const [p, e] of tree)
+        if (e.hash.endsWith('*') || (e.kind === 'file' && tree.get(parentOf(p))?.hash.endsWith('*')))
+            add(p);
+    return out;
+}
+/** What to send: on the default branch only what changed since the last sync (all of it the first time). */
+export function syncBody(s, tree, b, last, reset = false) {
+    const onDefault = b.branch === b.def;
+    const paths = onDefault ? [...tree.keys()] : [...branchPaths(s.root, b.def, tree)];
+    const keep = paths.length > MAX_NODES ? paths.filter((p) => tree.get(p)?.kind === 'dir') : paths;
+    const sent = {};
+    const nodes = [];
+    for (const p of keep) {
+        const e = tree.get(p);
+        if (!e)
+            continue;
+        const k = nodeKey(s, p);
+        const h = hashKey(s, e.hash);
+        sent[k] = h;
+        if (onDefault && last && !reset && last[k] === h)
+            continue;
+        const parent = parentOf(p);
+        nodes.push({ k, ...(parent ? { p: nodeKey(s, parent) } : {}), kind: e.kind, h });
+    }
+    const full = !onDefault || !last || reset;
+    const deleted = full ? [] : Object.keys(last).filter((k) => !(k in sent));
+    return {
+        sent,
+        body: {
+            repo: repoKey(s),
+            mode: s.mode,
+            ...(s.mode === 'blind' ? { fingerprint: s.keys.fp } : {}),
+            branch: branchKey(s, b.branch),
+            default_branch: branchKey(s, b.def),
+            ahead: b.ahead,
+            branches: b.all.map((x) => branchKey(s, x)),
+            merged: b.merged.map((x) => branchKey(s, x)),
+            full,
+            ...(reset ? { reset: true } : {}),
+            nodes,
+            deleted,
+        },
+    };
+}
+const cacheFile = (s, branch) => join(ARCROOM_HOME, 'tree', `${createHash('sha1').update(`${s.root}|${s.mode}|${s.fp ?? ''}|${branch}`).digest('hex').slice(0, 16)}.json`);
+/** Sends this checkout's tree to the Room. Off, or Blind without the key: nothing is sent. */
+export async function syncTree(cfg, s, reset = false) {
+    if (s.mode === 'off' || (s.mode === 'blind' && !s.keys))
+        return undefined;
+    const tree = readTree(s.root);
+    const b = branches(s.root);
+    const file = cacheFile(s, b.branch);
+    const last = existsSync(file) && !reset ? JSON.parse(readFileSync(file, 'utf8')) : undefined;
+    const { body, sent } = syncBody(s, tree, b, last, reset);
+    const r = await api(cfg, '/v1/code/sync', body, 30_000);
+    mkdirSync(join(ARCROOM_HOME, 'tree'), { recursive: true });
+    writeFileSync(file, JSON.stringify(sent));
+    return r;
+}

package/dist/usage.js

@@ -0,0 +1,93 @@
+import { closeSync, existsSync, openSync, readFileSync, readSync, statSync, writeFileSync } from 'node:fs';
+import { sessionFile } from './loop.js';
+const zero = () => ({ input: 0, output: 0, cache_read: 0, cache_write: 0 });
+export const tokensOf = (u) => u.input + u.output + u.cache_read + u.cache_write;
+const plus = (a, b) => ({
+    input: a.input + b.input,
+    output: a.output + b.output,
+    cache_read: a.cache_read + b.cache_read,
+    cache_write: a.cache_write + b.cache_write,
+    model: b.model ?? a.model,
+});
+const minus = (a, b) => ({
+    input: a.input - b.input,
+    output: a.output - b.output,
+    cache_read: a.cache_read - b.cache_read,
+    cache_write: a.cache_write - b.cache_write,
+    model: a.model,
+});
+/** Usage of the assistant messages in complete transcript lines, skipping message ids already counted. */
+export function sumUsage(text, seen) {
+    const usage = zero();
+    const consumed = text.lastIndexOf('\n') + 1; // a half-written last line waits for next time
+    const latest = new Map(); // ponytail: a message split across two reads keeps its first counts; fine since usage repeats per line
+    for (const line of text.slice(0, consumed).split('\n')) {
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const m = e?.type === 'assistant' ? e.message : undefined;
+        if (m?.usage && m.id && !seen.has(m.id))
+            latest.set(m.id, m);
+    }
+    for (const [id, m] of latest) {
+        seen.add(id);
+        usage.input += m.usage.input_tokens ?? 0;
+        usage.output += m.usage.output_tokens ?? 0;
+        usage.cache_read += m.usage.cache_read_input_tokens ?? 0;
+        usage.cache_write += m.usage.cache_creation_input_tokens ?? 0;
+        usage.model = m.model ?? usage.model;
+    }
+    return { usage, consumed };
+}
+const file = (session) => sessionFile(session, '.usage');
+/** Reads new transcript lines into the session's running total. */
+function advance(session, transcript) {
+    const f = file(session);
+    const st = existsSync(f) ? JSON.parse(readFileSync(f, 'utf8')) : { offset: 0, total: zero(), reported: zero(), ids: [], claims: {} };
+    if (transcript && existsSync(transcript) && statSync(transcript).size > st.offset) {
+        const fd = openSync(transcript, 'r');
+        const buf = Buffer.alloc(statSync(transcript).size - st.offset);
+        readSync(fd, buf, 0, buf.length, st.offset);
+        closeSync(fd);
+        const text = buf.toString('utf8');
+        const seen = new Set(st.ids);
+        const { usage, consumed } = sumUsage(text, seen);
+        st.offset += Buffer.byteLength(text.slice(0, consumed));
+        st.total = plus(st.total, usage);
+        st.ids = [...seen].slice(-500);
+    }
+    return st;
+}
+const save = (session, st) => writeFileSync(file(session), JSON.stringify(st));
+/** Everything this session has used so far (the status line). */
+export function sessionUsage(session, transcript) {
+    const st = advance(session, transcript);
+    save(session, st);
+    return st.total;
+}
+/** Turn end: the tokens used since the last report, or undefined when nothing new. */
+export function turnUsage(session, transcript) {
+    const st = advance(session, transcript);
+    const delta = minus(st.total, st.reported);
+    st.reported = st.total;
+    save(session, st);
+    return tokensOf(delta) > 0 ? delta : undefined;
+}
+/** claim_task: remember where the token count stood. */
+export function markClaim(session, transcript, memoId) {
+    const st = advance(session, transcript);
+    st.claims[memoId] = tokensOf(st.total);
+    save(session, st);
+}
+/** complete_task: tokens spent on this memo since its claim (since session start if it was never claimed here). */
+export function costSinceClaim(session, transcript, memoId) {
+    const st = advance(session, transcript);
+    const tokens = tokensOf(st.total) - (st.claims[memoId] ?? 0);
+    delete st.claims[memoId];
+    save(session, st);
+    return { tokens: Math.max(tokens, 0), model: st.total.model };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "arcroom",
+  "version": "0.0.1-beta",
+  "description": "Shared team memory and run control for coding agents: Claude Code, Codex, Cursor, OpenCode",
+  "license": "Apache-2.0",
+  "author": "ArcRoom AI",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "arcroom": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "homepage": "https://www.arcroomai.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArcROOM-AI/arcroom.git"
+  },
+  "bugs": "https://github.com/ArcROOM-AI/arcroom/issues",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "cursor",
+    "opencode",
+    "mcp",
+    "agent-memory"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "node test.mjs",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.6.0"
+  }
+}