@inventarch/cli 1.1.1 → 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 (116) hide show
  1. package/LANGUAGE.md +2 -2
  2. package/README.md +17 -4
  3. package/SPEC.md +51 -7
  4. package/assets/base/0305ca741b1dfec97ff35fbeb36d4a66a0c9c0614b730fe14fcdac0f1565e28a.ia.tgz +0 -0
  5. package/assets/base.json +3 -3
  6. package/assets/host/3d2c8530db8d14755410b17be8228a230d88de96f9dc78f953979d3ca7c6ea62.tgz +0 -0
  7. package/assets/host.json +4 -4
  8. package/assets/vocabulary.json +436 -4
  9. package/dist/bundled-base.d.ts +18 -0
  10. package/dist/bundled-base.d.ts.map +1 -0
  11. package/dist/bundled-base.js +44 -0
  12. package/dist/bundled-base.js.map +1 -0
  13. package/dist/capture.d.ts +108 -0
  14. package/dist/capture.d.ts.map +1 -0
  15. package/dist/capture.js +346 -0
  16. package/dist/capture.js.map +1 -0
  17. package/dist/claude-cli.js +1 -1
  18. package/dist/claude-cli.js.map +1 -1
  19. package/dist/commands.d.ts +23 -1
  20. package/dist/commands.d.ts.map +1 -1
  21. package/dist/commands.js +201 -10
  22. package/dist/commands.js.map +1 -1
  23. package/dist/compile.d.ts +5 -0
  24. package/dist/compile.d.ts.map +1 -1
  25. package/dist/compile.js +40 -51
  26. package/dist/compile.js.map +1 -1
  27. package/dist/consumer.d.ts +48 -7
  28. package/dist/consumer.d.ts.map +1 -1
  29. package/dist/consumer.js +142 -29
  30. package/dist/consumer.js.map +1 -1
  31. package/dist/decline.d.ts.map +1 -1
  32. package/dist/decline.js +15 -7
  33. package/dist/decline.js.map +1 -1
  34. package/dist/distribute.d.ts +68 -16
  35. package/dist/distribute.d.ts.map +1 -1
  36. package/dist/distribute.js +243 -110
  37. package/dist/distribute.js.map +1 -1
  38. package/dist/doctor.d.ts.map +1 -1
  39. package/dist/doctor.js +113 -60
  40. package/dist/doctor.js.map +1 -1
  41. package/dist/format.d.ts +2 -2
  42. package/dist/format.d.ts.map +1 -1
  43. package/dist/format.js +19 -11
  44. package/dist/format.js.map +1 -1
  45. package/dist/home-remedy.d.ts +8 -4
  46. package/dist/home-remedy.d.ts.map +1 -1
  47. package/dist/home-remedy.js +8 -4
  48. package/dist/home-remedy.js.map +1 -1
  49. package/dist/host-projection.d.ts +73 -6
  50. package/dist/host-projection.d.ts.map +1 -1
  51. package/dist/host-projection.js +296 -38
  52. package/dist/host-projection.js.map +1 -1
  53. package/dist/host.d.ts +106 -30
  54. package/dist/host.d.ts.map +1 -1
  55. package/dist/host.js +270 -139
  56. package/dist/host.js.map +1 -1
  57. package/dist/init.d.ts +285 -37
  58. package/dist/init.d.ts.map +1 -1
  59. package/dist/init.js +1270 -205
  60. package/dist/init.js.map +1 -1
  61. package/dist/inspect.d.ts +26 -2
  62. package/dist/inspect.d.ts.map +1 -1
  63. package/dist/inspect.js +117 -52
  64. package/dist/inspect.js.map +1 -1
  65. package/dist/main.d.ts.map +1 -1
  66. package/dist/main.js +3 -1
  67. package/dist/main.js.map +1 -1
  68. package/dist/migration-journal.d.ts +35 -0
  69. package/dist/migration-journal.d.ts.map +1 -0
  70. package/dist/migration-journal.js +205 -0
  71. package/dist/migration-journal.js.map +1 -0
  72. package/dist/next.d.ts +21 -0
  73. package/dist/next.d.ts.map +1 -0
  74. package/dist/next.js +210 -0
  75. package/dist/next.js.map +1 -0
  76. package/dist/operation-help.d.ts.map +1 -1
  77. package/dist/operation-help.js +14 -3
  78. package/dist/operation-help.js.map +1 -1
  79. package/dist/pack.d.ts +3 -1
  80. package/dist/pack.d.ts.map +1 -1
  81. package/dist/pack.js +56 -11
  82. package/dist/pack.js.map +1 -1
  83. package/dist/position.d.ts +22 -0
  84. package/dist/position.d.ts.map +1 -0
  85. package/dist/position.js +242 -0
  86. package/dist/position.js.map +1 -0
  87. package/dist/project.d.ts +42 -0
  88. package/dist/project.d.ts.map +1 -0
  89. package/dist/project.js +232 -0
  90. package/dist/project.js.map +1 -0
  91. package/dist/read.d.ts +31 -0
  92. package/dist/read.d.ts.map +1 -0
  93. package/dist/read.js +152 -0
  94. package/dist/read.js.map +1 -0
  95. package/dist/render.d.ts +19 -0
  96. package/dist/render.d.ts.map +1 -1
  97. package/dist/render.js +44 -1
  98. package/dist/render.js.map +1 -1
  99. package/dist/session.d.ts +12 -1
  100. package/dist/session.d.ts.map +1 -1
  101. package/dist/session.js +68 -6
  102. package/dist/session.js.map +1 -1
  103. package/dist/user-host.d.ts.map +1 -1
  104. package/dist/user-host.js +7 -5
  105. package/dist/user-host.js.map +1 -1
  106. package/dist/validate.d.ts +1 -2
  107. package/dist/validate.d.ts.map +1 -1
  108. package/dist/validate.js +6 -27
  109. package/dist/validate.js.map +1 -1
  110. package/dist/vocabulary.d.ts +4 -0
  111. package/dist/vocabulary.d.ts.map +1 -1
  112. package/dist/vocabulary.js +12 -7
  113. package/dist/vocabulary.js.map +1 -1
  114. package/package.json +6 -6
  115. package/assets/base/78bff5eb3188b628c06d2f1cf1477fb1bfcea874ec3863ae112b4972b8e81517.ia.tgz +0 -0
  116. package/assets/host/b97e367bbf15db09f552d6bd6dd3701210efe77931d34b57ccb85240957aba61.tgz +0 -0
package/dist/host.js CHANGED
@@ -1,59 +1,75 @@
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
- import { existsSync, realpathSync } from 'node:fs';
18
- import { resolve } from 'node:path';
19
- import { lifecycleProfile } from '@inventarch/agent-composition-system/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';
24
+ import { existsSync, realpathSync, statSync } from 'node:fs';
25
+ import { dirname, isAbsolute, relative, resolve } from 'node:path';
26
+ import { lifecycleProfile } from '@inventarch/workspace-runtime/lifecycle-profile';
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';
35
- const DAMAGED = 'The ia installation is damaged; reinstall @inventarch/cli so assets/host travels with it.';
42
+ /** The installation, not the workspace, is at fault; `ia doctor` names the channel a reinstall goes through. */
43
+ 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.';
36
44
  /** §7.1: the user-level command a workspace plan names when the plugin is missing. It takes no --root. */
37
45
  export const USER_PLUGIN_COMMAND = 'ia host claude --user --apply';
38
46
  export const USER_PLUGIN_MISSING = `The user-level plugin is not installed; run "${USER_PLUGIN_COMMAND}" to add it.`;
39
47
  /** §5.3's sentence, verbatim, per host. Every element — the projection included — is machine-local. */
40
48
  export const MACHINE_LOCAL = {
41
- 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.',
42
50
  codex: 'These files are machine-local: .codex/config.toml, AGENTS.md, .agents/skills/ia-authoring/ and .ia/distributions/. Do not commit them.',
43
51
  };
44
52
  /** §5.4: the MCP element's one fixed addition, from §2.3's host facts. */
45
53
  export const MCP_APPROVAL = 'Claude Code asks for approval before starting a project MCP server.';
46
- /** Operator decision 2026-09-23 ("narrow + disclose"): what the registered steward guard refuses, said where it is registered. */
47
- 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.';
48
59
  /** §5.1's files, exported once so `ia doctor` names the same ones. */
49
60
  export const MCP_PATH = { claude: '.mcp.json', codex: '.codex/config.toml' };
50
61
  export const SETTINGS = '.claude/settings.local.json';
51
62
  export const HOSTS_AREA = '.ia/distributions/hosts';
52
- /** §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
+ */
53
68
  export const STATE = {
54
69
  mcp: (host) => `${HOSTS_AREA}/${host}-${HOST_REGISTRATION}.json`,
55
70
  hooks: `${HOSTS_AREA}/claude-guard-${HOST_REGISTRATION}.json`,
56
71
  projection: (host) => `${HOSTS_AREA}/${host}-projection.json`,
72
+ receipt: (host) => `${HOSTS_AREA}/${host}-receipt.json`,
57
73
  };
58
74
  /**
59
75
  * What one host's MCP element owns, named so a user can find and delete exactly it. Codex's is a marked block
@@ -76,7 +92,7 @@ export function stateRepair(host, path, rerun) {
76
92
  return `Delete ${path} and ${OWNED_MCP[host]}, then run "${rerun}".`;
77
93
  if (host === 'claude' && path === STATE.hooks)
78
94
  return `Delete ${path} and ${OWNED_GUARD}, then run "${rerun}".`;
79
- if (path === STATE.projection(host))
95
+ if (path === STATE.projection(host) || path === STATE.receipt(host))
80
96
  return `Delete ${path}, then run "${rerun}".`;
81
97
  return null;
82
98
  }
@@ -86,7 +102,7 @@ export function stateRepair(host, path, rerun) {
86
102
  */
87
103
  export function modifiedRepair(host, elements) {
88
104
  const owned = elements.map((element) => (element === 'mcp' ? OWNED_MCP[host] : OWNED_GUARD)).join(' and ');
89
- return `Delete ${owned}, then run "ia host ${host} --remove --apply" and "ia host ${host} --apply".`;
105
+ return `Delete ${owned}, then run "ia host ${host} --remove --apply" and register again.`;
90
106
  }
91
107
  /** §8: each pending journal names its own recovery on the distribution binary. `ia doctor` reports the same ones. */
92
108
  export const JOURNALS = [
@@ -96,14 +112,47 @@ export const JOURNALS = [
96
112
  ];
97
113
  /** §8: the lock every host sub-transaction holds while it writes (`acquireHostRegistrationLock`). */
98
114
  export const HOST_LOCK = `${HOSTS_AREA}/lock.json`;
99
- /** A recovery on the distribution binary, rooted and quoted as every printed root is. */
100
- export const recoverCommand = (command, root) => `ia-distribution ${command} --root ${quote(root)}`;
115
+ /**
116
+ * The close of a remedy whose follow-up is the refused command itself, run again as typed, so the recovery before it
117
+ * is the one command named (design row 27). `ia init --host` cannot simply be run again once it has initialized, so it
118
+ * names `ia host` instead of such a remedy.
119
+ */
120
+ export const THEN_RERUN = ', then rerun.';
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
+ }
101
150
  /**
102
151
  * §8 "or refuses naming a recovery": a held host lock is another run or a killed one, and nothing here can tell
103
152
  * which, so the next action names the recovery that decides it — `recoverHost` takes the lock in recovery mode,
104
153
  * which clears a dead holder's lock and refuses a live one. It names no `ia host` command, so `--root` needs no rewrite.
105
154
  */
106
- export const lockNext = (root) => `Another ia host run holds the host lock, or a killed run left it: run "${recoverCommand('recover-host', root)}" (it clears a dead holder's lock and refuses a live one), then rerun.`;
155
+ export const lockNext = (root) => `Another ia host run holds the host lock, or a killed run left it: run "${recoverCommand('recover-host', root)}" (it clears a dead holder's lock and refuses a live one)${THEN_RERUN}`;
107
156
  /**
108
157
  * The refusal for a held host lock, located at the lock and naming its recovery, or null for any other error. Every
109
158
  * mechanism an `ia host` apply or an install's projection refresh runs raises IA-DIST-INSTALL-BUSY only from that
@@ -131,46 +180,100 @@ export function pinnedRelease(packageRoot) {
131
180
  return { release: null, code: codeOf(error, 'IA-DIST-ARTIFACT-UNAVAILABLE') };
132
181
  }
133
182
  }
134
- /** §4: the target must be initialized and admit; anything else names ia init or ia validate. */
135
- 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) {
136
188
  if (!existsSync(resolve(root, '.ia/release.json')))
137
- throw new Refusal('IA-CLI-CONFLICT', 'The target is not an initialized workspace: .ia/release.json is absent', 3, { path: root }, 'Run "ia init" 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.`);
138
190
  }
139
191
  /** The journal a failed transaction left behind, if any, with the command that recovers it. */
140
- const pendingJournal = (root) => JOURNALS.find(([path]) => existsSync(resolve(root, path)));
141
- const recoverNext = (root, command, host) => `Run "${recoverCommand(command, root)}", then rerun "ia host ${host}".`;
192
+ export const pendingJournal = (root) => JOURNALS.find(([path]) => existsSync(resolve(root, path)));
193
+ /** Design row 27: the recovery is the one command named; the refused command is simply run again after it. */
194
+ export const recoverNext = (root, command) => `Run "${recoverCommand(command, root)}"${THEN_RERUN}`;
142
195
  /**
143
- * A next action of this verb made runnable from any cwd: every quoted `ia host <host>` command it names gains
144
- * `--root <root>`. `ia init --host` uses it, because its `<directory>` may not be the cwd a rerun discovers from.
145
- * Every command this file prints opens with `"ia host <host>` and none names `--root` itself, so the rewrite reaches
146
- * each command 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.
147
201
  */
148
- export const rootedNext = (next, host, root) => next.replace(new RegExp(`"ia host ${host}(?! --root\\b)`, 'g'), () => `"ia host ${host} --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)}`);
149
203
  /** A next action as printed: with `--root` given, each `ia host <host>` command in it carries the root. */
150
204
  export const hostNext = (text, host, root, rooted) => rooted ? rootedNext(text, host, root) : text;
151
205
  /** The file a mechanism located its refusal at (`locate` in @inventarch/distribution's files.ts), or null. */
152
- 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;
213
+ /**
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.
218
+ */
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))));
153
253
  /**
154
- * §6.3: the repair for a projection refusal located at `path`. The ownership state has its own repair; any other file
155
- * is never replaced or adopted, so it is moved or deleted first. `ia host`, `ia doctor` and the install refresh all
156
- * name it this way.
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.
157
257
  */
158
- export const projectionRepair = (host, path, rerun) => stateRepair(host, path, rerun) ?? `Move or delete ${path}, then run "${rerun}".`;
159
- /** §8: a pending journal refuses the whole verb and names the recovery that clears it. */
160
- function requireIdle(root, host, supplied) {
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) {
161
261
  try {
162
262
  assertHostRegistrationIdle(root);
163
263
  }
164
264
  catch (error) {
165
265
  const refusal = refusalOf(error);
166
266
  const [journal, command] = pendingJournal(root) ?? JOURNALS[0];
167
- throw new Refusal(refusal.code, refusal.message, 3, { path: journal }, recoverNext(supplied, command, host));
267
+ throw new Refusal(refusal.code, refusal.message, 3, { path: journal }, recoverNext(supplied, command));
168
268
  }
169
269
  }
170
270
  /** A mechanism's refusal as an element conflict: the service's code and message, located at its file. */
171
271
  function conflictOf(error, path) {
172
272
  const refusal = refusalOf(error);
173
- 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 };
174
277
  }
175
278
  const pin = (text) => text === null ? null : createHash('sha256').update(text).digest('hex');
176
279
  /** A registration plan's action, from the bytes it would write against the bytes it read. */
@@ -182,20 +285,20 @@ const actionOf = (plan) => plan.after.state === null
182
285
  ? 'unchanged'
183
286
  : 'update';
184
287
  /** One registration element, planned by its mechanism; `none` when a removal finds nothing owned. */
185
- function registrationElement(id, path, owned, remove, plan) {
288
+ function registrationElement(path, owned, remove, plan) {
186
289
  if (remove && !owned)
187
- return { id, action: 'none', paths: [path], capability: 'absent', conflict: null };
290
+ return { id: 'mcp', action: 'none', paths: [path], capability: 'absent', conflict: null };
188
291
  try {
189
- return { id, action: actionOf(plan()), paths: [path], capability: 'registered', conflict: null };
292
+ return { id: 'mcp', action: actionOf(plan()), paths: [path], capability: 'registered', conflict: null };
190
293
  }
191
294
  catch (error) {
192
- 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) };
193
296
  }
194
297
  }
195
298
  /**
196
299
  * §5.2: the context element. Claude reports it `not selected` until the gate lifts; Codex reports it `unsupported by
197
- * host`, because it is delivered through lifecycle hooks and Codex hooks are unavailable — the same reason the
198
- * 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.
199
302
  */
200
303
  const contextElement = (host) => ({
201
304
  id: 'context',
@@ -204,18 +307,38 @@ const contextElement = (host) => ({
204
307
  capability: host === 'claude' ? 'not selected' : 'unsupported by host',
205
308
  conflict: null,
206
309
  });
207
- /** §5.1 `projection`, planned by the real planner: it reads only the workspace, so the plan is exactly apply's. */
208
- 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;
326
+ try {
327
+ guard = planRetirement(root, host) === null ? 'none' : 'retire';
328
+ }
329
+ catch (error) {
330
+ return refused(conflictOf(error, SETTINGS));
331
+ }
209
332
  try {
210
- const files = planProjection({ root, host, artifacts, marker: WORKSPACE_PROJECTION_MARKER }).actions;
211
- const touched = files.filter((file) => file.action !== 'unowned');
212
- const action = artifacts.length === 0
213
- ? touched.some((file) => file.action === 'remove')
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
214
337
  ? 'remove'
215
338
  : 'none'
216
- : touched.every((file) => file.action === 'unchanged')
339
+ : touched.every((file) => file.action === 'unchanged') && !changes && receipt
217
340
  ? 'unchanged'
218
- : touched.every((file) => file.action === 'create')
341
+ : touched.every((file) => file.action === 'create') && !changes
219
342
  ? 'create'
220
343
  : 'update';
221
344
  return {
@@ -225,16 +348,11 @@ function projectionElement(root, host, artifacts) {
225
348
  capability: action === 'none' ? 'absent' : 'registered',
226
349
  conflict: null,
227
350
  files,
351
+ guard,
228
352
  };
229
353
  }
230
354
  catch (error) {
231
- return {
232
- id: 'projection',
233
- action: 'refused',
234
- paths: [],
235
- capability: 'refused',
236
- conflict: conflictOf(error, STATE.projection(host)),
237
- };
355
+ return refused(conflictOf(error, STATE.projection(host)));
238
356
  }
239
357
  }
240
358
  /** The invocation is rebuilt from the parsed arguments, so the printed command is the one that was understood. */
@@ -255,8 +373,11 @@ export function collectHost(context) {
255
373
  if (hostRow(given) === undefined)
256
374
  throw new UsageError(`ia host takes claude, codex or cursor; got ${given}`);
257
375
  const row = workspaceRow(given);
258
- if (row === undefined)
259
- throw new Refusal('IA-DIST-HOST-UNSUPPORTED', `${hostRow(given).label} support is planned; nothing was written`, 3, null, 'Run "ia host claude" or "ia host codex".');
376
+ if (row === undefined) {
377
+ // Raised before the root is resolved, so the command names the root as it was typed.
378
+ const typed = args.value('root');
379
+ throw new Refusal('IA-DIST-HOST-UNSUPPORTED', `${hostRow(given).label} support is planned; nothing was written`, 3, null, `Run "ia host claude${typed === undefined ? '' : ` --root ${quote(typed)}`}" to plan a supported host; Codex is supported too.`);
380
+ }
260
381
  const name = row.id;
261
382
  const remove = args.flag('remove'), selected = args.value('context');
262
383
  if (selected !== undefined && name === 'codex')
@@ -266,41 +387,38 @@ export function collectHost(context) {
266
387
  // Spec §5.2's gate: until the binding's coordinate, bootstrap and policy are derived and one context run from a v2
267
388
  // payload is observed generating, the context element refuses. The spec fixes this code for the gate.
268
389
  if (selected !== undefined)
269
- throw new Refusal('IA-DIST-HOST-UNSUPPORTED', 'The lifecycle context element is not qualified in this release', 3, { path: supplied }, `Run "ia host ${name}" without --context.`);
390
+ throw new Refusal('IA-DIST-HOST-UNSUPPORTED', 'The lifecycle context element is not qualified in this release', 3, { path: supplied }, `Run "ia host ${name}" to plan the registration without the context element.`);
270
391
  // The mechanisms record the real path (files.ts `workspace()`), so the plan works on the same one.
271
392
  const root = realpathSync(supplied);
272
- const home = hostHome(host.env);
393
+ // Every IA home remedy ends by planning this invocation again; `runHost` adds `--root` as it does to every next action.
394
+ const plan = `ia host ${name}${remove ? ' --remove' : ''}`;
395
+ const home = hostHome(host.env, plan);
273
396
  // §3.3: neither may contain the other; the service raises IA-DIST-PATH-UNSAFE.
274
- located(supplied, 'Move the workspace, or set IA_HOME to an absolute directory outside it.', () => assertHomeOutsideWorkspace(home, root));
397
+ located(supplied, `Move the workspace, or set IA_HOME to an absolute directory outside it; then run "${plan}".`, () => assertHomeOutsideWorkspace(home, root));
275
398
  // §3: refuse a home that itself looks like a workspace at plan time, before any payload write is attempted.
276
- located(null, homeSrcRemedy(home), () => assertIaHomeUsable(home));
399
+ located(null, homeSrcRemedy(home, plan), () => assertIaHomeUsable(home));
277
400
  const { pin: bundled } = bundledPin(host.packageRoot);
278
- requireIdle(root, name, supplied);
401
+ requireIdle(root, supplied);
279
402
  // §4: zero error findings. A removal renders nothing, so it checks admission alone.
280
- let artifacts = [];
403
+ let rendered = null;
281
404
  if (remove)
282
405
  checkAdmitted(root);
283
406
  else
284
- artifacts = renderProjectionFor(root, name);
407
+ rendered = renderProjectionFor(root, name);
285
408
  // A host home reached through a symbolic link or junction is refused by the mechanism (IA-DIST-PATH-UNSAFE), because
286
409
  // the payload it verifies must be the one the registration names; the remedy is a home with no link in its path.
287
- const expected = located(null, 'Set IA_HOME to a directory path with no links, or unset it.', () => expectedHostCache(hostPayloadPath(home, bundled.release), bundled.release));
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));
288
411
  const owned = new Set();
289
412
  if (existsSync(resolve(root, STATE.mcp(name))))
290
413
  owned.add('mcp');
291
- if (name === 'claude' && existsSync(resolve(root, STATE.hooks)))
292
- owned.add('hooks');
293
- const mcp = registrationElement('mcp', MCP_PATH[name], owned.has('mcp'), remove, () => remove ? planHostFor(root, name, null, HOST_REGISTRATION) : planHostFor(root, name, expected));
294
- const hooks = name === 'codex'
295
- ? { id: 'hooks', action: 'none', paths: [], capability: 'unsupported by host', conflict: null }
296
- : 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));
297
415
  return {
298
416
  root: supplied,
299
417
  host: name,
300
418
  remove,
301
419
  release: bundled.release,
302
420
  home,
303
- elements: [mcp, hooks, contextElement(name), projectionElement(root, name, artifacts)],
421
+ elements: [mcp, contextElement(name), projectionElement(root, name, rendered)],
304
422
  undo: `ia host ${name} --remove --apply`,
305
423
  invocation: invocationOf(context, name, remove),
306
424
  owned,
@@ -308,6 +426,8 @@ export function collectHost(context) {
308
426
  userPlugin: row.user === 'plugin' ? { installed: readMaterializedPlugin(home) !== null, command: USER_PLUGIN_COMMAND } : null,
309
427
  };
310
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.';
311
431
  /** A next action of this verb as printed: with `--root` given, each `ia host` command in it carries the root. */
312
432
  const say = (view, text) => hostNext(text, view.host, view.root, view.rooted);
313
433
  /** The next action a conflict renders, and the one its refusal carries, rooted when `--root` was given. */
@@ -319,8 +439,6 @@ function conflictNext(view, id, conflict) {
319
439
  const unreadable = stateRepair(view.host, conflict.path, rerun);
320
440
  if (unreadable !== null)
321
441
  return unreadable;
322
- if (conflict.code === 'IA-DIST-LOCAL-MODIFICATION' && id === 'hooks' && view.owned.has('hooks'))
323
- return modifiedRepair(view.host, ['hooks']);
324
442
  if (conflict.code === 'IA-DIST-LOCAL-MODIFICATION' && id === 'mcp') {
325
443
  // Owned: removal tolerates a deleted entry, so deleting it and re-registering converges. Unowned: §5.3's wording,
326
444
  // made exact for Codex, where the collision can be any ia-workspace table or a file that no longer parses.
@@ -330,10 +448,8 @@ function conflictNext(view, id, conflict) {
330
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".'
331
449
  : `Remove that entry, then run "ia host ${view.host} --apply".`;
332
450
  }
333
- if (conflict.code === 'IA-DIST-HOST-UNSUPPORTED' && id === 'hooks')
334
- return `Remove disableAllHooks from the Claude settings, then run "${rerun}".`;
335
451
  if (id === 'projection')
336
- return projectionRepair(view.host, conflict.path, rerun);
452
+ return projectionRepair(view.host, conflict.path, rerun, conflict.code);
337
453
  return `Fix ${conflict.path}, then run "${rerun}".`;
338
454
  }
339
455
  const refusalFor = (view, id, conflict) => new Refusal(conflict.code, conflict.reason, 3, { path: conflict.path }, nextFor(view, id, conflict));
@@ -346,6 +462,17 @@ function replan(view, id, path, run) {
346
462
  throw refusalFor(view, id, conflictOf(error, path));
347
463
  }
348
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
+ }
349
476
  /**
350
477
  * §3.3 steps 3-4. A payload directory that fails verification is named by the mechanism and the remedy is to delete
351
478
  * it; nothing overwrites it. Any other failure is the bundled payload's own, which only a reinstall repairs.
@@ -356,7 +483,7 @@ function materialize(view, packageRoot) {
356
483
  // Re-checked explicitly rather than inferred from a caught refusal's message: verifyNaming's own PATH-UNSAFE
357
484
  // wrapping ("... at <payload>; delete that directory") also names a path under view.home, so pattern-matching the
358
485
  // message would misroute a real corrupt-payload refusal into this remedy.
359
- located(null, homeSrcRemedy(view.home), () => assertIaHomeUsable(view.home));
486
+ located(null, say(view, homeSrcRemedy(view.home, `ia host ${view.host} --apply`)), () => assertIaHomeUsable(view.home));
360
487
  try {
361
488
  return materializeHostPayload({ home: view.home, archive: archive(), pin: bundled }).directory;
362
489
  }
@@ -366,12 +493,14 @@ function materialize(view, packageRoot) {
366
493
  }
367
494
  }
368
495
  /**
369
- * §8: mcp, hooks, projection in order; removal in reverse. The payload is materialized, then every sub-transaction is
370
- * re-planned with the verifying planners before any is applied, so a refusal any planner can find is raised before
371
- * the workspace changes; each apply then re-plans under the host lock and refuses a plan that went stale.
372
- * Cancellation is observed between sub-transactions. A failure after an element was written names the rerun that
373
- * finishes the set, or the recovery a pending journal needs. `checkpoint` runs after each element completes, which
374
- * 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.
375
504
  */
376
505
  export function applyHostSet(view, packageRoot, signal, checkpoint = () => { }) {
377
506
  const refused = view.elements.find((element) => element.conflict !== null);
@@ -387,14 +516,16 @@ export function applyHostSet(view, packageRoot, signal, checkpoint = () => { })
387
516
  const step = (id, run) => {
388
517
  if (signal?.aborted)
389
518
  throw new Interrupted(say(view, `Run "${rerun}" to finish.`));
390
- let status;
519
+ let applied;
391
520
  try {
392
- status = run();
521
+ applied = run();
393
522
  }
394
523
  catch (error) {
524
+ if (id === 'projection')
525
+ throw projectionFailure(error, root, host, rerun);
395
526
  const refusal = refusalOf(error), journal = pendingJournal(root);
396
527
  if (journal !== undefined)
397
- throw new Refusal(refusal.code, refusal.message, 3, { path: journal[0] }, say(view, recoverNext(view.root, journal[1], host)));
528
+ throw new Refusal(refusal.code, refusal.message, 3, { path: journal[0] }, say(view, recoverNext(view.root, journal[1])));
398
529
  const busy = lockRefusal(error, view.root);
399
530
  if (busy !== null)
400
531
  throw busy;
@@ -402,40 +533,32 @@ export function applyHostSet(view, packageRoot, signal, checkpoint = () => { })
402
533
  throw new Refusal(refusal.code, refusal.message, 3, refusal.where, say(view, `Run "${rerun}" to finish.`));
403
534
  throw error;
404
535
  }
405
- done.push({ id, status });
536
+ done.push({ id, ...applied });
406
537
  checkpoint(id);
407
538
  };
539
+ const project = (rendered) => () => {
540
+ const { status, guard } = applyHostProjection(root, host, rendered);
541
+ return { status, guard };
542
+ };
408
543
  if (!view.remove) {
409
544
  const cache = materialize(view, packageRoot);
410
545
  const mcp = replan(view, 'mcp', MCP_PATH[host], () => planHost(root, host, cache));
411
- const hooks = host === 'claude' ? replan(view, 'hooks', SETTINGS, () => planGuardRegistration(root, { cache })) : null;
412
- const artifacts = renderProjectionFor(root, host);
413
- const projection = replan(view, 'projection', STATE.projection(host), () => planProjection({ root, host, artifacts, marker: WORKSPACE_PROJECTION_MARKER }));
414
- step('mcp', () => applyHost(mcp).status);
415
- if (hooks === null)
416
- done.push(skipped('hooks'));
417
- else
418
- 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 }));
419
549
  done.push(skipped('context'));
420
- step('projection', () => applyProjection(projection).status);
550
+ step('projection', project(rendered));
421
551
  return { status: 'host-registered', elements: done, observed: false };
422
552
  }
423
553
  // A removal plans only what the view found owned; `none` means there is nothing of that element to remove.
424
554
  const absent = (id) => view.elements.find((element) => element.id === id).action === 'none';
425
- const projection = replan(view, 'projection', STATE.projection(host), () => planProjection({ root, host, artifacts: [], marker: WORKSPACE_PROJECTION_MARKER }));
426
- const hooks = host === 'claude' && !absent('hooks')
427
- ? replan(view, 'hooks', SETTINGS, () => planGuardRegistration(root, { remove: HOST_REGISTRATION }))
428
- : null;
555
+ replanProjection(root, host, null, (conflict) => refusalFor(view, 'projection', conflict));
429
556
  const mcp = absent('mcp')
430
557
  ? null
431
558
  : replan(view, 'mcp', MCP_PATH[host], () => planHost(root, host, null, HOST_REGISTRATION));
432
- step('projection', () => (applyProjection(projection).removed > 0 ? 'projection-removed' : 'absent'));
559
+ step('projection', project(null));
433
560
  done.push(skipped('context'));
434
- if (host === 'codex')
435
- done.push(skipped('hooks'));
436
- else
437
- step('hooks', () => (hooks === null ? 'absent' : applyGuardRegistration(hooks).status));
438
- step('mcp', () => (mcp === null ? 'absent' : applyHost(mcp).status));
561
+ step('mcp', () => ({ status: mcp === null ? 'absent' : applyHost(mcp).status }));
439
562
  return { status: 'host-removed', elements: done, observed: false };
440
563
  }
441
564
  /** §4 `--json`: the plan always, and `applied` only after an apply. */
@@ -459,7 +582,7 @@ const FILE_SYMBOL = {
459
582
  update: 'updated',
460
583
  unchanged: 'info',
461
584
  remove: 'removed',
462
- unowned: 'warning',
585
+ foreign: 'info',
463
586
  };
464
587
  const elementSymbol = (element) => element.conflict !== null
465
588
  ? 'error'
@@ -469,8 +592,10 @@ const elementSymbol = (element) => element.conflict !== null
469
592
  function elementFields(view) {
470
593
  return view.elements.map((element) => {
471
594
  const facts = [element.action, element.capability, ...(element.id === 'projection' ? [] : element.paths)];
472
- if (element.id === 'hooks' && element.capability === 'unsupported by host')
595
+ if (element.id === 'context' && element.capability === 'unsupported by host')
473
596
  facts.push(CODEX_HOOKS.replace(/\.$/, ''));
597
+ if (element.guard === 'retire')
598
+ facts.push(GUARD_RETIRE);
474
599
  if (element.conflict !== null)
475
600
  facts.push(`${element.conflict.code} ${element.conflict.reason}`);
476
601
  return {
@@ -481,20 +606,22 @@ function elementFields(view) {
481
606
  };
482
607
  });
483
608
  }
484
- /** Each projected file with its action; an unowned steward file says why it is left alone. */
485
- 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([
486
616
  [
487
617
  atom(file.path, 'cyan', 0),
488
- ...words(file.action === 'unowned'
489
- ? "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"
490
620
  : file.action, null, 2),
491
621
  ],
492
- ],
493
- // Nested at the elements block's content column (§6.4 rule 3), so each file sits under the element it belongs to.
494
- {
495
- column: indentOf(1) + blockSymbolWidth(view.elements.map(elementSymbol), caps.ascii) + 2,
496
- symbol: FILE_SYMBOL[file.action],
497
- }, 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);
498
625
  const headerBlock = (view, caps) => [
499
626
  ...headerLine('Plan', `host ${view.host}${view.remove ? ' --remove' : ''}`, [{ text: `release ${truncateDigest(view.release, caps.ascii)}`, column: 35 }], caps),
500
627
  ...headerLine('Root', view.root, [], caps),
@@ -506,9 +633,9 @@ const elementsBlock = (view, caps) => [
506
633
  ...fileBlock(view, caps),
507
634
  ];
508
635
  /**
509
- * §5.3's machine-local sentence and, for a Claude registration, §5.4's approval note and the guard's scope (the
510
- * hooks element is registered only for Claude). `ia init --host` prints the same blocks after its host step, so the
511
- * 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.
512
639
  */
513
640
  export const hostNotes = (host, caps, remove = false) => [
514
641
  entry([words(MACHINE_LOCAL[host])], { depth: 1, symbol: 'warning' }, caps),
@@ -539,6 +666,7 @@ export function renderHostPlan(view, applied, caps) {
539
666
  words(applied.status === 'host-registered'
540
667
  ? 'Registered: written; not observed answering.'
541
668
  : 'Removed the owned host set.'),
669
+ ...(applied.elements.some((element) => element.guard === 'retired') ? [words(GUARD_RETIRED)] : []),
542
670
  ], { depth: 1, symbol: 'success' }, caps),
543
671
  elementsBlock(view, caps),
544
672
  ...notesBlocks(view, caps),
@@ -566,15 +694,18 @@ export async function runHost(context) {
566
694
  view = collectHost(context);
567
695
  }
568
696
  catch (error) {
569
- // Refusals raised before a view exists — the --context gate, a pending journal — name `ia host` commands too.
697
+ // Refusals raised before a view exists — the --context gate, a pending journal — name `ia host` commands too. A
698
+ // root that is not a directory is requireRoot's own refusal, whose next action already spells the whole invocation.
570
699
  const supplied = args.value('root'), name = args.positionals[0];
700
+ const given = supplied === undefined ? undefined : resolve(host.cwd, supplied);
571
701
  if (!(error instanceof Refusal) ||
572
702
  error.next === null ||
573
- supplied === undefined ||
703
+ given === undefined ||
704
+ !statSync(given, { throwIfNoEntry: false })?.isDirectory() ||
574
705
  (name !== 'claude' && name !== 'codex'))
575
706
  throw error;
576
707
  // The real path requireRoot resolved, which succeeded before any of these refusals could be raised.
577
- throw new Refusal(error.code, error.message, error.exit, error.where, rootedNext(error.next, name, realpathSync(resolve(host.cwd, supplied))), error.at);
708
+ throw new Refusal(error.code, error.message, error.exit, error.where, rootedNext(error.next, name, realpathSync(given)), error.at);
578
709
  }
579
710
  const rendered = (applied) => json
580
711
  ? { exitCode: 0, stdout: JSON.stringify(hostEnvelope(view, applied)) + '\n', stderr: '' }