peaks-loop 4.1.16 → 4.1.18

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 (48) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +193 -0
  3. package/dist/cli/commands/code-auto-compact-command.js +46 -23
  4. package/dist/cli/commands/code-auto-compact-deferral.d.ts +34 -0
  5. package/dist/cli/commands/code-auto-compact-deferral.js +59 -0
  6. package/dist/cli/commands/code-gate-command.d.ts +4 -4
  7. package/dist/cli/commands/code-gate-command.js +4 -4
  8. package/dist/cli/commands/core/skill-registry-commands.js +32 -0
  9. package/dist/cli/commands/core/skill-store-report.d.ts +8 -0
  10. package/dist/cli/commands/core/skill-store-report.js +79 -0
  11. package/dist/cli/commands/dispatch-prompt-composition.js +7 -2
  12. package/dist/cli/commands/dispatch-scratch-path-block.d.ts +73 -0
  13. package/dist/cli/commands/dispatch-scratch-path-block.js +131 -0
  14. package/dist/cli/commands/hooks-commands.js +36 -7
  15. package/dist/cli/commands/hooks-uninstall-command.js +5 -5
  16. package/dist/services/code/auto-compact-orchestrator.js +7 -5
  17. package/dist/services/code/auto-compact-run-types.d.ts +8 -4
  18. package/dist/services/dispatch/dispatch-ledger-reader.d.ts +13 -0
  19. package/dist/services/dispatch/dispatch-ledger-reader.js +164 -0
  20. package/dist/services/doctor/doctor-service/checks/canonical-store-version.d.ts +57 -0
  21. package/dist/services/doctor/doctor-service/checks/canonical-store-version.js +190 -0
  22. package/dist/services/doctor/doctor-service/plugin-registry.js +2 -0
  23. package/dist/services/doctor/doctor-service/types.d.ts +12 -0
  24. package/dist/services/hooks/gate-path-normalize.d.ts +37 -0
  25. package/dist/services/hooks/gate-path-normalize.js +74 -4
  26. package/dist/services/hooks/hook-payload-cwd.js +25 -9
  27. package/dist/services/hooks/pre-tool-code-gate.d.ts +24 -4
  28. package/dist/services/hooks/pre-tool-code-gate.js +72 -22
  29. package/dist/services/session/getSessionDir.d.ts +13 -0
  30. package/dist/services/session/getSessionDir.js +7 -1
  31. package/dist/services/skills/hooks-settings-types.d.ts +17 -21
  32. package/dist/services/skills/sync-service-support.d.ts +27 -0
  33. package/dist/services/skills/sync-service.js +1 -0
  34. package/dist/services/workflow/workflow-inflight-probe.d.ts +68 -31
  35. package/dist/services/workflow/workflow-inflight-probe.js +163 -75
  36. package/package.json +7 -5
  37. package/scripts/canonical-store-fs.mjs +112 -0
  38. package/scripts/canonical-store-link.mjs +13 -22
  39. package/scripts/canonical-store-marker.mjs +241 -0
  40. package/scripts/canonical-store.mjs +119 -141
  41. package/scripts/install-skills-bundles.mjs +56 -13
  42. package/scripts/install-skills-fs.mjs +73 -0
  43. package/scripts/install-skills-output-styles.mjs +8 -2
  44. package/scripts/install-skills-report.mjs +19 -0
  45. package/scripts/install-skills.mjs +9 -0
  46. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +20 -1
  47. package/skills/peaks-code/SKILL.md +1 -1
  48. package/skills/peaks-race-code/SKILL.md +6 -3
@@ -12,6 +12,7 @@ import { computeUiLibraryDispatchBlock } from '../../services/standards/ui-libra
12
12
  import { readFreshContextBlock } from '../../services/fresh-context/fresh-context-block.js';
13
13
  import { deprecatedReviewerWarnings } from './sub-agent-shared.js';
14
14
  import { buildIsolationBlock, buildMustLsFilesBlock } from './dispatch-prompt-blocks.js';
15
+ import { buildScratchPathInjection } from './dispatch-scratch-path-block.js';
15
16
  import { ensureArtifactContractBlock, readArtifactContractBlock } from '../../services/artifacts/artifact-contract-block.js';
16
17
  import { ensureKarpathyBlock } from '../../services/dispatch/karpathy-block.js';
17
18
  import { cliInvocationWarnings } from './dispatch-cli-invocation-check.js';
@@ -173,12 +174,15 @@ export async function composeDispatchPrompt(io, input) {
173
174
  requestId: rid,
174
175
  role
175
176
  });
177
+ // The scratch path for this dispatch: an ABSOLUTE directory, so a redirect
178
+ // into it cannot depend on the cwd the sub-agent happens to be in.
179
+ const scratch = buildScratchPathInjection({ projectRoot, sid, role });
176
180
  // The presence test runs on the ASSEMBLED prompt, not on the caller's draft:
177
181
  // this string is what the sub-agent receives as `toolCall.args.prompt` and
178
182
  // what the dispatch record stores as `prompt`. A draft that merely names
179
183
  // Karpathy (or carries a copy with a word wrong) does not count as carrying
180
184
  // the canonical block, so the block is added rather than trusted.
181
- const effectivePrompt = ensureKarpathyBlock(ensureArtifactContractBlock(`${memoryAugmentedBody}${isolationBlock}${mustLsFilesBlock}`, contractBlock));
185
+ const effectivePrompt = ensureKarpathyBlock(ensureArtifactContractBlock(`${memoryAugmentedBody}${isolationBlock}${mustLsFilesBlock}${scratch.block}`, contractBlock));
182
186
  // Findings travel as WARNINGS, never as a refusal, and they are read off the
183
187
  // CALLER's prompt rather than the assembled one — both decisions are measured
184
188
  // and recorded on `dispatch-cli-invocation-check.ts`.
@@ -187,7 +191,8 @@ export async function composeDispatchPrompt(io, input) {
187
191
  const warnings = [
188
192
  ...decision.warnings,
189
193
  ...deprecatedReviewerWarnings(role),
190
- ...invocationWarnings
194
+ ...invocationWarnings,
195
+ ...(scratch.warning === null ? [] : [scratch.warning])
191
196
  ];
192
197
  return { adapter, effectivePrompt, warnings, mustLsFilesVerification };
193
198
  }
@@ -0,0 +1,73 @@
1
+ /** The heading the block carries, and the marker a reader looks for. */
2
+ export declare const SCRATCH_PATH_BLOCK_HEADING = "Scratch path (REQUIRED \u2014 absolute path; never a cwd-relative redirect)";
3
+ /** Where the absolute path goes in the template. */
4
+ export declare const SCRATCH_DIR_PLACEHOLDER = "{{scratchDir}}";
5
+ /**
6
+ * The canonical block, verbatim, with the path left as a placeholder: the
7
+ * path differs for every dispatch, so the template is what can be pinned
8
+ * against the reference file's fenced copy.
9
+ */
10
+ export declare const SCRATCH_PATH_BLOCK_TEMPLATE = "Scratch path (REQUIRED \u2014 absolute path; never a cwd-relative redirect)\n\nWrite every temporary file for this task under this ABSOLUTE path:\n{{scratchDir}}\n\nNever redirect to a path that depends on the working directory \u2014 `2> out.err`, `> run.log`, `./scratch/`. A cwd-relative redirect writes wherever the task happens to `cd`: measured 2026-10-02, five zero-byte `*.err` captures landed at the repository root and were committed, and `git status` stayed clean because the files were tracked. Use the absolute path above; it lives under the session's runtime dir, which is gitignored, so nothing written there can be committed by accident.\n";
11
+ /**
12
+ * The path in the form every shell accepts: forward slashes on every
13
+ * platform.
14
+ *
15
+ * A Windows path spelled with backslashes is an ESCAPE SEQUENCE to a POSIX
16
+ * shell — `> D:\repo\x.log` there writes a file named `D:repox.log` into the
17
+ * CURRENT directory, which is the exact leak this block exists to stop. The
18
+ * forward-slash form is accepted by bash, cmd, PowerShell and Node alike.
19
+ */
20
+ export declare function toShellPath(path: string): string;
21
+ /**
22
+ * The absolute scratch directory for one dispatch.
23
+ *
24
+ * Pure, and independent of the working directory: the only input that is not
25
+ * the project root and the two id segments is the filesystem separator. A
26
+ * RELATIVE project root is resolved against the cwd — the dispatch CLI passes
27
+ * an absolute one (`options.project ?? process.cwd()`), and the emitted path
28
+ * is absolute either way.
29
+ */
30
+ export declare function resolveScratchDir(projectRoot: string, sid: string, role: string): string;
31
+ /**
32
+ * The block for one dispatch, with the absolute path substituted.
33
+ *
34
+ * Pure. The replacement is done with a FUNCTION so a path that contains a
35
+ * `$` sequence is inserted literally rather than read as a replacement
36
+ * pattern.
37
+ */
38
+ export declare function buildScratchPathBlock(scratchDir: string): string;
39
+ /** The outcome of creating the scratch directory. */
40
+ export type ScratchDirState = {
41
+ readonly ok: true;
42
+ } | {
43
+ readonly ok: false;
44
+ readonly reason: string;
45
+ };
46
+ /**
47
+ * Create the scratch directory so the FIRST redirect into it works.
48
+ *
49
+ * A redirect into a directory that does not exist fails, and an agent that
50
+ * hits that failure is an agent that may fall back to a cwd-relative path —
51
+ * the leak this block exists to stop. The failure is reported rather than
52
+ * swallowed: the caller turns it into a dispatch warning, so a scratch
53
+ * directory that could not be created is visible instead of silent.
54
+ */
55
+ export declare function ensureScratchDir(scratchDir: string): ScratchDirState;
56
+ /** What one dispatch's prompt gains. */
57
+ export type ScratchPathInjection = {
58
+ /** The block, with the absolute path substituted. */
59
+ readonly block: string;
60
+ /** The absolute scratch directory, with the platform's own separators. */
61
+ readonly scratchDir: string;
62
+ /** Null when the directory exists; the reason when it does not. */
63
+ readonly warning: string | null;
64
+ };
65
+ /**
66
+ * The scratch-path block for one dispatch, and the one side effect that makes
67
+ * it usable: the directory is created so the first redirect into it works.
68
+ */
69
+ export declare function buildScratchPathInjection(input: {
70
+ projectRoot: string;
71
+ sid: string;
72
+ role: string;
73
+ }): ScratchPathInjection;
@@ -0,0 +1,131 @@
1
+ /**
2
+ * The scratch-path block: the ABSOLUTE directory a dispatched sub-agent writes
3
+ * its temporary files to, machine-injected into every dispatch prompt.
4
+ *
5
+ * WHY THIS MODULE EXISTS. The rule "a leaf's scratch must not depend on the
6
+ * cwd it happens to be in" lived only as prose in an orchestrator's brief, so
7
+ * it was exactly as strong as the orchestrator's memory at 3am. Measured
8
+ * 2026-10-02: five zero-byte `*.err` captures — the `2> name.err` of five
9
+ * per-file test runs — landed at the repository root and were COMMITTED;
10
+ * `git status` stayed clean because the files were tracked, and neither the
11
+ * file-size census nor eslint reads a `.err`. An obligation a busy caller can
12
+ * forget is not an executor; this is the same shape as the Karpathy block
13
+ * (`src/services/dispatch/karpathy-block.ts`), which replaced the same class
14
+ * of prose obligation for the same reason.
15
+ *
16
+ * SOURCE OF TRUTH: the fenced block in
17
+ * `skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md` is the canonical
18
+ * human-facing text; `SCRATCH_PATH_BLOCK_TEMPLATE` below is its machine copy,
19
+ * and `tests/unit/cli/commands/dispatch-scratch-path-block.test.ts` asserts
20
+ * the two are byte-equal, so the copy cannot drift silently. A second copy
21
+ * that CAN drift is the same defect class as the dropped block; a pinned one
22
+ * is not.
23
+ *
24
+ * WHY THE PATH IS ABSOLUTE, AND WHY IT IS THIS SHAPE.
25
+ * - Absolute: a redirect that depends on the cwd writes wherever the task
26
+ * happens to `cd`. The path is derived from the project root alone.
27
+ * - Under the session's runtime dir (`.peaks/_runtime/<sessionId>/<role>/`):
28
+ * the shape the backlog names, and the runtime tree is gitignored, so a
29
+ * stray capture written there can never be committed by accident.
30
+ * - Per role: two leaves dispatched in parallel get two directories, so
31
+ * their captures cannot collide.
32
+ *
33
+ * The block is injected for EVERY role and regardless of which optional
34
+ * blocks a dispatch carries: the point of the block is that the rule is not
35
+ * per-brief.
36
+ */
37
+ import { mkdirSync } from 'node:fs';
38
+ import { join, resolve } from 'node:path';
39
+ import { getSessionDir, isSinglePathSegment } from '../../services/session/getSessionDir.js';
40
+ /** The heading the block carries, and the marker a reader looks for. */
41
+ export const SCRATCH_PATH_BLOCK_HEADING = 'Scratch path (REQUIRED — absolute path; never a cwd-relative redirect)';
42
+ /** Where the absolute path goes in the template. */
43
+ export const SCRATCH_DIR_PLACEHOLDER = '{{scratchDir}}';
44
+ /**
45
+ * The canonical block, verbatim, with the path left as a placeholder: the
46
+ * path differs for every dispatch, so the template is what can be pinned
47
+ * against the reference file's fenced copy.
48
+ */
49
+ export const SCRATCH_PATH_BLOCK_TEMPLATE = `${SCRATCH_PATH_BLOCK_HEADING}
50
+
51
+ Write every temporary file for this task under this ABSOLUTE path:
52
+ ${SCRATCH_DIR_PLACEHOLDER}
53
+
54
+ Never redirect to a path that depends on the working directory — \`2> out.err\`, \`> run.log\`, \`./scratch/\`. A cwd-relative redirect writes wherever the task happens to \`cd\`: measured 2026-10-02, five zero-byte \`*.err\` captures landed at the repository root and were committed, and \`git status\` stayed clean because the files were tracked. Use the absolute path above; it lives under the session's runtime dir, which is gitignored, so nothing written there can be committed by accident.
55
+ `;
56
+ /** The session id the dispatch context itself uses when none is bound. */
57
+ const UNKNOWN_SESSION_ID = 'unknown-sid';
58
+ /** The role segment used when the role is not a single safe path segment. */
59
+ const UNKNOWN_ROLE = 'unknown-role';
60
+ /**
61
+ * The path in the form every shell accepts: forward slashes on every
62
+ * platform.
63
+ *
64
+ * A Windows path spelled with backslashes is an ESCAPE SEQUENCE to a POSIX
65
+ * shell — `> D:\repo\x.log` there writes a file named `D:repox.log` into the
66
+ * CURRENT directory, which is the exact leak this block exists to stop. The
67
+ * forward-slash form is accepted by bash, cmd, PowerShell and Node alike.
68
+ */
69
+ export function toShellPath(path) {
70
+ return path.split('\\').join('/');
71
+ }
72
+ /**
73
+ * The absolute scratch directory for one dispatch.
74
+ *
75
+ * Pure, and independent of the working directory: the only input that is not
76
+ * the project root and the two id segments is the filesystem separator. A
77
+ * RELATIVE project root is resolved against the cwd — the dispatch CLI passes
78
+ * an absolute one (`options.project ?? process.cwd()`), and the emitted path
79
+ * is absolute either way.
80
+ */
81
+ export function resolveScratchDir(projectRoot, sid, role) {
82
+ const root = resolve(projectRoot);
83
+ const sessionId = isSinglePathSegment(sid) ? sid : UNKNOWN_SESSION_ID;
84
+ const roleSegment = isSinglePathSegment(role) ? role : UNKNOWN_ROLE;
85
+ return join(getSessionDir(root, sessionId), roleSegment, 'scratch');
86
+ }
87
+ /**
88
+ * The block for one dispatch, with the absolute path substituted.
89
+ *
90
+ * Pure. The replacement is done with a FUNCTION so a path that contains a
91
+ * `$` sequence is inserted literally rather than read as a replacement
92
+ * pattern.
93
+ */
94
+ export function buildScratchPathBlock(scratchDir) {
95
+ return SCRATCH_PATH_BLOCK_TEMPLATE.replace(SCRATCH_DIR_PLACEHOLDER, () => toShellPath(scratchDir));
96
+ }
97
+ /**
98
+ * Create the scratch directory so the FIRST redirect into it works.
99
+ *
100
+ * A redirect into a directory that does not exist fails, and an agent that
101
+ * hits that failure is an agent that may fall back to a cwd-relative path —
102
+ * the leak this block exists to stop. The failure is reported rather than
103
+ * swallowed: the caller turns it into a dispatch warning, so a scratch
104
+ * directory that could not be created is visible instead of silent.
105
+ */
106
+ export function ensureScratchDir(scratchDir) {
107
+ try {
108
+ mkdirSync(scratchDir, { recursive: true });
109
+ return { ok: true };
110
+ }
111
+ catch (error) {
112
+ return { ok: false, reason: error instanceof Error ? error.message : String(error) };
113
+ }
114
+ }
115
+ /**
116
+ * The scratch-path block for one dispatch, and the one side effect that makes
117
+ * it usable: the directory is created so the first redirect into it works.
118
+ */
119
+ export function buildScratchPathInjection(input) {
120
+ const scratchDir = resolveScratchDir(input.projectRoot, input.sid, input.role);
121
+ const state = ensureScratchDir(scratchDir);
122
+ return {
123
+ scratchDir,
124
+ block: buildScratchPathBlock(scratchDir),
125
+ warning: state.ok === true
126
+ ? null
127
+ : `scratch directory could not be created (${state.reason}); the sub-agent must ` +
128
+ 'create it before writing scratch into it, and must not fall back to a ' +
129
+ 'cwd-relative path'
130
+ };
131
+ }
@@ -18,7 +18,7 @@
18
18
  * `hooks-install-envelopes.ts`, and the scope / IDE resolution in
19
19
  * `hooks-command-shared.ts`.
20
20
  */
21
- import { existsSync, copyFileSync, mkdirSync } from 'node:fs';
21
+ import { existsSync, copyFileSync, mkdirSync, writeFileSync } from 'node:fs';
22
22
  import { dirname, resolve } from 'node:path';
23
23
  import { fileURLToPath } from 'node:url';
24
24
  import { resolveIdeOptionHelp } from '../../services/ide/ide-registry.js';
@@ -76,15 +76,43 @@ function copyBridgeHookIfPresent(userHome, dryRun = false) {
76
76
  copyFileSync(source, target);
77
77
  return { copied: true, source, target };
78
78
  }
79
+ /**
80
+ * The sibling file the copied code-gate wrapper reads to find the CLI.
81
+ *
82
+ * The wrapper is a THIN WRAPPER over the Node command: where a CLI is
83
+ * reachable it execs `peaks code-gate`, so there is one implementation of the
84
+ * rule wherever Node exists. It looks for that CLI in two places — `peaks` on
85
+ * PATH, and this file. What this file carries is the PACKAGE ROOT, which is
86
+ * INSTALLER information (where the installed package lives), not PROJECT
87
+ * information: the project root is per-project and one user-global copy of
88
+ * the wrapper serves every project, so it cannot be stored here.
89
+ */
90
+ const CODE_GATE_PACKAGE_ROOT_FILE = 'pre-tool-code-gate.package-root';
91
+ /**
92
+ * The package root this CLI was loaded from: `<root>/src/cli/commands` in the
93
+ * source tree, `<root>/dist/cli/commands` in a build. Three levels up is the
94
+ * root in both, and it is the directory that holds `bin/peaks.js`.
95
+ */
96
+ const PACKAGE_ROOT = resolve(MODULE_DIR, '..', '..', '..');
97
+ /**
98
+ * Write the package-root pointer next to the copied wrapper.
99
+ *
100
+ * It is written next to the script and NOT inside it: the script is copied
101
+ * once, byte for byte, and the pointer is a separate file the wrapper reads
102
+ * at run time. A dry-run install writes nothing.
103
+ */
104
+ function writeCodeGatePackageRootPointer(hooksDir) {
105
+ writeFileSync(resolve(hooksDir, CODE_GATE_PACKAGE_ROOT_FILE), `${PACKAGE_ROOT}\n`, 'utf8');
106
+ }
79
107
  /**
80
108
  * The same distribution for the code-gate hook
81
109
  * source (`src/services/hooks/pre-tool-code-gate.sh`) into the user-
82
110
  * global peaks-code hooks dir, mirroring the bridge-hook copy. The
83
- * hook itself is vendor-neutral (no `claude` / `anthropic` strings in
84
- * the script) — this installer is the vendor adapter that decides
111
+ * hook itself is vendor-neutral (no IDE / vendor names in the
112
+ * script) — this installer is the vendor adapter that decides
85
113
  * where the file lands. The CLI command `peaks code-gate` is the
86
114
  * runtime entry; the shell script is the canonical artifact distributed
87
- * alongside the bridge hook.
115
+ * alongside the bridge hook, and it is a thin wrapper over that command.
88
116
  */
89
117
  function copyCodeGateHookIfPresent(userHome, dryRun = false) {
90
118
  const source = resolve(MODULE_DIR, '..', '..', 'services', 'hooks', 'pre-tool-code-gate.sh');
@@ -97,6 +125,7 @@ function copyCodeGateHookIfPresent(userHome, dryRun = false) {
97
125
  }
98
126
  mkdirSync(dirname(target), { recursive: true });
99
127
  copyFileSync(source, target);
128
+ writeCodeGatePackageRootPointer(dirname(target));
100
129
  return { copied: true, source, target };
101
130
  }
102
131
  /** The `{ copied: false, source: '', target: '' }` a non-global scope reports. */
@@ -138,15 +167,15 @@ function runHooksInstall(io, options) {
138
167
  export function registerHooksCommands(program, io) {
139
168
  const hooks = program
140
169
  .command('hooks')
141
- .description("Manage the Peaks-managed hook entry in the adapter's settings.json (default: .claude/settings.json for Claude, .trae/settings.json for Trae). Slice #014: the only installed entry is the gate-enforce hook (SOP gate). The legacy progress-start hook (auto-spawn sub-agent progress terminal) is no longer installed — sub-agent progress is now surfaced via the dispatch + heartbeat flow (`peaks sub-agent dispatch` / `peaks sub-agent heartbeat`). The IDE is auto-detected from env / cwd; override with --ide <id>.");
170
+ .description("Manage the Peaks-managed hook entries in the adapter's settings.json (default: .claude/settings.json for Claude, .trae/settings.json for Trae). The installed set is the adapter's own peaks-managed entries — for Claude Code: peaks gate enforce (Bash and MCP tool calls), peaks code-gate (Edit|Write|MultiEdit), peaks outer-cache write, peaks session primer, peaks session reinject, peaks compact settle — plus the Layer-3 permissions.deny entries (worktree governance); the other adapters install their own single hook entry. The legacy progress-start hook (auto-spawn sub-agent progress terminal) is not installed (slice #014) — sub-agent progress is now surfaced via the dispatch + heartbeat flow (`peaks sub-agent dispatch` / `peaks sub-agent heartbeat`). The IDE is auto-detected from env / cwd; override with --ide <id>.");
142
171
  addJsonOption(hooks
143
172
  .command('install')
144
- .description(`Install the peaks-managed gate-enforce hook entry into the adapter's settings.json. Slice #014: only the gate-enforce entry is installed; the legacy progress-start entry is no longer installed. Idempotent: re-runs are no-ops. Project scope by default.`)
173
+ .description(`Install the peaks-managed hook entries into the adapter's settings.json — for Claude Code: peaks gate enforce (Bash and MCP tool calls), peaks code-gate (Edit|Write|MultiEdit), peaks outer-cache write, peaks session primer, peaks session reinject, peaks compact settle — plus the Layer-3 permissions.deny entries (worktree governance); the other adapters install their own single hook entry. The legacy progress-start entry is not installed (slice #014). Idempotent: re-runs are no-ops. Project scope by default. --global additionally copies the two hook scripts (pre-tool-code-gate.sh and pre-tool-superpowers-bridge.sh) and writes the package-root pointer pre-tool-code-gate.package-root into the user-global ~/.claude/skills/peaks-code/hooks/ directory; the project scope copies nothing there.`)
145
174
  .option('--global', 'install into the user-level ~/.claude/settings.json instead of the project')
146
175
  .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
147
176
  .option('--ide <id>', resolveIdeOptionHelp())
148
177
  .option('--dry-run', 'show what would change without writing')
149
- .option('--no-progress', 'skip the progress-start PreToolUse hook entry; install ONLY the gate-enforce entry')).action((options) => runHooksInstall(io, options));
178
+ .option('--no-progress', 'retained for backward compatibility and currently a no-op: the progress-start entry is no longer installed (slice #014), so the installed entry set is identical with or without this flag')).action((options) => runHooksInstall(io, options));
150
179
  registerHooksUninstallCommand(hooks, io);
151
180
  registerHooksStatusCommand(hooks, io);
152
181
  }
@@ -1,9 +1,9 @@
1
1
  // src/cli/commands/hooks-uninstall-command.ts
2
2
  //
3
- // `peaks hooks uninstall` — remove the peaks-managed gate-enforce hook entry
4
- // (and any legacy progress-start entry a pre-#014 install left behind). Split
5
- // out of `hooks-commands.ts`; the verb name, its options and the envelope shape
6
- // are unchanged.
3
+ // `peaks hooks uninstall` — remove the peaks-managed hook entries (the whole
4
+ // set the install writes, plus a legacy progress-start entry an install from
5
+ // before slice #014 left behind). Split out of `hooks-commands.ts`; the verb
6
+ // name, its options and the envelope shape are unchanged.
7
7
  import { listSuperpowersDenyEntries, removeHookInstall } from '../../services/skills/hooks-settings-service.js';
8
8
  import { resolveIdeOptionHelp } from '../../services/ide/ide-registry.js';
9
9
  import { fail, ok } from 'peaks-loop-shared/result';
@@ -36,7 +36,7 @@ function runHooksUninstall(io, options) {
36
36
  export function registerHooksUninstallCommand(hooks, io) {
37
37
  addJsonOption(hooks
38
38
  .command('uninstall')
39
- .description('Remove the peaks-managed gate-enforce hook entry from the target settings.json. Any legacy progress-start entry that a pre-#014 install left behind is also removed (sentinel-based scan). Third-party hooks are preserved.')
39
+ .description('Remove the peaks-managed hook entries from the target settings.json — for Claude Code: peaks gate enforce (Bash and MCP tool calls), peaks code-gate (Edit|Write|MultiEdit), peaks outer-cache write, peaks session primer, peaks session reinject, peaks compact settle — plus the Layer-3 permissions.deny entries (worktree governance); the other adapters remove their own single hook entry. A legacy progress-start entry left behind by an install from before slice #014 is removed too (sentinel-based scan). Third-party hooks are preserved.')
40
40
  .option('--global', 'remove from the user-level ~/.claude/settings.json instead of the project')
41
41
  .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
42
42
  .option('--ide <id>', resolveIdeOptionHelp())).action((options) => runHooksUninstall(io, options));
@@ -173,12 +173,14 @@ async function openRun(input, sessionId, mode) {
173
173
  });
174
174
  const decision = evaluateAutoCompactDecision({
175
175
  ratio: probe.ratio,
176
- // Production `inFlightBatch` MUST come from the graph probe. The legacy boolean is
177
- // preserved as a TEST-ONLY seam: when `probeInflightBatch` is supplied we call it and
178
- // pass an `InFlightBatchProbe`, so the pure decision sees a graph-backed value. The
179
- // CLI gates the boolean behind `PEAKS_TEST_SEAM === '1'`.
176
+ // Production `inFlightBatch` MUST come from the dispatch-ledger probe. The legacy
177
+ // boolean is preserved as a TEST-ONLY seam: when `probeInflightBatch` is supplied we
178
+ // call it and pass an `InFlightBatchProbe`, so the pure decision sees a
179
+ // ledger-backed value. The CLI gates the boolean behind `PEAKS_TEST_SEAM === '1'`.
180
+ // The session resolved above is the one the probe reads, so the two cannot name
181
+ // different sessions.
180
182
  inFlightBatch: input.probeInflightBatch !== undefined
181
- ? { hasInFlightBatch: input.probeInflightBatch() }
183
+ ? { hasInFlightBatch: input.probeInflightBatch(sessionId) }
182
184
  : input.inFlightBatch,
183
185
  force: input.force,
184
186
  bypassRedLine: input.bypassRedLine,
@@ -24,16 +24,20 @@ export interface AutoCompactInput {
24
24
  */
25
25
  readonly inFlightBatch?: InFlightBatchProbe | undefined;
26
26
  /**
27
- * Slice 4.0.8 (D4d): graph-only in-flight probe. When supplied,
28
- * the orchestrator calls this function and uses the boolean
29
- * result as the production `inFlightBatch` signal. The legacy
27
+ * Slice 4.0.8 (D4d): the in-flight probe. When supplied, the
28
+ * orchestrator calls this function with the session it resolved and uses
29
+ * the boolean result as the production `inFlightBatch` signal. The legacy
30
30
  * boolean parameter is suppressed in production callers — the
31
31
  * CLI's `--in-flight-batch` flag is gated behind
32
32
  * `PEAKS_TEST_SEAM === '1'`. The pure decision function
33
33
  * `evaluateAutoCompactDecision` retains the boolean signature
34
34
  * for the test seam + the red-line override.
35
+ *
36
+ * The session id is a parameter because the probe reads that session's
37
+ * dispatch ledger: the orchestrator already resolved the session, and a
38
+ * second resolution could name a different one.
35
39
  */
36
- readonly probeInflightBatch?: (() => boolean) | undefined;
40
+ readonly probeInflightBatch?: ((sessionId: string) => boolean) | undefined;
37
41
  /**
38
42
  * Force execute even when ratio < threshold (test seam). In
39
43
  * production this is always `false` — peaks-loop drives compact
@@ -0,0 +1,13 @@
1
+ import type { LedgerFacts } from '../workflow/workflow-inflight-probe.js';
2
+ export interface DispatchLedgerInput {
3
+ readonly projectRoot: string;
4
+ readonly sessionId: string;
5
+ }
6
+ /**
7
+ * Read one session's dispatch ledger.
8
+ *
9
+ * `absent` when the session has no ledger at all (no dispatch was ever
10
+ * registered), `unreadable` when the index is there but cannot be parsed, and
11
+ * `readable` with one fact per row otherwise.
12
+ */
13
+ export declare function readDispatchLedgerFacts(input: DispatchLedgerInput): LedgerFacts;
@@ -0,0 +1,164 @@
1
+ /**
2
+ * The dispatch-ledger reader: the half of the in-flight probe that touches the
3
+ * filesystem.
4
+ *
5
+ * WHAT IT READS. The session's ledger under `.peaks/_sub_agents/<sid>/`:
6
+ * the `active-dispatches.json` index (which rows are active) and the dispatch
7
+ * record each row names (what those dispatches are doing). The index is the
8
+ * enumeration and the records are the facts, and the two are read separately
9
+ * because only the record carries a lifecycle.
10
+ *
11
+ * WHY THE INDEX ENUMERATES. The index is bounded by the ledger reaper, so a
12
+ * session's index stays small while its records directory grows for the whole
13
+ * retention window. Reading the directory instead would read every record a
14
+ * session ever wrote on every probe.
15
+ *
16
+ * WHAT IT DOES NOT DECIDE. Nothing here says whether a dispatch is in flight.
17
+ * The reader reports facts — a record that is there, a record that is gone, a
18
+ * record that cannot be read — and the pure probe
19
+ * (`../workflow/workflow-inflight-probe.js`) turns them into the answer. That
20
+ * split is what lets the decision be tested without a filesystem.
21
+ *
22
+ * THE DIRECTION OF THE FACTS. A record that cannot be read is reported as
23
+ * unreadable rather than as absent, because "I could not look" and "there is
24
+ * nothing there" are different facts and only one of them may end a deferral.
25
+ */
26
+ import { existsSync, readFileSync } from 'node:fs';
27
+ import { dirname, isAbsolute, resolve } from 'node:path';
28
+ import { activeDispatchIndexPath } from './active-dispatch-index.js';
29
+ import { upgradeRecord } from './dispatch-record-upgrade.js';
30
+ import { assertSafeDispatchRecordPath } from '../security/safe-settings-path.js';
31
+ import { isSinglePathSegment } from '../session/getSessionDir.js';
32
+ /**
33
+ * Read one session's dispatch ledger.
34
+ *
35
+ * `absent` when the session has no ledger at all (no dispatch was ever
36
+ * registered), `unreadable` when the index is there but cannot be parsed, and
37
+ * `readable` with one fact per row otherwise.
38
+ */
39
+ export function readDispatchLedgerFacts(input) {
40
+ // The session id is the last caller-supplied segment of the ledger's path,
41
+ // so it is checked BEFORE the path is built: an id carrying a separator
42
+ // would point this reader outside the project root. A refused id is an
43
+ // unknown, not an absence, so the answer defers.
44
+ if (!isSinglePathSegment(input.sessionId)) {
45
+ return { ledgerState: 'unreadable', dispatches: [] };
46
+ }
47
+ const indexPath = activeDispatchIndexPath(input.projectRoot, input.sessionId);
48
+ if (!existsSync(indexPath))
49
+ return { ledgerState: 'absent', dispatches: [] };
50
+ const rows = readIndexRows(indexPath);
51
+ if (!rows.ok)
52
+ return { ledgerState: 'unreadable', dispatches: [] };
53
+ const ledgerDir = dirname(indexPath);
54
+ const dispatches = rows.recordPaths.map((recordPath) => readDispatchFact(input.projectRoot, ledgerDir, recordPath));
55
+ return { ledgerState: 'readable', dispatches };
56
+ }
57
+ /** The record paths the index names, or the refusal to enumerate them. */
58
+ function readIndexRows(indexPath) {
59
+ let raw;
60
+ try {
61
+ raw = readFileSync(indexPath, 'utf8');
62
+ }
63
+ catch (error) {
64
+ void error;
65
+ return { ok: false };
66
+ }
67
+ let parsed;
68
+ try {
69
+ parsed = JSON.parse(raw);
70
+ }
71
+ catch (error) {
72
+ void error;
73
+ return { ok: false };
74
+ }
75
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
76
+ return { ok: false };
77
+ }
78
+ return { ok: true, recordPaths: Object.keys(parsed) };
79
+ }
80
+ /**
81
+ * The record's path, guarded.
82
+ *
83
+ * A row whose path leaves the ledger is refused here: the row may name a
84
+ * dispatch, but the path it names is not one this session may read, so the
85
+ * facts behind it stay unknown.
86
+ */
87
+ function safeRecordPath(projectRoot, ledgerDir, recordPath) {
88
+ const candidate = isAbsolute(recordPath) ? recordPath : resolve(ledgerDir, recordPath);
89
+ try {
90
+ return assertSafeDispatchRecordPath(candidate, projectRoot);
91
+ }
92
+ catch (error) {
93
+ void error;
94
+ return null;
95
+ }
96
+ }
97
+ /** One row's facts: the record behind it, or why there are none. */
98
+ function readDispatchFact(projectRoot, ledgerDir, recordPath) {
99
+ const safe = safeRecordPath(projectRoot, ledgerDir, recordPath);
100
+ if (safe === null)
101
+ return { kind: 'unreadable', recordPath };
102
+ if (!existsSync(safe))
103
+ return { kind: 'absent', recordPath: safe };
104
+ const parsed = parseRecord(safe);
105
+ if (!parsed.ok)
106
+ return { kind: 'unreadable', recordPath: safe };
107
+ return {
108
+ kind: 'record',
109
+ recordPath: safe,
110
+ status: parsed.status,
111
+ outcome: parsed.outcome,
112
+ lastBeatAt: parsed.lastBeatAt,
113
+ createdAt: parsed.createdAt,
114
+ disposed: parsed.disposed
115
+ };
116
+ }
117
+ /**
118
+ * One record's fields.
119
+ *
120
+ * The record is upgraded through the writer's own reader, so a legacy record
121
+ * is read the same way every other reader reads it and a record from a build
122
+ * this one does not understand is refused rather than half-believed. The
123
+ * STATUS is taken from the raw record rather than from the upgrade: the
124
+ * upgrade maps a status it does not recognise onto `unreadable`, and this
125
+ * reader must be able to tell the probe that the record said something the
126
+ * probe does not know.
127
+ */
128
+ function parseRecord(recordPath) {
129
+ let raw;
130
+ try {
131
+ raw = readFileSync(recordPath, 'utf8');
132
+ }
133
+ catch (error) {
134
+ void error;
135
+ return { ok: false };
136
+ }
137
+ let parsed;
138
+ try {
139
+ parsed = JSON.parse(raw);
140
+ }
141
+ catch (error) {
142
+ void error;
143
+ return { ok: false };
144
+ }
145
+ let upgraded;
146
+ try {
147
+ upgraded = upgradeRecord(parsed);
148
+ }
149
+ catch (error) {
150
+ void error;
151
+ return { ok: false };
152
+ }
153
+ const status = parsed.status;
154
+ if (typeof status !== 'string')
155
+ return { ok: false };
156
+ return {
157
+ ok: true,
158
+ status,
159
+ outcome: upgraded.outcome,
160
+ lastBeatAt: upgraded.lastBeatAt,
161
+ createdAt: upgraded.createdAt,
162
+ disposed: upgraded.disposed
163
+ };
164
+ }
@@ -0,0 +1,57 @@
1
+ /**
2
+ * Check: the canonical skill store against the installed package
3
+ * (`skills:store-version:store`).
4
+ *
5
+ * THE HOLE THIS CLOSES. `skill-reference-parity` compares the canonical store
6
+ * against the IDE trees — and on a normal install the IDE entry is a LINK INTO
7
+ * the store, so the two sides are the SAME tree and the comparison is always in
8
+ * parity. A store frozen at an old release is perfectly self-consistent, and
9
+ * therefore invisible to that check. The comparison this one makes is the other
10
+ * axis: STORE against PACKAGE. The store's sidecar records the version that
11
+ * produced each copy; the package's `package.json#version` is the version that
12
+ * SHOULD have produced it. A gap between them is staleness nothing else can see.
13
+ *
14
+ * THE PATTERN. It is the `dist-source-version` shape applied to the store: a
15
+ * missing input is INFORMATIONAL, never a red — a machine with no store at all
16
+ * has nothing stale, and saying so is not a finding. A store that cannot be
17
+ * read is a different case: it looks exactly like "no drift", so it is
18
+ * reported.
19
+ *
20
+ * IT ALWAYS EMITS A ROW. A check that stays silent when it finds nothing
21
+ * cannot be told apart from a check that never ran; this one says "clean" out
22
+ * loud, with the version it compared against.
23
+ *
24
+ * READ-ONLY. It lists the store and reads sidecars. It never writes, repairs
25
+ * or deletes; the remedy it names (`peaks skill sync`) is the repair.
26
+ */
27
+ import type { DoctorCheckPlugin } from '../types.js';
28
+ /** One managed store entry, and the version its sidecar records. */
29
+ export type CanonicalStoreEntryVersion = {
30
+ readonly name: string;
31
+ /** null when the sidecar records no version — the legacy shape. */
32
+ readonly version: string | null;
33
+ };
34
+ /** What the store holds, compared with the installed package. */
35
+ export type CanonicalStoreVersionInspection = {
36
+ readonly storeRoot: string;
37
+ readonly storePresent: boolean;
38
+ /** False when the store root exists but cannot be listed. */
39
+ readonly readable: boolean;
40
+ /** How many entries the store owns (they carry a `.peaks-managed` sidecar). */
41
+ readonly managed: number;
42
+ readonly entries: readonly CanonicalStoreEntryVersion[];
43
+ /** The entries whose recorded version is behind the installed one. */
44
+ readonly stale: readonly CanonicalStoreEntryVersion[];
45
+ readonly installedVersion: string;
46
+ };
47
+ /** The version a sidecar records, or null when it records none. */
48
+ export declare function readMarkerVersion(markerPath: string): string | null;
49
+ /**
50
+ * The managed entries of one canonical skills store, and the ones behind.
51
+ *
52
+ * `storeRoot` is the canonical SKILLS directory (`<PEAKS_HOME or ~/.peaks>/skills`).
53
+ * An entry the user authored carries no sidecar and is not ours, so it is not
54
+ * counted and never reported.
55
+ */
56
+ export declare function inspectCanonicalStoreVersions(storeRoot: string, installedVersion: string): CanonicalStoreVersionInspection;
57
+ export declare const check: DoctorCheckPlugin;