@inventarch/cli 1.2.0 → 3.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 (125) hide show
  1. package/README.md +20 -5
  2. package/SPEC.md +86 -11
  3. package/assets/base/08eaab3e1a6215d78283b82a94a0228367ac7bd78d0a746c56db79c8d7546c3a.ia.tgz +0 -0
  4. package/assets/base.json +3 -3
  5. package/assets/host/d7722e32fd0511df2a6dfdf2353e621fdff1cf559d5c8b7ac256c7eceac0452f.tgz +0 -0
  6. package/assets/host.json +4 -4
  7. package/assets/vocabulary.json +11 -3
  8. package/dist/adopt.d.ts +8 -0
  9. package/dist/adopt.d.ts.map +1 -0
  10. package/dist/adopt.js +60 -0
  11. package/dist/adopt.js.map +1 -0
  12. package/dist/author.d.ts +32 -0
  13. package/dist/author.d.ts.map +1 -0
  14. package/dist/author.js +226 -0
  15. package/dist/author.js.map +1 -0
  16. package/dist/briefing.d.ts +2 -0
  17. package/dist/briefing.d.ts.map +1 -1
  18. package/dist/briefing.js +15 -3
  19. package/dist/briefing.js.map +1 -1
  20. package/dist/bundled-base.d.ts +18 -0
  21. package/dist/bundled-base.d.ts.map +1 -0
  22. package/dist/bundled-base.js +44 -0
  23. package/dist/bundled-base.js.map +1 -0
  24. package/dist/capture.d.ts +41 -6
  25. package/dist/capture.d.ts.map +1 -1
  26. package/dist/capture.js +132 -43
  27. package/dist/capture.js.map +1 -1
  28. package/dist/commands.d.ts +30 -8
  29. package/dist/commands.d.ts.map +1 -1
  30. package/dist/commands.js +287 -35
  31. package/dist/commands.js.map +1 -1
  32. package/dist/compile.d.ts +3 -4
  33. package/dist/compile.d.ts.map +1 -1
  34. package/dist/compile.js +28 -72
  35. package/dist/compile.js.map +1 -1
  36. package/dist/consumer.d.ts +11 -2
  37. package/dist/consumer.d.ts.map +1 -1
  38. package/dist/consumer.js +103 -20
  39. package/dist/consumer.js.map +1 -1
  40. package/dist/distribute.d.ts +30 -8
  41. package/dist/distribute.d.ts.map +1 -1
  42. package/dist/distribute.js +112 -60
  43. package/dist/distribute.js.map +1 -1
  44. package/dist/doctor-authority.d.ts +3 -0
  45. package/dist/doctor-authority.d.ts.map +1 -0
  46. package/dist/doctor-authority.js +65 -0
  47. package/dist/doctor-authority.js.map +1 -0
  48. package/dist/doctor-mounts.d.ts +4 -0
  49. package/dist/doctor-mounts.d.ts.map +1 -0
  50. package/dist/doctor-mounts.js +32 -0
  51. package/dist/doctor-mounts.js.map +1 -0
  52. package/dist/doctor.d.ts.map +1 -1
  53. package/dist/doctor.js +327 -79
  54. package/dist/doctor.js.map +1 -1
  55. package/dist/format.d.ts.map +1 -1
  56. package/dist/format.js +2 -1
  57. package/dist/format.js.map +1 -1
  58. package/dist/host-projection.d.ts +131 -6
  59. package/dist/host-projection.d.ts.map +1 -1
  60. package/dist/host-projection.js +663 -42
  61. package/dist/host-projection.js.map +1 -1
  62. package/dist/host.d.ts +154 -32
  63. package/dist/host.d.ts.map +1 -1
  64. package/dist/host.js +393 -142
  65. package/dist/host.js.map +1 -1
  66. package/dist/init.d.ts +296 -38
  67. package/dist/init.d.ts.map +1 -1
  68. package/dist/init.js +1303 -203
  69. package/dist/init.js.map +1 -1
  70. package/dist/main.d.ts +1 -6
  71. package/dist/main.d.ts.map +1 -1
  72. package/dist/main.js +4 -7
  73. package/dist/main.js.map +1 -1
  74. package/dist/migration-journal.d.ts +35 -0
  75. package/dist/migration-journal.d.ts.map +1 -0
  76. package/dist/migration-journal.js +205 -0
  77. package/dist/migration-journal.js.map +1 -0
  78. package/dist/next.d.ts +21 -0
  79. package/dist/next.d.ts.map +1 -0
  80. package/dist/next.js +216 -0
  81. package/dist/next.js.map +1 -0
  82. package/dist/operation-help.d.ts.map +1 -1
  83. package/dist/operation-help.js +15 -4
  84. package/dist/operation-help.js.map +1 -1
  85. package/dist/pack.d.ts.map +1 -1
  86. package/dist/pack.js +24 -2
  87. package/dist/pack.js.map +1 -1
  88. package/dist/position.d.ts +22 -0
  89. package/dist/position.d.ts.map +1 -0
  90. package/dist/position.js +244 -0
  91. package/dist/position.js.map +1 -0
  92. package/dist/preview.d.ts +145 -0
  93. package/dist/preview.d.ts.map +1 -0
  94. package/dist/preview.js +962 -0
  95. package/dist/preview.js.map +1 -0
  96. package/dist/profile.d.ts +118 -0
  97. package/dist/profile.d.ts.map +1 -0
  98. package/dist/profile.js +362 -0
  99. package/dist/profile.js.map +1 -0
  100. package/dist/project.d.ts +45 -0
  101. package/dist/project.d.ts.map +1 -0
  102. package/dist/project.js +263 -0
  103. package/dist/project.js.map +1 -0
  104. package/dist/read.d.ts +12 -2
  105. package/dist/read.d.ts.map +1 -1
  106. package/dist/read.js +32 -18
  107. package/dist/read.js.map +1 -1
  108. package/dist/render.d.ts +24 -2
  109. package/dist/render.d.ts.map +1 -1
  110. package/dist/render.js +171 -4
  111. package/dist/render.js.map +1 -1
  112. package/dist/session.d.ts +39 -12
  113. package/dist/session.d.ts.map +1 -1
  114. package/dist/session.js +55 -11
  115. package/dist/session.js.map +1 -1
  116. package/dist/user-host.d.ts +3 -3
  117. package/dist/user-host.js +10 -10
  118. package/dist/user-host.js.map +1 -1
  119. package/dist/validate.d.ts +28 -16
  120. package/dist/validate.d.ts.map +1 -1
  121. package/dist/validate.js +245 -23
  122. package/dist/validate.js.map +1 -1
  123. package/package.json +6 -6
  124. package/assets/base/0305ca741b1dfec97ff35fbeb36d4a66a0c9c0614b730fe14fcdac0f1565e28a.ia.tgz +0 -0
  125. package/assets/host/c5fb2bfbba619cbd558ecc1e94dd2c16e37aa8599b4e423f1f59ed01f2074e03.tgz +0 -0
package/dist/host.js CHANGED
@@ -1,36 +1,51 @@
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.
22
+ *
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.
15
28
  */
16
29
  import { createHash } from 'node:crypto';
17
30
  import { existsSync, realpathSync, statSync } from 'node:fs';
18
- import { resolve } from 'node:path';
31
+ import { dirname, isAbsolute, relative, resolve } from 'node:path';
19
32
  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';
33
+ import { hostRow, WORKSPACE_HOSTS, workspaceRow } from '@inventarch/distribution/hosts';
34
+ import { recoverInstallation } from '@inventarch/distribution/install';
35
+ import { recoverGuardRegistration } from '@inventarch/distribution/guard-registration';
36
+ import { recoverLifecycleRegistration } from '@inventarch/distribution/lifecycle-registration';
37
+ import { applyHost, assertHostRegistrationIdle, expectedHostCache, HOST_REGISTRATION, planHost, planHostFor, recoverHost, } from '@inventarch/distribution/host';
24
38
  import { assertHomeOutsideWorkspace, hostPayloadPath, materializeHostPayload, readHostPin, } from '@inventarch/distribution/host-home';
39
+ import { joinHost, JOINS, leaveHost, readJoins } from '@inventarch/distribution/implementations';
25
40
  import { assertIaHomeUsable } from '@inventarch/distribution/ia-home';
26
41
  import { readMaterializedPlugin } from '@inventarch/distribution/plugin-home';
27
- import { applyProjection, planProjection } from '@inventarch/distribution/projection';
28
42
  import { UsageError } from './args.js';
29
43
  import { homeSrcRemedy, hostHome, located } from './home-remedy.js';
30
44
  import { confirm, Interrupted, Refusal, refusalOf, requireRoot } from './consumer.js';
31
- import { checkAdmitted, renderProjectionFor } from './host-projection.js';
45
+ import { sessionGate } from './profile.js';
46
+ import { applyHostProjection, notTaken, planFiles, planHookStep, planRetirement, renderProjectionFor, } from './host-projection.js';
32
47
  import { codeOf } from './session.js';
33
- import { atom, blockSymbolWidth, commandFacts, document, entry, fieldRows, headerLine, indentOf, quote, sectionLabel, truncateDigest, words, } from './render.js';
48
+ import { atom, blockSymbolWidth, commandFacts, document, entry, fieldRows, headerLine, indentOf, quote, safeRootAdvice, sectionLabel, truncateDigest, words, } from './render.js';
34
49
  import { runUserHost } from './user-host.js';
35
50
  /** The installation, not the workspace, is at fault; `ia doctor` names the channel a reinstall goes through. */
36
51
  const DAMAGED = 'The ia installation is damaged; run "ia doctor" for its install channel and reinstall @inventarch/cli through it, so assets/host travels with it.';
@@ -39,22 +54,32 @@ export const USER_PLUGIN_COMMAND = 'ia host claude --user --apply';
39
54
  export const USER_PLUGIN_MISSING = `The user-level plugin is not installed; run "${USER_PLUGIN_COMMAND}" to add it.`;
40
55
  /** §5.3's sentence, verbatim, per host. Every element — the projection included — is machine-local. */
41
56
  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.',
43
- codex: 'These files are machine-local: .codex/config.toml, AGENTS.md, .agents/skills/ia-authoring/ and .ia/distributions/. Do not commit them.',
57
+ 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
+ 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.',
44
59
  };
45
60
  /** §5.4: the MCP element's one fixed addition, from §2.3's host facts. */
46
61
  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).";
62
+ /**
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.
65
+ */
66
+ 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.';
49
67
  /** §5.1's files, exported once so `ia doctor` names the same ones. */
50
68
  export const MCP_PATH = { claude: '.mcp.json', codex: '.codex/config.toml' };
51
69
  export const SETTINGS = '.claude/settings.local.json';
52
70
  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'. */
71
+ /**
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).
75
+ */
54
76
  export const STATE = {
55
77
  mcp: (host) => `${HOSTS_AREA}/${host}-${HOST_REGISTRATION}.json`,
56
78
  hooks: `${HOSTS_AREA}/claude-guard-${HOST_REGISTRATION}.json`,
79
+ /** The ownership state of the groups registered for authored `@hook` records (distribution `hookStatePath`). */
80
+ hookGroups: `${HOSTS_AREA}/claude-hooks-${HOST_REGISTRATION}.json`,
57
81
  projection: (host) => `${HOSTS_AREA}/${host}-projection.json`,
82
+ receipt: (host) => `${HOSTS_AREA}/${host}-receipt.json`,
58
83
  };
59
84
  /**
60
85
  * What one host's MCP element owns, named so a user can find and delete exactly it. Codex's is a marked block
@@ -67,6 +92,8 @@ const OWNED_MCP = {
67
92
  `through "# END IA PROJECTION host-${HOST_REGISTRATION}", markers included`,
68
93
  };
69
94
  const OWNED_GUARD = `the IA guard group in ${SETTINGS}`;
95
+ /** The groups registered for authored `@hook` records, each running the guard for its hook. */
96
+ const OWNED_HOOKS = `every IA hook group in ${SETTINGS} (each runs the guard for one authored @hook)`;
70
97
  /**
71
98
  * The repair for an ownership state file that cannot be read, or null when `path` is not one. The mechanisms refuse
72
99
  * every plan until the file goes, and deleting it alone would leave what it owned looking unmanaged, so the repair
@@ -77,7 +104,10 @@ export function stateRepair(host, path, rerun) {
77
104
  return `Delete ${path} and ${OWNED_MCP[host]}, then run "${rerun}".`;
78
105
  if (host === 'claude' && path === STATE.hooks)
79
106
  return `Delete ${path} and ${OWNED_GUARD}, then run "${rerun}".`;
80
- if (path === STATE.projection(host))
107
+ // Review finding H-N3: the hook ownership state names the groups it owns, so both go before the rerun.
108
+ if (host === 'claude' && path === STATE.hookGroups)
109
+ return `Delete ${path} and ${OWNED_HOOKS}, then run "${rerun}".`;
110
+ if (path === STATE.projection(host) || path === STATE.receipt(host))
81
111
  return `Delete ${path}, then run "${rerun}".`;
82
112
  return null;
83
113
  }
@@ -103,8 +133,35 @@ export const HOST_LOCK = `${HOSTS_AREA}/lock.json`;
103
133
  * names `ia host` instead of such a remedy.
104
134
  */
105
135
  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)}`;
136
+ /** An installed CLI recovery, delegating the named distribution mechanism with an explicit root. */
137
+ export const recoverCommand = (command, root) => `ia recover ${command === 'recover' ? 'installation' : command.replace(/^recover-/, '')} --root ${quote(root)}`;
138
+ /** Recovery needs an existing explicit root, including one whose initialization was interrupted. */
139
+ export function runRecovery(context) {
140
+ const mechanisms = {
141
+ installation: recoverInstallation,
142
+ host: recoverHost,
143
+ guard: recoverGuardRegistration,
144
+ lifecycle: recoverLifecycleRegistration,
145
+ };
146
+ const selected = context.args.positionals[0] ?? 'installation';
147
+ if (!Object.hasOwn(mechanisms, selected))
148
+ throw new UsageError('Recovery must be installation, host, guard or lifecycle');
149
+ const root = requireRoot(context);
150
+ try {
151
+ const result = mechanisms[selected](root);
152
+ return {
153
+ exitCode: 0,
154
+ stdout: context.json
155
+ ? JSON.stringify({ version: 1, ok: true, recovery: selected, root, result }) + '\n'
156
+ : `${selected} recovery: ${result.status}.\n`,
157
+ stderr: '',
158
+ };
159
+ }
160
+ catch (error) {
161
+ const refusal = refusalOf(error);
162
+ 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)}".`);
163
+ }
164
+ }
108
165
  /**
109
166
  * §8 "or refuses naming a recovery": a held host lock is another run or a killed one, and nothing here can tell
110
167
  * which, so the next action names the recovery that decides it — `recoverHost` takes the lock in recovery mode,
@@ -138,34 +195,110 @@ export function pinnedRelease(packageRoot) {
138
195
  return { release: null, code: codeOf(error, 'IA-DIST-ARTIFACT-UNAVAILABLE') };
139
196
  }
140
197
  }
141
- /** §4: the target must be initialized and admit; anything else names ia init or ia validate. */
142
- function requireInitialized(root) {
198
+ /**
199
+ * §4: the target must be initialized and admit; anything else names ia init or ia validate. `named` is the root as the
200
+ * init it names spells it: `ia host` names the resolved root, and `ia project` the root as its invocation typed it.
201
+ */
202
+ export function requireInitialized(root, named = root) {
143
203
  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.`);
204
+ 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
205
  }
146
206
  /** 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)));
207
+ export const pendingJournal = (root) => JOURNALS.find(([path]) => existsSync(resolve(root, path)));
148
208
  /** 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}`;
209
+ export const recoverNext = (root, command) => `Run "${recoverCommand(command, root)}"${THEN_RERUN}`;
150
210
  /**
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.
211
+ * A next action of this verb made runnable from any cwd: every quoted `ia host <host>` or `ia project <host>` command
212
+ * it names, and the `ia validate` a workspace that does not admit names (host-projection.ts), gains `--root <root>`.
213
+ * `ia init --host` uses it, because its `<directory>` may not be the cwd a rerun discovers from, and so do `ia project`
214
+ * and `ia doctor`. Every such command opens with `"ia host <host>`, `"ia project <host>` or `"ia validate`, and one
215
+ * that names `--root` itself is left as it is, so the rewrite reaches each one and nothing else.
155
216
  */
156
- export const rootedNext = (next, host, root) => next.replace(new RegExp(`"ia (?:host ${host}|validate)(?! --root\\b)`, 'g'), (command) => `${command} --root ${quote(root)}`);
217
+ export const rootedNext = (next, host, root) => next.replace(new RegExp(`"ia (?:host ${host}|project ${host}|validate)(?![^"]*\\s--root\\b)`, 'g'), (command) => `${command} --root ${quote(root)}`);
157
218
  /** A next action as printed: with `--root` given, each `ia host <host>` command in it carries the root. */
158
219
  export const hostNext = (text, host, root, rooted) => rooted ? rootedNext(text, host, root) : text;
159
220
  /** 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;
221
+ export const refusedPath = (error) => /^IA-/.test(codeOf(error, '')) &&
222
+ error !== null &&
223
+ typeof error === 'object' &&
224
+ 'path' in error &&
225
+ typeof error.path === 'string'
226
+ ? error.path
227
+ : null;
228
+ /**
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.
233
+ */
234
+ export const projectionRepair = (host, path, rerun, code) => code === 'IA-CLI-FAILED'
235
+ ? `Make ${path} writable and release any file lock, then run "${rerun}".`
236
+ : (stateRepair(host, path, rerun) ??
237
+ (![SETTINGS, '.claude/settings.json'].includes(path)
238
+ ? `Move or delete ${path}, then run "${rerun}".`
239
+ : code === undefined || code === 'IA-DIST-LOCAL-MODIFICATION'
240
+ ? `Delete only the IA guard group in ${path}, then run "${rerun}".`
241
+ : `Fix ${path}, then run "${rerun}".`));
242
+ /** The populated skill folder a projection refusal names (distribution's `skillFolder`, review finding A-F2), if any. */
243
+ export const skillFolderOf = (error) => error !== null && typeof error === 'object' && 'skillFolder' in error && typeof error.skillFolder === 'string'
244
+ ? error.skillFolder
245
+ : undefined;
246
+ /** The repair for a generated skill refused at a folder that holds the user's files: those files go, or the name changes. */
247
+ export const folderRepair = (folder, rerun) => `Move the files out of ${folder}, or rename the @playbook that renders it, then run "${rerun}".`;
248
+ /** The hook refusal an error carries (`hookRefusal`), if any. */
249
+ export const hookRefusalOf = (error) => error !== null && typeof error === 'object' && 'hookRefusal' in error
250
+ ? error.hookRefusal
251
+ : undefined;
252
+ /**
253
+ * The recovery for a hook refusal, as `ia doctor` names it: a group taken away by hand is one apply never puts back on
254
+ * its own, so the removal drops the registration (after a changed or duplicated group, which the removal refuses too,
255
+ * is deleted) and `ia host` registers the workspace's hooks again; a payload a change needs is materialized by `ia host`.
256
+ */
257
+ export const hookRepair = (refusal) => 'payload' in refusal
258
+ ? `Run "ia host claude --apply" to materialize this release's payload and register the workspace's hooks against it.`
259
+ : refusal.drift === 'foreign'
260
+ ? `Delete only the unowned IA hook group for ${refusal.hook} in ${refusal.path}, preserving other groups and settings, then run "ia host claude --remove --apply" to finish removal. Protection may remain active until that group is removed.`
261
+ : refusal.drift === 'modified'
262
+ ? `Delete every IA hook group for ${refusal.hook} in ${SETTINGS}, then run "ia host claude --remove --apply" and register again with ia host.`
263
+ : `Run "ia host claude --remove --apply", which drops the registration of the hook group deleted by hand, then register again with ia host.`;
264
+ /** A journal owns recovery; raw operating-system errors never authorize deleting settings or ownership. */
265
+ export function projectionFailure(error, root, host, rerun) {
266
+ const refusal = refusalOf(error), journal = pendingJournal(root);
267
+ if (journal !== undefined)
268
+ return new Refusal(refusal.code, refusal.message, 3, { path: journal[0] }, recoverNext(root, journal[1]));
269
+ const busy = lockRefusal(error, root);
270
+ if (busy !== null)
271
+ return busy;
272
+ const located = refusedPath(error);
273
+ if (located !== null) {
274
+ const path = isAbsolute(located) ? relative(root, located).replaceAll('\\', '/') : located;
275
+ return new Refusal(refusal.code, refusal.message, 3, { path }, rootedNext(skillFolderOf(error) !== undefined
276
+ ? folderRepair(skillFolderOf(error), rerun)
277
+ : hookRefusalOf(error) === undefined
278
+ ? projectionRepair(host, path, rerun, refusal.code)
279
+ : hookRepair(hookRefusalOf(error)), host, root));
280
+ }
281
+ const system = error;
282
+ if (system && ['EACCES', 'EPERM', 'EBUSY', 'EROFS', 'EISDIR', 'ENOTDIR'].includes(system.code ?? '')) {
283
+ const path = typeof system.path === 'string' ? (system.path.endsWith('.tmp') ? dirname(system.path) : system.path) : root;
284
+ return new Refusal(refusal.code, refusal.message, 3, { path }, rootedNext(`Make ${path} writable and release any file lock, then run "${rerun}".`, host, root));
285
+ }
286
+ 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));
287
+ }
288
+ /**
289
+ * Host registration spec §4: the hosts whose projection this workspace owns, by their projection state's presence, as
290
+ * `ia host`, `ia doctor` and the install refresh decide it, a projection `ia project` wrote without a registration
291
+ * included.
292
+ */
293
+ export const projectedHosts = (root) => WORKSPACE_HOSTS.filter((host) => existsSync(resolve(root, STATE.projection(host))));
161
294
  /**
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.
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.
165
298
  */
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) {
299
+ 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. */
301
+ export function requireIdle(root, supplied) {
169
302
  try {
170
303
  assertHostRegistrationIdle(root);
171
304
  }
@@ -178,7 +311,17 @@ function requireIdle(root, supplied) {
178
311
  /** A mechanism's refusal as an element conflict: the service's code and message, located at its file. */
179
312
  function conflictOf(error, path) {
180
313
  const refusal = refusalOf(error);
181
- return { code: refusal.code, path: refusedPath(error) ?? path, reason: refusal.message };
314
+ const raw = error;
315
+ const at = refusedPath(error) ??
316
+ (typeof raw?.path === 'string' ? (raw.path.endsWith('.tmp') ? dirname(raw.path) : raw.path) : path);
317
+ const hook = hookRefusalOf(error), folder = skillFolderOf(error);
318
+ return {
319
+ code: refusal.code,
320
+ path: at,
321
+ reason: refusal.message,
322
+ ...(hook === undefined ? {} : { hook }),
323
+ ...(folder === undefined ? {} : { folder }),
324
+ };
182
325
  }
183
326
  const pin = (text) => text === null ? null : createHash('sha256').update(text).digest('hex');
184
327
  /** A registration plan's action, from the bytes it would write against the bytes it read. */
@@ -190,20 +333,20 @@ const actionOf = (plan) => plan.after.state === null
190
333
  ? 'unchanged'
191
334
  : 'update';
192
335
  /** One registration element, planned by its mechanism; `none` when a removal finds nothing owned. */
193
- function registrationElement(id, path, owned, remove, plan) {
336
+ function registrationElement(path, owned, remove, plan) {
194
337
  if (remove && !owned)
195
- return { id, action: 'none', paths: [path], capability: 'absent', conflict: null };
338
+ return { id: 'mcp', action: 'none', paths: [path], capability: 'absent', conflict: null };
196
339
  try {
197
- return { id, action: actionOf(plan()), paths: [path], capability: 'registered', conflict: null };
340
+ return { id: 'mcp', action: actionOf(plan()), paths: [path], capability: 'registered', conflict: null };
198
341
  }
199
342
  catch (error) {
200
- return { id, action: 'refused', paths: [path], capability: 'refused', conflict: conflictOf(error, path) };
343
+ return { id: 'mcp', action: 'refused', paths: [path], capability: 'refused', conflict: conflictOf(error, path) };
201
344
  }
202
345
  }
203
346
  /**
204
347
  * §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.
348
+ * host`, because it is delivered through lifecycle hooks and Codex hooks are unavailable, so both hosts carry the
349
+ * same three rows.
207
350
  */
208
351
  const contextElement = (host) => ({
209
352
  id: 'context',
@@ -212,18 +355,41 @@ const contextElement = (host) => ({
212
355
  capability: host === 'claude' ? 'not selected' : 'unsupported by host',
213
356
  conflict: null,
214
357
  });
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) {
358
+ /**
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.
364
+ */
365
+ export function projectionElement(root, host, rendered, cache = null) {
366
+ const refused = (conflict) => ({
367
+ id: 'projection',
368
+ action: 'refused',
369
+ paths: [],
370
+ capability: 'refused',
371
+ conflict,
372
+ });
373
+ let guard, hooks, unregistered;
374
+ try {
375
+ guard = planRetirement(root, host) === null ? 'none' : 'retire';
376
+ const step = planHookStep(root, host, rendered, cache);
377
+ hooks = step.plan?.hooks ?? [];
378
+ unregistered = step.unregistered;
379
+ }
380
+ catch (error) {
381
+ return refused(conflictOf(error, SETTINGS));
382
+ }
217
383
  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')
384
+ const files = planFiles(root, host, rendered).actions;
385
+ const touched = files.filter((file) => file.action !== 'foreign'), changes = guard === 'retire' || hooks.some((hook) => hook.action !== 'unchanged'), receipt = existsSync(resolve(root, STATE.receipt(host)));
386
+ const action = rendered === null
387
+ ? touched.some((file) => file.action === 'remove') || changes || receipt
222
388
  ? 'remove'
223
389
  : 'none'
224
- : touched.every((file) => file.action === 'unchanged')
390
+ : touched.every((file) => file.action === 'unchanged') && !changes && receipt
225
391
  ? 'unchanged'
226
- : touched.every((file) => file.action === 'create')
392
+ : touched.every((file) => file.action === 'create') && !changes
227
393
  ? 'create'
228
394
  : 'update';
229
395
  return {
@@ -233,16 +399,13 @@ function projectionElement(root, host, artifacts) {
233
399
  capability: action === 'none' ? 'absent' : 'registered',
234
400
  conflict: null,
235
401
  files,
402
+ guard,
403
+ ...(host === 'claude' ? { hooks } : {}),
404
+ unsupported: notTaken(rendered?.receipt.unsupported ?? [], unregistered),
236
405
  };
237
406
  }
238
407
  catch (error) {
239
- return {
240
- id: 'projection',
241
- action: 'refused',
242
- paths: [],
243
- capability: 'refused',
244
- conflict: conflictOf(error, STATE.projection(host)),
245
- };
408
+ return refused(conflictOf(error, STATE.projection(host)));
246
409
  }
247
410
  }
248
411
  /** The invocation is rebuilt from the parsed arguments, so the printed command is the one that was understood. */
@@ -289,42 +452,43 @@ export function collectHost(context) {
289
452
  located(null, homeSrcRemedy(home, plan), () => assertIaHomeUsable(home));
290
453
  const { pin: bundled } = bundledPin(host.packageRoot);
291
454
  requireIdle(root, supplied);
292
- // §4: zero error findings. A removal renders nothing, so it checks admission alone.
293
- let artifacts = [];
294
- if (remove)
295
- checkAdmitted(root);
296
- else
297
- artifacts = renderProjectionFor(root, name);
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.
461
+ const rendered = remove
462
+ ? null
463
+ : renderProjectionFor(root, name, args.flag('apply') ? sessionGate(context, 'effect') : undefined);
298
464
  // A host home reached through a symbolic link or junction is refused by the mechanism (IA-DIST-PATH-UNSAFE), because
299
465
  // the payload it verifies must be the one the registration names; the remedy is a home with no link in its path.
300
466
  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
467
  const owned = new Set();
302
468
  if (existsSync(resolve(root, STATE.mcp(name))))
303
469
  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));
470
+ const mcp = registrationElement(MCP_PATH[name], owned.has('mcp'), remove, () => remove ? planHostFor(root, name, null, HOST_REGISTRATION) : planHostFor(root, name, expected));
310
471
  return {
311
472
  root: supplied,
312
473
  host: name,
313
474
  remove,
314
475
  release: bundled.release,
315
476
  home,
316
- elements: [mcp, hooks, contextElement(name), projectionElement(root, name, artifacts)],
477
+ elements: [mcp, contextElement(name), projectionElement(root, name, rendered, remove ? null : { expected })],
317
478
  undo: `ia host ${name} --remove --apply`,
318
479
  invocation: invocationOf(context, name, remove),
319
480
  owned,
320
481
  rooted: context.args.value('root') !== undefined,
321
482
  userPlugin: row.user === 'plugin' ? { installed: readMaterializedPlugin(home) !== null, command: USER_PLUGIN_COMMAND } : null,
483
+ rendered,
322
484
  };
323
485
  }
486
+ /** What an apply that retired the steward guard (B11) says it did. */
487
+ 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
488
  /** A next action of this verb as printed: with `--root` given, each `ia host` command in it carries the root. */
325
489
  const say = (view, text) => hostNext(text, view.host, view.root, view.rooted);
326
490
  /** The next action a conflict renders, and the one its refusal carries, rooted when `--root` was given. */
327
- const nextFor = (view, id, conflict) => say(view, conflictNext(view, id, conflict));
491
+ const nextFor = (view, id, conflict) => safeRootAdvice(say(view, conflictNext(view, id, conflict)), [view.root]);
328
492
  /** The unrooted next action for a conflict. §5.3 fixes the unowned MCP entry's wording. */
329
493
  function conflictNext(view, id, conflict) {
330
494
  const rerun = `ia host ${view.host}${view.remove ? ' --remove' : ''} --apply`;
@@ -332,8 +496,6 @@ function conflictNext(view, id, conflict) {
332
496
  const unreadable = stateRepair(view.host, conflict.path, rerun);
333
497
  if (unreadable !== null)
334
498
  return unreadable;
335
- if (conflict.code === 'IA-DIST-LOCAL-MODIFICATION' && id === 'hooks' && view.owned.has('hooks'))
336
- return modifiedRepair(view.host, ['hooks']);
337
499
  if (conflict.code === 'IA-DIST-LOCAL-MODIFICATION' && id === 'mcp') {
338
500
  // Owned: removal tolerates a deleted entry, so deleting it and re-registering converges. Unowned: §5.3's wording,
339
501
  // made exact for Codex, where the collision can be any ia-workspace table or a file that no longer parses.
@@ -343,10 +505,12 @@ function conflictNext(view, id, conflict) {
343
505
  ? '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
506
  : `Remove that entry, then run "ia host ${view.host} --apply".`;
345
507
  }
346
- if (conflict.code === 'IA-DIST-HOST-UNSUPPORTED' && id === 'hooks')
347
- return `Remove disableAllHooks from the Claude settings, then run "${rerun}".`;
348
508
  if (id === 'projection')
349
- return projectionRepair(view.host, conflict.path, rerun);
509
+ return conflict.folder !== undefined
510
+ ? folderRepair(conflict.folder, rerun)
511
+ : conflict.hook === undefined
512
+ ? projectionRepair(view.host, conflict.path, rerun, conflict.code)
513
+ : hookRepair(conflict.hook);
350
514
  return `Fix ${conflict.path}, then run "${rerun}".`;
351
515
  }
352
516
  const refusalFor = (view, id, conflict) => new Refusal(conflict.code, conflict.reason, 3, { path: conflict.path }, nextFor(view, id, conflict));
@@ -359,6 +523,17 @@ function replan(view, id, path, run) {
359
523
  throw refusalFor(view, id, conflictOf(error, path));
360
524
  }
361
525
  }
526
+ /**
527
+ * Apply's re-plan of the projection, shared by `ia host --apply` and `ia project --apply`: the projection element
528
+ * planned against the rendering the apply writes, so a conflict either of its planners finds (the guard retirement or
529
+ * the file plan) is raised, worded by the verb's `refuse`, before anything is written. `applyHostProjection` plans
530
+ * both again before its first write.
531
+ */
532
+ export function replanProjection(root, host, rendered, refuse, cache = null) {
533
+ const { conflict } = projectionElement(root, host, rendered, cache);
534
+ if (conflict !== null)
535
+ throw refuse(conflict);
536
+ }
362
537
  /**
363
538
  * §3.3 steps 3-4. A payload directory that fails verification is named by the mechanism and the remedy is to delete
364
539
  * it; nothing overwrites it. Any other failure is the bundled payload's own, which only a reinstall repairs.
@@ -379,12 +554,14 @@ function materialize(view, packageRoot) {
379
554
  }
380
555
  }
381
556
  /**
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.
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
559
+ * included — so a refusal any planner can find is raised before the workspace changes; each apply then re-plans under
560
+ * 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
563
+ * names the rerun that finishes the set, or the recovery a pending journal needs. `checkpoint` runs after each element
564
+ * completes, which is where an interruption test cuts.
388
565
  */
389
566
  export function applyHostSet(view, packageRoot, signal, checkpoint = () => { }) {
390
567
  const refused = view.elements.find((element) => element.conflict !== null);
@@ -397,60 +574,104 @@ export function applyHostSet(view, packageRoot, signal, checkpoint = () => { })
397
574
  id,
398
575
  status: view.elements.find((element) => element.id === id).capability,
399
576
  });
577
+ /** A failure as the refusal it raises: a pending journal's recovery, the held lock's, or once anything was written, the rerun. */
578
+ const failure = (error) => {
579
+ const refusal = refusalOf(error), journal = pendingJournal(root);
580
+ if (journal !== undefined)
581
+ return new Refusal(refusal.code, refusal.message, 3, { path: journal[0] }, say(view, recoverNext(view.root, journal[1])));
582
+ const busy = lockRefusal(error, view.root);
583
+ if (busy !== null)
584
+ return busy;
585
+ if (done.length > 0)
586
+ return new Refusal(refusal.code, refusal.message, 3, refusal.where, say(view, `Run "${rerun}" to finish.`));
587
+ return error;
588
+ };
400
589
  const step = (id, run) => {
401
590
  if (signal?.aborted)
402
591
  throw new Interrupted(say(view, `Run "${rerun}" to finish.`));
403
- let status;
592
+ let applied;
404
593
  try {
405
- status = run();
594
+ applied = run();
406
595
  }
407
596
  catch (error) {
408
- const refusal = refusalOf(error), journal = pendingJournal(root);
409
- if (journal !== undefined)
410
- throw new Refusal(refusal.code, refusal.message, 3, { path: journal[0] }, say(view, recoverNext(view.root, journal[1])));
411
- const busy = lockRefusal(error, view.root);
412
- if (busy !== null)
413
- throw busy;
414
- if (done.length > 0)
415
- throw new Refusal(refusal.code, refusal.message, 3, refusal.where, say(view, `Run "${rerun}" to finish.`));
416
- throw error;
597
+ if (id === 'projection')
598
+ throw projectionFailure(error, root, host, rerun);
599
+ throw failure(error);
417
600
  }
418
- done.push({ id, status });
601
+ done.push({ id, ...applied });
419
602
  checkpoint(id);
420
603
  };
604
+ /**
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.
608
+ */
609
+ const joinFailure = (error) => {
610
+ if (refusedPath(error) !== JOINS || pendingJournal(root) !== undefined)
611
+ return failure(error);
612
+ const refusal = refusalOf(error);
613
+ return new Refusal(refusal.code, refusal.message, 3, { path: JOINS }, say(view, `Delete ${JOINS}, then run "${rerun}".`));
614
+ };
615
+ /**
616
+ * The join recorded from the committed registration (`joinHost`), or dropped after a removal (`leaveHost`), once every
617
+ * element is applied, so an interrupted apply leaves no join, or the previous one, which `ia doctor` reports as
618
+ * unavailable or drifted rather than as current. A failure here names the rerun that finishes the set.
619
+ */
620
+ const receipt = (run) => {
621
+ try {
622
+ run();
623
+ }
624
+ catch (error) {
625
+ throw joinFailure(error);
626
+ }
627
+ };
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).
630
+ try {
631
+ readJoins(root);
632
+ }
633
+ catch (error) {
634
+ throw joinFailure(error);
635
+ }
636
+ const project = (rendered, cache) => () => {
637
+ const { status, guard } = applyHostProjection(root, host, rendered, undefined, undefined, cache);
638
+ return { status, guard };
639
+ };
421
640
  if (!view.remove) {
422
641
  const cache = materialize(view, packageRoot);
423
642
  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);
643
+ // Review C3-N2: the rendering the plan's gated session made, re-planned against the files as they are now.
644
+ const { rendered } = view;
645
+ // Only a removal's view carries no rendering (collectHost); an apply always has the one its gated plan made.
646
+ if (rendered === null)
647
+ 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).
649
+ replanProjection(root, host, rendered, (conflict) => refusalFor(view, 'projection', conflict), {
650
+ verified: cache,
651
+ });
652
+ step('mcp', () => ({ status: applyHost(mcp).status }));
432
653
  done.push(skipped('context'));
433
- step('projection', () => applyProjection(projection).status);
654
+ step('projection', project(rendered, { verified: cache }));
655
+ receipt(() => joinHost(root, host, rendered.receipt.revision));
434
656
  return { status: 'host-registered', elements: done, observed: false };
435
657
  }
436
658
  // A removal plans only what the view found owned; `none` means there is nothing of that element to remove.
437
659
  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;
660
+ replanProjection(root, host, null, (conflict) => refusalFor(view, 'projection', conflict));
442
661
  const mcp = absent('mcp')
443
662
  ? null
444
663
  : replan(view, 'mcp', MCP_PATH[host], () => planHost(root, host, null, HOST_REGISTRATION));
445
- step('projection', () => (applyProjection(projection).removed > 0 ? 'projection-removed' : 'absent'));
664
+ step('projection', project(null, null));
446
665
  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));
666
+ step('mcp', () => ({ status: mcp === null ? 'absent' : applyHost(mcp).status }));
667
+ receipt(() => leaveHost(root, host));
452
668
  return { status: 'host-removed', elements: done, observed: false };
453
669
  }
670
+ /**
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`.
673
+ */
674
+ export const printedConflict = (conflict) => conflict === null ? null : { code: conflict.code, path: conflict.path, reason: conflict.reason };
454
675
  /** §4 `--json`: the plan always, and `applied` only after an apply. */
455
676
  const hostEnvelope = (view, applied) => ({
456
677
  version: 1,
@@ -461,7 +682,7 @@ const hostEnvelope = (view, applied) => ({
461
682
  plan: {
462
683
  release: view.release,
463
684
  home: view.home,
464
- elements: view.elements,
685
+ elements: view.elements.map((element) => ({ ...element, conflict: printedConflict(element.conflict) })),
465
686
  undo: view.undo,
466
687
  ...(view.userPlugin === null ? {} : { userPlugin: view.userPlugin }),
467
688
  },
@@ -472,7 +693,7 @@ const FILE_SYMBOL = {
472
693
  update: 'updated',
473
694
  unchanged: 'info',
474
695
  remove: 'removed',
475
- unowned: 'warning',
696
+ foreign: 'info',
476
697
  };
477
698
  const elementSymbol = (element) => element.conflict !== null
478
699
  ? 'error'
@@ -482,8 +703,10 @@ const elementSymbol = (element) => element.conflict !== null
482
703
  function elementFields(view) {
483
704
  return view.elements.map((element) => {
484
705
  const facts = [element.action, element.capability, ...(element.id === 'projection' ? [] : element.paths)];
485
- if (element.id === 'hooks' && element.capability === 'unsupported by host')
706
+ if (element.id === 'context' && element.capability === 'unsupported by host')
486
707
  facts.push(CODEX_HOOKS.replace(/\.$/, ''));
708
+ if (element.guard === 'retire')
709
+ facts.push(GUARD_RETIRE);
487
710
  if (element.conflict !== null)
488
711
  facts.push(`${element.conflict.code} ${element.conflict.reason}`);
489
712
  return {
@@ -494,20 +717,42 @@ function elementFields(view) {
494
717
  };
495
718
  });
496
719
  }
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([
720
+ /** A projection plan's B11 step as its plan says it, in `ia host` and `ia project` alike. */
721
+ export const GUARD_RETIRE = `first retires the steward guard registered in ${SETTINGS}`;
722
+ /**
723
+ * Each projected file with its action, at `column`; a foreign steward file says why it is left alone. `ia host` nests
724
+ * the rows under its projection element and `ia project` lists them as its file plan, so both word them alike.
725
+ */
726
+ export const projectionFileRows = (files, column, caps) => files.flatMap((file) => entry([
499
727
  [
500
728
  atom(file.path, 'cyan', 0),
501
- ...words(file.action === 'unowned'
502
- ? "unowned; marked but not listed in this workspace's projection state, left untouched"
729
+ ...words(file.action === 'foreign'
730
+ ? "foreign; not this workspace's projection to write or delete, left in place"
503
731
  : file.action, null, 2),
504
732
  ],
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));
733
+ ], { column, symbol: FILE_SYMBOL[file.action] }, caps));
734
+ const HOOK_SYMBOL = {
735
+ create: 'added',
736
+ update: 'updated',
737
+ unchanged: 'info',
738
+ remove: 'removed',
739
+ };
740
+ /** Each authored `@hook`'s group with its action (plan amendment C9), worded alike by `ia host` and `ia project`. */
741
+ 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
+ /** Each authored record the host does not take, with the reason, worded alike by `ia host` and `ia project`. */
743
+ 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
+ /**
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.
747
+ */
748
+ const fileBlock = (view, caps) => {
749
+ const projection = view.elements.find((element) => element.id === 'projection'), column = indentOf(1) + blockSymbolWidth(view.elements.map(elementSymbol), caps.ascii) + 2;
750
+ return [
751
+ ...projectionFileRows(projection?.files ?? [], column, caps),
752
+ ...projectionHookRows(projection?.hooks ?? [], column, caps),
753
+ ...unsupportedRows(projection?.unsupported ?? [], column, caps),
754
+ ];
755
+ };
511
756
  const headerBlock = (view, caps) => [
512
757
  ...headerLine('Plan', `host ${view.host}${view.remove ? ' --remove' : ''}`, [{ text: `release ${truncateDigest(view.release, caps.ascii)}`, column: 35 }], caps),
513
758
  ...headerLine('Root', view.root, [], caps),
@@ -519,9 +764,9 @@ const elementsBlock = (view, caps) => [
519
764
  ...fileBlock(view, caps),
520
765
  ];
521
766
  /**
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.
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
769
+ * cannot word them differently.
525
770
  */
526
771
  export const hostNotes = (host, caps, remove = false) => [
527
772
  entry([words(MACHINE_LOCAL[host])], { depth: 1, symbol: 'warning' }, caps),
@@ -542,7 +787,7 @@ const notesBlocks = (view, caps) => [
542
787
  ? [entry([words(USER_PLUGIN_MISSING)], { depth: 1, symbol: 'info' }, caps)]
543
788
  : []),
544
789
  ];
545
- export function renderHostPlan(view, applied, caps) {
790
+ export function renderHostPlan(view, applied, caps, supplied) {
546
791
  const conflicted = view.elements.some((element) => element.conflict !== null);
547
792
  return document([
548
793
  headerBlock(view, caps),
@@ -552,15 +797,18 @@ export function renderHostPlan(view, applied, caps) {
552
797
  words(applied.status === 'host-registered'
553
798
  ? 'Registered: written; not observed answering.'
554
799
  : 'Removed the owned host set.'),
800
+ ...(applied.elements.some((element) => element.guard === 'retired') ? [words(GUARD_RETIRED)] : []),
555
801
  ], { depth: 1, symbol: 'success' }, caps),
556
802
  elementsBlock(view, caps),
557
803
  ...notesBlocks(view, caps),
558
804
  entry([
559
805
  ...(applied === null && !conflicted
560
- ? commandFacts('Apply with "', `${view.invocation} --apply --yes`, '".', 3, caps)
806
+ ? commandFacts('Apply with "', `${view.invocation} --apply --yes`, '".', 3, caps, [view.root, supplied])
561
807
  : []),
562
808
  // `plan.undo` stays unrooted (§4 `--json`); the printed command carries --root when it was given.
563
- ...(view.remove ? [] : commandFacts('Undo with "', say(view, `"${view.undo}"`).slice(1, -1), '".', 3, caps)),
809
+ ...(view.remove
810
+ ? []
811
+ : commandFacts('Undo with "', say(view, `"${view.undo}"`).slice(1, -1), '".', 3, caps, [view.root])),
564
812
  ...(applied !== null && !view.remove ? [words('Run "ia doctor" for the observed host state.')] : []),
565
813
  ], { depth: 0, symbol: 'step' }, caps),
566
814
  ], { leadingBlank: true });
@@ -594,7 +842,7 @@ export async function runHost(context) {
594
842
  }
595
843
  const rendered = (applied) => json
596
844
  ? { exitCode: 0, stdout: JSON.stringify(hostEnvelope(view, applied)) + '\n', stderr: '' }
597
- : { exitCode: 0, stdout: renderHostPlan(view, applied, caps), stderr: '' };
845
+ : { exitCode: 0, stdout: renderHostPlan(view, applied, caps, args.value('root')), stderr: '' };
598
846
  // §4: a plan with a conflict is a successful report; only --apply refuses it.
599
847
  if (!args.flag('apply'))
600
848
  return rendered(null);
@@ -605,7 +853,10 @@ export async function runHost(context) {
605
853
  exitCode: 0,
606
854
  stdout: document([
607
855
  entry([words('Nothing was applied.')], { depth: 0, symbol: 'info' }, caps),
608
- entry(commandFacts('Apply with "', `${view.invocation} --apply --yes`, '".', 3, caps), { depth: 0, symbol: 'step' }, caps),
856
+ entry(commandFacts('Apply with "', `${view.invocation} --apply --yes`, '".', 3, caps, [
857
+ view.root,
858
+ args.value('root'),
859
+ ]), { depth: 0, symbol: 'step' }, caps),
609
860
  ], { leadingBlank: true }),
610
861
  stderr: '',
611
862
  };