@bitkyc08/opencodex 2.94.0 → 2.95.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 (249) hide show
  1. package/gui/dist/assets/App-8yedBkhm.js +58 -0
  2. package/gui/dist/assets/App-B4j-Txmb.css +1 -0
  3. package/gui/dist/assets/{Tray-CZatQdoF.js → Tray-erSMzxPG.js} +1 -1
  4. package/gui/dist/assets/index-D7DCm5eQ.js +94 -0
  5. package/gui/dist/assets/quota-summary-BK4VuQNc.js +1 -0
  6. package/gui/dist/index.html +1 -1
  7. package/package.json +1 -1
  8. package/src/adapters/anthropic.ts +10 -3
  9. package/src/adapters/command-code-project-context.ts +3 -3
  10. package/src/adapters/kiro/adapter.ts +4 -1
  11. package/src/adapters/kiro/stream.ts +1 -0
  12. package/src/adapters/kiro-events.ts +1 -0
  13. package/src/adapters/openai-chat/messages.ts +20 -7
  14. package/src/adapters/openai-chat/passthrough.ts +4 -2
  15. package/src/adapters/openai-chat/single-system.ts +24 -0
  16. package/src/adapters/openai-responses/muse-tool-catalog.ts +87 -0
  17. package/src/adapters/openai-responses/passthrough.ts +42 -7
  18. package/src/adapters/openai-responses/prompt-cache.ts +3 -1
  19. package/src/adapters/openai-responses/request-strips.ts +23 -4
  20. package/src/adapters/openai-responses/tool-output-recovery.ts +21 -8
  21. package/src/adapters/openai-responses/tool-schema.ts +20 -8
  22. package/src/adapters/opencode-go-additional-tools.ts +39 -6
  23. package/src/adapters/routed-agent-messages.ts +3 -0
  24. package/src/adapters/xai-web-search.ts +6 -3
  25. package/src/adapters/zed-additional-tools.ts +7 -7
  26. package/src/adapters/zed.ts +1 -6
  27. package/src/advisor/consult.ts +22 -10
  28. package/src/advisor/runtime.ts +10 -4
  29. package/src/bridge/max-output-completion.ts +41 -0
  30. package/src/bridge/response-json.ts +9 -4
  31. package/src/bridge/sse.ts +13 -2
  32. package/src/chatgpt/app-server-shim/bundle-trust-policy.ts +5 -0
  33. package/src/chatgpt/app-server-shim/launcher.ts +40 -6
  34. package/src/claude/compatibility.ts +5 -1
  35. package/src/claude/desktop-3p.ts +27 -6
  36. package/src/claude/desktop-model-visibility.ts +141 -0
  37. package/src/claude/desktop-remote-store-io.ts +8 -8
  38. package/src/claude/inbound-content-options.ts +11 -1
  39. package/src/claude/intercept/proxy-auth.ts +16 -16
  40. package/src/cli/account-main.ts +3 -2
  41. package/src/cli/capabilities-provider-models.ts +7 -0
  42. package/src/cli/chatgpt-command.ts +1 -1
  43. package/src/cli/codex-launcher.ts +20 -8
  44. package/src/cli/codex-shim-autorestore.ts +19 -1
  45. package/src/cli/dispatch.ts +6 -6
  46. package/src/cli/doctor.ts +5 -5
  47. package/src/cli/index.ts +4 -9
  48. package/src/cli/init.ts +2 -2
  49. package/src/cli/internal-command.ts +29 -2
  50. package/src/cli/provider-cc-switch-import.ts +185 -0
  51. package/src/cli/provider.ts +5 -0
  52. package/src/cli/registry.ts +1 -0
  53. package/src/cli/restart-scope.ts +2 -2
  54. package/src/cli/root.ts +6 -6
  55. package/src/cli/stop-approval.ts +15 -1
  56. package/src/cli/v2.ts +69 -19
  57. package/src/client/machine-api.ts +2 -2
  58. package/src/clients/config-export.ts +14 -3
  59. package/src/codex/account-cooldown-response.ts +18 -0
  60. package/src/codex/app-server-restart-service.ts +2 -2
  61. package/src/codex/auth-api/login-flow.ts +2 -2
  62. package/src/codex/auth-api/pool-quota-probe.ts +2 -2
  63. package/src/codex/auth-context.ts +4 -4
  64. package/src/codex/catalog/bundled.ts +10 -3
  65. package/src/codex/catalog/metadata.ts +4 -5
  66. package/src/codex/catalog/native-omission.ts +28 -0
  67. package/src/codex/catalog/native-template.ts +58 -0
  68. package/src/codex/catalog/parsing.ts +3 -29
  69. package/src/codex/catalog/provider-models.ts +2 -1
  70. package/src/codex/catalog/retained-sync.ts +15 -5
  71. package/src/codex/catalog/write-audit.ts +18 -18
  72. package/src/codex/cli-install-provenance.ts +46 -45
  73. package/src/codex/cli-update-artifacts.ts +8 -6
  74. package/src/codex/cli-update-job-store-windows.ts +99 -27
  75. package/src/codex/cli-update-job-worker.ts +3 -11
  76. package/src/codex/cli-update-recovery.ts +54 -8
  77. package/src/codex/cli-update-selection-gate.ts +74 -4
  78. package/src/codex/cli-windows-plan-provenance.ts +37 -19
  79. package/src/codex/codex-home-owner.ts +9 -8
  80. package/src/codex/convergence.ts +13 -3
  81. package/src/codex/coordinator-doctor.ts +14 -8
  82. package/src/codex/desktop-app/handoff.ts +1 -1
  83. package/src/codex/desktop-app-restart.ts +11 -1
  84. package/src/codex/exec-boundary.ts +26 -5
  85. package/src/codex/history-provider.ts +11 -10
  86. package/src/codex/inject/bounded-config-reader.ts +14 -13
  87. package/src/codex/main-account.ts +6 -6
  88. package/src/codex/native-main-lock-file.ts +13 -12
  89. package/src/codex/native-residue.ts +18 -14
  90. package/src/codex/orca-auth-source.ts +8 -7
  91. package/src/codex/quota-types.ts +5 -0
  92. package/src/codex/quota.ts +49 -7
  93. package/src/codex/role-auto-assign.ts +50 -26
  94. package/src/codex/role-capability.ts +160 -0
  95. package/src/codex/role-sizing.ts +24 -6
  96. package/src/codex/routing/cooldown-math.ts +3 -2
  97. package/src/codex/runtime.ts +43 -3
  98. package/src/codex/shim-fingerprint.ts +11 -9
  99. package/src/codex/shim-inspect.ts +3 -2
  100. package/src/codex/shim-restore-lock.ts +11 -14
  101. package/src/codex/shim-state-file.ts +22 -14
  102. package/src/codex/shim-wrapper-write.ts +7 -6
  103. package/src/codex/shim.ts +25 -2
  104. package/src/codex/transition-state.ts +5 -4
  105. package/src/combos/failover.ts +43 -4
  106. package/src/config/atomic-write.ts +38 -7
  107. package/src/config/diagnostics.ts +3 -0
  108. package/src/config/initialize.ts +6 -6
  109. package/src/config/load-degrade.ts +2 -0
  110. package/src/config/process-state.ts +23 -5
  111. package/src/config/salvage.ts +1 -0
  112. package/src/config/schema/config-schema.ts +29 -1
  113. package/src/config/schema/leaf-validators.ts +7 -0
  114. package/src/config/schema/workflow-budget.ts +43 -0
  115. package/src/config/tracked-runtime-inspection.ts +188 -0
  116. package/src/generated/compatibility-version.json +313 -213
  117. package/src/integrations/aside-profile-context.ts +1 -1
  118. package/src/integrations/droid-settings.ts +4 -4
  119. package/src/integrations/hermes-profiles.ts +3 -3
  120. package/src/lib/bounded-file-read.ts +3 -9
  121. package/src/lib/bun-runtime-preflight.ts +9 -8
  122. package/src/lib/file-identity.ts +15 -0
  123. package/src/lib/local-chat-completion.ts +8 -6
  124. package/src/lib/local-destinations.ts +32 -3
  125. package/src/lib/redact-folding.ts +9 -0
  126. package/src/lib/spend-pool-alias-validation.ts +6 -6
  127. package/src/lib/state-store-registrations.ts +2 -0
  128. package/src/lib/test-home-guard.ts +37 -9
  129. package/src/lib/windows-secret-acl.ts +47 -29
  130. package/src/lib/workflow-budget-config.ts +39 -0
  131. package/src/local-credentials/generation.ts +6 -2
  132. package/src/local-credentials/inventory.ts +132 -8
  133. package/src/messaging/remote-forward-failure.ts +35 -0
  134. package/src/messaging/remote-ports.ts +27 -5
  135. package/src/messaging/remote-process.ts +30 -4
  136. package/src/messaging/remote-tunnels.ts +80 -15
  137. package/src/oauth/antigravity-discovery-diagnostics.ts +65 -0
  138. package/src/oauth/google-antigravity.ts +23 -10
  139. package/src/oauth/index.ts +2 -0
  140. package/src/oauth/kiro-device-login.ts +87 -30
  141. package/src/oauth/kiro-iam-identity-center.ts +107 -0
  142. package/src/oauth/store.ts +9 -7
  143. package/src/providers/account-quota-disk.ts +18 -4
  144. package/src/providers/cc-switch-import-bytes.ts +991 -0
  145. package/src/providers/cc-switch-import-source.ts +1083 -0
  146. package/src/providers/cc-switch-import.ts +942 -0
  147. package/src/providers/derive.ts +6 -0
  148. package/src/providers/model-discovery-diagnostic.ts +4 -0
  149. package/src/providers/model-discovery.ts +4 -4
  150. package/src/providers/model-rename-fields.ts +2 -0
  151. package/src/providers/model-rename-migration.ts +41 -6
  152. package/src/providers/quota/report-cache.ts +17 -4
  153. package/src/providers/quota.ts +2 -2
  154. package/src/providers/reasoning-metadata.ts +31 -15
  155. package/src/providers/registry/entries-core.ts +1 -1
  156. package/src/providers/registry/entries-extended.ts +1 -1
  157. package/src/providers/registry/model-ids.ts +1 -0
  158. package/src/providers/registry/model-seeds.ts +2 -1
  159. package/src/providers/registry/types.ts +3 -1
  160. package/src/providers/resolved-model-policy.ts +2 -2
  161. package/src/providers/routed-config.ts +2 -0
  162. package/src/providers/stale-model-roster-migration.ts +5 -1
  163. package/src/providers/xai-transport.ts +4 -4
  164. package/src/remote-control/workspace-codex-runtime.ts +2 -2
  165. package/src/remote-control/workspace-executor.ts +14 -13
  166. package/src/responses/custom-tool-compat.ts +2 -1
  167. package/src/responses/item-provenance.ts +79 -0
  168. package/src/responses/namespace-tool-compat.ts +21 -3
  169. package/src/router.ts +21 -2
  170. package/src/routing/analytics.ts +3 -5
  171. package/src/routing/fallback-policy.ts +7 -3
  172. package/src/routing/health.ts +5 -3
  173. package/src/routing/history/build-file.ts +6 -0
  174. package/src/routing/history/indexer.ts +158 -31
  175. package/src/routing/history/ingest.ts +1 -1
  176. package/src/routing/history/integrity.ts +208 -0
  177. package/src/routing/history/rebuild-job.ts +20 -6
  178. package/src/routing/history/rebuild-protocol.ts +2 -1
  179. package/src/routing/history/rebuild-worker.ts +18 -0
  180. package/src/routing/history/sqlite-errors.ts +9 -0
  181. package/src/server/admission-model-scope.ts +21 -4
  182. package/src/server/advisor-admission-scope.ts +29 -0
  183. package/src/server/auth-cors.ts +5 -2
  184. package/src/server/capture-admission-policy.ts +91 -0
  185. package/src/server/chat-completions.ts +33 -7
  186. package/src/server/claude-messages.ts +90 -2
  187. package/src/server/codex-model-list.ts +2 -1
  188. package/src/server/configured-credentials.ts +5 -0
  189. package/src/server/index/serve-options.ts +12 -2
  190. package/src/server/index/websocket-handler.ts +3 -0
  191. package/src/server/management/agent-settings-routes.ts +34 -9
  192. package/src/server/management/codex-agent-role-routes.ts +1 -0
  193. package/src/server/management/codex-role-auto-assign.ts +50 -6
  194. package/src/server/management/config-routes.ts +15 -4
  195. package/src/server/management/context.ts +3 -0
  196. package/src/server/management/native-integration-routes.ts +22 -0
  197. package/src/server/management/oauth-account-routes.ts +20 -4
  198. package/src/server/management/provider-overwrite-carry.ts +21 -0
  199. package/src/server/management/provider-routes.ts +3 -1
  200. package/src/server/management/route-registry.ts +2 -0
  201. package/src/server/management/shared.ts +17 -1
  202. package/src/server/management/workflow-budget-routes.ts +70 -3
  203. package/src/server/messages-native-eligibility.ts +6 -5
  204. package/src/server/messages-native-scope.ts +6 -1
  205. package/src/server/messages-shared.ts +57 -17
  206. package/src/server/persistent-gui-session.ts +4 -4
  207. package/src/server/request-log.ts +30 -2
  208. package/src/server/responses/adapter-delivery.ts +4 -0
  209. package/src/server/responses/advisor-plan-slot.ts +4 -0
  210. package/src/server/responses/advisor-slot.ts +73 -46
  211. package/src/server/responses/codex-auth-error.ts +5 -1
  212. package/src/server/responses/combo-required-tool-contract.ts +27 -0
  213. package/src/server/responses/compact.ts +4 -1
  214. package/src/server/responses/core-combo-failure.ts +2 -0
  215. package/src/server/responses/core-combo.ts +66 -5
  216. package/src/server/responses/core-lifetime.ts +4 -0
  217. package/src/server/responses/core-options.ts +9 -0
  218. package/src/server/responses/core.ts +2 -0
  219. package/src/server/responses/jev-model-invoke.ts +4 -2
  220. package/src/server/responses/passthrough-dispatch.ts +5 -4
  221. package/src/server/responses/policy-fallback.ts +2 -0
  222. package/src/server/responses/request-prepare.ts +4 -5
  223. package/src/server/responses/request-send-budget.ts +2 -1
  224. package/src/server/responses/request-sidecar-auth.ts +1 -0
  225. package/src/server/responses/request-transport.ts +2 -3
  226. package/src/server/responses/run-turn-execution.ts +4 -0
  227. package/src/server/responses/sidecar-execution.ts +21 -5
  228. package/src/server/responses-snapshot-repair.ts +18 -4
  229. package/src/server/responses-undeclared-tool-guard.ts +4 -0
  230. package/src/server/workflow-refusal.ts +2 -1
  231. package/src/service/state-lock.ts +12 -11
  232. package/src/service-manager-probe.ts +53 -8
  233. package/src/types/admission-policy.ts +13 -0
  234. package/src/types/config.ts +25 -0
  235. package/src/types/provider.ts +10 -0
  236. package/src/types/request.ts +7 -0
  237. package/src/types.ts +1 -0
  238. package/src/update/job.ts +20 -0
  239. package/src/update/worker-launch.ts +71 -1
  240. package/src/usage/log.ts +25 -4
  241. package/src/vision/index.ts +2 -0
  242. package/src/vision/plan.ts +4 -0
  243. package/src/vision/routed-describe.ts +38 -23
  244. package/src/web-search/loop.ts +104 -9
  245. package/src/web-search/parse.ts +10 -2
  246. package/gui/dist/assets/App-DMps4OLk.css +0 -1
  247. package/gui/dist/assets/App-DmvwlhQq.js +0 -58
  248. package/gui/dist/assets/index-3EPO_KbX.js +0 -94
  249. package/gui/dist/assets/quota-summary-BHvWg9mi.js +0 -1
@@ -0,0 +1,188 @@
1
+ /**
2
+ * Read-only classification of the tracked runtime record pair a guarded stop
3
+ * re-verifies before acting.
4
+ *
5
+ * "ocx stop --expect-*" asks "is the recorded runtime still the approved one",
6
+ * which collapses several observations into one boolean: a missing or invalid
7
+ * "ocx.pid", a dead, foreign or unverifiable recorded process, and a missing,
8
+ * invalid or PID-mismatched "runtime-port.json" all read as "not verified".
9
+ * The approval-changed refusal used to report only that umbrella fact, so a
10
+ * desktop log could not tell a stale record from a permission failure.
11
+ *
12
+ * This probe walks the same checks in the same order as "readPid()" followed
13
+ * by "readRuntimePort(pid)", but reports which one failed instead. Each state
14
+ * record is still read exactly once per call -- a guarded stop asks once, and
15
+ * caching the bytes would only carry a stale answer into a decision about a
16
+ * record that may have been rewritten. The process-identity question, though,
17
+ * is answered by the same cache-backed observation "readPid()" itself makes
18
+ * ("inspectOcxStartProcessIdentity"): a cached verdict serves this probe with
19
+ * no native command at all, and a miss performs the same single command-line
20
+ * probe readPid would, so this probe can never disagree with the admission
21
+ * readPid just granted or denied for the same PID. It performs no mutation, no
22
+ * signal beyond the same "process.kill(pid, 0)" liveness read, and no stop
23
+ * decision -- the refusal itself is unchanged; only its detail gains a cause.
24
+ *
25
+ * Two distinctions are deliberate:
26
+ *
27
+ * - "permission-denied" is reported only for a real EACCES/EPERM observed on a
28
+ * record read or the liveness signal. An "unverifiable" identity observation
29
+ * -- an unreadable process command line -- is not proof of a permission
30
+ * boundary, and no account or elevation cause is inferred from it.
31
+ * - No path, command line, stderr text, or token leaves this module: the refusal
32
+ * causes below are fixed strings and the detail built from them is a fixed
33
+ * sentence.
34
+ */
35
+ import { readFileSync } from "node:fs";
36
+ import {
37
+ getPidPath,
38
+ getRuntimePortPath,
39
+ inspectOcxStartProcessIdentity,
40
+ isValidRuntimePortState,
41
+ parsePidFile,
42
+ } from "./process-state";
43
+ import type { OcxStartIdentityObservation } from "./process-state";
44
+
45
+ /** The single check that failed, as a stable machine-readable token. */
46
+ export type TrackedRecordRefusal =
47
+ | "pid-record-absent"
48
+ | "pid-record-permission-denied"
49
+ | "pid-record-unreadable"
50
+ | "pid-record-invalid"
51
+ | "process-not-running"
52
+ | "process-identity-mismatch"
53
+ | "process-unverifiable"
54
+ | "runtime-record-absent"
55
+ | "runtime-record-permission-denied"
56
+ | "runtime-record-unreadable"
57
+ | "runtime-record-invalid"
58
+ | "runtime-record-pid-mismatch"
59
+ | "unverified";
60
+
61
+ export type TrackedRecordInspection =
62
+ | { status: "verified"; pid: number; port: number; hostname: string }
63
+ | { status: "refused"; reason: TrackedRecordRefusal };
64
+
65
+ /**
66
+ * Injectable read-only seams. Tests must supply fakes for "signal" and either
67
+ * "identity" or the process-state exec seams ("setProcessCommandLineExecForTests"
68
+ * and friends) so no real "process.kill" or native command probe runs; the
69
+ * defaults are exactly what the production caller uses, including the shared
70
+ * identity cache.
71
+ */
72
+ export interface TrackedRecordProbeDeps {
73
+ /** Read a state record like "readFileSync(path, 'utf-8')"; throw with errno codes. */
74
+ readFile?: (path: string) => string;
75
+ /** The "process.kill(pid, 0)" liveness read; throws like it (ESRCH/EPERM/...). */
76
+ signal?: (pid: number) => void;
77
+ /** The shared start-identity observation; the default consults the real cache. */
78
+ identity?: (pid: number) => OcxStartIdentityObservation;
79
+ }
80
+
81
+ function readRecordFile(
82
+ readFile: (path: string) => string,
83
+ path: string,
84
+ absent: TrackedRecordRefusal,
85
+ denied: TrackedRecordRefusal,
86
+ unreadable: TrackedRecordRefusal,
87
+ ): { ok: true; raw: string } | { ok: false; reason: TrackedRecordRefusal } {
88
+ try {
89
+ return { ok: true, raw: readFile(path) };
90
+ } catch (error) {
91
+ const code = (error as NodeJS.ErrnoException).code;
92
+ if (code === "EACCES" || code === "EPERM") return { ok: false, reason: denied };
93
+ if (code === "ENOENT") return { ok: false, reason: absent };
94
+ return { ok: false, reason: unreadable };
95
+ }
96
+ }
97
+
98
+ /**
99
+ * Classify why the tracked runtime record cannot back a guarded stop, or return
100
+ * the verified target when every check still holds. One read per record, in the
101
+ * same order the stop path already performs them.
102
+ */
103
+ export function inspectTrackedRuntimeRecord(
104
+ deps: TrackedRecordProbeDeps = {},
105
+ ): TrackedRecordInspection {
106
+ const readFile = deps.readFile ?? ((path: string) => readFileSync(path, "utf-8"));
107
+ const signal = deps.signal ?? ((pid: number) => { process.kill(pid, 0); });
108
+ const identity = deps.identity ?? inspectOcxStartProcessIdentity;
109
+ try {
110
+ const pidFile = readRecordFile(
111
+ readFile, getPidPath(), "pid-record-absent", "pid-record-permission-denied", "pid-record-unreadable",
112
+ );
113
+ if (!pidFile.ok) return { status: "refused", reason: pidFile.reason };
114
+ const pid = parsePidFile(pidFile.raw);
115
+ if (pid === null) return { status: "refused", reason: "pid-record-invalid" };
116
+ try {
117
+ signal(pid);
118
+ } catch (error) {
119
+ const code = (error as NodeJS.ErrnoException).code;
120
+ if (code === "ESRCH") return { status: "refused", reason: "process-not-running" };
121
+ // EPERM still names a live process; identity is decided by the shared
122
+ // observation below, exactly as readPid decides it. Any other signal
123
+ // error can only be reported as unverifiable.
124
+ if (code !== "EPERM") return { status: "refused", reason: "process-unverifiable" };
125
+ }
126
+ const observation = identity(pid);
127
+ if (observation === "unverifiable") {
128
+ return { status: "refused", reason: "process-unverifiable" };
129
+ }
130
+ if (observation === "mismatch") {
131
+ return { status: "refused", reason: "process-identity-mismatch" };
132
+ }
133
+ const runtimeFile = readRecordFile(
134
+ readFile, getRuntimePortPath(),
135
+ "runtime-record-absent", "runtime-record-permission-denied", "runtime-record-unreadable",
136
+ );
137
+ if (!runtimeFile.ok) return { status: "refused", reason: runtimeFile.reason };
138
+ let parsed: unknown;
139
+ try {
140
+ parsed = JSON.parse(runtimeFile.raw);
141
+ } catch {
142
+ return { status: "refused", reason: "runtime-record-invalid" };
143
+ }
144
+ if (!isValidRuntimePortState(parsed)) {
145
+ return { status: "refused", reason: "runtime-record-invalid" };
146
+ }
147
+ if (parsed.pid !== pid) {
148
+ return { status: "refused", reason: "runtime-record-pid-mismatch" };
149
+ }
150
+ return { status: "verified", pid, port: parsed.port, hostname: parsed.hostname ?? "" };
151
+ } catch {
152
+ return { status: "refused", reason: "unverified" };
153
+ }
154
+ }
155
+
156
+ /**
157
+ * Fixed refusal causes for the approval-changed detail. Every entry is a
158
+ * complete sentence fragment and contains no path, command line, stderr, or
159
+ * token, so the resulting detail is safe to surface in a caller's log or UI.
160
+ */
161
+ const TRACKED_REFUSAL_CAUSES: Record<TrackedRecordRefusal, string> = {
162
+ "pid-record-absent": "the recorded PID file is absent",
163
+ "pid-record-permission-denied": "reading the recorded PID file was denied",
164
+ "pid-record-unreadable": "the recorded PID file could not be read",
165
+ "pid-record-invalid": "the recorded PID file is not a valid record",
166
+ "process-not-running": "the recorded process is no longer running",
167
+ "process-identity-mismatch": "the recorded process does not match the expected start command",
168
+ "process-unverifiable": "the recorded process identity could not be verified",
169
+ "runtime-record-absent": "the tracked runtime record is absent",
170
+ "runtime-record-permission-denied": "reading the tracked runtime record was denied",
171
+ "runtime-record-unreadable": "the tracked runtime record could not be read",
172
+ "runtime-record-invalid": "the tracked runtime record is not a valid record",
173
+ "runtime-record-pid-mismatch": "the tracked runtime record names a different PID",
174
+ "unverified": "the tracked runtime record could not be re-verified",
175
+ };
176
+
177
+ /**
178
+ * The guarded stop's tracked() callback shape: the verified target, or the
179
+ * fixed cause of the single check that failed. Read-only; decides nothing.
180
+ */
181
+ export function describeTrackedRuntimeTarget(
182
+ deps: TrackedRecordProbeDeps = {},
183
+ ): { pid: number; port: number; hostname: string } | { untracked: string } {
184
+ const inspection = inspectTrackedRuntimeRecord(deps);
185
+ return inspection.status === "verified"
186
+ ? { pid: inspection.pid, port: inspection.port, hostname: inspection.hostname }
187
+ : { untracked: TRACKED_REFUSAL_CAUSES[inspection.reason] };
188
+ }