@ngockhoale/ukit 3.0.12 → 3.1.1

package/template_project/.claude/ukit/index/sidecar-decision.mjs

@@ -0,0 +1,595 @@
+#!/usr/bin/env node
+/**
+ * sidecar-decision.mjs (UNIC_DECISION_MIGRATION slice S3)
+ *
+ * Installed-side producer for the six bounded sidecar decisions enumerated in
+ * `.codex/settings.json` `smallTaskModel.decisionPolicy.decisions`. Each
+ * decision maps to a registered `workflow.*` key in src/decision/registry.js
+ * (owner: smallTaskMaintainer, fallbackPolicy: deterministic-*).
+ *
+ * Stage contract — `decisionPlane.families.workflow.stage` (family override
+ * wins over the global decisionPlane.stage; absent/malformed → 'off';
+ * decisionPlane.enabled === false → 'off'):
+ *   off              → deterministic rule answer, zero transport.
+ *   shadow           → unic-decision batch is advisory; deterministic rule
+ *                      stays authoritative (agreement reported).
+ *   canary/default   → a valid unic-decision answer wins; invalid or
+ *                      unavailable falls back to the deterministic rule.
+ *
+ * Transport is delegated to the sibling `unic-decision.mjs` CLI (spawned once
+ * with a bounded single-question batch on stdin). That adapter owns protocol
+ * encode/parse, gateway resolution, and the sensitive-value gate — this file
+ * never duplicates it. Any adapter failure resolves to the deterministic
+ * answer with outcomeClass 'unavailable' — NEVER another LLM for the verdict.
+ * unic-lite keeps summarization/doc work only; it emits no verdicts here.
+ *
+ * Verdict inputs are already-extracted, whitelisted context fields — no raw
+ * diffs, transcripts, or secrets cross the transport (statePacket whitelist).
+ *
+ * Modes:
+ *   node sidecar-decision.mjs --list                 print the name → key table
+ *   node sidecar-decision.mjs --fixture <path>       offline replay passthrough
+ *                                                    to unic-decision.mjs
+ *   node sidecar-decision.mjs --decision <name>      reads optional context JSON
+ *     [--root <dir>]                                 on stdin ({context:{...}}
+ *                                                    or bare fields); prints
+ *                                                    the typed result.
+ *
+ * Exit codes: 0 for every typed outcome (deterministic, accepted, unavailable
+ * — the JSON fields carry the truth); 1 only for usage errors or malformed
+ * stdin JSON. Never throws.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __sidecarDir = path.dirname(fileURLToPath(import.meta.url));
+const UNIC_DECISION_CLI_PATH = path.join(__sidecarDir, 'unic-decision.mjs');
+const ADAPTER_TIMEOUT_CAP_MS = 3000;
+
+// ---------------------------------------------------------------------------
+// Decision catalog — the name → workflow.* key mapping lives HERE (not in
+// .codex/settings.json) so the settings file keeps its existing schema. Each
+// entry mirrors its DECISION_REGISTRY row: decisionKey, choice candidates as
+// protocol-local labels, fallbackPolicy, and the deterministic rule that stays
+// authoritative at stage 'off' / 'shadow' / adapter-failure.
+// ---------------------------------------------------------------------------
+
+// Shared/security/irreversible path signals — a match forces 'risky' (and the
+// lane decision biases 'slow'). Token scan over normalized path segments.
+const RISKY_PATH_TOKENS = new Set([
+  'src', '.github', 'workflows', 'release', 'scripts', 'migrations',
+  'secrets', '.env', 'auth', 'security', 'package.json', 'yarn.lock',
+  'package-lock.json', 'pnpm-lock.yaml',
+]);
+
+function normalizedPathTokens(targetPath) {
+  if (typeof targetPath !== 'string' || targetPath.length === 0) return [];
+  return targetPath
+    .split(/[\\/]+/)
+    .map((segment) => segment.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function targetIsRisky(context) {
+  for (const token of normalizedPathTokens(context?.targetPath)) {
+    if (RISKY_PATH_TOKENS.has(token)) return true;
+  }
+  return false;
+}
+
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+export const SIDECAR_DECISIONS = Object.freeze({
+  'fast-vs-slow-lane': {
+    decisionKey: 'workflow.sidecar-lane.v1',
+    fallbackPolicy: 'deterministic-lane-rules',
+    question: {
+      decisionKey: 'workflow.sidecar-lane.v1',
+      kind: 'choice',
+      instruction:
+        'Chore lane: fast (single reversible step on local state) | slow (needs main-model review).',
+      candidates: ['fast', 'slow'],
+    },
+    contextFields: ['targetPath', 'riskLevel', 'riskSignal', 'stepsUsed', 'maxSteps'],
+    // Deterministic rule: any risky/shared-path signal or explicit high risk
+    // escalates to the slow lane; everything else stays fast.
+    decide(context) {
+      if (targetIsRisky(context) || context.riskLevel === 'high' || context.riskSignal === true) {
+        return 'slow';
+      }
+      return 'fast';
+    },
+  },
+  'safe-vs-risky-lane': {
+    decisionKey: 'workflow.sidecar-risk.v1',
+    fallbackPolicy: 'deterministic-lane-rules',
+    question: {
+      decisionKey: 'workflow.sidecar-risk.v1',
+      kind: 'choice',
+      instruction:
+        'Risk class for the sidecar candidate: safe (reversible local state) | risky (escalate to main model).',
+      candidates: ['safe', 'risky'],
+    },
+    contextFields: ['targetPath', 'riskLevel', 'riskSignal', 'irreversible'],
+    // Deterministic rule: risky when the target matches shared/security/
+    // irreversible paths or an explicit risk/irreversibility signal is set;
+    // otherwise safe.
+    decide(context) {
+      if (
+        targetIsRisky(context)
+        || context.riskSignal === true
+        || context.irreversible === true
+        || context.riskLevel === 'high'
+      ) {
+        return 'risky';
+      }
+      return 'safe';
+    },
+  },
+  'skill-routing-needed': {
+    decisionKey: 'workflow.routing-needed.v1',
+    fallbackPolicy: 'deterministic-route',
+    question: {
+      decisionKey: 'workflow.routing-needed.v1',
+      kind: 'choice',
+      instruction:
+        'Does this prompt still need routing/intent classification: needed | skip.',
+      candidates: ['needed', 'skip'],
+    },
+    contextFields: ['routingNeeded', 'resolution'],
+    // Deterministic rule: an existing route resolution (or routingNeeded=false)
+    // skips; otherwise routing is needed.
+    decide(context) {
+      if (context.routingNeeded === false) return 'skip';
+      if (typeof context.resolution === 'string' && context.resolution.length > 0) return 'skip';
+      return 'needed';
+    },
+  },
+  'step-budget-enough': {
+    decisionKey: 'workflow.step-budget.v1',
+    fallbackPolicy: 'deterministic-budget',
+    question: {
+      decisionKey: 'workflow.step-budget.v1',
+      kind: 'choice',
+      instruction:
+        'Is the remaining planned step budget enough for this task: enough | exceeds.',
+      candidates: ['enough', 'exceeds'],
+    },
+    contextFields: ['stepsUsed', 'maxSteps'],
+    // Deterministic rule: when both counters are present, at/over the budget
+    // means it exceeds; missing counters default to enough (no fake precision).
+    decide(context) {
+      if (isFiniteNumber(context.stepsUsed) && isFiniteNumber(context.maxSteps)) {
+        return context.stepsUsed >= context.maxSteps ? 'exceeds' : 'enough';
+      }
+      return 'enough';
+    },
+  },
+  'compact-now-or-later': {
+    decisionKey: 'workflow.compact-now.v1',
+    fallbackPolicy: 'deterministic-threshold',
+    question: {
+      decisionKey: 'workflow.compact-now.v1',
+      kind: 'choice',
+      instruction:
+        'Context hygiene at this boundary: compact-now | compact-later.',
+      candidates: ['compact-now', 'compact-later'],
+    },
+    contextFields: ['lineCount', 'tokenCount', 'budgetTokens', 'compactTargetMax'],
+    // Deterministic rule: compact now when the observed size crosses the
+    // configured hard limits — lineCount at/over compactTargetMax (default 170)
+    // or tokenCount at/over 90% of budgetTokens (default 100000).
+    decide(context) {
+      const targetMax = isFiniteNumber(context.compactTargetMax) ? context.compactTargetMax : 170;
+      const budget = isFiniteNumber(context.budgetTokens) ? context.budgetTokens : 100000;
+      if (isFiniteNumber(context.lineCount) && context.lineCount >= targetMax) return 'compact-now';
+      if (isFiniteNumber(context.tokenCount) && context.tokenCount >= budget * 0.9) {
+        return 'compact-now';
+      }
+      return 'compact-later';
+    },
+  },
+  'summarize-docs-or-keep-detail': {
+    decisionKey: 'workflow.summarize-vs-keep.v1',
+    fallbackPolicy: 'deterministic-threshold',
+    question: {
+      decisionKey: 'workflow.summarize-vs-keep.v1',
+      kind: 'choice',
+      instruction:
+        'Stored artifact/doc handling: summarize | keep-detail.',
+      candidates: ['summarize', 'keep-detail'],
+    },
+    contextFields: ['docLength', 'lineCount', 'preserveDetail'],
+    // Deterministic rule: an explicit preserve flag keeps detail; long docs
+    // (docLength/lineCount >= 200) summarize; anything else keeps detail
+    // (prefer no-op over lossy cleanup).
+    decide(context) {
+      if (context.preserveDetail === true) return 'keep-detail';
+      const length = isFiniteNumber(context.docLength) ? context.docLength
+        : isFiniteNumber(context.lineCount) ? context.lineCount
+          : 0;
+      return length >= 200 ? 'summarize' : 'keep-detail';
+    },
+  },
+});
+
+const SIDECAR_FAMILY = 'workflow';
+const DECISION_STAGES = new Set(['off', 'shadow', 'canary', 'default']);
+
+// ---------------------------------------------------------------------------
+// Runtime config + stage resolution — mirror of route-task.mjs
+// resolveDecisionPlaneStage/resolveDecisionFamilyStage (absent/malformed →
+// 'off'; enabled === false → 'off'; family override wins over global stage).
+// ---------------------------------------------------------------------------
+
+function safeReadJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeConfigObjects(base, override) {
+  if (!isPlainObject(base)) return isPlainObject(override) ? { ...override } : {};
+  if (!isPlainObject(override)) return { ...base };
+  const out = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') continue;
+    out[key] = isPlainObject(value) && isPlainObject(base[key])
+      ? mergeConfigObjects(base[key], value)
+      : value;
+  }
+  return out;
+}
+
+function readMergedConfig(rootDir, homeDir) {
+  const projectRaw = rootDir
+    ? safeReadJson(path.join(rootDir, '.ukit', 'storage', 'config.json'))
+    : null;
+  const userRaw = safeReadJson(
+    path.join(homeDir ?? os.homedir(), '.ukit', 'storage', 'config.json'),
+  );
+  return mergeConfigObjects(userRaw ?? {}, projectRaw ?? {});
+}
+
+export function resolveSidecarStage(config = null) {
+  const plane = config?.decisionPlane;
+  if (!plane || typeof plane !== 'object' || plane.enabled === false) return 'off';
+  const globalStage = DECISION_STAGES.has(plane.stage) ? plane.stage : 'off';
+  const override = plane?.families?.[SIDECAR_FAMILY]?.stage;
+  return DECISION_STAGES.has(override) ? override : globalStage;
+}
+
+// ---------------------------------------------------------------------------
+// State packet — whitelisted fields only (per-decision contextFields). Strings
+// are truncated; non-finite numbers and unknown keys are dropped before they
+// can reach the transport.
+// ---------------------------------------------------------------------------
+
+const MAX_FIELD_LENGTH = 200;
+
+export function buildStatePacket(decision, context) {
+  const spec = SIDECAR_DECISIONS[decision];
+  const fields = spec?.contextFields ?? [];
+  const packet = { stateVersion: 1, boundary: 'sidecar', decision };
+  for (const field of fields) {
+    const value = context?.[field];
+    if (typeof value === 'string' && value.length > 0) {
+      packet[field] = value.slice(0, MAX_FIELD_LENGTH);
+    } else if (isFiniteNumber(value)) {
+      packet[field] = value;
+    } else if (typeof value === 'boolean') {
+      packet[field] = value;
+    }
+  }
+  return packet;
+}
+
+// ---------------------------------------------------------------------------
+// Adapter spawn — one bounded single-question batch to unic-decision.mjs.
+// Never throws: every failure resolves to a typed 'unavailable' result.
+// ---------------------------------------------------------------------------
+
+function runAdapterBatch({ spec, context, rootDir, config, batchId }) {
+  const cliPath = process.env.UKIT_DECISION_CLI_PATH || UNIC_DECISION_CLI_PATH;
+  const timeoutMs = Math.min(
+    (isFiniteNumber(config?.decisionPlane?.timeoutMs)
+      ? config.decisionPlane.timeoutMs
+      : ADAPTER_TIMEOUT_CAP_MS) + 1000,
+    ADAPTER_TIMEOUT_CAP_MS + 1000,
+  );
+  const batch = {
+    batchId,
+    boundary: 'sidecar',
+    deadlineMs: Math.max(500, timeoutMs - 1000),
+    statePacket: buildStatePacket(spec.decision, context),
+    questions: [spec.question],
+  };
+  let result = null;
+  try {
+    const spawned = spawnSync(
+      process.execPath,
+      [cliPath, '--root', rootDir],
+      {
+        cwd: rootDir,
+        input: JSON.stringify(batch),
+        encoding: 'utf8',
+        timeout: timeoutMs,
+      },
+    );
+    if (spawned && !spawned.error && spawned.status === 0 && spawned.stdout) {
+      result = JSON.parse(spawned.stdout);
+    } else {
+      result = { status: 'unavailable', fallbackCode: 'adapter-spawn-failed' };
+    }
+  } catch {
+    result = { status: 'unavailable', fallbackCode: 'adapter-spawn-failed' };
+  }
+  if (!result || typeof result !== 'object') {
+    result = { status: 'unavailable', fallbackCode: 'malformed-response' };
+  }
+  return result;
+}
+
+function validModelAnswer(result, decisionKey) {
+  const answers = Array.isArray(result?.answers) ? result.answers : [];
+  const answer = answers.find(
+    (a) => a?.decisionKey === decisionKey && a.validationStatus === 'valid',
+  );
+  return typeof answer?.value === 'string' ? answer.value : null;
+}
+
+/**
+ * Resolve one sidecar decision. Returns a typed result; never throws.
+ *   {decision, decisionKey, stage, answer, deterministic, source,
+ *    outcomeClass, modelAnswer?, agreement?, fallbackCode}
+ * `answer` is the authoritative value: the deterministic rule at 'off' and
+ * 'shadow', the model's valid answer at 'canary'/'default', and the
+ * deterministic rule again on any adapter failure (outcomeClass 'unavailable').
+ */
+export async function runSidecarDecision({ decision, context = {}, rootDir, homeDir, config } = {}) {
+  const spec = SIDECAR_DECISIONS[decision];
+  if (!spec) {
+    return {
+      decision: decision ?? null,
+      decisionKey: null,
+      stage: 'off',
+      answer: null,
+      deterministic: null,
+      source: 'none',
+      outcomeClass: 'invalid',
+      fallbackCode: 'unknown-decision',
+    };
+  }
+  const mergedConfig = config ?? readMergedConfig(rootDir, homeDir);
+  const stage = resolveSidecarStage(mergedConfig);
+  const ctx = isPlainObject(context) ? context : {};
+  let deterministic;
+  try {
+    deterministic = spec.decide(ctx);
+  } catch {
+    deterministic = spec.question.candidates[0];
+  }
+  const base = {
+    decision,
+    decisionKey: spec.decisionKey,
+    stage,
+    deterministic,
+    fallbackPolicy: spec.fallbackPolicy,
+  };
+
+  if (stage === 'off') {
+    return { ...base, answer: deterministic, source: 'deterministic', outcomeClass: 'deterministic' };
+  }
+
+  const result = runAdapterBatch({
+    spec, context: ctx, rootDir: rootDir ?? process.cwd(), config: mergedConfig,
+    batchId: `sidecar-${decision}-${Date.now().toString(36)}`,
+  });
+  const modelAnswer = validModelAnswer(result, spec.decisionKey);
+  const outcomeClass = result?.status ?? 'unavailable';
+  const agreement = modelAnswer === null
+    ? 'unknown'
+    : modelAnswer.toLowerCase() === String(deterministic).toLowerCase()
+      ? 'agree'
+      : 'disagree';
+
+  if (outcomeClass === 'unavailable' || outcomeClass === 'unsupported' || outcomeClass === 'invalid') {
+    return {
+      ...base,
+      answer: deterministic,
+      source: 'deterministic-fallback',
+      outcomeClass: 'unavailable',
+      modelAnswer,
+      agreement,
+      fallbackCode: result?.fallbackCode ?? outcomeClass,
+    };
+  }
+  if (stage === 'shadow') {
+    return {
+      ...base,
+      answer: deterministic,
+      source: 'deterministic',
+      outcomeClass,
+      modelAnswer,
+      agreement,
+      fallbackCode: result?.fallbackCode ?? null,
+    };
+  }
+  // canary/default: valid model answer wins; invalid → deterministic fallback.
+  if (modelAnswer !== null) {
+    return {
+      ...base,
+      answer: modelAnswer,
+      source: 'unic-decision',
+      outcomeClass,
+      modelAnswer,
+      agreement,
+      fallbackCode: result?.fallbackCode ?? null,
+    };
+  }
+  return {
+    ...base,
+    answer: deterministic,
+    source: 'deterministic-fallback',
+    outcomeClass,
+    modelAnswer,
+    agreement,
+    fallbackCode: result?.fallbackCode ?? 'missing-answer',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function readFlagValue(argv, flag) {
+  const index = argv.indexOf(flag);
+  if (index === -1) return null;
+  const value = argv[index + 1];
+  return value && !value.startsWith('--') ? value : null;
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+function printResult(result) {
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+function printDecisionList() {
+  const rows = Object.entries(SIDECAR_DECISIONS).map(([name, spec]) => ({
+    decision: name,
+    decisionKey: spec.decisionKey,
+    fallbackPolicy: spec.fallbackPolicy,
+    candidates: spec.question.candidates,
+  }));
+  printResult({ family: SIDECAR_FAMILY, decisions: rows });
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const rootDir = readFlagValue(args, '--root') ?? process.env.UKIT_TEST_ROOT ?? process.cwd();
+  const homeDir = process.env.UKIT_TEST_HOME ?? os.homedir();
+
+  if (args.includes('--list')) {
+    printDecisionList();
+    return 0;
+  }
+
+  // Offline replay passthrough: the sibling adapter owns fixture semantics;
+  // this CLI adds none of its own. Exit code is propagated verbatim.
+  const fixturePath = readFlagValue(args, '--fixture');
+  if (fixturePath !== null) {
+    const cliPath = process.env.UKIT_DECISION_CLI_PATH || UNIC_DECISION_CLI_PATH;
+    try {
+      const spawned = spawnSync(
+        process.execPath,
+        [cliPath, '--fixture', fixturePath],
+        { cwd: rootDir, encoding: 'utf8', timeout: ADAPTER_TIMEOUT_CAP_MS + 2000 },
+      );
+      if (spawned?.stdout) process.stdout.write(spawned.stdout);
+      if (spawned?.stderr) process.stderr.write(spawned.stderr);
+      return spawned?.status ?? 1;
+    } catch (error) {
+      process.stderr.write(
+        `sidecar-decision: fixture replay failed: ${error?.message ?? error}\n`,
+      );
+      return 1;
+    }
+  }
+
+  const raw = await readStdin();
+  let input = {};
+  if (raw.trim().length > 0) {
+    try {
+      input = JSON.parse(raw);
+    } catch {
+      process.stderr.write(
+        'sidecar-decision: expected context JSON on stdin ({} allowed) '
+          + 'or --decision <name> or --fixture <path> or --list\n',
+      );
+      return 1;
+    }
+    if (!isPlainObject(input)) {
+      process.stderr.write('sidecar-decision: stdin context must be a JSON object\n');
+      return 1;
+    }
+  }
+
+  const decision = readFlagValue(args, '--decision') ?? input.decision;
+  if (typeof decision !== 'string' || !SIDECAR_DECISIONS[decision]) {
+    process.stderr.write(
+      `sidecar-decision: unknown or missing decision; expected one of: `
+        + `${Object.keys(SIDECAR_DECISIONS).join(', ')}\n`,
+    );
+    return 1;
+  }
+  const context = isPlainObject(input.context) ? input.context : input;
+
+  try {
+    printResult(await runSidecarDecision({ decision, context, rootDir, homeDir }));
+  } catch (error) {
+    // Last-resort never-throws guard: emit the deterministic rule answer.
+    const spec = SIDECAR_DECISIONS[decision];
+    let deterministic = spec.question.candidates[0];
+    try {
+      deterministic = spec.decide(isPlainObject(context) ? context : {});
+    } catch { /* keep first candidate */ }
+    printResult({
+      decision,
+      decisionKey: spec.decisionKey,
+      stage: 'unknown',
+      answer: deterministic,
+      deterministic,
+      source: 'deterministic-fallback',
+      outcomeClass: 'unavailable',
+      fallbackCode: 'internal-error',
+    });
+  }
+  return 0;
+}
+
+const isMainModule = (() => {
+  try {
+    const invoked = process.argv[1] ?? '';
+    if (!invoked) return false;
+    const self = path.resolve(fileURLToPath(import.meta.url));
+    const target = path.resolve(invoked);
+    if (self === target) return true;
+    // Installed mirrors may be reached through a symlinked directory (e.g.
+    // .codex/ukit -> ../.claude/ukit): realpath resolves the link, basename
+    // equality keeps same-named unrelated scripts from matching.
+    return path.basename(invoked) === 'sidecar-decision.mjs'
+      && fs.realpathSync(target) === self;
+  } catch {
+    return false;
+  }
+})();
+
+if (isMainModule) {
+  main()
+    .then((code) => { process.exitCode = code; })
+    .catch((error) => {
+      process.stderr.write(`sidecar-decision: ${error?.message ?? error}\n`);
+      process.exitCode = 1;
+    });
+}

package/template_project/.claude/ukit/index/unic-decision.mjs

@@ -789,7 +789,16 @@ async function main() {
 
 const isMainModule = (() => {
   try {
-    return path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1] ?? '');
+    const invoked = process.argv[1] ?? '';
+    if (!invoked) return false;
+    const self = path.resolve(fileURLToPath(import.meta.url));
+    const target = path.resolve(invoked);
+    if (self === target) return true;
+    // Installed mirrors may be reached through a symlinked directory (e.g.
+    // .codex/ukit -> ../.claude/ukit): realpath resolves the link, basename
+    // equality keeps same-named unrelated scripts from matching.
+    return path.basename(invoked) === 'unic-decision.mjs'
+      && fs.realpathSync(target) === self;
   } catch {
     return false;
   }

package/template_project/.claude/ukit/runtime/async-lock.mjs

@@ -452,6 +452,15 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
   const releaseRetry = (op) => withTransientFsRetry(op, { deadlineMs: LOCK_RESERVE_MS });
 
   while (true) {
+    // Abort wins over every other condition, checked once per iteration: an abort
+    // landing mid-sweep/mid-op must still surface the typed aborted outcome — the
+    // ops below can throw the raw signal.reason (withTransientFsRetry rethrows
+    // AbortError when the signal fires during a transient retry), and a non-EEXIST
+    // throw would otherwise escape as an unhandled rejection instead of the
+    // contract's { ok: false, reason: 'aborted' } envelope.
+    if (signal?.aborted) {
+      return { ok: false, reason: 'aborted', waitedMs: Date.now() - startedAt };
+    }
     // Reap stale `*.reclaim-*` quarantine dirs stranded by dead reapers. Cheap:
     // one readdir per attempt, all failures swallowed (C79-21).
     await sweepStaleReclaims(lockPath, stale);
@@ -489,6 +498,11 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
       owned = true;
       break;
     } catch (error) {
+      // An abort surfacing as the raw AbortError out of a transient retry is the
+      // typed aborted outcome, never an untyped throw.
+      if (signal?.aborted) {
+        return { ok: false, reason: 'aborted', waitedMs: Date.now() - startedAt };
+      }
       if (error?.code !== 'EEXIST') throw error;
     }
 
@@ -533,6 +547,12 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
     }
     if (reclaimed) continue;
 
+    // Abort after the wait phase still returns the typed aborted outcome — the
+    // budget check must not claim 'busy' for a caller that was actually cancelled.
+    if (signal?.aborted) {
+      return { ok: false, reason: 'aborted', waitedMs: Date.now() - startedAt };
+    }
+
     const waitedMs = Date.now() - startedAt;
     if (waitedMs >= budget) {
       // Fail closed: the caller's policy decides what a busy lock means. The callback
@@ -548,6 +568,12 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
     }
   }
 
+  // Abort between acquire and the critical section releases the owned lock through
+  // the normal finally path and reports 'aborted' instead of running fn after the
+  // caller was cancelled.
+  if (signal?.aborted) {
+    return { ok: false, reason: 'aborted', waitedMs: Date.now() - startedAt };
+  }
   try {
     return { ok: true, value: await fn() };
   } finally {

package/template_project/.codex/settings.json

@@ -188,6 +188,9 @@
           "compact-now-or-later",
           "summarize-docs-or-keep-detail"
         ],
+        "decisionAdapter": "sidecar-decision.mjs",
+        "decisionStageGate": "decisionPlane.families.workflow.stage",
+        "decisionKeysSource": "cli",
         "stepBudgets": {
           "trivial": {
             "maxSteps": 1,