@decibelsystems/tools 2.2.0-beta.0 → 3.1.0

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,15 @@ export interface CreateIssueInput {
     epicId?: string;
     priority?: IssuePriority;
     tags?: string[];
+    /** Optional. Defaults to 'med'. Distinct from priority — see createIssue. */
+    severity?: IssueSeverity;
+    /**
+     * Who is working on it — EPIC-0040. A prefixed identity: user:<uuid>,
+     * agent:<uuid> or human:<name>. Rejected if it names a team.
+     */
+    assignee?: string;
+    /** Which team owns it — EPIC-0040. `team:<uuid>`, minted by HQ. */
+    team?: string;
 }
 export interface CreateIssueOutput extends SentinelIssue {
     filePath: string;
@@ -37,6 +47,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
@@ -49,6 +80,15 @@ export interface UpdateIssueInput {
     priority?: IssuePriority;
     tags?: string[];
     note?: string;
+    /**
+     * Reassign — EPIC-0040. A prefixed identity, or the empty string to
+     * UNASSIGN. The empty string is a deliberate part of the interface: without
+     * it there is no way to take an assignee off, and "leave it set forever" is
+     * not a reassignment model.
+     */
+    assignee?: string;
+    /** Move to another team, or the empty string to clear it. */
+    team?: string;
 }
 export interface UpdateIssueOutput extends SentinelIssue {
     filePath: string;

package/dist/sentinelIssues.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sentinelIssues.d.ts","sourceRoot":"","sources":["../src/sentinelIssues.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,aAAa,GAAG,MAAM,GAAG,SAAS,CAAC;AACtE,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAiDD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyBtE;AAMD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,EAAE,CAAC,CA2E1B;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,iBAAiB,CAAC,CA4E5B;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAa/B;AAMD,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,iBAAiB,CAAC,CAiG5B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EAAE,EACvB,MAAM,EAAE,WAAW,GAClB,aAAa,EAAE,CAEjB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EAAE,EACvB,MAAM,EAAE,MAAM,GACb,aAAa,EAAE,CAEjB"}
+{"version":3,"file":"sentinelIssues.d.ts","sourceRoot":"","sources":["../src/sentinelIssues.ts"],"names":[],"mappings":"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"}