peaks-loop 4.1.17 → 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 (45) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +143 -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/pre-tool-code-gate.d.ts +4 -4
  25. package/dist/services/hooks/pre-tool-code-gate.js +4 -4
  26. package/dist/services/session/getSessionDir.d.ts +13 -0
  27. package/dist/services/session/getSessionDir.js +7 -1
  28. package/dist/services/skills/hooks-settings-types.d.ts +17 -21
  29. package/dist/services/skills/sync-service-support.d.ts +27 -0
  30. package/dist/services/skills/sync-service.js +1 -0
  31. package/dist/services/workflow/workflow-inflight-probe.d.ts +68 -31
  32. package/dist/services/workflow/workflow-inflight-probe.js +163 -75
  33. package/package.json +7 -5
  34. package/scripts/canonical-store-fs.mjs +112 -0
  35. package/scripts/canonical-store-link.mjs +13 -22
  36. package/scripts/canonical-store-marker.mjs +241 -0
  37. package/scripts/canonical-store.mjs +119 -141
  38. package/scripts/install-skills-bundles.mjs +56 -13
  39. package/scripts/install-skills-fs.mjs +73 -0
  40. package/scripts/install-skills-output-styles.mjs +8 -2
  41. package/scripts/install-skills-report.mjs +19 -0
  42. package/scripts/install-skills.mjs +9 -0
  43. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +20 -1
  44. package/skills/peaks-code/SKILL.md +1 -1
  45. package/skills/peaks-race-code/SKILL.md +6 -3
@@ -0,0 +1,190 @@
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 { existsSync, readdirSync, readFileSync } from 'node:fs';
28
+ import { join } from 'node:path';
29
+ import { CLI_VERSION } from 'peaks-loop-shared/version';
30
+ import { z } from 'zod';
31
+ import { isExpectedFsMiss } from '../../../../shared/fs-utils.js';
32
+ import { tryParseJson } from '../../../../shared/json-parse.js';
33
+ import { compareReleaseVersions } from '../../../artifacts/prerequisite-checks.js';
34
+ import { peaksHome } from '../../../sop/sop-paths.js';
35
+ /** The sidecar shape the store writes. A marker in any other shape is legacy. */
36
+ const markerSchema = z.object({
37
+ format: z.literal('peaks-managed-v2'),
38
+ path: z.string().optional(),
39
+ version: z.string().optional()
40
+ });
41
+ /** The version a sidecar records, or null when it records none. */
42
+ export function readMarkerVersion(markerPath) {
43
+ let content;
44
+ try {
45
+ content = readFileSync(markerPath, 'utf8');
46
+ }
47
+ catch (err) {
48
+ // A sidecar that raced away is "no version"; anything else is a real fault
49
+ // and is not swallowed here.
50
+ if (!isExpectedFsMiss(err))
51
+ throw err;
52
+ return null;
53
+ }
54
+ const parsed = tryParseJson(content, markerSchema);
55
+ if (!parsed.ok)
56
+ return null;
57
+ const version = parsed.value.version;
58
+ return typeof version === 'string' && version.length > 0 ? version : null;
59
+ }
60
+ /**
61
+ * Is the recorded version behind the installed one? An UNKNOWN version is
62
+ * behind: a copy that cannot say how old it is cannot be shown to be current,
63
+ * and the installed package is the authority on what should be there.
64
+ */
65
+ function isBehind(recorded, installed) {
66
+ return compareReleaseVersions(recorded ?? '0.0.0', installed) < 0;
67
+ }
68
+ /**
69
+ * The managed entries of one canonical skills store, and the ones behind.
70
+ *
71
+ * `storeRoot` is the canonical SKILLS directory (`<PEAKS_HOME or ~/.peaks>/skills`).
72
+ * An entry the user authored carries no sidecar and is not ours, so it is not
73
+ * counted and never reported.
74
+ */
75
+ export function inspectCanonicalStoreVersions(storeRoot, installedVersion) {
76
+ if (!existsSync(storeRoot)) {
77
+ return {
78
+ storeRoot,
79
+ storePresent: false,
80
+ readable: true,
81
+ managed: 0,
82
+ entries: [],
83
+ stale: [],
84
+ installedVersion
85
+ };
86
+ }
87
+ let names;
88
+ try {
89
+ names = readdirSync(storeRoot).sort();
90
+ }
91
+ catch (err) {
92
+ // A store root that exists but cannot be listed is not "no drift" — it is
93
+ // a store nobody can check, and it is reported rather than passed over.
94
+ if (!isExpectedFsMiss(err))
95
+ throw err;
96
+ return {
97
+ storeRoot,
98
+ storePresent: true,
99
+ readable: false,
100
+ managed: 0,
101
+ entries: [],
102
+ stale: [],
103
+ installedVersion
104
+ };
105
+ }
106
+ const entries = [];
107
+ for (const name of names) {
108
+ if (name.endsWith('.peaks-managed') || name.startsWith('.peaks-tmp-'))
109
+ continue;
110
+ const markerPath = join(storeRoot, `${name}.peaks-managed`);
111
+ if (!existsSync(markerPath))
112
+ continue;
113
+ entries.push({ name, version: readMarkerVersion(markerPath) });
114
+ }
115
+ const stale = entries.filter((entry) => isBehind(entry.version, installedVersion));
116
+ return {
117
+ storeRoot,
118
+ storePresent: true,
119
+ readable: true,
120
+ managed: entries.length,
121
+ entries,
122
+ stale,
123
+ installedVersion
124
+ };
125
+ }
126
+ /** The canonical skills store, exactly where the store writes it. */
127
+ function canonicalSkillsStore() {
128
+ return join(peaksHome(), 'skills');
129
+ }
130
+ /** How an entry's recorded version reads in a message. */
131
+ function describeEntry(entry) {
132
+ return entry.version === null
133
+ ? `${entry.name} (no version recorded)`
134
+ : `${entry.name} (${entry.version})`;
135
+ }
136
+ function toCheck(inspection) {
137
+ const id = 'skills:store-version:store';
138
+ if (!inspection.storePresent) {
139
+ return {
140
+ id,
141
+ ok: true,
142
+ message: `No canonical skill store at ${inspection.storeRoot}; nothing to compare ` +
143
+ '(run `peaks skill sync` to create one)'
144
+ };
145
+ }
146
+ if (!inspection.readable) {
147
+ return {
148
+ id,
149
+ ok: false,
150
+ severity: 'warning',
151
+ message: `The canonical skill store at ${inspection.storeRoot} cannot be read; ` +
152
+ 'it was not compared with the installed package'
153
+ };
154
+ }
155
+ if (inspection.managed === 0) {
156
+ return {
157
+ id,
158
+ ok: true,
159
+ message: `The canonical skill store at ${inspection.storeRoot} holds no peaks-managed entries; ` +
160
+ 'nothing to compare'
161
+ };
162
+ }
163
+ if (inspection.stale.length === 0) {
164
+ return {
165
+ id,
166
+ ok: true,
167
+ message: `The canonical skill store at ${inspection.storeRoot} is current for all ` +
168
+ `${inspection.managed} managed entries against peaks-loop ${inspection.installedVersion}`
169
+ };
170
+ }
171
+ return {
172
+ id,
173
+ ok: false,
174
+ message: `The canonical skill store at ${inspection.storeRoot} is behind the installed ` +
175
+ `peaks-loop ${inspection.installedVersion}: ${inspection.stale.length} of ` +
176
+ `${inspection.managed} managed entries record an older version ` +
177
+ `(${inspection.stale.map(describeEntry).join(', ')}). ` +
178
+ 'Run `peaks skill sync` to refresh the store.'
179
+ };
180
+ }
181
+ function run({ options }) {
182
+ const injected = options.canonicalStoreVersion;
183
+ const storeRoot = injected?.storeRoot ?? canonicalSkillsStore();
184
+ const installedVersion = injected?.installedVersion ?? CLI_VERSION;
185
+ return [toCheck(inspectCanonicalStoreVersions(storeRoot, installedVersion))];
186
+ }
187
+ export const check = {
188
+ name: 'canonical-store-version',
189
+ run
190
+ };
@@ -35,6 +35,7 @@ import { check as skillParse } from './checks/skill-parse.js';
35
35
  import { check as skillRunbook } from './checks/skill-runbook.js';
36
36
  import { check as skillApplyNote } from './checks/skill-apply-note.js';
37
37
  import { check as skillReferenceParity } from './checks/skill-reference-parity.js';
38
+ import { check as canonicalStoreVersion } from './checks/canonical-store-version.js';
38
39
  import { check as schemaValidity } from './checks/schema-validity.js';
39
40
  import { check as userConfig } from './checks/user-config.js';
40
41
  import { check as skillPresence } from './checks/skill-presence.js';
@@ -66,6 +67,7 @@ export const PLUGINS = [
66
67
  skillRunbook, // id prefix "skill-runbook:"
67
68
  skillApplyNote, // id prefix "skill-apply-note:"
68
69
  skillReferenceParity, // ids "skills:reference-parity:<ide>:<skill>" + "skills:reference-parity:store"
70
+ canonicalStoreVersion, // id "skills:store-version:store" — the store against the installed package
69
71
  schemaValidity, // id prefix "schema:"
70
72
  userConfig, // id "config:user"
71
73
  skillPresence, // ids "skill-presence:current" + "skill-presence:freshness"
@@ -120,6 +120,18 @@ export type DoctorOptions = {
120
120
  skillsDir: string;
121
121
  }>;
122
122
  };
123
+ /**
124
+ * Injected roots/versions for the `skills:store-version` check. When omitted
125
+ * the check binds `$PEAKS_HOME`/`~/.peaks` and the installed release. Tests
126
+ * pass a temp store and a temp version here, so no test reads the real home
127
+ * directory or the real release.
128
+ */
129
+ canonicalStoreVersion?: {
130
+ /** The canonical SKILLS directory (`<root>/skills`). */
131
+ readonly storeRoot: string;
132
+ /** The version to compare the store against. */
133
+ readonly installedVersion: string;
134
+ };
123
135
  /**
124
136
  * root for the L3:l3-memory-health check (defaults to
125
137
  * `findProjectRoot(process.cwd())`). Tests use this to point the
@@ -13,10 +13,10 @@
13
13
  * (.peaks/**, .peaks/_runtime/**, skills/**, docs/**, *.md)
14
14
  * → allow (silent exit 0).
15
15
  *
16
- * Pure function. The shell-script sibling
17
- * (`pre-tool-code-gate.sh`) is the canonical source for the same
18
- * logic, usable from any non-Node harness. Both share the same
19
- * hard-blocked + allow-listed path families.
16
+ * Pure function. This module is the ONE implementation of the rule: the
17
+ * shell-script sibling (`pre-tool-code-gate.sh`) is a thin wrapper that
18
+ * execs the CLI built on it, and its own no-CLI fallback carries a
19
+ * narrower copy of the same families.
20
20
  */
21
21
  import { normalizeGatePath, type GateRoots } from './gate-path-normalize.js';
22
22
  export { normalizeGatePath };
@@ -13,10 +13,10 @@
13
13
  * (.peaks/**, .peaks/_runtime/**, skills/**, docs/**, *.md)
14
14
  * → allow (silent exit 0).
15
15
  *
16
- * Pure function. The shell-script sibling
17
- * (`pre-tool-code-gate.sh`) is the canonical source for the same
18
- * logic, usable from any non-Node harness. Both share the same
19
- * hard-blocked + allow-listed path families.
16
+ * Pure function. This module is the ONE implementation of the rule: the
17
+ * shell-script sibling (`pre-tool-code-gate.sh`) is a thin wrapper that
18
+ * execs the CLI built on it, and its own no-CLI fallback carries a
19
+ * narrower copy of the same families.
20
20
  */
21
21
  import { canonicalGatePath, normalizeGatePath, rootPair } from './gate-path-normalize.js';
22
22
  export { normalizeGatePath };
@@ -1,3 +1,16 @@
1
+ /**
2
+ * The documented contract: one path segment. `isUnsafePathInput` is a
3
+ * traversal guard only and ADMITS `a/b`, so the separator axes are
4
+ * checked here as well. The session dir is ONE directory name under
5
+ * `_runtime/`.
6
+ *
7
+ * EXPORTED because the session id is the last caller-supplied segment of
8
+ * more than one session-scoped path: the runtime dir here, and the dispatch
9
+ * ledger's dir under `.peaks/_sub_agents/` (read by
10
+ * `src/services/dispatch/dispatch-ledger-reader.ts`). One predicate, two
11
+ * users, so the two cannot drift apart.
12
+ */
13
+ export declare function isSinglePathSegment(sessionId: string): boolean;
1
14
  export declare function getSessionDir(projectRoot: string, sessionId: string): string;
2
15
  /**
3
16
  * The TOTAL entry to the same axis. Same predicate, same path; the only
@@ -49,8 +49,14 @@ import { isUnsafePathInput } from '../../shared/path-safety.js';
49
49
  * traversal guard only and ADMITS `a/b`, so the separator axes are
50
50
  * checked here as well. The session dir is ONE directory name under
51
51
  * `_runtime/`.
52
+ *
53
+ * EXPORTED because the session id is the last caller-supplied segment of
54
+ * more than one session-scoped path: the runtime dir here, and the dispatch
55
+ * ledger's dir under `.peaks/_sub_agents/` (read by
56
+ * `src/services/dispatch/dispatch-ledger-reader.ts`). One predicate, two
57
+ * users, so the two cannot drift apart.
52
58
  */
53
- function isSinglePathSegment(sessionId) {
59
+ export function isSinglePathSegment(sessionId) {
54
60
  return !isUnsafePathInput(sessionId) && !sessionId.includes('/') && !sessionId.includes('\\');
55
61
  }
56
62
  export function getSessionDir(projectRoot, sessionId) {
@@ -17,28 +17,24 @@ export type HookInstallOptions = {
17
17
  */
18
18
  readonly ide?: IdeId;
19
19
  /**
20
- * Slice #013 (bugfix — peaks hooks install --no-progress): when `true`,
21
- * skip emitting the progress-start PreToolUse hook entry while still
22
- * installing the gate-enforce entry. The progress-start hook auto-spawns
23
- * a new terminal running `peaks progress watch`; with dispatch +
24
- * heartbeat (slice #009 + #010) that auto-spawn is dead weight. Default
25
- * `false` preserves the pre-slice install shape (both entries). The
26
- * sentinel-based install is idempotent: re-running with `skipProgress:
27
- * true` over a settings.json that previously had the progress entry
28
- * installed will remove that entry. `uninstall` honors the same flag
29
- * so it can find and remove both entries when both are present and
30
- * only the gate-enforce entry when only the gate-enforce is present.
20
+ * Slice #013 (bugfix — peaks hooks install --no-progress): the published
21
+ * flag that skipped the progress-start PreToolUse hook entry. That hook
22
+ * auto-spawns a new terminal running a progress watcher; with dispatch +
23
+ * heartbeat (slice #009 + #010) the auto-spawn is dead weight.
31
24
  *
32
- * Slice #014 (refactor — full removal of legacy progress-start surface):
33
- * the field is preserved for API stability, but the underlying
34
- * install only ever emits the gate-enforce entry. The progress-start
35
- * entry is no longer installed regardless of this flag's value. The
36
- * legacy `peaks progress start|watch|close` CLI surface is gone
37
- * (replaced by `peaks sub-agent dispatch|heartbeat|share`); the hook
38
- * entry would have been pointing at a `peaks progress start` that no
39
- * longer exists. The sentinel `peaks progress start` constant is still
40
- * exported (some tests + back-compat reads rely on it) but no new
41
- * hook entries use it.
25
+ * The field is retained for API stability and NO LONGER CHANGES WHAT IS
26
+ * INSTALLED: it defaults to unset and the entry resolver ignores it, so an
27
+ * install always writes the adapter's whole peaks-managed entry set — for
28
+ * Claude Code: `peaks gate enforce` (Bash and MCP tool calls),
29
+ * `peaks code-gate` (Edit|Write|MultiEdit), `peaks outer-cache write`,
30
+ * `peaks session primer`, `peaks session reinject`, `peaks compact settle`
31
+ * — plus the Layer-3 `permissions.deny` entries (worktree governance);
32
+ * the other adapters install their own single hook entry. No code path
33
+ * writes the legacy progress-start entry any more.
34
+ *
35
+ * `uninstall` ignores this field as well: it strips entries by a sentinel
36
+ * scan over the peaks-managed sentinel set, which covers every entry an
37
+ * install writes plus the legacy progress-start one.
42
38
  */
43
39
  readonly skipProgress?: boolean;
44
40
  };
@@ -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;
@@ -1,52 +1,89 @@
1
1
  /**
2
- * Workflow in-flight probe (RD §4 D4d — slice 4.0.8).
2
+ * The in-flight probe: is a dispatch in flight right now?
3
3
  *
4
- * The single source of truth for `inFlightBatch` in 24h mode is the
5
- * set of `status=running && age(lastHeartbeat)<30min` nodes across
6
- * all valid graphs for the bound session. No CLI boolean or lease-age
7
- * heuristic may override graph facts in production. This probe is the
8
- * production replacement for the previous lease-age `inFlightBatch`
9
- * computation in `auto-compact-orchestrator.ts`.
4
+ * THE DISPATCH LEDGER IS THE SOURCE OF TRUTH. The session's ledger — the
5
+ * `active-dispatches.json` index plus the dispatch record each row names — is
6
+ * the artifact that records what the auto-compact deferral is about: a
7
+ * sub-agent that is running right now. The workflow graphs never carried that
8
+ * fact. A dispatch node sits at `prepared` and no writer stamps a heartbeat
9
+ * onto it, so a graph-backed probe could only ever answer "no"; the deferral
10
+ * was unreachable in production for that reason alone.
11
+ *
12
+ * WHERE THE BOUNDARY SITS. This module is the pure half: it opens no file,
13
+ * reads no clock of its own, and decides from the facts the reader hands it.
14
+ * The reader lives in `../dispatch/dispatch-ledger-reader.js` and produces
15
+ * plain data for the types below. That split is what keeps the decision
16
+ * testable without a filesystem, and it is the reason the reader and the probe
17
+ * are two modules rather than one.
18
+ *
19
+ * THE DIRECTION OF THE ANSWER. A wrongly deferred compaction is an
20
+ * inconvenience; a compaction that lands in the middle of a batch is a lost
21
+ * batch. So every unknown — a ledger that cannot be enumerated, a record that
22
+ * cannot be read, a status this probe does not recognise, a freshness signal
23
+ * that cannot be parsed — answers "in flight" and defers the compaction.
24
+ */
25
+ /**
26
+ * The freshness bound, shared with the deferral that uses it. A dispatch whose
27
+ * freshness signal is older than this is not in flight any more.
10
28
  */
11
- import { type GraphNodeStatus, type WorkflowId } from './workflow-graph-types.js';
12
29
  export declare const FRESH_RUNNING_THRESHOLD_MS: number;
30
+ /** The dispatch record carried no freshness signal this probe could read. */
13
31
  export declare const PEAKS_HEARTBEAT_MISSING = "PEAKS_HEARTBEAT_MISSING";
14
- export declare const PEAKS_GRAPH_REF_BROKEN = "PEAKS_GRAPH_REF_BROKEN";
15
- export declare const PEAKS_GRAPH_CORRUPTED = "PEAKS_GRAPH_CORRUPTED";
16
- export interface ProbeGraph {
17
- readonly workflowId?: WorkflowId;
18
- readonly rootSkill?: string;
19
- readonly nodes?: ReadonlyArray<{
20
- readonly id?: string;
21
- readonly kind?: string;
22
- readonly status?: GraphNodeStatus;
23
- readonly lastHeartbeat?: string;
24
- }>;
25
- readonly edges?: ReadonlyArray<unknown>;
26
- readonly schemaVersion?: number;
27
- /** Sentinel for corrupt graphs the test seam wants to surface as broken. */
28
- readonly corrupt?: boolean;
29
- readonly graphRef?: string;
32
+ /** The ledger, or one of the records it names, could not be read. */
33
+ export declare const PEAKS_DISPATCH_LEDGER_UNREADABLE = "PEAKS_DISPATCH_LEDGER_UNREADABLE";
34
+ /** The record's status is not one this probe recognises. */
35
+ export declare const PEAKS_DISPATCH_STATUS_UNKNOWN = "PEAKS_DISPATCH_STATUS_UNKNOWN";
36
+ /**
37
+ * One dispatch's ledger facts, as the reader found them.
38
+ *
39
+ * `absent` means the record file is gone, so no dispatch is running behind it —
40
+ * the record IS the artifact that proves liveness, and without it there is
41
+ * nothing running. `unreadable` means the record is there but cannot be
42
+ * believed, which is an unknown, not an absence.
43
+ */
44
+ export type LedgerDispatchFact = {
45
+ readonly kind: 'absent';
46
+ readonly recordPath: string;
47
+ } | {
48
+ readonly kind: 'unreadable';
49
+ readonly recordPath: string;
50
+ } | {
51
+ readonly kind: 'record';
52
+ readonly recordPath: string;
53
+ readonly status: string;
54
+ readonly outcome: string;
55
+ readonly lastBeatAt: string | null;
56
+ readonly createdAt: string;
57
+ readonly disposed: boolean;
58
+ };
59
+ /** What the reader found in one session's dispatch ledger. */
60
+ export interface LedgerFacts {
61
+ /** `absent` = the session has no ledger; `unreadable` = the ledger cannot be enumerated. */
62
+ readonly ledgerState: 'absent' | 'unreadable' | 'readable';
63
+ readonly dispatches: readonly LedgerDispatchFact[];
30
64
  }
31
65
  export interface ProbeInput {
32
66
  readonly now: string;
33
- readonly graphs: ReadonlyArray<ProbeGraph>;
34
- readonly leases?: ReadonlyArray<unknown>;
67
+ readonly ledger: LedgerFacts;
35
68
  readonly redLine?: boolean;
36
- readonly autoCompact?: boolean;
37
69
  }
38
70
  export interface ProbeWarning {
39
71
  readonly code: string;
40
72
  readonly message: string;
41
- readonly graphRef?: string;
42
- readonly nodeId?: string;
73
+ readonly recordPath?: string;
43
74
  }
44
75
  export interface ProbeResult {
45
76
  readonly inFlightBatch: boolean;
46
77
  readonly shouldCompact: boolean;
47
78
  readonly deferPreCompact: boolean;
48
- readonly warnings: ReadonlyArray<ProbeWarning>;
49
- readonly errors: ReadonlyArray<ProbeWarning>;
79
+ readonly warnings: readonly ProbeWarning[];
80
+ readonly errors: readonly ProbeWarning[];
50
81
  readonly reason: string;
51
82
  }
83
+ /**
84
+ * The decision. Pure: the ledger's facts go in, the answer comes out.
85
+ *
86
+ * Red-line compaction overrides the in-flight deferral, so a session at the
87
+ * red line still asks the harness to compact.
88
+ */
52
89
  export declare function probeInFlightBatch(input: ProbeInput): ProbeResult;