@ngockhoale/ukit 3.4.74 → 3.4.76

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/CHANGELOG.md +110 -95
  2. package/manifests/platform.full.yaml +15 -0
  3. package/package.json +14 -4
  4. package/src/cli/commands/markerStore.js +15 -0
  5. package/src/cli/index.js +7 -0
  6. package/src/core/markerStoreMigration.js +122 -0
  7. package/template_project/.claude/hooks/completion-gate.sh +10 -1
  8. package/template_project/.claude/hooks/handoff-resume.sh +9 -0
  9. package/template_project/.claude/hooks/owner-stop-gate.mjs +41 -0
  10. package/template_project/.claude/hooks/skill-router.sh +262 -28
  11. package/template_project/.claude/settings.json +11 -1
  12. package/template_project/.claude/ukit/index/publication-intent.mjs +144 -18
  13. package/template_project/.claude/ukit/index/route-task.mjs +91 -9
  14. package/template_project/.claude/ukit/runtime/cron-operation-adapter.mjs +11 -4
  15. package/template_project/.claude/ukit/runtime/execution-ledger.mjs +369 -29
  16. package/template_project/.claude/ukit/runtime/operation-evidence.mjs +9 -0
  17. package/template_project/.claude/ukit/runtime/resumable-run.mjs +33 -11
  18. package/template_project/.claude/ukit/runtime/stop-coordinator.mjs +161 -32
  19. package/template_project/.omp/hooks/pre/ukit-bridge.js +552 -4
  20. package/scripts/bug/triage.mjs +0 -76
  21. package/scripts/dev/worktree-preflight.mjs +0 -166
  22. package/scripts/docs/render-instructions.mjs +0 -66
  23. package/scripts/index/build-index.mjs +0 -102
  24. package/scripts/index/query-index.mjs +0 -128
  25. package/scripts/index/refresh-index.mjs +0 -195
  26. package/scripts/install/sync-installed-mirror.mjs +0 -263
  27. package/scripts/measure-decision-gateway.mjs +0 -306
  28. package/scripts/probe/codex-capability-probe.mjs +0 -169
  29. package/scripts/skill/audit-skill.mjs +0 -68
  30. package/scripts/test/run-handoff-isolated.mjs +0 -178
@@ -1226,6 +1226,7 @@ items:
1226
1226
  - hook-block-dangerous
1227
1227
  - hook-handoff-model-guard
1228
1228
  - hook-delegation-gate-module
1229
+ - hook-owner-stop-gate-module
1229
1230
  - hook-auto-prune-bash
1230
1231
  - hook-project-important
1231
1232
  # Env block is post-merged by applyGatewayResilienceEnv (TASK-011) to add managed
@@ -1426,6 +1427,20 @@ items:
1426
1427
  packs:
1427
1428
  - core
1428
1429
 
1430
+ # Owner STOP gate: in-proc PreToolUse catch-all (`.*`) step; denies every NEW tool/spawn start for a stopped session
1431
+ # and its delegated children. Reads route state through ukit-runtime-scripts (execution-ledger.mjs).
1432
+ - id: hook-owner-stop-gate-module
1433
+ type: hook
1434
+ sourceTemplate: .claude/hooks/owner-stop-gate.mjs
1435
+ targetPath: .claude/hooks/owner-stop-gate.mjs
1436
+ requires:
1437
+ - ukit-runtime-scripts
1438
+ mergeStrategy: overwrite_with_backup
1439
+ variables: []
1440
+ enabledByDefault: true
1441
+ packs:
1442
+ - core
1443
+
1429
1444
  # P0 delegation enforcement: in-proc PreToolUse chain step (Edit|Write, MultiEdit, Bash). Claude Code
1430
1445
  # only (agent_id main/worker identity); reads route state + ledger from ukit-runtime-scripts.
1431
1446
  - id: hook-delegation-gate-module
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ngockhoale/ukit",
3
- "version": "3.4.74",
3
+ "version": "3.4.76",
4
4
  "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -32,7 +32,18 @@
32
32
  "scripts/",
33
33
  "!scripts/dev/benchmark-verification-currency.mjs",
34
34
  "!scripts/dev/capture-omp-stall.mjs",
35
+ "!scripts/dev/worktree-preflight.mjs",
36
+ "!scripts/measure-decision-gateway.mjs",
37
+ "!scripts/probe/codex-capability-probe.mjs",
35
38
  "!scripts/install/generate-semantic-engine.mjs",
39
+ "!scripts/install/sync-installed-mirror.mjs",
40
+ "!scripts/test/run-handoff-isolated.mjs",
41
+ "!scripts/docs/render-instructions.mjs",
42
+ "!scripts/index/build-index.mjs",
43
+ "!scripts/index/query-index.mjs",
44
+ "!scripts/index/refresh-index.mjs",
45
+ "!scripts/bug/triage.mjs",
46
+ "!scripts/skill/audit-skill.mjs",
36
47
  "!scripts/release/progress-reporter.mjs",
37
48
  "!scripts/release/publish-guard-core.mjs",
38
49
  "!scripts/audit/c100/attribution-gap.mjs",
@@ -48,10 +59,9 @@
48
59
  "template_user/",
49
60
  "!template_project/**/.smbdelete*",
50
61
  "!template_project/.smbdelete*",
62
+ "!template_project/.ukit/**",
63
+ "!template_project/**/skill-router-state.json",
51
64
  "CHANGELOG.md",
52
- "LICENSE",
53
- "template_project/CLAUDE.md",
54
- "template_project/AGENTS.md",
55
65
  "template_project/.gitignore",
56
66
  "manifests/"
57
67
  ],
@@ -0,0 +1,15 @@
1
+ import { migrateMarkerStore } from '../../core/markerStoreMigration.js';
2
+
3
+ export async function runMarkerStore({ projectRoot, argv = [] }) {
4
+ if (argv[0] !== 'migrate' || argv.includes('--help')) {
5
+ console.log('Usage: ukit marker-store migrate [--apply --writers-stopped]');
6
+ console.log('');
7
+ console.log('Plan (default) or apply the OMP bridge UNKNOWN marker-store migration. Apply needs --writers-stopped');
8
+ console.log('(you closed every OMP/bridge session of this project); UKit verifies, refuses when unverifiable,');
9
+ console.log('never kills processes and keeps the original store in a quarantine directory.');
10
+ return;
11
+ }
12
+ const result = await migrateMarkerStore({ projectRoot, apply: argv.includes('--apply'), attestWritersStopped: argv.includes('--writers-stopped') });
13
+ console.log(JSON.stringify(result, null, 2));
14
+ if (!result.ok) process.exitCode = 2;
15
+ }
package/src/cli/index.js CHANGED
@@ -14,6 +14,7 @@ import { runPlaybook } from './commands/playbook.js';
14
14
  import { runDecision } from './commands/decision.js';
15
15
  import { runSelfImproveCommand } from './commands/selfImprove.js';
16
16
  import { runVm } from './commands/vm.js';
17
+ import { runMarkerStore } from './commands/markerStore.js';
17
18
  const GLOBAL_FLAGS = new Set(['--help', '-h', '--version', '-v']);
18
19
 
19
20
  export async function runCli({ argv, packageRoot, projectRoot, packageVersion }) {
@@ -106,6 +107,11 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
106
107
  return;
107
108
  }
108
109
 
110
+ if (command === 'marker-store') {
111
+ await runMarkerStore({ projectRoot, argv: commandArgv });
112
+ return;
113
+ }
114
+
109
115
  if (command === 'vm') {
110
116
  await runVm({ projectRoot, argv: commandArgv });
111
117
  return;
@@ -145,6 +151,7 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
145
151
  console.log(' feedback Record or list wrong-route feedback labels');
146
152
  console.log(' self-improve Run the automatic learn/tune/collect pass now (hooks run it)');
147
153
  console.log(' vm Agent VM driver (list/show/status/shadow-run/evidence)');
154
+ console.log(' marker-store Plan/apply the OMP bridge UNKNOWN marker-store migration (refuses unless writers are verified stopped)');
148
155
  console.log(' update Upgrade the global UKit CLI to the latest version');
149
156
  console.log(' version Show UKit version');
150
157
  console.log('');
@@ -0,0 +1,122 @@
1
+ // Migration of the OMP bridge UNKNOWN repeat-marker store (.ukit/storage/cache/omp-bridge-unknown-markers).
2
+ // Writers are bridge processes with no registry/lock, so a rewrite is only allowed when the owner attests the old
3
+ // writers are stopped AND this tool finds no process with the project as cwd and an unchanged store. Otherwise it
4
+ // refuses. Never kills processes, never deletes: the original store is renamed to a quarantine directory.
5
+ // Every block marker becomes a sticky release marker (a dead writer's block would only ever release on repeat);
6
+ // release markers are kept byte-for-byte, so STOP, session and task isolation (hashed names) are untouched.
7
+ import fs from 'node:fs';
8
+ import path from 'node:path';
9
+ import crypto from 'node:crypto';
10
+ import { spawnSync } from 'node:child_process';
11
+
12
+ export const STORE_REL = path.join('.ukit', 'storage', 'cache', 'omp-bridge-unknown-markers');
13
+ const NAME = /^([0-9a-f]{64})\.([0-9a-f]{64})\.(block|release)$/;
14
+ const refuse = (reason, extra = {}) => ({ ok: false, reason, ...extra });
15
+
16
+ export function scanStore(store) {
17
+ const entries = [];
18
+ const invalid = [];
19
+ for (const name of fs.readdirSync(store)) {
20
+ const m = NAME.exec(name);
21
+ let body = null;
22
+ try { body = JSON.parse(fs.readFileSync(path.join(store, name), 'utf8')); } catch { /* invalid */ }
23
+ const ok = m && body && body.v === 2 && typeof body.p === 'string' && Number.isInteger(body.k);
24
+ if (ok) entries.push({ name, kind: m[3], stem: `${m[1]}.${m[2]}`, text: fs.readFileSync(path.join(store, name), 'utf8') });
25
+ else invalid.push(name);
26
+ }
27
+ return { entries, invalid };
28
+ }
29
+
30
+ // Processes (other than this one) whose cwd is inside the project. null = could not be enumerated.
31
+ export function liveProjectProcesses(projectRoot) {
32
+ const root = fs.realpathSync(projectRoot);
33
+ const inside = (cwd) => cwd === root || cwd.startsWith(root + path.sep);
34
+ const found = [];
35
+ try {
36
+ if (process.platform === 'linux') {
37
+ for (const pid of fs.readdirSync('/proc').filter((n) => /^\d+$/.test(n) && Number(n) !== process.pid)) {
38
+ try { if (inside(fs.readlinkSync(`/proc/${pid}/cwd`))) found.push(pid); } catch { /* exited or not ours */ }
39
+ }
40
+ return found;
41
+ }
42
+ if (process.platform === 'win32') return null;
43
+ const ps = spawnSync('ps', ['-axo', 'pid=,command='], { encoding: 'utf8', timeout: 20000 });
44
+ if (ps.error || ps.status !== 0) return null;
45
+ for (const line of ps.stdout.split('\n')) {
46
+ const m = /^\s*(\d+)\s+(.*)$/.exec(line);
47
+ if (m && Number(m[1]) !== process.pid && Number(m[1]) !== process.ppid && m[2].includes(root) && !m[2].includes('marker-store')) found.push(m[1]);
48
+ }
49
+ const r = spawnSync('lsof', ['-a', '-d', 'cwd', '-Fpn'], { encoding: 'utf8', timeout: 20000 });
50
+ if (r.error || !r.stdout) return null;
51
+ let pid = '';
52
+ for (const line of r.stdout.split('\n')) {
53
+ if (line[0] === 'p') pid = line.slice(1);
54
+ else if (line[0] === 'n' && Number(pid) !== process.pid && Number(pid) !== process.ppid && inside(line.slice(1))) found.push(pid);
55
+ }
56
+ return found;
57
+ } catch { return null; }
58
+ }
59
+
60
+ const fingerprint = (store) => crypto.createHash('sha256').update(fs.readdirSync(store).sort().map((n) => {
61
+ const s = fs.statSync(path.join(store, n));
62
+ return `${n}:${s.size}:${s.mtimeMs}`;
63
+ }).join('\n')).digest('hex');
64
+
65
+ export async function migrateMarkerStore({ projectRoot, apply = false, attestWritersStopped = false, observeMs = 2000, hooks = {} }) {
66
+ const store = path.join(projectRoot, STORE_REL);
67
+ const journal = `${store}.migration.json`;
68
+ const stat = fs.existsSync(store) ? fs.statSync(store) : null;
69
+ const pending = fs.existsSync(journal) ? JSON.parse(fs.readFileSync(journal, 'utf8')) : null;
70
+ if (!pending && !stat) return { ok: true, status: 'no-store' };
71
+ if (!pending && !stat.isDirectory()) return refuse('marker store path is not a directory');
72
+
73
+ const plan = !pending ? scanStore(store) : { entries: [], invalid: [] };
74
+ const blocks = plan.entries.filter((e) => e.kind === 'block').length;
75
+ const summary = { releases: plan.entries.length - blocks, blocks, invalid: plan.invalid.length, tempFiles: plan.invalid.filter((n) => n.includes('.tmp-')).length };
76
+ if (!pending && blocks === 0 && plan.invalid.length === 0) return { ok: true, status: 'already-migrated', ...summary };
77
+ if (!apply) return { ok: true, status: 'plan', ...summary };
78
+
79
+ if (!attestWritersStopped) return refuse('owner attestation missing: close every OMP/bridge session that uses this project, then pass --writers-stopped', summary);
80
+ const live = liveProjectProcesses(projectRoot);
81
+ if (live === null) return refuse('cannot verify that no process is using this project on this platform; migration refused (no automatic reclaim)', summary);
82
+ if (live.length) return refuse(`processes still use this project (pids ${live.join(', ')}); close them yourself, UKit never stops processes`, summary);
83
+
84
+ const id = pending?.id ?? crypto.randomBytes(6).toString('hex');
85
+ const quarantine = `${store}.migrated-${id}`;
86
+ const fresh = `${store}.new-${id}`;
87
+ const step = (name) => { try { hooks.step?.(name); } catch (e) { e.fromHook = true; throw e; } };
88
+
89
+ if (!pending) {
90
+ if (summary.tempFiles) return refuse('writer temp files present (a writer may be active); retry after all sessions are closed', summary);
91
+ const before = fingerprint(store);
92
+ await new Promise((r) => setTimeout(r, observeMs));
93
+ if (fingerprint(store) !== before) return refuse('marker store changed during the observation window; a writer is still active', summary);
94
+ try { fs.mkdirSync(fresh); } catch (error) { return refuse(`cannot create the fresh marker directory (${error.code ?? error.message}); nothing was changed`, summary); }
95
+ // A stem that already has a release keeps it byte-for-byte; its block adds nothing (a release is sticky).
96
+ const released = new Set(plan.entries.filter((e) => e.kind === 'release').map((e) => e.stem));
97
+ for (const e of plan.entries) {
98
+ if (e.kind === 'block' && released.has(e.stem)) continue;
99
+ fs.writeFileSync(path.join(fresh, `${e.stem}.release`), e.text, { flag: 'wx' });
100
+ }
101
+ // Last check before the store is touched: a writer arriving after the observation window aborts the run.
102
+ if (fingerprint(store) !== before) { fs.rmSync(fresh, { recursive: true, force: true }); return refuse('marker store changed just before the swap; a writer is still active', summary); }
103
+ fs.writeFileSync(journal, JSON.stringify({ v: 1, id }), { flag: 'wx' });
104
+ }
105
+ step('journaled');
106
+ // Recovery-safe sequence: quarantine -> fence file at the store path -> unlink fence -> publish new directory.
107
+ // A journal without its fresh directory is only valid after the final rename (quarantine kept, store a directory).
108
+ if (pending && !fs.existsSync(fresh) && !(fs.existsSync(quarantine) && stat?.isDirectory())) return refuse('migration journal has no fresh directory to resume from; nothing was changed, keep the files and contact the maintainer', summary);
109
+ try {
110
+ if (!fs.existsSync(fresh) && fs.existsSync(quarantine)) { fs.rmSync(journal, { force: true }); return { ok: true, status: 'migrated', ...summary, quarantine }; }
111
+ if (fs.existsSync(store) && fs.statSync(store).isDirectory()) { fs.renameSync(store, quarantine); step('quarantined'); }
112
+ if (!fs.existsSync(store)) fs.writeFileSync(store, 'ukit marker store migrating', { flag: 'wx' });
113
+ step('fenced');
114
+ if (fs.statSync(store).isFile()) fs.unlinkSync(store);
115
+ fs.renameSync(fresh, store);
116
+ } catch (error) {
117
+ if (error.fromHook) throw error;
118
+ return refuse(`migration did not complete (${error.code ?? error.message}); rerun the same command to resume, nothing was deleted`, { ...summary, quarantine });
119
+ }
120
+ fs.rmSync(journal, { force: true });
121
+ return { ok: true, status: 'migrated', ...summary, quarantine };
122
+ }
@@ -85,7 +85,9 @@ fi
85
85
  # (coordinator deadline + margin); a forced kill lands on the existing crash-streak
86
86
  # path (non-zero STATUS) so the outcome is announced, never silently released.
87
87
  __ukit_coord_out="$(mktemp "${TMPDIR:-/tmp}/ukit-coord-out.XXXXXX")"
88
- printf '%s' "$INPUT" | UKIT_HARNESS="${UKIT_HARNESS:-claude-code}" UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node "$SCRIPT" --evaluate-stop > "$__ukit_coord_out" 2>/dev/null &
88
+ __ukit_coord_err="$(mktemp "${TMPDIR:-/tmp}/ukit-coord-err.XXXXXX" 2>/dev/null)" || __ukit_coord_err=/dev/null
89
+ __ukit_coord_t0=$SECONDS
90
+ printf '%s' "$INPUT" | UKIT_HARNESS="${UKIT_HARNESS:-claude-code}" UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node "$SCRIPT" --evaluate-stop > "$__ukit_coord_out" 2>"$__ukit_coord_err" &
89
91
  __ukit_coord_pid=$!
90
92
  __ukit_coord_ms="${UKIT_HOOK_DEADLINE_MS:-3000}"
91
93
  case "$__ukit_coord_ms" in ''|*[!0-9]*) __ukit_coord_ms=3000 ;; esac
@@ -99,6 +101,13 @@ kill "$__ukit_killer_pid" 2>/dev/null
99
101
  wait "$__ukit_killer_pid" 2>/dev/null
100
102
  OUTPUT="$(cat "$__ukit_coord_out" 2>/dev/null)"
101
103
  rm -f "$__ukit_coord_out"
104
+ # Bounded diagnostic for a crashed coordinator (status>128 = killed by signal N-128, e.g. 137 = the deadline killer's SIGKILL).
105
+ # Written to a private cache file only; never part of the decision text (the reason stays fixed and redacted).
106
+ if [ "$STATUS" -ne 0 ]; then
107
+ mkdir -p "$PROJECT_ROOT/.ukit/storage/cache" 2>/dev/null
108
+ { printf 'status=%s elapsed_s=%s deadline_ms=%s\n' "$STATUS" "$((SECONDS - __ukit_coord_t0))" "${__ukit_coord_ms}"; head -c 400 "$__ukit_coord_err" 2>/dev/null; printf '\n'; } > "$PROJECT_ROOT/.ukit/storage/cache/completion-gate-crash.last" 2>/dev/null
109
+ fi
110
+ [ "$__ukit_coord_err" = /dev/null ] || rm -f "$__ukit_coord_err"
102
111
 
103
112
  if [ "$STATUS" -ne 0 ]; then
104
113
  # BUG-C22-05: a PERSISTENT coordinator crash must not block every Stop forever.
@@ -280,6 +280,15 @@ function boundedTaskScopeLines(all, runCycle, currentTask) {
280
280
  process.exit(0);
281
281
  }
282
282
 
283
+ try {
284
+ const ledger = await import(pathToFileURL(runtimePath).href);
285
+ const routeState = await ledger.readRouteState(projectRoot, payload);
286
+ if (ledger.ownerStopActive(routeState, payload)) {
287
+ process.stdout.write('UKit note: an owner STOP is standing for this session; handoff run not resumed. Cursor untouched. Only a new owner request resumes work.\n');
288
+ process.exit(0);
289
+ }
290
+ } catch {}
291
+
283
292
  // Transcript intent cannot establish ownership of a cursor. Resolve the current
284
293
  // session's durable binding before either injecting a resume or lifting a pause.
285
294
  let ownership;
@@ -0,0 +1,41 @@
1
+ // owner-stop-gate.mjs — PreToolUse chain step (in-proc `runHook(ctx)`), wired on the catch-all `.*` matcher.
2
+ //
3
+ // While an owner STOP stands on a session (route state `ownerControl.kind === 'stop'`), NO new tool, shell command,
4
+ // edit, MCP call or subagent may start for that session or for a subagent it delegated. Matching is by the shared
5
+ // dispatch point (every tool name), not a tool list, so a new or renamed tool cannot slip past it.
6
+ //
7
+ // Scope, stated honestly:
8
+ // * It prevents NEW starts. It cannot cancel an operation that is already running — that is the host's `session_stop`.
9
+ // * Session-bound: an independent session in the same repo has its own route record and is never affected.
10
+ // * The STOP never expires; only a genuine owner prompt (the router) lifts it. Quoted/hook-shaped text cannot.
11
+ // * Denying is terminal for the call and creates no continuation: the Stop lanes already release on a standing STOP.
12
+ // * Codex exposes no hook surface, so nothing here runs there (advisory-only engine; see manifests/hostCapabilities.yaml).
13
+ // Fail-open on an internal fault (a broken advisory step must not wedge the session); the omp bridge applies the same
14
+ // check in-process at its own `tool_call` / `before_subagent_spawn` handlers.
15
+
16
+ import { ownerStopGovernsStart } from '../ukit/runtime/execution-ledger.mjs';
17
+
18
+ export const hookFailClosed = false;
19
+
20
+ export const OWNER_STOP_REASON = 'Owner STOP is in effect for this session: no new tool, shell command, edit or subagent may start until the owner sends a new request. Do not retry; report the stop and wait.';
21
+
22
+ export async function runHook(ctx) {
23
+ try {
24
+ const payload = ctx?.payload || {};
25
+ const env = ctx?.env || {};
26
+ // Bounded by the chain runner's per-step deadline (ctx.deadlineMs); a slow read fails open rather than wedge the call.
27
+ const deadlineMs = Number(ctx?.deadlineMs) > 0 ? Number(ctx.deadlineMs) : 4000;
28
+ const root = env.CLAUDE_PROJECT_DIR || ctx?.projectRoot || process.cwd();
29
+ const ids = [payload.session_id, payload.sessionId, payload.ukit_parent_session_id];
30
+ const stopped = await Promise.race([ownerStopGovernsStart(root, ids), new Promise((resolve) => setTimeout(() => resolve(false), Math.max(500, deadlineMs - 500)).unref())]);
31
+ if (!stopped) return { code: 0, stdout: '', stderr: '' };
32
+ const inChain = Boolean(env.UKIT_HOOK_CHAIN_RUNNER);
33
+ return {
34
+ code: inChain ? 2 : 0,
35
+ stdout: `${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: OWNER_STOP_REASON } })}\n`,
36
+ stderr: `BLOCKED: ${OWNER_STOP_REASON}\n`,
37
+ };
38
+ } catch {
39
+ return { code: 0, stdout: '', stderr: '' };
40
+ }
41
+ }