peaks-loop 4.1.17 → 4.1.19

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 (205) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +269 -0
  3. package/README-en.md +6 -0
  4. package/README.md +5 -0
  5. package/contracts/test-style-contract.md +14 -5
  6. package/dist/cli/commands/audit-red-lines-runners.js +6 -1
  7. package/dist/cli/commands/best-practice-scan-collision.d.ts +42 -0
  8. package/dist/cli/commands/best-practice-scan-collision.js +115 -0
  9. package/dist/cli/commands/best-practice-scan-command.d.ts +5 -0
  10. package/dist/cli/commands/best-practice-scan-command.js +9 -18
  11. package/dist/cli/commands/best-practice-scan-helpers.d.ts +12 -6
  12. package/dist/cli/commands/best-practice-scan-helpers.js +37 -17
  13. package/dist/cli/commands/code-auto-compact-command.js +71 -40
  14. package/dist/cli/commands/code-auto-compact-deferral.d.ts +34 -0
  15. package/dist/cli/commands/code-auto-compact-deferral.js +59 -0
  16. package/dist/cli/commands/code-gate-command.d.ts +4 -4
  17. package/dist/cli/commands/code-gate-command.js +4 -4
  18. package/dist/cli/commands/core/skill-generated-config-notice.d.ts +5 -0
  19. package/dist/cli/commands/core/skill-generated-config-notice.js +42 -8
  20. package/dist/cli/commands/core/skill-presence-commands.js +42 -74
  21. package/dist/cli/commands/core/skill-presence-set-command.d.ts +11 -0
  22. package/dist/cli/commands/core/skill-presence-set-command.js +175 -0
  23. package/dist/cli/commands/core/skill-registry-commands.js +32 -0
  24. package/dist/cli/commands/core/skill-store-report.d.ts +8 -0
  25. package/dist/cli/commands/core/skill-store-report.js +79 -0
  26. package/dist/cli/commands/core/standards-init-command.js +44 -8
  27. package/dist/cli/commands/core/standards-migrate-command.js +5 -4
  28. package/dist/cli/commands/dispatch-dag-runners.d.ts +1 -0
  29. package/dist/cli/commands/dispatch-dag-runners.js +11 -1
  30. package/dist/cli/commands/dispatch-detached-branch.js +19 -1
  31. package/dist/cli/commands/dispatch-prompt-composition.js +7 -2
  32. package/dist/cli/commands/dispatch-scratch-path-block.d.ts +73 -0
  33. package/dist/cli/commands/dispatch-scratch-path-block.js +131 -0
  34. package/dist/cli/commands/hooks-commands.js +36 -7
  35. package/dist/cli/commands/hooks-uninstall-command.js +5 -5
  36. package/dist/cli/commands/mut-commands-helpers.d.ts +72 -5
  37. package/dist/cli/commands/mut-commands-helpers.js +197 -4
  38. package/dist/cli/commands/mut-commands.d.ts +9 -1
  39. package/dist/cli/commands/mut-commands.js +82 -154
  40. package/dist/cli/commands/preferences-commands.js +27 -2
  41. package/dist/cli/commands/scan-scope-helpers.js +2 -2
  42. package/dist/services/24h-mode/auto-engage.d.ts +11 -3
  43. package/dist/services/24h-mode/auto-engage.js +14 -6
  44. package/dist/services/artifacts/artifact-templates.js +10 -0
  45. package/dist/services/artifacts/backcompat-acceptance.d.ts +8 -1
  46. package/dist/services/artifacts/backcompat-acceptance.js +8 -7
  47. package/dist/services/artifacts/rd-transition-gates.d.ts +32 -5
  48. package/dist/services/artifacts/rd-transition-gates.js +96 -19
  49. package/dist/services/artifacts/request-artifact-service.js +6 -6
  50. package/dist/services/audit/enforcers/lint-output-style.js +14 -2
  51. package/dist/services/audit/enforcers/root-scratch-artifacts.d.ts +46 -0
  52. package/dist/services/audit/enforcers/root-scratch-artifacts.js +97 -0
  53. package/dist/services/audit/static-service.js +4 -4
  54. package/dist/services/code/auto-compact-history.d.ts +6 -1
  55. package/dist/services/code/auto-compact-history.js +6 -1
  56. package/dist/services/code/auto-compact-modes.d.ts +60 -14
  57. package/dist/services/code/auto-compact-modes.js +75 -20
  58. package/dist/services/code/auto-compact-orchestrator.js +7 -5
  59. package/dist/services/code/auto-compact-profile.d.ts +23 -0
  60. package/dist/services/code/auto-compact-profile.js +51 -0
  61. package/dist/services/code/auto-compact-run-types.d.ts +8 -4
  62. package/dist/services/compact-history/compact-history-service.d.ts +6 -1
  63. package/dist/services/compact-history/compact-history-service.js +5 -1
  64. package/dist/services/context/auto-compact-types.d.ts +7 -5
  65. package/dist/services/dispatch/dispatch-ledger-reader.d.ts +13 -0
  66. package/dist/services/dispatch/dispatch-ledger-reader.js +164 -0
  67. package/dist/services/doctor/doctor-service/checks/canonical-store-version.d.ts +57 -0
  68. package/dist/services/doctor/doctor-service/checks/canonical-store-version.js +190 -0
  69. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.d.ts +37 -0
  70. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.js +100 -0
  71. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +11 -3
  72. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +48 -29
  73. package/dist/services/doctor/doctor-service/plugin-registry.js +4 -0
  74. package/dist/services/doctor/doctor-service/types.d.ts +12 -0
  75. package/dist/services/hooks/hook-payload-cwd.d.ts +11 -4
  76. package/dist/services/hooks/hook-payload-cwd.js +11 -4
  77. package/dist/services/hooks/pre-tool-code-gate.d.ts +4 -4
  78. package/dist/services/hooks/pre-tool-code-gate.js +4 -4
  79. package/dist/services/hooks/presence-marker-detector.d.ts +3 -0
  80. package/dist/services/hooks/presence-marker-detector.js +21 -19
  81. package/dist/services/ide/adapters/claude-code-adapter.js +6 -8
  82. package/dist/services/ide/adapters/codex-adapter.js +23 -7
  83. package/dist/services/ide/adapters/cursor-adapter.js +23 -7
  84. package/dist/services/mode/mode-status-service.d.ts +26 -27
  85. package/dist/services/mode/mode-status-service.js +36 -60
  86. package/dist/services/preferences/preferences-types.d.ts +30 -0
  87. package/dist/services/preferences/preferences-types.js +13 -0
  88. package/dist/services/scan/acceptance-coverage-service.d.ts +14 -11
  89. package/dist/services/scan/acceptance-coverage-service.js +157 -52
  90. package/dist/services/scan/rid-change-claims.d.ts +15 -0
  91. package/dist/services/scan/rid-change-claims.js +116 -0
  92. package/dist/services/session/getSessionDir.d.ts +13 -0
  93. package/dist/services/session/getSessionDir.js +7 -1
  94. package/dist/services/skills/hooks-settings-types.d.ts +17 -21
  95. package/dist/services/skills/presence-caller-id.d.ts +51 -0
  96. package/dist/services/skills/presence-caller-id.js +43 -0
  97. package/dist/services/skills/presence-gate.d.ts +65 -0
  98. package/dist/services/skills/presence-gate.js +113 -0
  99. package/dist/services/skills/presence-lease-resolver.d.ts +63 -0
  100. package/dist/services/skills/presence-lease-resolver.js +114 -0
  101. package/dist/services/skills/presence-lease-selection.d.ts +91 -0
  102. package/dist/services/skills/presence-lease-selection.js +135 -0
  103. package/dist/services/skills/presence-lease-service.d.ts +3 -11
  104. package/dist/services/skills/presence-lease-service.js +34 -87
  105. package/dist/services/skills/presence-lease-store.d.ts +33 -0
  106. package/dist/services/skills/presence-lease-store.js +94 -0
  107. package/dist/services/skills/presence-lease-types.d.ts +31 -0
  108. package/dist/services/skills/presence-lease-types.js +27 -0
  109. package/dist/services/skills/presence-role.d.ts +35 -0
  110. package/dist/services/skills/presence-role.js +72 -0
  111. package/dist/services/skills/skill-presence-service.d.ts +39 -9
  112. package/dist/services/skills/skill-presence-service.js +143 -174
  113. package/dist/services/skills/skill-presence-write.d.ts +60 -0
  114. package/dist/services/skills/skill-presence-write.js +74 -0
  115. package/dist/services/skills/skill-statusline-service.js +7 -7
  116. package/dist/services/skills/sync-service-support.d.ts +27 -0
  117. package/dist/services/skills/sync-service.js +1 -0
  118. package/dist/services/standards/ide-aware-standards-service.d.ts +35 -23
  119. package/dist/services/standards/ide-aware-standards-service.js +45 -20
  120. package/dist/services/standards/migrate-claude-rules-service.d.ts +6 -0
  121. package/dist/services/standards/migrate-claude-rules-service.js +18 -0
  122. package/dist/services/standards/migrate-service.d.ts +1 -1
  123. package/dist/services/standards/migrate-service.js +27 -7
  124. package/dist/services/standards/project-scripts.d.ts +25 -0
  125. package/dist/services/standards/project-scripts.js +116 -0
  126. package/dist/services/standards/project-standards-service.d.ts +23 -15
  127. package/dist/services/standards/project-standards-service.js +176 -243
  128. package/dist/services/standards/standards-constitution.d.ts +89 -0
  129. package/dist/services/standards/standards-constitution.js +199 -0
  130. package/dist/services/standards/standards-files.d.ts +37 -0
  131. package/dist/services/standards/standards-files.js +138 -0
  132. package/dist/services/standards/standards-pointer.d.ts +73 -0
  133. package/dist/services/standards/standards-pointer.js +98 -0
  134. package/dist/services/standards/standards-render-agents.d.ts +34 -0
  135. package/dist/services/standards/standards-render-agents.js +149 -0
  136. package/dist/services/standards/standards-render-common.d.ts +38 -1
  137. package/dist/services/standards/standards-render-common.js +44 -7
  138. package/dist/services/standards/standards-render.d.ts +1 -3
  139. package/dist/services/standards/standards-render.js +6 -87
  140. package/dist/services/workflow/workflow-graph-ensure.d.ts +77 -0
  141. package/dist/services/workflow/workflow-graph-ensure.js +97 -0
  142. package/dist/services/workflow/workflow-inflight-probe.d.ts +68 -31
  143. package/dist/services/workflow/workflow-inflight-probe.js +163 -75
  144. package/dist/services/workflow/workflow-presence-lifecycle.js +21 -6
  145. package/dist/services/workspace/generated-artifacts-content.d.ts +46 -0
  146. package/dist/services/workspace/generated-artifacts-content.js +167 -0
  147. package/dist/services/workspace/generated-artifacts-stamp.d.ts +36 -13
  148. package/dist/services/workspace/generated-artifacts-stamp.js +37 -15
  149. package/dist/services/workspace/runtime-layout.d.ts +64 -0
  150. package/dist/services/workspace/runtime-layout.js +62 -0
  151. package/output-styles/peaks-skill-swarm.md +18 -2
  152. package/package.json +10 -9
  153. package/schemas/doctor-report.schema.json +1 -1
  154. package/scripts/canonical-store-fs.mjs +112 -0
  155. package/scripts/canonical-store-link.mjs +13 -22
  156. package/scripts/canonical-store-marker.mjs +241 -0
  157. package/scripts/canonical-store.mjs +119 -141
  158. package/scripts/install-skills-bundles.mjs +56 -13
  159. package/scripts/install-skills-fs.mjs +73 -0
  160. package/scripts/install-skills-output-styles.mjs +8 -2
  161. package/scripts/install-skills-report.mjs +19 -0
  162. package/scripts/install-skills.mjs +9 -0
  163. package/skills/bee/peaks-perf-audit/SKILL.md +3 -1
  164. package/skills/bee/peaks-prd/SKILL.md +5 -3
  165. package/skills/bee/peaks-qa/SKILL.md +4 -2
  166. package/skills/bee/peaks-qa/references/qa-skill-presence.md +1 -1
  167. package/skills/bee/peaks-qa/references/qa-standards-preflight.md +3 -1
  168. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  169. package/skills/bee/peaks-rd/SKILL.md +4 -2
  170. package/skills/bee/peaks-rd/references/artifact-and-standards-output.md +1 -1
  171. package/skills/bee/peaks-rd/references/rd-runbook.md +11 -2
  172. package/skills/bee/peaks-rd/references/rd-standards-preflight.md +3 -1
  173. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +24 -5
  174. package/skills/bee/peaks-rd/references/rd-transition-gates.md +49 -5
  175. package/skills/bee/peaks-rd/references/skill-presence-and-title.md +1 -1
  176. package/skills/bee/peaks-reviewer/SKILL.md +3 -1
  177. package/skills/bee/peaks-sc/SKILL.md +4 -2
  178. package/skills/bee/peaks-security-audit/SKILL.md +3 -1
  179. package/skills/bee/peaks-txt/SKILL.md +5 -3
  180. package/skills/bee/peaks-ui/SKILL.md +6 -4
  181. package/skills/peaks-audit/SKILL.md +3 -1
  182. package/skills/peaks-code/SKILL.md +4 -2
  183. package/skills/peaks-code/references/a2a-artifact-mapping.md +3 -3
  184. package/skills/peaks-code/references/completion-handoff.md +1 -1
  185. package/skills/peaks-code/references/local-artifact-workspace.md +10 -11
  186. package/skills/peaks-code/references/micro-cycle.md +2 -2
  187. package/skills/peaks-code/references/mode-selection-with-stale-presence.md +3 -3
  188. package/skills/peaks-code/references/runbook.md +4 -4
  189. package/skills/peaks-code/references/skill-presence-and-title.md +4 -2
  190. package/skills/peaks-code/references/standards-preflight.md +7 -6
  191. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  192. package/skills/peaks-code/references/swarm-dispatch-contract.md +5 -5
  193. package/skills/peaks-code/references/workflow-gates-and-types.md +37 -11
  194. package/skills/peaks-content/SKILL.md +3 -1
  195. package/skills/peaks-doctor/SKILL.md +3 -1
  196. package/skills/peaks-final-review/SKILL.md +3 -1
  197. package/skills/peaks-ide/SKILL.md +3 -1
  198. package/skills/peaks-issue-fix-orchestrator/SKILL.md +5 -3
  199. package/skills/peaks-race-code/SKILL.md +9 -4
  200. package/skills/peaks-resume/SKILL.md +3 -1
  201. package/skills/peaks-slice-decompose/SKILL.md +3 -1
  202. package/skills/peaks-solo/SKILL.md +3 -1
  203. package/skills/peaks-sop/SKILL.md +4 -2
  204. package/skills/peaks-status/SKILL.md +3 -1
  205. package/skills/peaks-test/SKILL.md +3 -1
@@ -1,24 +1,31 @@
1
1
  import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
2
2
  import { dirname, join, resolve } from 'node:path';
3
- import { findProjectRoot } from '../config/config-safety.js';
4
3
  import { tryParseJson } from '../../shared/json-parse.js';
5
4
  import { ensureMemoryBootstrap } from '../memory/project-memory-service.js';
6
5
  import { getSessionId, getSessionMeta } from '../session/session-manager.js';
7
6
  import { SessionIdentitySchema } from '../session/session-file-schema.js';
8
7
  // Slice 4.0.8 compat shim: the canonical write path lives in
9
- // `presence-lease-service.ts`. The legacy shim dynamically imports
10
- // it inside `setSkillPresence` so the cold path of the legacy
11
- // `getSkillPresence` / `checkStalePresence` / `clearStalePresenceOnRotation`
12
- // read paths stays cheap. The static imports below are reserved for
13
- // the migration window and are referenced through the dynamic
14
- // `leaseMod.*` accessor at runtime.
15
- import { listPresenceLeases } from './presence-lease-service.js';
16
- // Re-export the 4.0.8 compat surface so legacy callers
17
- // (`presence-service` consumers in `code-mode-gate-commands.ts`,
18
- // `mode-enforcement.ts`, `code-job-shape-commands.ts`, etc.) keep
19
- // their `setSkillPresence` / `getSkillPresence` / etc. import paths
20
- // while the actual work flows through the canonical lease service.
21
- void null;
8
+ // `presence-lease-service.ts`, and the WRITE ITSELF is owned by
9
+ // `skill-presence-write.ts` — the awaited, fail-closed write. The legacy
10
+ // shim calls it so the cold path of the legacy `getSkillPresence` /
11
+ // `checkStalePresence` / `clearStalePresenceOnRotation` read paths stays
12
+ // cheap: the write module imports the lease service and the caller-id
13
+ // resolver DYNAMICALLY, so a read-only command never pulls the canonical
14
+ // lease and adapter machinery into module load.
15
+ //
16
+ // WHAT MOVED AND WHY. The canonical write used to live here, inside a
17
+ // non-awaited `void (async () => { ... catch {} })()`. That shape made a
18
+ // failed write invisible: the failure was swallowed, and the caller was
19
+ // handed a success-shaped envelope anyway. The write now lives in
20
+ // `skill-presence-write.ts`, where it is awaited and its failure escapes.
21
+ //
22
+ // Slice 4.0.17 (presence cross-session): the cross-session read and
23
+ // the pure SELECTION RULES live in sibling modules (this file is over the
24
+ // repository's 300-line cap, which may only go down).
25
+ import { resolvePresenceLease, resolveProjectRoot } from './presence-lease-resolver.js';
26
+ import { normalizePresenceGate, readPresenceGate } from './presence-gate.js';
27
+ import { presenceRoleTier } from './presence-role.js';
28
+ import { writeCanonicalPresenceLease } from './skill-presence-write.js';
22
29
  export const VALID_SKILL_PRESENCE_MODES = [
23
30
  'full-auto',
24
31
  'assisted',
@@ -76,11 +83,6 @@ function getCurrentOuterSessionId() {
76
83
  // `PRESENCE_FILE_LEGACY` are deleted; readers use `listPresenceLeases`.
77
84
  const SESSION_FILE = join('.peaks', '_runtime', 'session.json');
78
85
  const SESSION_FILE_LEGACY = '.peaks/.session.json';
79
- function resolveProjectRoot(override) {
80
- if (override)
81
- return resolve(override);
82
- return findProjectRoot(process.cwd()) ?? process.cwd();
83
- }
84
86
  /**
85
87
  * Resolve the active peaks session id.
86
88
  *
@@ -130,43 +132,36 @@ export function getCurrentSessionId(projectRootOverride) {
130
132
  }
131
133
  }
132
134
  /**
133
- * Slice 4.0.11 statusline-sid-scoped-lease C: read the canonical
134
- * sid-scoped lease projection and project the freshest in-flight
135
- * lease into the legacy `SkillPresence` shape that the public
136
- * `getSkillPresence` / `checkStalePresence` /
137
- * `clearStalePresenceOnRotation` consumers expect. The projection
138
- * is lossy (the lease does not carry `outerSessionId`; `setAt`
139
- * maps to `startedAt`; `lastHeartbeat` is reused as `lastHeartbeat`).
135
+ * Read the canonical sid-scoped lease projection and project the freshest
136
+ * in-flight lease into the legacy `SkillPresence` shape the public consumers
137
+ * expect. The projection is lossy (the lease does not carry `outerSessionId`;
138
+ * `setAt` maps to `startedAt`; `lastHeartbeat` is reused as `lastHeartbeat`).
140
139
  *
141
- * Returns `null` when the bound session has no in-flight leases
142
- * (`running` or `preparing`); terminalized leases are ignored so
143
- * the read does not resurrect a stale skill on a fresh session.
140
+ * The read spans EVERY session tree of the project and selects the lease that
141
+ * is actually driving peaks; terminalized and stale leases are ignored so
142
+ * the read does not resurrect a stale skill. The `role` tier comes from the
143
+ * lease's skill, so the header's Role cell is read from the tier lists
144
+ * rather than written by the model.
144
145
  */
145
146
  function readSkillPresenceFromLease(projectRootOverride) {
146
- const projectRoot = resolveProjectRoot(projectRootOverride);
147
- const sessionId = getSessionId(projectRoot);
148
- if (sessionId === null)
149
- return null;
150
- const leases = listPresenceLeases(projectRoot, sessionId);
151
- const inFlight = leases.filter((l) => l.status === 'running' || l.status === 'preparing');
152
- if (inFlight.length === 0)
153
- return null;
154
- inFlight.sort((a, b) => b.lastHeartbeat.localeCompare(a.lastHeartbeat));
155
- const lease = inFlight[0];
156
- if (lease === undefined)
147
+ const selection = resolvePresenceLease(resolveProjectRoot(projectRootOverride));
148
+ if (selection === null)
157
149
  return null;
150
+ const lease = selection.lease;
158
151
  // The lease carries `callerId` (the adapter / harness session id),
159
152
  // not the legacy `outerSessionId` field. Project it for back-compat
160
153
  // with `clearStalePresenceOnRotation`'s outer-mismatch check.
161
- //
162
- // silently dropped before, which made `getSkillPresence().mode` always
163
- // undefined and left every `presence.mode` consumer dead). Normalize on
164
- // read so a legacy `'swarm'` lease surfaces as `'full-auto'`.
154
+ // Normalize on read so a legacy `'swarm'` lease surfaces as
155
+ // `'full-auto'`.
165
156
  const leaseMode = normalizeSkillPresenceMode(lease.mode);
157
+ // The gate is the machine fact behind the status header's middle cell.
158
+ const gate = readPresenceGate(lease.gate);
166
159
  return {
167
160
  skill: lease.skill,
168
161
  ...(leaseMode !== undefined ? { mode: leaseMode } : {}),
169
- sessionId,
162
+ ...(gate !== undefined ? { gate } : {}),
163
+ role: presenceRoleTier(lease.skill),
164
+ sessionId: selection.sessionId,
170
165
  outerSessionId: lease.callerId,
171
166
  setAt: lease.startedAt,
172
167
  lastHeartbeat: lease.lastHeartbeat
@@ -196,26 +191,14 @@ function getBoundOuterSessionId(projectRootOverride) {
196
191
  : undefined;
197
192
  }
198
193
  /**
199
- * Snapshot of the previous peaks session's outer session id, read
200
- * straight off the active-skill marker *before* we overwrite it.
201
- * Used to detect "the LLM just opened a fresh outer session" — if
202
- * the previously-recorded outer session id differs from the one we
203
- * are about to stamp, the user probably closed the previous outer
204
- * session and is now driving peaks from a new one.
205
- *
206
- * is `ensureSessionWithRotation`'s job, not this one. The presence
207
- * service still emits the structured `outerSessionMismatch` field on
208
- * the presence envelope (useful for the statusline to render a stale
209
- * marker and for the QA / log consumers to know an outer-session swap
210
- * promise — `peaks-code`'s Step 0 no longer needs to surface an
211
- * AskUserQuestion, because the rotation already fired by the time the
212
- * skill is invoked.
194
+ * The outer session id recorded on the presence that is about to be
195
+ * overwritten. It powers the informational `outerSessionMismatch` field on
196
+ * the presence envelope: when the recorded id differs from the one about to
197
+ * be stamped, the harness probably opened a fresh session.
213
198
  *
214
- * `getPreviousOuterSessionId` keeps its read-side role: it powers the
215
- * informational `outerSessionMismatch` field below and the legacy
216
- * `claudeSessionId` back-compat. Reads from
217
- * `.peaks/_runtime/active-skill.json` first; falls back to the
218
- * legacy `.peaks/.active-skill.json` for one minor release.
199
+ * The value comes from the canonical lease projection
200
+ * (`.peaks/_runtime/<sid>/leases/presence-*.json`). The project-level
201
+ * single-slot marker files were removed in 4.0.11 and are NOT read here.
219
202
  */
220
203
  function getPreviousOuterSessionId(projectRootOverride) {
221
204
  const result = readSkillPresenceFromLease(projectRootOverride);
@@ -229,25 +212,16 @@ function getPreviousOuterSessionId(projectRootOverride) {
229
212
  // ============================================================================
230
213
  // ============================================================================
231
214
  //
232
- // Today's per-project active-skill marker (`.peaks/_runtime/active-skill.json`)
233
- // races when multiple Claude Code windows (or different platforms) drive the
234
- // `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). Two callers
235
- // bound to the same peak session never clobber each other.
236
- //
237
- // The single-file marker is RETAINED for one minor release as read-only
238
- // back-compat (M1, M4). The new write path is `setSkillPresenceForCaller`;
239
- // the legacy `setSkillPresence` is now a thin wrapper that synthesises a
240
- // legacy callerId from `process.env.CLAUDE_CODE_SESSION_ID` (or
241
- // `projectRoot` for the truly-anonymous case) and delegates.
215
+ // The canonical presence write path is the sid-scoped lease
216
+ // (`.peaks/_runtime/<sid>/leases/presence-<callerId>-<workflowId>.json`).
217
+ // The project-level single-slot markers (`.peaks/_runtime/active-skill.json`
218
+ // and the legacy `.peaks/.active-skill.json`) were removed in 4.0.11 and
219
+ // are neither written nor read from here.
242
220
  /**
243
- * Write the per-caller active-skill marker to
244
- * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). Returns
245
- * the written presence with the `callerId` field set.
246
- *
247
- * The caller is responsible for resolving the `callerId` (via
248
- * `resolveCallerId` from `src/services/session/resolve-caller-id.ts`)
249
- * and the `peakSessionId` (via `getCallerBinding` then reading
250
- * `peakSessionId`, OR via `ensureSession` for the first-time case).
221
+ * Write the LEGACY per-caller marker
222
+ * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). This path
223
+ * was superseded by the sid-scoped lease; it stays for the audit enforcer,
224
+ * which still reads those files. New code calls `setPresenceLease` instead.
251
225
  */
252
226
  export function setSkillPresenceForCaller(projectRootOverride, callerId, peakSessionId, skill, mode, gate) {
253
227
  const validatedMode = normalizeSkillPresenceMode(mode);
@@ -283,26 +257,71 @@ export function setSkillPresenceForCaller(projectRootOverride, callerId, peakSes
283
257
  function getActiveSkillFileForCallerPath(projectRoot, peakSessionId, callerId) {
284
258
  return resolve(projectRoot, '.peaks', '_runtime', peakSessionId, `active-skill-${callerId}.json`);
285
259
  }
286
- export function setSkillPresence(skill, mode, gate, projectRootOverride) {
287
- // Slice 4.0.8 compat wrapper: the canonical write path is
288
- // `presence-lease-service.setPresenceLease`. The legacy
289
- // `setSkillPresence` is retained as a thin shim so callers that
290
- // haven't migrated (statusline consumers, code-mode-gate, the
291
- // dashboard's read-side) keep working. The compat shim:
292
- // 1. resolves the canonical session id (legacy file
293
- // `.peaks/_runtime/session.json` -> canonical
294
- // `.peaks/_runtime/session.json` + caller binding);
295
- // 2. resolves the adapter-owned caller id (PEAKS_CALLER_ID override
296
- // > active IDE adapter); the resolution happens in
297
- // `resolveCallerId`; if it fails we still write a *legacy*
298
- // `SkillPresence` record (so non-4.0.8 callers that expect
299
- // the old shape don't break) but we surface a warning to the
300
- // CLI boundary via the `outerSessionMismatch` field.
301
- // 3. delegates the canonical write to `setPresenceLease`.
260
+ /**
261
+ * Record the informational outer-session mismatch on the presence envelope.
262
+ *
263
+ * It powers the `outerSessionMismatch` field: when the recorded id differs
264
+ * from the one about to be stamped, the harness probably opened a fresh
265
+ * session. The field is INFORMATIONAL — it tells the statusline and any
266
+ * log / observability consumer that an outer-session swap was observed on
267
+ * the previous heartbeat. It does NOT rotate anything: the actual binding
268
+ * rotation is the session layer's business, and by the time the skill is
269
+ * invoked the rotation has already happened.
270
+ *
271
+ * The previous outer session id comes from the canonical lease projection
272
+ * (`.peaks/_runtime/<sid>/leases/presence-*.json`). The project-level
273
+ * single-slot marker files were removed in 4.0.11 and are NOT read here.
274
+ *
275
+ * The bound session's own recorded outer id is the second signal: when it
276
+ * matches the id about to be stamped, the swap is a re-connect of the SAME
277
+ * outer session and no mismatch is recorded.
278
+ */
279
+ function markOuterSessionMismatch(presence, sessionId, outerSessionId, projectRootOverride) {
280
+ if (outerSessionId === undefined)
281
+ return;
282
+ const previousOuterSessionId = getPreviousOuterSessionId(projectRootOverride);
283
+ const boundOuterSessionId = getBoundOuterSessionId(projectRootOverride);
284
+ const outerChanged = previousOuterSessionId !== outerSessionId;
285
+ const boundOuterMatches = boundOuterSessionId === outerSessionId;
286
+ const hasOuterSignal = previousOuterSessionId !== undefined || boundOuterSessionId !== undefined;
287
+ if (!hasOuterSignal || !outerChanged || boundOuterMatches || sessionId === null)
288
+ return;
289
+ presence.outerSessionMismatch = {
290
+ ...(previousOuterSessionId !== undefined ? { previous: previousOuterSessionId } : {}),
291
+ current: outerSessionId,
292
+ boundSessionId: sessionId,
293
+ ...(boundOuterSessionId !== undefined ? { boundOuterSessionId } : {})
294
+ };
295
+ }
296
+ /**
297
+ * Set the presence for the current skill.
298
+ *
299
+ * ASYNC, AND AWAITED. The canonical write — the graph the lease names, the
300
+ * lease itself, the caller index — is awaited here, so a caller that awaits
301
+ * this function KNOWS whether the presence landed. It used to run inside a
302
+ * non-awaited `void (async () => { ... catch {} })()`: a graph that could
303
+ * not be built, or a lease that could not be written, was swallowed and the
304
+ * caller was handed a success-shaped envelope anyway. That failure now
305
+ * ESCAPES, and the CLI turns it into a fail-closed envelope.
306
+ *
307
+ * The compat shim (slice 4.0.8) still holds:
308
+ * 1. the canonical session id is resolved (caller binding first, then the
309
+ * project-global `.peaks/_runtime/session.json`);
310
+ * 2. the caller id the caller already resolved wins (`--caller-id` >
311
+ * `PEAKS_CALLER_ID` > active IDE adapter — the chain lives in
312
+ * `resolve-caller-id.ts`); when none is supplied the write resolves one
313
+ * itself and fails closed when that is impossible;
314
+ * 3. the canonical write is delegated to `setPresenceLease`, AWAITED.
315
+ */
316
+ export async function setSkillPresence(skill, mode, gate, options) {
317
+ const projectRootOverride = options?.projectRootOverride;
318
+ const callerIdOverride = options?.callerIdOverride;
302
319
  const validatedMode = normalizeSkillPresenceMode(mode);
320
+ // The gate is normalized ONCE, here, so the in-memory envelope and the
321
+ // persisted lease can never disagree about what gate was recorded.
322
+ const validatedGate = normalizePresenceGate(gate);
303
323
  const sessionId = getCurrentSessionId(projectRootOverride);
304
324
  const outerSessionId = getCurrentOuterSessionId();
305
- const previousOuterSessionId = getPreviousOuterSessionId(projectRootOverride);
306
325
  const now = new Date().toISOString();
307
326
  // as `''`) when no harness env var is set. Without this, the JSON
308
327
  // envelope omits the key entirely, which makes downstream staleness
@@ -313,7 +332,7 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
313
332
  const presence = {
314
333
  skill,
315
334
  ...(validatedMode ? { mode: validatedMode } : {}),
316
- ...(gate ? { gate } : {}),
335
+ ...(validatedGate !== undefined ? { gate: validatedGate } : {}),
317
336
  ...(sessionId ? { sessionId } : {}),
318
337
  outerSessionId: outerSessionId ?? '',
319
338
  setAt: now,
@@ -322,78 +341,23 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
322
341
  // Outer-session-mismatch detection. Same logic as the 4.0.7
323
342
  // implementation; we keep the legacy field for back-compat with
324
343
  // statusline consumers.
325
- if (outerSessionId !== undefined) {
326
- const boundOuterSessionId = getBoundOuterSessionId(projectRootOverride);
327
- const outerChanged = previousOuterSessionId !== outerSessionId;
328
- const boundOuterMatches = boundOuterSessionId === outerSessionId;
329
- const hasOuterSignal = previousOuterSessionId !== undefined || boundOuterSessionId !== undefined;
330
- if (hasOuterSignal && outerChanged && !boundOuterMatches && sessionId !== null) {
331
- presence.outerSessionMismatch = {
332
- ...(previousOuterSessionId !== undefined ? { previous: previousOuterSessionId } : {}),
333
- current: outerSessionId,
334
- boundSessionId: sessionId,
335
- ...(boundOuterSessionId !== undefined ? { boundOuterSessionId } : {})
336
- };
337
- }
338
- }
339
- // Canonical lease write — when a session is bound and we can derive
340
- // a (callerId, workflowId, graphRef) tuple, we route through
341
- // `setPresenceLease`. The lease service is fail-closed on missing
342
- // session or unresolved caller; the shim's behavior in that case
343
- // is the legacy `setSkillPresence` (write a flat `SkillPresence`
344
- // record) so callers that pre-date 4.0.8 keep their shape contract.
344
+ markOuterSessionMismatch(presence, sessionId, outerSessionId, projectRootOverride);
345
+ // Canonical lease write — when a session is bound we route through
346
+ // `setPresenceLease`, which writes the graph the lease names BEFORE the
347
+ // lease: no lease is ever left pointing at a missing graph. The write is
348
+ // AWAITED and its failure ESCAPES — a presence that was not written is
349
+ // not a presence that was set.
345
350
  const projectRoot = resolveProjectRoot(projectRootOverride);
346
351
  if (sessionId !== null) {
347
- // Lazy ESM dynamic import: the presence-lease-service and
348
- // resolve-caller-id services are imported here so the cold
349
- // path of the legacy compat shim doesn't pull in the canonical
350
- // lease / adapter machinery at module load. The try/catch
351
- // converts the typed failure (PEAKS_CALLER_NOT_RESOLVED,
352
- // PEAKS_SESSION_NOT_BOUND) into a fall-through to the legacy
353
- // write path — production CLI traffic is gated upstream in
354
- // `skill-command.ts` (exit 1) and this shim exists for legacy
355
- // statusline / hook / dashboard consumers.
356
- void (async () => {
357
- try {
358
- const [{ resolveCallerProjection }, leaseMod] = await Promise.all([
359
- import('../session/resolve-caller-id.js'),
360
- import('./presence-lease-service.js')
361
- ]);
362
- const projection = resolveCallerProjection({ projectRoot, env: process.env });
363
- // shim's workflowId from `projection.callerId` (caller-keyed,
364
- // matching the 4.0.8 caller-binding direction) instead of
365
- // `sessionId` (sid-keyed, pre-4.0.8). `slice(0, 189)` caps the
366
- // callerId to 189 chars so the resulting workflowId
367
- // (`wf-` + callerId + `-compat`) stays under the 200-char
368
- // `WORKFLOW_ID_REGEX = /^[a-zA-Z0-9._-]{1,200}$/` cap. The
369
- // truncation is loss-free for regex purposes — callerId is
370
- // already regex-conformant before the slice. Existing 4.0.14
371
- // leases with `wf-<sid>-compat` become orphans and are GC'd
372
- // by the 24h30m stale-started GC at
373
- // presence-lease-service.ts:42.
374
- const workflowId = `wf-${projection.callerId.slice(0, 189)}-compat`;
375
- const result = leaseMod.setPresenceLease({
376
- projectRoot,
377
- sessionId,
378
- callerId: projection.callerId,
379
- workflowId,
380
- graphRef: `graphs/${workflowId}.json`,
381
- skill,
382
- now,
383
- ...(validatedMode !== undefined ? { mode: validatedMode } : {}),
384
- ...(gate !== undefined ? { gate } : {})
385
- });
386
- // Suppress unused-import warnings for inputs reserved for the
387
- // migration window.
388
- void leaseMod.readPresenceLease;
389
- void leaseMod.markPresenceLost;
390
- void leaseMod.listPresenceLeases;
391
- void result;
392
- }
393
- catch {
394
- /* fall through to legacy write */
395
- }
396
- })();
352
+ await writeCanonicalPresenceLease({
353
+ projectRoot,
354
+ sessionId,
355
+ skill,
356
+ now,
357
+ ...(callerIdOverride !== undefined ? { callerId: callerIdOverride } : {}),
358
+ ...(validatedMode !== undefined ? { mode: validatedMode } : {}),
359
+ ...(validatedGate !== undefined ? { gate: validatedGate } : {})
360
+ });
397
361
  }
398
362
  // Slice 4.0.11 statusline-sid-scoped-lease A: the canonical write
399
363
  // path is now exclusively `presence-lease-service.setPresenceLease`.
@@ -424,10 +388,15 @@ export function getSkillPresence(projectRootOverride) {
424
388
  }
425
389
  export function checkStalePresence(opts) {
426
390
  const result = readSkillPresenceFromLease(opts?.projectRootOverride);
427
- // `opts?.currentOuter === undefined` is the omitted-key case. A
428
- // falsy string `''` is an explicit "no signal" (used by tests to
429
- // simulate a CLI run with no harness env vars).
430
- const current = opts && 'currentOuter' in opts ? opts.currentOuter : getCurrentOuterSessionId();
391
+ // `opts?.currentOuter === undefined` is the omitted-key case. A falsy
392
+ // string `''` is an explicit "no signal" (used by tests to simulate a
393
+ // CLI run with no harness env vars). The env signal wins; the bound
394
+ // session's recorded outer-session id is the fallback, so a presence
395
+ // written with an explicit caller id (no harness env var) is still
396
+ // recognised as belonging to the current session.
397
+ const current = opts && 'currentOuter' in opts
398
+ ? opts.currentOuter
399
+ : (getCurrentOuterSessionId() ?? getBoundOuterSessionId(opts?.projectRootOverride));
431
400
  if (result === null) {
432
401
  return {
433
402
  stale: true,
@@ -0,0 +1,60 @@
1
+ /**
2
+ * The canonical presence write — AWAITED, and fail-closed.
3
+ *
4
+ * WHY THIS IS A MODULE OF ITS OWN. `skill-presence-service.ts` is over the
5
+ * repository's 300-line cap (a ratchet that may only go DOWN), and the
6
+ * canonical write is exactly the part that had to change: it used to run
7
+ * inside a non-awaited `void (async () => { ... catch {} })()`, so a graph
8
+ * that could not be built — or a lease that could not be written — was
9
+ * swallowed and the caller was handed a success-shaped envelope anyway.
10
+ * The write lives here now, the caller AWAITS it, and a failure ESCAPES
11
+ * with a typed code instead of vanishing.
12
+ *
13
+ * WHAT IT DOES NOT DO. It does not decide the session, the mode or the
14
+ * gate — the caller resolved those before it got here. It does not build
15
+ * the legacy `SkillPresence` envelope either; that stays in the service.
16
+ *
17
+ * THE LAZY IMPORT IS DELIBERATE. `presence-lease-service` and the caller-id
18
+ * resolver are imported DYNAMICALLY so the cold path of the legacy READ
19
+ * side (`getSkillPresence` / `checkStalePresence` /
20
+ * `clearStalePresenceOnRotation`) does not pull the canonical lease and
21
+ * the adapter machinery into module load.
22
+ */
23
+ /** What the canonical write needs. */
24
+ export interface CanonicalPresenceWriteInput {
25
+ /** The canonical project root the lease and the graph are written under. */
26
+ readonly projectRoot: string;
27
+ /** The bound session id — the lease is scoped to it. */
28
+ readonly sessionId: string;
29
+ /**
30
+ * The caller id the caller already resolved. When it is absent the write
31
+ * resolves one itself; when THAT fails the write fails closed with
32
+ * `PEAKS_CALLER_NOT_RESOLVED` — a lease is never written for nobody.
33
+ */
34
+ readonly callerId?: string | undefined;
35
+ /** The skill that owns the presence. */
36
+ readonly skill: string;
37
+ /** The timestamp stamped onto the lease. */
38
+ readonly now: string;
39
+ /** The execution mode, already normalized by the caller. */
40
+ readonly mode?: string | undefined;
41
+ /** The gate, already normalized by the caller. */
42
+ readonly gate?: string | undefined;
43
+ }
44
+ /** What the canonical write produced. */
45
+ export interface CanonicalPresenceWriteResult {
46
+ /** The workflow id the lease and the graph are keyed by. */
47
+ readonly workflowId: string;
48
+ /** The graph the lease names. */
49
+ readonly graphRef: string;
50
+ }
51
+ /**
52
+ * Write the canonical presence lease.
53
+ *
54
+ * The graph the lease names is written FIRST (inside
55
+ * `presence-lease-service.setPresenceLease`), so no lease is ever left
56
+ * pointing at a graph that does not exist. When the graph cannot be built
57
+ * or the lease cannot be written, the failure ESCAPES this function: the
58
+ * caller sees it and reports it. Nothing is swallowed here.
59
+ */
60
+ export declare function writeCanonicalPresenceLease(input: CanonicalPresenceWriteInput): Promise<CanonicalPresenceWriteResult>;
@@ -0,0 +1,74 @@
1
+ /**
2
+ * The canonical presence write — AWAITED, and fail-closed.
3
+ *
4
+ * WHY THIS IS A MODULE OF ITS OWN. `skill-presence-service.ts` is over the
5
+ * repository's 300-line cap (a ratchet that may only go DOWN), and the
6
+ * canonical write is exactly the part that had to change: it used to run
7
+ * inside a non-awaited `void (async () => { ... catch {} })()`, so a graph
8
+ * that could not be built — or a lease that could not be written — was
9
+ * swallowed and the caller was handed a success-shaped envelope anyway.
10
+ * The write lives here now, the caller AWAITS it, and a failure ESCAPES
11
+ * with a typed code instead of vanishing.
12
+ *
13
+ * WHAT IT DOES NOT DO. It does not decide the session, the mode or the
14
+ * gate — the caller resolved those before it got here. It does not build
15
+ * the legacy `SkillPresence` envelope either; that stays in the service.
16
+ *
17
+ * THE LAZY IMPORT IS DELIBERATE. `presence-lease-service` and the caller-id
18
+ * resolver are imported DYNAMICALLY so the cold path of the legacy READ
19
+ * side (`getSkillPresence` / `checkStalePresence` /
20
+ * `clearStalePresenceOnRotation`) does not pull the canonical lease and
21
+ * the adapter machinery into module load.
22
+ */
23
+ import { getErrorMessage } from 'peaks-loop-shared/result';
24
+ import { presenceError } from './presence-lease-store.js';
25
+ /**
26
+ * The caller-id prefix cap. `wf-` + <callerId prefix> + `-compat` has to
27
+ * stay under the 200-char `WORKFLOW_ID_REGEX` cap, so the caller id is cut
28
+ * at 189 characters.
29
+ */
30
+ const CALLER_ID_PREFIX_CAP = 189;
31
+ /**
32
+ * Write the canonical presence lease.
33
+ *
34
+ * The graph the lease names is written FIRST (inside
35
+ * `presence-lease-service.setPresenceLease`), so no lease is ever left
36
+ * pointing at a graph that does not exist. When the graph cannot be built
37
+ * or the lease cannot be written, the failure ESCAPES this function: the
38
+ * caller sees it and reports it. Nothing is swallowed here.
39
+ */
40
+ export async function writeCanonicalPresenceLease(input) {
41
+ const [{ resolveCallerProjection }, leaseMod] = await Promise.all([
42
+ import('../session/resolve-caller-id.js'),
43
+ import('./presence-lease-service.js')
44
+ ]);
45
+ let callerId = input.callerId;
46
+ if (callerId === undefined) {
47
+ try {
48
+ callerId = resolveCallerProjection({
49
+ projectRoot: input.projectRoot,
50
+ env: process.env
51
+ }).callerId;
52
+ }
53
+ catch (error) {
54
+ // The resolver reports `EX_USAGE`; the write path reports the
55
+ // canonical `PEAKS_CALLER_NOT_RESOLVED` instead, so this failure is
56
+ // recognizable as a CALLER failure and not as a write failure.
57
+ throw presenceError('PEAKS_CALLER_NOT_RESOLVED', `Could not resolve a callerId for the presence write: ${getErrorMessage(error)}`);
58
+ }
59
+ }
60
+ const workflowId = `wf-${callerId.slice(0, CALLER_ID_PREFIX_CAP)}-compat`;
61
+ const graphRef = `graphs/${workflowId}.json`;
62
+ leaseMod.setPresenceLease({
63
+ projectRoot: input.projectRoot,
64
+ sessionId: input.sessionId,
65
+ callerId,
66
+ workflowId,
67
+ graphRef,
68
+ skill: input.skill,
69
+ now: input.now,
70
+ ...(input.mode !== undefined ? { mode: input.mode } : {}),
71
+ ...(input.gate !== undefined ? { gate: input.gate } : {})
72
+ });
73
+ return { workflowId, graphRef };
74
+ }
@@ -19,14 +19,14 @@ export { parseStatusLineStdin, read24hOverlay } from './skill-statusline-model.j
19
19
  * and survives context compaction.
20
20
  *
21
21
  * This module is intentionally READ-ONLY. Unlike getSkillPresence in
22
- * skill-presence-service.ts, it never deletes or rewrites the presence file:
23
- * the statusLine runs on every turn and must have zero side effects.
22
+ * skill-presence-service.ts, it never deletes or rewrites the presence
23
+ * lease: the statusLine runs on every turn and must have zero side effects.
24
24
  *
25
- * back to the project-level `.peaks/_runtime/active-skill.json` (or its
26
- * legacy `.peaks/.active-skill.json`). The canonical lease projection is
27
- * the only source. When `callerId === null` (non-IDE caller), the read
28
- * picks the most recent in-flight lease across all callers; this is the
29
- * documented back-compat path.
25
+ * The canonical lease projection is the only source — there is no fallback
26
+ * to the removed project-level `.peaks/_runtime/active-skill.json` (or its
27
+ * legacy `.peaks/.active-skill.json`). When `callerId === null` (non-IDE
28
+ * caller), the read picks the most recent in-flight lease across all
29
+ * callers; this is the documented back-compat path.
30
30
  */
31
31
  import { normalizeSkillPresenceMode } from './skill-presence-service.js';
32
32
  const STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000;
@@ -5,6 +5,29 @@ import type { IdeId } from '../ide/ide-types.js';
5
5
  * single source of truth for the sync fan-out.
6
6
  */
7
7
  export declare const SYNC_PLATFORMS: readonly IdeId[];
8
+ /**
9
+ * What the canonical store holds for one skill, as the installer found it.
10
+ *
11
+ * `current` — the store holds this entry and it is not behind the installed
12
+ * release. `stale` — it is behind, or its bytes differ from the package's.
13
+ * `unmanaged` — the store holds an entry peaks-loop does not own (no
14
+ * sidecar); it is never overwritten, and it is reported so the skip is not
15
+ * silent. `retired` — the store holds an entry peaks-loop owns that this
16
+ * release does not ship any more. `absent` — the store does not hold this
17
+ * entry at all: there is nothing there to compare, so it is neither current
18
+ * nor stale.
19
+ */
20
+ export type StoreEntryState = 'current' | 'stale' | 'unmanaged' | 'retired' | 'absent';
21
+ export interface StoreEntryReport {
22
+ readonly name: string;
23
+ readonly state: StoreEntryState;
24
+ /** What the installer did: `installed`, `unchanged`, `planned`, `unmanaged`. */
25
+ readonly action: string;
26
+ /** The version the copy was made from, or null when the marker records none. */
27
+ readonly version: string | null;
28
+ /** Why a stale entry was stale: `version` or `content`; null otherwise. */
29
+ readonly reason: string | null;
30
+ }
8
31
  export interface PlatformSyncResult {
9
32
  /** The platform that was attempted. */
10
33
  readonly platform: IdeId;
@@ -14,6 +37,8 @@ export interface PlatformSyncResult {
14
37
  readonly installed: readonly string[];
15
38
  /** Skills whose target was not a managed symlink (third-party owned). */
16
39
  readonly skipped: readonly string[];
40
+ /** What the canonical store holds per skill, as found. */
41
+ readonly entries?: readonly StoreEntryReport[];
17
42
  /** Error message; present when ok=false. */
18
43
  readonly error?: string;
19
44
  /** Wall-clock duration in ms. */
@@ -47,6 +72,8 @@ export interface InstallBundledSkillsOptions {
47
72
  export interface InstallResult {
48
73
  readonly installed: readonly string[];
49
74
  readonly skipped: readonly string[];
75
+ /** What the canonical store holds per skill, when the installer reports it. */
76
+ readonly entries?: readonly StoreEntryReport[];
50
77
  }
51
78
  export type InstallerFn = (opts: InstallBundledSkillsOptions) => InstallResult;
52
79
  /**
@@ -191,6 +191,7 @@ export async function runSkillSync(input) {
191
191
  ok: true,
192
192
  installed: result.installed,
193
193
  skipped: result.skipped,
194
+ ...(result.entries !== undefined ? { entries: result.entries } : {}),
194
195
  durationMs: Date.now() - start
195
196
  });
196
197
  syncedCount += 1;