peaks-loop 4.1.26 → 4.2.1

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 (157) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +160 -0
  3. package/contracts/readonly-argv-whitelist.json +116 -0
  4. package/dist/cli/commands/code-auto-compact-command.js +15 -3
  5. package/dist/cli/commands/core/session-info-command.js +3 -4
  6. package/dist/cli/commands/core/skill-presence-housekeeping-commands.js +7 -1
  7. package/dist/cli/commands/dashboard-long-run.js +2 -1
  8. package/dist/cli/commands/doctor/invoke-from-code.js +6 -1
  9. package/dist/cli/commands/job-state-root.js +4 -2
  10. package/dist/cli/commands/lease-metrics-commands-support.js +2 -1
  11. package/dist/cli/commands/loop-eval-capture-index.js +2 -1
  12. package/dist/cli/commands/loop-eval-eval-command.js +2 -1
  13. package/dist/cli/commands/mut-commands-helpers.d.ts +9 -28
  14. package/dist/cli/commands/mut-commands-helpers.js +53 -80
  15. package/dist/cli/commands/mut-failure-diagnostic.d.ts +48 -0
  16. package/dist/cli/commands/mut-failure-diagnostic.js +147 -0
  17. package/dist/cli/commands/outer-cache-commands.js +3 -2
  18. package/dist/cli/commands/playwright-session-store.js +5 -2
  19. package/dist/cli/commands/project-context-command.js +7 -2
  20. package/dist/cli/commands/qa-archive-screenshots-command.js +2 -1
  21. package/dist/cli/commands/request-transition-preflight.js +2 -2
  22. package/dist/cli/commands/slice-decompose-artifacts.js +10 -2
  23. package/dist/cli/commands/verdict-aggregate-command.js +4 -3
  24. package/dist/cli/commands/workspace/init-actions.js +5 -0
  25. package/dist/cli/commands/workspace/init-context.js +1 -0
  26. package/dist/cli/commands/worktree-lease-effects.d.ts +13 -0
  27. package/dist/cli/commands/worktree-lease-effects.js +23 -0
  28. package/dist/cli/commands/worktree-lease-gc-command.d.ts +3 -4
  29. package/dist/cli/commands/worktree-lease-gc-command.js +59 -58
  30. package/dist/cli/commands/worktree-lease-git.d.ts +13 -18
  31. package/dist/cli/commands/worktree-lease-git.js +21 -44
  32. package/dist/cli/commands/worktree-lease-list-command.js +1 -1
  33. package/dist/cli/commands/worktree-lease-load.d.ts +19 -7
  34. package/dist/cli/commands/worktree-lease-load.js +37 -9
  35. package/dist/cli/commands/worktree-lease-release-command.d.ts +4 -5
  36. package/dist/cli/commands/worktree-lease-release-command.js +60 -47
  37. package/dist/cli/commands/worktree-lease-renew-command.d.ts +5 -4
  38. package/dist/cli/commands/worktree-lease-renew-command.js +36 -32
  39. package/dist/cli/commands/worktree-lease-session.d.ts +7 -5
  40. package/dist/cli/commands/worktree-lease-session.js +9 -6
  41. package/dist/cli/commands/worktree-lease-spawn-command.d.ts +4 -3
  42. package/dist/cli/commands/worktree-lease-spawn-command.js +38 -46
  43. package/dist/cli/commands/worktree-lease-status-command.js +1 -1
  44. package/dist/cli/commands/worktree-lease-store.d.ts +3 -2
  45. package/dist/cli/commands/worktree-lease-store.js +3 -2
  46. package/dist/services/artifacts/prerequisite-path-resolver.js +5 -1
  47. package/dist/services/audit/enforcers/lint-output-style.js +5 -1
  48. package/dist/services/audit/enforcers/lint-rd-handoff-coverage.js +9 -4
  49. package/dist/services/audit-independent/handoff-missing-refusal.js +16 -1
  50. package/dist/services/audit-independent/judged-declaration-check.js +5 -1
  51. package/dist/services/audit-independent/perf-audit-service.d.ts +2 -4
  52. package/dist/services/audit-independent/perf-audit-service.js +4 -5
  53. package/dist/services/audit-independent/security-audit-artifact.js +5 -1
  54. package/dist/services/capability-audit-service/runner.js +4 -1
  55. package/dist/services/capability-baseline/store.js +2 -1
  56. package/dist/services/capability-guard-runner/contracts/J05.js +4 -2
  57. package/dist/services/capability-guard-runner/contracts/J12.js +2 -2
  58. package/dist/services/code/auto-compact-artifacts.js +42 -10
  59. package/dist/services/code/auto-compact-checkpoint-content.d.ts +49 -0
  60. package/dist/services/code/auto-compact-checkpoint-content.js +157 -0
  61. package/dist/services/code/auto-compact-envelopes.d.ts +11 -2
  62. package/dist/services/code/auto-compact-envelopes.js +18 -4
  63. package/dist/services/code/auto-compact-orchestrator.js +1 -1
  64. package/dist/services/code/emit-handoff.js +8 -1
  65. package/dist/services/code/job-shape-decision.js +13 -2
  66. package/dist/services/code/job-shape-provisional.js +9 -1
  67. package/dist/services/code/post-compact-detector.js +9 -1
  68. package/dist/services/code/step-08-session-readers.js +14 -5
  69. package/dist/services/compact/request-transition-hook.js +6 -1
  70. package/dist/services/compact/suggest-service.js +8 -1
  71. package/dist/services/context/post-compact-reinjection.js +15 -14
  72. package/dist/services/context/spillover-store.js +2 -1
  73. package/dist/services/dispatch/contract-store.d.ts +11 -4
  74. package/dist/services/dispatch/contract-store.js +21 -8
  75. package/dist/services/doctor/doctor-service/checks/workspace-layout.js +8 -3
  76. package/dist/services/doctor/doctor-service/index.js +2 -1
  77. package/dist/services/final-review/final-review-evidence-collect.js +5 -1
  78. package/dist/services/fresh-context/fresh-context-block.js +5 -1
  79. package/dist/services/hooks/auto-compact-hook-install.d.ts +13 -3
  80. package/dist/services/hooks/auto-compact-hook-install.js +13 -3
  81. package/dist/services/hooks/worktree-authorization-gate.d.ts +1 -1
  82. package/dist/services/hooks/worktree-authorization-gate.js +14 -11
  83. package/dist/services/loop/evaluator-dispatcher.js +7 -7
  84. package/dist/services/loop/monotonic-runner.js +2 -1
  85. package/dist/services/loop/spec-service.js +10 -9
  86. package/dist/services/mcp/context-tool.d.ts +3 -0
  87. package/dist/services/mcp/context-tool.js +135 -0
  88. package/dist/services/mcp/surface.js +7 -1
  89. package/dist/services/mcp/tools.js +3 -1
  90. package/dist/services/memory/project-context-service.d.ts +10 -1
  91. package/dist/services/memory/project-context-service.js +13 -6
  92. package/dist/services/observability/jsonl-store.js +4 -1
  93. package/dist/services/polyrepo/polyrepo-dispatcher.js +5 -1
  94. package/dist/services/prd/prd-blocks-checker.js +12 -6
  95. package/dist/services/prd/project-scan-body-tables.d.ts +33 -0
  96. package/dist/services/prd/project-scan-body-tables.js +185 -0
  97. package/dist/services/prd/project-scan-bootstrap-service.d.ts +16 -3
  98. package/dist/services/prd/project-scan-bootstrap-service.js +127 -231
  99. package/dist/services/prd/project-scan-content.d.ts +24 -0
  100. package/dist/services/prd/project-scan-content.js +207 -0
  101. package/dist/services/prd/project-scan-existing-state.d.ts +22 -0
  102. package/dist/services/prd/project-scan-existing-state.js +61 -0
  103. package/dist/services/prd/project-scan-field-refresh.d.ts +87 -0
  104. package/dist/services/prd/project-scan-field-refresh.js +217 -0
  105. package/dist/services/prd/project-scan-frontmatter.d.ts +32 -0
  106. package/dist/services/prd/project-scan-frontmatter.js +34 -0
  107. package/dist/services/prd/project-scan-library-versions.d.ts +60 -0
  108. package/dist/services/prd/project-scan-library-versions.js +135 -0
  109. package/dist/services/prd/project-scan-techstack.d.ts +34 -0
  110. package/dist/services/prd/project-scan-techstack.js +167 -0
  111. package/dist/services/reviewer/reviewer-artifacts.js +2 -1
  112. package/dist/services/sc/sc-service.js +8 -8
  113. package/dist/services/scan/api-diff-recorded.d.ts +2 -3
  114. package/dist/services/scan/api-diff-recorded.js +5 -5
  115. package/dist/services/session/binding-status-service.js +2 -1
  116. package/dist/services/session/binding-store.js +6 -7
  117. package/dist/services/session/caller-binding-service.js +5 -2
  118. package/dist/services/session/getSessionDir.d.ts +4 -0
  119. package/dist/services/session/getSessionDir.js +38 -13
  120. package/dist/services/session/session-binding-bridge.d.ts +3 -6
  121. package/dist/services/session/session-binding-bridge.js +13 -13
  122. package/dist/services/session/session-checkpoint-service.js +22 -3
  123. package/dist/services/session/session-manager.js +16 -20
  124. package/dist/services/skills/presence-lease-resolver.js +3 -2
  125. package/dist/services/skills/presence-lease-service.js +7 -15
  126. package/dist/services/skills/presence-lease-store.d.ts +26 -0
  127. package/dist/services/skills/presence-lease-store.js +60 -5
  128. package/dist/services/skills/skill-presence-service.js +13 -20
  129. package/dist/services/skills/skill-statusline-model.js +7 -2
  130. package/dist/services/slice/slice-archive-service.js +4 -1
  131. package/dist/services/standards/missing-standards-detector.js +2 -1
  132. package/dist/services/test-cache/test-cache-service.js +2 -1
  133. package/dist/services/workflow/artifact-paths.js +6 -2
  134. package/dist/services/workflow/pipeline-verify-gate-support.d.ts +1 -1
  135. package/dist/services/workflow/pipeline-verify-gate-support.js +23 -11
  136. package/dist/services/workflow/workflow-graph-store-helpers.js +12 -3
  137. package/dist/services/workflow/workflow-state-store.js +11 -4
  138. package/dist/services/workspace/migrate-1-4-1-service.js +2 -1
  139. package/dist/services/workspace/reconcile-migrate.js +2 -2
  140. package/dist/services/workspace/reconcile-service.d.ts +4 -6
  141. package/dist/services/workspace/reconcile-service.js +11 -11
  142. package/dist/services/workspace/workspace-service.js +5 -5
  143. package/dist/services/worktree/dispatch-provenance.d.ts +1 -1
  144. package/dist/services/worktree/dispatch-provenance.js +9 -2
  145. package/dist/services/worktree/host-worktree-reconciler.d.ts +1 -1
  146. package/dist/services/worktree/host-worktree-reconciler.js +5 -3
  147. package/dist/shared/runtime-root.js +6 -1
  148. package/package.json +6 -5
  149. package/skills/peaks-code/SKILL.md +1 -1
  150. package/skills/peaks-code/references/project-scan-checklist.md +3 -1
  151. package/skills/peaks-mut/SKILL.md +6 -2
  152. package/dist/services/worktree/git-worktree-parser.d.ts +0 -8
  153. package/dist/services/worktree/git-worktree-parser.js +0 -55
  154. package/dist/services/worktree/worktree-lease-types.d.ts +0 -52
  155. package/dist/services/worktree/worktree-lease-types.js +0 -9
  156. package/dist/services/worktree/worktree-lease.d.ts +0 -116
  157. package/dist/services/worktree/worktree-lease.js +0 -252
@@ -10,7 +10,9 @@
10
10
  * shape as before. `workflow-graph-store.ts` re-exports every public
11
11
  * name from this module so all importers keep resolving the same path.
12
12
  */
13
- import { join, resolve, sep } from 'node:path';
13
+ import { resolve } from 'node:path';
14
+ import { isInsidePath } from '../../shared/path-utils.js';
15
+ import { getSessionDir } from '../session/getSessionDir.js';
14
16
  import { WORKFLOW_ID_REGEX, isSafeRelativeGraphRef } from './workflow-graph-types.js';
15
17
  export const PEAKS_GRAPH_NOT_FOUND = 'PEAKS_GRAPH_NOT_FOUND';
16
18
  export const PEAKS_GRAPH_CORRUPTED = 'PEAKS_GRAPH_CORRUPTED';
@@ -42,7 +44,7 @@ function safeSessionRuntimeRoot(projectRoot, sessionId) {
42
44
  throw makeError(PEAKS_GRAPH_REF_BROKEN, `invalid sessionId: ${sessionId}`);
43
45
  }
44
46
  const root = resolve(projectRoot);
45
- return join(root, '.peaks', '_runtime', sessionId);
47
+ return getSessionDir(root, sessionId);
46
48
  }
47
49
  /** Compute the on-disk graph path. Validates `graphRef` stays under the session root. */
48
50
  export function graphPathFor(input) {
@@ -54,7 +56,14 @@ export function graphPathFor(input) {
54
56
  }
55
57
  const sessionRoot = safeSessionRuntimeRoot(input.projectRoot, input.sessionId);
56
58
  const resolved = resolve(sessionRoot, input.graphRef);
57
- if (!resolved.startsWith(sessionRoot + sep) && resolved !== sessionRoot) {
59
+ // Containment is asked through `relative()`, never by string-prefix: the
60
+ // session root is emitted by the workspace-runtime package with FORWARD
61
+ // slashes, while `resolve()` here returns the platform's separators. On
62
+ // Windows the prefix test compared `D:/…/_runtime/<sid>` against
63
+ // `D:\…\graphs\x.json`, was false for every legitimate ref, and threw. Any
64
+ // prefix scheme has the same defect unless BOTH sides are folded first;
65
+ // `relative()` folds both and also answers the cross-drive case.
66
+ if (!isInsidePath(resolved, sessionRoot)) {
58
67
  throw makeError(PEAKS_GRAPH_REF_BROKEN, `graphRef escapes session root: ${input.graphRef}`);
59
68
  }
60
69
  return resolved;
@@ -20,6 +20,7 @@
20
20
  */
21
21
  import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
22
22
  import { dirname, join } from 'node:path';
23
+ import { getSessionDir, tryGetSessionDir } from '../session/getSessionDir.js';
23
24
  const STATE_FILE_NAME = 'workflow-state.json';
24
25
  /** C0/C1 controls and DEL. A newline or escape in a printed field is a spoofed line. */
25
26
  export function hasControlChars(value) {
@@ -29,8 +30,14 @@ export function hasControlChars(value) {
29
30
  }
30
31
  return false;
31
32
  }
33
+ /**
34
+ * The state file, or `null` when the session id cannot name a session dir.
35
+ * The TOTAL entry: the read and delete frames answer "no state" for it; the
36
+ * write frame cannot proceed and takes the throwing entry instead.
37
+ */
32
38
  function stateFilePath(projectRoot, sessionId, rid) {
33
- return join(projectRoot, '.peaks', '_runtime', sessionId, 'workflow-state', `${rid}.json`);
39
+ const resolved = tryGetSessionDir(projectRoot, sessionId);
40
+ return resolved.ok ? join(resolved.dir, 'workflow-state', `${rid}.json`) : null;
34
41
  }
35
42
  /**
36
43
  * Read the skip-state for a rid, or `null` if no state file exists or
@@ -46,7 +53,7 @@ function stateFilePath(projectRoot, sessionId, rid) {
46
53
  */
47
54
  export function readSkipState(projectRoot, sessionId, rid) {
48
55
  const path = stateFilePath(projectRoot, sessionId, rid);
49
- if (!existsSync(path)) {
56
+ if (path === null || !existsSync(path)) {
50
57
  return null;
51
58
  }
52
59
  try {
@@ -68,7 +75,7 @@ export function readSkipState(projectRoot, sessionId, rid) {
68
75
  * surfacing this in the envelope as `persistedTo`.
69
76
  */
70
77
  export function writeSkipState(projectRoot, sessionId, state) {
71
- const path = stateFilePath(projectRoot, sessionId, state.rid);
78
+ const path = join(getSessionDir(projectRoot, sessionId), 'workflow-state', `${state.rid}.json`);
72
79
  mkdirSync(dirname(path), { recursive: true });
73
80
  writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
74
81
  return path;
@@ -81,7 +88,7 @@ export function writeSkipState(projectRoot, sessionId, state) {
81
88
  */
82
89
  export function deleteSkipState(projectRoot, sessionId, rid) {
83
90
  const path = stateFilePath(projectRoot, sessionId, rid);
84
- if (!existsSync(path)) {
91
+ if (path === null || !existsSync(path)) {
85
92
  return false;
86
93
  }
87
94
  unlinkSync(path);
@@ -20,6 +20,7 @@
20
20
  */
21
21
  import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync } from 'node:fs';
22
22
  import { join } from 'node:path';
23
+ import { getSessionDir } from '../session/getSessionDir.js';
23
24
  // Frozen: the filenames release 1.4.1 wrote, not the current contract. The
24
25
  // entries name what this migration must FIND on an upgraded tree, so they stay
25
26
  // bare even where a later release put the request id in the canonical name.
@@ -97,7 +98,7 @@ function buildPlan(projectRoot) {
97
98
  const plan = [];
98
99
  for (const sid of enumerateLegacySessions(projectRoot)) {
99
100
  const legacyRoot = join(projectRoot, '.peaks', sid);
100
- const canonicalRoot = join(projectRoot, '.peaks', '_runtime', sid);
101
+ const canonicalRoot = getSessionDir(projectRoot, sid);
101
102
  // Per-session files (no <rid> template).
102
103
  for (const rel of PER_SESSION_ARTIFACT_TYPES) {
103
104
  const from = join(legacyRoot, rel);
@@ -4,6 +4,7 @@
4
4
  */
5
5
  import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, rmdirSync, unlinkSync } from 'node:fs';
6
6
  import { dirname, join, resolve } from 'node:path';
7
+ import { defaultStateRoot } from 'peaks-loop-workspace-runtime';
7
8
  // Call-time-only dependency on the sibling service: `migrateSubAgentState`
8
9
  // walks every discovered session via `discoverSessions`, which is invoked
9
10
  // only at call time (after both modules have fully evaluated), so the
@@ -27,7 +28,6 @@ const RUNTIME_OLD_PATHS = [
27
28
  '.active-skill.json',
28
29
  'sop-state'
29
30
  ];
30
- const RUNTIME_DIR = join('.peaks', '_runtime');
31
31
  /**
32
32
  * Map a legacy path basename (e.g. `.session.json`) to its canonical
33
33
  * new basename (e.g. `session.json`). The dot is dropped so the new
@@ -70,7 +70,7 @@ function runtimeNewBasename(oldBasename) {
70
70
  export function migrateOldRuntimeState(projectRoot) {
71
71
  const root = resolve(projectRoot);
72
72
  const peaksRoot = join(root, '.peaks');
73
- const newDir = join(root, RUNTIME_DIR);
73
+ const newDir = defaultStateRoot(root);
74
74
  const migratedFiles = [];
75
75
  const errors = [];
76
76
  for (const rel of RUNTIME_OLD_PATHS) {
@@ -18,13 +18,11 @@
18
18
  import type { ReconcileOptions, ReconcileResult, SessionEntry } from './reconcile-types.js';
19
19
  /**
20
20
  * Walk the project root's `.peaks/` directory and return an entry per
21
- * session dir matching the standard naming pattern, sorted by name
22
- * ascending (the most recent is last by sort order, since the date
23
- * prefix dominates the lexicographic order).
21
+ * session dir matching the standard naming pattern, sorted by name ascending
22
+ * (the date prefix dominates the lexicographic order).
24
23
  *
25
- * Each entry's `lastActivity` is the mtime of the inner `session.json`
26
- * file, or null if that file is missing. `artifactCount` is the count
27
- * of files under the dir excluding `session.json` itself.
24
+ * `lastActivity` is the mtime of the inner `session.json` (or null when it is
25
+ * missing); `artifactCount` counts the files under the dir excluding it.
28
26
  */
29
27
  export declare function discoverSessions(projectRoot: string): SessionEntry[];
30
28
  /**
@@ -17,22 +17,22 @@
17
17
  */
18
18
  import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
19
19
  import { join, resolve } from 'node:path';
20
+ import { defaultStateRoot } from 'peaks-loop-workspace-runtime';
21
+ import { getSessionDir } from '../session/getSessionDir.js';
20
22
  import { getSessionIdCanonical, setCurrentSessionBinding } from '../session/session-manager.js';
21
23
  import { migrateOldRuntimeState, migrateSubAgentState } from './reconcile-migrate.js';
22
24
  const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/;
23
25
  const META_FILE = 'session.json';
24
26
  /**
25
27
  * Walk the project root's `.peaks/` directory and return an entry per
26
- * session dir matching the standard naming pattern, sorted by name
27
- * ascending (the most recent is last by sort order, since the date
28
- * prefix dominates the lexicographic order).
28
+ * session dir matching the standard naming pattern, sorted by name ascending
29
+ * (the date prefix dominates the lexicographic order).
29
30
  *
30
- * Each entry's `lastActivity` is the mtime of the inner `session.json`
31
- * file, or null if that file is missing. `artifactCount` is the count
32
- * of files under the dir excluding `session.json` itself.
31
+ * `lastActivity` is the mtime of the inner `session.json` (or null when it is
32
+ * missing); `artifactCount` counts the files under the dir excluding it.
33
33
  */
34
34
  export function discoverSessions(projectRoot) {
35
- const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
35
+ const runtimeRoot = defaultStateRoot(projectRoot);
36
36
  const peaksRoot = join(projectRoot, '.peaks');
37
37
  // `.peaks/_runtime/<sid>/`. The legacy top-level layout is
38
38
  // read for back-compat (one minor release) so pre-migration
@@ -270,7 +270,7 @@ export function applyDeletions(candidates, apply) {
270
270
  * Returns null when the file is missing or malformed.
271
271
  */
272
272
  function readActiveSkillSessionId(projectRoot) {
273
- const newPath = join(projectRoot, '.peaks', '_runtime', 'active-skill.json');
273
+ const newPath = join(defaultStateRoot(projectRoot), 'active-skill.json');
274
274
  const legacyPath = join(projectRoot, '.peaks', '.active-skill.json');
275
275
  const pathToRead = existsSync(newPath) ? newPath : legacyPath;
276
276
  if (!existsSync(pathToRead))
@@ -318,7 +318,7 @@ function readActiveSkillSessionId(projectRoot) {
318
318
  */
319
319
  export function syncChangeMarker(projectRoot, canonicalSessionId) {
320
320
  const root = resolve(projectRoot);
321
- const changeDir = join(root, '.peaks', '_runtime', 'change');
321
+ const changeDir = join(defaultStateRoot(root), 'change');
322
322
  const removed = [];
323
323
  let created = null;
324
324
  let error = null;
@@ -479,8 +479,8 @@ export function reconcilePresenceLeases(input) {
479
479
  const conflicts = [];
480
480
  const legacyPaths = [];
481
481
  // Canonical target tree (RD §6).
482
- const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
483
- const sessionRoot = join(runtimeRoot, sessionId);
482
+ const runtimeRoot = defaultStateRoot(projectRoot);
483
+ const sessionRoot = getSessionDir(projectRoot, sessionId);
484
484
  const leasesDir = join(sessionRoot, 'leases');
485
485
  const presenceIndexDir = join(sessionRoot, 'presence-index');
486
486
  const migrationsDir = join(sessionRoot, 'migrations');
@@ -4,6 +4,7 @@ import { join } from 'node:path';
4
4
  import { isDirectory } from 'peaks-loop-shared/fs';
5
5
  import { getSessionIdCanonical, setCurrentSessionBinding, setSessionMeta } from '../session/session-manager.js';
6
6
  import { updateCallerBindingSessionId } from '../session/caller-binding-service.js';
7
+ import { getSessionDir, tryGetSessionDir } from '../session/getSessionDir.js';
7
8
  import { resolveCallerProjection } from '../session/resolve-caller-id.js';
8
9
  import { normalizePath } from '../../shared/path-utils.js';
9
10
  import { assertWritableProjectRoot } from '../config/config-safety.js';
@@ -196,8 +197,7 @@ export async function initWorkspace(options) {
196
197
  // session-scoped layout (`.peaks/_runtime/<session-id>/<role>/<file>`) is
197
198
  // no longer used by writes; pre-1.3.1 trees get their session
198
199
  // files migrated to the change-id dir by `peaks workspace reconcile`.
199
- const runtimeRoot = join(options.projectRoot, '.peaks', '_runtime');
200
- const sessionRoot = join(runtimeRoot, options.sessionId);
200
+ const sessionRoot = getSessionDir(options.projectRoot, options.sessionId);
201
201
  const created = [];
202
202
  const alreadyExisted = [];
203
203
  // 1. Create the session dir (canonical location `.peaks/_runtime/<sid>/`)
@@ -298,10 +298,10 @@ export async function initWorkspace(options) {
298
298
  // etc.) regardless of whether the per-session metadata file is present.
299
299
  // Refuse to rebind without explicit authorization.
300
300
  previousSessionId = existingSessionId;
301
- const existingSessionDir = join(runtimeRoot, existingSessionId);
302
- if ((await isDirectory(existingSessionDir)) && !options.allowSessionRebind) {
301
+ const existingDir = tryGetSessionDir(options.projectRoot, existingSessionId);
302
+ if (existingDir.ok && (await isDirectory(existingDir.dir)) && !options.allowSessionRebind) {
303
303
  const { readdirSync } = await import('node:fs');
304
- const entries = readdirSync(existingSessionDir);
304
+ const entries = readdirSync(existingDir.dir);
305
305
  if (entries.length > 0) {
306
306
  throw new ConflictingSessionError(`Project is already bound to session "${existingSessionId}". ` +
307
307
  `Cannot start session "${options.sessionId}" without closing the previous one. ` +
@@ -13,7 +13,7 @@ export declare function createDispatchProvenanceToken(input: {
13
13
  readonly requestId: string;
14
14
  readonly leaseId: string;
15
15
  }): string;
16
- export declare function dispatchProvenanceFilePath(projectRoot: string, sessionId: string, token: string): string;
16
+ export declare function dispatchProvenanceFilePath(projectRoot: string, sessionId: string, token: string): string | null;
17
17
  export declare function writeDispatchProvenance(input: {
18
18
  readonly projectRoot: string;
19
19
  readonly record: DispatchProvenance;
@@ -1,6 +1,7 @@
1
1
  import { createHash } from 'node:crypto';
2
2
  import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
3
3
  import { dirname, join } from 'node:path';
4
+ import { tryGetSessionDir } from '../session/getSessionDir.js';
4
5
  export const DISPATCH_PROVENANCE_ENV = 'PEAKS_SUB_AGENT_DISPATCH_PROVENANCE';
5
6
  const PROVENANCE_DIR = 'dispatch-provenance';
6
7
  export function createDispatchProvenanceToken(input) {
@@ -10,10 +11,16 @@ export function createDispatchProvenanceToken(input) {
10
11
  .slice(0, 32);
11
12
  }
12
13
  export function dispatchProvenanceFilePath(projectRoot, sessionId, token) {
13
- return join(projectRoot, '.peaks', '_runtime', sessionId, PROVENANCE_DIR, `${token}.json`);
14
+ // Total: the reader treats an unresolvable id as "no provenance record",
15
+ // the same answer as a missing file.
16
+ const resolved = tryGetSessionDir(projectRoot, sessionId);
17
+ return resolved.ok ? join(resolved.dir, PROVENANCE_DIR, `${token}.json`) : null;
14
18
  }
15
19
  export function writeDispatchProvenance(input) {
16
20
  const path = dispatchProvenanceFilePath(input.projectRoot, input.record.sessionId, input.record.token);
21
+ if (path === null) {
22
+ throw new Error(`Invalid session id: ${input.record.sessionId} (must be a single path segment)`);
23
+ }
17
24
  mkdirSync(dirname(path), { recursive: true });
18
25
  const tempPath = `${path}.tmp-${process.pid}-${Date.now()}`;
19
26
  writeFileSync(tempPath, `${JSON.stringify(input.record, null, 2)}\n`, 'utf8');
@@ -23,7 +30,7 @@ export function readDispatchProvenance(input) {
23
30
  if (!/^[a-f0-9]{32}$/.test(input.token))
24
31
  return null;
25
32
  const path = dispatchProvenanceFilePath(input.projectRoot, input.sessionId, input.token);
26
- if (!existsSync(path))
33
+ if (path === null || !existsSync(path))
27
34
  return null;
28
35
  try {
29
36
  const parsed = JSON.parse(readFileSync(path, 'utf8'));
@@ -1,4 +1,4 @@
1
- import { type GitWorktreeRecord } from './git-worktree-parser.js';
1
+ import { type GitWorktreeRecord } from 'peaks-loop-workspace-runtime';
2
2
  export type HostWorktreeFinding = GitWorktreeRecord & {
3
3
  readonly managedLeaseId: string | null;
4
4
  readonly state: 'managed' | 'unleased' | 'prunable';
@@ -1,8 +1,7 @@
1
1
  import { execFileSync } from 'node:child_process';
2
2
  import { existsSync, readFileSync, readdirSync } from 'node:fs';
3
3
  import { basename, join, resolve } from 'node:path';
4
- import { leaseStoreDir, listLeasesSync } from './worktree-lease.js';
5
- import { isPathInside, parseGitWorktreePorcelain } from './git-worktree-parser.js';
4
+ import { defaultStateRoot, isPathInside, leaseStoreDir, listLeasesSync, parseGitWorktreePorcelain, sessionRuntimeDir } from 'peaks-loop-workspace-runtime';
6
5
  export function reconcileHostWorktrees(input) {
7
6
  const hostRoot = resolve(input.hostRoot ?? join(input.projectRoot, '.claude', 'worktrees'));
8
7
  let records = [];
@@ -18,7 +17,10 @@ export function reconcileHostWorktrees(input) {
18
17
  catch {
19
18
  records = [];
20
19
  }
21
- const storeDir = leaseStoreDir(join(input.projectRoot, '.peaks', '_runtime', input.sessionId));
20
+ const storeDir = leaseStoreDir(sessionRuntimeDir({
21
+ stateRoot: defaultStateRoot(input.projectRoot),
22
+ sessionId: input.sessionId
23
+ }));
22
24
  const leaseResult = listLeasesSync(storeDir, {
23
25
  existsSync,
24
26
  readdir: (path) => readdirSync(path),
@@ -23,6 +23,7 @@
23
23
  * enumerate the root itself; it is not a join.
24
24
  */
25
25
  import { join } from 'node:path';
26
+ import { defaultStateRoot } from 'peaks-loop-workspace-runtime';
26
27
  import { isUnsafePathInput } from './path-safety.js';
27
28
  /**
28
29
  * Check a caller-supplied string and brand it for use as a runtime path
@@ -51,7 +52,11 @@ export class RuntimeRoot {
51
52
  }
52
53
  /** The runtime root of `projectRoot`. */
53
54
  static at(projectRoot) {
54
- return new RuntimeRoot(join(projectRoot, '.peaks', '_runtime'));
55
+ // The layout lives in the workspace-runtime package (the single place this
56
+ // project composes it). `join` over the one value is separator
57
+ // normalization only: `dir()` has always emitted the platform's separator
58
+ // and callers compare against it byte-for-byte.
59
+ return new RuntimeRoot(join(defaultStateRoot(projectRoot)));
55
60
  }
56
61
  /**
57
62
  * Join guarded segments onto the root. At least one segment is required: a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "peaks-loop",
3
- "version": "4.1.26",
3
+ "version": "4.2.1",
4
4
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
5
5
  "author": "SquabbyZ",
6
6
  "keywords": [
@@ -133,10 +133,11 @@
133
133
  "picomatch": "4.0.7",
134
134
  "yaml": "^2.9.1",
135
135
  "zod": "^4.6.7",
136
- "peaks-loop-internal-runtime": "0.0.66",
137
- "peaks-loop-mut": "0.1.80",
138
- "peaks-loop-shared": "0.0.115",
139
- "peaks-loop-shared-channel": "0.0.83"
136
+ "peaks-loop-internal-runtime": "0.0.68",
137
+ "peaks-loop-mut": "0.1.82",
138
+ "peaks-loop-shared": "0.0.117",
139
+ "peaks-loop-shared-channel": "0.0.85",
140
+ "peaks-loop-workspace-runtime": "0.0.2"
140
141
  },
141
142
  "devDependencies": {
142
143
  "@changesets/cli": "2.31.1",
@@ -248,7 +248,7 @@ Step 0 creates the workspace; all intermediate artifacts land under `.peaks/_run
248
248
 
249
249
  ## Peaks-Loop Pre-RD project scan checklist (MANDATORY)
250
250
 
251
- Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/project-scan/project-scan.md` (project-level, git-tracked; sibling of `.peaks/PROJECT.md`). Slice 2026-07-15-project-scan-bootstrap (G1 + G2): `peaks workspace init` and `peaks project context` both bootstrap this file automatically; only re-run the manual flow when the scan output is genuinely out of date. → `references/project-scan-checklist.md`.
251
+ Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/project-scan/project-scan.md` (project-level, git-tracked; sibling of `.peaks/PROJECT.md`). Slice 2026-07-15-project-scan-bootstrap (G1 + G2): `peaks workspace init` and `peaks project context` both bootstrap this file automatically. `peaks project context` also refreshes its machine fields (`capturedAt` / `techStack` / `libraryVersions`) in place on every run, leaving the prose alone; only re-run the manual flow when the SCAN ITSELF (archetype / project mode) is genuinely out of date. → `references/project-scan-checklist.md`.
252
252
 
253
253
  > **Slice 2026-07-15-project-scan-bootstrap G4b / AC9:** after `peaks workspace init`, the consumer project's `.peaks/project-scan/` directory carries 5 files: `project-scan.md` (generated by the scan logic) + `business-knowledge.md` + `security-template.md` + `perf-template.md` + `audit-output-schema.md` (the 4 audit/business templates bundled at `src/services/workspace/templates/project-scan/*.md`, copied on init; idempotent — existing files preserved unless `--force-project-scan-templates`). RD / UI / TXT / QA read from this tree; nothing else.
254
254
 
@@ -4,7 +4,9 @@
4
4
 
5
5
  Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/project-scan/project-scan.md` (project-level, git-tracked; sibling of `.peaks/PROJECT.md`). RD and UI roles read this before starting work. **project-scan.md is a project-scoped singleton** — check if it already exists before regenerating (e.g. via `ls .peaks/project-scan/project-scan.md`). If it exists and is complete (has `## Archetype` and `## Project mode` sections), reuse it. Only regenerate if missing or incomplete.
6
6
 
7
- > **Slice 2026-07-15-project-scan-bootstrap (G1 + G2 + G4b):** `peaks workspace init` and `peaks project context` now both bootstrap `.peaks/project-scan/project-scan.md` automatically. On a brand-new 0-1 project (no `package.json` or no source files) the file is seeded with `archetype: unknown` + `(empty)` placeholder rows. On an existing project it is filled from `peaks scan archetype` + `peaks scan libraries` output. Idempotent — re-running `workspace init` does NOT overwrite the existing file unless `--force` is passed.
7
+ > **Slice 2026-07-15-project-scan-bootstrap (G1 + G2 + G4b):** `peaks workspace init` and `peaks project context` now both bootstrap `.peaks/project-scan/project-scan.md` automatically. On a brand-new 0-1 project (no `package.json` or no source files) the file is seeded with `archetype: unknown` + `(empty)` placeholder rows. On an existing project it is filled from `peaks scan archetype` + `peaks scan libraries` output.
8
+ >
9
+ > **Refresh semantics (2026-11-15):** the file is never REGENERATED once it exists — its markdown body is sediment. What a refresh does is rewrite only its three machine-derivable frontmatter fields (`capturedAt`, `techStack`, `libraryVersions`) in place, preserving every other byte. `peaks project context --project <repo>` does that by default; `--no-project-scan-refresh` opts out. A file that was never populated (empty `architecture` AND empty `techStack`) is filled automatically, because it carries no sediment to protect. `peaks workspace init` keeps its skip semantics, and `--force-project-scan-templates` governs only the 4 bundled audit/business templates.
8
10
 
9
11
  ### 0. Project archetype detection (MANDATORY — run FIRST, deterministic CLI)
10
12
 
@@ -115,8 +115,8 @@ All artifact-producing subcommands require `--session-id <sid>` (one-axis envelo
115
115
 
116
116
  | Subcommand | Flags | What it writes | Exit code |
117
117
  | ---------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
118
- | `run` | `--project <path> --test-files <files...> [--mutate <patterns...>] --input-sig <hex> --session-id <sid> --out <path> [--json]` | full `MutReportJson` (mutation + assertions + followups) | `1` if `thresholds.passed === false` |
119
- | `mutants` | `--project <path> --test-files <files...> [--mutate <patterns...>] --input-sig <hex> --session-id <sid> --out <path> [--json]` | full `MutReportJson` with empty assertions | `1` if `thresholds.passed === false` |
118
+ | `run` | `--project <path> --test-files <files...> [--mutate <patterns...>] [--ignore <patterns...>] --input-sig <hex> --session-id <sid> --out <path> [--json]` | full `MutReportJson` (mutation + assertions + followups) | `1` if `thresholds.passed === false` |
119
+ | `mutants` | `--project <path> --test-files <files...> [--mutate <patterns...>] [--ignore <patterns...>] --input-sig <hex> --session-id <sid> --out <path> [--json]` | full `MutReportJson` with empty assertions | `1` if `thresholds.passed === false` |
120
120
  | `asserts` | `--project <path> --test-files <files...> --input-sig <hex> --session-id <sid> --out <path> [--json]` | full `MutReportJson` with empty mutation | `1` if `thresholds.passed === false` |
121
121
  | `report` | `--in <path> --session-id <sid> [--json]` | nothing on disk — re-emits a one-line summary | `1` if input report's `thresholds.passed === false`; `2` on invalid JSON or schema failure |
122
122
 
@@ -132,6 +132,10 @@ MEASURED: `peaks mut asserts` writes an **empty** mutation block, so its `mutati
132
132
 
133
133
  The Stryker configuration is **built programmatically** by the CLI (`peaks-loop-mut` → `buildStrykerOptions`): the test runner, the timing, the coverage mode and the mutation scope all come from the flags. A project-root `stryker.conf.js` is **optional** — a backwards-compatible fallback for projects that already ship one. When one exists, the CLI's own options win over it (Stryker deep-merges the CLI options over the config file).
134
134
 
135
+ `--ignore <patterns...>` names paths that must **not** be copied into the Stryker sandbox (repeatable: `--ignore .peaks --ignore dist`). It is optional and empty by default; the builder always appends `.stryker-tmp`, because the sandbox must never be copied into itself. Use it on a repository whose gitignored directories hold symlinks or junction fixtures: Stryker copies the whole project into `.stryker-tmp/sandbox-*`, and such a tree makes that copy fail with `EPERM` unless it is ignored.
136
+
137
+ When a Stryker run fails, the CLI writes `<out dir>/stryker-failure.log` — the error chain plus the log Stryker itself wrote — and names that absolute path in the envelope's `data.diagnosticPath` and `nextActions`. Stryker's console log is off (stdout belongs to `--json`), so this file is the only place the real reason appears: `Something went wrong in the initial test run` is Stryker's bare summary, not a diagnosis. A successful run writes no diagnostic.
138
+
135
139
  Named error codes the mut family can emit:
136
140
 
137
141
  | Code | Meaning |
@@ -1,8 +0,0 @@
1
- export type GitWorktreeRecord = {
2
- readonly path: string;
3
- readonly head: string | null;
4
- readonly branch: string | null;
5
- readonly prunable: boolean;
6
- };
7
- export declare function parseGitWorktreePorcelain(raw: string): ReadonlyArray<GitWorktreeRecord>;
8
- export declare function isPathInside(parent: string, candidate: string): boolean;
@@ -1,55 +0,0 @@
1
- import { relative, resolve, sep } from 'node:path';
2
- export function parseGitWorktreePorcelain(raw) {
3
- const records = [];
4
- let current = null;
5
- const flush = () => {
6
- if (current !== null) {
7
- records.push({
8
- path: current.path,
9
- head: current.head,
10
- branch: current.branch,
11
- prunable: current.prunable
12
- });
13
- }
14
- current = null;
15
- };
16
- for (const line of raw.split(/\r?\n/)) {
17
- if (line.length === 0) {
18
- flush();
19
- continue;
20
- }
21
- const space = line.indexOf(' ');
22
- const key = space === -1 ? line : line.slice(0, space);
23
- const value = space === -1 ? '' : line.slice(space + 1);
24
- if (key === 'worktree') {
25
- flush();
26
- const next = { path: value, head: null, branch: null, prunable: false };
27
- current = next;
28
- }
29
- else if (current !== null && key === 'HEAD') {
30
- current = {
31
- path: current.path,
32
- head: value,
33
- branch: current.branch,
34
- prunable: current.prunable
35
- };
36
- }
37
- else if (current !== null && key === 'branch') {
38
- current = {
39
- path: current.path,
40
- head: current.head,
41
- branch: value.replace(/^refs\/heads\//, ''),
42
- prunable: current.prunable
43
- };
44
- }
45
- else if (current !== null && key === 'prunable') {
46
- current = { path: current.path, head: current.head, branch: current.branch, prunable: true };
47
- }
48
- }
49
- flush();
50
- return records;
51
- }
52
- export function isPathInside(parent, candidate) {
53
- const rel = relative(resolve(parent), resolve(candidate));
54
- return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep));
55
- }
@@ -1,52 +0,0 @@
1
- /**
2
- * worktree-lease-types — the pure declaration surface of the worktree lease
3
- * store (`worktree-lease.ts`).
4
- *
5
- * module owns only the shapes (lifecycle status, lease record, creation draft,
6
- * and the list-read result). `worktree-lease.ts` imports and re-exports every
7
- * name here, so importers keep resolving them from the original path.
8
- */
9
- export type WorktreeLeaseStatus = 'active' | 'released' | 'expired' | 'gc';
10
- export interface WorktreeLease {
11
- /** Random 16-hex lease id; emitted to the operator as the lease handle. */
12
- readonly leaseId: string;
13
- /** The peaks request id (rid) that the lease was spawned for. */
14
- readonly rid: string;
15
- /** Sub-agent role (rd | qa | ui | sc | prd | general-purpose | ...). */
16
- readonly role: string;
17
- /** Absolute worktree path on disk (under .peaks/_runtime/<sid>/worktrees/<leaseId>/). */
18
- readonly path: string;
19
- /** Branch name (one of the worktree's --branch / -b args). */
20
- readonly branch: string;
21
- /** Unix epoch ms when the lease was created. */
22
- readonly createdAt: number;
23
- /** Unix epoch ms when the lease expires. */
24
- readonly expiresAt: number;
25
- /** Operator-supplied purpose text (audit log). */
26
- readonly purpose: string;
27
- /** Lifecycle status; updated by `releaseLease` / `markExpired`. */
28
- readonly status: WorktreeLeaseStatus;
29
- /** Sub-agent batch / dispatch ids that have consumed this lease. */
30
- readonly consumedBySubAgents: ReadonlyArray<string>;
31
- }
32
- /** Subset of WorktreeLease that the CLI writes on creation. Status starts at 'active'. */
33
- export type WorktreeLeaseDraft = Omit<WorktreeLease, 'status' | 'consumedBySubAgents'>;
34
- /**
35
- * Pure: read every lease file under the session's lease store dir.
36
- * Returns leases in the order returned by `fs.readdir` (no sort).
37
- * Malformed files are surfaced as `{ file, error }` records so the caller
38
- * (the `list` CLI) can warn without aborting the whole list. Missing
39
- * directory is not an error — it returns an empty leases array.
40
- */
41
- export interface LeaseReadError {
42
- readonly file: string;
43
- readonly error: string;
44
- }
45
- export type LeaseListResult = {
46
- readonly kind: 'ok';
47
- readonly leases: ReadonlyArray<WorktreeLease>;
48
- readonly errors: ReadonlyArray<LeaseReadError>;
49
- } | {
50
- readonly kind: 'store-missing';
51
- readonly storeDir: string;
52
- };
@@ -1,9 +0,0 @@
1
- /**
2
- * worktree-lease-types — the pure declaration surface of the worktree lease
3
- * store (`worktree-lease.ts`).
4
- *
5
- * module owns only the shapes (lifecycle status, lease record, creation draft,
6
- * and the list-read result). `worktree-lease.ts` imports and re-exports every
7
- * name here, so importers keep resolving them from the original path.
8
- */
9
- export {};