@decibelsystems/tools 2.2.0-beta.0 → 3.1.0

package/dist/lib/fileLock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileLock.d.ts","sourceRoot":"","sources":["../../src/lib/fileLock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD,qEAAqE;AACrE,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAQjE;AA8DD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,CAAC,CAAC,CAyBZ"}

package/dist/lib/fileLock.js

@@ -0,0 +1,124 @@
+/**
+ * Cross-process advisory file lock.
+ *
+ * Decibel's stores are plain files in `.decibel/`, written concurrently by
+ * every MCP client, CLI invocation, hook, and migration script on the machine.
+ * An in-process mutex is useless here — the contending writers are separate
+ * processes, often separate installs.
+ *
+ * Acquisition is `open(path, 'wx')`: O_EXCL, which either creates the file
+ * atomically or fails with EEXIST. There is no read-then-write window for a
+ * second caller to slip through, which is the property that makes this safe
+ * where a "does a lock exist?" check would not be.
+ *
+ * The lock is advisory: it only protects callers that take it. That is why the
+ * operations it guards should *also* be individually safe (e.g. creating a file
+ * with O_EXCL so a colliding write fails loudly). Old clients, one-off scripts,
+ * and migrations are part of the threat model and will not take the lock.
+ */
+import { openSync, closeSync, writeSync, unlinkSync, statSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_STALE_MS = 30_000;
+const DEFAULT_RETRY_INTERVAL_MS = 25;
+/** Thrown when the lock could not be acquired before the timeout. */
+export class FileLockTimeoutError extends Error {
+    constructor(lockPath, timeoutMs, holder) {
+        super(`Timed out after ${timeoutMs}ms acquiring lock ${lockPath}` +
+            (holder ? ` (held by ${holder})` : '') +
+            `. If no Decibel process is running, remove the lock file and retry.`);
+        this.name = 'FileLockTimeoutError';
+    }
+}
+function readHolder(lockPath) {
+    try {
+        const raw = statSync(lockPath);
+        return `pid unknown, age ${Math.round((Date.now() - raw.mtimeMs) / 1000)}s`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** One acquisition attempt. Returns true on success. */
+function tryAcquire(lockPath, staleMs) {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    try {
+        const fd = openSync(lockPath, 'wx');
+        try {
+            writeSync(fd, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }));
+        }
+        finally {
+            closeSync(fd);
+        }
+        return true;
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+    }
+    // Held. Abandoned by a crashed holder?
+    try {
+        const age = Date.now() - statSync(lockPath).mtimeMs;
+        if (age > staleMs) {
+            unlinkSync(lockPath);
+            // One retry. If we lose this one too, another waiter beat us to the
+            // steal — fine, they hold it legitimately and we keep waiting.
+            try {
+                const fd = openSync(lockPath, 'wx');
+                try {
+                    writeSync(fd, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }));
+                }
+                finally {
+                    closeSync(fd);
+                }
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    catch {
+        // Lock vanished between EEXIST and stat — the holder released it. The next
+        // loop iteration will acquire normally.
+    }
+    return false;
+}
+function release(lockPath) {
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+        // Already gone (released elsewhere, or stolen as stale). Nothing to do.
+    }
+}
+/**
+ * Run `fn` while holding an exclusive cross-process lock.
+ *
+ * The lock is always released, including when `fn` throws — a failed write must
+ * not wedge every other writer on the machine.
+ */
+export async function withFileLock(lockPath, fn, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    const retryIntervalMs = options.retryIntervalMs ?? DEFAULT_RETRY_INTERVAL_MS;
+    const deadline = Date.now() + timeoutMs;
+    let acquired = false;
+    while (Date.now() < deadline) {
+        if (tryAcquire(lockPath, staleMs)) {
+            acquired = true;
+            break;
+        }
+        await new Promise((r) => setTimeout(r, retryIntervalMs));
+    }
+    if (!acquired) {
+        throw new FileLockTimeoutError(lockPath, timeoutMs, readHolder(lockPath));
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        release(lockPath);
+    }
+}
+//# sourceMappingURL=fileLock.js.map

package/dist/lib/fileLock.js.map

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

package/dist/lib/recordIdAllocator.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Serialized ISS-NNNN and EPIC-NNNN allocation.
+ *
+ * The defect this closes: `create_issue` picked the next id by scanning the
+ * issues directory for the current maximum, then wrote the file many awaits
+ * later. Two processes could read the same maximum and both write ISS-0141.
+ * Four duplicate-id groups were produced by exactly this and were found on disk
+ * (ISS-0015, ISS-0028, ISS-0054, ISS-0112), reported independently by the
+ * `machina` peer and reproduced locally. THIS repo's four were cleared: as of
+ * 2026-09-19 it holds 200 issues and 38 epics with ZERO duplicate frontmatter
+ * ids. ISS-0136 remains OPEN, because it is portfolio-wide and 61 groups still
+ * sit in five other projects (frontend_v0.2, senken-trading-agent, machina,
+ * decibel-studio, decibel-tools-mobile). Do not read "clean" here as "clean
+ * everywhere". The history is kept because it is the evidence
+ * this lock exists, not because the state persists — stated in the past tense
+ * deliberately, since the present-tense version outlived the fact and was read
+ * as current by an outside reader, who repeated it in a document.
+ *
+ * Verify by parsing frontmatter, not by grepping. `grep "^id: ISS-"` over this
+ * store counts documents that QUOTE an id — a report about malformed
+ * frontmatter contains the line it is reporting — and that false positive has
+ * already cost one confidently wrong correction.
+ *
+ * Two independent defences, because a lock only protects callers that take it:
+ *
+ *   1. The lock spans **allocation through successful write**, not just the id
+ *      calculation. Serializing only the scan leaves the same race — both
+ *      processes still compute 141 before either file lands.
+ *
+ *   2. The write itself is exclusive. If a caller bypasses the lock entirely —
+ *      an old client, a migration script, a future mistake — a colliding write
+ *      fails loudly with EEXIST instead of silently overwriting a real issue.
+ *      It is also atomic (ISS-0195): the record is published by link(2) from a
+ *      complete, fsynced temp, so a SIGKILL mid-write can no longer leave a
+ *      0-byte record under a real id, which plain O_EXCL could.
+ *
+ * Both `createIssue` implementations (src/tools/sentinel.ts and
+ * src/sentinelIssues.ts) allocate from a single numbering space and write
+ * different formats into the same directory, so they must share this path or
+ * they race against each other.
+ */
+/** The record kinds that carry an allocated NNNN. */
+export type RecordPrefix = 'ISS' | 'EPIC';
+export declare function formatRecordId(prefix: RecordPrefix, num: number): string;
+export declare function formatIssueId(num: number): string;
+/**
+ * Highest PREFIX-NNNN currently present, by filename prefix or frontmatter id.
+ *
+ * Both sources are checked because the two record formats disagree: PREFIX-NNNN
+ * files carry the id in the name, while timestamp-slug records carry it only in
+ * frontmatter. Scanning one source alone under-counts and hands out an id that
+ * is already taken.
+ */
+export declare function scanMaxRecordNumber(dir: string, prefix: RecordPrefix): Promise<number>;
+export declare function scanMaxIssueNumber(issuesDir: string): Promise<number>;
+export interface AllocatedRecord {
+    id: string;
+    filename: string;
+    filePath: string;
+}
+/**
+ * Allocate the next PREFIX-NNNN and write the record, with both held under one
+ * lock so no other process can allocate the same id in between.
+ *
+ * `buildContent` receives the allocated id because the id appears inside the
+ * record body (frontmatter `id:`), so content cannot be built before allocation.
+ *
+ * On the rare EEXIST — a bypassing writer took the id between our scan and our
+ * write — the allocation is retried rather than failed, up to `maxAttempts`.
+ * Retrying is correct here: the id is genuinely taken, and the next one up is a
+ * valid answer to the caller's request.
+ */
+export declare function allocateAndWriteRecord(dir: string, prefix: RecordPrefix, extension: 'md' | 'yml', slug: string, buildContent: (recordId: string) => string, options?: {
+    maxAttempts?: number;
+    timeoutMs?: number;
+    /** Called with the resolved path before each write attempt, to reject a
+     *  path that escapes the project. Throwing aborts the allocation. */
+    validate?: (filePath: string) => void;
+}): Promise<AllocatedRecord>;
+/** ISS-NNNN allocation. See {@link allocateAndWriteRecord}. */
+export declare function allocateAndWriteIssue(issuesDir: string, extension: 'md' | 'yml', slug: string, buildContent: (issueId: string) => string, options?: {
+    maxAttempts?: number;
+    timeoutMs?: number;
+    validate?: (filePath: string) => void;
+}): Promise<AllocatedRecord>;
+/**
+ * EPIC-NNNN allocation.
+ *
+ * Added because `logEpic` had the pre-lock defect verbatim: it read the
+ * directory for the current maximum, then wrote the file ~20 awaits later.
+ * Epics are the worse half of that race. An issue collision at least left two
+ * files and a visible duplicate id; the epic path wrote through
+ * `writeFileAtomic`, whose rename CLOBBERS, so the loser was not duplicated —
+ * it was gone, and its caller had already been told it was created. Found by
+ * the S5 concurrency sweep.
+ */
+export declare function allocateAndWriteEpic(epicsDir: string, slug: string, buildContent: (epicId: string) => string, options?: {
+    maxAttempts?: number;
+    timeoutMs?: number;
+    validate?: (filePath: string) => void;
+}): Promise<AllocatedRecord>;
+//# sourceMappingURL=recordIdAllocator.d.ts.map

package/dist/lib/recordIdAllocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recordIdAllocator.d.ts","sourceRoot":"","sources":["../../src/lib/recordIdAllocator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAeH,qDAAqD;AACrD,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,MAAM,CAAC;AAgB1C,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAExE;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAiC5F;AAED,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE3E;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,IAAI,GAAG,KAAK,EACvB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,EAC1C,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;yEACqE;IACrE,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC,GACL,OAAO,CAAC,eAAe,CAAC,CAiC1B;AAED,+DAA+D;AAC/D,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,IAAI,GAAG,KAAK,EACvB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,EACzC,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GAChG,OAAO,CAAC,eAAe,CAAC,CAE1B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,EACxC,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GAChG,OAAO,CAAC,eAAe,CAAC,CAE1B"}

package/dist/lib/recordIdAllocator.js

@@ -0,0 +1,179 @@
+/**
+ * Serialized ISS-NNNN and EPIC-NNNN allocation.
+ *
+ * The defect this closes: `create_issue` picked the next id by scanning the
+ * issues directory for the current maximum, then wrote the file many awaits
+ * later. Two processes could read the same maximum and both write ISS-0141.
+ * Four duplicate-id groups were produced by exactly this and were found on disk
+ * (ISS-0015, ISS-0028, ISS-0054, ISS-0112), reported independently by the
+ * `machina` peer and reproduced locally. THIS repo's four were cleared: as of
+ * 2026-09-19 it holds 200 issues and 38 epics with ZERO duplicate frontmatter
+ * ids. ISS-0136 remains OPEN, because it is portfolio-wide and 61 groups still
+ * sit in five other projects (frontend_v0.2, senken-trading-agent, machina,
+ * decibel-studio, decibel-tools-mobile). Do not read "clean" here as "clean
+ * everywhere". The history is kept because it is the evidence
+ * this lock exists, not because the state persists — stated in the past tense
+ * deliberately, since the present-tense version outlived the fact and was read
+ * as current by an outside reader, who repeated it in a document.
+ *
+ * Verify by parsing frontmatter, not by grepping. `grep "^id: ISS-"` over this
+ * store counts documents that QUOTE an id — a report about malformed
+ * frontmatter contains the line it is reporting — and that false positive has
+ * already cost one confidently wrong correction.
+ *
+ * Two independent defences, because a lock only protects callers that take it:
+ *
+ *   1. The lock spans **allocation through successful write**, not just the id
+ *      calculation. Serializing only the scan leaves the same race — both
+ *      processes still compute 141 before either file lands.
+ *
+ *   2. The write itself is exclusive. If a caller bypasses the lock entirely —
+ *      an old client, a migration script, a future mistake — a colliding write
+ *      fails loudly with EEXIST instead of silently overwriting a real issue.
+ *      It is also atomic (ISS-0195): the record is published by link(2) from a
+ *      complete, fsynced temp, so a SIGKILL mid-write can no longer leave a
+ *      0-byte record under a real id, which plain O_EXCL could.
+ *
+ * Both `createIssue` implementations (src/tools/sentinel.ts and
+ * src/sentinelIssues.ts) allocate from a single numbering space and write
+ * different formats into the same directory, so they must share this path or
+ * they race against each other.
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { withFileLock } from './fileLock.js';
+import { createFileExclusive, sweepAllocationTemps } from './atomicWrite.js';
+/**
+ * Lock file guarding id allocation, scoped per record directory.
+ *
+ * Issues and epics number independently and live in different directories, so
+ * one lock file name per directory is exactly one lock per numbering space.
+ */
+const LOCK_FILENAME = '.record-id.lock';
+/** Records the allocator considers when scanning for the current maximum. */
+function isRecordFile(filename) {
+    return /\.(md|yml|yaml)$/i.test(filename);
+}
+function frontmatterRegion(content) {
+    const delimited = /^---\n([\s\S]*?)\n---/.exec(content);
+    if (delimited)
+        return delimited[1];
+    // Bare-YAML records have no delimiters; the whole head is the region.
+    if (/^---/.test(content.trimStart()))
+        return null;
+    const headingIdx = content.split('\n').findIndex((l) => /^#{1,6}\s/.test(l));
+    return headingIdx > 0 ? content.split('\n').slice(0, headingIdx).join('\n') : content;
+}
+export function formatRecordId(prefix, num) {
+    return `${prefix}-${num.toString().padStart(4, '0')}`;
+}
+export function formatIssueId(num) {
+    return formatRecordId('ISS', num);
+}
+/**
+ * Highest PREFIX-NNNN currently present, by filename prefix or frontmatter id.
+ *
+ * Both sources are checked because the two record formats disagree: PREFIX-NNNN
+ * files carry the id in the name, while timestamp-slug records carry it only in
+ * frontmatter. Scanning one source alone under-counts and hands out an id that
+ * is already taken.
+ */
+export async function scanMaxRecordNumber(dir, prefix) {
+    let max = 0;
+    let files;
+    try {
+        files = await fs.readdir(dir);
+    }
+    catch {
+        return 0; // Directory does not exist yet.
+    }
+    const fromName = new RegExp(`^${prefix}-(\\d+)`, 'i');
+    const fromId = new RegExp(`^${prefix}-(\\d+)$`, 'i');
+    for (const file of files) {
+        const prefixMatch = file.match(fromName);
+        if (prefixMatch) {
+            max = Math.max(max, parseInt(prefixMatch[1], 10));
+            continue;
+        }
+        if (!isRecordFile(file))
+            continue;
+        try {
+            const content = await fs.readFile(path.join(dir, file), 'utf-8');
+            const region = frontmatterRegion(content);
+            if (!region)
+                continue;
+            const idLine = region.split('\n').find((l) => l.trim().toLowerCase().startsWith('id:'));
+            if (!idLine)
+                continue;
+            const idVal = idLine.slice(idLine.indexOf(':') + 1).trim();
+            const idMatch = idVal.match(fromId);
+            if (idMatch)
+                max = Math.max(max, parseInt(idMatch[1], 10));
+        }
+        catch {
+            // Unreadable record — skip rather than abort the whole allocation.
+        }
+    }
+    return max;
+}
+export async function scanMaxIssueNumber(issuesDir) {
+    return scanMaxRecordNumber(issuesDir, 'ISS');
+}
+/**
+ * Allocate the next PREFIX-NNNN and write the record, with both held under one
+ * lock so no other process can allocate the same id in between.
+ *
+ * `buildContent` receives the allocated id because the id appears inside the
+ * record body (frontmatter `id:`), so content cannot be built before allocation.
+ *
+ * On the rare EEXIST — a bypassing writer took the id between our scan and our
+ * write — the allocation is retried rather than failed, up to `maxAttempts`.
+ * Retrying is correct here: the id is genuinely taken, and the next one up is a
+ * valid answer to the caller's request.
+ */
+export async function allocateAndWriteRecord(dir, prefix, extension, slug, buildContent, options = {}) {
+    const maxAttempts = options.maxAttempts ?? 5;
+    const lockPath = path.join(dir, LOCK_FILENAME);
+    return withFileLock(lockPath, async () => {
+        await sweepAllocationTemps(dir);
+        let next = (await scanMaxRecordNumber(dir, prefix)) + 1;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const id = formatRecordId(prefix, next);
+            const filename = `${id}-${slug}.${extension}`;
+            const filePath = path.join(dir, filename);
+            options.validate?.(filePath);
+            try {
+                // Exclusive (EEXIST rather than clobbering) and atomic (never partial).
+                await createFileExclusive(filePath, buildContent(id));
+                return { id, filename, filePath };
+            }
+            catch (err) {
+                if (err.code !== 'EEXIST')
+                    throw err;
+                next++; // Taken by a writer that did not hold the lock. Try the next.
+            }
+        }
+        throw new Error(`Could not allocate an unused ${prefix} id in ${dir} after ${maxAttempts} attempts ` +
+            `(last tried ${formatRecordId(prefix, next - 1)}). The directory may contain records ` +
+            `written by a process that bypasses id locking.`);
+    }, { timeoutMs: options.timeoutMs });
+}
+/** ISS-NNNN allocation. See {@link allocateAndWriteRecord}. */
+export async function allocateAndWriteIssue(issuesDir, extension, slug, buildContent, options = {}) {
+    return allocateAndWriteRecord(issuesDir, 'ISS', extension, slug, buildContent, options);
+}
+/**
+ * EPIC-NNNN allocation.
+ *
+ * Added because `logEpic` had the pre-lock defect verbatim: it read the
+ * directory for the current maximum, then wrote the file ~20 awaits later.
+ * Epics are the worse half of that race. An issue collision at least left two
+ * files and a visible duplicate id; the epic path wrote through
+ * `writeFileAtomic`, whose rename CLOBBERS, so the loser was not duplicated —
+ * it was gone, and its caller had already been told it was created. Found by
+ * the S5 concurrency sweep.
+ */
+export async function allocateAndWriteEpic(epicsDir, slug, buildContent, options = {}) {
+    return allocateAndWriteRecord(epicsDir, 'EPIC', 'md', slug, buildContent, options);
+}
+//# sourceMappingURL=recordIdAllocator.js.map

package/dist/lib/recordIdAllocator.js.map

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

package/dist/orgId.d.ts

@@ -0,0 +1,23 @@
+export declare class OrgIdError extends Error {
+}
+/**
+ * The configured org, or null when DECIBEL_ORG_ID is unset or blank.
+ * A value that is set but not a uuid throws: a typo must not look like "unset".
+ */
+export declare function getOrgId(): string | null;
+/** The configured org, or an actionable error naming the variable. */
+export declare function requireOrgId(): string;
+/** True when this process holds HQ service credentials. */
+export declare function isHqConnected(): boolean;
+/**
+ * Startup gate. Throws when HQ credentials are present but no valid org is.
+ * Returns the org when connected, or null for a local-only install.
+ */
+export declare function assertOrgForHqConnection(): string | null;
+/**
+ * For the HQ writers' entry points, which must never throw into the daemon:
+ * the org, or null after logging why the feature is off. Reaching null on the
+ * daemon path means the startup gate was skipped.
+ */
+export declare function orgOrLog(feature: string): string | null;
+//# sourceMappingURL=orgId.d.ts.map

package/dist/orgId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orgId.d.ts","sourceRoot":"","sources":["../src/orgId.ts"],"names":[],"mappings":"AAqBA,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAExC;;;GAGG;AACH,wBAAgB,QAAQ,IAAI,MAAM,GAAG,IAAI,CAUxC;AAED,sEAAsE;AACtE,wBAAgB,YAAY,IAAI,MAAM,CAWrC;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAGxD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOvD"}

package/dist/orgId.js

@@ -0,0 +1,73 @@
+// ============================================================================
+// The org this daemon serves: one source (EPIC-0040, ADR-0014)
+// ============================================================================
+// There is no default. This used to fall back to a hardcoded uuid, Ben's org,
+// so an HQ-connected daemon that forgot DECIBEL_ORG_ID silently wrote presence
+// and command settlements into that org under service_role. RLS sits below
+// service_role, so nothing caught it. Once HQ gives every account a personal
+// org (decibel-hq ADR-0016), that fallback becomes a cross-tenant write on
+// every solo install, which is why removing it is step (a) of ADR-0014.
+//
+// The org is required exactly where it is used: the HQ-connected path, i.e.
+// SUPABASE_URL and SUPABASE_SERVICE_KEY are set. A local-only install never
+// reads it. assertOrgForHqConnection() is the daemon's startup gate; the
+// readers call requireOrgId() lazily, never at import time, so a missing
+// variable cannot break boot for a process that would never use it.
+// ============================================================================
+import { log } from './config.js';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export class OrgIdError extends Error {
+}
+/**
+ * The configured org, or null when DECIBEL_ORG_ID is unset or blank.
+ * A value that is set but not a uuid throws: a typo must not look like "unset".
+ */
+export function getOrgId() {
+    const raw = process.env.DECIBEL_ORG_ID?.trim();
+    if (!raw)
+        return null;
+    if (!UUID_RE.test(raw)) {
+        throw new OrgIdError('DECIBEL_ORG_ID is set but is not a uuid. It must be the id of your org ' +
+            'in HQ (hq.orgs.id).');
+    }
+    return raw.toLowerCase();
+}
+/** The configured org, or an actionable error naming the variable. */
+export function requireOrgId() {
+    const org = getOrgId();
+    if (!org) {
+        throw new OrgIdError('DECIBEL_ORG_ID is not set. HQ-connected features (presence, agent commands, ' +
+            'roster resolution) need the id of the org this machine works for. Set ' +
+            'DECIBEL_ORG_ID to your org id from HQ (hq.orgs.id) in the daemon environment. ' +
+            'There is no default, so writes cannot land in someone else\'s org.');
+    }
+    return org;
+}
+/** True when this process holds HQ service credentials. */
+export function isHqConnected() {
+    return Boolean(process.env.SUPABASE_URL && process.env.SUPABASE_SERVICE_KEY);
+}
+/**
+ * Startup gate. Throws when HQ credentials are present but no valid org is.
+ * Returns the org when connected, or null for a local-only install.
+ */
+export function assertOrgForHqConnection() {
+    if (!isHqConnected())
+        return null;
+    return requireOrgId();
+}
+/**
+ * For the HQ writers' entry points, which must never throw into the daemon:
+ * the org, or null after logging why the feature is off. Reaching null on the
+ * daemon path means the startup gate was skipped.
+ */
+export function orgOrLog(feature) {
+    try {
+        return requireOrgId();
+    }
+    catch (e) {
+        log(`${feature}: disabled. ${e instanceof Error ? e.message : String(e)}`);
+        return null;
+    }
+}
+//# sourceMappingURL=orgId.js.map

package/dist/orgId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orgId.js","sourceRoot":"","sources":["../src/orgId.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,+DAA+D;AAC/D,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,2EAA2E;AAC3E,6EAA6E;AAC7E,2EAA2E;AAC3E,wEAAwE;AACxE,EAAE;AACF,4EAA4E;AAC5E,4EAA4E;AAC5E,yEAAyE;AACzE,yEAAyE;AACzE,oEAAoE;AACpE,+EAA+E;AAE/E,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAElC,MAAM,OAAO,GAAG,iEAAiE,CAAC;AAElF,MAAM,OAAO,UAAW,SAAQ,KAAK;CAAG;AAExC;;;GAGG;AACH,MAAM,UAAU,QAAQ;IACtB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC;IAC/C,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,UAAU,CAClB,yEAAyE;YACvE,qBAAqB,CACxB,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC;AAC3B,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,YAAY;IAC1B,MAAM,GAAG,GAAG,QAAQ,EAAE,CAAC;IACvB,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,UAAU,CAClB,8EAA8E;YAC5E,wEAAwE;YACxE,gFAAgF;YAChF,oEAAoE,CACvE,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,aAAa;IAC3B,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;AAC/E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB;IACtC,IAAI,CAAC,aAAa,EAAE;QAAE,OAAO,IAAI,CAAC;IAClC,OAAO,YAAY,EAAE,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,IAAI,CAAC;QACH,OAAO,YAAY,EAAE,CAAC;IACxB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,GAAG,CAAC,GAAG,OAAO,eAAe,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/pairCli.d.ts

@@ -0,0 +1,2 @@
+export declare function runPairCli(argv: string[]): Promise<number>;
+//# sourceMappingURL=pairCli.d.ts.map

package/dist/pairCli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairCli.d.ts","sourceRoot":"","sources":["../src/pairCli.ts"],"names":[],"mappings":"AAwCA,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA0DhE"}

package/dist/pairCli.js

@@ -0,0 +1,97 @@
+// ============================================================================
+// `decibel-tools pair` — the only place a browser pairing is approved
+// ============================================================================
+// ADR-0012 (this repo): approval is unreachable from any browser. It happens
+// here, in a terminal on this machine, by typing the code HQ is showing — which
+// proves the person approving can see both sides. `pair list` deliberately does
+// NOT print pending codes: a code read from here instead of from HQ proves
+// nothing.
+// ============================================================================
+import { createInterface } from 'readline';
+import { approveByCode, listPairings, pairingsPath, revokePairing } from './pty/pairing.js';
+function ago(iso) {
+    if (!iso)
+        return '-';
+    const s = Math.max(0, Math.round((Date.now() - Date.parse(iso)) / 1000));
+    if (s < 60)
+        return `${s}s ago`;
+    if (s < 3600)
+        return `${Math.round(s / 60)}m ago`;
+    if (s < 86400)
+        return `${Math.round(s / 3600)}h ago`;
+    return `${Math.round(s / 86400)}d ago`;
+}
+function describe(p) {
+    return `${p.origin}  "${p.label}"  requested ${ago(p.requested_at)}`;
+}
+async function confirm(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => rl.question(question, resolve));
+    rl.close();
+    return /^y(es)?$/i.test(answer.trim());
+}
+const USAGE = `Usage:
+  decibel-tools pair list              pending requests and approved browsers
+  decibel-tools pair approve <code>    approve the request showing <code> in HQ
+  decibel-tools pair revoke <id>       remove a pairing (closes its live sessions)
+
+Store: ${'~/.decibel/pairings.yaml'} (public keys only, mode 0600)`;
+export async function runPairCli(argv) {
+    const [cmd, arg, ...rest] = argv;
+    const yes = rest.includes('--yes') || arg === '--yes';
+    if (cmd === 'list') {
+        const all = listPairings();
+        const pending = all.filter((p) => p.status === 'pending');
+        const approved = all.filter((p) => p.status === 'approved');
+        console.log(`Pending (${pending.length}) — approve with the code HQ shows:`);
+        for (const p of pending)
+            console.log(`  ${p.id}  ${describe(p)}`);
+        console.log(`Approved (${approved.length}):`);
+        for (const p of approved)
+            console.log(`  ${p.id}  ${p.origin}  "${p.label}"  approved ${ago(p.approved_at)}, last used ${ago(p.last_used)}`);
+        if (!all.length)
+            console.log(`  (none — ${pairingsPath()})`);
+        return 0;
+    }
+    if (cmd === 'approve') {
+        if (!arg || !/^\d{6}$/.test(arg)) {
+            console.error('Type the 6-digit code HQ is showing: decibel-tools pair approve <code>');
+            return 2;
+        }
+        const pending = listPairings().filter((p) => p.status === 'pending');
+        const target = pending.find((p) => p.code === arg);
+        if (!target) {
+            console.error(`No pending request with code ${arg}. Requests expire after 10 minutes; start again in HQ.`);
+            return 1;
+        }
+        console.log(`Pairing request: ${describe(target)}`);
+        if (pending.length > 1) {
+            console.log(`WARNING: ${pending.length} requests are pending at once. If you did not start all of them, approve nothing and check HQ.`);
+        }
+        if (!yes) {
+            if (!process.stdin.isTTY) {
+                console.error('Refusing to approve without a terminal to confirm in. Re-run interactively (or pass --yes if you are certain).');
+                return 1;
+            }
+            if (!(await confirm(`Let ${target.origin} act on this machine's daemon? [y/N] `))) {
+                console.log('Not approved.');
+                return 1;
+            }
+        }
+        const p = await approveByCode(arg);
+        console.log(`Approved ${p.id} (${p.origin}). Revoke any time: decibel-tools pair revoke ${p.id}`);
+        return 0;
+    }
+    if (cmd === 'revoke') {
+        if (!arg) {
+            console.error('decibel-tools pair revoke <id>   (ids: decibel-tools pair list)');
+            return 2;
+        }
+        const removed = await revokePairing(arg);
+        console.log(removed ? `Revoked ${arg}. Its live sessions close within 5s.` : `No pairing ${arg}.`);
+        return removed ? 0 : 1;
+    }
+    console.log(USAGE);
+    return cmd ? 2 : 0;
+}
+//# sourceMappingURL=pairCli.js.map

package/dist/pairCli.js.map

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