iterate-plugin 3.5.3 → 3.5.5

package/dist/atomic-fs.js

@@ -48,12 +48,21 @@ function tempPathFor(filePath) {
  */
 export function writeTextAtomic(filePath, data) {
     const tmp = tempPathFor(filePath);
-    writeFileSync(tmp, data, 'utf-8');
+    try {
+        writeFileSync(tmp, data, 'utf-8');
+    }
+    catch (err) {
+        // The write itself failed (disk full, permission, …): the temp file may
+        // already be partially written, so remove it before propagating — a
+        // failed write must never litter the directory either.
+        cleanupTemp(tmp);
+        throw err;
+    }
     try {
         renameSync(tmp, filePath);
     }
     catch (err) {
-        // Best-effort temp cleanup so a failed write never litters the directory.
+        // Best-effort temp cleanup so a failed rename never litters the directory.
         cleanupTemp(tmp);
         throw err;
     }
@@ -61,12 +70,21 @@ export function writeTextAtomic(filePath, data) {
 /** Async variant of {@link writeTextAtomic} (same temp naming convention). */
 export async function writeTextAtomicAsync(filePath, data) {
     const tmp = tempPathFor(filePath);
-    await writeFile(tmp, data, 'utf-8');
+    try {
+        await writeFile(tmp, data, 'utf-8');
+    }
+    catch (err) {
+        // The write itself failed (disk full, permission, …): the temp file may
+        // already be partially written, so remove it before propagating — a
+        // failed write must never litter the directory either.
+        await cleanupTempAsync(tmp);
+        throw err;
+    }
     try {
         await rename(tmp, filePath);
     }
     catch (err) {
-        // Best-effort temp cleanup so a failed write never litters the directory.
+        // Best-effort temp cleanup so a failed rename never litters the directory.
         await cleanupTempAsync(tmp);
         throw err;
     }

package/dist/config-loader.js

@@ -10,7 +10,10 @@ export function loadConfig(projectRoot) {
     try {
         const content = readFileSync(join(projectRoot, 'iterate.config.yaml'), 'utf-8');
         const parsed = yaml.load(content);
-        if (!parsed || typeof parsed !== 'object')
+        // A YAML sequence root (e.g. a list of findings or a `- foo` file) must
+        // not masquerade as a config object — treating it as one would merge its
+        // indices into the config (config bomb). Reject it, not coerce it.
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
             return null;
         return parsed;
     }
@@ -141,7 +144,7 @@ export function flattenCommands(commands) {
  */
 export function validateConfig(config) {
     const errors = [];
-    if (!config || typeof config !== 'object') {
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
         errors.push('root');
         return errors;
     }
@@ -190,7 +193,9 @@ export function validateConfig(config) {
  *      the DSH runtime injects per-session env into tool sub-processes).
  */
 export function resolveProjectRoot(input, sessionCwd) {
-    const raw = (input ?? '').trim();
+    // A non-string input (number, array, …) from a hostile tool invocation must
+    // be treated as "no explicit path" instead of crashing on `.trim()`.
+    const raw = (typeof input === 'string' ? input : '').trim();
     // A NUL byte can never name a real path and makes `resolve()` (and every
     // downstream fs call) throw — treat it as unsafe input, not a throw path.
     if (raw.includes('\0')) {

package/dist/config-write.js

@@ -9,8 +9,8 @@
  * The security posture mirrors the triage tool: never overwrite a malformed
  * config, always back up before writing, roll back on failure.
  */
-import { copyFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
+import { copyFileSync, existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 import yaml from 'js-yaml';
 import { writeTextAtomic } from "./atomic-fs.js";
 /** Config file name (must match config-loader). */
@@ -19,6 +19,39 @@ export const CONFIG_FILE = 'iterate.config.yaml';
 export function configBackupSuffix(now = new Date()) {
     return now.toISOString().replace(/[:.]/g, '-');
 }
+/** Upper bound on configurable iteration rounds (config bomb guard). */
+export const MAX_MAX_ROUNDS = 100;
+/** Upper bound on `atomic.max_lines` (a single fix never needs more). */
+export const MAX_ATOMIC_MAX_LINES = 10_000;
+/** Upper bound on `atomic.max_adjacent_methods`. */
+export const MAX_MAX_ADJACENT_METHODS = 200;
+/** Keep at most this many timestamped config backups (older ones are removed). */
+export const MAX_CONFIG_BACKUPS = 5;
+/**
+ * Bound the timestamped config backups: after a fresh one is written, delete
+ * every older `config.bak-*` file beyond the newest `keep`. Best-effort — a
+ * filesystem failure here must never fail the write that just succeeded.
+ * @returns the absolute paths of the backups that were removed.
+ */
+export function pruneOldConfigBackups(configPath, keep = MAX_CONFIG_BACKUPS) {
+    const removed = [];
+    try {
+        const dir = dirname(configPath);
+        const prefix = `${basename(configPath)}.bak-`;
+        const matches = existsSync(dir)
+            ? readdirSync(dir).filter((f) => f.startsWith(prefix)).sort()
+            : [];
+        const doomed = matches.slice(0, Math.max(0, matches.length - keep));
+        for (const f of doomed) {
+            rmSync(join(dir, f), { force: true });
+            removed.push(join(dir, f));
+        }
+    }
+    catch {
+        // Best-effort cleanup — never surface a cleanup failure.
+    }
+    return removed;
+}
 /**
  * Validate a partial config update.
  * Returns an array of error strings (empty when the update is valid).
@@ -40,8 +73,9 @@ export function validateConfigUpdates(updates) {
         }
     }
     if ('max_rounds' in updates) {
-        if (typeof updates.max_rounds !== 'number' || !Number.isInteger(updates.max_rounds) || updates.max_rounds < 1) {
-            errors.push('updates.max_rounds must be a positive integer');
+        if (typeof updates.max_rounds !== 'number' || !Number.isInteger(updates.max_rounds) ||
+            updates.max_rounds < 1 || updates.max_rounds > MAX_MAX_ROUNDS) {
+            errors.push(`updates.max_rounds must be an integer between 1 and ${MAX_MAX_ROUNDS}`);
         }
     }
     if ('review' in updates) {
@@ -59,11 +93,11 @@ export function validateConfigUpdates(updates) {
             errors.push('updates.atomic must be an object');
         }
         else {
-            if (a.max_lines !== undefined && (typeof a.max_lines !== 'number' || !Number.isInteger(a.max_lines) || a.max_lines < 1)) {
-                errors.push('updates.atomic.max_lines must be a positive integer');
+            if (a.max_lines !== undefined && (typeof a.max_lines !== 'number' || !Number.isInteger(a.max_lines) || a.max_lines < 1 || a.max_lines > MAX_ATOMIC_MAX_LINES)) {
+                errors.push(`updates.atomic.max_lines must be an integer between 1 and ${MAX_ATOMIC_MAX_LINES}`);
             }
-            if (a.max_adjacent_methods !== undefined && (typeof a.max_adjacent_methods !== 'number' || a.max_adjacent_methods < 0)) {
-                errors.push('updates.atomic.max_adjacent_methods must be a non-negative number');
+            if (a.max_adjacent_methods !== undefined && (typeof a.max_adjacent_methods !== 'number' || a.max_adjacent_methods < 0 || a.max_adjacent_methods > MAX_MAX_ADJACENT_METHODS)) {
+                errors.push(`updates.atomic.max_adjacent_methods must be a number between 0 and ${MAX_MAX_ADJACENT_METHODS}`);
             }
         }
     }
@@ -164,7 +198,10 @@ export function readRawConfig(configPath) {
     catch {
         throw new Error('existing iterate.config.yaml is not a valid YAML mapping');
     }
-    if (!parsed || typeof parsed !== 'object') {
+    // A YAML sequence root (array) must not masquerade as a config object —
+    // `typeof [] === 'object'`, so the presence check alone would accept a
+    // config file that is actually a list. Writing over it would destroy data.
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
         throw new Error('existing iterate.config.yaml is not a valid YAML mapping');
     }
     return parsed;
@@ -201,5 +238,9 @@ export function writeConfigFile(projectRoot, config) {
         }
         return { ok: false, error: `failed to write config: ${String(err)}${rollbackError}` };
     }
+    // Success: bound the accumulation of timestamped backups so a long-lived
+    // project never collects an unbounded pile of config snapshots.
+    if (backupPath)
+        pruneOldConfigBackups(configPath);
     return { ok: true, backupPath };
 }

package/dist/evidence.js

@@ -89,8 +89,35 @@ export function verifyLineBounds(line, text) {
 }
 /** Verify a single finding's location against the real filesystem. */
 export function verifyFinding(root, input, opts = {}) {
-    const relFile = input.file ?? '';
+    // A null element / non-object finding (hostile or model-authored JSON) must
+    // be reported as poisoned evidence, never crash `path.resolve` downstream.
+    if (!input || typeof input !== 'object') {
+        return {
+            file: '',
+            line: null,
+            lineTotal: null,
+            resolvedPath: null,
+            verified: false,
+            error: 'file_not_found',
+        };
+    }
+    // A non-string `file` (number, object, …) would make `resolve` throw
+    // ERR_INVALID_ARG_TYPE — coerce to "" so it fails closed as not-found.
+    const relFile = typeof input.file === 'string' ? input.file : '';
     const line = typeof input.line === 'number' ? input.line : null;
+    // "" resolves to the project ROOT (resolve(root, '') === root), which then
+    // trips the not-a-regular-file branch as `line_out_of_range` — but there is
+    // no file reference at all. Report it as `file_not_found` upfront.
+    if (relFile === '') {
+        return {
+            file: '',
+            line,
+            lineTotal: null,
+            resolvedPath: null,
+            verified: false,
+            error: 'file_not_found',
+        };
+    }
     const resolved = resolveWithin(root, relFile);
     if (resolved === null || !existsSync(resolved)) {
         return {

package/dist/git-scope.js

@@ -89,7 +89,10 @@ function decodeQuotedPath(content) {
 }
 export function parseChangedFiles(stdout) {
     if (stdout.includes('\0')) {
-        return stdout.split('\0').map((s) => s.trim()).filter((s) => s.length > 0);
+        // NUL mode: git emits exact names with no surrounding whitespace, so any
+        // trim would CORRUPT a filename that legitimately starts/ends with spaces
+        // (git supports such names). Split and drop only the trailing empty entry.
+        return stdout.split('\0').filter((s) => s.length > 0);
     }
     return stdout
         .split('\n')
@@ -147,9 +150,15 @@ export function decideScope(changedFiles) {
  * Uses execFile (no shell), so a model-controlled branch name can never be
  * interpreted as shell syntax.
  */
-export function runGit(args, cwd) {
+export function runGit(args, cwd, opts = {}) {
     return new Promise((resolve) => {
-        execFile('git', args, { cwd, timeout: 30_000, maxBuffer: 10 * 1024 * 1024, env: { ...process.env, PAGER: 'cat' } }, (error, stdout, stderr) => {
+        execFile('git', args, {
+            cwd,
+            timeout: 30_000,
+            maxBuffer: 10 * 1024 * 1024,
+            env: { ...process.env, PAGER: 'cat' },
+            signal: opts.signal,
+        }, (error, stdout, stderr) => {
             const exitCode = error ? (typeof error.code === 'number' ? error.code : 1) : 0;
             resolve({ ok: exitCode === 0, stdout: stdout ?? '', stderr: stderr ?? '', exitCode });
         });
@@ -161,7 +170,7 @@ export function runGit(args, cwd) {
  * `full`-scope result with `error` set — the reviewer must never crash the
  * plan because git is unavailable.
  */
-export async function resolveChangedFiles(root, targetBranch) {
+export async function resolveChangedFiles(root, targetBranch, opts = {}) {
     // Option-injection guard: a branch name starting with '-' would be parsed by
     // git as an option (e.g. --output=...), not a ref. Reject it outright.
     if (typeof targetBranch !== 'string' || targetBranch.trim() === '' || targetBranch.startsWith('-')) {
@@ -174,7 +183,7 @@ export async function resolveChangedFiles(root, targetBranch) {
     }
     // -z: NUL-delimited names — machine-safe for any filename (spaces, quotes,
     // non-ASCII), and never confused with option-like content.
-    const { ok, stdout, stderr } = await runGit(['diff', '--name-only', '-z', targetBranch, '--'], root);
+    const { ok, stdout, stderr } = await runGit(['diff', '--name-only', '-z', targetBranch, '--'], root, opts);
     if (!ok) {
         const reason = stderr.trim() || `git diff --name-only -z ${targetBranch} failed`;
         return { scope: 'full', changedFiles: [], fallbackToFull: true, error: reason };

package/dist/jobs.js

@@ -16,6 +16,20 @@
  * - The registry is memory-only and panel rows are read-only (no progress
  *   updates), so these jobs are completion records, not control channels.
  */
+/**
+ * Read `ctx.jobs` defensively: the dsh plugin context can be a Proxy whose
+ * `jobs` getter throws (or is missing) when no job registry is present. A
+ * Proxy throw on property access must degrade to "no jobs", never crash the
+ * tool execution we are about to wrap.
+ */
+function safeJobs(ctx) {
+    try {
+        return ctx?.jobs;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Run `fn` wrapped in a dsh background job, settling it completed/failed
  * with the execution's outcome. When the host exposes no job registry (or
@@ -29,7 +43,7 @@
  * @returns the registry-issued job id, or `null` when unavailable.
  */
 export async function runWithJob(ctx, kind, label, fn) {
-    const jobs = ctx?.jobs;
+    const jobs = safeJobs(ctx);
     if (!jobs || typeof jobs.start !== 'function') {
         return { result: await fn(), jobId: null };
     }

package/dist/live.js

@@ -36,6 +36,45 @@ export const LIVE_MAX_BYTES = 64 * 1024;
 export function liveFilePath(projectRoot) {
     return join(projectRoot, '.iterate', 'transcript-live.ndjson');
 }
+/**
+ * Module-level in-process queue serializing live-feed writes. The trim path
+ * (read → rewrite → append) is a read-modify-write: two concurrent tool
+ * results could interleave and one's rewrite would silently drop the other's
+ * freshly-appended line. Chaining every append onto one tail makes the whole
+ * read+rewrite+append atomic within the process (the only realistic mode for
+ * the plugin); cross-process racing remains a theoretical hazard, but the
+ * cap-trim makes a lost line a cosmetic issue, not a correctness one.
+ */
+let liveWriteQueue = Promise.resolve();
+function enqueueLiveWrite(task) {
+    const next = liveWriteQueue.then(task, task);
+    liveWriteQueue = next.catch(() => { });
+    return next;
+}
+/** Append one activity record to the project's live feed (byte-capped). */
+export function appendLive(projectRoot, entry) {
+    return enqueueLiveWrite(async () => {
+        const file = liveFilePath(projectRoot);
+        const line = JSON.stringify(entry) + '\n';
+        await mkdir(join(projectRoot, '.iterate'), { recursive: true });
+        // Amortized O(1): only read+rewrite when the file has grown past the cap.
+        try {
+            const st = await stat(file).catch(() => null);
+            if (st && st.size > LIVE_MAX_BYTES) {
+                const raw = await readFile(file, 'utf-8');
+                const lines = raw.split('\n').filter(Boolean);
+                const tail = lines.slice(-LIVE_MAX_ENTRIES);
+                // Atomic rewrite (unique temp + rename) so a crash mid-trim never
+                // truncates the live feed; the temp file is prunable by iterate_prune.
+                await writeTextAtomicAsync(file, tail.join('\n') + '\n');
+            }
+            await appendFile(file, line, 'utf-8');
+        }
+        catch {
+            // Fire-and-forget: never let live capture break a tool call.
+        }
+    });
+}
 /** Resolve the project root a tool execution belongs to, if any. */
 function projectRootOf(exec) {
     const cwd = exec.agent?.session?.header?.cwd;
@@ -95,28 +134,6 @@ export function classifyTool(name, args, projectRoot) {
         target = name;
     return { ts: new Date().toISOString(), type, tool: name, target };
 }
-/** Append one activity record to the project's live feed (byte-capped). */
-export async function appendLive(projectRoot, entry) {
-    const file = liveFilePath(projectRoot);
-    const line = JSON.stringify(entry) + '\n';
-    await mkdir(join(projectRoot, '.iterate'), { recursive: true });
-    // Amortized O(1): only read+rewrite when the file has grown past the cap.
-    try {
-        const st = await stat(file).catch(() => null);
-        if (st && st.size > LIVE_MAX_BYTES) {
-            const raw = await readFile(file, 'utf-8');
-            const lines = raw.split('\n').filter(Boolean);
-            const tail = lines.slice(-LIVE_MAX_ENTRIES);
-            // Atomic rewrite (unique temp + rename) so a crash mid-trim never
-            // truncates the live feed; the temp file is prunable by iterate_prune.
-            await writeTextAtomicAsync(file, tail.join('\n') + '\n');
-        }
-        await appendFile(file, line, 'utf-8');
-    }
-    catch {
-        // Fire-and-forget: never let live capture break a tool call.
-    }
-}
 /** Read the live feed (newest first), capped at the last LIVE_MAX_ENTRIES. */
 export async function readLive(projectRoot) {
     const file = liveFilePath(projectRoot);

package/dist/meta-review.js

@@ -99,7 +99,7 @@ export function metaReviewReport(report) {
     if (dimSum !== total) {
         add('DIMENSION_SUM', 'high', 'byDimension counts do not sum to totalFindings', `byDimension sums to ${dimSum}, but totalFindings is ${total}.`);
     }
-    const invalidDim = findings.find((f) => !dimensions.includes(f?.dimension));
+    const invalidDim = findings.find((f) => !!f && !dimensions.includes(f?.dimension));
     if (invalidDim) {
         add('DIMENSION_UNKNOWN', 'medium', `Finding references unknown dimension "${invalidDim.dimension}"`, `dimension "${invalidDim.dimension}" is not in report.dimensions ` +
             `(${dimensions.join(', ') || 'none'}).`);
@@ -227,7 +227,7 @@ export function buildFinalReviewReport(report, opts = {}) {
                     // Try to attribute the poisoned finding to the round that first
                     // surfaced it (best-effort; report rounds carry it).
                     for (const r of report.rounds ?? []) {
-                        const matched = (r.findings ?? []).some((fnd) => fnd.file === violation.file && fnd.line === violation.line);
+                        const matched = (r.findings ?? []).some((fnd) => !!fnd && fnd?.file === violation.file && fnd?.line === violation.line);
                         if (matched) {
                             roundHint = ` (round ${r.round})`;
                             break;

package/dist/review-scope.js

@@ -57,10 +57,14 @@ function normalizePath(path) {
         if (part === '' || part === '.')
             continue;
         if (part === '..') {
-            if (parts.length > 0)
+            // Mirrors Python `os.path.normpath`: a leading `..` is preserved and a
+            // second `..` is NEVER collapsed into a bare `/` away — otherwise a
+            // traversal like `../../evil` folds into the single segment `evil` and
+            // the escape becomes undetectable downstream.
+            if (parts.length > 0 && parts[parts.length - 1] !== '..')
                 parts.pop();
             else
-                parts.push(part); // no root segment to pop — keep the leading '..'
+                parts.push(part);
             continue;
         }
         parts.push(part);

package/dist/review.js

@@ -28,19 +28,20 @@ export const SEVERITY_RANK = {
 export function sortFindings(findings) {
     return [...findings].sort((a, b) => {
         // Guard against an out-of-spec severity string (e.g. from a model that
-        // bypassed the schema): treat it as the least severe so NaN never enters
-        // the comparator and ordering stays deterministic.
-        const rankA = SEVERITY_RANK[a.severity] ?? SEVERITY_RANK.low;
-        const rankB = SEVERITY_RANK[b.severity] ?? SEVERITY_RANK.low;
+        // bypassed the schema) AND against a null list element (model-authored
+        // JSON): treat both as the least severe so NaN never enters the
+        // comparator and ordering stays deterministic.
+        const rankA = SEVERITY_RANK[a?.severity] ?? SEVERITY_RANK.low;
+        const rankB = SEVERITY_RANK[b?.severity] ?? SEVERITY_RANK.low;
         const bySeverity = rankA - rankB;
         if (bySeverity !== 0)
             return bySeverity;
         // Defensive coercion: `file`/`line` can be wrong-typed when schema
         // validation is disabled — String()/Number() keep the comparator total.
-        const byFile = String(a.file ?? '').localeCompare(String(b.file ?? ''));
+        const byFile = String(a?.file ?? '').localeCompare(String(b?.file ?? ''));
         if (byFile !== 0)
             return byFile;
-        return (Number(a.line) || 0) - (Number(b.line) || 0);
+        return (Number(a?.line) || 0) - (Number(b?.line) || 0);
     });
 }
 /** Normalize a summary so near-identical duplicates collapse to one key. */

package/dist/session-hooks.js

@@ -7,12 +7,22 @@
  *
  *   - `allow` policy      → the call runs.
  *   - `deny`  policy      → the call is refused (fail-closed), surfaced as an
- *                           error to the model.
+ *                           error to the model. Since dsh 0.1.6-alpha.1 the
+ *                           denial carries a structured `info` (name
+ *                           `iterate-approval-gate`, code `APPROVAL_DENIED`,
+ *                           plus the human-readable reason) so durable
+ *                           projections can route it distinctly from a normal
+ *                           tool failure.
  *   - `ask`   policy      → return `{ kind: 'ask', reason }`; dsh's own
  *                           scheduler routes it through the `approval` service
  *                           (see `@deepseek-ai/dsh-user-approval`), which
  *                           prompts the human and audits an approve/deny pair
  *                           on the session.
+ *   - canceled            → if the caller aborted the invocation before
+ *                           dispatch, return `{ kind: 'cancel' }` (the
+ *                           canonical 0.1.6-alpha.1 cancellation result) so a
+ *                           destructive call never runs (or asks) for a dead
+ *                           request.
  *
  * We deliberately do NOT also add `approved` flags inside the tool bodies:
  * the pre-execute waterfall consumes the human decision before the tool runs,
@@ -27,6 +37,13 @@
  */
 import { loadEffectiveConfig, resolveProjectRoot } from "./config-loader.js";
 import { decideApproval, isDestructiveIterateTool } from "./approval-gate.js";
+/** Structured error identity attached to policy denials (dsh 0.1.6-alpha.1:
+ *  `deny.info` lets durable projections / retry / replay distinguish an
+ *  approval-policy denial from a tool-thrown failure). */
+const DENY_INFO = {
+    name: 'iterate-approval-gate',
+    code: 'APPROVAL_DENIED',
+};
 /**
  * Build the per-call approval decision for a tool execution.
  * Returns a dsh `PreToolDecision` so the caller can short-circuit the caller.
@@ -46,6 +63,20 @@ export function gateDecision(exec) {
     }
     if (!isDestructiveIterateTool(name))
         return { kind: 'allow' };
+    // dsh 0.1.6-alpha.1: if the caller already aborted this invocation before
+    // dispatch, there is nothing to gate — select the canonical cancellation
+    // result (`cancel`) rather than prompting a human for a dead call or running
+    // `next()` (which would allow) on an aborted one.
+    let signal;
+    try {
+        signal = exec.signal;
+    }
+    catch {
+        signal = undefined;
+    }
+    if (signal && typeof signal.aborted === 'boolean' && signal.aborted) {
+        return { kind: 'cancel' };
+    }
     // Resolve the project root (use the call's own `path` arg, else the agent's
     // session cwd) to read the effective observatory policy.
     let argPath;
@@ -74,8 +105,18 @@ export function gateDecision(exec) {
         // anything else (including a corrupt/missing `ask`) → 'ask'
     }
     const decision = decideApproval(exec, policy);
-    if (decision.kind === 'deny')
-        return { kind: 'deny', reason: decision.reason };
+    if (decision.kind === 'deny') {
+        return {
+            kind: 'deny',
+            reason: decision.reason,
+            info: {
+                ...DENY_INFO,
+                // ToolErrorInfo.reason (0.1.6-alpha.1): raw user-facing detail kept in
+                // durable state; the model-facing text still only sees `reason` above.
+                reason: decision.reason,
+            },
+        };
+    }
     if (decision.kind === 'ask')
         return { kind: 'ask', reason: decision.reason };
     return { kind: 'allow' };
@@ -106,7 +147,10 @@ export function registerSessionHooks(ctx) {
             // to allow, which would bypass consent — so return our ask decision.
             return Promise.resolve(decision);
         }
-        if (decision.kind === 'deny') {
+        if (decision.kind === 'deny' || decision.kind === 'cancel') {
+            // deny: refuse the call. cancel: the caller already aborted this
+            // invocation — selecting the canonical cancellation result instead of
+            // letting `next()` allow it or prompting consent for a dead request.
             return Promise.resolve(decision);
         }
         return next();