@inventarch/cli 1.2.0 → 2.0.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 (84) hide show
  1. package/README.md +12 -5
  2. package/SPEC.md +39 -7
  3. package/assets/host/3d2c8530db8d14755410b17be8228a230d88de96f9dc78f953979d3ca7c6ea62.tgz +0 -0
  4. package/assets/host.json +4 -4
  5. package/dist/bundled-base.d.ts +18 -0
  6. package/dist/bundled-base.d.ts.map +1 -0
  7. package/dist/bundled-base.js +44 -0
  8. package/dist/bundled-base.js.map +1 -0
  9. package/dist/capture.d.ts +30 -3
  10. package/dist/capture.d.ts.map +1 -1
  11. package/dist/capture.js +112 -37
  12. package/dist/capture.js.map +1 -1
  13. package/dist/commands.d.ts +23 -1
  14. package/dist/commands.d.ts.map +1 -1
  15. package/dist/commands.js +175 -13
  16. package/dist/commands.js.map +1 -1
  17. package/dist/compile.d.ts +3 -4
  18. package/dist/compile.d.ts.map +1 -1
  19. package/dist/compile.js +29 -70
  20. package/dist/compile.js.map +1 -1
  21. package/dist/consumer.d.ts.map +1 -1
  22. package/dist/consumer.js +9 -2
  23. package/dist/consumer.js.map +1 -1
  24. package/dist/distribute.d.ts +25 -5
  25. package/dist/distribute.d.ts.map +1 -1
  26. package/dist/distribute.js +75 -52
  27. package/dist/distribute.js.map +1 -1
  28. package/dist/doctor.d.ts.map +1 -1
  29. package/dist/doctor.js +113 -60
  30. package/dist/doctor.js.map +1 -1
  31. package/dist/format.d.ts.map +1 -1
  32. package/dist/format.js +2 -1
  33. package/dist/format.js.map +1 -1
  34. package/dist/host-projection.d.ts +73 -6
  35. package/dist/host-projection.d.ts.map +1 -1
  36. package/dist/host-projection.js +296 -38
  37. package/dist/host-projection.js.map +1 -1
  38. package/dist/host.d.ts +100 -30
  39. package/dist/host.d.ts.map +1 -1
  40. package/dist/host.js +235 -120
  41. package/dist/host.js.map +1 -1
  42. package/dist/init.d.ts +280 -35
  43. package/dist/init.d.ts.map +1 -1
  44. package/dist/init.js +1238 -194
  45. package/dist/init.js.map +1 -1
  46. package/dist/main.d.ts.map +1 -1
  47. package/dist/main.js +3 -1
  48. package/dist/main.js.map +1 -1
  49. package/dist/migration-journal.d.ts +35 -0
  50. package/dist/migration-journal.d.ts.map +1 -0
  51. package/dist/migration-journal.js +205 -0
  52. package/dist/migration-journal.js.map +1 -0
  53. package/dist/next.d.ts +21 -0
  54. package/dist/next.d.ts.map +1 -0
  55. package/dist/next.js +210 -0
  56. package/dist/next.js.map +1 -0
  57. package/dist/operation-help.d.ts.map +1 -1
  58. package/dist/operation-help.js +14 -3
  59. package/dist/operation-help.js.map +1 -1
  60. package/dist/pack.d.ts.map +1 -1
  61. package/dist/pack.js +24 -2
  62. package/dist/pack.js.map +1 -1
  63. package/dist/position.d.ts +22 -0
  64. package/dist/position.d.ts.map +1 -0
  65. package/dist/position.js +242 -0
  66. package/dist/position.js.map +1 -0
  67. package/dist/project.d.ts +42 -0
  68. package/dist/project.d.ts.map +1 -0
  69. package/dist/project.js +232 -0
  70. package/dist/project.js.map +1 -0
  71. package/dist/read.d.ts +12 -2
  72. package/dist/read.d.ts.map +1 -1
  73. package/dist/read.js +29 -18
  74. package/dist/read.js.map +1 -1
  75. package/dist/render.d.ts +8 -0
  76. package/dist/render.d.ts.map +1 -1
  77. package/dist/render.js +16 -0
  78. package/dist/render.js.map +1 -1
  79. package/dist/session.d.ts +9 -3
  80. package/dist/session.d.ts.map +1 -1
  81. package/dist/session.js +24 -8
  82. package/dist/session.js.map +1 -1
  83. package/package.json +6 -6
  84. package/assets/host/c5fb2bfbba619cbd558ecc1e94dd2c16e37aa8599b4e423f1f59ed01f2074e03.tgz +0 -0
package/dist/host.js CHANGED
@@ -1,34 +1,41 @@
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, the steward guard hook and the workspace projection,
5
- * plus the context element §5.2's gate keeps unselected. It plans by default and never writes while planning — the
6
- * payload's location is computed, not created. `--apply` materializes the embedded payload once per user (§3.3),
7
- * re-plans every sub-transaction against the verified payload, then applies them in order — mcp, hooks, projection —
8
- * and removal runs them in reverse (§8). No cross-file atomicity is claimed: a rerun converges, and a pending journal
9
- * refuses naming its recovery. Nothing here reports that a server answered or a hook ran; `applied.observed` is
10
- * always false (plan-0002 M5 exit).
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).
11
11
  *
12
- * The plan asks the mechanisms themselves. `planHostFor` and `planGuardFor` plan against the payload apply will
13
- * materialize, described from the pin without reading it (`expectedHostCache`), so a conflict in the preview is the
14
- * service's own refusal — its code and message unchanged (contract §4.1) — and is the refusal apply would raise.
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
17
+ * (`projectionElement`), re-plan (`replanProjection`) and writer, and its file rows (`projectionFileRows`).
18
+ *
19
+ * The plan asks the mechanisms themselves. `planHostFor` plans against the payload apply will materialize, described
20
+ * 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.
15
22
  */
16
23
  import { createHash } from 'node:crypto';
17
24
  import { existsSync, realpathSync, statSync } from 'node:fs';
18
- import { resolve } from 'node:path';
25
+ import { dirname, isAbsolute, relative, resolve } from 'node:path';
19
26
  import { lifecycleProfile } from '@inventarch/workspace-runtime/lifecycle-profile';
20
- import { WORKSPACE_PROJECTION_MARKER } from '@inventarch/compliance';
21
- import { applyGuardRegistration, planGuardFor, planGuardRegistration, } from '@inventarch/distribution/guard-registration';
22
- import { hostRow, workspaceRow } from '@inventarch/distribution/hosts';
23
- import { applyHost, assertHostRegistrationIdle, expectedHostCache, HOST_REGISTRATION, planHost, planHostFor, } from '@inventarch/distribution/host';
27
+ import { hostRow, WORKSPACE_HOSTS, workspaceRow } from '@inventarch/distribution/hosts';
28
+ import { recoverInstallation } from '@inventarch/distribution/install';
29
+ import { recoverGuardRegistration } from '@inventarch/distribution/guard-registration';
30
+ import { recoverLifecycleRegistration } from '@inventarch/distribution/lifecycle-registration';
31
+ import { applyHost, assertHostRegistrationIdle, expectedHostCache, HOST_REGISTRATION, planHost, planHostFor, recoverHost, } from '@inventarch/distribution/host';
24
32
  import { assertHomeOutsideWorkspace, hostPayloadPath, materializeHostPayload, readHostPin, } from '@inventarch/distribution/host-home';
25
33
  import { assertIaHomeUsable } from '@inventarch/distribution/ia-home';
26
34
  import { readMaterializedPlugin } from '@inventarch/distribution/plugin-home';
27
- import { applyProjection, planProjection } from '@inventarch/distribution/projection';
28
35
  import { UsageError } from './args.js';
29
36
  import { homeSrcRemedy, hostHome, located } from './home-remedy.js';
30
37
  import { confirm, Interrupted, Refusal, refusalOf, requireRoot } from './consumer.js';
31
- import { checkAdmitted, renderProjectionFor } from './host-projection.js';
38
+ import { applyHostProjection, checkAdmitted, planFiles, planRetirement, renderProjectionFor, } from './host-projection.js';
32
39
  import { codeOf } from './session.js';
33
40
  import { atom, blockSymbolWidth, commandFacts, document, entry, fieldRows, headerLine, indentOf, quote, sectionLabel, truncateDigest, words, } from './render.js';
34
41
  import { runUserHost } from './user-host.js';
@@ -39,22 +46,30 @@ export const USER_PLUGIN_COMMAND = 'ia host claude --user --apply';
39
46
  export const USER_PLUGIN_MISSING = `The user-level plugin is not installed; run "${USER_PLUGIN_COMMAND}" to add it.`;
40
47
  /** §5.3's sentence, verbatim, per host. Every element — the projection included — is machine-local. */
41
48
  export const MACHINE_LOCAL = {
42
- claude: 'These files are machine-local: .mcp.json, .claude/settings.local.json, .claude/rules/ia-workspace.md, .claude/skills/ia-authoring/, the projected .claude/agents/*.md files and .ia/distributions/. Do not commit them.',
49
+ claude: 'These files are machine-local: .mcp.json, .claude/settings.local.json, .claude/rules/ia-workspace.md, .claude/skills/ia-authoring/ and .ia/distributions/. Do not commit them.',
43
50
  codex: 'These files are machine-local: .codex/config.toml, AGENTS.md, .agents/skills/ia-authoring/ and .ia/distributions/. Do not commit them.',
44
51
  };
45
52
  /** §5.4: the MCP element's one fixed addition, from §2.3's host facts. */
46
53
  export const MCP_APPROVAL = 'Claude Code asks for approval before starting a project MCP server.';
47
- /** Operator decision 2026-09-23 ("narrow + disclose"): what the registered steward guard refuses, said where it is registered. */
48
- export const GUARD_SCOPE = "The steward guard denies file-tool edits to the files ia host owns and to records under .ia/src/systems/<name>/ unless the edit comes from that system's steward subagent (<name>-steward).";
54
+ /**
55
+ * Operator decision 2026-10-08 (plan amendment B11), said where the guard used to be registered, as operator decision
56
+ * 2026-09-23 ("narrow + disclose") said what it refused: the guard is retired, so nothing it refused is refused now.
57
+ */
58
+ export const GUARD_SCOPE = 'ia host registers no steward guard, and applying the projection retires one an earlier release registered: with no per-system steward subagents left, it would deny every edit under .ia/src/systems/<name>/. Until a later release re-keys the guard to @mandate scope, nothing blocks those edits.';
49
59
  /** §5.1's files, exported once so `ia doctor` names the same ones. */
50
60
  export const MCP_PATH = { claude: '.mcp.json', codex: '.codex/config.toml' };
51
61
  export const SETTINGS = '.claude/settings.local.json';
52
62
  export const HOSTS_AREA = '.ia/distributions/hosts';
53
- /** §5.1's state files. Their presence says whether this workspace owns an element; their content is the mechanisms'. */
63
+ /**
64
+ * §5.1's state files. Their presence says whether this workspace owns an element; their content is the mechanisms'.
65
+ * `hooks` is a steward-guard registration an earlier release made, which the projection apply retires (B11), and
66
+ * `receipt` the receipt it writes beside the projection state (B12).
67
+ */
54
68
  export const STATE = {
55
69
  mcp: (host) => `${HOSTS_AREA}/${host}-${HOST_REGISTRATION}.json`,
56
70
  hooks: `${HOSTS_AREA}/claude-guard-${HOST_REGISTRATION}.json`,
57
71
  projection: (host) => `${HOSTS_AREA}/${host}-projection.json`,
72
+ receipt: (host) => `${HOSTS_AREA}/${host}-receipt.json`,
58
73
  };
59
74
  /**
60
75
  * What one host's MCP element owns, named so a user can find and delete exactly it. Codex's is a marked block
@@ -77,7 +92,7 @@ export function stateRepair(host, path, rerun) {
77
92
  return `Delete ${path} and ${OWNED_MCP[host]}, then run "${rerun}".`;
78
93
  if (host === 'claude' && path === STATE.hooks)
79
94
  return `Delete ${path} and ${OWNED_GUARD}, then run "${rerun}".`;
80
- if (path === STATE.projection(host))
95
+ if (path === STATE.projection(host) || path === STATE.receipt(host))
81
96
  return `Delete ${path}, then run "${rerun}".`;
82
97
  return null;
83
98
  }
@@ -103,8 +118,35 @@ export const HOST_LOCK = `${HOSTS_AREA}/lock.json`;
103
118
  * names `ia host` instead of such a remedy.
104
119
  */
105
120
  export const THEN_RERUN = ', then rerun.';
106
- /** A recovery on the distribution binary, rooted and quoted as every printed root is. */
107
- export const recoverCommand = (command, root) => `ia-distribution ${command} --root ${quote(root)}`;
121
+ /** An installed CLI recovery, delegating the named distribution mechanism with an explicit root. */
122
+ export const recoverCommand = (command, root) => `ia recover ${command === 'recover' ? 'installation' : command.replace(/^recover-/, '')} --root ${quote(root)}`;
123
+ /** Recovery needs an existing explicit root, including one whose initialization was interrupted. */
124
+ export function runRecovery(context) {
125
+ const mechanisms = {
126
+ installation: recoverInstallation,
127
+ host: recoverHost,
128
+ guard: recoverGuardRegistration,
129
+ lifecycle: recoverLifecycleRegistration,
130
+ };
131
+ const selected = context.args.positionals[0] ?? 'installation';
132
+ if (!Object.hasOwn(mechanisms, selected))
133
+ throw new UsageError('Recovery must be installation, host, guard or lifecycle');
134
+ const root = requireRoot(context);
135
+ try {
136
+ const result = mechanisms[selected](root);
137
+ return {
138
+ exitCode: 0,
139
+ stdout: context.json
140
+ ? JSON.stringify({ version: 1, ok: true, recovery: selected, root, result }) + '\n'
141
+ : `${selected} recovery: ${result.status}.\n`,
142
+ stderr: '',
143
+ };
144
+ }
145
+ catch (error) {
146
+ const refusal = refusalOf(error);
147
+ throw new Refusal(refusal.code, refusal.message, 3, refusedPath(error) === null ? refusal.where : { path: refusedPath(error) }, `Preserve the recovery state, resolve the reported conflict or wait for its running owner to finish, then run "ia recover ${selected} --root ${quote(root)}".`);
148
+ }
149
+ }
108
150
  /**
109
151
  * §8 "or refuses naming a recovery": a held host lock is another run or a killed one, and nothing here can tell
110
152
  * which, so the next action names the recovery that decides it — `recoverHost` takes the lock in recovery mode,
@@ -138,34 +180,84 @@ export function pinnedRelease(packageRoot) {
138
180
  return { release: null, code: codeOf(error, 'IA-DIST-ARTIFACT-UNAVAILABLE') };
139
181
  }
140
182
  }
141
- /** §4: the target must be initialized and admit; anything else names ia init or ia validate. */
142
- function requireInitialized(root) {
183
+ /**
184
+ * §4: the target must be initialized and admit; anything else names ia init or ia validate. `named` is the root as the
185
+ * init it names spells it: `ia host` names the resolved root, and `ia project` the root as its invocation typed it.
186
+ */
187
+ export function requireInitialized(root, named = root) {
143
188
  if (!existsSync(resolve(root, '.ia/release.json')))
144
- throw new Refusal('IA-CLI-CONFLICT', 'The target is not an initialized workspace: .ia/release.json is absent', 3, { path: root }, `Run "ia init ${quote(root)}" first.`);
189
+ throw new Refusal('IA-CLI-CONFLICT', 'The target is not an initialized workspace: .ia/release.json is absent', 3, { path: root }, `Run "ia init ${quote(named)}" first.`);
145
190
  }
146
191
  /** The journal a failed transaction left behind, if any, with the command that recovers it. */
147
- const pendingJournal = (root) => JOURNALS.find(([path]) => existsSync(resolve(root, path)));
192
+ export const pendingJournal = (root) => JOURNALS.find(([path]) => existsSync(resolve(root, path)));
148
193
  /** Design row 27: the recovery is the one command named; the refused command is simply run again after it. */
149
- const recoverNext = (root, command) => `Run "${recoverCommand(command, root)}"${THEN_RERUN}`;
194
+ export const recoverNext = (root, command) => `Run "${recoverCommand(command, root)}"${THEN_RERUN}`;
150
195
  /**
151
- * A next action of this verb made runnable from any cwd: every quoted `ia host <host>` command it names, and the
152
- * `ia validate` a workspace that does not admit names (host-projection.ts), gains `--root <root>`. `ia init --host`
153
- * uses it, because its `<directory>` may not be the cwd a rerun discovers from. Every such command opens with
154
- * `"ia host <host>` or `"ia validate` and none names `--root` itself, so the rewrite reaches each one and nothing else.
196
+ * A next action of this verb made runnable from any cwd: every quoted `ia host <host>` or `ia project <host>` command
197
+ * it names, and the `ia validate` a workspace that does not admit names (host-projection.ts), gains `--root <root>`.
198
+ * `ia init --host` uses it, because its `<directory>` may not be the cwd a rerun discovers from, and so do `ia project`
199
+ * and `ia doctor`. Every such command opens with `"ia host <host>`, `"ia project <host>` or `"ia validate`, and one
200
+ * that names `--root` itself is left as it is, so the rewrite reaches each one and nothing else.
155
201
  */
156
- export const rootedNext = (next, host, root) => next.replace(new RegExp(`"ia (?:host ${host}|validate)(?! --root\\b)`, 'g'), (command) => `${command} --root ${quote(root)}`);
202
+ export const rootedNext = (next, host, root) => next.replace(new RegExp(`"ia (?:host ${host}|project ${host}|validate)(?! --root\\b)`, 'g'), (command) => `${command} --root ${quote(root)}`);
157
203
  /** A next action as printed: with `--root` given, each `ia host <host>` command in it carries the root. */
158
204
  export const hostNext = (text, host, root, rooted) => rooted ? rootedNext(text, host, root) : text;
159
205
  /** The file a mechanism located its refusal at (`locate` in @inventarch/distribution's files.ts), or null. */
160
- export const refusedPath = (error) => error !== null && typeof error === 'object' && 'path' in error && typeof error.path === 'string' ? error.path : null;
206
+ export const refusedPath = (error) => /^IA-/.test(codeOf(error, '')) &&
207
+ error !== null &&
208
+ typeof error === 'object' &&
209
+ 'path' in error &&
210
+ typeof error.path === 'string'
211
+ ? error.path
212
+ : null;
161
213
  /**
162
- * §6.3: the repair for a projection refusal located at `path`. The ownership state has its own repair; any other file
163
- * is never replaced or adopted, so it is moved or deleted first. `ia host`, `ia doctor` and the install refresh all
164
- * name it this way.
214
+ * §6.3: the repair for a projection refusal with `code` located at `path`. The ownership state has its own repair; a
215
+ * guard group the retirement (B11) refuses as changed is deleted by hand, after which the retirement removes the
216
+ * ownership state alone, and settings it cannot read are fixed; any other file is never replaced or adopted, so it is
217
+ * moved or deleted first. `ia host`, `ia doctor` and the install refresh all name it this way.
165
218
  */
166
- export const projectionRepair = (host, path, rerun) => stateRepair(host, path, rerun) ?? `Move or delete ${path}, then run "${rerun}".`;
167
- /** §8: a pending journal refuses the whole verb and names the recovery that clears it. */
168
- function requireIdle(root, supplied) {
219
+ export const projectionRepair = (host, path, rerun, code) => code === 'IA-CLI-FAILED'
220
+ ? `Make ${path} writable and release any file lock, then run "${rerun}".`
221
+ : (stateRepair(host, path, rerun) ??
222
+ (![SETTINGS, '.claude/settings.json'].includes(path)
223
+ ? `Move or delete ${path}, then run "${rerun}".`
224
+ : code === undefined || code === 'IA-DIST-LOCAL-MODIFICATION'
225
+ ? `Delete only the IA guard group in ${path}, then run "${rerun}".`
226
+ : `Fix ${path}, then run "${rerun}".`));
227
+ /** A journal owns recovery; raw operating-system errors never authorize deleting settings or ownership. */
228
+ export function projectionFailure(error, root, host, rerun) {
229
+ const refusal = refusalOf(error), journal = pendingJournal(root);
230
+ if (journal !== undefined)
231
+ return new Refusal(refusal.code, refusal.message, 3, { path: journal[0] }, recoverNext(root, journal[1]));
232
+ const busy = lockRefusal(error, root);
233
+ if (busy !== null)
234
+ return busy;
235
+ const located = refusedPath(error);
236
+ if (located !== null) {
237
+ const path = isAbsolute(located) ? relative(root, located).replaceAll('\\', '/') : located;
238
+ return new Refusal(refusal.code, refusal.message, 3, { path }, rootedNext(projectionRepair(host, path, rerun, refusal.code), host, root));
239
+ }
240
+ const system = error;
241
+ if (system && ['EACCES', 'EPERM', 'EBUSY', 'EROFS', 'EISDIR', 'ENOTDIR'].includes(system.code ?? '')) {
242
+ const path = typeof system.path === 'string' ? (system.path.endsWith('.tmp') ? dirname(system.path) : system.path) : root;
243
+ return new Refusal(refusal.code, refusal.message, 3, { path }, rootedNext(`Make ${path} writable and release any file lock, then run "${rerun}".`, host, root));
244
+ }
245
+ return new Refusal(refusal.code, refusal.message, 3, refusal.where, rootedNext(error instanceof Refusal && refusal.next !== null ? refusal.next : `Run "${rerun}" to finish.`, host, root));
246
+ }
247
+ /**
248
+ * Host registration spec §4: the hosts whose projection this workspace owns, by their projection state's presence, as
249
+ * `ia host`, `ia doctor` and the install refresh decide it, a projection `ia project` wrote without a registration
250
+ * included.
251
+ */
252
+ export const projectedHosts = (root) => WORKSPACE_HOSTS.filter((host) => existsSync(resolve(root, STATE.projection(host))));
253
+ /**
254
+ * The apply that repairs `host`'s projection, which `ia doctor` and the install refresh both name (task
255
+ * ia-project-verb): `ia host <host> --apply` for a registered host, and `ia project <host> --apply` for a projection
256
+ * `ia project` wrote without a registration, which `ia host` would also register an MCP server for.
257
+ */
258
+ export const projectionRerun = (root, host) => existsSync(resolve(root, STATE.mcp(host))) ? `ia host ${host} --apply` : `ia project ${host} --apply`;
259
+ /** §8: a pending journal refuses the whole verb and names the recovery that clears it. `ia project` shares it. */
260
+ export function requireIdle(root, supplied) {
169
261
  try {
170
262
  assertHostRegistrationIdle(root);
171
263
  }
@@ -178,7 +270,10 @@ function requireIdle(root, supplied) {
178
270
  /** A mechanism's refusal as an element conflict: the service's code and message, located at its file. */
179
271
  function conflictOf(error, path) {
180
272
  const refusal = refusalOf(error);
181
- return { code: refusal.code, path: refusedPath(error) ?? path, reason: refusal.message };
273
+ const raw = error;
274
+ const at = refusedPath(error) ??
275
+ (typeof raw?.path === 'string' ? (raw.path.endsWith('.tmp') ? dirname(raw.path) : raw.path) : path);
276
+ return { code: refusal.code, path: at, reason: refusal.message };
182
277
  }
183
278
  const pin = (text) => text === null ? null : createHash('sha256').update(text).digest('hex');
184
279
  /** A registration plan's action, from the bytes it would write against the bytes it read. */
@@ -190,20 +285,20 @@ const actionOf = (plan) => plan.after.state === null
190
285
  ? 'unchanged'
191
286
  : 'update';
192
287
  /** One registration element, planned by its mechanism; `none` when a removal finds nothing owned. */
193
- function registrationElement(id, path, owned, remove, plan) {
288
+ function registrationElement(path, owned, remove, plan) {
194
289
  if (remove && !owned)
195
- return { id, action: 'none', paths: [path], capability: 'absent', conflict: null };
290
+ return { id: 'mcp', action: 'none', paths: [path], capability: 'absent', conflict: null };
196
291
  try {
197
- return { id, action: actionOf(plan()), paths: [path], capability: 'registered', conflict: null };
292
+ return { id: 'mcp', action: actionOf(plan()), paths: [path], capability: 'registered', conflict: null };
198
293
  }
199
294
  catch (error) {
200
- return { id, action: 'refused', paths: [path], capability: 'refused', conflict: conflictOf(error, path) };
295
+ return { id: 'mcp', action: 'refused', paths: [path], capability: 'refused', conflict: conflictOf(error, path) };
201
296
  }
202
297
  }
203
298
  /**
204
299
  * §5.2: the context element. Claude reports it `not selected` until the gate lifts; Codex reports it `unsupported by
205
- * host`, because it is delivered through lifecycle hooks and Codex hooks are unavailable — the same reason the
206
- * hooks element gives — so both hosts carry the same four rows.
300
+ * host`, because it is delivered through lifecycle hooks and Codex hooks are unavailable, so both hosts carry the
301
+ * same three rows.
207
302
  */
208
303
  const contextElement = (host) => ({
209
304
  id: 'context',
@@ -212,18 +307,38 @@ const contextElement = (host) => ({
212
307
  capability: host === 'claude' ? 'not selected' : 'unsupported by host',
213
308
  conflict: null,
214
309
  });
215
- /** §5.1 `projection`, planned by the real planner: it reads only the workspace, so the plan is exactly apply's. */
216
- function projectionElement(root, host, artifacts) {
310
+ /**
311
+ * §5.1 `projection`, planned by the real planners: B11's retirement of an owned guard registration, then the file plan
312
+ * (B9). Both read only the workspace, so the plan is exactly apply's. A retirement is a change, and so is a missing
313
+ * receipt, which every apply writes (B12), so a projection whose files are unchanged is then an update; a removal that
314
+ * finds only a guard registration or a receipt removes them. `ia project` plans with it, and both verbs' applies
315
+ * re-plan with it (`replanProjection`), so no two of them can plan the projection differently.
316
+ */
317
+ export function projectionElement(root, host, rendered) {
318
+ const refused = (conflict) => ({
319
+ id: 'projection',
320
+ action: 'refused',
321
+ paths: [],
322
+ capability: 'refused',
323
+ conflict,
324
+ });
325
+ let guard;
217
326
  try {
218
- const files = planProjection({ root, host, artifacts, marker: WORKSPACE_PROJECTION_MARKER }).actions;
219
- const touched = files.filter((file) => file.action !== 'unowned');
220
- const action = artifacts.length === 0
221
- ? touched.some((file) => file.action === 'remove')
327
+ guard = planRetirement(root, host) === null ? 'none' : 'retire';
328
+ }
329
+ catch (error) {
330
+ return refused(conflictOf(error, SETTINGS));
331
+ }
332
+ try {
333
+ const files = planFiles(root, host, rendered).actions;
334
+ const touched = files.filter((file) => file.action !== 'foreign'), changes = guard === 'retire', receipt = existsSync(resolve(root, STATE.receipt(host)));
335
+ const action = rendered === null
336
+ ? touched.some((file) => file.action === 'remove') || changes || receipt
222
337
  ? 'remove'
223
338
  : 'none'
224
- : touched.every((file) => file.action === 'unchanged')
339
+ : touched.every((file) => file.action === 'unchanged') && !changes && receipt
225
340
  ? 'unchanged'
226
- : touched.every((file) => file.action === 'create')
341
+ : touched.every((file) => file.action === 'create') && !changes
227
342
  ? 'create'
228
343
  : 'update';
229
344
  return {
@@ -233,16 +348,11 @@ function projectionElement(root, host, artifacts) {
233
348
  capability: action === 'none' ? 'absent' : 'registered',
234
349
  conflict: null,
235
350
  files,
351
+ guard,
236
352
  };
237
353
  }
238
354
  catch (error) {
239
- return {
240
- id: 'projection',
241
- action: 'refused',
242
- paths: [],
243
- capability: 'refused',
244
- conflict: conflictOf(error, STATE.projection(host)),
245
- };
355
+ return refused(conflictOf(error, STATE.projection(host)));
246
356
  }
247
357
  }
248
358
  /** The invocation is rebuilt from the parsed arguments, so the printed command is the one that was understood. */
@@ -290,30 +400,25 @@ export function collectHost(context) {
290
400
  const { pin: bundled } = bundledPin(host.packageRoot);
291
401
  requireIdle(root, supplied);
292
402
  // §4: zero error findings. A removal renders nothing, so it checks admission alone.
293
- let artifacts = [];
403
+ let rendered = null;
294
404
  if (remove)
295
405
  checkAdmitted(root);
296
406
  else
297
- artifacts = renderProjectionFor(root, name);
407
+ rendered = renderProjectionFor(root, name);
298
408
  // A host home reached through a symbolic link or junction is refused by the mechanism (IA-DIST-PATH-UNSAFE), because
299
409
  // the payload it verifies must be the one the registration names; the remedy is a home with no link in its path.
300
410
  const expected = located(null, `Set IA_HOME to a directory path with no links, or unset it; then run "${plan}".`, () => expectedHostCache(hostPayloadPath(home, bundled.release), bundled.release));
301
411
  const owned = new Set();
302
412
  if (existsSync(resolve(root, STATE.mcp(name))))
303
413
  owned.add('mcp');
304
- if (name === 'claude' && existsSync(resolve(root, STATE.hooks)))
305
- owned.add('hooks');
306
- const mcp = registrationElement('mcp', MCP_PATH[name], owned.has('mcp'), remove, () => remove ? planHostFor(root, name, null, HOST_REGISTRATION) : planHostFor(root, name, expected));
307
- const hooks = name === 'codex'
308
- ? { id: 'hooks', action: 'none', paths: [], capability: 'unsupported by host', conflict: null }
309
- : registrationElement('hooks', SETTINGS, owned.has('hooks'), remove, () => remove ? planGuardRegistration(root, { remove: HOST_REGISTRATION }) : planGuardFor(root, expected));
414
+ const mcp = registrationElement(MCP_PATH[name], owned.has('mcp'), remove, () => remove ? planHostFor(root, name, null, HOST_REGISTRATION) : planHostFor(root, name, expected));
310
415
  return {
311
416
  root: supplied,
312
417
  host: name,
313
418
  remove,
314
419
  release: bundled.release,
315
420
  home,
316
- elements: [mcp, hooks, contextElement(name), projectionElement(root, name, artifacts)],
421
+ elements: [mcp, contextElement(name), projectionElement(root, name, rendered)],
317
422
  undo: `ia host ${name} --remove --apply`,
318
423
  invocation: invocationOf(context, name, remove),
319
424
  owned,
@@ -321,6 +426,8 @@ export function collectHost(context) {
321
426
  userPlugin: row.user === 'plugin' ? { installed: readMaterializedPlugin(home) !== null, command: USER_PLUGIN_COMMAND } : null,
322
427
  };
323
428
  }
429
+ /** What an apply that retired the steward guard (B11) says it did. */
430
+ 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.';
324
431
  /** A next action of this verb as printed: with `--root` given, each `ia host` command in it carries the root. */
325
432
  const say = (view, text) => hostNext(text, view.host, view.root, view.rooted);
326
433
  /** The next action a conflict renders, and the one its refusal carries, rooted when `--root` was given. */
@@ -332,8 +439,6 @@ function conflictNext(view, id, conflict) {
332
439
  const unreadable = stateRepair(view.host, conflict.path, rerun);
333
440
  if (unreadable !== null)
334
441
  return unreadable;
335
- if (conflict.code === 'IA-DIST-LOCAL-MODIFICATION' && id === 'hooks' && view.owned.has('hooks'))
336
- return modifiedRepair(view.host, ['hooks']);
337
442
  if (conflict.code === 'IA-DIST-LOCAL-MODIFICATION' && id === 'mcp') {
338
443
  // Owned: removal tolerates a deleted entry, so deleting it and re-registering converges. Unowned: §5.3's wording,
339
444
  // made exact for Codex, where the collision can be any ia-workspace table or a file that no longer parses.
@@ -343,10 +448,8 @@ function conflictNext(view, id, conflict) {
343
448
  ? 'Remove any ia-workspace server outside the IA block from .codex/config.toml and make sure the file parses as TOML, then run "ia host codex --apply".'
344
449
  : `Remove that entry, then run "ia host ${view.host} --apply".`;
345
450
  }
346
- if (conflict.code === 'IA-DIST-HOST-UNSUPPORTED' && id === 'hooks')
347
- return `Remove disableAllHooks from the Claude settings, then run "${rerun}".`;
348
451
  if (id === 'projection')
349
- return projectionRepair(view.host, conflict.path, rerun);
452
+ return projectionRepair(view.host, conflict.path, rerun, conflict.code);
350
453
  return `Fix ${conflict.path}, then run "${rerun}".`;
351
454
  }
352
455
  const refusalFor = (view, id, conflict) => new Refusal(conflict.code, conflict.reason, 3, { path: conflict.path }, nextFor(view, id, conflict));
@@ -359,6 +462,17 @@ function replan(view, id, path, run) {
359
462
  throw refusalFor(view, id, conflictOf(error, path));
360
463
  }
361
464
  }
465
+ /**
466
+ * Apply's re-plan of the projection, shared by `ia host --apply` and `ia project --apply`: the projection element
467
+ * planned against the rendering the apply writes, so a conflict either of its planners finds (the guard retirement or
468
+ * the file plan) is raised, worded by the verb's `refuse`, before anything is written. `applyHostProjection` plans
469
+ * both again before its first write.
470
+ */
471
+ export function replanProjection(root, host, rendered, refuse) {
472
+ const { conflict } = projectionElement(root, host, rendered);
473
+ if (conflict !== null)
474
+ throw refuse(conflict);
475
+ }
362
476
  /**
363
477
  * §3.3 steps 3-4. A payload directory that fails verification is named by the mechanism and the remedy is to delete
364
478
  * it; nothing overwrites it. Any other failure is the bundled payload's own, which only a reinstall repairs.
@@ -379,12 +493,14 @@ function materialize(view, packageRoot) {
379
493
  }
380
494
  }
381
495
  /**
382
- * §8: mcp, hooks, projection in order; removal in reverse. The payload is materialized, then every sub-transaction is
383
- * re-planned with the verifying planners before any is applied, so a refusal any planner can find is raised before
384
- * the workspace changes; each apply then re-plans under the host lock and refuses a plan that went stale.
385
- * Cancellation is observed between sub-transactions. A failure after an element was written names the rerun that
386
- * finishes the set, or the recovery a pending journal needs. `checkpoint` runs after each element completes, which
387
- * is where an interruption test cuts.
496
+ * §8: mcp, projection in order; removal in reverse. The payload is materialized, then every sub-transaction is
497
+ * re-planned with the verifying planners before any is applied — the projection's guard retirement (B11) and file plan
498
+ * included — so a refusal any planner can find is raised before the workspace changes; each apply then re-plans under
499
+ * the host lock and refuses a plan that went stale. The projection is applied through `applyHostProjection`, the one
500
+ * writer of projection files, which retires an owned steward guard before any projection file changes and reports it
501
+ * as the element's `guard`. Cancellation is observed between sub-transactions. A failure after an element was written
502
+ * names the rerun that finishes the set, or the recovery a pending journal needs. `checkpoint` runs after each element
503
+ * completes, which is where an interruption test cuts.
388
504
  */
389
505
  export function applyHostSet(view, packageRoot, signal, checkpoint = () => { }) {
390
506
  const refused = view.elements.find((element) => element.conflict !== null);
@@ -400,11 +516,13 @@ export function applyHostSet(view, packageRoot, signal, checkpoint = () => { })
400
516
  const step = (id, run) => {
401
517
  if (signal?.aborted)
402
518
  throw new Interrupted(say(view, `Run "${rerun}" to finish.`));
403
- let status;
519
+ let applied;
404
520
  try {
405
- status = run();
521
+ applied = run();
406
522
  }
407
523
  catch (error) {
524
+ if (id === 'projection')
525
+ throw projectionFailure(error, root, host, rerun);
408
526
  const refusal = refusalOf(error), journal = pendingJournal(root);
409
527
  if (journal !== undefined)
410
528
  throw new Refusal(refusal.code, refusal.message, 3, { path: journal[0] }, say(view, recoverNext(view.root, journal[1])));
@@ -415,40 +533,32 @@ export function applyHostSet(view, packageRoot, signal, checkpoint = () => { })
415
533
  throw new Refusal(refusal.code, refusal.message, 3, refusal.where, say(view, `Run "${rerun}" to finish.`));
416
534
  throw error;
417
535
  }
418
- done.push({ id, status });
536
+ done.push({ id, ...applied });
419
537
  checkpoint(id);
420
538
  };
539
+ const project = (rendered) => () => {
540
+ const { status, guard } = applyHostProjection(root, host, rendered);
541
+ return { status, guard };
542
+ };
421
543
  if (!view.remove) {
422
544
  const cache = materialize(view, packageRoot);
423
545
  const mcp = replan(view, 'mcp', MCP_PATH[host], () => planHost(root, host, cache));
424
- const hooks = host === 'claude' ? replan(view, 'hooks', SETTINGS, () => planGuardRegistration(root, { cache })) : null;
425
- const artifacts = renderProjectionFor(root, host);
426
- const projection = replan(view, 'projection', STATE.projection(host), () => planProjection({ root, host, artifacts, marker: WORKSPACE_PROJECTION_MARKER }));
427
- step('mcp', () => applyHost(mcp).status);
428
- if (hooks === null)
429
- done.push(skipped('hooks'));
430
- else
431
- step('hooks', () => applyGuardRegistration(hooks).status);
546
+ const rendered = renderProjectionFor(root, host);
547
+ replanProjection(root, host, rendered, (conflict) => refusalFor(view, 'projection', conflict));
548
+ step('mcp', () => ({ status: applyHost(mcp).status }));
432
549
  done.push(skipped('context'));
433
- step('projection', () => applyProjection(projection).status);
550
+ step('projection', project(rendered));
434
551
  return { status: 'host-registered', elements: done, observed: false };
435
552
  }
436
553
  // A removal plans only what the view found owned; `none` means there is nothing of that element to remove.
437
554
  const absent = (id) => view.elements.find((element) => element.id === id).action === 'none';
438
- const projection = replan(view, 'projection', STATE.projection(host), () => planProjection({ root, host, artifacts: [], marker: WORKSPACE_PROJECTION_MARKER }));
439
- const hooks = host === 'claude' && !absent('hooks')
440
- ? replan(view, 'hooks', SETTINGS, () => planGuardRegistration(root, { remove: HOST_REGISTRATION }))
441
- : null;
555
+ replanProjection(root, host, null, (conflict) => refusalFor(view, 'projection', conflict));
442
556
  const mcp = absent('mcp')
443
557
  ? null
444
558
  : replan(view, 'mcp', MCP_PATH[host], () => planHost(root, host, null, HOST_REGISTRATION));
445
- step('projection', () => (applyProjection(projection).removed > 0 ? 'projection-removed' : 'absent'));
559
+ step('projection', project(null));
446
560
  done.push(skipped('context'));
447
- if (host === 'codex')
448
- done.push(skipped('hooks'));
449
- else
450
- step('hooks', () => (hooks === null ? 'absent' : applyGuardRegistration(hooks).status));
451
- step('mcp', () => (mcp === null ? 'absent' : applyHost(mcp).status));
561
+ step('mcp', () => ({ status: mcp === null ? 'absent' : applyHost(mcp).status }));
452
562
  return { status: 'host-removed', elements: done, observed: false };
453
563
  }
454
564
  /** §4 `--json`: the plan always, and `applied` only after an apply. */
@@ -472,7 +582,7 @@ const FILE_SYMBOL = {
472
582
  update: 'updated',
473
583
  unchanged: 'info',
474
584
  remove: 'removed',
475
- unowned: 'warning',
585
+ foreign: 'info',
476
586
  };
477
587
  const elementSymbol = (element) => element.conflict !== null
478
588
  ? 'error'
@@ -482,8 +592,10 @@ const elementSymbol = (element) => element.conflict !== null
482
592
  function elementFields(view) {
483
593
  return view.elements.map((element) => {
484
594
  const facts = [element.action, element.capability, ...(element.id === 'projection' ? [] : element.paths)];
485
- if (element.id === 'hooks' && element.capability === 'unsupported by host')
595
+ if (element.id === 'context' && element.capability === 'unsupported by host')
486
596
  facts.push(CODEX_HOOKS.replace(/\.$/, ''));
597
+ if (element.guard === 'retire')
598
+ facts.push(GUARD_RETIRE);
487
599
  if (element.conflict !== null)
488
600
  facts.push(`${element.conflict.code} ${element.conflict.reason}`);
489
601
  return {
@@ -494,20 +606,22 @@ function elementFields(view) {
494
606
  };
495
607
  });
496
608
  }
497
- /** Each projected file with its action; an unowned steward file says why it is left alone. */
498
- const fileBlock = (view, caps) => (view.elements.find((element) => element.id === 'projection')?.files ?? []).flatMap((file) => entry([
609
+ /** A projection plan's B11 step as its plan says it, in `ia host` and `ia project` alike. */
610
+ export const GUARD_RETIRE = `first retires the steward guard registered in ${SETTINGS}`;
611
+ /**
612
+ * Each projected file with its action, at `column`; a foreign steward file says why it is left alone. `ia host` nests
613
+ * the rows under its projection element and `ia project` lists them as its file plan, so both word them alike.
614
+ */
615
+ export const projectionFileRows = (files, column, caps) => files.flatMap((file) => entry([
499
616
  [
500
617
  atom(file.path, 'cyan', 0),
501
- ...words(file.action === 'unowned'
502
- ? "unowned; marked but not listed in this workspace's projection state, left untouched"
618
+ ...words(file.action === 'foreign'
619
+ ? "foreign; not this workspace's projection to write or delete, left in place"
503
620
  : file.action, null, 2),
504
621
  ],
505
- ],
506
- // Nested at the elements block's content column (§6.4 rule 3), so each file sits under the element it belongs to.
507
- {
508
- column: indentOf(1) + blockSymbolWidth(view.elements.map(elementSymbol), caps.ascii) + 2,
509
- symbol: FILE_SYMBOL[file.action],
510
- }, caps));
622
+ ], { column, symbol: FILE_SYMBOL[file.action] }, caps));
623
+ /** Each projected file, nested at the elements block's content column (§6.4 rule 3), under the element it belongs to. */
624
+ const fileBlock = (view, caps) => projectionFileRows(view.elements.find((element) => element.id === 'projection')?.files ?? [], indentOf(1) + blockSymbolWidth(view.elements.map(elementSymbol), caps.ascii) + 2, caps);
511
625
  const headerBlock = (view, caps) => [
512
626
  ...headerLine('Plan', `host ${view.host}${view.remove ? ' --remove' : ''}`, [{ text: `release ${truncateDigest(view.release, caps.ascii)}`, column: 35 }], caps),
513
627
  ...headerLine('Root', view.root, [], caps),
@@ -519,9 +633,9 @@ const elementsBlock = (view, caps) => [
519
633
  ...fileBlock(view, caps),
520
634
  ];
521
635
  /**
522
- * §5.3's machine-local sentence and, for a Claude registration, §5.4's approval note and the guard's scope (the
523
- * hooks element is registered only for Claude). `ia init --host` prints the same blocks after its host step, so the
524
- * two verbs cannot word them differently.
636
+ * §5.3's machine-local sentence and, for a Claude registration, §5.4's approval note and the guard's retirement (only
637
+ * Claude ever registered the guard, B11). `ia init --host` prints the same blocks after its host step, so the two verbs
638
+ * cannot word them differently.
525
639
  */
526
640
  export const hostNotes = (host, caps, remove = false) => [
527
641
  entry([words(MACHINE_LOCAL[host])], { depth: 1, symbol: 'warning' }, caps),
@@ -552,6 +666,7 @@ export function renderHostPlan(view, applied, caps) {
552
666
  words(applied.status === 'host-registered'
553
667
  ? 'Registered: written; not observed answering.'
554
668
  : 'Removed the owned host set.'),
669
+ ...(applied.elements.some((element) => element.guard === 'retired') ? [words(GUARD_RETIRED)] : []),
555
670
  ], { depth: 1, symbol: 'success' }, caps),
556
671
  elementsBlock(view, caps),
557
672
  ...notesBlocks(view, caps),