@decibelsystems/tools 2.2.0-beta.0 → 3.1.0

package/dist/pty/tmux.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmux.d.ts","sourceRoot":"","sources":["../../src/pty/tmux.ts"],"names":[],"mappings":"AAmBA,qFAAqF;AACrF,eAAO,MAAM,cAAc,SAAS,CAAC;AAOrC,wBAAgB,WAAW,IAAI,MAAM,CAMpC;AAED,gDAAgD;AAChD,wBAAgB,cAAc,CAAC,CAAC,GAAE,MAAM,GAAG,IAAW,GAAG,IAAI,CAE5D;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAE1C,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAE9C,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAcvD;AAED,6EAA6E;AAC7E;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,QAGmF,CAAC;AAE7G,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAElD;AAwBD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGrD;AAED,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,IAAI,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,EAAE,CAE/E;AAED,wBAAgB,QAAQ,CAAC,IAAI,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAetF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,EAAE,CAIlF;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAM9F;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,YAAY,CAAC;AAEnC;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,SAAM,GAAG,MAAM,GAAG,SAAS,CAI/E;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,IAAI,EAAE,OAAO,CAAC;CACf;AAgBD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAKlD;AAgBD,yGAAyG;AACzG,wBAAsB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAG7E;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CAgB3D;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAY/D;AAED,oEAAoE;AACpE,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAEhF"}

package/dist/pty/tmux.js

@@ -0,0 +1,271 @@
+// ============================================================================
+// tmux — the substrate hosted sessions live in (ADR-0012 / decibel-hq EPIC-0015)
+// ============================================================================
+// Every call is execFile with an argv array, never a shell string, so a session
+// name or label can never become a command. Session targets use tmux's `=name`
+// exact-match form: a bare `-t name` is a PREFIX match, so `-t dcb-a` would
+// happily hit `dcb-abc`.
+//
+// Session metadata (project, branch, issue label) is stored ON the tmux session
+// as user options (@dcb_*), not in a daemon-side file. It then lives exactly as
+// long as the session does and survives a daemon restart with nothing to
+// reconcile.
+// ============================================================================
+import { execFile } from 'child_process';
+import { existsSync } from 'fs';
+import { log } from '../config.js';
+import { SessionError } from './errors.js';
+/** Prefix for sessions the daemon spawned. Anything else is adopted, never owned. */
+export const SPAWNED_PREFIX = 'dcb-';
+/**
+ * launchd does not give the daemon a login PATH, so `tmux` alone may not
+ * resolve. Probe the usual install locations first.
+ */
+let tmuxPath = null;
+export function resolveTmux() {
+    if (tmuxPath)
+        return tmuxPath;
+    for (const p of ['/opt/homebrew/bin/tmux', '/usr/local/bin/tmux', '/usr/bin/tmux']) {
+        if (existsSync(p))
+            return (tmuxPath = p);
+    }
+    return (tmuxPath = 'tmux');
+}
+/** Test seam: forget the cached binary path. */
+export function _resetTmuxPath(p = null) {
+    tmuxPath = p;
+}
+export const OWNED_SOCKET_DEFAULT = 'decibel';
+export function socketArgs(server) {
+    // -f /dev/null: the owned server must not read ~/.tmux.conf. HQ's pane needs
+    // predictable behaviour — no custom prefix, and no `mouse on`, whose mouse
+    // capture breaks xterm.js selection. (-f only matters when the server starts;
+    // passing it on every call is harmless.)
+    //
+    // -u on every call: launchd gives the daemon no locale, and a tmux client
+    // without one is treated as non-UTF-8 — every non-ASCII glyph Claude draws
+    // (❯, ⏵⏵, the logo) arrived in HQ as '_'. cleanEnv also supplies a UTF-8
+    // LANG/LC_CTYPE, so a server started by the daemon is UTF-8 too. Found by
+    // decibel-hq on its first live pass.
+    if (server === 'owned')
+        return ['-u', '-L', process.env.DECIBEL_TMUX_SOCKET || OWNED_SOCKET_DEFAULT, '-f', '/dev/null'];
+    const user = process.env.DECIBEL_TMUX_USER_SOCKET;
+    return user ? ['-u', '-L', user] : ['-u'];
+}
+/** Which server a session key lives on: the prefix is the ownership mark. */
+/**
+ * Terminal title for clients of the owned server (set-titles): the repo, plus
+ * the issue label, or else a branch other than main/master. Built from the
+ * @dcb_* options the daemon sets at spawn, which cleanLabel has already
+ * stripped of control characters. tmux sends it as OSC 2 to every attached
+ * client, so a Ghostty tab is titled without any title text in its command
+ * (ISS-0210).
+ */
+export const TITLE_FORMAT = '#{?@dcb_project,#{@dcb_project},#{session_name}}' +
+    '#{?@dcb_issue, · #{@dcb_issue},' +
+    '#{?#{&&:#{@dcb_branch},#{&&:#{!=:#{@dcb_branch},main},#{!=:#{@dcb_branch},master}}}, · #{@dcb_branch},}}';
+export function serverFor(name) {
+    return name.startsWith(SPAWNED_PREFIX) ? 'owned' : 'user';
+}
+/**
+ * The environment every tmux client and spawned claude gets. TMUX is removed so
+ * a daemon started inside tmux does not make nested-client calls. CLAUDECODE,
+ * CLAUDE_CODE_* and CLAUDE_PID are removed because claude refuses to start when
+ * it sees them (the nested-session guard): a daemon ever launched from inside a
+ * Claude Code session would otherwise start an owned server whose every session
+ * dies instantly. Found by decibel-hq against its mock of this contract.
+ */
+/**
+ * The daemon's own environment, which a spawned agent must not inherit
+ * (ISS-0225). launchd starts the daemon with its env file loaded and
+ * NODE_ENV=production, and before this every hosted Claude session held them
+ * all, including SUPABASE_SERVICE_KEY, which bypasses RLS on Core. Only the
+ * daemon writes with service_role; an agent and anything it runs must not.
+ * NODE_ENV=production also makes npm/pnpm skip and prune devDependencies.
+ *
+ * Matched by name: credentials by suffix, plus the daemon-only config.
+ * ANTHROPIC_* is kept, so Claude Code's own auth is untouched.
+ */
+const DAEMON_ONLY = new Set(['NODE_ENV', 'SUPABASE_URL', 'SUPABASE_ANON_KEY', 'SUPABASE_SERVICE_KEY', 'SUPABASE_SERVICE_ROLE_KEY', 'DECIBEL_ORG_ID']);
+const CREDENTIAL_RE = /(_KEY|_TOKEN|_SECRET|PASSWORD|_DATABASE_URL|_DSN)$/i;
+export function isDaemonOnlyVar(name) {
+    if (name.startsWith('ANTHROPIC_'))
+        return false;
+    return DAEMON_ONLY.has(name) || CREDENTIAL_RE.test(name);
+}
+/** Names in `base` that cleanEnv drops for being the daemon's. Names only, never values. */
+export function daemonOnlyNames(base = process.env) {
+    return Object.keys(base).filter((k) => base[k] !== undefined && isDaemonOnlyVar(k)).sort();
+}
+export function cleanEnv(base = process.env) {
+    const env = {};
+    for (const [k, v] of Object.entries(base)) {
+        if (v === undefined)
+            continue;
+        if (k === 'TMUX' || k === 'TMUX_PANE' || k === 'CLAUDECODE' || k === 'CLAUDE_PID' || k.startsWith('CLAUDE_CODE_'))
+            continue;
+        if (isDaemonOnlyVar(k))
+            continue;
+        env[k] = v;
+    }
+    // No locale at all (launchd) means tmux and claude both fall back to ASCII.
+    // Supply UTF-8 only when nothing is set, so a user's own choice stands.
+    if (!env.LANG && !env.LC_ALL && !env.LC_CTYPE) {
+        env.LANG = 'en_US.UTF-8';
+        env.LC_CTYPE = 'en_US.UTF-8';
+    }
+    return env;
+}
+/**
+ * tmux keeps the environment its server started with as the GLOBAL
+ * environment and copies it into every new session. A server started before
+ * ISS-0225 already holds the daemon's variables, so cleaning the client env
+ * is not enough: unset them there too. Applied before every spawn and at
+ * daemon start.
+ */
+export function unsetDaemonEnvArgs(base = process.env) {
+    const out = [];
+    for (const name of daemonOnlyNames(base))
+        out.push(';', 'set-environment', '-g', '-u', name);
+    return out.slice(1);
+}
+export function tmux(server, args, timeoutMs = 5000) {
+    return new Promise((resolve) => {
+        execFile(resolveTmux(), [...socketArgs(server), ...args], { timeout: timeoutMs, env: cleanEnv() }, (err, stdout, stderr) => {
+            resolve({ ok: !err, stdout: String(stdout), stderr: String(stderr) || (err ? err.message : '') });
+        });
+    });
+}
+/**
+ * Exact-match session target, for commands that take a SESSION target:
+ * has-session, kill-session, attach-session.
+ */
+export function sessionTarget(name) {
+    return `=${name}`;
+}
+/**
+ * Exact-match target for everything that parses -t as a pane or window:
+ * set-option, show-options, send-keys, respawn-pane. tmux 3.5a rejects a bare
+ * `=name` there with "no such session"; the trailing colon is required
+ * (verified 2026-09-25, and hit independently by decibel-hq's mock).
+ */
+export function paneTarget(name) {
+    return `=${name}:`;
+}
+/**
+ * Field separator for -F output. PRINTABLE on purpose: with no LANG/LC_* in
+ * the environment — which is exactly the launchd daemon's environment — tmux
+ * rewrites a TAB in format output as '_', every field collapsed into the
+ * session name, and no spawned session ever matched its project. The tests
+ * passed because the shell running them had a locale. Pinned by a test that
+ * lists with the locale removed.
+ */
+export const FIELD_SEP = '|:dcb:|';
+/**
+ * Newlines and the field separator would corrupt list output, and a label has
+ * no business being long. Applied to every value written into a tmux option.
+ */
+export function cleanLabel(v, max = 200) {
+    if (v === undefined || v === null)
+        return undefined;
+    const cleaned = String(v).split(FIELD_SEP).join(' ').replace(/[\t\r\n]/g, ' ').trim().slice(0, max);
+    return cleaned || undefined;
+}
+const LIST_FORMAT = [
+    '#{session_name}',
+    '#{@dcb_project}',
+    '#{@dcb_branch}',
+    '#{@dcb_issue}',
+    '#{@dcb_uuid}',
+    '#{session_created}',
+    '#{pane_current_path}',
+    '#{pane_dead}',
+    // #{pane_current_path} is empty once the pane is dead, so spawned sessions
+    // also record their cwd as an option (found by decibel-hq's mock).
+    '#{@dcb_cwd}',
+].join(FIELD_SEP);
+/**
+ * "No server" is a normal answer; "could not ask" is not. A missing socket
+ * means no server, so no sessions. Any other failure — a server that exists
+ * but did not answer — must NOT read as an empty list, because HQ would render
+ * a live session as gone. It gets one retry and then throws. (A spawned session
+ * once went unlisted for minutes while its server was plainly up; the old check
+ * swallowed every "error connecting to" as "no server". Cause unverified.)
+ */
+export function isNoServer(stderr) {
+    // A stale socket file (the server died without removing it) refuses the
+    // connection; that is also "no server".
+    return /no server running/.test(stderr) ||
+        /error connecting to .*\((No such file or directory|Connection refused)\)/.test(stderr);
+}
+async function tmuxRead(server, args) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const r = await tmux(server, args);
+        if (r.ok)
+            return r;
+        if (isNoServer(r.stderr))
+            return null;
+        log(`Sessions: tmux ${args[0]} (${server}) failed${attempt ? '' : ', retrying'}: ${r.stderr.trim() || 'no stderr'}`);
+        if (!attempt)
+            await new Promise((res) => setTimeout(res, 250));
+        else {
+            throw new SessionError(503, 'TMUX_UNAVAILABLE', `The ${server} tmux server did not answer: ${r.stderr.trim() || 'no stderr'}`);
+        }
+    }
+    return null;
+}
+/** Every session on one server. Empty when that server is not running; throws when it cannot be read. */
+export async function listSessions(server) {
+    const r = await tmuxRead(server, ['list-sessions', '-F', LIST_FORMAT]);
+    return r ? parseSessions(r.stdout) : [];
+}
+export function parseSessions(stdout) {
+    const out = [];
+    for (const line of stdout.split('\n')) {
+        if (!line.trim())
+            continue;
+        const [name, project, branch, issue, uuid, created, paneCwd, dead, dcbCwd] = line.split(FIELD_SEP);
+        const cwd = dcbCwd || paneCwd;
+        const s = { name, dead: dead === '1' };
+        if (uuid)
+            s.claude_session_id = uuid;
+        if (project)
+            s.project_id = project;
+        if (branch)
+            s.branch = branch;
+        if (issue)
+            s.issue_label = issue;
+        if (created && /^\d+$/.test(created))
+            s.created = new Date(Number(created) * 1000).toISOString();
+        if (cwd)
+            s.cwd = cwd;
+        out.push(s);
+    }
+    return out;
+}
+/**
+ * pane tty (without /dev/) → session name, across BOTH servers, for matching
+ * claude-peers ttys. A user-server session carrying the dcb- prefix is skipped:
+ * the prefix means "owned", and honouring it on the wrong server would route
+ * attach and kill to a session the daemon does not own.
+ */
+export async function paneTtyMap() {
+    const m = new Map();
+    for (const server of ['owned', 'user']) {
+        const r = await tmuxRead(server, ['list-panes', '-a', '-F', `#{pane_tty}${FIELD_SEP}#{session_name}`]);
+        if (!r)
+            continue;
+        for (const line of r.stdout.split('\n')) {
+            const [tty, name] = line.split(FIELD_SEP);
+            if (!tty || !name || serverFor(name) !== server)
+                continue;
+            m.set(tty.replace(/^\/dev\//, ''), name);
+        }
+    }
+    return m;
+}
+/** Find a session by key on the server its key says it lives on. */
+export async function findSession(name) {
+    return (await listSessions(serverFor(name))).find((s) => s.name === name);
+}
+//# sourceMappingURL=tmux.js.map

package/dist/pty/tmux.js.map

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

package/dist/roster.d.ts

@@ -0,0 +1,37 @@
+export interface ScopeFilter {
+    assignee?: unknown;
+    team?: unknown;
+}
+export interface ScopeTerm {
+    requested: string;
+    /** Every id a record may carry to match this filter. */
+    match: string[];
+}
+export interface ResolvedScope {
+    assignee?: ScopeTerm;
+    team?: ScopeTerm;
+    /** True when the roster answered and aliases were applied. */
+    expanded: boolean;
+    /** Present whenever the result may be short, and why. */
+    note?: string;
+}
+export interface RosterRow {
+    id: string;
+    kind: string;
+    canonical_id: string | null;
+    aliases: string[] | null;
+}
+export type RosterResolver = (ids: string[]) => Promise<RosterRow[]>;
+/** Test seam. */
+export declare function _setRosterResolver(fn: RosterResolver | null): void;
+/**
+ * Resolve a scope filter. Returns null when no filter was given, so an
+ * unscoped call keeps exactly its current behaviour.
+ */
+export declare function resolveScope(f: ScopeFilter): Promise<ResolvedScope | null>;
+/** Does a record fall inside the scope? Both terms must hold when both are set. */
+export declare function inScope(record: {
+    assignee?: string;
+    team?: string;
+}, scope: ResolvedScope): boolean;
+//# sourceMappingURL=roster.d.ts.map

package/dist/roster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roster.d.ts","sourceRoot":"","sources":["../src/roster.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;AAkBrE,iBAAiB;AACjB,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAGlE;AA+BD;;;GAGG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAoChF;AAED,mFAAmF;AACnF,wBAAgB,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAInG"}

package/dist/roster.js

@@ -0,0 +1,126 @@
+// ============================================================================
+// Roster resolution for scoped reads (EPIC-0040 slice 3)
+// ============================================================================
+// A filter such as assignee=user:<ben> has to match every id that means Ben:
+// the canonical user:<uuid> AND every human:<name> claimed to that account.
+// Records are never rewritten to upgrade a human: to a user:, so without this
+// expansion a filter by user:<uuid> misses every record written before the
+// claim (44 human:ben records in this repo alone) and returns a confidently
+// short list.
+//
+// HQ owns the mapping: hq.resolve_ids(p_org, p_ids) returns, per input id, its
+// canonical_id and aliases. The daemon turns one filter id into an IN-list:
+// {requested} ∪ {canonical_id} ∪ aliases.
+//
+// Offline degradation, agreed with decibel-hq: when the roster is unreachable,
+// match the literal id only and SAY SO in the result ("not expanded"). Never a
+// guess, never a quiet omission.
+// ============================================================================
+import { assertActor, assertTeam, IdentityError } from './identity.js';
+import { requireOrgId } from './orgId.js';
+import { getSupabaseServiceClient, isSupabaseConfigured } from './lib/supabase.js';
+const CACHE_MS = 5 * 60_000;
+const TIMEOUT_MS = 3_000;
+const cache = new Map();
+async function supabaseResolver(ids) {
+    if (!isSupabaseConfigured())
+        throw new Error('Supabase is not configured on this process');
+    const client = getSupabaseServiceClient();
+    const call = client.schema('hq').rpc('resolve_ids', { p_org: requireOrgId(), p_ids: ids });
+    const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error(`no answer in ${TIMEOUT_MS}ms`)), TIMEOUT_MS));
+    const { data, error } = (await Promise.race([call, timeout]));
+    if (error)
+        throw new Error(error.message);
+    if (!Array.isArray(data))
+        throw new Error('resolve_ids returned no rows');
+    return data;
+}
+let resolver = supabaseResolver;
+/** Test seam. */
+export function _setRosterResolver(fn) {
+    resolver = fn ?? supabaseResolver;
+    cache.clear();
+}
+/** Validate a filter's SHAPE. Membership is HQ's business, never checked here. */
+function parseFilter(f) {
+    const out = {};
+    try {
+        if (f.assignee !== undefined && f.assignee !== '') {
+            if (typeof f.assignee !== 'string')
+                throw new IdentityError('assignee must be a string');
+            assertActor(f.assignee);
+            out.assignee = f.assignee;
+        }
+        if (f.team !== undefined && f.team !== '') {
+            if (typeof f.team !== 'string')
+                throw new IdentityError('team must be a string');
+            assertTeam(f.team);
+            out.team = f.team;
+        }
+    }
+    catch (err) {
+        throw new Error(`Invalid scope filter: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return out;
+}
+function termFrom(requested, row) {
+    const ids = new Set([requested]);
+    if (row && row.kind !== 'unresolved') {
+        if (row.canonical_id)
+            ids.add(row.canonical_id);
+        for (const a of row.aliases ?? [])
+            ids.add(a);
+    }
+    return { requested, match: [...ids] };
+}
+/**
+ * Resolve a scope filter. Returns null when no filter was given, so an
+ * unscoped call keeps exactly its current behaviour.
+ */
+export async function resolveScope(f) {
+    const parsed = parseFilter(f);
+    const wanted = [parsed.assignee, parsed.team].filter((x) => !!x);
+    if (!wanted.length)
+        return null;
+    const now = Date.now();
+    const rows = new Map();
+    const missing = wanted.filter((id) => {
+        const hit = cache.get(id);
+        if (hit && now - hit.at < CACHE_MS) {
+            rows.set(id, hit.row);
+            return false;
+        }
+        return true;
+    });
+    let failure;
+    if (missing.length) {
+        try {
+            const answered = await resolver(missing);
+            for (const row of answered) {
+                rows.set(row.id, row);
+                cache.set(row.id, { row, at: now });
+            }
+        }
+        catch (err) {
+            failure = err instanceof Error ? err.message : String(err);
+        }
+    }
+    const scope = { expanded: !failure };
+    if (parsed.assignee)
+        scope.assignee = termFrom(parsed.assignee, rows.get(parsed.assignee));
+    if (parsed.team)
+        scope.team = termFrom(parsed.team, rows.get(parsed.team));
+    if (failure) {
+        scope.note = `Roster unreachable (${failure}): matched the literal id only; local identities were not expanded, so this list may be short.`;
+    }
+    return scope;
+}
+/** Does a record fall inside the scope? Both terms must hold when both are set. */
+export function inScope(record, scope) {
+    if (scope.assignee && !(record.assignee && scope.assignee.match.includes(record.assignee)))
+        return false;
+    if (scope.team && !(record.team && scope.team.match.includes(record.team)))
+        return false;
+    return true;
+}
+//# sourceMappingURL=roster.js.map

package/dist/roster.js.map

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

package/dist/runtime/circuitBreaker.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Per-facade circuit breaker.
+ *
+ * The failure this exists for: one facade's dependency wedges — Mother's
+ * Postgres stops accepting connections, Supabase hangs, a disk mount goes
+ * away — and every call into that facade sits on a socket until it times out.
+ * With six clients sharing one runtime that is enough to make the whole
+ * runtime feel dead, even though twenty other facades are fine. The breaker
+ * turns a slow, repeated failure into a fast, local one.
+ *
+ * WHAT COUNTS AS A FAULT is the whole design, because Decibel's tools rarely
+ * throw. `senken_trade_summary` catches its own Postgres error and returns
+ * `{isError: true}` (src/tools/senken.ts:117), so a breaker that only counted
+ * exceptions would never trip on the exact case it was built for. But counting
+ * every `isError` is worse: `create_issue` missing a title is an `isError`
+ * too, and five bad calls in a row from one confused agent must not take the
+ * sentinel facade offline for everyone.
+ *
+ * So the signal is *unresponsiveness*, not *unhappiness*:
+ *
+ *   - a thrown exception is always a fault (the handler didn't handle it)
+ *   - an `isError` result that took longer than `slowFailureMs` is a fault
+ *     (a dependency that times out is slow; a rejected argument is not)
+ *   - an `isError` result that came back fast is neither fault nor proof of
+ *     health — it leaves the counters exactly where they were
+ *   - a success closes the circuit and clears the count
+ *
+ * State machine: closed → (threshold consecutive faults) → open → (cooldown
+ * elapses) → half-open → success closes it, fault re-opens it. Half-open
+ * admits exactly one probe; concurrent callers are rejected until it lands, so
+ * a recovering database gets one connection attempt rather than six.
+ *
+ * The breaker never converts a working call into a failure — it only refuses
+ * calls it has good reason to believe would fail slowly.
+ */
+export type CircuitState = 'closed' | 'open' | 'half_open';
+export interface CircuitBreakerOptions {
+    /** Consecutive faults before the circuit opens. Default 5. */
+    failureThreshold?: number;
+    /** How long the circuit stays open before admitting a probe. Default 30s. */
+    cooldownMs?: number;
+    /** An `isError` result slower than this counts as a fault. Default 2s. */
+    slowFailureMs?: number;
+    /** Injectable clock — tests drive this instead of sleeping. */
+    now?: () => number;
+}
+export interface CircuitSnapshot {
+    state: CircuitState;
+    consecutive_faults: number;
+    opened_at?: string;
+    retry_after_ms?: number;
+    last_error?: string;
+}
+/** What the caller learns when it asks permission to run. */
+export type CircuitDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    retryAfterMs: number;
+    lastError?: string;
+    openedAt?: string;
+};
+export declare class CircuitBreakerRegistry {
+    private readonly circuits;
+    private readonly failureThreshold;
+    private readonly cooldownMs;
+    readonly slowFailureMs: number;
+    private readonly now;
+    constructor(opts?: CircuitBreakerOptions);
+    /**
+     * Ask whether a call to `key` may proceed. Transitions open → half_open when
+     * the cooldown has elapsed, and reserves the half-open probe for the caller
+     * it says yes to.
+     */
+    beforeCall(key: string): CircuitDecision;
+    /**
+     * Report what happened. `threw` and `durationMs` decide whether this was a
+     * fault; see the module comment for why `isError` alone is not enough and
+     * not too much.
+     */
+    afterCall(key: string, outcome: {
+        threw: boolean;
+        isError: boolean;
+        durationMs: number;
+        error?: string;
+    }): void;
+    recordSuccess(key: string): void;
+    recordFault(key: string, error?: string): void;
+    state(key: string): CircuitState;
+    /** Open circuits only — a healthy runtime reports `{}`. */
+    snapshot(): Record<string, CircuitSnapshot>;
+    reset(key?: string): void;
+    private close;
+}
+//# sourceMappingURL=circuitBreaker.d.ts.map

package/dist/runtime/circuitBreaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuitBreaker.d.ts","sourceRoot":"","sources":["../../src/runtime/circuitBreaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,6DAA6D;AAC7D,MAAM,MAAM,eAAe,GACvB;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GACjB;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAgBpF,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,IAAI,GAAE,qBAA0B;IAO5C;;;;OAIG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe;IAiCxC;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAiB/G,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAMhC,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IA0B9C,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY;IAIhC,2DAA2D;IAC3D,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC;IAiB3C,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAKzB,OAAO,CAAC,KAAK;CAQd"}