projectstore-claude 0.29.3 → 0.30.0

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 (57) hide show
  1. package/README.md +13 -12
  2. package/bin/projectstore-claude.mjs +2 -2
  3. package/node_modules/projectstore/.claude-plugin/marketplace.json +1 -1
  4. package/node_modules/projectstore/.claude-plugin/plugin.json +1 -1
  5. package/node_modules/projectstore/README.md +153 -77
  6. package/node_modules/projectstore/commands/bind.md +6 -17
  7. package/node_modules/projectstore/commands/doctor.md +12 -7
  8. package/node_modules/projectstore/commands/statusline.md +1 -1
  9. package/node_modules/projectstore/commands/story.md +15 -2
  10. package/node_modules/projectstore/docs/extending.md +11 -6
  11. package/node_modules/projectstore/docs/getting-started.md +21 -1
  12. package/node_modules/projectstore/docs/harnesses.md +13 -10
  13. package/node_modules/projectstore/docs/how-it-works.md +6 -4
  14. package/node_modules/projectstore/harnesses/claude-code.json +16 -15
  15. package/node_modules/projectstore/harnesses/codex.json +12 -13
  16. package/node_modules/projectstore/hooks/band.tsx +48 -20
  17. package/node_modules/projectstore/hooks/pre-compact.mjs +7 -10
  18. package/node_modules/projectstore/hooks/session-rules.mjs +14 -8
  19. package/node_modules/projectstore/hooks/session-start.mjs +50 -18
  20. package/node_modules/projectstore/hooks/session-stop.mjs +8 -6
  21. package/node_modules/projectstore/package.json +11 -2
  22. package/node_modules/projectstore/scripts/band-shared.mjs +141 -24
  23. package/node_modules/projectstore/scripts/band.mjs +72 -21
  24. package/node_modules/projectstore/scripts/binding.mjs +616 -85
  25. package/node_modules/projectstore/scripts/build-adapters.mjs +73 -29
  26. package/node_modules/projectstore/scripts/cli.mjs +1015 -185
  27. package/node_modules/projectstore/scripts/codemap.mjs +22 -7
  28. package/node_modules/projectstore/scripts/convergence.mjs +253 -83
  29. package/node_modules/projectstore/scripts/diff-refs.mjs +14 -8
  30. package/node_modules/projectstore/scripts/doctor-report.mjs +91 -23
  31. package/node_modules/projectstore/scripts/doctor.mjs +1317 -371
  32. package/node_modules/projectstore/scripts/draft.mjs +5 -2
  33. package/node_modules/projectstore/scripts/fetch-shell.mjs +188 -39
  34. package/node_modules/projectstore/scripts/graph.mjs +19 -13
  35. package/node_modules/projectstore/scripts/harness.mjs +123 -48
  36. package/node_modules/projectstore/scripts/install-harness.mjs +3532 -618
  37. package/node_modules/projectstore/scripts/kanban.mjs +2 -1
  38. package/node_modules/projectstore/scripts/lib.mjs +694 -159
  39. package/node_modules/projectstore/scripts/mcp.mjs +386 -105
  40. package/node_modules/projectstore/scripts/portable-registration.mjs +224 -51
  41. package/node_modules/projectstore/scripts/provenance.mjs +26 -10
  42. package/node_modules/projectstore/scripts/query.mjs +378 -80
  43. package/node_modules/projectstore/scripts/reconcile.mjs +55 -18
  44. package/node_modules/projectstore/scripts/run-host.mjs +62 -17
  45. package/node_modules/projectstore/scripts/scaffold.mjs +89 -28
  46. package/node_modules/projectstore/scripts/setup.mjs +987 -0
  47. package/node_modules/projectstore/scripts/stages.mjs +5 -1
  48. package/node_modules/projectstore/scripts/statusline-launcher.mjs +36 -11
  49. package/node_modules/projectstore/scripts/statusline.mjs +32 -14
  50. package/node_modules/projectstore/scripts/story-section.mjs +39 -17
  51. package/node_modules/projectstore/scripts/surfaces.mjs +416 -95
  52. package/node_modules/projectstore/scripts/term.mjs +382 -97
  53. package/node_modules/projectstore/scripts/tokens.mjs +106 -28
  54. package/node_modules/projectstore/scripts/touch-session.mjs +109 -70
  55. package/node_modules/projectstore/scripts/version-guard.mjs +74 -27
  56. package/node_modules/projectstore/scripts/worktree.mjs +16 -5
  57. package/package.json +3 -3
@@ -27,7 +27,7 @@
27
27
  import { readFileSync, existsSync, realpathSync, readdirSync } from "node:fs";
28
28
  import { join, resolve } from "node:path";
29
29
  import { homedir } from "node:os";
30
- import { loadHarnesses, loadHarness, harnessIds, detectHarnesses, sourceHarness, MANIFEST_DIR } from "./harness.mjs";
30
+ import { loadHarnesses, harnessIds, detectHarnesses, sourceHarness, MANIFEST_DIR } from "./harness.mjs";
31
31
  import { stamp, deriveState, parseProvenance, sourceHash, STALE, STALE_TEXT, FOREIGN_TEXT } from "./provenance.mjs";
32
32
  import {
33
33
  pluginRoot,
@@ -55,10 +55,15 @@ import {
55
55
  commandForm,
56
56
  registrationProvenance,
57
57
  } from "./lib.mjs";
58
- import { analysePortableRegistration, portableRegistrationPaths, portablePayloadRoot } from "./portable-registration.mjs";
58
+ import {
59
+ analysePortableRegistration,
60
+ portableRegistrationPaths,
61
+ portablePayloadRoot,
62
+ } from "./portable-registration.mjs";
59
63
 
60
64
  export const GENERATOR = "scripts/install-harness.mjs";
61
- export const INSTALLED_REMEDY = "projectstore doctor reports this file when it is stale; run install again to refresh it.";
65
+ export const INSTALLED_REMEDY =
66
+ "projectstore doctor reports this file when it is stale; run install again to refresh it.";
62
67
  // The line every launcher has carried since the template was written; the
63
68
  // recogniser for a pre-provenance launcher (contract 4, rung 1″). A substring
64
69
  // of the template's own header, so a reworded comment cannot turn every
@@ -96,40 +101,85 @@ export function isOurFile(text) {
96
101
  // run names more than one: the migration reason then names the one whose
97
102
  // files lack the block's file, rather than the harness whose surface `s` is
98
103
  // (the story "One run plans the agents block once…", rules 1 and 3).
99
- export function analyseBlock(projectDir, s, { root = pluginRoot(), manifestDir = MANIFEST_DIR, layout = null, readers = null } = {}) {
104
+ export function analyseBlock(
105
+ projectDir,
106
+ s,
107
+ { root = pluginRoot(), manifestDir = MANIFEST_DIR, layout = null, readers = null } = {},
108
+ ) {
100
109
  const files = s.files || ["AGENTS.md", "CLAUDE.md"];
101
- const PREFERRED = files[0], FALLBACK = files[files.length - 1];
110
+ const PREFERRED = files[0],
111
+ FALLBACK = files[files.length - 1];
102
112
  // LOOK across every file any manifest names; WRITE to one this harness can
103
113
  // read. The two are different questions and conflating them is what let the
104
114
  // block be created twice: a harness that scanned only its own list could not
105
115
  // see the copy another harness had already written, so it created a second.
106
116
  // Scanning is free and static — the union is manifest data, not project
107
117
  // state — while the write target stays this manifest's own preference.
108
- const scan = [...files, ...[...loadHarnesses(manifestDir).values()]
109
- .flatMap((m) => m.surfaces?.agents_block?.files || [])
110
- .filter((f) => !files.includes(f))];
111
- const found = scan.map((f) => ({ file: f, path: join(projectDir, f), ...readText(join(projectDir, f)) }))
118
+ const scan = [
119
+ ...files,
120
+ ...[...loadHarnesses(manifestDir).values()]
121
+ .flatMap((m) => m.surfaces?.agents_block?.files || [])
122
+ .filter((f) => !files.includes(f)),
123
+ ];
124
+ const found = scan
125
+ .map((f) => ({ file: f, path: join(projectDir, f), ...readText(join(projectDir, f)) }))
112
126
  .map((e) => ({ ...e, block: e.text !== null ? findAgentsBlock(e.text) : null, own: files.includes(e.file) }));
113
127
  const withBlock = found.filter((e) => e.block);
114
128
  const preferred = found.find((e) => e.file === PREFERRED && e.present) || found.find((e) => e.file === FALLBACK);
115
129
  const claude = found.find((e) => e.file === FALLBACK);
116
130
  const importLine = `@${PREFERRED}`;
117
- const a = { files: found, own: files, withBlock, preferred, claude, importLine, PREFERRED, FALLBACK, entryKey: "projectstore:agents", version: null, desired: null, current: null, state: "ours-absent", reason: null, refusal: null };
131
+ const a = {
132
+ files: found,
133
+ own: files,
134
+ withBlock,
135
+ preferred,
136
+ claude,
137
+ importLine,
138
+ PREFERRED,
139
+ FALLBACK,
140
+ entryKey: "projectstore:agents",
141
+ version: null,
142
+ desired: null,
143
+ current: null,
144
+ state: "ours-absent",
145
+ reason: null,
146
+ refusal: null,
147
+ };
118
148
 
119
149
  const unclosed = withBlock.find((e) => e.block.unclosed);
120
- if (unclosed && unclosed.block.wrapped) return { ...a, state: "unparseable", refusal: `${unclosed.file}:${unclosed.block.line}: the projectstore:agents open marker does not close on its own line — the parser reads one line. Put \`-->\` back on the marker's line, then run ${commandForm("agents", { args: "register" })}` };
121
- if (unclosed) return { ...a, state: "unparseable", refusal: `${unclosed.file}: the block opens and never closes — restore the closing marker or remove the block by hand` };
150
+ if (unclosed && unclosed.block.wrapped)
151
+ return {
152
+ ...a,
153
+ state: "unparseable",
154
+ refusal: `${unclosed.file}:${unclosed.block.line}: the projectstore:agents open marker does not close on its own line — the parser reads one line. Put \`-->\` back on the marker's line, then run ${commandForm("agents", { args: "register" })}`,
155
+ };
156
+ if (unclosed)
157
+ return {
158
+ ...a,
159
+ state: "unparseable",
160
+ refusal: `${unclosed.file}: the block opens and never closes — restore the closing marker or remove the block by hand`,
161
+ };
122
162
  const twice = withBlock.find((e) => e.block.count > 1);
123
- if (twice) return { ...a, state: "unparseable", refusal: `${twice.file} carries the block more than once — keep exactly one` };
163
+ if (twice)
164
+ return { ...a, state: "unparseable", refusal: `${twice.file} carries the block more than once — keep exactly one` };
124
165
 
125
166
  const tmpl = readText(agentsBlockTemplatePath(root));
126
- if (!tmpl.present || tmpl.text === null) return { ...a, state: "unparseable", refusal: `the block's source is missing from the plugin at ${agentsBlockTemplatePath(root)}` };
167
+ if (!tmpl.present || tmpl.text === null)
168
+ return {
169
+ ...a,
170
+ state: "unparseable",
171
+ refusal: `the block's source is missing from the plugin at ${agentsBlockTemplatePath(root)}`,
172
+ };
127
173
  a.version = agentsBlockVersion(tmpl.text);
128
174
  const cfg = readConfigAt(projectDir);
129
175
  let roster = null;
130
176
  const name = layout ?? cfg?.layout;
131
177
  if (typeof name === "string") {
132
- try { roster = loadLayout(name, root).agents || null; } catch { roster = null; }
178
+ try {
179
+ roster = loadLayout(name, root).agents || null;
180
+ } catch {
181
+ roster = null;
182
+ }
133
183
  }
134
184
  a.desired = renderAgentsBlock(tmpl.text, roster);
135
185
  a.current = withBlock.find((e) => e.file === preferred.file) || withBlock[0] || null;
@@ -144,12 +194,29 @@ export function analyseBlock(projectDir, s, { root = pluginRoot(), manifestDir =
144
194
  // CLAUDE.md importing it.
145
195
  if (!a.current.own) {
146
196
  const reader = readers?.find((r) => !(r.files || []).includes(a.current.file))?.display;
147
- return { ...a, state: "ours-stale", reason: `in ${a.current.file}, which ${reader || s.harness_display || "this harness"} does not read; install moves it to ${preferred.file}` };
197
+ return {
198
+ ...a,
199
+ state: "ours-stale",
200
+ reason: `in ${a.current.file}, which ${reader || s.harness_display || "this harness"} does not read; install moves it to ${preferred.file}`,
201
+ };
148
202
  }
149
- if (a.current.file !== preferred.file && preferred.present) return { ...a, state: "ours-stale", reason: `in ${a.current.file}; install migrates it to ${preferred.file}` };
150
- if (a.duplicates.length) return { ...a, state: "ours-stale", reason: `also in ${a.duplicates.map((e) => e.file).join(", ")}; install keeps the one in ${a.current.file}` };
203
+ if (a.current.file !== preferred.file && preferred.present)
204
+ return { ...a, state: "ours-stale", reason: `in ${a.current.file}; install migrates it to ${preferred.file}` };
205
+ if (a.duplicates.length)
206
+ return {
207
+ ...a,
208
+ state: "ours-stale",
209
+ reason: `also in ${a.duplicates.map((e) => e.file).join(", ")}; install keeps the one in ${a.current.file}`,
210
+ };
151
211
  if (a.current.block.v === a.version && a.current.block.block === a.desired) return { ...a, state: "ours-current" };
152
- return { ...a, state: "ours-stale", reason: a.current.block.v !== a.version ? `v${a.current.block.v} → v${a.version}` : "content differs from the current source" };
212
+ return {
213
+ ...a,
214
+ state: "ours-stale",
215
+ reason:
216
+ a.current.block.v !== a.version
217
+ ? `v${a.current.block.v} → v${a.version}`
218
+ : "content differs from the current source",
219
+ };
153
220
  }
154
221
 
155
222
  // ─── json-entry: one entry in a JSON file the user co-owns ─────────────
@@ -162,18 +229,40 @@ export function analyseJsonEntry(projectDir, s, { root = pluginRoot(), home = ho
162
229
  const pointer = s.marker?.pointer || "statusLine.command";
163
230
  const entryKey = pointer.split(".")[0];
164
231
  const cur = readText(path);
165
- const a = { path, entryKey, cur, settings: {}, curEntry: null, curCmd: null, ours: false, desired: null, state: "ours-absent", reason: null };
232
+ const a = {
233
+ path,
234
+ entryKey,
235
+ cur,
236
+ settings: {},
237
+ curEntry: null,
238
+ curCmd: null,
239
+ ours: false,
240
+ desired: null,
241
+ state: "ours-absent",
242
+ reason: null,
243
+ };
166
244
  if (cur.present) {
167
245
  if (cur.text === null) return { ...a, state: "unparseable", reason: "the file cannot be read" };
168
- try { a.settings = JSON.parse(cur.text); } catch { return { ...a, state: "unparseable", reason: "the file is not valid JSON — nothing outside a marked entry is touched, so nothing is written" }; }
169
- if (!a.settings || typeof a.settings !== "object" || Array.isArray(a.settings)) return { ...a, state: "unparseable", reason: "the file is not a JSON object" };
246
+ try {
247
+ a.settings = JSON.parse(cur.text);
248
+ } catch {
249
+ return {
250
+ ...a,
251
+ state: "unparseable",
252
+ reason: "the file is not valid JSON — nothing outside a marked entry is touched, so nothing is written",
253
+ };
254
+ }
255
+ if (!a.settings || typeof a.settings !== "object" || Array.isArray(a.settings))
256
+ return { ...a, state: "unparseable", reason: "the file is not a JSON object" };
170
257
  }
171
258
  a.curEntry = a.settings[entryKey] ?? null;
172
259
  a.curCmd = a.curEntry && typeof a.curEntry.command === "string" ? a.curEntry.command : null;
173
260
  // "Did we write this?" is asked of the EXISTING entry, written by whatever
174
261
  // root was current then: a dev checkout's direct wiring stays ours when the
175
262
  // plan now renders against a registration's install path (reviewer, 2026-09-05).
176
- a.ours = statusLineIsOurWiring(a.curCmd, projectDir, home, root) || statusLineIsOurWiring(a.curCmd, projectDir, home, renderRoot);
263
+ a.ours =
264
+ statusLineIsOurWiring(a.curCmd, projectDir, home, root) ||
265
+ statusLineIsOurWiring(a.curCmd, projectDir, home, renderRoot);
177
266
  a.desired = desiredStatusLineCommand(projectDir, renderRoot, home).command;
178
267
  if (!a.curEntry) return { ...a, state: "ours-absent" };
179
268
  if (!a.ours) return { ...a, state: "theirs", reason: "a status line we did not write owns the slot" };
@@ -183,7 +272,11 @@ export function analyseJsonEntry(projectDir, s, { root = pluginRoot(), home = ho
183
272
 
184
273
  // ─── mjs: an exclusive, provenance-stamped file ────────────────────────
185
274
 
186
- export function analyseStampedFile(projectDir, s, { root = pluginRoot(), home = homedir(), harness = null, renderRoot = root } = {}) {
275
+ export function analyseStampedFile(
276
+ projectDir,
277
+ s,
278
+ { root = pluginRoot(), home = homedir(), harness = null, renderRoot = root } = {},
279
+ ) {
187
280
  const path = join(projectDir, s.file);
188
281
  let file = readText(path);
189
282
  // The manifest may name where an earlier release wrote this file
@@ -192,28 +285,74 @@ export function analyseStampedFile(projectDir, s, { root = pluginRoot(), home =
192
285
  const legacyPath = s.legacy_file ? join(projectDir, s.legacy_file) : null;
193
286
  const atLegacy = !file.present && legacyPath && existsSync(legacyPath);
194
287
  if (atLegacy) file = readText(legacyPath);
195
- const a = { path, file, produced: true, ours: null, refusal: null, stamped: null, state: "absent", reason: null, writtenBy: null, sameProject: false, legacy: false, renderRoot, legacyPath: atLegacy ? legacyPath : null };
288
+ const a = {
289
+ path,
290
+ file,
291
+ produced: true,
292
+ ours: null,
293
+ refusal: null,
294
+ stamped: null,
295
+ state: "absent",
296
+ reason: null,
297
+ writtenBy: null,
298
+ sameProject: false,
299
+ legacy: false,
300
+ renderRoot,
301
+ legacyPath: atLegacy ? legacyPath : null,
302
+ };
196
303
  if (s.condition === "plugin_cache_install" && !isPluginCacheRoot(renderRoot, home)) {
197
304
  // Not produced for this installation (a dev checkout is wired directly).
198
305
  a.produced = false;
199
306
  if (!file.present) return { ...a, state: "absent" };
200
307
  a.ours = isOurFile(file.text);
201
- return { ...a, state: a.ours ? "stale" : "foreign", reason: a.ours ? "not produced for this installation (a dev checkout is wired directly) — left in place; a prune of a launcher this root did not write needs the root that wrote it, or uninstall" : null };
308
+ return {
309
+ ...a,
310
+ state: a.ours ? "stale" : "foreign",
311
+ reason: a.ours
312
+ ? "not produced for this installation (a dev checkout is wired directly) — left in place; a prune of a launcher this root did not write needs the root that wrote it, or uninstall"
313
+ : null,
314
+ };
202
315
  }
203
316
  const src = join(root, s.source);
204
317
  const tpl = readText(src);
205
- if (!tpl.present || tpl.text === null) return { ...a, state: "unparseable", refusal: `the source ${s.source} is missing from the plugin at ${root}` };
318
+ if (!tpl.present || tpl.text === null)
319
+ return { ...a, state: "unparseable", refusal: `the source ${s.source} is missing from the plugin at ${root}` };
206
320
  const rendered = renderStatusLineLauncher(tpl.text, renderRoot, projectDir);
207
- if (rendered === null) return { ...a, state: "unparseable", refusal: "the launcher template is not one this installer knows how to fill" };
321
+ if (rendered === null)
322
+ return { ...a, state: "unparseable", refusal: "the launcher template is not one this installer knows how to fill" };
208
323
  const pkg = pluginVersionAt(root, harness) || "0.0.0";
209
324
  a.pkg = pkg;
210
- a.stamped = stamp(rendered, { format: s.format, src: s.source, srcHash: sourceHash(tpl.text), pkg, project: projectDir, harness: harness?.id || sourceHarness()?.id || "harness", generator: GENERATOR, remedy: INSTALLED_REMEDY });
211
- let st = deriveState({ file, sourceHash: sourceHash(tpl.text), pkg, renderNowHash: a.stamped.render, project: projectDir });
325
+ a.stamped = stamp(rendered, {
326
+ format: s.format,
327
+ src: s.source,
328
+ srcHash: sourceHash(tpl.text),
329
+ pkg,
330
+ project: projectDir,
331
+ harness: harness?.id || sourceHarness()?.id || "harness",
332
+ generator: GENERATOR,
333
+ remedy: INSTALLED_REMEDY,
334
+ });
335
+ let st = deriveState({
336
+ file,
337
+ sourceHash: sourceHash(tpl.text),
338
+ pkg,
339
+ renderNowHash: a.stamped.render,
340
+ project: projectDir,
341
+ });
212
342
  // Contract 4, rung 1″: a launcher written before provenance existed carries
213
343
  // no line but the template's own header. It is ours, stale, replaceable.
214
- if (st.state === "foreign" && typeof file.text === "string" && file.text.includes(LAUNCHER_HEADER)) { st = { ...st, state: "stale", reason: STALE.PLUGIN }; a.legacy = true; }
344
+ if (st.state === "foreign" && typeof file.text === "string" && file.text.includes(LAUNCHER_HEADER)) {
345
+ st = { ...st, state: "stale", reason: STALE.PLUGIN };
346
+ a.legacy = true;
347
+ }
215
348
  a.installedPkg = st.provenance?.pkg || null;
216
- return { ...a, state: st.state, reason: st.reason ? STALE_TEXT[st.reason] + (a.legacy ? " (pre-provenance file)" : "") : null, writtenBy: st.writtenBy, sameProject: st.sameProject };
349
+ return {
350
+ ...a,
351
+ state: st.state,
352
+ reason: st.reason ? STALE_TEXT[st.reason] + (a.legacy ? " (pre-provenance file)" : "") : null,
353
+ writtenBy: st.writtenBy,
354
+ sameProject: st.sameProject,
355
+ };
217
356
  }
218
357
 
219
358
  // ─── host-plugin-registration: our marketplace directory + the host's registry ──
@@ -225,12 +364,22 @@ export function analyseStampedFile(projectDir, s, { root = pluginRoot(), home =
225
364
  // located, never run.
226
365
 
227
366
  function samePath(a, b) {
228
- const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
367
+ const real = (p) => {
368
+ try {
369
+ return realpathSync(p);
370
+ } catch {
371
+ return resolve(p);
372
+ }
373
+ };
229
374
  return Boolean(a && b) && real(a) === real(b);
230
375
  }
231
376
 
232
377
  function readJson(p) {
233
- try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; }
378
+ try {
379
+ return JSON.parse(readFileSync(p, "utf8"));
380
+ } catch {
381
+ return null;
382
+ }
234
383
  }
235
384
 
236
385
  export function registrationPaths(s, { home = homedir(), projectDir = null, harness = null } = {}) {
@@ -250,35 +399,68 @@ export function registrationPaths(s, { home = homedir(), projectDir = null, harn
250
399
  };
251
400
  }
252
401
 
253
- export function analyseRegistration(projectDir, s, { root = pluginRoot(), home = homedir(), harness = null, env = process.env } = {}) {
402
+ export function analyseRegistration(
403
+ projectDir,
404
+ s,
405
+ { root = pluginRoot(), home = homedir(), harness = null, env = process.env } = {},
406
+ ) {
254
407
  const id = `${s.plugin_name}@${s.marketplace_name}`;
255
408
  const paths = registrationPaths(s, { home, projectDir, harness });
256
409
  const pkg = pluginVersionAt(root, harness) || "0.0.0";
257
- const a = { id, paths, path: paths.dir, entryKey: id, pkg, bin: whichOnPath(s.cli?.bin || "claude", env), produced: !(s.condition === "npm_package_root" && isPluginCacheRoot(root, home)),
258
- dir: { present: existsSync(paths.dir), manifest: null, prov: null, pkg: null, disabled: [], digestOk: null }, known: null, registeredHere: null, installed: null, installedVersion: null, installPath: null,
259
- enabled: null, others: [], otherProjects: 0, writtenBy: null, newer: false, state: "absent", reason: null, refusal: null };
410
+ const a = {
411
+ id,
412
+ paths,
413
+ path: paths.dir,
414
+ entryKey: id,
415
+ pkg,
416
+ bin: whichOnPath(s.cli?.bin || "claude", env),
417
+ produced: !(s.condition === "npm_package_root" && isPluginCacheRoot(root, home)),
418
+ dir: { present: existsSync(paths.dir), manifest: null, prov: null, pkg: null, disabled: [], digestOk: null },
419
+ known: null,
420
+ registeredHere: null,
421
+ installed: null,
422
+ installedVersion: null,
423
+ installPath: null,
424
+ enabled: null,
425
+ others: [],
426
+ otherProjects: 0,
427
+ writtenBy: null,
428
+ newer: false,
429
+ state: "absent",
430
+ reason: null,
431
+ refusal: null,
432
+ };
260
433
 
261
434
  // Machine-global facts: our directory, the host's marketplace registry, every row of ours.
262
435
  if (a.dir.present) {
263
436
  a.dir.manifest = readJson(paths.manifest);
264
437
  const prov = registrationProvenance(a.dir.manifest, s);
265
438
  if (prov) {
266
- a.dir.prov = prov; a.dir.pkg = prov.pkg;
439
+ a.dir.prov = prov;
440
+ a.dir.pkg = prov.pkg;
267
441
  a.dir.disabled = Array.isArray(prov.disabled) ? prov.disabled.filter((x) => typeof x === "string") : [];
268
442
  if (typeof prov.project === "string" && !samePath(prov.project, projectDir)) a.writtenBy = prov.project;
269
443
  // The payload digest: a copy that did not finish, or a hand edit, is not current.
270
444
  if (prov.digest && typeof prov.digest.sha256 === "string") {
271
- try { const d = treeDigest(paths.payload); a.dir.digestOk = d.count === prov.digest.count && d.sha256 === prov.digest.sha256; } catch { a.dir.digestOk = false; }
445
+ try {
446
+ const d = treeDigest(paths.payload);
447
+ a.dir.digestOk = d.count === prov.digest.count && d.sha256 === prov.digest.sha256;
448
+ } catch {
449
+ a.dir.digestOk = false;
450
+ }
272
451
  } else a.dir.digestOk = null; // no digest recorded: nothing to compare
273
452
  }
274
453
  }
275
454
  const known = readJson(paths.marketplaces);
276
455
  const mp = known && known[s.marketplace_name];
277
- a.known = mp ? { path: (mp.installLocation || mp.source?.path || null), source: mp.source?.source || null } : null;
456
+ a.known = mp ? { path: mp.installLocation || mp.source?.path || null, source: mp.source?.source || null } : null;
278
457
  const all = installedPluginEntries(home, projectDir).filter((e) => e.key === id);
279
458
  // Per-project facts: the checkout's own settings file and the registry row carrying its path.
280
459
  const local = readJson(paths.projectSettings);
281
- const here = local && local[s.registry?.known_pointer || "extraKnownMarketplaces"] && local[s.registry?.known_pointer || "extraKnownMarketplaces"][s.marketplace_name];
460
+ const here =
461
+ local &&
462
+ local[s.registry?.known_pointer || "extraKnownMarketplaces"] &&
463
+ local[s.registry?.known_pointer || "extraKnownMarketplaces"][s.marketplace_name];
282
464
  a.registeredHere = here ? { path: here.source?.path || null } : null;
283
465
  const enabledHere = (local && local[s.registry?.enabled_pointer || "enabledPlugins"]) || {};
284
466
  a.disabledHere = Object.keys(enabledHere).filter((k) => enabledHere[k] === false);
@@ -302,7 +484,12 @@ export function analyseRegistration(projectDir, s, { root = pluginRoot(), home =
302
484
  // this package's — contract 4's rung 3 (source changed) for a directory.
303
485
  a.contentDiffers = null;
304
486
  if (a.dir.prov && a.dir.pkg === pkg && a.dir.prov.digest && typeof a.dir.prov.digest.sha256 === "string") {
305
- try { const d = packageDigest(root); a.contentDiffers = d.sha256 !== a.dir.prov.digest.sha256 || d.count !== a.dir.prov.digest.count; } catch { a.contentDiffers = null; }
487
+ try {
488
+ const d = packageDigest(root);
489
+ a.contentDiffers = d.sha256 !== a.dir.prov.digest.sha256 || d.count !== a.dir.prov.digest.count;
490
+ } catch {
491
+ a.contentDiffers = null;
492
+ }
306
493
  }
307
494
  // The version the host would install from the directory as it will stand after this run.
308
495
  a.targetPkg = a.newer ? a.dir.pkg : pkg;
@@ -312,22 +499,91 @@ export function analyseRegistration(projectDir, s, { root = pluginRoot(), home =
312
499
  const bin = s.cli?.bin || "claude";
313
500
 
314
501
  // The ladder (contract 4′).
315
- if (!a.bin && nothingOfOurs) return { ...a, state: "unavailable", reason: `\`${bin}\` is not on PATH — the registration needs the host's CLI; the other surfaces still install` };
316
- if (a.dir.present && !a.dir.prov) return { ...a, state: "foreign", refusal: `${paths.dir} exists and its ${s.manifest} carries no \`${s.provenance_key}\` field of ours — a directory we did not write sits at our path; move it if it is yours, or delete it to let install take the name` };
317
- if (a.known && a.known.path && !samePath(a.known.path, paths.dir)) return { ...a, state: "foreign", refusal: `the host's registry names marketplace \`${s.marketplace_name}\` at ${a.known.path}, not at ${paths.dir} — a registration we did not make holds our name; \`${bin} plugin marketplace remove ${s.marketplace_name}\` lets install take it` };
318
- if (a.registeredHere && a.registeredHere.path && !samePath(a.registeredHere.path, paths.dir)) return { ...a, state: "foreign", refusal: `${paths.projectSettings} declares marketplace \`${s.marketplace_name}\` at ${a.registeredHere.path}, not at ${paths.dir} — remove that entry to let install take the name` };
502
+ if (!a.bin && nothingOfOurs)
503
+ return {
504
+ ...a,
505
+ state: "unavailable",
506
+ reason: `\`${bin}\` is not on PATH — the registration needs the host's CLI; the other surfaces still install`,
507
+ };
508
+ if (a.dir.present && !a.dir.prov)
509
+ return {
510
+ ...a,
511
+ state: "foreign",
512
+ refusal: `${paths.dir} exists and its ${s.manifest} carries no \`${s.provenance_key}\` field of ours — a directory we did not write sits at our path; move it if it is yours, or delete it to let install take the name`,
513
+ };
514
+ if (a.known && a.known.path && !samePath(a.known.path, paths.dir))
515
+ return {
516
+ ...a,
517
+ state: "foreign",
518
+ refusal: `the host's registry names marketplace \`${s.marketplace_name}\` at ${a.known.path}, not at ${paths.dir} — a registration we did not make holds our name; \`${bin} plugin marketplace remove ${s.marketplace_name}\` lets install take it`,
519
+ };
520
+ if (a.registeredHere && a.registeredHere.path && !samePath(a.registeredHere.path, paths.dir))
521
+ return {
522
+ ...a,
523
+ state: "foreign",
524
+ refusal: `${paths.projectSettings} declares marketplace \`${s.marketplace_name}\` at ${a.registeredHere.path}, not at ${paths.dir} — remove that entry to let install take the name`,
525
+ };
319
526
  if (nothingOfOurs) return { ...a, state: "absent" };
320
527
  // The directory is shared by every checkout on the machine; a project that never registered is absent, whatever the directory holds.
321
- if (nothingOfOursHere) return { ...a, state: "absent", reason: a.dir.present ? `the marketplace directory is present${a.writtenBy ? ` (written from ${a.writtenBy})` : ""}; this checkout is not registered` : null };
528
+ if (nothingOfOursHere)
529
+ return {
530
+ ...a,
531
+ state: "absent",
532
+ reason: a.dir.present
533
+ ? `the marketplace directory is present${a.writtenBy ? ` (written from ${a.writtenBy})` : ""}; this checkout is not registered`
534
+ : null,
535
+ };
322
536
  if (!a.dir.present) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + " (the directory is gone)" };
323
- if (cmpPrecedence(a.dir.pkg, pkg) < 0) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + ` (directory at ${a.dir.pkg}, package at ${pkg})` };
324
- if (a.dir.digestOk === false) return { ...a, state: "stale", reason: "edited by hand or half-written (the payload does not match the digest its manifest carries)" };
325
- if (a.contentDiffers === true) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + ` (same version ${pkg}, different content — the directory's digest is not this package's)` };
326
- if (!a.known || !a.registeredHere) return { ...a, state: "stale", reason: STALE_TEXT[STALE.CONFIG] + (a.known ? " (this checkout does not declare the marketplace)" : " (the host does not know the marketplace)") };
327
- if (!a.installed || !a.installed.present) return { ...a, state: "stale", reason: "not installed" + (a.installed ? " (the host's install path is gone)" : " (registered, not installed for this checkout)") };
328
- if (a.installedVersion !== a.dir.pkg) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + ` (installed ${a.installedVersion}, directory ${a.dir.pkg})` };
537
+ if (cmpPrecedence(a.dir.pkg, pkg) < 0)
538
+ return {
539
+ ...a,
540
+ state: "stale",
541
+ reason: STALE_TEXT[STALE.PLUGIN] + ` (directory at ${a.dir.pkg}, package at ${pkg})`,
542
+ };
543
+ if (a.dir.digestOk === false)
544
+ return {
545
+ ...a,
546
+ state: "stale",
547
+ reason: "edited by hand or half-written (the payload does not match the digest its manifest carries)",
548
+ };
549
+ if (a.contentDiffers === true)
550
+ return {
551
+ ...a,
552
+ state: "stale",
553
+ reason:
554
+ STALE_TEXT[STALE.PLUGIN] +
555
+ ` (same version ${pkg}, different content — the directory's digest is not this package's)`,
556
+ };
557
+ if (!a.known || !a.registeredHere)
558
+ return {
559
+ ...a,
560
+ state: "stale",
561
+ reason:
562
+ STALE_TEXT[STALE.CONFIG] +
563
+ (a.known ? " (this checkout does not declare the marketplace)" : " (the host does not know the marketplace)"),
564
+ };
565
+ if (!a.installed || !a.installed.present)
566
+ return {
567
+ ...a,
568
+ state: "stale",
569
+ reason:
570
+ "not installed" +
571
+ (a.installed ? " (the host's install path is gone)" : " (registered, not installed for this checkout)"),
572
+ };
573
+ if (a.installedVersion !== a.dir.pkg)
574
+ return {
575
+ ...a,
576
+ state: "stale",
577
+ reason: STALE_TEXT[STALE.PLUGIN] + ` (installed ${a.installedVersion}, directory ${a.dir.pkg})`,
578
+ };
329
579
  if (!a.enabled) return { ...a, state: "stale", reason: "disabled for this checkout" };
330
- return { ...a, state: "current", reason: a.newer ? `the directory is at ${a.dir.pkg}, newer than this package (${pkg})${a.writtenBy ? `, written from ${a.writtenBy}` : ""} — not downgraded` : null };
580
+ return {
581
+ ...a,
582
+ state: "current",
583
+ reason: a.newer
584
+ ? `the directory is at ${a.dir.pkg}, newer than this package (${pkg})${a.writtenBy ? `, written from ${a.writtenBy}` : ""} — not downgraded`
585
+ : null,
586
+ };
331
587
  }
332
588
 
333
589
  // The root a registration renders the project's dependent surfaces against,
@@ -350,13 +606,27 @@ export function analyseLayout(projectDir, { harness = null } = {}) {
350
606
  const has = (f) => existsSync(f);
351
607
  const legacy = {
352
608
  dir: p.legacy.dir,
353
- binding: has(p.legacy.binding), runtime: has(p.legacy.runtime), state: has(p.legacy.state), launcher: has(p.legacy.launcher),
354
- entryLog: has(p.legacy.entryLog), welcomed: has(p.legacy.welcomed), sessionId: has(p.legacy.sessionId),
355
- runtimeOurs: false, stateFiles: [],
609
+ binding: has(p.legacy.binding),
610
+ runtime: has(p.legacy.runtime),
611
+ state: has(p.legacy.state),
612
+ launcher: has(p.legacy.launcher),
613
+ entryLog: has(p.legacy.entryLog),
614
+ welcomed: has(p.legacy.welcomed),
615
+ sessionId: has(p.legacy.sessionId),
616
+ runtimeOurs: false,
617
+ stateFiles: [],
356
618
  };
357
619
  if (legacy.runtime) {
358
- try { legacy.runtimeOurs = readFileSync(p.legacy.gitignore, "utf8").includes(RUNTIME_GITIGNORE_HEADER); } catch { legacy.runtimeOurs = false; }
359
- if (legacy.state) { try { legacy.stateFiles = readdirSync(p.legacy.state).filter((n) => n !== ".gitignore"); } catch {} }
620
+ try {
621
+ legacy.runtimeOurs = readFileSync(p.legacy.gitignore, "utf8").includes(RUNTIME_GITIGNORE_HEADER);
622
+ } catch {
623
+ legacy.runtimeOurs = false;
624
+ }
625
+ if (legacy.state) {
626
+ try {
627
+ legacy.stateFiles = readdirSync(p.legacy.state).filter((n) => n !== ".gitignore");
628
+ } catch {}
629
+ }
360
630
  }
361
631
  const current = { root: has(p.root), binding: has(p.binding) };
362
632
  const any = legacy.binding || legacy.runtime || legacy.welcomed || legacy.sessionId;
@@ -365,16 +635,21 @@ export function analyseLayout(projectDir, { harness = null } = {}) {
365
635
  let resumable = false;
366
636
  if (legacy.binding && current.binding) {
367
637
  try {
368
- const { agents, ...oldRest } = JSON.parse(readFileSync(p.legacy.binding, "utf8"));
638
+ const { agents: _agents, ...oldRest } = JSON.parse(readFileSync(p.legacy.binding, "utf8"));
369
639
  const cur = JSON.parse(readFileSync(p.binding, "utf8"));
370
640
  resumable = JSON.stringify(oldRest) === JSON.stringify(cur);
371
- } catch { resumable = false; }
641
+ } catch {
642
+ resumable = false;
643
+ }
372
644
  }
373
645
  return {
374
- paths: p, legacy, current, resumable,
646
+ paths: p,
647
+ legacy,
648
+ current,
649
+ resumable,
375
650
  twoConfigs: legacy.binding && current.binding,
376
651
  pending: any,
377
- state: !any ? "current" : (legacy.binding && current.binding) ? "both" : legacy.binding ? "legacy" : "partial",
652
+ state: !any ? "current" : legacy.binding && current.binding ? "both" : legacy.binding ? "legacy" : "partial",
378
653
  };
379
654
  }
380
655
 
@@ -397,9 +672,15 @@ export function analyseHarnessState(projectDir, id) {
397
672
  const p = layoutPaths(projectDir);
398
673
  const dir = p.harnessState(id);
399
674
  let names;
400
- try { names = readdirSync(dir).sort(); } catch { return { dir, present: false, names: [], headed: false, marker: null, others: [] }; }
675
+ try {
676
+ names = readdirSync(dir).sort();
677
+ } catch {
678
+ return { dir, present: false, names: [], headed: false, marker: null, others: [] };
679
+ }
401
680
  let headed = false;
402
- try { headed = readFileSync(p.stateGitignore, "utf8").includes(RUNTIME_GITIGNORE_HEADER); } catch {}
681
+ try {
682
+ headed = readFileSync(p.stateGitignore, "utf8").includes(RUNTIME_GITIGNORE_HEADER);
683
+ } catch {}
403
684
  const markerPath = p.welcomed(id);
404
685
  const markerName = markerPath.slice(dir.length + 1);
405
686
  const t = names.includes(markerName) ? readText(markerPath) : { present: false, text: null };
@@ -410,12 +691,21 @@ export function analyseHarnessState(projectDir, id) {
410
691
  // ─── every surface, for doctor ─────────────────────────────────────────
411
692
 
412
693
  export { analysePortableRegistration, portableRegistrationPaths };
413
- const ANALYSERS = { "markdown-block": analyseBlock, "json-entry": analyseJsonEntry, "mjs": analyseStampedFile, "host-plugin-registration": analyseRegistration, "portable-plugin-registration": analysePortableRegistration };
694
+ const ANALYSERS = {
695
+ "markdown-block": analyseBlock,
696
+ "json-entry": analyseJsonEntry,
697
+ mjs: analyseStampedFile,
698
+ "host-plugin-registration": analyseRegistration,
699
+ "portable-plugin-registration": analysePortableRegistration,
700
+ };
414
701
 
415
702
  // The states of every non-host, supported surface of every harness this
416
703
  // project uses — detected by directory, or carrying a file of ours (contract
417
704
  // 16). Host-managed rows have nothing to derive (contract 14).
418
- export function surfaceStates(projectDir, { home = homedir(), root = pluginRoot(), manifestDir = MANIFEST_DIR, harnesses = null, env = process.env } = {}) {
705
+ export function surfaceStates(
706
+ projectDir,
707
+ { home = homedir(), root = pluginRoot(), manifestDir = MANIFEST_DIR, harnesses = null, env = process.env } = {},
708
+ ) {
419
709
  projectDir = resolve(projectDir);
420
710
  const detected = detectHarnesses(projectDir, { dir: manifestDir }).map((d) => d.id);
421
711
  const out = { projectDir, detected, used: [], installable: harnessIds(manifestDir), states: [] };
@@ -426,8 +716,14 @@ export function surfaceStates(projectDir, { home = homedir(), root = pluginRoot(
426
716
  // and so does this (S2, the 2026-10-03 review): reporting it from the
427
717
  // core printed "<core> is not a portable plugin root" into every project
428
718
  // that merely contained the harness's directory.
429
- const rows = Object.entries(m.surfaces || {}).filter(([k, s]) => !k.startsWith("_") && s.kind !== "host" && s.supported !== false && ANALYSERS[s.format]
430
- && !(s.condition === "distribution_root" && !portablePayloadRoot(s, { root, env })));
719
+ const rows = Object.entries(m.surfaces || {}).filter(
720
+ ([k, s]) =>
721
+ !k.startsWith("_") &&
722
+ s.kind !== "host" &&
723
+ s.supported !== false &&
724
+ ANALYSERS[s.format] &&
725
+ !(s.condition === "distribution_root" && !portablePayloadRoot(s, { root, env })),
726
+ );
431
727
  // The render root, as plan() takes it (contract 0 as amended 2026-10-10):
432
728
  // an enabled, produced registration's install path. The launcher and the
433
729
  // status-line entry are analysed against it — from the marketplace
@@ -442,36 +738,61 @@ export function surfaceStates(projectDir, { home = homedir(), root = pluginRoot(
442
738
  const states = [];
443
739
  for (const [key, s] of rows) {
444
740
  const dependent = renderRoot !== root && ["json-entry", "mjs"].includes(s.format);
445
- const a = reg && s === reg[1] ? regA : ANALYSERS[s.format](projectDir, s, { root, home, harness: m, env, ...(dependent ? { renderRoot } : {}) });
446
- const entry = s.kind === "shared" ? (a.entryKey || s.marker?.pointer || null) : null;
447
- const path = a.legacyPath || a.path || (a.current ? a.current.path : (a.preferred ? a.preferred.path : join(projectDir, s.file || "")));
448
- const row = { harness: m.id, surface: key, kind: s.kind, path, entry, state: a.state, reason: a.reason || a.refusal || null, writtenBy: a.writtenBy || null, sameProject: Boolean(a.sameProject), produced: a.produced !== false, legacy: Boolean(a.legacy), installedPkg: a.installedPkg || null, present: a.file ? a.file.present : (a.current ? true : (a.curEntry ? true : false)) };
449
- if (s.kind === "registration") Object.assign(row, {
450
- entry: a.id,
451
- present: Boolean(a.dir?.present || a.ownership || a.known || a.market || a.installed),
452
- produced: a.produced,
453
- pkg: a.pkg || a.desiredVersion || null,
454
- dirPkg: a.dir?.pkg || a.ownership?.version || null,
455
- installedVersion: a.installedVersion,
456
- installPath: a.installPath,
457
- // The plugin's root inside our directory (registrationPaths' payload):
458
- // what a host that loads the registration in place runs from.
459
- payload: a.paths?.payload || null,
460
- enabled: a.enabled,
461
- others: a.others || [],
462
- otherProjects: a.otherProjects || 0,
741
+ const a =
742
+ reg && s === reg[1]
743
+ ? regA
744
+ : ANALYSERS[s.format](projectDir, s, { root, home, harness: m, env, ...(dependent ? { renderRoot } : {}) });
745
+ const entry = s.kind === "shared" ? a.entryKey || s.marker?.pointer || null : null;
746
+ const path =
747
+ a.legacyPath ||
748
+ a.path ||
749
+ (a.current ? a.current.path : a.preferred ? a.preferred.path : join(projectDir, s.file || ""));
750
+ const row = {
751
+ harness: m.id,
752
+ surface: key,
753
+ kind: s.kind,
754
+ path,
755
+ entry,
756
+ state: a.state,
757
+ reason: a.reason || a.refusal || null,
463
758
  writtenBy: a.writtenBy || null,
464
- newer: Boolean(a.newer),
465
- bin: a.bin,
466
- // What this registration silenced for the checkout and the checkout
467
- // still holds off: exactly the set uninstall re-enables (contract 13).
468
- silenced: (a.dir?.disabled || []).filter((k) => (a.disabledHere || []).includes(k)),
469
- });
759
+ sameProject: Boolean(a.sameProject),
760
+ produced: a.produced !== false,
761
+ legacy: Boolean(a.legacy),
762
+ installedPkg: a.installedPkg || null,
763
+ present: a.file ? a.file.present : a.current ? true : a.curEntry ? true : false,
764
+ };
765
+ if (s.kind === "registration")
766
+ Object.assign(row, {
767
+ entry: a.id,
768
+ present: Boolean(a.dir?.present || a.ownership || a.known || a.market || a.installed),
769
+ produced: a.produced,
770
+ pkg: a.pkg || a.desiredVersion || null,
771
+ dirPkg: a.dir?.pkg || a.ownership?.version || null,
772
+ installedVersion: a.installedVersion,
773
+ installPath: a.installPath,
774
+ // The plugin's root inside our directory (registrationPaths' payload):
775
+ // what a host that loads the registration in place runs from.
776
+ payload: a.paths?.payload || null,
777
+ enabled: a.enabled,
778
+ others: a.others || [],
779
+ otherProjects: a.otherProjects || 0,
780
+ writtenBy: a.writtenBy || null,
781
+ newer: Boolean(a.newer),
782
+ bin: a.bin,
783
+ // What this registration silenced for the checkout and the checkout
784
+ // still holds off: exactly the set uninstall re-enables (contract 13).
785
+ silenced: (a.dir?.disabled || []).filter((k) => (a.disabledHere || []).includes(k)),
786
+ });
470
787
  states.push(row);
471
788
  }
472
789
  // A registration is the host's to load and never counts as a file of ours
473
790
  // (contract 16): it decides nothing about whether the harness is in use.
474
- const hasOurs = states.some((x) => (x.kind === "exclusive" && ["current", "stale"].includes(x.state)) || (x.kind === "shared" && ["ours-current", "ours-stale"].includes(x.state)));
791
+ const hasOurs = states.some(
792
+ (x) =>
793
+ (x.kind === "exclusive" && ["current", "stale"].includes(x.state)) ||
794
+ (x.kind === "shared" && ["ours-current", "ours-stale"].includes(x.state)),
795
+ );
475
796
  if (detected.includes(m.id) || hasOurs) {
476
797
  out.used.push(m.id);
477
798
  // The agents block is deliberately shared across harnesses. Its presence