@skillcap/gdh 0.23.0 → 0.25.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 (165) hide show
  1. package/INSTALL-BUNDLE.json +1 -1
  2. package/RELEASE-SPAN-UPDATE-CONTRACTS.json +122 -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 +9 -131
  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 +6 -28
  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 +7 -40
  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 +7 -68
  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 +11 -3
  24. package/node_modules/@gdh/adapters/dist/index.d.ts.map +1 -1
  25. package/node_modules/@gdh/adapters/dist/index.js +79 -43
  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 +2 -5
  40. package/node_modules/@gdh/adapters/dist/skill-rendering.d.ts.map +1 -1
  41. package/node_modules/@gdh/adapters/dist/skill-rendering.js +39 -56
  42. package/node_modules/@gdh/adapters/dist/skill-rendering.js.map +1 -1
  43. package/node_modules/@gdh/adapters/dist/template-assets.d.ts +2 -0
  44. package/node_modules/@gdh/adapters/dist/template-assets.d.ts.map +1 -0
  45. package/node_modules/@gdh/adapters/dist/template-assets.js +26 -0
  46. package/node_modules/@gdh/adapters/dist/template-assets.js.map +1 -0
  47. package/node_modules/@gdh/adapters/dist/templates/authoring-hook.js.tpl +128 -0
  48. package/node_modules/@gdh/adapters/dist/templates/claude-check-update-hook.js.tpl +37 -0
  49. package/node_modules/@gdh/adapters/dist/templates/claude-check-update-worker.js.tpl +65 -0
  50. package/node_modules/@gdh/adapters/dist/templates/claude-statusline.js.tpl +25 -0
  51. package/node_modules/@gdh/adapters/package.json +8 -8
  52. package/node_modules/@gdh/authoring/package.json +2 -2
  53. package/node_modules/@gdh/cli/dist/index.d.ts +9 -0
  54. package/node_modules/@gdh/cli/dist/index.d.ts.map +1 -1
  55. package/node_modules/@gdh/cli/dist/index.js +249 -6
  56. package/node_modules/@gdh/cli/dist/index.js.map +1 -1
  57. package/node_modules/@gdh/cli/dist/migrate.d.ts +152 -1
  58. package/node_modules/@gdh/cli/dist/migrate.d.ts.map +1 -1
  59. package/node_modules/@gdh/cli/dist/migrate.js +355 -8
  60. package/node_modules/@gdh/cli/dist/migrate.js.map +1 -1
  61. package/node_modules/@gdh/cli/dist/self-update.d.ts +14 -0
  62. package/node_modules/@gdh/cli/dist/self-update.d.ts.map +1 -1
  63. package/node_modules/@gdh/cli/dist/self-update.js +197 -15
  64. package/node_modules/@gdh/cli/dist/self-update.js.map +1 -1
  65. package/node_modules/@gdh/cli/dist/setup.d.ts +4 -0
  66. package/node_modules/@gdh/cli/dist/setup.d.ts.map +1 -1
  67. package/node_modules/@gdh/cli/dist/setup.js +8 -67
  68. package/node_modules/@gdh/cli/dist/setup.js.map +1 -1
  69. package/node_modules/@gdh/cli/package.json +10 -10
  70. package/node_modules/@gdh/core/dist/index.d.ts +99 -5
  71. package/node_modules/@gdh/core/dist/index.d.ts.map +1 -1
  72. package/node_modules/@gdh/core/dist/index.js +24 -5
  73. package/node_modules/@gdh/core/dist/index.js.map +1 -1
  74. package/node_modules/@gdh/core/dist/migrations/entries/s2c2_to_s2c3_rules_schema_v2_to_v3.d.ts +3 -0
  75. package/node_modules/@gdh/core/dist/migrations/entries/s2c2_to_s2c3_rules_schema_v2_to_v3.d.ts.map +1 -0
  76. package/node_modules/@gdh/core/dist/migrations/entries/s2c2_to_s2c3_rules_schema_v2_to_v3.js +247 -0
  77. package/node_modules/@gdh/core/dist/migrations/entries/s2c2_to_s2c3_rules_schema_v2_to_v3.js.map +1 -0
  78. package/node_modules/@gdh/core/dist/migrations/entries/s3c8_to_s3c9_register_runtime_bridge_autoload.d.ts +3 -0
  79. package/node_modules/@gdh/core/dist/migrations/entries/s3c8_to_s3c9_register_runtime_bridge_autoload.d.ts.map +1 -0
  80. package/node_modules/@gdh/core/dist/migrations/entries/s3c8_to_s3c9_register_runtime_bridge_autoload.js +152 -0
  81. package/node_modules/@gdh/core/dist/migrations/entries/s3c8_to_s3c9_register_runtime_bridge_autoload.js.map +1 -0
  82. package/node_modules/@gdh/core/dist/migrations/envelopes/envelope-output-validator.d.ts +3 -0
  83. package/node_modules/@gdh/core/dist/migrations/envelopes/envelope-output-validator.d.ts.map +1 -0
  84. package/node_modules/@gdh/core/dist/migrations/envelopes/envelope-output-validator.js +67 -0
  85. package/node_modules/@gdh/core/dist/migrations/envelopes/envelope-output-validator.js.map +1 -0
  86. package/node_modules/@gdh/core/dist/migrations/envelopes/index.d.ts +37 -0
  87. package/node_modules/@gdh/core/dist/migrations/envelopes/index.d.ts.map +1 -0
  88. package/node_modules/@gdh/core/dist/migrations/envelopes/index.js +60 -0
  89. package/node_modules/@gdh/core/dist/migrations/envelopes/index.js.map +1 -0
  90. package/node_modules/@gdh/core/dist/migrations/envelopes/types.d.ts +121 -0
  91. package/node_modules/@gdh/core/dist/migrations/envelopes/types.d.ts.map +1 -0
  92. package/node_modules/@gdh/core/dist/migrations/envelopes/types.js +2 -0
  93. package/node_modules/@gdh/core/dist/migrations/envelopes/types.js.map +1 -0
  94. package/node_modules/@gdh/core/dist/migrations/golden-harness.d.ts +40 -0
  95. package/node_modules/@gdh/core/dist/migrations/golden-harness.d.ts.map +1 -0
  96. package/node_modules/@gdh/core/dist/migrations/golden-harness.js +71 -0
  97. package/node_modules/@gdh/core/dist/migrations/golden-harness.js.map +1 -0
  98. package/node_modules/@gdh/core/dist/migrations/managed-surface-classes.d.ts +322 -0
  99. package/node_modules/@gdh/core/dist/migrations/managed-surface-classes.d.ts.map +1 -0
  100. package/node_modules/@gdh/core/dist/migrations/managed-surface-classes.js +384 -0
  101. package/node_modules/@gdh/core/dist/migrations/managed-surface-classes.js.map +1 -0
  102. package/node_modules/@gdh/core/dist/migrations/managed-target-surface-inventory.d.ts +294 -0
  103. package/node_modules/@gdh/core/dist/migrations/managed-target-surface-inventory.d.ts.map +1 -0
  104. package/node_modules/@gdh/core/dist/migrations/managed-target-surface-inventory.js +365 -0
  105. package/node_modules/@gdh/core/dist/migrations/managed-target-surface-inventory.js.map +1 -0
  106. package/node_modules/@gdh/core/dist/migrations/probes.d.ts +58 -0
  107. package/node_modules/@gdh/core/dist/migrations/probes.d.ts.map +1 -0
  108. package/node_modules/@gdh/core/dist/migrations/probes.js +112 -0
  109. package/node_modules/@gdh/core/dist/migrations/probes.js.map +1 -0
  110. package/node_modules/@gdh/core/dist/migrations/registry.d.ts +205 -0
  111. package/node_modules/@gdh/core/dist/migrations/registry.d.ts.map +1 -0
  112. package/node_modules/@gdh/core/dist/migrations/registry.js +214 -0
  113. package/node_modules/@gdh/core/dist/migrations/registry.js.map +1 -0
  114. package/node_modules/@gdh/core/dist/state/atomic-write.d.ts +19 -0
  115. package/node_modules/@gdh/core/dist/state/atomic-write.d.ts.map +1 -0
  116. package/node_modules/@gdh/core/dist/state/atomic-write.js +34 -0
  117. package/node_modules/@gdh/core/dist/state/atomic-write.js.map +1 -0
  118. package/node_modules/@gdh/core/dist/state/migration-state.d.ts +135 -0
  119. package/node_modules/@gdh/core/dist/state/migration-state.d.ts.map +1 -0
  120. package/node_modules/@gdh/core/dist/state/migration-state.js +186 -0
  121. package/node_modules/@gdh/core/dist/state/migration-state.js.map +1 -0
  122. package/node_modules/@gdh/core/dist/state/processes-snapshot.d.ts +72 -0
  123. package/node_modules/@gdh/core/dist/state/processes-snapshot.d.ts.map +1 -0
  124. package/node_modules/@gdh/core/dist/state/processes-snapshot.js +113 -0
  125. package/node_modules/@gdh/core/dist/state/processes-snapshot.js.map +1 -0
  126. package/node_modules/@gdh/core/dist/state/render-inventory.d.ts +54 -0
  127. package/node_modules/@gdh/core/dist/state/render-inventory.d.ts.map +1 -0
  128. package/node_modules/@gdh/core/dist/state/render-inventory.js +77 -0
  129. package/node_modules/@gdh/core/dist/state/render-inventory.js.map +1 -0
  130. package/node_modules/@gdh/core/package.json +1 -1
  131. package/node_modules/@gdh/docs/dist/agent-contract.d.ts +2 -1
  132. package/node_modules/@gdh/docs/dist/agent-contract.d.ts.map +1 -1
  133. package/node_modules/@gdh/docs/dist/agent-contract.js +5 -3
  134. package/node_modules/@gdh/docs/dist/agent-contract.js.map +1 -1
  135. package/node_modules/@gdh/docs/dist/guidance.d.ts +2 -0
  136. package/node_modules/@gdh/docs/dist/guidance.d.ts.map +1 -1
  137. package/node_modules/@gdh/docs/dist/guidance.js +29 -255
  138. package/node_modules/@gdh/docs/dist/guidance.js.map +1 -1
  139. package/node_modules/@gdh/docs/dist/index.d.ts +1 -1
  140. package/node_modules/@gdh/docs/dist/index.d.ts.map +1 -1
  141. package/node_modules/@gdh/docs/dist/index.js +1 -1
  142. package/node_modules/@gdh/docs/dist/index.js.map +1 -1
  143. package/node_modules/@gdh/docs/dist/query.d.ts.map +1 -1
  144. package/node_modules/@gdh/docs/dist/query.js +4 -5
  145. package/node_modules/@gdh/docs/dist/query.js.map +1 -1
  146. package/node_modules/@gdh/docs/dist/recovery-hints.js +1 -1
  147. package/node_modules/@gdh/docs/dist/recovery-hints.js.map +1 -1
  148. package/node_modules/@gdh/docs/dist/template-assets.d.ts +2 -0
  149. package/node_modules/@gdh/docs/dist/template-assets.d.ts.map +1 -0
  150. package/node_modules/@gdh/docs/dist/template-assets.js +26 -0
  151. package/node_modules/@gdh/docs/dist/template-assets.js.map +1 -0
  152. package/node_modules/@gdh/docs/dist/templates/guidance/authoring-and-validation.md.tpl +111 -0
  153. package/node_modules/@gdh/docs/dist/templates/guidance/gdh-glossary.md.tpl +34 -0
  154. package/node_modules/@gdh/docs/dist/templates/guidance/persistence-semantics.md.tpl +24 -0
  155. package/node_modules/@gdh/docs/dist/templates/guidance/project-migration.md.tpl +19 -0
  156. package/node_modules/@gdh/docs/dist/templates/guidance/project-surfaces.md.tpl +14 -0
  157. package/node_modules/@gdh/docs/package.json +2 -2
  158. package/node_modules/@gdh/mcp/package.json +8 -8
  159. package/node_modules/@gdh/observability/package.json +2 -2
  160. package/node_modules/@gdh/runtime/dist/bridge-surface.js +63 -2
  161. package/node_modules/@gdh/runtime/dist/bridge-surface.js.map +1 -1
  162. package/node_modules/@gdh/runtime/package.json +2 -2
  163. package/node_modules/@gdh/scan/package.json +3 -3
  164. package/node_modules/@gdh/verify/package.json +7 -7
  165. package/package.json +11 -11
@@ -0,0 +1,98 @@
1
+ import fs from "node:fs/promises";
2
+ import path from "node:path";
3
+ import { GDH_MANAGED_SURFACE_CLASSES, isWorkspaceRelativePath, } from "@gdh/core";
4
+ /**
5
+ * Derive the expected render set from the Phase 70 manifest
6
+ * (`GDH_MANAGED_SURFACE_CLASSES`).
7
+ *
8
+ * Only entries with a non-null `relativePath` contribute. Skill-class
9
+ * entries with `relativePath: null` are conceptual surfaces (the renderer
10
+ * resolves the actual paths per-adapter) and are NOT in the inventory's
11
+ * direct delete-comparison set.
12
+ */
13
+ export function deriveExpectedRenderSet() {
14
+ const expected = new Set();
15
+ for (const entry of GDH_MANAGED_SURFACE_CLASSES) {
16
+ if (entry.relativePath !== null) {
17
+ expected.add(entry.relativePath);
18
+ }
19
+ }
20
+ return expected;
21
+ }
22
+ /**
23
+ * Run the orphan sweep (STA-02).
24
+ *
25
+ * Orphans = (oldInventory.paths ∪ supplementaryDeletions) MINUS expected
26
+ * render set (derived from `GDH_MANAGED_SURFACE_CLASSES`).
27
+ *
28
+ * Behaviour contract:
29
+ * - **Path traversal blocked:** any candidate failing
30
+ * `isWorkspaceRelativePath` (T-72-03-01) is skipped with reason
31
+ * `path_traversal_blocked`; never deleted.
32
+ * - **Symlinks not followed:** existence is probed via `fs.lstat` so
33
+ * symlinks are detected by-link (not by-target); deletion via
34
+ * `fs.rm(... { force: true })` calls `unlink` for symlinks (T-72-03-02).
35
+ * Symlink targets are never deleted.
36
+ * - **Idempotent:** missing files report as `alreadyAbsent`; not an error.
37
+ * - **First-run bootstrap (D-16):** when `oldInventory` is null, only
38
+ * `supplementaryDeletions` is processed (no set-diff input from a
39
+ * prior render-inventory.paths).
40
+ * - **Caller writes the new inventory after** consuming this result. The
41
+ * sweep does NOT write `.gdh-state/render-inventory.json`; Plan 08 step
42
+ * 11 wires the write into `bumpAndRebakePin` after the sweep returns
43
+ * successfully (transactional ordering: deletions first, then commit
44
+ * the new inventory).
45
+ */
46
+ export async function runInventorySweep(input) {
47
+ const expected = deriveExpectedRenderSet();
48
+ const candidates = new Set();
49
+ if (input.oldInventory !== null) {
50
+ for (const candidate of input.oldInventory.paths)
51
+ candidates.add(candidate);
52
+ }
53
+ for (const candidate of input.supplementaryDeletions ?? []) {
54
+ candidates.add(candidate);
55
+ }
56
+ const orphans = [...candidates]
57
+ .filter((candidate) => !expected.has(candidate))
58
+ .sort();
59
+ const deleted = [];
60
+ const alreadyAbsent = [];
61
+ const skipped = [];
62
+ for (const orphan of orphans) {
63
+ if (!isWorkspaceRelativePath(orphan)) {
64
+ skipped.push({ path: orphan, reason: "path_traversal_blocked" });
65
+ continue;
66
+ }
67
+ const absolute = path.join(input.targetPath, orphan);
68
+ let exists = true;
69
+ try {
70
+ // lstat (not stat) so symlinks are reported by-link, not by-target
71
+ await fs.lstat(absolute);
72
+ }
73
+ catch {
74
+ exists = false;
75
+ }
76
+ if (!exists) {
77
+ alreadyAbsent.push(orphan);
78
+ continue;
79
+ }
80
+ try {
81
+ // fs.rm with force:true uses unlink semantics for symlinks (does NOT
82
+ // follow them) and removes regular files. Directories would be removed
83
+ // recursively only if `recursive: true` is set, which we do not pass —
84
+ // the sweep targets files-only by design.
85
+ await fs.rm(absolute, { force: true });
86
+ deleted.push(orphan);
87
+ }
88
+ catch (error) {
89
+ skipped.push({
90
+ path: orphan,
91
+ reason: "delete_failed",
92
+ detail: error instanceof Error ? error.message : String(error),
93
+ });
94
+ }
95
+ }
96
+ return { state: "swept", deleted, alreadyAbsent, skipped };
97
+ }
98
+ //# sourceMappingURL=inventory-sweep.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"inventory-sweep.js","sourceRoot":"","sources":["../src/inventory-sweep.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,223 @@
1
+ import { type GdhCapturedProcess, type GdhProcessesSnapshot } 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 declare const STOP_AND_RESTART_ENV_SUBSET_KEYS: readonly string[];
18
+ /**
19
+ * Default graceful-stop timeout. Production-safe value; tests inject a much
20
+ * lower number (e.g. 5ms) via the `gracefulTimeoutMs` parameter so suites stay
21
+ * fast. T-72-06-04 mitigation: bounded single-attempt timeout, no retry loop.
22
+ */
23
+ export declare const DEFAULT_GRACEFUL_STOP_TIMEOUT_MS = 2500;
24
+ export type GdhProcessOrchestrationPlatform = "darwin" | "linux" | "win32" | "other";
25
+ /** Discovered MCP process — caller's adapter sources this from the OS. */
26
+ export interface GdhDiscoveredMcpProcess {
27
+ readonly pid: number;
28
+ readonly cmd: string;
29
+ readonly args: readonly string[];
30
+ readonly cwd: string | null;
31
+ readonly env: Record<string, string>;
32
+ }
33
+ /** Discovered broker process — caller's adapter sources this from
34
+ * inspectRuntimeBridgeBroker.metadata. */
35
+ export interface GdhDiscoveredBrokerProcess {
36
+ readonly pid: number;
37
+ readonly cmd: string;
38
+ readonly args: readonly string[];
39
+ readonly cwd: string | null;
40
+ readonly env: Record<string, string>;
41
+ }
42
+ /**
43
+ * Injectable environment for the process orchestrator.
44
+ *
45
+ * In production, callers wire the defaults around mcp-cleanup +
46
+ * bridge-broker primitives (cleanupGdhMcpProcessesWithEnvironment +
47
+ * inspectRuntimeBridgeBroker / pruneRuntimeBridgeBroker /
48
+ * ensureRuntimeBridgeBroker). In tests, every method is stubbed — the
49
+ * orchestrator never touches `process.kill` or `spawn` directly. This is the
50
+ * sole OS-touching surface (must_have: "GdhProcessOrchestrationEnvironment
51
+ * injectable adapter for testability").
52
+ */
53
+ export interface GdhProcessOrchestrationEnvironment {
54
+ readonly platform: GdhProcessOrchestrationPlatform;
55
+ readonly nowIso: () => string;
56
+ readonly discoverOwnedMcpProcesses: () => Promise<readonly GdhDiscoveredMcpProcess[]>;
57
+ readonly inspectBroker: () => Promise<GdhDiscoveredBrokerProcess | null>;
58
+ readonly killProcess: (pid: number) => Promise<void>;
59
+ readonly hardKillProcess: (pid: number) => Promise<void>;
60
+ readonly isProcessRunning: (pid: number) => Promise<boolean>;
61
+ readonly pruneBroker: (targetPath: string) => Promise<void>;
62
+ readonly ensureBroker: (captured: GdhCapturedProcess) => Promise<{
63
+ readonly state: "started" | "failed";
64
+ readonly detail?: string;
65
+ }>;
66
+ readonly spawnProcess: (captured: GdhCapturedProcess) => Promise<{
67
+ readonly state: "spawned" | "failed";
68
+ readonly pid?: number;
69
+ readonly detail?: string;
70
+ }>;
71
+ }
72
+ export interface GdhCaptureProcessSnapshotResult {
73
+ readonly snapshot: GdhProcessesSnapshot;
74
+ readonly degraded: boolean;
75
+ readonly degradedReason?: "platform_unsupported_win32";
76
+ }
77
+ /**
78
+ * Discover owned MCP processes + broker, build a {@link GdhProcessesSnapshot}.
79
+ *
80
+ * Returns a degraded result on win32 (Pitfall 5: process orchestration is
81
+ * Mac/Linux only). The discovery hooks are NOT called on win32; the snapshot
82
+ * is empty and the caller routes around stop/restart, allowing the update to
83
+ * proceed.
84
+ *
85
+ * The returned snapshot has `stop_method = null` on every row. Plan 08 writes
86
+ * this snapshot to disk via {@link writeProcessesSnapshot}, then calls
87
+ * {@link stopCapturedProcesses} which mutates the rows to record the actual
88
+ * stop method per row.
89
+ */
90
+ export declare function captureProcessSnapshot(input: {
91
+ readonly targetPath: string;
92
+ readonly env: GdhProcessOrchestrationEnvironment;
93
+ }): Promise<GdhCaptureProcessSnapshotResult>;
94
+ export interface GdhStopCapturedProcessesSkipped {
95
+ readonly pid: number;
96
+ readonly reason: string;
97
+ }
98
+ export interface GdhStopCapturedProcessesResult {
99
+ readonly state: "stopped";
100
+ readonly updatedSnapshot: GdhProcessesSnapshot;
101
+ readonly skipped: readonly GdhStopCapturedProcessesSkipped[];
102
+ }
103
+ /**
104
+ * Stop every captured process per row.
105
+ *
106
+ * Dispatch (D-18 step 4):
107
+ * - kind === "broker": prefer {@link GdhProcessOrchestrationEnvironment.pruneBroker}
108
+ * over raw kill so broker-owned sessions are stopped cleanly first
109
+ * (Pitfall 4 / T-72-06-05). Records `stop_method: "broker_prune"`.
110
+ * - kind === "mcp": graceful SIGTERM via env.killProcess; wait
111
+ * `gracefulTimeoutMs` (default {@link DEFAULT_GRACEFUL_STOP_TIMEOUT_MS});
112
+ * if env.isProcessRunning still true, escalate to env.hardKillProcess.
113
+ * Records `stop_method: "graceful_sigterm"` or `"hard_kill"`.
114
+ *
115
+ * Idempotent: if the kill probe finds the process already gone (kill throws,
116
+ * isProcessRunning returns false), records `stop_method: "none"` and
117
+ * continues. T-72-06-04: no retry loop; bounded single-attempt timeout.
118
+ */
119
+ export declare function stopCapturedProcesses(input: {
120
+ readonly snapshot: GdhProcessesSnapshot;
121
+ readonly env: GdhProcessOrchestrationEnvironment;
122
+ readonly targetPath: string;
123
+ readonly gracefulTimeoutMs?: number;
124
+ }): Promise<GdhStopCapturedProcessesResult>;
125
+ /** A row that failed to restart; carried in the deferred-action payload. */
126
+ export interface GdhRestartFailedRow {
127
+ readonly kind: "mcp" | "broker";
128
+ readonly pid: number;
129
+ readonly cmd: string;
130
+ readonly reason: string;
131
+ }
132
+ /** A row that successfully restarted (PID may differ from original — see
133
+ * T-72-06-06: PID drift accepted, identity carried via originalPid for
134
+ * audit and via cmd for re-discovery). */
135
+ export interface GdhRestartedRow {
136
+ readonly kind: "mcp" | "broker";
137
+ readonly originalPid: number;
138
+ readonly newPid: number | null;
139
+ readonly cmd: string;
140
+ }
141
+ /**
142
+ * Discriminated result of {@link restartFromSnapshot}. On `all_restarted`,
143
+ * Plan 08 deletes processes-snapshot.json (D-18 step 12 success path). On
144
+ * `some_failed`, Plan 08 leaves the snapshot in place AND creates a
145
+ * `process_restart` deferred action whose payload carries the `failed` rows
146
+ * for the runtime probe (D-19).
147
+ */
148
+ export type GdhRestartFromSnapshotResult = {
149
+ readonly state: "all_restarted";
150
+ readonly restarted: readonly GdhRestartedRow[];
151
+ } | {
152
+ readonly state: "some_failed";
153
+ readonly restarted: readonly GdhRestartedRow[];
154
+ readonly failed: readonly GdhRestartFailedRow[];
155
+ };
156
+ /**
157
+ * Re-spawn every captured process per row.
158
+ *
159
+ * Dispatch (D-18 step 5):
160
+ * - kind === "broker": call env.ensureBroker(captured) — wraps
161
+ * ensureRuntimeBridgeBroker which polls for the ready handshake.
162
+ * - kind === "mcp": call env.spawnProcess(captured) — production wires this to
163
+ * child_process.spawn with the captured cmd/args/cwd/env_subset and detached:true.
164
+ *
165
+ * Privilege of restarted processes matches captured cwd + env_subset; no
166
+ * implicit elevation, no inheritance of process.env (T-72-06-02).
167
+ */
168
+ export declare function restartFromSnapshot(input: {
169
+ readonly snapshot: GdhProcessesSnapshot;
170
+ readonly env: GdhProcessOrchestrationEnvironment;
171
+ readonly targetPath: string;
172
+ }): Promise<GdhRestartFromSnapshotResult>;
173
+ /**
174
+ * Convert a structured payload (the same shape produced by Plan 08 when it
175
+ * registers a `process_restart` deferred action) into a runtime probe that
176
+ * Plan 05's `runDeferredActionProbe` consumes.
177
+ *
178
+ * Payload shape: `{ failed_rows: { kind: "mcp"|"broker", pid: number, cmd: string }[] }`
179
+ *
180
+ * The probe returns:
181
+ * - `true` when every referenced row's pid is currently running OR a
182
+ * discovered process matches by cmd (PID drift acceptable; T-72-06-06).
183
+ * - `false` when at least one row's pid is gone AND discovery does not
184
+ * surface a process with matching cmd.
185
+ * - `null` when the env adapter is unable to evaluate (win32 degraded
186
+ * platform per T-72-06-09, or malformed payload — caller's runDeferredActionProbe
187
+ * converts null to `status: "pending"` with a documented reason).
188
+ *
189
+ * The probe never throws — every error mode collapses into a defined return
190
+ * value so the advisory layer cannot crash on a misbehaving adapter.
191
+ *
192
+ * T-72-06-03: each invocation reads fresh discovery results via the env
193
+ * adapter; nothing cached crosses call boundaries.
194
+ */
195
+ export declare function buildProcessRestartProbeFromSnapshot(env: GdhProcessOrchestrationEnvironment): (payload: Record<string, unknown>) => Promise<boolean | null>;
196
+ /**
197
+ * Default production-safe `GdhProcessOrchestrationEnvironment` factory.
198
+ *
199
+ * Returns a minimal environment that:
200
+ * - reports `process.platform` reduced to the closed enum
201
+ * - returns `() => new Date().toISOString()` for nowIso
202
+ * - returns empty discovery (no MCP processes / no broker) — production
203
+ * callers (Plan 13-02 self-update.ts) wire a richer factory backed by
204
+ * `cleanupGdhMcpProcessesWithEnvironment` + `inspectRuntimeBridgeBroker`
205
+ * + `pruneRuntimeBridgeBroker` + `ensureRuntimeBridgeBroker` from
206
+ * `@gdh/runtime`. The default factory exists so `bumpAndRebakePin`
207
+ * callers that omit the optional adapter still get a working
208
+ * no-orchestration flow (Test 1 and Test 2 of Plan 72-08 Task 08-02
209
+ * happy paths exercise this default with empty discovery).
210
+ * - uses `process.kill(pid, 'SIGTERM')` and `process.kill(pid, 'SIGKILL')`
211
+ * for kill primitives; `process.kill(pid, 0)` for liveness probe
212
+ * - no-ops `pruneBroker` and `ensureBroker` (production callers wire
213
+ * the real broker primitives)
214
+ * - no-ops `spawnProcess` (production callers wire `child_process.spawn`)
215
+ *
216
+ * The defaults are conservative — when discovery returns empty, every
217
+ * downstream stop/restart loop is a no-op and `bumpAndRebakePin`'s 12-step
218
+ * flow still completes cleanly. Production wiring layers richer adapters on
219
+ * top of this default; tests inject a fully-stubbed environment via the
220
+ * optional `processOrchestrationEnvironment` parameter to bumpAndRebakePin.
221
+ */
222
+ export declare function defaultProcessOrchestrationEnvironment(): GdhProcessOrchestrationEnvironment;
223
+ //# sourceMappingURL=process-orchestration.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"process-orchestration.d.ts","sourceRoot":"","sources":["../src/process-orchestration.ts"],"names":[],"mappings":"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"}