@holmes-lab/holmes-kit 0.31.0 → 0.31.2

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.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
  <!-- @implements A-SPEC-209 -->
8
+ ## [0.31.2] - 2026-09-30
9
+
10
+ ### Fixed
11
+
12
+ - **A project `.codex/config.toml` left by a pre-0.30 init is named and offered for removal** (A-SPEC-721, amended).
13
+ Holmes wires Codex in the user configuration since 0.30, but in a trusted project Codex loads that old file over it:
14
+ a consumer workspace kept starting the 0.29.0 server through a committed `npx @holmes-lab/holmes-kit@0.29.0` pin
15
+ while init and doctor wired and judged the current release. doctor now says `codex legacy wiring` (WARN) with the
16
+ file, its launch and the command to remove it; `init --agent codex` (or `all`) asks before deleting it (default no),
17
+ and a non-interactive run — `upgrade`'s re-pin included — prints the command and deletes nothing. Only a file that is
18
+ exactly Holmes's own wiring is recognised; a comment, another table or key, or any other launch leaves it alone.
19
+ - **doctor names an expired approval** (A-SPEC-178, amended). An `HOLMES_APPROVAL` in `.mcp.json`'s server env whose
20
+ `expires` has passed read `approval channel` PASS ("spec_approve reaches it"); it is now WARN with the expiry (never
21
+ the value) and the fix to remove it.
22
+
23
+ ## [0.31.1] - 2026-09-29
24
+
25
+ ### Fixed
26
+
27
+ - **`holmes-kit upgrade` asks the registry for the latest version** (A-SPEC-543.2, amended). It read only the update
28
+ cache, which SessionStart refreshes at most once a day, so right after 0.31.0 was published it answered `already up
29
+ to date (current 0.31.0, latest 0.30.0)` and a newer release would not have been installed for up to a day. The
30
+ command now queries the registry (5 s, the same public `dist-tags` the banner uses) and refreshes the cache; when the
31
+ registry cannot be reached it says it used the cache and how old that answer is; an installed version newer than the
32
+ latest is no longer called "already up to date". `--dry-run` asks and shows, and writes nothing.
33
+
8
34
  ## [0.31.0] - 2026-09-29
9
35
 
10
36
  Post-0.30 hardening (H1–H12) and a new rule for Codex: whether Codex loads its own files is now
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- 89eba670-mum0nzxm
1
+ 8bd6277b-mumvdzzj
@@ -0,0 +1,16 @@
1
+ export declare function legacyCodexLayer(target: string): {
2
+ path: string;
3
+ launch: string;
4
+ } | null;
5
+ /**
6
+ * A-SPEC-721 (amendment 2026-09-29) — after init wires Codex: ask before deleting a Holmes-only legacy project file
7
+ * (default no); a non-interactive run (and so `upgrade`'s re-pin) only prints the command; a dry run asks nothing.
8
+ */
9
+ export declare function offerLegacyCodexRemoval(o: {
10
+ target: string;
11
+ interactive: boolean;
12
+ dryRun: boolean;
13
+ confirm: (question: string) => Promise<boolean>;
14
+ remove: (file: string) => void;
15
+ out: (line: string) => void;
16
+ }): Promise<void>;
@@ -0,0 +1,129 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.legacyCodexLayer = legacyCodexLayer;
37
+ exports.offerLegacyCodexRemoval = offerLegacyCodexRemoval;
38
+ // @implements A-SPEC-721
39
+ const fs = __importStar(require("node:fs"));
40
+ const path = __importStar(require("node:path"));
41
+ const smol_toml_1 = require("smol-toml");
42
+ /**
43
+ * A-SPEC-721 (amendment 2026-09-29) — the project `.codex/config.toml` a pre-0.30 init wrote. Holmes now wires Codex in
44
+ * the user configuration, but in a trusted project Codex loads this file OVER it: measured in a consumer workspace, a
45
+ * committed file pinning `npx @holmes-lab/holmes-kit@0.29.0` kept Codex on the 0.29.0 server while init and doctor
46
+ * wired and judged the current one. Only a file that is exactly Holmes's own legacy wiring is recognised — anything
47
+ * the user wrote or added is left alone.
48
+ */
49
+ const LEGACY_MAX_BYTES = 64 * 1024;
50
+ const TABLE_KEYS = new Set(['command', 'args', 'env']);
51
+ const ENV_KEYS = new Set(['HOLMES_SPECS', 'HOLMES_MCP_AUTORELOAD']);
52
+ function legacyCodexLayer(target) {
53
+ const file = path.join(target, '.codex', 'config.toml');
54
+ let text;
55
+ try {
56
+ const st = fs.lstatSync(file);
57
+ if (!st.isFile() || st.size > LEGACY_MAX_BYTES)
58
+ return null; // a link or a large file is not what init wrote
59
+ text = fs.readFileSync(file, 'utf8');
60
+ }
61
+ catch {
62
+ return null;
63
+ }
64
+ if (text.split(/\r?\n/).some((l) => l.trim().startsWith('#')))
65
+ return null; // a comment is the user's
66
+ let doc;
67
+ try {
68
+ doc = (0, smol_toml_1.parse)(text);
69
+ }
70
+ catch {
71
+ return null;
72
+ }
73
+ const keys = Object.keys(doc);
74
+ if (keys.length !== 1 || keys[0] !== 'mcp_servers')
75
+ return null;
76
+ const servers = doc.mcp_servers;
77
+ if (servers === null || typeof servers !== 'object' || Array.isArray(servers))
78
+ return null;
79
+ if (Object.keys(servers).length !== 1 || !('holmes-kit' in servers))
80
+ return null;
81
+ const table = servers['holmes-kit'];
82
+ if (table === null || typeof table !== 'object' || Array.isArray(table))
83
+ return null;
84
+ if (!Object.keys(table).every((k) => TABLE_KEYS.has(k)))
85
+ return null;
86
+ const { command, args, env } = table;
87
+ if (typeof command !== 'string' || !Array.isArray(args) || !args.every((a) => typeof a === 'string'))
88
+ return null;
89
+ const words = args;
90
+ const holmesLaunch = command === 'npx'
91
+ ? words.some((a) => a.startsWith('@holmes-lab/holmes-kit')) && words[words.length - 1] === 'holmes-mcp'
92
+ : command === 'node' && typeof words[0] === 'string' && /holmes-mcp\.js$/.test(words[0]);
93
+ if (!holmesLaunch)
94
+ return null;
95
+ if (env !== undefined) {
96
+ if (env === null || typeof env !== 'object' || Array.isArray(env))
97
+ return null;
98
+ if (!Object.keys(env).every((k) => ENV_KEYS.has(k)))
99
+ return null;
100
+ }
101
+ return { path: file, launch: [command, ...words].join(' ') };
102
+ }
103
+ /**
104
+ * A-SPEC-721 (amendment 2026-09-29) — after init wires Codex: ask before deleting a Holmes-only legacy project file
105
+ * (default no); a non-interactive run (and so `upgrade`'s re-pin) only prints the command; a dry run asks nothing.
106
+ */
107
+ async function offerLegacyCodexRemoval(o) {
108
+ const legacy = legacyCodexLayer(o.target);
109
+ if (legacy === null)
110
+ return;
111
+ const rel = path.relative(o.target, legacy.path).split(path.sep).join('/');
112
+ const why = `${legacy.path} holds only the Holmes wiring an older init wrote (\`${legacy.launch}\`); in a trusted project Codex loads it instead of the user-level wiring.`;
113
+ if (o.dryRun) {
114
+ o.out(`${why} (dry run — nothing asked or removed)`);
115
+ return;
116
+ }
117
+ if (!o.interactive) {
118
+ o.out(`${why} Remove it: git rm ${rel} (or delete it), then commit.`);
119
+ return;
120
+ }
121
+ o.out(why);
122
+ if (await o.confirm(`Remove the stale Holmes Codex wiring in ${legacy.path}? [y/N] `)) {
123
+ o.remove(legacy.path);
124
+ o.out(`Removed ${legacy.path} — commit the deletion (git add -A ${rel} && git commit).`);
125
+ }
126
+ else {
127
+ o.out(`Kept ${legacy.path}. Remove it later with: git rm ${rel}`);
128
+ }
129
+ }
@@ -1202,7 +1202,28 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1202
1202
  mcpApproval = false;
1203
1203
  } // absent or unreadable is "not guaranteed", which is the point
1204
1204
  const procApproval = !!process.env.HOLMES_APPROVAL;
1205
- if (mcpApproval) {
1205
+ // @implements A-SPEC-178 (amendment 2026-09-29) — an expired approval is not a channel (it read PASS twelve days after
1206
+ // it expired — measured). Only the expiry is printed, never the value.
1207
+ const mcpApprovalExpiry = (() => {
1208
+ try {
1209
+ const raw = fs.readFileSync(path.join(target, '.mcp.json'), 'utf8');
1210
+ const v = JSON.parse(raw).mcpServers?.[init_1.SERVER_NAME]?.env?.HOLMES_APPROVAL;
1211
+ if (typeof v !== 'string')
1212
+ return null;
1213
+ const expires = JSON.parse(v).expires;
1214
+ if (typeof expires !== 'string')
1215
+ return null;
1216
+ const at = Date.parse(expires);
1217
+ return Number.isFinite(at) && at < Date.now() ? expires : null;
1218
+ }
1219
+ catch {
1220
+ return null;
1221
+ }
1222
+ })();
1223
+ if (mcpApproval && mcpApprovalExpiry !== null) {
1224
+ add('approval channel', 'WARN', `The approval in .mcp.json's server env expired on ${(0, codex_oracle_1.clipText)(mcpApprovalExpiry, 40)} — spec_approve will refuse it`, 'Remove HOLMES_APPROVAL from the holmes-kit env in .mcp.json; set a fresh one only when an approval is needed.');
1225
+ }
1226
+ else if (mcpApproval) {
1206
1227
  add('approval channel', 'PASS', 'The approval variable is in .mcp.json\'s server env — spec_approve reaches it');
1207
1228
  }
1208
1229
  else if (!procApproval) {
@@ -1505,6 +1526,16 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1505
1526
  // judged for THIS target only when it carries Holmes's table or the target is Codex-wired;
1506
1527
  // otherwise a Claude- or Antigravity-only workspace would inherit another tool's diagnosis.
1507
1528
  const targetWantsCodex = codexWiredTarget(target);
1529
+ // @implements A-SPEC-721 (amendment 2026-09-29) — a project file that is exactly Holmes's pre-0.30 wiring replaces the
1530
+ // user-level wiring in a trusted project (a consumer's Codex ran 0.29.0 — measured); named with its launch.
1531
+ {
1532
+ const { legacyCodexLayer } = require('./codex-legacy');
1533
+ const legacy = legacyCodexLayer(target);
1534
+ if (legacy !== null) {
1535
+ const rel = path.relative(target, legacy.path).split(path.sep).join('/');
1536
+ add('codex legacy wiring', 'WARN', `${(0, codex_oracle_1.clipText)(legacy.path)} holds only the Holmes wiring an older init wrote (\`${(0, codex_oracle_1.clipText)(legacy.launch)}\`); in a trusted project Codex loads it instead of the user-level wiring`, `Remove it: git rm ${(0, codex_oracle_1.clipText)(rel)} (or delete it), or run holmes-kit init --agent codex and confirm the removal.`);
1537
+ }
1538
+ }
1508
1539
  let cdxRaw;
1509
1540
  // @implements A-SPEC-731 (round 6) — decoded strictly: Codex refuses a config that is not UTF-8.
1510
1541
  let cdxUndecodable = null;
@@ -1261,6 +1261,27 @@ async function main(argv) {
1261
1261
  process.stdout.write(c.after.split('\n').map((l) => ` | ${(0, doctor_1.terminalSafe)(l)}`).join('\n') + '\n');
1262
1262
  }
1263
1263
  }
1264
+ // @implements A-SPEC-721 (amendment 2026-09-29) — a Holmes-only project Codex file from a pre-0.30 init replaces the
1265
+ // user-level wiring in a trusted project: offered for removal after the user's yes (non-interactive: the command).
1266
+ if (!opts.remove && agents.includes('codex')) {
1267
+ const { offerLegacyCodexRemoval } = require('./codex-legacy');
1268
+ await offerLegacyCodexRemoval({
1269
+ target: opts.target, dryRun: opts.dryRun === true,
1270
+ interactive: process.stdin.isTTY === true && process.stdout.isTTY === true,
1271
+ confirm: async (q) => {
1272
+ const rl = require('node:readline/promises').createInterface({ input: process.stdin, output: process.stdout });
1273
+ try {
1274
+ const ans = (await rl.question(q)).trim().toLowerCase();
1275
+ return ans === 'y' || ans === 'yes';
1276
+ }
1277
+ finally {
1278
+ rl.close();
1279
+ }
1280
+ },
1281
+ remove: (f) => fs.rmSync(f),
1282
+ out: (l) => process.stdout.write(`${(0, doctor_1.terminalSafe)(l)}\n`),
1283
+ });
1284
+ }
1264
1285
  // @implements A-SPEC-543.1 — zero-config upgrade PREPARATION: a successful real wiring records
1265
1286
  // WHERE holmes-kit is wired, so `upgrade` later knows every workspace to re-pin. Best-effort by
1266
1287
  // contract: a registry problem must never change init's output or exit code.
@@ -1303,7 +1324,10 @@ async function main(argv) {
1303
1324
  // non-TTY passes --yes), never a silent auto-install of a gate-enforcing engine.
1304
1325
  if (cmd === 'upgrade') {
1305
1326
  const { runUpgrade } = require('./upgrade');
1327
+ const { queryRegistryLatest } = require('../update/refresh');
1306
1328
  return await runUpgrade({
1329
+ // A-SPEC-543.2 (amendment 2026-09-29): the explicit command asks the registry for latest.
1330
+ queryLatest: () => queryRegistryLatest(),
1307
1331
  dryRun: flags['dry-run'] === true,
1308
1332
  yes: flags.yes === true,
1309
1333
  stdout: (s) => process.stdout.write(s),
@@ -5,6 +5,11 @@ export interface UpgradeIO {
5
5
  stdout: (s: string) => void;
6
6
  stderr: (s: string) => void;
7
7
  confirm: (prompt: string) => Promise<boolean>;
8
+ /**
9
+ * A-SPEC-543.2 (amendment 2026-09-29) — asks the registry for latest; the CLI passes `queryRegistryLatest`. A caller
10
+ * that passes nothing makes no query and the update cache decides.
11
+ */
12
+ queryLatest?: () => Promise<string | null>;
8
13
  }
9
14
  /** What upgrade does with one registered workspace — decided once, shown in the plan and done in the run. */
10
15
  interface RepinDecision {
@@ -144,6 +144,18 @@ async function runUpgrade(io) {
144
144
  const current = currentVersion(root);
145
145
  const mode = (0, session_start_1.detectInstallMode)(root);
146
146
  const cached = (0, update_notice_1.readCache)(os.homedir(), (p) => fs.readFileSync(p, 'utf8'));
147
+ // A-SPEC-543.2 (amendment 2026-09-29): the registry is asked first — the cache alone kept a release unseen for up to a
148
+ // day ("already up to date (current 0.31.0, latest 0.30.0)", measured). A fresh answer refreshes the cache.
149
+ const now = Date.now();
150
+ const fresh = io.queryLatest ? await io.queryLatest().catch(() => null) : null;
151
+ if (fresh !== null && !io.dryRun) { // --dry-run asks and shows, and writes nothing
152
+ try {
153
+ fs.mkdirSync(path.join(os.homedir(), '.holmes'), { recursive: true });
154
+ fs.writeFileSync(path.join(os.homedir(), '.holmes', 'update-check.json'), JSON.stringify({ latest: fresh, checkedAt: now }));
155
+ }
156
+ catch { /* the cache is a convenience; the plan below uses the fresh answer either way */ }
157
+ }
158
+ const resolved = (0, upgrade_plan_1.resolveLatest)({ fresh, cached: cached ? { latest: cached.latest, checkedAt: cached.checkedAt } : null, now });
147
159
  const registry = (() => {
148
160
  try {
149
161
  return (0, workspaces_1.readRegistry)(fs.readFileSync(path.join(os.homedir(), '.holmes', 'workspaces.json'), 'utf8'));
@@ -152,7 +164,7 @@ async function runUpgrade(io) {
152
164
  return (0, workspaces_1.readRegistry)(null);
153
165
  }
154
166
  })();
155
- const plan = (0, upgrade_plan_1.planUpgrade)({ current, latest: cached?.latest ?? null, registry, installMode: mode });
167
+ const plan = (0, upgrade_plan_1.planUpgrade)({ current, latest: resolved.latest, registry, installMode: mode, latestNote: (0, upgrade_plan_1.describeLatest)(resolved) });
156
168
  if (plan.kind === 'noop') {
157
169
  io.stdout(`${plan.reason}\n`);
158
170
  return 0;
@@ -21,6 +21,11 @@ export declare function parseLatest(body: string): string | null;
21
21
  * caller's decision — this always attempts.
22
22
  */
23
23
  export declare function refreshCache(opts: RefreshOpts): Promise<boolean>;
24
+ /**
25
+ * @implements A-SPEC-543.2 (amendment 2026-09-29) — the registry's latest, asked now: `node:https` GET of REGISTRY_URL
26
+ * with a 5 s timeout, `parseLatest`, null on any failure. What `holmes-kit upgrade` asks before it plans.
27
+ */
28
+ export declare function queryRegistryLatest(timeoutMs?: number): Promise<string | null>;
24
29
  export interface SpawnRefreshOpts {
25
30
  home: string;
26
31
  env: NodeJS.ProcessEnv;
@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.REGISTRY_URL = void 0;
37
37
  exports.parseLatest = parseLatest;
38
38
  exports.refreshCache = refreshCache;
39
+ exports.queryRegistryLatest = queryRegistryLatest;
39
40
  exports.shouldRefreshCache = shouldRefreshCache;
40
41
  exports.maybeSpawnRefresh = maybeSpawnRefresh;
41
42
  // @implements A-SPEC-547.1
@@ -80,6 +81,28 @@ async function refreshCache(opts) {
80
81
  opts.writeFile(path.join(dir, 'update-check.json'), JSON.stringify({ latest, checkedAt: opts.now }));
81
82
  return true;
82
83
  }
84
+ /**
85
+ * @implements A-SPEC-543.2 (amendment 2026-09-29) — the registry's latest, asked now: `node:https` GET of REGISTRY_URL
86
+ * with a 5 s timeout, `parseLatest`, null on any failure. What `holmes-kit upgrade` asks before it plans.
87
+ */
88
+ function queryRegistryLatest(timeoutMs = 5000) {
89
+ return new Promise((resolve) => {
90
+ try {
91
+ const https = require('node:https');
92
+ const req = https.get(exports.REGISTRY_URL, { headers: { accept: 'application/vnd.npm.install-v1+json' } }, (res) => {
93
+ let d = '';
94
+ res.on('data', (c) => (d += c));
95
+ res.on('end', () => resolve(res.statusCode === 200 ? parseLatest(d) : null));
96
+ res.on('error', () => resolve(null));
97
+ });
98
+ req.on('error', () => resolve(null));
99
+ req.setTimeout(timeoutMs, () => { req.destroy(); resolve(null); });
100
+ }
101
+ catch {
102
+ resolve(null);
103
+ }
104
+ });
105
+ }
83
106
  /**
84
107
  * @implements A-SPEC-547.2
85
108
  * Pure: whether a network refresh should fire now — network allowed (not opted out / not CI) AND the
@@ -23,7 +23,35 @@ export declare function planUpgrade(a: {
23
23
  latest: string | null;
24
24
  registry: Registry;
25
25
  installMode: InstallMode;
26
+ /** Where latest came from (`describeLatest`), appended to a noop reason. */
27
+ latestNote?: string;
26
28
  }): UpgradePlan;
29
+ /** Where `upgrade` found latest: the registry just now, the update cache (with its age), or nowhere. */
30
+ export type ResolvedLatest = {
31
+ latest: string;
32
+ source: 'registry';
33
+ } | {
34
+ latest: string;
35
+ source: 'cache';
36
+ ageMs: number;
37
+ } | {
38
+ latest: null;
39
+ source: 'none';
40
+ };
41
+ /**
42
+ * @implements A-SPEC-543.2 (amendment 2026-09-29) — pure: a fresh registry answer wins; without one the cache answers
43
+ * and keeps its age; with neither latest is unknown.
44
+ */
45
+ export declare function resolveLatest(a: {
46
+ fresh: string | null;
47
+ cached: {
48
+ latest: string;
49
+ checkedAt: number;
50
+ } | null;
51
+ now: number;
52
+ }): ResolvedLatest;
53
+ /** The words for where latest came from — the note `planUpgrade` appends. */
54
+ export declare function describeLatest(r: ResolvedLatest): string;
27
55
  /** The env switch that turns SessionStart's forward self-heal re-pin OFF. */
28
56
  export declare const NO_AUTO_REPIN_ENV = "HOLMES_NO_AUTO_REPIN";
29
57
  /**
@@ -2,6 +2,8 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.NO_AUTO_REPIN_ENV = void 0;
4
4
  exports.planUpgrade = planUpgrade;
5
+ exports.resolveLatest = resolveLatest;
6
+ exports.describeLatest = describeLatest;
5
7
  exports.repinDecision = repinDecision;
6
8
  // @implements A-SPEC-543.2
7
9
  const update_notice_1 = require("./update-notice");
@@ -13,14 +15,41 @@ const update_notice_1 = require("./update-notice");
13
15
  * (install-only, first machine).
14
16
  */
15
17
  function planUpgrade(a) {
18
+ const note = a.latestNote ? ` ${a.latestNote}` : '';
16
19
  if (a.latest === null) {
17
20
  return { kind: 'noop', reason: 'latest version unknown (registry unreachable and no cache) — nothing to plan' };
18
21
  }
19
- if ((0, update_notice_1.compareSemver)(a.latest, a.current) <= 0) {
20
- return { kind: 'noop', reason: `already up to date (current ${a.current}, latest ${a.latest})` };
22
+ const order = (0, update_notice_1.compareSemver)(a.latest, a.current);
23
+ // A-SPEC-543.2 (amendment 2026-09-29): an installed version newer than latest means latest is stale — it is not
24
+ // "already up to date" (the report read `current 0.31.0, latest 0.30.0` from a cache that predated the release).
25
+ if (order < 0)
26
+ return { kind: 'noop', reason: `installed ${a.current} is newer than the latest ${a.latest}${note}` };
27
+ if (order === 0) {
28
+ return { kind: 'noop', reason: `already up to date (current ${a.current}, latest ${a.latest})${note}` };
21
29
  }
22
30
  return { kind: 'run', current: a.current, latest: a.latest, installMode: a.installMode, repins: a.registry.workspaces };
23
31
  }
32
+ /**
33
+ * @implements A-SPEC-543.2 (amendment 2026-09-29) — pure: a fresh registry answer wins; without one the cache answers
34
+ * and keeps its age; with neither latest is unknown.
35
+ */
36
+ function resolveLatest(a) {
37
+ if (a.fresh !== null)
38
+ return { latest: a.fresh, source: 'registry' };
39
+ if (a.cached !== null)
40
+ return { latest: a.cached.latest, source: 'cache', ageMs: Math.max(0, a.now - a.cached.checkedAt) };
41
+ return { latest: null, source: 'none' };
42
+ }
43
+ /** The words for where latest came from — the note `planUpgrade` appends. */
44
+ function describeLatest(r) {
45
+ if (r.source === 'registry')
46
+ return '(registry)';
47
+ if (r.source === 'none')
48
+ return '';
49
+ const minutes = Math.round(r.ageMs / 60_000);
50
+ const age = minutes < 60 ? `${minutes} min` : `${Math.round(r.ageMs / 3_600_000)} h`;
51
+ return `(cached check from ${age} ago — the registry could not be reached)`;
52
+ }
24
53
  /** The env switch that turns SessionStart's forward self-heal re-pin OFF. */
25
54
  exports.NO_AUTO_REPIN_ENV = 'HOLMES_NO_AUTO_REPIN';
26
55
  /**
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "@implements A-SPEC-209",
3
3
  "name": "@holmes-lab/holmes-kit",
4
- "version": "0.31.0",
4
+ "version": "0.31.2",
5
5
  "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
6
6
  "main": "dist/holmes/mcp/server.js",
7
7
  "types": "dist/holmes/mcp/server.d.ts",