@ngockhoale/ukit 3.0.3 → 3.0.5

package/src/core/taskProgressGuard.js

@@ -66,24 +66,74 @@ function sliceSection(markdown, headingRe) {
   return markdown.slice(start, end);
 }
 
+// Target-file entries may carry brace alternation (`src/core/{a,b}.js`) or glob
+// stars (`src/core/compact/*.js`) — planners write both. Expand them so a
+// progress entry naming a covered file is not a false undeclared-drift.
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function targetPatternToRegExp(pattern) {
+  // `{a,b}` → alternation; `**` → any path; `*` → any non-separator run.
+  let source = '';
+  for (let i = 0; i < pattern.length; i += 1) {
+    const ch = pattern[i];
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        source += '.*';
+        i += 1;
+      } else {
+        source += '[^/]*';
+      }
+    } else if (ch === '{') {
+      const close = pattern.indexOf('}', i + 1);
+      if (close === -1) {
+        source += '\\{';
+      } else {
+        source += `(?:${pattern.slice(i + 1, close).split(',').map(escapeRegExp).join('|')})`;
+        i = close;
+      }
+    } else {
+      source += escapeRegExp(ch);
+    }
+  }
+  return new RegExp(`^${source}$`);
+}
+
 function collectTargetFiles(markdown) {
   const section = sliceSection(markdown, TARGET_HEADING);
-  if (!section) return new Set();
   const files = new Set();
-  for (const line of section.split('\n')) {
-    // Lines look like "- `path/to/file.js` — what changes"
-    const m = /^\s*-\s+`?([^`\s]+(?:\.[^`\s]+)?)`?/.exec(line);
-    if (m) files.add(m[1]);
+  const patterns = [];
+  if (section) {
+    for (const line of section.split('\n')) {
+      // Lines look like "- `path/to/file.js` — what changes"
+      const m = /^\s*-\s+`?([^`\s]+(?:\.[^`\s]+)?)`?/.exec(line);
+      if (!m) continue;
+      const target = m[1];
+      if (/[{*]/.test(target)) patterns.push(targetPatternToRegExp(target));
+      else files.add(target);
+    }
   }
-  return files;
+  return {
+    has(file) {
+      return files.has(file) || patterns.some((re) => re.test(file));
+    },
+  };
 }
 
 function collectProgressEntries(progressSection) {
   const entries = [];
   for (const line of progressSection.split('\n')) {
-    if (!line.trim().startsWith('- ')) continue;
-    const parsed = parseEntry(line.trim());
-    if (parsed) entries.push(parsed);
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('- ')) continue;
+    const parsed = parseEntry(trimmed);
+    if (parsed) {
+      entries.push(parsed);
+    } else if (trimmed.includes('milestone:')) {
+      // A bullet that looks like a progress entry but fails the entry grammar is
+      // malformed — report it rather than silently dropping it.
+      entries.push({ ok: false, raw: trimmed });
+    }
   }
   return entries;
 }

package/src/core/unattendedDoctor.js

@@ -103,7 +103,10 @@ export async function inspectUnattendedMode({ projectRoot, ompPath = 'omp' }) {
   for (const entry of bashPatterns) {
     if (entry && typeof entry === 'object' && 'approval' in entry) promptValues.push(entry.approval);
   }
-  const promptPolicyCount = promptValues.filter((v) => v === 'prompt').length;
+  // 'ask' dead-ends under unattended exactly like 'prompt' (omp has no native
+  // ask — the bridge converts it to a block). permissionDoctor already counts
+  // both; counting only 'prompt' here was a fail-open gap.
+  const promptPolicyCount = promptValues.filter((v) => v === 'prompt' || v === 'ask').length;
 
   const bridgePath = path.join(projectRoot, '.omp', 'hooks', 'pre', 'ukit-bridge.js');
   const bridgeExists = await pathExists(bridgePath);
@@ -192,7 +195,7 @@ export async function inspectUnattendedMode({ projectRoot, ompPath = 'omp' }) {
       'Run ukit install to strip `prompt` approvals (unattended mode cannot surface prompts).',
       {
         ...(omp.exists ? {} : { applicable: false, detail: '.omp/config.yml absent' }),
-        detail: `${promptPolicyCount} prompt policy(ies)`,
+        detail: `${promptPolicyCount} prompt/ask policy(ies)`,
       },
     ),
     // 5 — project override active

package/src/core/uninstall.js

@@ -4,6 +4,7 @@ import {
   cleanupEmptyParents,
   copyFileRawExclusive,
   readJsonIfExists,
+  removeFileOrLinkOnly,
   removeLinkOrDir,
   removeLinkOnly,
   resolveProjectRelativePath,
@@ -314,7 +315,10 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
   if (Array.isArray(installData.files)) {
     // New format: tracked files give us ownership metadata even when the list is
     // empty. Skip invalid entries to avoid path traversal.
-    regularPaths = [stateDir]; // always delete state dir — it's always UKit-owned
+    // stateDir is always UKit-owned and removed recursively; every tracked
+    // entry is a file/link, so a real directory at a tracked path is user
+    // content and must be refused (removeFileOrLinkOnly), never rm -rf'd.
+    regularPaths = [{ abs: stateDir, recursive: true }];
     linkPaths = [];
 
     // Two arrays for two unrelated meanings: invalidPaths are suspicious (forged
@@ -361,7 +365,7 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
         continue;
       }
 
-      regularPaths.push(entry.absolutePath);
+      regularPaths.push({ abs: entry.absolutePath, recursive: false });
     }
 
     if (invalidPaths.length > 0) {
@@ -373,13 +377,16 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
     // These are user-created content (mergeStrategy: skip) — deleting them
     // would cause data loss. Users must remove them manually if desired.
     const fallback = buildFallbackPaths(projectRoot);
-    regularPaths = fallback.regularPaths;
+    // Legacy installs have no per-file ownership metadata; the hardcoded list
+    // keeps its historical recursive semantics (.ukit/, state dir are dirs).
+    regularPaths = fallback.regularPaths.map((abs) => ({ abs, recursive: true }));
     linkPaths = fallback.linkPaths;
   }
 
+
   const allEntries = [
-    ...regularPaths.map((abs) => ({ abs, useLink: false })),
-    ...linkPaths.map((abs) => ({ abs, useLink: true })),
+    ...regularPaths.map(({ abs, recursive }) => ({ abs, useLink: false, recursive })),
+    ...linkPaths.map((abs) => ({ abs, useLink: true, recursive: false })),
   ];
 
   // Never delete through a symlinked parent — see hasSymlinkedParent. Skipped entries
@@ -439,13 +446,35 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
   }
 
   // Remove all paths in parallel
+  // Remove all paths in parallel. Tracked file entries use removeFileOrLinkOnly:
+  // a real directory at a tracked path is user content (the user replaced the
+  // managed file) and is refused — same protection link entries already had.
   const results = await Promise.all(
-    safeEntries.map(({ abs, useLink }) => {
-      const remove = useLink ? removeLinkOnly : removeLinkOrDir;
-      return remove(abs).then((didRemove) => ({ abs, didRemove }));
+    safeEntries.map(({ abs, useLink, recursive }) => {
+      const remove = useLink ? removeLinkOnly : recursive ? removeLinkOrDir : removeFileOrLinkOnly;
+      return remove(abs).then((didRemove) => ({ abs, didRemove, recursive }));
     }),
   );
 
+  // Surface refused real directories instead of silently leaving them behind —
+  // matches the link-update warning in applyPlan.js.
+  const refusedDirs = [];
+  for (const { abs, didRemove, recursive } of results) {
+    if (didRemove || recursive) continue;
+    try {
+      const stat = await fs.lstat(abs);
+      if (stat.isDirectory() && !stat.isSymbolicLink()) refusedDirs.push(abs);
+    } catch {
+      // vanished — nothing to report
+    }
+  }
+  if (refusedDirs.length > 0) {
+    console.warn(
+      '[UKit] Warning: skipping tracked paths that now exist as real directories (possible user content). Remove them manually if intended:',
+      refusedDirs,
+    );
+  }
+
   // Clean up .gitignore block added during install
   await removeGitignoreBlock(projectRoot);
 

package/src/decision/client.js

@@ -0,0 +1,371 @@
+/**
+ * client.js (TASK-002 / M07)
+ *
+ * Typed client for the UNIC Decision Agent: OpenAI-compatible
+ * `POST <baseUrl>/v1/chat/completions` against the configured UNIC gateway
+ * (docs/pstack/UNIC_DECISION_SPEC.md §3/§15/§16).
+ *
+ * - Endpoint + credentials resolve via gatewayProbe env indirection only —
+ *   no literal keys, no new credential store.
+ * - Auth header mirrors Claude Code's own forwarding: ANTHROPIC_AUTH_TOKEN →
+ *   `Authorization: Bearer`, ANTHROPIC_API_KEY → `x-api-key`.
+ * - Typed outcomes: accepted | abstained | invalid | unavailable | timeout |
+ *   blocked-sensitive | unsupported.
+ * - One bounded same-request retry for transient failures inside deadlineMs;
+ *   circuit breaker (failureThreshold + cooldownMs) short-circuits to
+ *   'unavailable' while open.
+ * - `tool_calls` in responses are data only — parsed, never dispatched.
+ */
+
+import { createHash } from 'node:crypto';
+import {
+  resolveGatewayBaseUrl,
+  resolveGatewayApiKey,
+} from '../core/gatewayProbe.js';
+import {
+  encodeBatch,
+  parseBatchResponse,
+  classifyLanguage,
+} from './protocol.js';
+import {
+  redactStatePacket,
+  assertStateBudget,
+  serializeStatePacket,
+} from './statePacket.js';
+
+const DEFAULT_CHECKPOINTS = {
+  default: 'unic-decision/laya-multilingual',
+  english: 'unic-decision/laya',
+  unknownLanguage: 'unic-decision/auto',
+};
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_RETRIES = 1;
+const DEFAULT_BREAKER = { failureThreshold: 3, cooldownMs: 30_000 };
+
+function decisionPlaneConfig(config) {
+  const dp = config?.decisionPlane ?? config ?? {};
+  return dp && typeof dp === 'object' ? dp : {};
+}
+
+/**
+ * Checkpoint resolution (UNIC_DECISION_SPEC §3 / FR-004):
+ *   multilingual → checkpoints.default   (laya-multilingual)
+ *   english      → checkpoints.english   (laya) — only for proven-English state
+ *   unknown      → checkpoints.unknownLanguage (auto)
+ * The English checkpoint NEVER receives Vietnamese/mixed state — callers must
+ * pass the output of `classifyLanguage`, not a guess.
+ *
+ * @param {'english'|'multilingual'|'unknown'} languageClass
+ * @param {object} config runtime config (or the decisionPlane block itself)
+ * @returns {string} checkpoint model id
+ */
+export function resolveCheckpoint(languageClass, config) {
+  const checkpoints = {
+    ...DEFAULT_CHECKPOINTS,
+    ...(decisionPlaneConfig(config).checkpoints ?? {}),
+  };
+  if (languageClass === 'english') return checkpoints.english;
+  if (languageClass === 'unknown') return checkpoints.unknownLanguage;
+  return checkpoints.default;
+}
+
+// Latency classes for receipts — bands, never raw volatile numbers.
+function latencyClass(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return 'unknown';
+  if (ms < 250) return 'fast';
+  if (ms < 2000) return 'normal';
+  return 'slow';
+}
+
+function requestFingerprint(body) {
+  return createHash('sha256').update(body).digest('hex').slice(0, 16);
+}
+
+function buildAuthHeaders(key) {
+  if (!key?.value) return {};
+  if (key.scheme === 'auth-token') {
+    return { Authorization: `Bearer ${key.value}` };
+  }
+  return { 'x-api-key': key.value };
+}
+
+function isTransientStatus(status) {
+  return status === 429 || (status >= 500 && status <= 599);
+}
+
+async function readResponseBody(res) {
+  if (res && typeof res.json === 'function') return res.json();
+  if (res && typeof res.text === 'function') return JSON.parse(await res.text());
+  return res;
+}
+
+/**
+ * Create a decision client.
+ *
+ * @param {{config?: object, transport?: Function, now?: Function,
+ *          projectRoot?: string, homeDir?: string, env?: object}} options
+ *   transport: fetch-compatible `async (url, init) => response`; tests inject a
+ *   fake — the client itself performs no I/O beyond it.
+ *   now: ms clock, injectable for deterministic circuit-breaker tests.
+ * @returns {{requestBatch: Function, healthProbe: Function, circuitState: Function}}
+ */
+export function createDecisionClient({
+  config,
+  transport = globalThis.fetch?.bind(globalThis),
+  now = () => Date.now(),
+  projectRoot,
+  homeDir,
+  env = process.env,
+} = {}) {
+  const dp = decisionPlaneConfig(config);
+  const breakerCfg = { ...DEFAULT_BREAKER, ...(dp.circuitBreaker ?? {}) };
+  const timeoutMs = Number.isFinite(dp.timeoutMs) ? dp.timeoutMs : DEFAULT_TIMEOUT_MS;
+  const maxStateTokens = dp.maxStateTokens ?? {};
+
+  // Circuit breaker state: consecutive transport-level failures open the
+  // circuit; after cooldownMs a single half-open probe is allowed through.
+  let consecutiveFailures = 0;
+  let openedAt = null;
+  // Half-open admits exactly one in-flight probe; concurrent callers get a
+  // defined contention result instead of piling onto a possibly-dead gateway.
+  let probeInFlight = false;
+
+  function circuitState() {
+    if (openedAt === null) return 'closed';
+    return now() - openedAt >= breakerCfg.cooldownMs ? 'half-open' : 'open';
+  }
+
+  function recordSuccess() {
+    consecutiveFailures = 0;
+    openedAt = null;
+  }
+
+  function recordFailure() {
+    consecutiveFailures += 1;
+    if (consecutiveFailures >= breakerCfg.failureThreshold && openedAt === null) {
+      openedAt = now();
+    }
+  }
+
+  function outcome(status, extra = {}) {
+    return {
+      status,
+      finishReason: null,
+      answers: [],
+      circuitState: circuitState(),
+      ...extra,
+    };
+  }
+
+  async function resolveEndpoint() {
+    const base = await resolveGatewayBaseUrl({ projectRoot, homeDir, env });
+    if (!base?.baseUrl) return null;
+    const key = await resolveGatewayApiKey({ projectRoot, homeDir, env });
+    return {
+      url: `${String(base.baseUrl).replace(/\/+$/, '')}/v1/chat/completions`,
+      headers: buildAuthHeaders(key),
+    };
+  }
+
+  async function postWithDeadline(url, headers, body, deadlineMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deadlineMs);
+    try {
+      return await transport(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...headers },
+        body,
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Send one C13 batch. `batch` = {batchId?, boundary?, statePacket, questions,
+   * deadlineMs?}. Returns a typed DecisionBatchResult; never throws for
+   * transport-level failures.
+   */
+  async function requestBatch(batch) {
+    if (dp.enabled === false) {
+      return outcome('unavailable', { fallbackCode: 'decision-plane-disabled' });
+    }
+    if (circuitState() === 'open' || probeInFlight) {
+      return outcome('unavailable', { fallbackCode: 'circuit-open' });
+    }
+    if (!transport) {
+      return outcome('unsupported', { fallbackCode: 'no-transport' });
+    }
+    const questions = Array.isArray(batch?.questions) ? batch.questions : [];
+    if (questions.length === 0) {
+      return outcome('invalid', { fallbackCode: 'empty-batch' });
+    }
+
+    // Language classification covers state + question text; the English
+    // checkpoint is reachable only when the whole request proves English.
+    const serialized = serializeStatePacket(batch.statePacket ?? {});
+    const questionText = questions
+      .map((q) => `${q.decisionKey} ${q.instruction} ${(q.candidates ?? []).join(' ')}`)
+      .join(' ');
+    const languageClass = classifyLanguage(`${serialized} ${questionText}`);
+    const checkpoint = resolveCheckpoint(languageClass, config);
+
+    // Budget gate — oversize state is never silently truncated.
+    try {
+      assertStateBudget(serialized, languageClass, maxStateTokens);
+    } catch (err) {
+      if (err?.code === 'state-too-large') {
+        return outcome('invalid', { fallbackCode: 'state-too-large', checkpoint });
+      }
+      throw err;
+    }
+
+    // Sensitive-value gate before serialization leaves the process.
+    const gate = redactStatePacket(serialized, { config });
+    if (gate.status === 'blocked-sensitive') {
+      return outcome('blocked-sensitive', { checkpoint });
+    }
+
+    // Claim the half-open probe slot synchronously — before the first await —
+    // so concurrent callers see probeInFlight and get 'circuit-open' instead
+    // of a second probe. finally clears it on every exit path.
+    const probing = circuitState() === 'half-open';
+    if (probing) probeInFlight = true;
+    try {
+      const endpoint = await resolveEndpoint();
+      if (!endpoint) {
+        return outcome('unsupported', {
+          fallbackCode: 'endpoint-unconfigured',
+          checkpoint,
+        });
+      }
+
+      const body = JSON.stringify(
+        encodeBatch({ model: checkpoint, statePacket: serialized, questions }),
+      );
+      const fingerprint = requestFingerprint(body);
+      const deadlineMs = Number.isFinite(batch?.deadlineMs)
+        ? batch.deadlineMs
+        : timeoutMs;
+
+      // A half-open probe is a single trial — no retry against a possibly-dead
+      // gateway; a closed circuit gets the bounded transient retry.
+      const maxAttempts = probing ? 1 : 1 + DEFAULT_MAX_RETRIES;
+      let lastError = null;
+      let lastStatus = null;
+      for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        const startedAt = now();
+        let res;
+        try {
+          res = await postWithDeadline(endpoint.url, endpoint.headers, body, deadlineMs);
+        } catch (err) {
+          const isTimeout =
+            err?.name === 'AbortError' || err?.code === 'ABORT_ERR';
+          lastError = isTimeout ? 'timeout' : 'unavailable';
+          lastStatus = null;
+          // Timeouts never retry; transient transport errors retry once inside
+          // the deadline.
+          if (isTimeout || attempt + 1 >= maxAttempts) break;
+          continue;
+        }
+
+        const status = res?.status ?? (res?.ok === false ? 500 : 200);
+        if (res?.ok === false || status < 200 || status >= 300) {
+          if (isTransientStatus(status) && attempt + 1 < maxAttempts) continue;
+          if (status === 401 || status === 403) {
+            lastError = 'unavailable';
+            lastStatus = 'auth-rejected';
+          } else if (status === 400 || status === 404 || status === 422) {
+            lastError = 'unsupported';
+            lastStatus = 'endpoint-rejected';
+          } else {
+            lastError = 'unavailable';
+            lastStatus = 'gateway-error';
+          }
+          break;
+        }
+
+        let parsed;
+        try {
+          parsed = await readResponseBody(res);
+        } catch {
+          lastError = 'invalid';
+          lastStatus = 'malformed-response';
+          break;
+        }
+
+        const result = parseBatchResponse(parsed, questions);
+        recordSuccess();
+        return {
+          batchId: batch?.batchId ?? null,
+          checkpoint,
+          finishReason: result.finishReason,
+          status: result.status,
+          answers: result.answers,
+          requestFingerprint: fingerprint,
+          latencyClass: latencyClass(now() - startedAt),
+          circuitState: circuitState(),
+        };
+      }
+
+      // Only transport-class failures (timeout/unavailable) count toward the
+      // breaker — deterministic outcomes (unsupported endpoint, malformed body,
+      // auth rejection) would otherwise open the circuit on a misconfigured
+      // endpoint and mask the precise typed outcome behind circuit-open.
+      if (lastError === 'timeout' || lastError === 'unavailable') {
+        recordFailure();
+        // A failed half-open probe re-opens the circuit with a fresh cooldown —
+        // otherwise openedAt stays stale and the circuit is half-open forever,
+        // probing a dead gateway on every request.
+        if (probing) openedAt = now();
+      }
+      return outcome(lastError ?? 'unavailable', {
+        batchId: batch?.batchId ?? null,
+        checkpoint,
+        fallbackCode:
+          lastStatus ?? (lastError === 'timeout' ? 'deadline-exceeded' : 'transport-error'),
+        requestFingerprint: fingerprint,
+      });
+    } finally {
+      if (probing) probeInFlight = false;
+    }
+  }
+
+  /**
+   * Explicit no-tools health probe — the ONLY request allowed to carry no
+   * tools (UNIC_DECISION_SPEC §9). Returns {status:'ok'|'unavailable'|...}.
+   */
+  async function healthProbe() {
+    if (dp.enabled === false) return { status: 'unavailable' };
+    if (!transport) return { status: 'unsupported' };
+    const endpoint = await resolveEndpoint();
+    if (!endpoint) return { status: 'unsupported' };
+    const checkpoint = resolveCheckpoint('multilingual', config);
+    const body = JSON.stringify({
+      model: checkpoint,
+      messages: [{ role: 'user', content: 'ping' }],
+      max_tokens: 1,
+    });
+    try {
+      const res = await postWithDeadline(
+        endpoint.url,
+        endpoint.headers,
+        body,
+        timeoutMs,
+      );
+      const status = res?.status ?? (res?.ok === false ? 500 : 200);
+      if (res?.ok === false || status < 200 || status >= 300) {
+        return { status: 'unavailable', httpStatus: status };
+      }
+      return { status: 'ok', checkpoint };
+    } catch (err) {
+      return {
+        status: err?.name === 'AbortError' ? 'timeout' : 'unavailable',
+      };
+    }
+  }
+
+  return { requestBatch, healthProbe, circuitState };
+}