@ngockhoale/ukit 2.3.15 → 2.3.17

package/CHANGELOG.md

@@ -2,28 +2,131 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.17 - 2026-09-12
+
+Long-task resilience — a handoff run is now measured before planning, checkpointed during
+execution, and auto-split on wall-clock overrun instead of silently wedging. Cycle C12 turns
+three questions into enforced machinery: "is this task too big to hand to an executor?"
+(answered with data before a task is ever marked `ready`), "did the executor actually record
+where it last stood green?" (answered by a machine-checkable milestone protocol), and "what
+happens when a task blows its time budget?" (answered by a watchdog that cuts the task in
+half and keeps the pipeline moving). Also fixes a repo-level gitignore trap that could
+silently swallow new template files.
+
+- **Task-budget validator — `needs_breakdown` as data, not prose.** New
+  `src/core/taskBudgetValidator.js` plus a behavior-identical shipped CLI twin at
+  `templates/.claude/ukit/index/task-budget-validator.mjs` (self-contained, no `src/`
+  dependency, so user installs get the same gate). Thresholds: `maxTargetFiles: 3`,
+  `maxTestCases: 8`, `maxVerificationMinutes: 10`, with a table-driven verification-minutes
+  estimator (`yarn test:release-core` = 3 min, `node scripts/release/verify-release.mjs` =
+  2 min, `yarn vitest run` = 0.5 min per file argument, unknown commands flat 1 min) and an
+  `investigate`+`first` prose rule for spike-vs-build splits. The `handoff-planner` agents
+  (Claude Code + omp) run the twin on every candidate task and must mark over-budget
+  `needs_breakdown` instead of shipping it as `ready`. Missing required sections emit
+  `missing-field` reasons; the validator never throws and the CLI always exits 0 (advisory
+  gate). TDD: 14/14 vitest cases + 4/4 ship-contract checks.
+- **Executor milestone protocol.** Task executors now append `## Progress` entries in a
+  fixed, parseable shape — `- <ISO-8601> · milestone: <name> · last-green: <what passed> ·
+  files: <paths> · drift: none|<why>` — and both task templates gain a `- Size: S|M|L`
+  line. New `src/core/taskProgressGuard.js` makes the entries machine-checkable, with the
+  staleness boundary at exactly 2 × `milestoneIntervalMin` (inclusive = ok, beyond = stale).
+  The feature-implementer agents (Claude Code + omp) and the `handoff-fullstack` command
+  carry matching protocol text as byte-identical pairs. TDD: 6/6 unit cases + 4/4 protocol
+  contract checks.
+- **Wall-clock watchdog hook, `hardPolicy: "split"`.** New
+  `templates/.claude/hooks/task-watchdog.sh` + `templates/.claude/ukit/runtime/
+  task-watchdog.mjs`, wired through `.claude/settings.json` (Stop + PostToolUse Edit/Write,
+  timeout 4) and `manifests/platform.full.yaml` (`hook-task-watchdog`). Budgets come from
+  `handoff.taskBudgets`: S 8/15, M 15/30, L 25/45 soft/hard minutes, `milestoneIntervalMin:
+  5` default, `hardPolicy` `"split"` (default) or `"pause"`. Soft overrun emits a visible
+  "checkpoint a milestone now" advisory; hard overrun under split policy emits a Stop
+  `decision=block` naming the follow-up `TASK-<id>-b` — blocking the stop IS the
+  auto-split-and-continue mechanism — capped at 2 blocks per task before degrading to an
+  advisory that hands back to the user. The hook can never hang a session: 3 s self-kill
+  (`HOOK_DEADLINE_MS`), all-async I/O, 64 KB stdin cap, fail-open `exit 0` on every path;
+  PostToolUse is advisory-only and never emits a decision. State lives at
+  `.ukit/storage/cache/task-watchdog/state.json`; config load is fail-open to
+  `DEFAULT_CONFIG`. TDD: 16 sandbox checks (hard-trip block, pause, cap, fail-open,
+  wiring, no-undefined advisories) + config-docs sync coverage.
+- **Gitignore trap fixed at both layers.** An unanchored `.claude/` pattern treats every
+  directory named `.claude` at any depth as ignored, and `templates/.gitignore` is a
+  per-directory ignore for the `templates/` subtree — so it silently hid NEW files under
+  `templates/.claude/**` from `git status`/`diff`/`add` (already-tracked files were
+  unaffected, which is why the trap stayed invisible). It ate the TASK-014 CLI twin, which
+  a `git worktree remove --force` then destroyed. Root `.gitignore` runtime dirs are now
+  anchored (`/.claude/`, `/.codex/`, `/.omp/`, `/.ukit/`, `/.worktrees/`) and the
+  `templates/.gitignore` runtime-dir lines are removed with an explanatory NOTE; new
+  template files no longer need `git add -f`.
+
+## 2.3.16 - 2026-09-11
+
+Gateway-stall root cause, part 5 — the operator's gateway stayed invisible in the repo. Wave 1
+(TASK-011 + TASK-012) shipped the two client-side fixes that defend Claude Code against the
+stall and the malformed-body incident; this release closes the loop with a written contract
+the operator (UNIC or any other proxy in front of `ANTHROPIC_BASE_URL`) can be handed. The
+two client-side fixes are also safe no-ops on the official Anthropic endpoint — they only
+fire when a gateway is in the path, so uninstall does not need to clean them up.
+
+- **Managed gateway resilience env defaults.** When `ANTHROPIC_BASE_URL` is non-empty (env,
+  project `.claude/settings.json`, or home `~/.claude/settings.json`), `ukit install` now
+  writes `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK='1'` and
+  `CLAUDE_STREAM_IDLE_TIMEOUT_MS='600000'` into the project `.claude/settings.json` `env`
+  block via a new `merge_env_overwrite_with_backup` strategy. Never clobbers a user-set
+  value (a non-default value moves into the report's `skipped` list); re-running `ukit
+  install` is a no-op (`unchanged`); corrupt settings JSON fails safe without overwriting
+  the file. New module `src/core/gatewayResilienceEnv.js` + wiring in
+  `src/core/runInstallPipeline.js` and `src/cli/commands/install.js`. TDD: 12/12 unit
+  cases + 5/5 installCommand wiring cases green.
+- **`ukit doctor --gateway` live probe.** New opt-in flag on `ukit doctor` posts one tiny
+  streaming and one tiny non-streaming probe to `/v1/messages` and prints a `✓`/`✗` per
+  requirement. Streaming is flagged as `buffered` when the first body read alone already
+  carries ≥2 SSE events (the exact stall signature). Non-streaming fails when the body is
+  HTTP 200 but not an Anthropic Message **or** the `request-id` header is missing — the
+  exact check whose absence let the 888-byte gateway error envelope slip through and kill
+  the user's turn. New module `src/core/gatewayProbe.js` (`fetchImpl` injectable, fully
+  hermetic test surface); wiring in `src/cli/commands/doctor.js` (`--gateway` added to
+  `KNOWN_FLAGS` + help; verdict is advisory and MUST NOT set `process.exitCode` so
+  scripted `ukit doctor` runs stay hermetic). TDD: 6/6 unit cases + 8/8 doctorCommand
+  wiring cases green.
+- **Gateway operator requirements doc.** New `docs/GATEWAY.md` states the three
+  requirements the operator must satisfy — (1) SSE/bytes relayed incrementally (no
+  full-response buffering), (2) idle streams kept alive ≥600 s under the watchdog, (3)
+  non-streaming route returns a real Anthropic Message with a `request-id` header — plus a
+  client-side knob table (`CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK`,
+  `CLAUDE_STREAM_IDLE_TIMEOUT_MS`, `ukit doctor --gateway`) and the explicit safe-no-op
+  guarantee on the official Anthropic endpoint. Probe hint lines from TASK-012's
+  `gatewayProbe.js` point at this doc.
+
+Residual unknown: `gatewayProbe.js` is exercised end-to-end against the real gateway only
+through a hermetic `fetchImpl` (every test path uses an injected `ReadableStream`). A live
+`ukit doctor --gateway` round-trip against the real gateway was NOT run in CI; it is a
+manual post-release step on a gateway-connected machine. Recorded in `docs/STATUS.md`.
+
 ## 2.3.15 - 2026-09-11
 
-Vision-lane root cause, part 4 — native-first dispatch order. Found by mining the user's own
-failing sessions across four real projects (UnicDB, VSDB, BAGuide, AI-Gateway): the API `model`
-field in the transcripts proved failed specialist dispatches landed on `glm-5-turbo` / lite lanes
-(self-reported `MODEL: unic-lite`, `STATUS: WRONG_MODEL`) while the same sessions' main Claude
-lanes read images fine (`STATUS: OK` ×14 in one transcript). Two stacked defects:
-
-- **No fallback when the specialist fails.** The honored-lane hint ordered the parent to dispatch
-  `ukit-vision-analyst` and simply continue; when the gateway routed the alias to a backend that
-  cannot receive the image through the Read tool_result, the analyst returned `WRONG_MODEL` and
-  the image ended up unread even though the parent could have read it natively. The hint now
-  verifies the parent's own vision FIRST (step 2: Read the materialized files yourself, write the
-  receipts, do NOT dispatch), dispatches the specialist only when the parent's own Read yields no
-  image (step 3), and defines the fallback: on `WRONG_MODEL`/`NO_IMAGE` re-read natively, analyse
-  from your own view for pasted images, and never fabricate when no reader can see it (step 4).
+Vision-lane root cause, part 4 — the analyst never looked at the image. Found by mining the
+user's own failing sessions across four real projects (UnicDB, VSDB, BAGuide, AI-Gateway). The
+decisive record: a failed analyst subagent transcript is THREE lines with ZERO Read calls — the
+analyst refused by name ("I am running on unic-lite, which is not a vision-capable model … I
+must refuse to open, describe, or guess") without ever probing. The user confirmed the gateway's
+vision routing is stable by design: unic-vision (backed by minimax/glm/chatgpt in their setup)
+always reads images; nothing falls back to a non-visual lane. The failure was entirely
+UKit-side, two stacked defects:
+
 - **Refusal by name instead of by probe.** The omp analyst template mandated refusing *before
-  touching any image* when the runtime model could not be confirmed vision-capable — field
-  transcripts show exactly this refusal (`I must refuse to open, describe, or guess`). Both agent
-  templates now decide ONLY by the first image Read (the probe): a backend that self-identifies as
-  `glm-5-turbo`/`MiniMax-M3`/a lite lane does not license refusal when the probe actually shows
-  the image; a vision-sounding name with a failed probe is still `WRONG_MODEL`.
+  touching any image* when the runtime model could not be confirmed vision-capable — and any
+  backend self-identification (`glm-5-turbo`, `MiniMax-M3`) or lite-lane label counted as "not
+  confirmed". Both agent templates now decide ONLY by the first image Read (the probe): if the
+  probe shows the image the lane reads it and reports the mapping it actually ran on in
+  `MODEL:`; a probe that fails to deliver the image is still `STATUS: WRONG_MODEL`.
+- **No fallback after a refusal.** The honored-lane hint ordered the parent to dispatch the
+  specialist and simply continue, so a name-refusal left the image unread even though the parent
+  could read it natively (`STATUS: OK` ×14 from main Claude lanes in one VSDB transcript). The
+  hint now verifies the parent's own vision FIRST (step 2: Read the materialized files yourself,
+  write the receipts, do NOT dispatch), dispatches the specialist only when the parent's own
+  Read yields no image (step 3), and defines the fallback: on `WRONG_MODEL`/`NO_IMAGE` re-read
+  natively, analyse from your own view for pasted images, and never fabricate when no reader can
+  see it (step 4).
 
 Unchanged doctrine: never guess at image contents — the fix removes the two paths that turned
 "don't guess" into "don't read". omp mirrors synced. TDD: `vision-router-hint` tests 13-14 and

package/manifests/platform.full.yaml

@@ -973,7 +973,10 @@ items:
       - hook-block-dangerous
       - hook-handoff-model-guard
       - hook-auto-prune-bash
-    mergeStrategy: overwrite_with_backup
+    # Env block is post-merged by applyGatewayResilienceEnv (TASK-011) to add managed
+    # gateway-resilience defaults without clobbering user values, so the diff ignores
+    # the env block — byte-equality on the rest of the file is enough to flag an update.
+    mergeStrategy: merge_env_overwrite_with_backup
     variables: []
     enabledByDefault: true
     packs:
@@ -1176,6 +1179,28 @@ items:
     packs:
       - core
 
+  - id: hook-task-watchdog
+    type: hook
+    sourceTemplate: .claude/hooks/task-watchdog.sh
+    targetPath: .claude/hooks/task-watchdog.sh
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: ukit-runtime-task-watchdog-script
+    type: config
+    sourceTemplate: .claude/ukit/runtime/task-watchdog.mjs
+    targetPath: .claude/ukit/runtime/task-watchdog.mjs
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-reset-compact-pressure
     type: hook
     sourceTemplate: .claude/hooks/reset-compact-pressure.sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.15",
+  "version": "2.3.17",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/cli/commands/doctor.js

@@ -8,9 +8,14 @@ import { loadManifest } from '../../manifest/loadManifest.js';
 import { detectStack } from '../../stack/detectStack.js';
 import { detectProviders } from '../../context/detectProviders.js';
 import { profileSkills } from '../../core/skillProfile.js';
+import {
+  resolveGatewayBaseUrl,
+  probeGateway,
+} from '../../core/gatewayProbe.js';
 
 export const DOCTOR_HELP_FLAGS = new Set(['--help', '-h']);
-const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills']);
+const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway']);
+const SUPPORTED_FLAGS_LIST = '--help, -h, --skills, --gateway';
 
 export function printDoctorHelp() {
   console.log('Usage: ukit doctor [options]');
@@ -20,12 +25,13 @@ export function printDoctorHelp() {
   console.log('Options:');
   console.log('  --help, -h      Show this help message');
   console.log('  --skills        Also print a skill word-count/budget report');
+  console.log('  --gateway       Live gateway probe (streaming + non-streaming); advisory only');
 }
 
 export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
   const unknownFlags = argv.filter((flag) => !KNOWN_FLAGS.has(flag));
   if (unknownFlags.length > 0) {
-    throw new Error(`Unknown option: ${unknownFlags[0]}. Supported: --help, -h, --skills`);
+    throw new Error(`Unknown option: ${unknownFlags[0]}. Supported: ${SUPPORTED_FLAGS_LIST}`);
   }
 
   if (argv.some((flag) => DOCTOR_HELP_FLAGS.has(flag))) {
@@ -149,6 +155,47 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
     );
   }
 
+  if (argv.includes('--gateway')) {
+    console.log('');
+    console.log('[UKit] Gateway probe (advisory — does not affect exit code):');
+    let resolved;
+    try {
+      resolved = await resolveGatewayBaseUrl({ projectRoot });
+    } catch {
+      resolved = { baseUrl: null, source: null };
+    }
+    if (!resolved.baseUrl) {
+      console.log('[UKit]   -  Gateway probe skipped — no custom gateway configured (ANTHROPIC_BASE_URL not set in env, project .claude/settings.json, or ~/.claude/settings.json).');
+    } else {
+      console.log(`[UKit]   baseUrl: ${resolved.baseUrl} (source: ${resolved.source})`);
+      let result;
+      try {
+        result = await probeGateway({ baseUrl: resolved.baseUrl });
+      } catch (error) {
+        result = null;
+        console.log(`[UKit]   ✗  Gateway probe threw: ${error?.message ?? String(error)}`);
+      }
+      if (result) {
+        const s = result.streaming;
+        const n = result.nonStreaming;
+        const streamingLabel = s.ok
+          ? `streaming OK (events=${s.eventsReceived}, chunks=${s.chunks})`
+          : `streaming FAIL (events=${s.eventsReceived}, chunks=${s.chunks}, buffered=${s.buffered}${s.error ? `, error=${s.error}` : ''})`;
+        const nonStreamingLabel = n.ok
+          ? `non-streaming OK (http=${n.httpOk}, isAnthropicMessage=${n.isAnthropicMessage}, request-id=${n.requestIdPresent}, bytes=${n.bodyBytes ?? 0})`
+          : `non-streaming FAIL (http=${n.httpOk}, isAnthropicMessage=${n.isAnthropicMessage}, request-id=${n.requestIdPresent}${n.error ? `, error=${n.error}` : ''})`;
+        console.log(`[UKit]   ${ok(s.ok)}  ${streamingLabel}`);
+        console.log(`[UKit]   ${ok(n.ok)}  ${nonStreamingLabel}`);
+        console.log(
+          `[UKit]   ${ok(result.verdict === 'pass')}  verdict: ${result.verdict}`,
+        );
+        for (const hint of result.hints) {
+          console.log(`[UKit]      hint: ${hint}`);
+        }
+      }
+    }
+  }
+
   const allPassed = Object.values(checks).every(Boolean);
   if (!allPassed) {
     console.log('[UKit] Some checks failed. Run `ukit install` to fix missing files.');

package/src/cli/commands/install.js

@@ -1,6 +1,7 @@
 import { buildPathConfig } from '../../core/paths.js';
 import { runInstallPipeline } from '../../core/runInstallPipeline.js';
 import { formatRepairReport } from '../../core/repairBrokenHooks.js';
+import { formatGatewayResilienceReport } from '../../core/gatewayResilienceEnv.js';
 import { buildCodeIndex } from '../../index/buildIndex.js';
 import { installIndexRefreshHooks } from '../../index/gitHooks.js';
 import fs from 'node:fs/promises';
@@ -246,6 +247,10 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
     console.log(`[UKit] ${line}`);
   }
 
+  for (const line of formatGatewayResilienceReport(result.gatewayResilience ?? { customGateway: false })) {
+    console.log(`[UKit] ${line}`);
+  }
+
   const docsLabels = [
     'docs/PROJECT.md',
     'docs/MEMORY.md',

package/src/core/applyPlan.js

@@ -69,7 +69,7 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
     // Back up the existing file before overwriting
     if (
       entry.action === 'update' &&
-      entry.mergeStrategy === 'overwrite_with_backup' &&
+      (entry.mergeStrategy === 'overwrite_with_backup' || entry.mergeStrategy === 'merge_env_overwrite_with_backup') &&
       backupRoot &&
       projectRoot
     ) {

package/src/core/diffPlan.js

@@ -1,5 +1,8 @@
 import fs from 'node:fs/promises';
 import { isSymlinkTo } from './fileOps.js';
+import { GATEWAY_RESILIENCE_ENV_DEFAULTS } from './gatewayResilienceEnv.js';
+
+const GATEWAY_RESILIENCE_KEYS = new Set(Object.keys(GATEWAY_RESILIENCE_ENV_DEFAULTS));
 
 async function readFileOrNull(filePath, encoding = 'utf8') {
   try {
@@ -24,6 +27,78 @@ async function checkLinkStatus(targetPath, linkTarget) {
   }
 }
 
+// Settings.json uses a strategy where only the gateway-resilience env keys (managed by
+// applyGatewayResilienceEnv post-apply) are ignored during the diff. Every other top-level
+// key — including the rest of the env block — is still compared byte-for-byte against the
+// template, so a template-side change to e.g. CLAUDE_CODE_AUTO_COMPACT_WINDOW still triggers
+// a real reinstall. Without this carve-out, the managed gateway keys written by the post-apply
+// step would cause a spurious "update" on every subsequent install.
+function settingsJsonIgnoresGatewayEnvDiff(existingContent, renderedContent) {
+  if (typeof existingContent !== 'string' || typeof renderedContent !== 'string') {
+    return false;
+  }
+  let parsedExisting;
+  let parsedRendered;
+  try {
+    parsedExisting = JSON.parse(existingContent);
+    parsedRendered = JSON.parse(renderedContent);
+  } catch {
+    return false;
+  }
+  if (!parsedExisting || typeof parsedExisting !== 'object' || Array.isArray(parsedExisting)) {
+    return false;
+  }
+  if (!parsedRendered || typeof parsedRendered !== 'object' || Array.isArray(parsedRendered)) {
+    return false;
+  }
+
+  for (const key of Object.keys(parsedRendered)) {
+    if (key === 'env') continue;
+    if (!(key in parsedExisting)) return false;
+    if (JSON.stringify(parsedExisting[key]) !== JSON.stringify(parsedRendered[key])) {
+      return false;
+    }
+  }
+
+  // Reverse direction: an existing top-level key that the template does NOT ship is also
+  // drift. Catches template key REMOVAL (e.g. a previous template shipped `permissions`
+  // and the new one dropped it) and user-side additions. The `merge_env_overwrite_with_backup`
+  // strategy is a narrowed overwrite — the only carve-out is the UKit-managed gateway env
+  // keys below — so every other byte mismatch must reinstall, in either direction.
+  for (const key of Object.keys(parsedExisting)) {
+    if (key === 'env') continue;
+    if (!(key in parsedRendered)) return false;
+  }
+
+  const templateEnv = parsedRendered.env && typeof parsedRendered.env === 'object' && !Array.isArray(parsedRendered.env)
+    ? parsedRendered.env
+    : {};
+  const fileEnv = parsedExisting.env && typeof parsedExisting.env === 'object' && !Array.isArray(parsedExisting.env)
+    ? parsedExisting.env
+    : {};
+
+  // Only enforce template env keys that are NOT UKit-managed. UKit-managed keys
+  // (CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK, CLAUDE_STREAM_IDLE_TIMEOUT_MS) are owned by
+  // applyGatewayResilienceEnv — it adds them post-apply and preserves user overrides.
+  for (const key of Object.keys(templateEnv)) {
+    if (GATEWAY_RESILIENCE_KEYS.has(key)) continue;
+    if (JSON.stringify(fileEnv[key]) !== JSON.stringify(templateEnv[key])) {
+      return false;
+    }
+  }
+
+  // Reverse direction for env: an env key in the file that the template does NOT ship
+  // (and that is not UKit-managed) is also drift — a removed template env key, or a
+  // user-added env key, must reinstall. UKit-managed gateway keys remain carved out
+  // because applyGatewayResilienceEnv owns them post-apply.
+  for (const key of Object.keys(fileEnv)) {
+    if (GATEWAY_RESILIENCE_KEYS.has(key)) continue;
+    if (!(key in templateEnv)) return false;
+  }
+
+  return true;
+}
+
 function resolveFileAction(entry, existingContent) {
   const exists = existingContent !== null;
   const binaryEntry = Buffer.isBuffer(entry.renderedContent);
@@ -41,6 +116,11 @@ function resolveFileAction(entry, existingContent) {
       : entry.mergeStrategy === 'skip'
         ? 'skip'
         : 'update';
+  } else if (entry.mergeStrategy === 'merge_env_overwrite_with_backup' && typeof existingContent === 'string') {
+    // Settings.json: ignore UKit-managed gateway resilience env keys (post-apply written
+    // and may carry user overrides). All other top-level keys — and the rest of the env
+    // block — must still match the template, so genuine template updates still reinstall.
+    action = settingsJsonIgnoresGatewayEnvDiff(existingContent, entry.renderedContent) ? 'unchanged' : 'update';
   } else if (existingContent === entry.renderedContent) {
     action = 'unchanged';
   } else if (entry.mergeStrategy === 'skip') {