@skillcap/gdh 0.23.0 → 0.24.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 (128) hide show
  1. package/INSTALL-BUNDLE.json +1 -1
  2. package/RELEASE-SPAN-UPDATE-CONTRACTS.json +64 -0
  3. package/node_modules/@gdh/adapters/dist/authoring-hook-render.d.ts.map +1 -1
  4. package/node_modules/@gdh/adapters/dist/authoring-hook-render.js +2 -1
  5. package/node_modules/@gdh/adapters/dist/authoring-hook-render.js.map +1 -1
  6. package/node_modules/@gdh/adapters/dist/claude-statusline-render.d.ts.map +1 -1
  7. package/node_modules/@gdh/adapters/dist/claude-statusline-render.js +2 -1
  8. package/node_modules/@gdh/adapters/dist/claude-statusline-render.js.map +1 -1
  9. package/node_modules/@gdh/adapters/dist/claude-update-hook-render.d.ts.map +1 -1
  10. package/node_modules/@gdh/adapters/dist/claude-update-hook-render.js +2 -1
  11. package/node_modules/@gdh/adapters/dist/claude-update-hook-render.js.map +1 -1
  12. package/node_modules/@gdh/adapters/dist/claude-update-worker-render.d.ts.map +1 -1
  13. package/node_modules/@gdh/adapters/dist/claude-update-worker-render.js +2 -1
  14. package/node_modules/@gdh/adapters/dist/claude-update-worker-render.js.map +1 -1
  15. package/node_modules/@gdh/adapters/dist/deferred-actions-advisory.d.ts +71 -0
  16. package/node_modules/@gdh/adapters/dist/deferred-actions-advisory.d.ts.map +1 -0
  17. package/node_modules/@gdh/adapters/dist/deferred-actions-advisory.js +89 -0
  18. package/node_modules/@gdh/adapters/dist/deferred-actions-advisory.js.map +1 -0
  19. package/node_modules/@gdh/adapters/dist/durable-backup.d.ts +209 -0
  20. package/node_modules/@gdh/adapters/dist/durable-backup.d.ts.map +1 -0
  21. package/node_modules/@gdh/adapters/dist/durable-backup.js +346 -0
  22. package/node_modules/@gdh/adapters/dist/durable-backup.js.map +1 -0
  23. package/node_modules/@gdh/adapters/dist/index.d.ts +10 -1
  24. package/node_modules/@gdh/adapters/dist/index.d.ts.map +1 -1
  25. package/node_modules/@gdh/adapters/dist/index.js +24 -2
  26. package/node_modules/@gdh/adapters/dist/index.js.map +1 -1
  27. package/node_modules/@gdh/adapters/dist/inventory-sweep.d.ts +53 -0
  28. package/node_modules/@gdh/adapters/dist/inventory-sweep.d.ts.map +1 -0
  29. package/node_modules/@gdh/adapters/dist/inventory-sweep.js +98 -0
  30. package/node_modules/@gdh/adapters/dist/inventory-sweep.js.map +1 -0
  31. package/node_modules/@gdh/adapters/dist/process-orchestration.d.ts +223 -0
  32. package/node_modules/@gdh/adapters/dist/process-orchestration.d.ts.map +1 -0
  33. package/node_modules/@gdh/adapters/dist/process-orchestration.js +368 -0
  34. package/node_modules/@gdh/adapters/dist/process-orchestration.js.map +1 -0
  35. package/node_modules/@gdh/adapters/dist/self-update-mechanics.d.ts +157 -14
  36. package/node_modules/@gdh/adapters/dist/self-update-mechanics.d.ts.map +1 -1
  37. package/node_modules/@gdh/adapters/dist/self-update-mechanics.js +570 -89
  38. package/node_modules/@gdh/adapters/dist/self-update-mechanics.js.map +1 -1
  39. package/node_modules/@gdh/adapters/dist/skill-rendering.d.ts.map +1 -1
  40. package/node_modules/@gdh/adapters/dist/skill-rendering.js +25 -0
  41. package/node_modules/@gdh/adapters/dist/skill-rendering.js.map +1 -1
  42. package/node_modules/@gdh/adapters/package.json +8 -8
  43. package/node_modules/@gdh/authoring/package.json +2 -2
  44. package/node_modules/@gdh/cli/dist/index.d.ts +9 -0
  45. package/node_modules/@gdh/cli/dist/index.d.ts.map +1 -1
  46. package/node_modules/@gdh/cli/dist/index.js +244 -2
  47. package/node_modules/@gdh/cli/dist/index.js.map +1 -1
  48. package/node_modules/@gdh/cli/dist/migrate.d.ts +152 -1
  49. package/node_modules/@gdh/cli/dist/migrate.d.ts.map +1 -1
  50. package/node_modules/@gdh/cli/dist/migrate.js +290 -6
  51. package/node_modules/@gdh/cli/dist/migrate.js.map +1 -1
  52. package/node_modules/@gdh/cli/dist/self-update.d.ts +14 -0
  53. package/node_modules/@gdh/cli/dist/self-update.d.ts.map +1 -1
  54. package/node_modules/@gdh/cli/dist/self-update.js +197 -15
  55. package/node_modules/@gdh/cli/dist/self-update.js.map +1 -1
  56. package/node_modules/@gdh/cli/package.json +10 -10
  57. package/node_modules/@gdh/core/dist/index.d.ts +97 -5
  58. package/node_modules/@gdh/core/dist/index.d.ts.map +1 -1
  59. package/node_modules/@gdh/core/dist/index.js +23 -5
  60. package/node_modules/@gdh/core/dist/index.js.map +1 -1
  61. package/node_modules/@gdh/core/dist/migrations/entries/s2c2_to_s2c3_rules_schema_v2_to_v3.d.ts +3 -0
  62. package/node_modules/@gdh/core/dist/migrations/entries/s2c2_to_s2c3_rules_schema_v2_to_v3.d.ts.map +1 -0
  63. package/node_modules/@gdh/core/dist/migrations/entries/s2c2_to_s2c3_rules_schema_v2_to_v3.js +247 -0
  64. package/node_modules/@gdh/core/dist/migrations/entries/s2c2_to_s2c3_rules_schema_v2_to_v3.js.map +1 -0
  65. package/node_modules/@gdh/core/dist/migrations/entries/s3c8_to_s3c9_register_runtime_bridge_autoload.d.ts +3 -0
  66. package/node_modules/@gdh/core/dist/migrations/entries/s3c8_to_s3c9_register_runtime_bridge_autoload.d.ts.map +1 -0
  67. package/node_modules/@gdh/core/dist/migrations/entries/s3c8_to_s3c9_register_runtime_bridge_autoload.js +152 -0
  68. package/node_modules/@gdh/core/dist/migrations/entries/s3c8_to_s3c9_register_runtime_bridge_autoload.js.map +1 -0
  69. package/node_modules/@gdh/core/dist/migrations/envelopes/envelope-output-validator.d.ts +3 -0
  70. package/node_modules/@gdh/core/dist/migrations/envelopes/envelope-output-validator.d.ts.map +1 -0
  71. package/node_modules/@gdh/core/dist/migrations/envelopes/envelope-output-validator.js +67 -0
  72. package/node_modules/@gdh/core/dist/migrations/envelopes/envelope-output-validator.js.map +1 -0
  73. package/node_modules/@gdh/core/dist/migrations/envelopes/index.d.ts +37 -0
  74. package/node_modules/@gdh/core/dist/migrations/envelopes/index.d.ts.map +1 -0
  75. package/node_modules/@gdh/core/dist/migrations/envelopes/index.js +60 -0
  76. package/node_modules/@gdh/core/dist/migrations/envelopes/index.js.map +1 -0
  77. package/node_modules/@gdh/core/dist/migrations/envelopes/types.d.ts +121 -0
  78. package/node_modules/@gdh/core/dist/migrations/envelopes/types.d.ts.map +1 -0
  79. package/node_modules/@gdh/core/dist/migrations/envelopes/types.js +2 -0
  80. package/node_modules/@gdh/core/dist/migrations/envelopes/types.js.map +1 -0
  81. package/node_modules/@gdh/core/dist/migrations/golden-harness.d.ts +40 -0
  82. package/node_modules/@gdh/core/dist/migrations/golden-harness.d.ts.map +1 -0
  83. package/node_modules/@gdh/core/dist/migrations/golden-harness.js +71 -0
  84. package/node_modules/@gdh/core/dist/migrations/golden-harness.js.map +1 -0
  85. package/node_modules/@gdh/core/dist/migrations/managed-surface-classes.d.ts +322 -0
  86. package/node_modules/@gdh/core/dist/migrations/managed-surface-classes.d.ts.map +1 -0
  87. package/node_modules/@gdh/core/dist/migrations/managed-surface-classes.js +384 -0
  88. package/node_modules/@gdh/core/dist/migrations/managed-surface-classes.js.map +1 -0
  89. package/node_modules/@gdh/core/dist/migrations/probes.d.ts +58 -0
  90. package/node_modules/@gdh/core/dist/migrations/probes.d.ts.map +1 -0
  91. package/node_modules/@gdh/core/dist/migrations/probes.js +112 -0
  92. package/node_modules/@gdh/core/dist/migrations/probes.js.map +1 -0
  93. package/node_modules/@gdh/core/dist/migrations/registry.d.ts +205 -0
  94. package/node_modules/@gdh/core/dist/migrations/registry.d.ts.map +1 -0
  95. package/node_modules/@gdh/core/dist/migrations/registry.js +214 -0
  96. package/node_modules/@gdh/core/dist/migrations/registry.js.map +1 -0
  97. package/node_modules/@gdh/core/dist/state/atomic-write.d.ts +19 -0
  98. package/node_modules/@gdh/core/dist/state/atomic-write.d.ts.map +1 -0
  99. package/node_modules/@gdh/core/dist/state/atomic-write.js +34 -0
  100. package/node_modules/@gdh/core/dist/state/atomic-write.js.map +1 -0
  101. package/node_modules/@gdh/core/dist/state/migration-state.d.ts +135 -0
  102. package/node_modules/@gdh/core/dist/state/migration-state.d.ts.map +1 -0
  103. package/node_modules/@gdh/core/dist/state/migration-state.js +186 -0
  104. package/node_modules/@gdh/core/dist/state/migration-state.js.map +1 -0
  105. package/node_modules/@gdh/core/dist/state/processes-snapshot.d.ts +72 -0
  106. package/node_modules/@gdh/core/dist/state/processes-snapshot.d.ts.map +1 -0
  107. package/node_modules/@gdh/core/dist/state/processes-snapshot.js +113 -0
  108. package/node_modules/@gdh/core/dist/state/processes-snapshot.js.map +1 -0
  109. package/node_modules/@gdh/core/dist/state/render-inventory.d.ts +54 -0
  110. package/node_modules/@gdh/core/dist/state/render-inventory.d.ts.map +1 -0
  111. package/node_modules/@gdh/core/dist/state/render-inventory.js +77 -0
  112. package/node_modules/@gdh/core/dist/state/render-inventory.js.map +1 -0
  113. package/node_modules/@gdh/core/package.json +1 -1
  114. package/node_modules/@gdh/docs/dist/agent-contract.d.ts.map +1 -1
  115. package/node_modules/@gdh/docs/dist/agent-contract.js +2 -1
  116. package/node_modules/@gdh/docs/dist/agent-contract.js.map +1 -1
  117. package/node_modules/@gdh/docs/dist/guidance.d.ts.map +1 -1
  118. package/node_modules/@gdh/docs/dist/guidance.js +3 -1
  119. package/node_modules/@gdh/docs/dist/guidance.js.map +1 -1
  120. package/node_modules/@gdh/docs/package.json +2 -2
  121. package/node_modules/@gdh/mcp/package.json +8 -8
  122. package/node_modules/@gdh/observability/package.json +2 -2
  123. package/node_modules/@gdh/runtime/dist/bridge-surface.js +63 -2
  124. package/node_modules/@gdh/runtime/dist/bridge-surface.js.map +1 -1
  125. package/node_modules/@gdh/runtime/package.json +2 -2
  126. package/node_modules/@gdh/scan/package.json +3 -3
  127. package/node_modules/@gdh/verify/package.json +7 -7
  128. package/package.json +11 -11
@@ -0,0 +1,368 @@
1
+ import {} from "@gdh/core";
2
+ /**
3
+ * Allowlist of environment variable keys captured into each process row's
4
+ * `env_subset` (T-72-06-01 mitigation).
5
+ *
6
+ * The orchestrator never persists `process.env` wholesale into
7
+ * processes-snapshot.json — only keys explicitly named here, plus any key
8
+ * matching the `GDH_*` prefix (matched in {@link pickEnvSubset}). The
9
+ * regression-safe assertion test in process-orchestration.test.ts asserts
10
+ * non-allowlisted env vars (SECRET_TOKEN, AWS_SECRET_ACCESS_KEY, OPENAI_API_KEY)
11
+ * are NOT captured.
12
+ *
13
+ * If you need to add a key, add it here and document why in the commit
14
+ * message — this is the single ops-review point for what crosses the
15
+ * snapshot-file trust boundary.
16
+ */
17
+ export const STOP_AND_RESTART_ENV_SUBSET_KEYS = [
18
+ "PATH",
19
+ "NODE_PATH",
20
+ "HOME",
21
+ "USER",
22
+ "LANG",
23
+ "LC_ALL",
24
+ // GDH_* allowlist matched as prefix in `pickEnvSubset`
25
+ ];
26
+ /**
27
+ * Default graceful-stop timeout. Production-safe value; tests inject a much
28
+ * lower number (e.g. 5ms) via the `gracefulTimeoutMs` parameter so suites stay
29
+ * fast. T-72-06-04 mitigation: bounded single-attempt timeout, no retry loop.
30
+ */
31
+ export const DEFAULT_GRACEFUL_STOP_TIMEOUT_MS = 2500;
32
+ /**
33
+ * Restrict each process's `env` to the documented allowlist + any key with
34
+ * the `GDH_*` prefix. T-72-06-01 mitigation: secret env vars
35
+ * (SECRET_TOKEN, *_API_KEY, AWS_SECRET_ACCESS_KEY, etc.) never enter the
36
+ * snapshot.
37
+ */
38
+ function pickEnvSubset(env) {
39
+ const subset = {};
40
+ for (const [key, value] of Object.entries(env)) {
41
+ if (STOP_AND_RESTART_ENV_SUBSET_KEYS.includes(key) || key.startsWith("GDH_")) {
42
+ subset[key] = value;
43
+ }
44
+ }
45
+ return subset;
46
+ }
47
+ /**
48
+ * Discover owned MCP processes + broker, build a {@link GdhProcessesSnapshot}.
49
+ *
50
+ * Returns a degraded result on win32 (Pitfall 5: process orchestration is
51
+ * Mac/Linux only). The discovery hooks are NOT called on win32; the snapshot
52
+ * is empty and the caller routes around stop/restart, allowing the update to
53
+ * proceed.
54
+ *
55
+ * The returned snapshot has `stop_method = null` on every row. Plan 08 writes
56
+ * this snapshot to disk via {@link writeProcessesSnapshot}, then calls
57
+ * {@link stopCapturedProcesses} which mutates the rows to record the actual
58
+ * stop method per row.
59
+ */
60
+ export async function captureProcessSnapshot(input) {
61
+ const { env } = input;
62
+ const capturedAt = env.nowIso();
63
+ if (env.platform === "win32") {
64
+ return {
65
+ snapshot: { snapshot_version: 1, captured_at: capturedAt, processes: [] },
66
+ degraded: true,
67
+ degradedReason: "platform_unsupported_win32",
68
+ };
69
+ }
70
+ const processes = [];
71
+ const owned = await env.discoverOwnedMcpProcesses();
72
+ for (const m of owned) {
73
+ processes.push({
74
+ kind: "mcp",
75
+ pid: m.pid,
76
+ cmd: m.cmd,
77
+ args: m.args,
78
+ cwd: m.cwd,
79
+ env_subset: pickEnvSubset(m.env),
80
+ stop_method: null,
81
+ });
82
+ }
83
+ const broker = await env.inspectBroker();
84
+ if (broker !== null) {
85
+ processes.push({
86
+ kind: "broker",
87
+ pid: broker.pid,
88
+ cmd: broker.cmd,
89
+ args: broker.args,
90
+ cwd: broker.cwd,
91
+ env_subset: pickEnvSubset(broker.env),
92
+ stop_method: null,
93
+ });
94
+ }
95
+ return {
96
+ snapshot: { snapshot_version: 1, captured_at: capturedAt, processes },
97
+ degraded: false,
98
+ };
99
+ }
100
+ /**
101
+ * Stop every captured process per row.
102
+ *
103
+ * Dispatch (D-18 step 4):
104
+ * - kind === "broker": prefer {@link GdhProcessOrchestrationEnvironment.pruneBroker}
105
+ * over raw kill so broker-owned sessions are stopped cleanly first
106
+ * (Pitfall 4 / T-72-06-05). Records `stop_method: "broker_prune"`.
107
+ * - kind === "mcp": graceful SIGTERM via env.killProcess; wait
108
+ * `gracefulTimeoutMs` (default {@link DEFAULT_GRACEFUL_STOP_TIMEOUT_MS});
109
+ * if env.isProcessRunning still true, escalate to env.hardKillProcess.
110
+ * Records `stop_method: "graceful_sigterm"` or `"hard_kill"`.
111
+ *
112
+ * Idempotent: if the kill probe finds the process already gone (kill throws,
113
+ * isProcessRunning returns false), records `stop_method: "none"` and
114
+ * continues. T-72-06-04: no retry loop; bounded single-attempt timeout.
115
+ */
116
+ export async function stopCapturedProcesses(input) {
117
+ const timeoutMs = input.gracefulTimeoutMs ?? DEFAULT_GRACEFUL_STOP_TIMEOUT_MS;
118
+ const updated = [];
119
+ const skipped = [];
120
+ for (const proc of input.snapshot.processes) {
121
+ let stopMethod = "none";
122
+ if (proc.kind === "broker") {
123
+ try {
124
+ await input.env.pruneBroker(input.targetPath);
125
+ stopMethod = "broker_prune";
126
+ }
127
+ catch (error) {
128
+ skipped.push({
129
+ pid: proc.pid,
130
+ reason: `broker_prune_failed:${error instanceof Error ? error.message : String(error)}`,
131
+ });
132
+ }
133
+ }
134
+ else {
135
+ // mcp
136
+ try {
137
+ await input.env.killProcess(proc.pid);
138
+ await new Promise((resolve) => {
139
+ setTimeout(resolve, timeoutMs);
140
+ });
141
+ const stillAlive = await input.env.isProcessRunning(proc.pid);
142
+ if (stillAlive) {
143
+ await input.env.hardKillProcess(proc.pid);
144
+ stopMethod = "hard_kill";
145
+ }
146
+ else {
147
+ stopMethod = "graceful_sigterm";
148
+ }
149
+ }
150
+ catch (error) {
151
+ // killProcess threw — could be ESRCH (already gone) or permission
152
+ // denied. Probe for liveness; if gone, treat as 'none' (idempotent).
153
+ const stillAlive = await input.env.isProcessRunning(proc.pid).catch(() => false);
154
+ if (!stillAlive) {
155
+ stopMethod = "none";
156
+ }
157
+ else {
158
+ skipped.push({
159
+ pid: proc.pid,
160
+ reason: `kill_failed:${error instanceof Error ? error.message : String(error)}`,
161
+ });
162
+ }
163
+ }
164
+ }
165
+ updated.push({ ...proc, stop_method: stopMethod });
166
+ }
167
+ return {
168
+ state: "stopped",
169
+ updatedSnapshot: {
170
+ snapshot_version: 1,
171
+ captured_at: input.snapshot.captured_at,
172
+ processes: updated,
173
+ },
174
+ skipped,
175
+ };
176
+ }
177
+ /**
178
+ * Re-spawn every captured process per row.
179
+ *
180
+ * Dispatch (D-18 step 5):
181
+ * - kind === "broker": call env.ensureBroker(captured) — wraps
182
+ * ensureRuntimeBridgeBroker which polls for the ready handshake.
183
+ * - kind === "mcp": call env.spawnProcess(captured) — production wires this to
184
+ * child_process.spawn with the captured cmd/args/cwd/env_subset and detached:true.
185
+ *
186
+ * Privilege of restarted processes matches captured cwd + env_subset; no
187
+ * implicit elevation, no inheritance of process.env (T-72-06-02).
188
+ */
189
+ export async function restartFromSnapshot(input) {
190
+ const restarted = [];
191
+ const failed = [];
192
+ for (const proc of input.snapshot.processes) {
193
+ if (proc.kind === "broker") {
194
+ const result = await input.env.ensureBroker(proc);
195
+ if (result.state === "started") {
196
+ restarted.push({
197
+ kind: "broker",
198
+ originalPid: proc.pid,
199
+ newPid: null,
200
+ cmd: proc.cmd,
201
+ });
202
+ }
203
+ else {
204
+ failed.push({
205
+ kind: "broker",
206
+ pid: proc.pid,
207
+ cmd: proc.cmd,
208
+ reason: result.detail ?? "broker_ensure_failed",
209
+ });
210
+ }
211
+ }
212
+ else {
213
+ const result = await input.env.spawnProcess(proc);
214
+ if (result.state === "spawned") {
215
+ restarted.push({
216
+ kind: "mcp",
217
+ originalPid: proc.pid,
218
+ newPid: result.pid ?? null,
219
+ cmd: proc.cmd,
220
+ });
221
+ }
222
+ else {
223
+ failed.push({
224
+ kind: "mcp",
225
+ pid: proc.pid,
226
+ cmd: proc.cmd,
227
+ reason: result.detail ?? "spawn_failed",
228
+ });
229
+ }
230
+ }
231
+ }
232
+ if (failed.length === 0) {
233
+ return { state: "all_restarted", restarted };
234
+ }
235
+ return { state: "some_failed", restarted, failed };
236
+ }
237
+ /**
238
+ * Convert a structured payload (the same shape produced by Plan 08 when it
239
+ * registers a `process_restart` deferred action) into a runtime probe that
240
+ * Plan 05's `runDeferredActionProbe` consumes.
241
+ *
242
+ * Payload shape: `{ failed_rows: { kind: "mcp"|"broker", pid: number, cmd: string }[] }`
243
+ *
244
+ * The probe returns:
245
+ * - `true` when every referenced row's pid is currently running OR a
246
+ * discovered process matches by cmd (PID drift acceptable; T-72-06-06).
247
+ * - `false` when at least one row's pid is gone AND discovery does not
248
+ * surface a process with matching cmd.
249
+ * - `null` when the env adapter is unable to evaluate (win32 degraded
250
+ * platform per T-72-06-09, or malformed payload — caller's runDeferredActionProbe
251
+ * converts null to `status: "pending"` with a documented reason).
252
+ *
253
+ * The probe never throws — every error mode collapses into a defined return
254
+ * value so the advisory layer cannot crash on a misbehaving adapter.
255
+ *
256
+ * T-72-06-03: each invocation reads fresh discovery results via the env
257
+ * adapter; nothing cached crosses call boundaries.
258
+ */
259
+ export function buildProcessRestartProbeFromSnapshot(env) {
260
+ return async (payload) => {
261
+ if (env.platform === "win32")
262
+ return null;
263
+ const failedRows = payload["failed_rows"];
264
+ if (!Array.isArray(failedRows))
265
+ return null;
266
+ for (const row of failedRows) {
267
+ if (typeof row !== "object" || row === null)
268
+ return null;
269
+ const r = row;
270
+ const pid = r["pid"];
271
+ const cmd = r["cmd"];
272
+ if (typeof pid !== "number" || typeof cmd !== "string")
273
+ return null;
274
+ const stillRunningOriginalPid = await env.isProcessRunning(pid).catch(() => false);
275
+ if (stillRunningOriginalPid)
276
+ continue;
277
+ // PID drift acceptable: check discovery for matching cmd
278
+ const owned = await env.discoverOwnedMcpProcesses().catch(() => []);
279
+ const broker = await env.inspectBroker().catch(() => null);
280
+ const matchesMcp = owned.some((m) => m.cmd === cmd);
281
+ const matchesBroker = broker !== null && broker.cmd === cmd;
282
+ if (!matchesMcp && !matchesBroker) {
283
+ return false;
284
+ }
285
+ }
286
+ return true;
287
+ };
288
+ }
289
+ // ---------------------------------------------------------------------------
290
+ // Default production env factory (Plan 72-08 Task 08-02)
291
+ // ---------------------------------------------------------------------------
292
+ /**
293
+ * Default production-safe `GdhProcessOrchestrationEnvironment` factory.
294
+ *
295
+ * Returns a minimal environment that:
296
+ * - reports `process.platform` reduced to the closed enum
297
+ * - returns `() => new Date().toISOString()` for nowIso
298
+ * - returns empty discovery (no MCP processes / no broker) — production
299
+ * callers (Plan 13-02 self-update.ts) wire a richer factory backed by
300
+ * `cleanupGdhMcpProcessesWithEnvironment` + `inspectRuntimeBridgeBroker`
301
+ * + `pruneRuntimeBridgeBroker` + `ensureRuntimeBridgeBroker` from
302
+ * `@gdh/runtime`. The default factory exists so `bumpAndRebakePin`
303
+ * callers that omit the optional adapter still get a working
304
+ * no-orchestration flow (Test 1 and Test 2 of Plan 72-08 Task 08-02
305
+ * happy paths exercise this default with empty discovery).
306
+ * - uses `process.kill(pid, 'SIGTERM')` and `process.kill(pid, 'SIGKILL')`
307
+ * for kill primitives; `process.kill(pid, 0)` for liveness probe
308
+ * - no-ops `pruneBroker` and `ensureBroker` (production callers wire
309
+ * the real broker primitives)
310
+ * - no-ops `spawnProcess` (production callers wire `child_process.spawn`)
311
+ *
312
+ * The defaults are conservative — when discovery returns empty, every
313
+ * downstream stop/restart loop is a no-op and `bumpAndRebakePin`'s 12-step
314
+ * flow still completes cleanly. Production wiring layers richer adapters on
315
+ * top of this default; tests inject a fully-stubbed environment via the
316
+ * optional `processOrchestrationEnvironment` parameter to bumpAndRebakePin.
317
+ */
318
+ export function defaultProcessOrchestrationEnvironment() {
319
+ const platformRaw = process.platform;
320
+ const platform = platformRaw === "darwin"
321
+ ? "darwin"
322
+ : platformRaw === "linux"
323
+ ? "linux"
324
+ : platformRaw === "win32"
325
+ ? "win32"
326
+ : "other";
327
+ return {
328
+ platform,
329
+ nowIso: () => new Date().toISOString(),
330
+ discoverOwnedMcpProcesses: async () => [],
331
+ inspectBroker: async () => null,
332
+ killProcess: async (pid) => {
333
+ try {
334
+ process.kill(pid, "SIGTERM");
335
+ }
336
+ catch {
337
+ // ESRCH or EPERM — caller's stop loop probes liveness and treats as 'none'
338
+ }
339
+ },
340
+ hardKillProcess: async (pid) => {
341
+ try {
342
+ process.kill(pid, "SIGKILL");
343
+ }
344
+ catch {
345
+ // process already gone; no-op
346
+ }
347
+ },
348
+ isProcessRunning: async (pid) => {
349
+ try {
350
+ process.kill(pid, 0);
351
+ return true;
352
+ }
353
+ catch {
354
+ return false;
355
+ }
356
+ },
357
+ pruneBroker: async () => {
358
+ // No-op default. Production wires pruneRuntimeBridgeBroker.
359
+ },
360
+ ensureBroker: async () => ({ state: "started" }),
361
+ spawnProcess: async (captured) => {
362
+ // No-op default. Production wires child_process.spawn with the
363
+ // captured cmd/args/cwd/env_subset and detached:true.
364
+ return { state: "spawned", pid: captured.pid };
365
+ },
366
+ };
367
+ }
368
+ //# sourceMappingURL=process-orchestration.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"process-orchestration.js","sourceRoot":"","sources":["../src/process-orchestration.ts"],"names":[],"mappings":"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"}
@@ -1,11 +1,34 @@
1
- import type { GdhAgentAdapterInstallAction } from "@gdh/core";
1
+ import type { GdhAgentAdapterInstallAction, GdhApplyMigrationChainResult, GdhMigrationEnvelope, GdhMigrationVersionPair } from "@gdh/core";
2
+ import { type GdhBackupPreservationNote } from "./durable-backup.js";
3
+ import { type GdhProcessOrchestrationEnvironment, type GdhRestartFailedRow } from "./process-orchestration.js";
2
4
  /**
3
5
  * Result of a bumpAndRebakePin invocation.
4
- * - `updated`: pin rewritten; every managed surface re-baked at the new version
6
+ *
7
+ * Plan 12 / Plan 72-08 D-10 12-step flow result variants:
8
+ * - `updated`: pin rewritten; every managed surface re-baked at the new version;
9
+ * processes restarted cleanly; processes-snapshot deleted
5
10
  * - `noop`: target already at the requested version; zero writes
6
11
  * - `skipped_dev_mode`: SELF-03 gate (GDH_DEV_REPO set or local-paths.json hint present)
7
- * - `rolled_back`: re-bake failed post-commit; originals restored (best-effort)
8
- * - `blocked`: pre-commit failure (pin write itself failed); no re-bake attempted
12
+ * - `rolled_back`: legacy in-memory rollback path (preserved for backwards
13
+ * compatibility; new flow uses `rolled_back_from_durable_backup` per D-10 step 8a)
14
+ * - `blocked`: pre-commit failure (e.g., invalid semver from writePinnedVersion;
15
+ * or current pair unresolvable); no re-bake attempted
16
+ * - `rolled_back_from_durable_backup`: applyMigrationChain reported verify_failed
17
+ * or transform_threw; restoreFromDurableBackup re-created files byte-equal
18
+ * pre-update; processes stay stopped per WFL-01 D-18 step 6
19
+ * - `updated_with_deferred_actions`: re-bake + applyMigrationChain succeeded;
20
+ * restartFromSnapshot reported some_failed → migration.json gained a
21
+ * process_restart deferred action whose payload carries the failed rows
22
+ * (D-19); processes-snapshot.json persists for the runtime probe
23
+ * - `needs_envelope` (Phase 73 D-09 / D-11): applyMigrationChain paused on an
24
+ * entry whose `envelope_ref` is unresolved. `pending_envelope_resume` is
25
+ * set on `migration.json`, durable backup + processes-snapshot persist,
26
+ * and steps 3-7 are skipped on the resume run so the original pre-update
27
+ * backup content is preserved (re-taking would clobber the rollback
28
+ * substrate). Step 11 on resume reads the snapshot via
29
+ * `readProcessesSnapshot(effectiveTargetPath)` and derives any deferred-
30
+ * action id from that re-read snapshot's `captured_at` (the local
31
+ * `captureResult` is undefined on resume).
9
32
  */
10
33
  export type BumpAndRebakePinResult = {
11
34
  readonly state: "updated";
@@ -28,24 +51,144 @@ export type BumpAndRebakePinResult = {
28
51
  } | {
29
52
  readonly state: "blocked";
30
53
  readonly reason: string;
54
+ } | {
55
+ readonly state: "rolled_back_from_durable_backup";
56
+ readonly fromVersion: string;
57
+ readonly attemptedToVersion: string;
58
+ readonly failureReason: {
59
+ readonly kind: "verify_failed";
60
+ readonly entryId: string;
61
+ readonly reason: string;
62
+ } | {
63
+ readonly kind: "transform_threw";
64
+ readonly entryId: string;
65
+ readonly error: string;
66
+ };
67
+ readonly preservationNotes: readonly GdhBackupPreservationNote[];
68
+ readonly restoredPaths: readonly string[];
69
+ readonly removedPaths: readonly string[];
70
+ /**
71
+ * WR-06: Aggregate restore-failure surface from
72
+ * `restoreFromDurableBackup`. When `> 0`, some captured paths failed
73
+ * to restore (disk full, EROFS, EACCES, EISDIR, etc.) and the
74
+ * workspace is in a PARTIALLY-restored state — NOT a clean rollback.
75
+ * `restoredPaths.length === 0 && removedPaths.length === 0 &&
76
+ * restoreFailedCount > 0` means EVERY captured path failed; the
77
+ * operator must inspect the durable backup at .gdh-state/backup/ and
78
+ * recover manually. Always present (zero on a clean restore) so
79
+ * downstream consumers can treat the field as a typed scalar.
80
+ */
81
+ readonly restoreFailedCount: number;
82
+ } | {
83
+ readonly state: "updated_with_deferred_actions";
84
+ readonly fromVersion: string;
85
+ readonly toVersion: string;
86
+ readonly actions: readonly GdhAgentAdapterInstallAction[];
87
+ readonly migrationChainResult: Extract<GdhApplyMigrationChainResult, {
88
+ state: "applied";
89
+ } | {
90
+ state: "noop";
91
+ }>;
92
+ readonly deferredActions: readonly {
93
+ readonly id: string;
94
+ readonly kind: string;
95
+ }[];
96
+ readonly restartFailedRows: readonly GdhRestartFailedRow[];
97
+ readonly preservationNotes: readonly GdhBackupPreservationNote[];
98
+ } | {
99
+ /**
100
+ * Phase 73 D-09 / D-11. Migration chain paused on an unresolved
101
+ * envelope_ref. `migration.json.pending_envelope_resume` is set; the
102
+ * durable backup persists; processes-snapshot.json persists. The agent
103
+ * calls `gdh migration record-envelope-result <slug> --result-file <path>`
104
+ * (Plan 73-05 contract), then re-runs `gdh self-update` which resumes
105
+ * from step 8 (steps 3-7 are skipped on resume — the durable backup
106
+ * must NOT be re-taken because it would clobber the pre-update content
107
+ * that the rollback substrate depends on).
108
+ */
109
+ readonly state: "needs_envelope";
110
+ readonly fromVersion: string;
111
+ readonly attemptedToVersion: string;
112
+ readonly envelopeRef: string;
113
+ readonly envelope: GdhMigrationEnvelope;
114
+ readonly preservationNotes: readonly GdhBackupPreservationNote[];
115
+ /**
116
+ * Entries already applied in this chain run before the pause. Empty when
117
+ * the first envelope-bearing entry pauses; populated when one or more
118
+ * mechanical entries advance before an envelope-bearing entry pauses.
119
+ */
120
+ readonly priorlyApplied: readonly string[];
31
121
  };
32
122
  /**
33
- * Phase 12 MIG-01 + MIG-02 orchestrator. Atomically bumps the .gdh/project.yaml
34
- * `gdh_version` pin and re-bakes every managed surface at the new pin.
123
+ * Resolve the {schema, agentContract} pair for an onboarded target.
124
+ *
125
+ * Returns:
126
+ * - `null` when `.gdh/project.yaml` is absent or unparseable (project not
127
+ * onboarded; bumpAndRebakePin treats this as `blocked` with reason
128
+ * `current_pair_unresolvable`)
129
+ * - the supported-range floor pair `{schema: 2, agentContract: 2}` for any
130
+ * readable target
131
+ *
132
+ * Why a constant floor instead of the on-disk version? The supported floor
133
+ * pair gates the s2c2_to_s2c3 registry entry's range filter
134
+ * (entry.from = {2,2} must be ≥ fromPair). Per Plan 72-02 audit, every entry
135
+ * in the supported range is idempotent — running it on a target that's
136
+ * already past the entry's `to` pair is a verify-true no-op. Using the
137
+ * constant floor means the chain considers every entry on every run; the
138
+ * entry transforms self-detect "already at HEAD" and skip work, and the
139
+ * entry verify probes self-confirm "rules.yaml at version: 3" regardless of
140
+ * whether the entry just rewrote it or it was already there.
141
+ *
142
+ * The on-disk schema version (`version:` field of `.gdh/project.yaml`) is
143
+ * read defensively to confirm the config is parseable, but is not used to
144
+ * narrow the pair: per the audit, project.yaml `version: 3` has been
145
+ * forward-compatible since v0.18 and does not gate registry entries.
146
+ */
147
+ export declare function resolveCurrentMigrationPairOrNull(targetPath: string): Promise<GdhMigrationVersionPair | null>;
148
+ /**
149
+ * Resolve the {schema, agentContract} pair for the running GDH version.
150
+ *
151
+ * Always the package's compile-time pair: `GDH_PROJECT_CONFIG_VERSION` and
152
+ * `GDH_AGENT_CONTRACT_VERSION` from `@gdh/core`. This is the chain's `to`
153
+ * pair ceiling — applyMigrationChain runs every entry whose `to` ≤ this pair.
154
+ */
155
+ export declare function resolveTargetMigrationPair(): GdhMigrationVersionPair;
156
+ /**
157
+ * Phase 12 MIG-01 + MIG-02 + Plan 72-08 D-10 orchestrator. Atomically bumps the
158
+ * `.gdh/project.yaml` `gdh_version` pin, re-bakes every managed surface at the
159
+ * new pin (class-1), runs the migration registry chain (class-2/3 transforms +
160
+ * verify probes), sweeps orphan files, and orchestrates managed-process
161
+ * stop/restart with a deferred-action recovery path on restart failure.
35
162
  *
36
- * Sequencing invariant (MIG-02): writePinnedVersion is called BEFORE
37
- * installSupportedAgentAdapters. Because installSupportedAgentAdapters reads
38
- * the pin from disk once per top-level call (adapters/index.ts:173), pinning
39
- * first guarantees every renderer bakes the new value.
163
+ * The full 12-step ordering (D-10):
164
+ * 1. SELF-03 dev-mode short-circuit (preserved unchanged)
165
+ * 2. Plan: dry-run installSupportedAgentAdapters + resolve from/to pair
166
+ * 3. Capture process snapshot (writeProcessesSnapshot)
167
+ * 4. Stop processes (broker → pruneBroker; mcp → graceful → hard kill)
168
+ * 5. Write durable backup (.gdh-state/backup/) with WFL-02 marker drift detection
169
+ * 6. Write pin (writePinnedVersion) — MIG-02 sequencing precedes final re-bake
170
+ * 7. Re-bake adapters (installSupportedAgentAdapters apply)
171
+ * 8. Apply migration chain (registry entries class-2/3); failure → 8a rollback
172
+ * 9. Inventory set-diff sweep (orphan deletion)
173
+ * 10. Write new render-inventory.json + migration.json
174
+ * 11. Restart processes from snapshot; on all_restarted delete snapshot,
175
+ * on some_failed write process_restart deferred action (D-19)
176
+ * 12. Emit structured BumpAndRebakePinResult
40
177
  *
41
- * Transactional invariant (MIG-02): on re-bake failure, every captured original
42
- * is restored. Partial state is not acceptable.
178
+ * On step-8 chain failure: restoreFromDurableBackup re-creates files byte-equal
179
+ * pre-update (writePinnedVersion is rolled back automatically because
180
+ * `.gdh/project.yaml` is in the captured paths). Processes stay stopped per
181
+ * WFL-01 D-18 step 6. Inventory is NOT updated (the new render set was never
182
+ * reached coherently). Result: `rolled_back_from_durable_backup`.
43
183
  *
44
- * SELF-03 leak barrier: dev-mode check gates at the mechanics layer, not only at
45
- * Phase 13 entry points. Single source of truth.
184
+ * Sequencing invariant (MIG-02 + validate-docs Check 43): writePinnedVersion
185
+ * is called textually BEFORE the FINAL installSupportedAgentAdapters call in
186
+ * this file. The dry-run plan call at step 2 reads the current pin; the apply
187
+ * call at step 7 reads the new pin from disk after writePinnedVersion.
46
188
  */
47
189
  export declare function bumpAndRebakePin(targetPath: string, options: {
48
190
  readonly targetVersion: string;
49
191
  readonly dryRun?: boolean;
192
+ readonly processOrchestrationEnvironment?: GdhProcessOrchestrationEnvironment;
50
193
  }): Promise<BumpAndRebakePinResult>;
51
194
  //# sourceMappingURL=self-update-mechanics.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"self-update-mechanics.d.ts","sourceRoot":"","sources":["../src/self-update-mechanics.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,WAAW,CAAC;AAmB9D;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IACE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,4BAA4B,EAAE,CAAC;CAC3D,GACD;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAC3D;IACE,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC,GACD;IACE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C,GACD;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;IACP,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B,GACA,OAAO,CAAC,sBAAsB,CAAC,CA6FjC"}
1
+ {"version":3,"file":"self-update-mechanics.d.ts","sourceRoot":"","sources":["../src/self-update-mechanics.ts"],"names":[],"mappings":"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"}