@decibelsystems/tools 2.1.4 → 3.0.0

package/dist/runtime/extensions.js

@@ -0,0 +1,216 @@
+// ============================================================================
+// Extension Loader — EPIC-0038 Phase 7
+// ============================================================================
+// Private facades are not compiled into the published package. They arrive at
+// boot as extensions: modules named by absolute path in an allowlist under
+// ~/.decibel/config.yaml, registered into the same registry core facades use.
+//
+// The security model is registration, not permission. A facade that was never
+// registered cannot be dispatched to, cannot appear in tools/list, and cannot
+// be reached by a name-prefix trick — there is nothing on the other end. That
+// is a stronger guarantee than a runtime tier check, which is one missed branch
+// away from failing open. It replaces the DECIBEL_APPS env gate, which had the
+// opposite failure mode: the flag lived in a launchd plist, so regenerating the
+// plist silently dropped four facades with no error anywhere.
+//
+// TRUST BOUNDARY — read before changing anything here.
+// An extension runs in-process with the runtime's full filesystem and database
+// access. There is no sandbox and this loader does not pretend to be one. The
+// allowlist is what makes that proportionate: for single-user private use,
+// "the owner named this exact file" is a real boundary. It stops being one the
+// moment a path can come from somewhere other than the owner's config, so:
+//
+//   - Only absolute paths are accepted. A bare specifier ("senken") would be
+//     resolved by Node against node_modules, which makes the allowlist
+//     decorative — anything that can write a package into the tree chooses
+//     what runs.
+//   - The path is never read from the environment. Config file only.
+//   - An extension may not shadow an already-registered facade name.
+// ============================================================================
+import { existsSync } from 'fs';
+import { isAbsolute, normalize } from 'path';
+import { pathToFileURL } from 'url';
+import { loadConfig } from '../daemonConfig.js';
+import { log } from '../config.js';
+import { RUNTIME_PROTOCOL_VERSION, isProtocolCompatible } from './protocol.js';
+const EMPTY_RESULT = {
+    extensions: [],
+    facades: [],
+    tools: [],
+    rejected: [],
+};
+/** Facade names must look like facade names — this is also what the kernel keys on. */
+const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+// ============================================================================
+// Manifest validation
+// ============================================================================
+function validateManifest(value) {
+    if (!value || typeof value !== 'object') {
+        return { ok: false, reason: 'manifest is missing or not an object' };
+    }
+    const m = value;
+    if (typeof m.name !== 'string' || !NAME_PATTERN.test(m.name)) {
+        return { ok: false, reason: `manifest.name must match ${NAME_PATTERN} (got ${JSON.stringify(m.name)})` };
+    }
+    if (typeof m.version !== 'string' || m.version.length === 0) {
+        return { ok: false, reason: 'manifest.version must be a non-empty string' };
+    }
+    if (m.tier !== 'pro' && m.tier !== 'apps') {
+        return { ok: false, reason: `manifest.tier must be "pro" or "apps" (got ${JSON.stringify(m.tier)}) — "core" is what ships in the package, so it cannot be an extension` };
+    }
+    if (typeof m.protocolVersion !== 'string') {
+        return { ok: false, reason: 'manifest.protocolVersion must be a string' };
+    }
+    // The extension is a client of the runtime's wire contract, so the runtime is
+    // the "server" side of the comparison. A stale extension fails here with a
+    // version mismatch rather than later with a missing endpoint.
+    const compat = isProtocolCompatible(RUNTIME_PROTOCOL_VERSION, m.protocolVersion);
+    if (!compat.compatible) {
+        return { ok: false, reason: `protocol mismatch — ${compat.reason}` };
+    }
+    return {
+        ok: true,
+        manifest: {
+            name: m.name,
+            version: m.version,
+            protocolVersion: m.protocolVersion,
+            tier: m.tier,
+        },
+    };
+}
+function validateShape(value) {
+    if (!value || typeof value !== 'object') {
+        return { ok: false, reason: 'module does not export `extension`' };
+    }
+    const ext = value;
+    const manifestResult = validateManifest(ext.manifest);
+    if (!manifestResult.ok)
+        return manifestResult;
+    if (!Array.isArray(ext.facades) || ext.facades.length === 0) {
+        return { ok: false, reason: 'extension.facades must be a non-empty array' };
+    }
+    if (!Array.isArray(ext.tools) || ext.tools.length === 0) {
+        return { ok: false, reason: 'extension.tools must be a non-empty array' };
+    }
+    const manifest = manifestResult.manifest;
+    // Every facade the extension declares must carry the manifest's tier. An
+    // extension cannot smuggle a facade in at a laxer tier than it was allowed at.
+    for (const facade of ext.facades) {
+        if (!facade || typeof facade.name !== 'string' || !NAME_PATTERN.test(facade.name)) {
+            return { ok: false, reason: 'every entry in extension.facades must be a FacadeSpec with a valid name' };
+        }
+        if (facade.tier !== manifest.tier) {
+            return {
+                ok: false,
+                reason: `facade "${facade.name}" declares tier "${facade.tier}" but the manifest declares "${manifest.tier}"`,
+            };
+        }
+    }
+    return { ok: true, extension: ext };
+}
+// ============================================================================
+// Allowlist
+// ============================================================================
+/**
+ * Read the extension allowlist from ~/.decibel/config.yaml.
+ *
+ * Deliberately config-only. Reading a path from the environment would let
+ * anything that can set an env var — a plist, a shell profile, a parent
+ * process — choose code that runs in-process with full access, which is
+ * exactly the property the allowlist exists to provide.
+ */
+export function readAllowlist() {
+    const config = loadConfig();
+    const entries = config.extensions?.allow;
+    if (!Array.isArray(entries))
+        return [];
+    return entries.filter((e) => typeof e === 'string');
+}
+/** Path rules, split out so the test suite can exercise them without a filesystem. */
+export function checkAllowlistEntry(entry) {
+    const trimmed = entry.trim();
+    if (trimmed.length === 0) {
+        return { ok: false, reason: 'empty allowlist entry' };
+    }
+    if (!isAbsolute(trimmed)) {
+        return {
+            ok: false,
+            reason: 'not an absolute path — a bare specifier would be resolved against node_modules, which makes the allowlist decorative',
+        };
+    }
+    // normalize() collapses any ".." segments. Compare against the original so a
+    // path that only *looks* like the allowed one is rejected rather than quietly
+    // rewritten into something else.
+    const normalized = normalize(trimmed);
+    if (normalized !== trimmed) {
+        return { ok: false, reason: `path is not normalized (resolves to ${normalized})` };
+    }
+    return { ok: true, path: normalized };
+}
+// ============================================================================
+// Loader
+// ============================================================================
+/**
+ * Load every allowlisted extension.
+ *
+ * Never throws. A broken extension is reported in `rejected` and the runtime
+ * boots without it — one bad private module must not take down core. Callers
+ * that care (the daemon's startup log, /health) surface the rejections.
+ *
+ * @param reservedNames Facade names already registered. An extension may not
+ *   shadow one; that would let a private module silently replace `sentinel`.
+ */
+export async function loadExtensions(reservedNames = new Set()) {
+    const entries = readAllowlist();
+    if (entries.length === 0)
+        return EMPTY_RESULT;
+    const extensions = [];
+    const facades = [];
+    const tools = [];
+    const rejected = [];
+    const claimed = new Set(reservedNames);
+    for (const entry of entries) {
+        const pathCheck = checkAllowlistEntry(entry);
+        if (!pathCheck.ok) {
+            rejected.push({ entry, reason: pathCheck.reason });
+            continue;
+        }
+        if (!existsSync(pathCheck.path)) {
+            rejected.push({ entry, reason: 'file does not exist' });
+            continue;
+        }
+        let mod;
+        try {
+            mod = (await import(pathToFileURL(pathCheck.path).href));
+        }
+        catch (error) {
+            rejected.push({ entry, reason: `import failed — ${error instanceof Error ? error.message : String(error)}` });
+            continue;
+        }
+        const shape = validateShape(mod.extension);
+        if (!shape.ok) {
+            rejected.push({ entry, reason: shape.reason });
+            continue;
+        }
+        const extension = shape.extension;
+        const collision = extension.facades.find(f => claimed.has(f.name));
+        if (collision) {
+            rejected.push({ entry, reason: `facade "${collision.name}" is already registered — an extension may not shadow it` });
+            continue;
+        }
+        for (const facade of extension.facades)
+            claimed.add(facade.name);
+        extensions.push(extension);
+        facades.push(...extension.facades);
+        tools.push(...extension.tools);
+    }
+    for (const r of rejected) {
+        log(`Extensions: rejected ${r.entry} — ${r.reason}`);
+    }
+    if (extensions.length > 0) {
+        const names = extensions.map(e => `${e.manifest.name}@${e.manifest.version}`).join(', ');
+        log(`Extensions: loaded ${extensions.length} (${names}) — ${facades.length} facades, ${tools.length} tools`);
+    }
+    return { extensions, facades, tools, rejected };
+}
+//# sourceMappingURL=extensions.js.map

package/dist/runtime/extensions.js.map

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

package/dist/runtime/localHttp.d.ts

@@ -0,0 +1,24 @@
+export interface LocalResponse {
+    status: number;
+    ok: boolean;
+    text: string;
+}
+export interface LocalRequestOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    timeoutMs: number;
+}
+/**
+ * Perform one loopback HTTP request. Rejects on transport failure (nothing
+ * listening, socket closed, timeout); resolves with the status for any
+ * response the server actually sent, including 4xx and 5xx.
+ */
+export declare function localRequest(url: string, opts: LocalRequestOptions): Promise<LocalResponse>;
+/** localRequest + JSON.parse, with the status preserved for the caller. */
+export declare function localJson<T = unknown>(url: string, opts: LocalRequestOptions): Promise<{
+    status: number;
+    ok: boolean;
+    body: T;
+}>;
+//# sourceMappingURL=localHttp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"localHttp.d.ts","sourceRoot":"","sources":["../../src/runtime/localHttp.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAoD3F;AAED,2EAA2E;AAC3E,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,CAWnD"}

package/dist/runtime/localHttp.js

@@ -0,0 +1,84 @@
+// ============================================================================
+// Loopback HTTP for the thin client
+// ============================================================================
+// Node's global fetch() is undici, and undici is initialised lazily on first
+// use: touching fetch() once costs ~10.8 MB resident (measured — see
+// scripts/measure-memory.mjs). node:http is already resident in every process
+// and costs ~2.5 MB for the same work.
+//
+// That trade is only obviously correct because of what these requests are:
+// loopback, plaintext, small JSON bodies, no redirects, no compression, no
+// cookies, no keep-alive pooling worth having. None of undici's surface is in
+// use here, so none of it is worth 10 MB in five client processes.
+//
+// This is deliberately NOT a fetch polyfill. It returns the response body as
+// text and lets callers parse, so a non-JSON error page surfaces as the status
+// code the server actually sent rather than a parse error.
+// ============================================================================
+import { request } from 'http';
+/**
+ * Perform one loopback HTTP request. Rejects on transport failure (nothing
+ * listening, socket closed, timeout); resolves with the status for any
+ * response the server actually sent, including 4xx and 5xx.
+ */
+export function localRequest(url, opts) {
+    const { method = 'GET', headers = {}, body, timeoutMs } = opts;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const target = new URL(url);
+        const req = request({
+            protocol: target.protocol,
+            hostname: target.hostname,
+            port: target.port,
+            path: `${target.pathname}${target.search}`,
+            method,
+            headers: body === undefined
+                ? headers
+                : { ...headers, 'Content-Length': String(Buffer.byteLength(body)) },
+        }, (res) => {
+            const chunks = [];
+            res.on('data', (c) => chunks.push(c));
+            res.on('error', (err) => finish(() => reject(err)));
+            res.on('end', () => finish(() => {
+                const status = res.statusCode ?? 0;
+                resolve({
+                    status,
+                    ok: status >= 200 && status < 300,
+                    text: Buffer.concat(chunks).toString('utf-8'),
+                });
+            }));
+        });
+        // Timeout is enforced here rather than via req.setTimeout, which fires on
+        // socket inactivity and so cannot bound a slow-but-trickling response.
+        const timer = setTimeout(() => {
+            finish(() => {
+                req.destroy();
+                reject(new Error(`request to ${url} timed out after ${timeoutMs}ms`));
+            });
+        }, timeoutMs);
+        req.on('error', (err) => finish(() => reject(err)));
+        if (body !== undefined)
+            req.write(body);
+        req.end();
+    });
+}
+/** localRequest + JSON.parse, with the status preserved for the caller. */
+export async function localJson(url, opts) {
+    const res = await localRequest(url, opts);
+    let parsed;
+    try {
+        parsed = JSON.parse(res.text);
+    }
+    catch {
+        throw new Error(`${url} returned ${res.status} with a non-JSON body: ${res.text.slice(0, 200)}`);
+    }
+    return { status: res.status, ok: res.ok, body: parsed };
+}
+//# sourceMappingURL=localHttp.js.map

package/dist/runtime/localHttp.js.map

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

package/dist/runtime/projectResolution.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Which strategy answered. The `matched` flag is the part callers care about:
+ * strategies 1-5 and an explicit default all identify the project the caller
+ * meant; 6 and 7 substitute a different one.
+ */
+export type ResolutionStrategy = 'exact_id' | 'alias' | 'env_root_exact' | 'absolute_path' | 'cwd_exact' | 'env_root_fallback' | 'cwd_fallback' | 'default_project';
+export interface ResolutionRecord {
+    /** What the caller asked for. Undefined when the call omitted a project id. */
+    requested?: string;
+    /** The id of the project actually served. */
+    resolvedId: string;
+    /** The path actually served — the field strategy 6 substitutes silently. */
+    resolvedPath: string;
+    strategy: ResolutionStrategy;
+    /** False when the resolver substituted a project the caller did not ask for. */
+    matched: boolean;
+}
+/**
+ * Run `fn` with resolution tracking active. Nested calls share the outermost
+ * slot, so a tool that resolves several projects reports the last one — good
+ * enough for the single-project calls this exists to protect, and honest about
+ * it rather than silently reporting the first.
+ */
+export declare function withResolutionTracking<T>(fn: () => Promise<T>): Promise<T>;
+/** Called by the resolver at each of its exits. A no-op outside a tracked scope. */
+export declare function recordResolution(requested: string | undefined, resolvedId: string, resolvedPath: string, strategy: ResolutionStrategy): void;
+/** The resolution that happened during this dispatch, if any. */
+export declare function currentResolution(): ResolutionRecord | undefined;
+//# sourceMappingURL=projectResolution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"projectResolution.d.ts","sourceRoot":"","sources":["../../src/runtime/projectResolution.ts"],"names":[],"mappings":"AAkCA;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,OAAO,GACP,gBAAgB,GAChB,eAAe,GACf,WAAW,GACX,mBAAmB,GACnB,cAAc,GACd,iBAAiB,CAAC;AAOtB,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAC;CAClB;AAQD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAI1E;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,kBAAkB,GAC3B,IAAI,CAUN;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,IAAI,gBAAgB,GAAG,SAAS,CAEhE"}

package/dist/runtime/projectResolution.js

@@ -0,0 +1,67 @@
+// ============================================================================
+// Project resolution tracking — EPIC-0038 Phase 4
+// ============================================================================
+// Project resolution is forgiving by design. `resolveProject` has seven
+// strategies, and the last two do not match the caller's request at all —
+// they substitute a project discovered from the environment or the working
+// directory so that an interactive agent's typo doesn't hard-fail:
+//
+//     // Strategy 7: If we discovered a project from cwd but ID didn't match,
+//     // use it anyway. This prevents hard failures when Claude sends a
+//     // slightly wrong project ID.
+//
+// That is a reasonable trade for one agent guessing at a name. It is the
+// wrong trade for a programmatic caller sweeping a list of known-good ids:
+// HQ fans out across 34 projects and five facades, and an id that fails to
+// resolve does not come back empty — it comes back carrying ANOTHER project's
+// issues, actions and friction, wearing the requested project's name in the
+// UI. Absence is visible. Misattribution is not.
+//
+// Strategy 6 is subtler still: it returns the REQUESTED id with a substituted
+// path, so comparing the id you asked for against the id you got cannot
+// detect it. Only the resolver knows, and until now it dropped that knowledge
+// on the floor — it logs a line locally and returns a value indistinguishable
+// from a real match.
+//
+// This module keeps the resolver's own account of what happened for the
+// duration of one dispatch, so the runtime can tell the caller when the
+// project it served is not the project that was asked for. It changes no
+// resolution behaviour; whether strategy 6 and 7 should exist at all for a
+// programmatic caller is a separate and larger question.
+// ============================================================================
+import { AsyncLocalStorage } from 'async_hooks';
+const SUBSTITUTING = new Set([
+    'env_root_fallback',
+    'cwd_fallback',
+]);
+const storage = new AsyncLocalStorage();
+/**
+ * Run `fn` with resolution tracking active. Nested calls share the outermost
+ * slot, so a tool that resolves several projects reports the last one — good
+ * enough for the single-project calls this exists to protect, and honest about
+ * it rather than silently reporting the first.
+ */
+export function withResolutionTracking(fn) {
+    const existing = storage.getStore();
+    if (existing)
+        return fn();
+    return storage.run({}, fn);
+}
+/** Called by the resolver at each of its exits. A no-op outside a tracked scope. */
+export function recordResolution(requested, resolvedId, resolvedPath, strategy) {
+    const slot = storage.getStore();
+    if (!slot)
+        return;
+    slot.record = {
+        requested,
+        resolvedId,
+        resolvedPath,
+        strategy,
+        matched: !SUBSTITUTING.has(strategy),
+    };
+}
+/** The resolution that happened during this dispatch, if any. */
+export function currentResolution() {
+    return storage.getStore()?.record;
+}
+//# sourceMappingURL=projectResolution.js.map

package/dist/runtime/projectResolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectResolution.js","sourceRoot":"","sources":["../../src/runtime/projectResolution.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,kDAAkD;AAClD,+EAA+E;AAC/E,wEAAwE;AACxE,0EAA0E;AAC1E,2EAA2E;AAC3E,mEAAmE;AACnE,EAAE;AACF,8EAA8E;AAC9E,wEAAwE;AACxE,oCAAoC;AACpC,EAAE;AACF,yEAAyE;AACzE,2EAA2E;AAC3E,2EAA2E;AAC3E,8EAA8E;AAC9E,4EAA4E;AAC5E,iDAAiD;AACjD,EAAE;AACF,8EAA8E;AAC9E,wEAAwE;AACxE,8EAA8E;AAC9E,8EAA8E;AAC9E,qBAAqB;AACrB,EAAE;AACF,wEAAwE;AACxE,wEAAwE;AACxE,yEAAyE;AACzE,2EAA2E;AAC3E,yDAAyD;AACzD,+EAA+E;AAE/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAiBhD,MAAM,YAAY,GAAoC,IAAI,GAAG,CAAqB;IAChF,mBAAmB;IACnB,cAAc;CACf,CAAC,CAAC;AAkBH,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAQ,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAI,EAAoB;IAC5D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IACpC,IAAI,QAAQ;QAAE,OAAO,EAAE,EAAE,CAAC;IAC1B,OAAO,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,gBAAgB,CAC9B,SAA6B,EAC7B,UAAkB,EAClB,YAAoB,EACpB,QAA4B;IAE5B,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAChC,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,IAAI,CAAC,MAAM,GAAG;QACZ,SAAS;QACT,UAAU;QACV,YAAY;QACZ,QAAQ;QACR,OAAO,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC;KACrC,CAAC;AACJ,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,iBAAiB;IAC/B,OAAO,OAAO,CAAC,QAAQ,EAAE,EAAE,MAAM,CAAC;AACpC,CAAC"}

package/dist/runtime/protocol.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Runtime protocol version.
+ *
+ * A long-lived daemon can outlive the clients that connect to it — a terminal
+ * opened yesterday, an editor extension pinned to an older release, a hook
+ * script from a previous install. Without an explicit protocol handshake those
+ * clients fail in confusing ways (a missing facade, a renamed action, a changed
+ * envelope) rather than saying "we disagree about the contract".
+ *
+ * This version describes the **runtime wire contract**: the shape of `/call`,
+ * `/batch`, `/health`, and the dispatch envelope. It is deliberately separate
+ * from the package version — most releases do not change the contract, and a
+ * client should not be forced to restart a healthy daemon just because a patch
+ * shipped.
+ *
+ * Bump MAJOR when an existing client would break: a removed or renamed
+ * endpoint, a changed request/response envelope, changed error semantics.
+ * Bump MINOR for backward-compatible additions (a new endpoint, a new optional
+ * field). Clients require an exact MAJOR match and tolerate any MINOR at or
+ * above their own.
+ */
+export declare const RUNTIME_PROTOCOL_VERSION = "1.1";
+/**
+ * 1.1 — adds `GET /mcp/tools?tier=`, serving MCP tool definitions verbatim.
+ *       Additive, so an older client is unaffected. A 1.1 CLIENT against a 1.0
+ *       runtime is not: the thin stdio adapter has no local kernel and cannot
+ *       answer tools/list without that endpoint. The minor-version rule
+ *       (server.minor >= client.minor) turns that into an actionable
+ *       "restart the runtime" at handshake time rather than a bare 404 on the
+ *       first request — which is exactly the confusion this file exists to
+ *       prevent, and which it caught the first time it was exercised for real.
+ * 1.0 — initial contract: /call, /batch, /health, dispatch envelope.
+ */
+export interface ParsedProtocolVersion {
+    major: number;
+    minor: number;
+}
+/** Parse `"1.0"` into `{major: 1, minor: 0}`. Returns null if malformed. */
+export declare function parseProtocolVersion(value: string): ParsedProtocolVersion | null;
+export type CompatibilityResult = {
+    compatible: true;
+} | {
+    compatible: false;
+    reason: string;
+};
+/**
+ * Is a runtime speaking `serverVersion` usable by a client requiring
+ * `clientVersion`?
+ *
+ * Rules:
+ *   - MAJOR must match exactly. A different major is a breaking contract change
+ *     in either direction, so we refuse rather than guess.
+ *   - The server's MINOR must be >= the client's. A newer server has every
+ *     endpoint an older client knows about (minor bumps are additive), but an
+ *     older server may be missing something the client depends on.
+ *
+ * An unparseable version is treated as incompatible. That is deliberate: a
+ * daemon that cannot state its protocol is a daemon we cannot reason about, and
+ * failing loudly beats dispatching into an unknown contract.
+ */
+export declare function isProtocolCompatible(serverVersion: string | undefined, clientVersion?: string): CompatibilityResult;
+//# sourceMappingURL=protocol.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/runtime/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAE9C;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAIhF;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,UAAU,EAAE,IAAI,CAAA;CAAE,GACpB;IAAE,UAAU,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,aAAa,GAAE,MAAiC,GAC/C,mBAAmB,CAiCrB"}

package/dist/runtime/protocol.js

@@ -0,0 +1,74 @@
+/**
+ * Runtime protocol version.
+ *
+ * A long-lived daemon can outlive the clients that connect to it — a terminal
+ * opened yesterday, an editor extension pinned to an older release, a hook
+ * script from a previous install. Without an explicit protocol handshake those
+ * clients fail in confusing ways (a missing facade, a renamed action, a changed
+ * envelope) rather than saying "we disagree about the contract".
+ *
+ * This version describes the **runtime wire contract**: the shape of `/call`,
+ * `/batch`, `/health`, and the dispatch envelope. It is deliberately separate
+ * from the package version — most releases do not change the contract, and a
+ * client should not be forced to restart a healthy daemon just because a patch
+ * shipped.
+ *
+ * Bump MAJOR when an existing client would break: a removed or renamed
+ * endpoint, a changed request/response envelope, changed error semantics.
+ * Bump MINOR for backward-compatible additions (a new endpoint, a new optional
+ * field). Clients require an exact MAJOR match and tolerate any MINOR at or
+ * above their own.
+ */
+export const RUNTIME_PROTOCOL_VERSION = '1.1';
+/** Parse `"1.0"` into `{major: 1, minor: 0}`. Returns null if malformed. */
+export function parseProtocolVersion(value) {
+    const match = /^(\d+)\.(\d+)$/.exec(value.trim());
+    if (!match)
+        return null;
+    return { major: Number(match[1]), minor: Number(match[2]) };
+}
+/**
+ * Is a runtime speaking `serverVersion` usable by a client requiring
+ * `clientVersion`?
+ *
+ * Rules:
+ *   - MAJOR must match exactly. A different major is a breaking contract change
+ *     in either direction, so we refuse rather than guess.
+ *   - The server's MINOR must be >= the client's. A newer server has every
+ *     endpoint an older client knows about (minor bumps are additive), but an
+ *     older server may be missing something the client depends on.
+ *
+ * An unparseable version is treated as incompatible. That is deliberate: a
+ * daemon that cannot state its protocol is a daemon we cannot reason about, and
+ * failing loudly beats dispatching into an unknown contract.
+ */
+export function isProtocolCompatible(serverVersion, clientVersion = RUNTIME_PROTOCOL_VERSION) {
+    if (!serverVersion) {
+        return {
+            compatible: false,
+            reason: 'runtime did not report a protocol_version (it predates protocol negotiation)',
+        };
+    }
+    const server = parseProtocolVersion(serverVersion);
+    const client = parseProtocolVersion(clientVersion);
+    if (!server) {
+        return { compatible: false, reason: `runtime reported an unparseable protocol_version "${serverVersion}"` };
+    }
+    if (!client) {
+        return { compatible: false, reason: `client requested an unparseable protocol version "${clientVersion}"` };
+    }
+    if (server.major !== client.major) {
+        return {
+            compatible: false,
+            reason: `runtime speaks protocol ${serverVersion}, client requires ${clientVersion} (major version mismatch)`,
+        };
+    }
+    if (server.minor < client.minor) {
+        return {
+            compatible: false,
+            reason: `runtime speaks protocol ${serverVersion}, client requires at least ${clientVersion} (runtime is older)`,
+        };
+    }
+    return { compatible: true };
+}
+//# sourceMappingURL=protocol.js.map

package/dist/runtime/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/runtime/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,CAAC;AAmB9C,4EAA4E;AAC5E,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9D,CAAC;AAMD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAClC,aAAiC,EACjC,gBAAwB,wBAAwB;IAEhD,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,OAAO;YACL,UAAU,EAAE,KAAK;YACjB,MAAM,EACJ,8EAA8E;SACjF,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,oBAAoB,CAAC,aAAa,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,oBAAoB,CAAC,aAAa,CAAC,CAAC;IAEnD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,qDAAqD,aAAa,GAAG,EAAE,CAAC;IAC9G,CAAC;IACD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,qDAAqD,aAAa,GAAG,EAAE,CAAC;IAC9G,CAAC;IAED,IAAI,MAAM,CAAC,KAAK,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC;QAClC,OAAO;YACL,UAAU,EAAE,KAAK;YACjB,MAAM,EAAE,2BAA2B,aAAa,qBAAqB,aAAa,2BAA2B;SAC9G,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;QAChC,OAAO;YACL,UAAU,EAAE,KAAK;YACjB,MAAM,EAAE,2BAA2B,aAAa,8BAA8B,aAAa,qBAAqB;SACjH,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;AAC9B,CAAC"}

package/dist/sentinelIssues.d.ts

@@ -1,5 +1,6 @@
-export type IssueStatus = 'open' | 'in_progress' | 'done' | 'blocked';
-export type IssuePriority = 'low' | 'medium' | 'high';
+import type { IssueSeverity, IssueStatus as CanonicalIssueStatus, IssuePriority as CanonicalIssuePriority } from './domain/issue.js';
+export type IssueStatus = CanonicalIssueStatus;
+export type IssuePriority = CanonicalIssuePriority;
 export interface SentinelIssue {
     id: string;
     title: string;
@@ -20,6 +21,8 @@ export interface CreateIssueInput {
     epicId?: string;
     priority?: IssuePriority;
     tags?: string[];
+    /** Optional. Defaults to 'med'. Distinct from priority — see createIssue. */
+    severity?: IssueSeverity;
 }
 export interface CreateIssueOutput extends SentinelIssue {
     filePath: string;
@@ -37,6 +40,27 @@ export declare function listIssuesForProject(projectId: string): Promise<Sentine
 /**
  * Create a new issue for a project
  */
+/**
+ * Create an issue.
+ *
+ * EPIC-0038 Phase 5: this used to be the second writer. It emitted `.yml` while
+ * the facade path (src/tools/sentinel.ts -> FsIssueRepository) emitted `.md`,
+ * into the same directory, from the same ISS-NNNN space. Converging the files
+ * while both writers ran would have left this one re-emitting `.yml` behind the
+ * migration — which is why the epic sequences behaviour before representation.
+ *
+ * So it now delegates. The name, the input contract and the return shape are
+ * all preserved; only the bytes on disk change. `SentinelIssue` is a subset of
+ * the canonical `Issue`, so the mapping back is total rather than lossy:
+ * `details` carries what this API calls `description`, and everything else is
+ * the same field under the same name.
+ *
+ * One field needs a decision rather than a mapping. This API has no `severity`
+ * and the canonical model wants one, so callers may now pass it and it defaults
+ * to 'med' — the neutral middle of ['low','med','high','critical'] — rather
+ * than inventing a severity from `priority`, which answers a different question
+ * (how bad it is, versus when it gets worked on).
+ */
 export declare function createIssue(input: CreateIssueInput): Promise<CreateIssueOutput>;
 /**
  * Get a single issue by ID (e.g., "ISS-0005") with full content