@inventarch/cli 3.1.0 → 3.2.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 (129) hide show
  1. package/LANGUAGE.md +2 -2
  2. package/README.md +222 -23
  3. package/SPEC.md +26 -25
  4. package/assets/base/62ecd5092f364b40e335e9e509ef512ac8030eb5689e72a5d0ff1e073cb13cfb.ia.tgz +0 -0
  5. package/assets/base.json +3 -3
  6. package/assets/host/185ebc43ae4798ede53905a6d6ff35fb0cf65e9e1bafa6413fe58e3306cf8af7.tgz +0 -0
  7. package/assets/host.json +3 -3
  8. package/assets/vocabulary.json +14 -14
  9. package/dist/args.d.ts +1 -1
  10. package/dist/args.d.ts.map +1 -1
  11. package/dist/author.d.ts.map +1 -1
  12. package/dist/author.js +6 -7
  13. package/dist/author.js.map +1 -1
  14. package/dist/briefing.d.ts +10 -5
  15. package/dist/briefing.d.ts.map +1 -1
  16. package/dist/briefing.js +10 -3
  17. package/dist/briefing.js.map +1 -1
  18. package/dist/capture.d.ts +6 -4
  19. package/dist/capture.d.ts.map +1 -1
  20. package/dist/capture.js +13 -11
  21. package/dist/capture.js.map +1 -1
  22. package/dist/channel.d.ts +4 -1
  23. package/dist/channel.d.ts.map +1 -1
  24. package/dist/channel.js +4 -1
  25. package/dist/channel.js.map +1 -1
  26. package/dist/claude-cli.d.ts +3 -3
  27. package/dist/claude-cli.js +7 -7
  28. package/dist/commands.d.ts +9 -9
  29. package/dist/commands.d.ts.map +1 -1
  30. package/dist/commands.js +31 -33
  31. package/dist/commands.js.map +1 -1
  32. package/dist/compile.d.ts +1 -1
  33. package/dist/compile.d.ts.map +1 -1
  34. package/dist/compile.js +1 -1
  35. package/dist/compile.js.map +1 -1
  36. package/dist/consumer.d.ts +49 -42
  37. package/dist/consumer.d.ts.map +1 -1
  38. package/dist/consumer.js +60 -56
  39. package/dist/consumer.js.map +1 -1
  40. package/dist/decline.js +4 -4
  41. package/dist/decline.js.map +1 -1
  42. package/dist/distribute.d.ts +31 -29
  43. package/dist/distribute.d.ts.map +1 -1
  44. package/dist/distribute.js +40 -37
  45. package/dist/distribute.js.map +1 -1
  46. package/dist/doctor-user.d.ts +3 -3
  47. package/dist/doctor-user.d.ts.map +1 -1
  48. package/dist/doctor-user.js +8 -8
  49. package/dist/doctor-user.js.map +1 -1
  50. package/dist/doctor.d.ts +3 -3
  51. package/dist/doctor.d.ts.map +1 -1
  52. package/dist/doctor.js +70 -64
  53. package/dist/doctor.js.map +1 -1
  54. package/dist/format.d.ts +2 -2
  55. package/dist/format.d.ts.map +1 -1
  56. package/dist/format.js +6 -6
  57. package/dist/format.js.map +1 -1
  58. package/dist/home-remedy.d.ts +2 -2
  59. package/dist/home-remedy.d.ts.map +1 -1
  60. package/dist/home-remedy.js +3 -3
  61. package/dist/home-remedy.js.map +1 -1
  62. package/dist/host-projection.d.ts +39 -39
  63. package/dist/host-projection.d.ts.map +1 -1
  64. package/dist/host-projection.js +73 -74
  65. package/dist/host-projection.js.map +1 -1
  66. package/dist/host.d.ts +52 -53
  67. package/dist/host.d.ts.map +1 -1
  68. package/dist/host.js +92 -95
  69. package/dist/host.js.map +1 -1
  70. package/dist/init.d.ts +65 -60
  71. package/dist/init.d.ts.map +1 -1
  72. package/dist/init.js +119 -118
  73. package/dist/init.js.map +1 -1
  74. package/dist/main.d.ts +1 -1
  75. package/dist/main.js +8 -8
  76. package/dist/main.js.map +1 -1
  77. package/dist/next.d.ts +1 -1
  78. package/dist/next.js +16 -16
  79. package/dist/next.js.map +1 -1
  80. package/dist/operation-help.d.ts +3 -3
  81. package/dist/operation-help.d.ts.map +1 -1
  82. package/dist/operation-help.js +9 -9
  83. package/dist/operation-help.js.map +1 -1
  84. package/dist/pack.d.ts +1 -1
  85. package/dist/pack.d.ts.map +1 -1
  86. package/dist/pack.js +12 -12
  87. package/dist/pack.js.map +1 -1
  88. package/dist/position.d.ts +1 -1
  89. package/dist/position.d.ts.map +1 -1
  90. package/dist/position.js +11 -12
  91. package/dist/position.js.map +1 -1
  92. package/dist/preview.d.ts +4 -4
  93. package/dist/preview.d.ts.map +1 -1
  94. package/dist/preview.js +28 -28
  95. package/dist/preview.js.map +1 -1
  96. package/dist/profile.d.ts +23 -23
  97. package/dist/profile.d.ts.map +1 -1
  98. package/dist/profile.js +50 -51
  99. package/dist/profile.js.map +1 -1
  100. package/dist/project.d.ts +10 -11
  101. package/dist/project.d.ts.map +1 -1
  102. package/dist/project.js +31 -33
  103. package/dist/project.js.map +1 -1
  104. package/dist/read.d.ts +2 -2
  105. package/dist/read.d.ts.map +1 -1
  106. package/dist/read.js +5 -5
  107. package/dist/read.js.map +1 -1
  108. package/dist/render.d.ts +31 -30
  109. package/dist/render.d.ts.map +1 -1
  110. package/dist/render.js +27 -26
  111. package/dist/render.js.map +1 -1
  112. package/dist/session.d.ts +9 -9
  113. package/dist/session.d.ts.map +1 -1
  114. package/dist/session.js +13 -13
  115. package/dist/session.js.map +1 -1
  116. package/dist/user-host.d.ts +1 -1
  117. package/dist/user-host.js +5 -5
  118. package/dist/user-host.js.map +1 -1
  119. package/dist/validate.d.ts +9 -9
  120. package/dist/validate.d.ts.map +1 -1
  121. package/dist/validate.js +35 -38
  122. package/dist/validate.js.map +1 -1
  123. package/dist/vocabulary.d.ts +1 -1
  124. package/dist/vocabulary.d.ts.map +1 -1
  125. package/dist/vocabulary.js +2 -2
  126. package/dist/vocabulary.js.map +1 -1
  127. package/package.json +6 -6
  128. package/assets/base/7db20e0dbbc2b88701ea24991886b4a8e08d419dda469cce5caff66911f81e4c.ia.tgz +0 -0
  129. package/assets/host/7e80bd7098018c1c13e3fae4cd363acfeffedccd5b6ec06c4952b62f449a4246.tgz +0 -0
package/dist/host.js CHANGED
@@ -1,30 +1,27 @@
1
1
  /**
2
2
  * `ia host`: docs/specs/host-registration/README.md §4.
3
3
  *
4
- * One verb owns the managed host set of §5.1: the MCP entry and the workspace projection, plus the context element
5
- * §5.2's gate keeps unselected. It plans by default and never writes while planning — the payload's location is
6
- * computed, not created. `--apply` materializes the embedded payload once per user (§3.3), re-plans every
7
- * sub-transaction against the verified payload, then applies them in order — mcp, projection — and removal runs them
8
- * in reverse (§8). No cross-file atomicity is claimed: a rerun converges, and a pending journal refuses naming its
9
- * recovery. Nothing here reports that a server answered or a hook ran; `applied.observed` is always false (plan-0002
10
- * M5 exit).
4
+ * One verb owns the managed host set of §4: the MCP entry and the workspace projection, plus the context element
5
+ * §4's gate keeps unselected. It plans by default and never writes while planning — the payload's location is
6
+ * computed, not created. `--apply` materializes the embedded payload once per user (§3), re-plans every
7
+ * sub-transaction against the verified payload, then applies them in order — mcp, projection — and removal runs them in
8
+ * reverse (§4). No cross-file atomicity is claimed (§6): a rerun converges, and a pending journal refuses naming its
9
+ * recovery. Nothing here reports that a server answered or a hook ran; `applied.observed` is always false.
11
10
  *
12
- * Milestone position-packet task replace-renderers (plan amendments B9, B11 and B12): the projection is the position
13
- * packet's consumer rendering, and `ia host` registers no steward guard. The projection element lists instead the
14
- * retirement of a guard an earlier release registered, which `applyHostProjection` (host-projection.ts) performs before
15
- * any projection file changes, the owned 1.x steward files it deletes and the foreign files it leaves. Task
16
- * ia-project-verb: `ia project` (project.ts) plans and applies that element alone, through the same planner
11
+ * The projection is the position packet's consumer rendering, and `ia host` registers no steward guard. The projection
12
+ * element lists instead the retirement of a guard an earlier release registered, which `applyHostProjection`
13
+ * (host-projection.ts) performs before any projection file changes, the owned 1.x steward files it deletes and the
14
+ * foreign files it leaves. `ia project` (project.ts) plans and applies that element alone, through the same planner
17
15
  * (`projectionElement`), re-plan (`replanProjection`) and writer, and its file rows (`projectionFileRows`).
18
16
  *
19
17
  * The plan asks the mechanisms themselves. `planHostFor` plans against the payload apply will materialize, described
20
18
  * from the pin without reading it (`expectedHostCache`), so a conflict in the preview is the service's own refusal —
21
- * its code and message unchanged (contract §4.1) — and is the refusal apply would raise.
19
+ * its code and message unchanged (contract §4) — and is the refusal apply would raise.
22
20
  *
23
- * Milestone generation-binding (plan amendments C16 and C24, design item 9): the apply reads the join receipts before it
24
- * writes anything, refusing ones it cannot read, and once every element is applied it records the host's join from the
25
- * committed registration (`joinHost`): the installed-implementation catalog of the payload it names, at the workspace's
26
- * authored revision. A removal drops it (`leaveHost`). The plan and the envelope do not change; `ia doctor` reports
27
- * the join.
21
+ * The apply reads the join receipts before it writes anything, refusing ones it cannot read, and once every element is
22
+ * applied it records the host's join from the committed registration (`joinHost`): the installed-implementation catalog
23
+ * of the payload it names, at the workspace's authored revision. A removal drops it (`leaveHost`). The plan and the
24
+ * envelope do not change; `ia doctor` reports the join.
28
25
  */
29
26
  import { createHash } from 'node:crypto';
30
27
  import { existsSync, realpathSync, statSync } from 'node:fs';
@@ -52,26 +49,26 @@ const DAMAGED = 'The ia installation is damaged; run "ia doctor" for its install
52
49
  /** §7.1: the user-level command a workspace plan names when the plugin is missing. It takes no --root. */
53
50
  export const USER_PLUGIN_COMMAND = 'ia host claude --user --apply';
54
51
  export const USER_PLUGIN_MISSING = `The user-level plugin is not installed; run "${USER_PLUGIN_COMMAND}" to add it.`;
55
- /** §5.3's sentence, verbatim, per host. Every element — the projection included — is machine-local. */
52
+ /** §4's machine-local sentence, per host. Every element — the projection included — is machine-local. */
56
53
  export const MACHINE_LOCAL = {
57
54
  claude: 'These files are machine-local: .mcp.json, .claude/settings.local.json, .claude/rules/ia-workspace.md, .claude/skills/ia-authoring/, the agents and skills generated from authored records under .claude/agents/ and .claude/skills/, and .ia/distributions/. Do not commit them.',
58
55
  codex: 'These files are machine-local: .codex/config.toml, AGENTS.md, .agents/skills/ia-authoring/, the skills generated from authored records under .agents/skills/, and .ia/distributions/. Do not commit them.',
59
56
  };
60
- /** §5.4: the MCP element's one fixed addition, from §2.3's host facts. */
57
+ /** The MCP element's one fixed addition, from the host's facts. */
61
58
  export const MCP_APPROVAL = 'Claude Code asks for approval before starting a project MCP server.';
62
59
  /**
63
- * Operator decision 2026-10-08 (plan amendment B11), said where the guard used to be registered, as operator decision
64
- * 2026-09-23 ("narrow + disclose") said what it refused: the guard is retired, so nothing it refused is refused now.
60
+ * From 2026-10-08 this says where the guard used to be registered, as from 2026-09-23 it said what the guard refused:
61
+ * the guard is retired, so nothing it refused is refused now.
65
62
  */
66
63
  export const GUARD_SCOPE = 'ia host registers one guard group per authored @hook, which refuses an edit its paths and tools select unless the acting agent holds a governing @mandate granting Synthesis there; it registers no per-system steward guard, and applying the projection retires one an earlier release registered.';
67
- /** §5.1's files, exported once so `ia doctor` names the same ones. */
64
+ /** §4's files, exported once so `ia doctor` names the same ones. */
68
65
  export const MCP_PATH = { claude: '.mcp.json', codex: '.codex/config.toml' };
69
66
  export const SETTINGS = '.claude/settings.local.json';
70
67
  export const HOSTS_AREA = '.ia/distributions/hosts';
71
68
  /**
72
- * §5.1's state files. Their presence says whether this workspace owns an element; their content is the mechanisms'.
73
- * `hooks` is a steward-guard registration an earlier release made, which the projection apply retires (B11), and
74
- * `receipt` the receipt it writes beside the projection state (B12).
69
+ * The state files. Their presence says whether this workspace owns an element; their content is the mechanisms'.
70
+ * `hooks` is a steward-guard registration an earlier release made, which the projection apply retires, and `receipt`
71
+ * the receipt it writes beside the projection state.
75
72
  */
76
73
  export const STATE = {
77
74
  mcp: (host) => `${HOSTS_AREA}/${host}-${HOST_REGISTRATION}.json`,
@@ -104,7 +101,7 @@ export function stateRepair(host, path, rerun) {
104
101
  return `Delete ${path} and ${OWNED_MCP[host]}, then run "${rerun}".`;
105
102
  if (host === 'claude' && path === STATE.hooks)
106
103
  return `Delete ${path} and ${OWNED_GUARD}, then run "${rerun}".`;
107
- // Review finding H-N3: the hook ownership state names the groups it owns, so both go before the rerun.
104
+ // The hook ownership state names the groups it owns, so both go before the rerun.
108
105
  if (host === 'claude' && path === STATE.hookGroups)
109
106
  return `Delete ${path} and ${OWNED_HOOKS}, then run "${rerun}".`;
110
107
  if (path === STATE.projection(host) || path === STATE.receipt(host))
@@ -119,18 +116,18 @@ export function modifiedRepair(host, elements) {
119
116
  const owned = elements.map((element) => (element === 'mcp' ? OWNED_MCP[host] : OWNED_GUARD)).join(' and ');
120
117
  return `Delete ${owned}, then run "ia host ${host} --remove --apply" and register again.`;
121
118
  }
122
- /** §8: each pending journal names its own recovery on the distribution binary. `ia doctor` reports the same ones. */
119
+ /** §6: each pending journal names its own recovery on the distribution binary. `ia doctor` reports the same ones. */
123
120
  export const JOURNALS = [
124
121
  [`${HOSTS_AREA}/pending.json`, 'recover-host'],
125
122
  [`${HOSTS_AREA}/guard-pending.json`, 'recover-guard'],
126
123
  [`${HOSTS_AREA}/lifecycle-pending.json`, 'recover-lifecycle'],
127
124
  ];
128
- /** §8: the lock every host sub-transaction holds while it writes (`acquireHostRegistrationLock`). */
125
+ /** §5: the lock every host sub-transaction holds while it writes (`acquireHostRegistrationLock`). */
129
126
  export const HOST_LOCK = `${HOSTS_AREA}/lock.json`;
130
127
  /**
131
- * The close of a remedy whose follow-up is the refused command itself, run again as typed, so the recovery before it
132
- * is the one command named (design row 27). `ia init --host` cannot simply be run again once it has initialized, so it
133
- * names `ia host` instead of such a remedy.
128
+ * The close of a remedy whose follow-up is the refused command itself, run again as typed, so the recovery before it is
129
+ * the one command named. `ia init --host` cannot simply be run again once it has initialized, so it names `ia host`
130
+ * instead of such a remedy.
134
131
  */
135
132
  export const THEN_RERUN = ', then rerun.';
136
133
  /** An installed CLI recovery, delegating the named distribution mechanism with an explicit root. */
@@ -163,9 +160,9 @@ export function runRecovery(context) {
163
160
  }
164
161
  }
165
162
  /**
166
- * §8 "or refuses naming a recovery": a held host lock is another run or a killed one, and nothing here can tell
167
- * which, so the next action names the recovery that decides it — `recoverHost` takes the lock in recovery mode,
168
- * which clears a dead holder's lock and refuses a live one. It names no `ia host` command, so `--root` needs no rewrite.
163
+ * §5: a held host lock names its recovery. It is another run or a killed one, and nothing here can tell which, so the
164
+ * next action names the recovery that decides it — `recoverHost` takes the lock in recovery mode, which clears a dead
165
+ * holder's lock and refuses a live one. It names no `ia host` command, so `--root` needs no rewrite.
169
166
  */
170
167
  export const lockNext = (root) => `Another ia host run holds the host lock, or a killed run left it: run "${recoverCommand('recover-host', root)}" (it clears a dead holder's lock and refuses a live one)${THEN_RERUN}`;
171
168
  /**
@@ -181,7 +178,7 @@ export function lockRefusal(error, root) {
181
178
  }
182
179
  /** lifecycle-profile.ts: Codex's hooks are unavailable, and the profile says why. */
183
180
  const CODEX_HOOKS = lifecycleProfile('codex', '0.116.0').reason ?? 'Codex hooks are unavailable.';
184
- /** §3.3 step 1, through the service: a missing or malformed pin or archive is IA-DIST-ARTIFACT-UNAVAILABLE. */
181
+ /** §3, through the service: a missing or malformed pin or archive is IA-DIST-ARTIFACT-UNAVAILABLE. */
185
182
  const bundledPin = (packageRoot) => located(null, DAMAGED, () => readHostPin(packageRoot));
186
183
  /**
187
184
  * §7: the release `ia doctor` and `ia inspect` observe hosts against. An installation that carries no payload is not
@@ -205,7 +202,7 @@ export function requireInitialized(root, named = root) {
205
202
  }
206
203
  /** The journal a failed transaction left behind, if any, with the command that recovers it. */
207
204
  export const pendingJournal = (root) => JOURNALS.find(([path]) => existsSync(resolve(root, path)));
208
- /** Design row 27: the recovery is the one command named; the refused command is simply run again after it. */
205
+ /** The recovery is the one command named; the refused command is simply run again after it. */
209
206
  export const recoverNext = (root, command) => `Run "${recoverCommand(command, root)}"${THEN_RERUN}`;
210
207
  /**
211
208
  * A next action of this verb made runnable from any cwd: every quoted `ia host <host>` or `ia project <host>` command
@@ -226,10 +223,10 @@ export const refusedPath = (error) => /^IA-/.test(codeOf(error, '')) &&
226
223
  ? error.path
227
224
  : null;
228
225
  /**
229
- * §6.3: the repair for a projection refusal with `code` located at `path`. The ownership state has its own repair; a
230
- * guard group the retirement (B11) refuses as changed is deleted by hand, after which the retirement removes the
231
- * ownership state alone, and settings it cannot read are fixed; any other file is never replaced or adopted, so it is
232
- * moved or deleted first. `ia host`, `ia doctor` and the install refresh all name it this way.
226
+ * §6: the repair for a projection refusal with `code` located at `path`. The ownership state has its own repair; a
227
+ * guard group the retirement refuses as changed is deleted by hand, after which the retirement removes the ownership
228
+ * state alone, and settings it cannot read are fixed; any other file is never replaced or adopted, so it is moved or
229
+ * deleted first. `ia host`, `ia doctor` and the install refresh all name it this way.
233
230
  */
234
231
  export const projectionRepair = (host, path, rerun, code) => code === 'IA-CLI-FAILED'
235
232
  ? `Make ${path} writable and release any file lock, then run "${rerun}".`
@@ -239,7 +236,7 @@ export const projectionRepair = (host, path, rerun, code) => code === 'IA-CLI-FA
239
236
  : code === undefined || code === 'IA-DIST-LOCAL-MODIFICATION'
240
237
  ? `Delete only the IA guard group in ${path}, then run "${rerun}".`
241
238
  : `Fix ${path}, then run "${rerun}".`));
242
- /** The populated skill folder a projection refusal names (distribution's `skillFolder`, review finding A-F2), if any. */
239
+ /** The populated skill folder a projection refusal names (distribution's `skillFolder`), if any. */
243
240
  export const skillFolderOf = (error) => error !== null && typeof error === 'object' && 'skillFolder' in error && typeof error.skillFolder === 'string'
244
241
  ? error.skillFolder
245
242
  : undefined;
@@ -292,12 +289,12 @@ export function projectionFailure(error, root, host, rerun) {
292
289
  */
293
290
  export const projectedHosts = (root) => WORKSPACE_HOSTS.filter((host) => existsSync(resolve(root, STATE.projection(host))));
294
291
  /**
295
- * The apply that repairs `host`'s projection, which `ia doctor` and the install refresh both name (task
296
- * ia-project-verb): `ia host <host> --apply` for a registered host, and `ia project <host> --apply` for a projection
297
- * `ia project` wrote without a registration, which `ia host` would also register an MCP server for.
292
+ * The apply that repairs `host`'s projection, which `ia doctor` and the install refresh both name:
293
+ * `ia host <host> --apply` for a registered host, and `ia project <host> --apply` for a projection `ia project` wrote
294
+ * without a registration, which `ia host` would also register an MCP server for.
298
295
  */
299
296
  export const projectionRerun = (root, host) => existsSync(resolve(root, STATE.mcp(host))) ? `ia host ${host} --apply` : `ia project ${host} --apply`;
300
- /** §8: a pending journal refuses the whole verb and names the recovery that clears it. `ia project` shares it. */
297
+ /** §6: a pending journal refuses the whole verb and names the recovery that clears it. `ia project` shares it. */
301
298
  export function requireIdle(root, supplied) {
302
299
  try {
303
300
  assertHostRegistrationIdle(root);
@@ -344,7 +341,7 @@ function registrationElement(path, owned, remove, plan) {
344
341
  }
345
342
  }
346
343
  /**
347
- * §5.2: the context element. Claude reports it `not selected` until the gate lifts; Codex reports it `unsupported by
344
+ * §4: the context element. Claude reports it `not selected` until the gate lifts; Codex reports it `unsupported by
348
345
  * host`, because it is delivered through lifecycle hooks and Codex hooks are unavailable, so both hosts carry the
349
346
  * same three rows.
350
347
  */
@@ -356,11 +353,11 @@ const contextElement = (host) => ({
356
353
  conflict: null,
357
354
  });
358
355
  /**
359
- * §5.1 `projection`, planned by the real planners: B11's retirement of an owned guard registration, then the file plan
360
- * (B9). Both read only the workspace, so the plan is exactly apply's. A retirement is a change, and so is a missing
361
- * receipt, which every apply writes (B12), so a projection whose files are unchanged is then an update; a removal that
362
- * finds only a guard registration or a receipt removes them. `ia project` plans with it, and both verbs' applies
363
- * re-plan with it (`replanProjection`), so no two of them can plan the projection differently.
356
+ * §4 `projection`, planned by the real planners: the retirement of an owned guard registration, then the file plan.
357
+ * Both read only the workspace, so the plan is exactly apply's. A retirement is a change, and so is a missing receipt,
358
+ * which every apply writes, so a projection whose files are unchanged is then an update; a removal that finds only a
359
+ * guard registration or a receipt removes them. `ia project` plans with it, and both verbs' applies re-plan with it
360
+ * (`replanProjection`), so no two of them can plan the projection differently.
364
361
  */
365
362
  export function projectionElement(root, host, rendered, cache = null) {
366
363
  const refused = (conflict) => ({
@@ -421,7 +418,7 @@ function invocationOf(context, host, remove) {
421
418
  export function collectHost(context) {
422
419
  const { args, host } = context;
423
420
  // Host plugin distribution spec §4: the adapter table decides. An unknown host is usage, and so is --context with
424
- // Codex; both precede every read (§3). A known row without the workspace set (Cursor, planned) refuses.
421
+ // Codex; both precede every read (contract §1.2). A known row without the workspace set (Cursor, planned) refuses.
425
422
  const given = args.positionals[0] ?? '';
426
423
  if (hostRow(given) === undefined)
427
424
  throw new UsageError(`ia host takes claude, codex or cursor; got ${given}`);
@@ -437,8 +434,8 @@ export function collectHost(context) {
437
434
  throw new UsageError('--context applies to claude only; Codex hooks are unavailable');
438
435
  const supplied = requireRoot(context);
439
436
  requireInitialized(supplied);
440
- // Spec §5.2's gate: until the binding's coordinate, bootstrap and policy are derived and one context run from a v2
441
- // payload is observed generating, the context element refuses. The spec fixes this code for the gate.
437
+ // Host registration spec §4's gate: until the binding's coordinate, bootstrap and policy are derived and one context
438
+ // run from a v2 payload is observed generating, the context element refuses. The spec fixes this code for the gate.
442
439
  if (selected !== undefined)
443
440
  throw new Refusal('IA-DIST-HOST-UNSUPPORTED', 'The lifecycle context element is not qualified in this release', 3, { path: supplied }, `Run "ia host ${name}" to plan the registration without the context element.`);
444
441
  // The mechanisms record the real path (files.ts `workspace()`), so the plan works on the same one.
@@ -446,18 +443,18 @@ export function collectHost(context) {
446
443
  // Every IA home remedy ends by planning this invocation again; `runHost` adds `--root` as it does to every next action.
447
444
  const plan = `ia host ${name}${remove ? ' --remove' : ''}`;
448
445
  const home = hostHome(host.env, plan);
449
- // §3.3: neither may contain the other; the service raises IA-DIST-PATH-UNSAFE.
446
+ // §5: neither may contain the other; the service raises IA-DIST-PATH-UNSAFE.
450
447
  located(supplied, `Move the workspace, or set IA_HOME to an absolute directory outside it; then run "${plan}".`, () => assertHomeOutsideWorkspace(home, root));
451
- // §3: refuse a home that itself looks like a workspace at plan time, before any payload write is attempted.
448
+ // §5: refuse a home that itself looks like a workspace at plan time, before any payload write is attempted.
452
449
  located(null, homeSrcRemedy(home, plan), () => assertIaHomeUsable(home));
453
450
  const { pin: bundled } = bundledPin(host.packageRoot);
454
451
  requireIdle(root, supplied);
455
- // §4: zero error findings before anything is rendered or registered. A removal renders nothing and reads no record, so
456
- // it needs neither an admitting workspace nor records that open (review findings H-R2 and H-R8): it is what restores
457
- // editing when a broken record or an unreadable workspace leaves a hook group refusing the repair.
458
- // Review C2-R7: a workspace apply writes the projection `ia project --apply` writes, so it is the effect mode (Execution)
459
- // under the participant's mandate profile, judged on the rendering session before the confirmation; its plan writes
460
- // nothing, `--remove` restores editing, and `--user` reads no workspace, so none of them is gated.
452
+ // §4: zero error findings before anything is rendered or registered. A removal renders nothing and reads no record,
453
+ // so it needs neither an admitting workspace nor records that open: it is what restores editing when a broken record
454
+ // or an unreadable workspace leaves a hook group refusing the repair.
455
+ // A workspace apply writes the projection `ia project --apply` writes, so it is the effect mode (Execution) under the
456
+ // participant's mandate profile, judged on the rendering session before the confirmation; its plan writes nothing,
457
+ // `--remove` restores editing, and `--user` reads no workspace, so none of them is gated.
461
458
  const rendered = remove
462
459
  ? null
463
460
  : renderProjectionFor(root, name, args.flag('apply') ? sessionGate(context, 'effect') : undefined);
@@ -483,13 +480,13 @@ export function collectHost(context) {
483
480
  rendered,
484
481
  };
485
482
  }
486
- /** What an apply that retired the steward guard (B11) says it did. */
483
+ /** What an apply that retired the steward guard says it did. */
487
484
  export const GUARD_RETIRED = 'Retired the steward guard an earlier release registered: its group in .claude/settings.local.json and its ownership state are removed.';
488
485
  /** A next action of this verb as printed: with `--root` given, each `ia host` command in it carries the root. */
489
486
  const say = (view, text) => hostNext(text, view.host, view.root, view.rooted);
490
487
  /** The next action a conflict renders, and the one its refusal carries, rooted when `--root` was given. */
491
488
  const nextFor = (view, id, conflict) => safeRootAdvice(say(view, conflictNext(view, id, conflict)), [view.root]);
492
- /** The unrooted next action for a conflict. §5.3 fixes the unowned MCP entry's wording. */
489
+ /** The unrooted next action for a conflict. */
493
490
  function conflictNext(view, id, conflict) {
494
491
  const rerun = `ia host ${view.host}${view.remove ? ' --remove' : ''} --apply`;
495
492
  // An unreadable ownership state: the mechanisms locate the refusal at the state file itself.
@@ -497,8 +494,8 @@ function conflictNext(view, id, conflict) {
497
494
  if (unreadable !== null)
498
495
  return unreadable;
499
496
  if (conflict.code === 'IA-DIST-LOCAL-MODIFICATION' && id === 'mcp') {
500
- // Owned: removal tolerates a deleted entry, so deleting it and re-registering converges. Unowned: §5.3's wording,
501
- // made exact for Codex, where the collision can be any ia-workspace table or a file that no longer parses.
497
+ // Owned: removal tolerates a deleted entry, so deleting it and re-registering converges. Unowned: remove that
498
+ // entry, made exact for Codex, where the collision can be any ia-workspace table or a file that no longer parses.
502
499
  if (view.owned.has('mcp'))
503
500
  return modifiedRepair(view.host, ['mcp']);
504
501
  return view.host === 'codex'
@@ -535,7 +532,7 @@ export function replanProjection(root, host, rendered, refuse, cache = null) {
535
532
  throw refuse(conflict);
536
533
  }
537
534
  /**
538
- * §3.3 steps 3-4. A payload directory that fails verification is named by the mechanism and the remedy is to delete
535
+ * §3. A payload directory that fails verification is named by the mechanism and the remedy is to delete
539
536
  * it; nothing overwrites it. Any other failure is the bundled payload's own, which only a reinstall repairs.
540
537
  */
541
538
  function materialize(view, packageRoot) {
@@ -554,12 +551,12 @@ function materialize(view, packageRoot) {
554
551
  }
555
552
  }
556
553
  /**
557
- * §8: mcp, projection in order; removal in reverse. The payload is materialized, then every sub-transaction is
558
- * re-planned with the verifying planners before any is applied — the projection's guard retirement (B11) and file plan
554
+ * §4: mcp, projection in order; removal in reverse. The payload is materialized, then every sub-transaction is
555
+ * re-planned with the verifying planners before any is applied — the projection's guard retirement and file plan
559
556
  * included — so a refusal any planner can find is raised before the workspace changes; each apply then re-plans under
560
557
  * the host lock and refuses a plan that went stale. The projection is applied through `applyHostProjection`, the one
561
- * writer of projection files, which retires an owned steward guard before any projection file changes and reports it
562
- * as the element's `guard`. Cancellation is observed between sub-transactions. A failure after an element was written
558
+ * writer of projection files, which retires an owned steward guard before any projection file changes and reports it as
559
+ * the element's `guard`. Cancellation is observed between sub-transactions. A failure after an element was written
563
560
  * names the rerun that finishes the set, or the recovery a pending journal needs. `checkpoint` runs after each element
564
561
  * completes, which is where an interruption test cuts.
565
562
  */
@@ -602,9 +599,9 @@ export function applyHostSet(view, packageRoot, signal, checkpoint = () => { })
602
599
  checkpoint(id);
603
600
  };
604
601
  /**
605
- * Design item 9 (plan amendment C16): the host's join receipts. Receipts that cannot be read are never replaced, and a
606
- * rerun alone would refuse again, so their refusal names deleting them first: they are derived, and the rerun records
607
- * them again. Any other failure is `failure`'s.
602
+ * The host's join receipts. Receipts that cannot be read are never replaced, and a rerun alone would refuse again, so
603
+ * their refusal names deleting them first: they are derived, and the rerun records them again. Any other failure is
604
+ * `failure`'s.
608
605
  */
609
606
  const joinFailure = (error) => {
610
607
  if (refusedPath(error) !== JOINS || pendingJournal(root) !== undefined)
@@ -625,8 +622,8 @@ export function applyHostSet(view, packageRoot, signal, checkpoint = () => { })
625
622
  throw joinFailure(error);
626
623
  }
627
624
  };
628
- // Review finding B-N1: receipts that cannot be read refuse before anything is written, the payload included, rather
629
- // than after the MCP registration (`joinHost` and `leaveHost` read them again under the host lock).
625
+ // Receipts that cannot be read refuse before anything is written, the payload included, rather than after the MCP
626
+ // registration (`joinHost` and `leaveHost` read them again under the host lock).
630
627
  try {
631
628
  readJoins(root);
632
629
  }
@@ -640,12 +637,12 @@ export function applyHostSet(view, packageRoot, signal, checkpoint = () => { })
640
637
  if (!view.remove) {
641
638
  const cache = materialize(view, packageRoot);
642
639
  const mcp = replan(view, 'mcp', MCP_PATH[host], () => planHost(root, host, cache));
643
- // Review C3-N2: the rendering the plan's gated session made, re-planned against the files as they are now.
640
+ // The rendering the plan's gated session made, re-planned against the files as they are now.
644
641
  const { rendered } = view;
645
642
  // Only a removal's view carries no rendering (collectHost); an apply always has the one its gated plan made.
646
643
  if (rendered === null)
647
644
  throw new Error('A host apply view carries no rendering');
648
- // The hook groups run the guard in the payload just materialized and verified (plan amendment C9).
645
+ // The hook groups run the guard in the payload just materialized and verified.
649
646
  replanProjection(root, host, rendered, (conflict) => refusalFor(view, 'projection', conflict), {
650
647
  verified: cache,
651
648
  });
@@ -668,11 +665,11 @@ export function applyHostSet(view, packageRoot, signal, checkpoint = () => { })
668
665
  return { status: 'host-removed', elements: done, observed: false };
669
666
  }
670
667
  /**
671
- * A conflict as the `--json` envelopes print it (review finding A-F4): its code, path and reason. The descriptors a
672
- * refusal carries to word its own repair (`hook`, `folder`) stay internal; the repair is the refusal's `next`.
668
+ * A conflict as the `--json` envelopes print it: its code, path and reason. The descriptors a refusal carries to word
669
+ * its own repair (`hook`, `folder`) stay internal; the repair is the refusal's `next`.
673
670
  */
674
671
  export const printedConflict = (conflict) => conflict === null ? null : { code: conflict.code, path: conflict.path, reason: conflict.reason };
675
- /** §4 `--json`: the plan always, and `applied` only after an apply. */
672
+ /** `--json`: the plan always, and `applied` only after an apply. */
676
673
  const hostEnvelope = (view, applied) => ({
677
674
  version: 1,
678
675
  command: 'host',
@@ -717,7 +714,7 @@ function elementFields(view) {
717
714
  };
718
715
  });
719
716
  }
720
- /** A projection plan's B11 step as its plan says it, in `ia host` and `ia project` alike. */
717
+ /** A projection plan's guard retirement as its plan says it, in `ia host` and `ia project` alike. */
721
718
  export const GUARD_RETIRE = `first retires the steward guard registered in ${SETTINGS}`;
722
719
  /**
723
720
  * Each projected file with its action, at `column`; a foreign steward file says why it is left alone. `ia host` nests
@@ -737,13 +734,13 @@ const HOOK_SYMBOL = {
737
734
  unchanged: 'info',
738
735
  remove: 'removed',
739
736
  };
740
- /** Each authored `@hook`'s group with its action (plan amendment C9), worded alike by `ia host` and `ia project`. */
737
+ /** Each authored `@hook`'s group with its action, worded alike by `ia host` and `ia project`. */
741
738
  export const projectionHookRows = (hooks, column, caps) => hooks.flatMap((hook) => entry([[atom(hook.hook, 'cyan', 0), ...words(`hook group ${hook.action}`, null, 2)]], { column, symbol: HOOK_SYMBOL[hook.action] }, caps));
742
739
  /** Each authored record the host does not take, with the reason, worded alike by `ia host` and `ia project`. */
743
740
  export const unsupportedRows = (rows, column, caps) => rows.flatMap((row) => entry([[atom(row.identity, 'cyan', 0), ...words(`${row.word} not taken: ${row.reason}`, null, 2)]], { column, symbol: 'warning' }, caps));
744
741
  /**
745
- * Each projected file, then each hook group and each record not taken, nested at the elements block's content column
746
- * (§6.4 rule 3), under the element they belong to.
742
+ * Each projected file, then each hook group and each record not taken, nested at the elements block's content column,
743
+ * under the element they belong to.
747
744
  */
748
745
  const fileBlock = (view, caps) => {
749
746
  const projection = view.elements.find((element) => element.id === 'projection'), column = indentOf(1) + blockSymbolWidth(view.elements.map(elementSymbol), caps.ascii) + 2;
@@ -764,8 +761,8 @@ const elementsBlock = (view, caps) => [
764
761
  ...fileBlock(view, caps),
765
762
  ];
766
763
  /**
767
- * §5.3's machine-local sentence and, for a Claude registration, §5.4's approval note and the guard's retirement (only
768
- * Claude ever registered the guard, B11). `ia init --host` prints the same blocks after its host step, so the two verbs
764
+ * §4's machine-local sentence and, for a Claude registration, the MCP approval note and the guard's retirement (only
765
+ * Claude ever registered the guard). `ia init --host` prints the same blocks after its host step, so the two verbs
769
766
  * cannot word them differently.
770
767
  */
771
768
  export const hostNotes = (host, caps, remove = false) => [
@@ -778,8 +775,8 @@ export const hostNotes = (host, caps, remove = false) => [
778
775
  : []),
779
776
  ];
780
777
  /**
781
- * §7.1: a registration plan also names the missing user-level plugin's command. It is printed as is, never through
782
- * `say`: that command belongs to no workspace, so it never carries --root.
778
+ * Host plugin distribution spec §7.1: a registration plan also names the missing user-level plugin's command. It is
779
+ * printed as is, never through `say`: that command belongs to no workspace, so it never carries --root.
783
780
  */
784
781
  const notesBlocks = (view, caps) => [
785
782
  ...hostNotes(view.host, caps, view.remove),
@@ -805,7 +802,7 @@ export function renderHostPlan(view, applied, caps, supplied) {
805
802
  ...(applied === null && !conflicted
806
803
  ? commandFacts('Apply with "', `${view.invocation} --apply --yes`, '".', 3, caps, [view.root, supplied])
807
804
  : []),
808
- // `plan.undo` stays unrooted (§4 `--json`); the printed command carries --root when it was given.
805
+ // `plan.undo` stays unrooted in `--json`; the printed command carries --root when it was given.
809
806
  ...(view.remove
810
807
  ? []
811
808
  : commandFacts('Undo with "', say(view, `"${view.undo}"`).slice(1, -1), '".', 3, caps, [view.root])),
@@ -813,13 +810,13 @@ export function renderHostPlan(view, applied, caps, supplied) {
813
810
  ], { depth: 0, symbol: 'step' }, caps),
814
811
  ], { leadingBlank: true });
815
812
  }
816
- /** §2.8 rule 3's summary: what the preview shows, without its note or footer, because the question is the action. */
813
+ /** Contract §2.0's summary: what the preview shows, without its note or footer, because the question is the action. */
817
814
  const renderHostSummary = (view, caps) => document([headerBlock(view, caps), elementsBlock(view, caps), ...notesBlocks(view, caps)], { leadingBlank: true });
818
815
  export const CONFIRMATION = 'Apply this host registration? [y/N] ';
819
816
  const REMOVAL_CONFIRMATION = 'Remove this host registration? [y/N] ';
820
817
  export async function runHost(context) {
821
818
  const { args, caps, host, json } = context;
822
- // Host plugin distribution spec §7.1: `--user` is the user-level entry point, which needs no workspace.
819
+ // Host plugin distribution spec §6.3: `--user` is the user-level entry point, which needs no workspace.
823
820
  if (args.flag('user'))
824
821
  return runUserHost(context);
825
822
  let view;
@@ -843,10 +840,10 @@ export async function runHost(context) {
843
840
  const rendered = (applied) => json
844
841
  ? { exitCode: 0, stdout: JSON.stringify(hostEnvelope(view, applied)) + '\n', stderr: '' }
845
842
  : { exitCode: 0, stdout: renderHostPlan(view, applied, caps, args.value('root')), stderr: '' };
846
- // §4: a plan with a conflict is a successful report; only --apply refuses it.
843
+ // §5: a plan with a conflict is a successful report; only --apply refuses it.
847
844
  if (!args.flag('apply'))
848
845
  return rendered(null);
849
- // §2.8 rule 3. Parsing has already refused every --apply whose question cannot be asked or answered.
846
+ // Contract §2.0. Parsing has already refused every --apply whose question cannot be asked or answered.
850
847
  if (!args.flag('yes') &&
851
848
  !(await confirm(host.interaction, renderHostSummary(view, caps), view.remove ? REMOVAL_CONFIRMATION : CONFIRMATION)))
852
849
  return {