peaks-loop 4.1.17 → 4.1.19
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +269 -0
- package/README-en.md +6 -0
- package/README.md +5 -0
- package/contracts/test-style-contract.md +14 -5
- package/dist/cli/commands/audit-red-lines-runners.js +6 -1
- package/dist/cli/commands/best-practice-scan-collision.d.ts +42 -0
- package/dist/cli/commands/best-practice-scan-collision.js +115 -0
- package/dist/cli/commands/best-practice-scan-command.d.ts +5 -0
- package/dist/cli/commands/best-practice-scan-command.js +9 -18
- package/dist/cli/commands/best-practice-scan-helpers.d.ts +12 -6
- package/dist/cli/commands/best-practice-scan-helpers.js +37 -17
- package/dist/cli/commands/code-auto-compact-command.js +71 -40
- package/dist/cli/commands/code-auto-compact-deferral.d.ts +34 -0
- package/dist/cli/commands/code-auto-compact-deferral.js +59 -0
- package/dist/cli/commands/code-gate-command.d.ts +4 -4
- package/dist/cli/commands/code-gate-command.js +4 -4
- package/dist/cli/commands/core/skill-generated-config-notice.d.ts +5 -0
- package/dist/cli/commands/core/skill-generated-config-notice.js +42 -8
- package/dist/cli/commands/core/skill-presence-commands.js +42 -74
- package/dist/cli/commands/core/skill-presence-set-command.d.ts +11 -0
- package/dist/cli/commands/core/skill-presence-set-command.js +175 -0
- package/dist/cli/commands/core/skill-registry-commands.js +32 -0
- package/dist/cli/commands/core/skill-store-report.d.ts +8 -0
- package/dist/cli/commands/core/skill-store-report.js +79 -0
- package/dist/cli/commands/core/standards-init-command.js +44 -8
- package/dist/cli/commands/core/standards-migrate-command.js +5 -4
- package/dist/cli/commands/dispatch-dag-runners.d.ts +1 -0
- package/dist/cli/commands/dispatch-dag-runners.js +11 -1
- package/dist/cli/commands/dispatch-detached-branch.js +19 -1
- package/dist/cli/commands/dispatch-prompt-composition.js +7 -2
- package/dist/cli/commands/dispatch-scratch-path-block.d.ts +73 -0
- package/dist/cli/commands/dispatch-scratch-path-block.js +131 -0
- package/dist/cli/commands/hooks-commands.js +36 -7
- package/dist/cli/commands/hooks-uninstall-command.js +5 -5
- package/dist/cli/commands/mut-commands-helpers.d.ts +72 -5
- package/dist/cli/commands/mut-commands-helpers.js +197 -4
- package/dist/cli/commands/mut-commands.d.ts +9 -1
- package/dist/cli/commands/mut-commands.js +82 -154
- package/dist/cli/commands/preferences-commands.js +27 -2
- package/dist/cli/commands/scan-scope-helpers.js +2 -2
- package/dist/services/24h-mode/auto-engage.d.ts +11 -3
- package/dist/services/24h-mode/auto-engage.js +14 -6
- package/dist/services/artifacts/artifact-templates.js +10 -0
- package/dist/services/artifacts/backcompat-acceptance.d.ts +8 -1
- package/dist/services/artifacts/backcompat-acceptance.js +8 -7
- package/dist/services/artifacts/rd-transition-gates.d.ts +32 -5
- package/dist/services/artifacts/rd-transition-gates.js +96 -19
- package/dist/services/artifacts/request-artifact-service.js +6 -6
- package/dist/services/audit/enforcers/lint-output-style.js +14 -2
- package/dist/services/audit/enforcers/root-scratch-artifacts.d.ts +46 -0
- package/dist/services/audit/enforcers/root-scratch-artifacts.js +97 -0
- package/dist/services/audit/static-service.js +4 -4
- package/dist/services/code/auto-compact-history.d.ts +6 -1
- package/dist/services/code/auto-compact-history.js +6 -1
- package/dist/services/code/auto-compact-modes.d.ts +60 -14
- package/dist/services/code/auto-compact-modes.js +75 -20
- package/dist/services/code/auto-compact-orchestrator.js +7 -5
- package/dist/services/code/auto-compact-profile.d.ts +23 -0
- package/dist/services/code/auto-compact-profile.js +51 -0
- package/dist/services/code/auto-compact-run-types.d.ts +8 -4
- package/dist/services/compact-history/compact-history-service.d.ts +6 -1
- package/dist/services/compact-history/compact-history-service.js +5 -1
- package/dist/services/context/auto-compact-types.d.ts +7 -5
- package/dist/services/dispatch/dispatch-ledger-reader.d.ts +13 -0
- package/dist/services/dispatch/dispatch-ledger-reader.js +164 -0
- package/dist/services/doctor/doctor-service/checks/canonical-store-version.d.ts +57 -0
- package/dist/services/doctor/doctor-service/checks/canonical-store-version.js +190 -0
- package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.d.ts +37 -0
- package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.js +100 -0
- package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +11 -3
- package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +48 -29
- package/dist/services/doctor/doctor-service/plugin-registry.js +4 -0
- package/dist/services/doctor/doctor-service/types.d.ts +12 -0
- package/dist/services/hooks/hook-payload-cwd.d.ts +11 -4
- package/dist/services/hooks/hook-payload-cwd.js +11 -4
- package/dist/services/hooks/pre-tool-code-gate.d.ts +4 -4
- package/dist/services/hooks/pre-tool-code-gate.js +4 -4
- package/dist/services/hooks/presence-marker-detector.d.ts +3 -0
- package/dist/services/hooks/presence-marker-detector.js +21 -19
- package/dist/services/ide/adapters/claude-code-adapter.js +6 -8
- package/dist/services/ide/adapters/codex-adapter.js +23 -7
- package/dist/services/ide/adapters/cursor-adapter.js +23 -7
- package/dist/services/mode/mode-status-service.d.ts +26 -27
- package/dist/services/mode/mode-status-service.js +36 -60
- package/dist/services/preferences/preferences-types.d.ts +30 -0
- package/dist/services/preferences/preferences-types.js +13 -0
- package/dist/services/scan/acceptance-coverage-service.d.ts +14 -11
- package/dist/services/scan/acceptance-coverage-service.js +157 -52
- package/dist/services/scan/rid-change-claims.d.ts +15 -0
- package/dist/services/scan/rid-change-claims.js +116 -0
- package/dist/services/session/getSessionDir.d.ts +13 -0
- package/dist/services/session/getSessionDir.js +7 -1
- package/dist/services/skills/hooks-settings-types.d.ts +17 -21
- package/dist/services/skills/presence-caller-id.d.ts +51 -0
- package/dist/services/skills/presence-caller-id.js +43 -0
- package/dist/services/skills/presence-gate.d.ts +65 -0
- package/dist/services/skills/presence-gate.js +113 -0
- package/dist/services/skills/presence-lease-resolver.d.ts +63 -0
- package/dist/services/skills/presence-lease-resolver.js +114 -0
- package/dist/services/skills/presence-lease-selection.d.ts +91 -0
- package/dist/services/skills/presence-lease-selection.js +135 -0
- package/dist/services/skills/presence-lease-service.d.ts +3 -11
- package/dist/services/skills/presence-lease-service.js +34 -87
- package/dist/services/skills/presence-lease-store.d.ts +33 -0
- package/dist/services/skills/presence-lease-store.js +94 -0
- package/dist/services/skills/presence-lease-types.d.ts +31 -0
- package/dist/services/skills/presence-lease-types.js +27 -0
- package/dist/services/skills/presence-role.d.ts +35 -0
- package/dist/services/skills/presence-role.js +72 -0
- package/dist/services/skills/skill-presence-service.d.ts +39 -9
- package/dist/services/skills/skill-presence-service.js +143 -174
- package/dist/services/skills/skill-presence-write.d.ts +60 -0
- package/dist/services/skills/skill-presence-write.js +74 -0
- package/dist/services/skills/skill-statusline-service.js +7 -7
- package/dist/services/skills/sync-service-support.d.ts +27 -0
- package/dist/services/skills/sync-service.js +1 -0
- package/dist/services/standards/ide-aware-standards-service.d.ts +35 -23
- package/dist/services/standards/ide-aware-standards-service.js +45 -20
- package/dist/services/standards/migrate-claude-rules-service.d.ts +6 -0
- package/dist/services/standards/migrate-claude-rules-service.js +18 -0
- package/dist/services/standards/migrate-service.d.ts +1 -1
- package/dist/services/standards/migrate-service.js +27 -7
- package/dist/services/standards/project-scripts.d.ts +25 -0
- package/dist/services/standards/project-scripts.js +116 -0
- package/dist/services/standards/project-standards-service.d.ts +23 -15
- package/dist/services/standards/project-standards-service.js +176 -243
- package/dist/services/standards/standards-constitution.d.ts +89 -0
- package/dist/services/standards/standards-constitution.js +199 -0
- package/dist/services/standards/standards-files.d.ts +37 -0
- package/dist/services/standards/standards-files.js +138 -0
- package/dist/services/standards/standards-pointer.d.ts +73 -0
- package/dist/services/standards/standards-pointer.js +98 -0
- package/dist/services/standards/standards-render-agents.d.ts +34 -0
- package/dist/services/standards/standards-render-agents.js +149 -0
- package/dist/services/standards/standards-render-common.d.ts +38 -1
- package/dist/services/standards/standards-render-common.js +44 -7
- package/dist/services/standards/standards-render.d.ts +1 -3
- package/dist/services/standards/standards-render.js +6 -87
- package/dist/services/workflow/workflow-graph-ensure.d.ts +77 -0
- package/dist/services/workflow/workflow-graph-ensure.js +97 -0
- package/dist/services/workflow/workflow-inflight-probe.d.ts +68 -31
- package/dist/services/workflow/workflow-inflight-probe.js +163 -75
- package/dist/services/workflow/workflow-presence-lifecycle.js +21 -6
- package/dist/services/workspace/generated-artifacts-content.d.ts +46 -0
- package/dist/services/workspace/generated-artifacts-content.js +167 -0
- package/dist/services/workspace/generated-artifacts-stamp.d.ts +36 -13
- package/dist/services/workspace/generated-artifacts-stamp.js +37 -15
- package/dist/services/workspace/runtime-layout.d.ts +64 -0
- package/dist/services/workspace/runtime-layout.js +62 -0
- package/output-styles/peaks-skill-swarm.md +18 -2
- package/package.json +10 -9
- package/schemas/doctor-report.schema.json +1 -1
- package/scripts/canonical-store-fs.mjs +112 -0
- package/scripts/canonical-store-link.mjs +13 -22
- package/scripts/canonical-store-marker.mjs +241 -0
- package/scripts/canonical-store.mjs +119 -141
- package/scripts/install-skills-bundles.mjs +56 -13
- package/scripts/install-skills-fs.mjs +73 -0
- package/scripts/install-skills-output-styles.mjs +8 -2
- package/scripts/install-skills-report.mjs +19 -0
- package/scripts/install-skills.mjs +9 -0
- package/skills/bee/peaks-perf-audit/SKILL.md +3 -1
- package/skills/bee/peaks-prd/SKILL.md +5 -3
- package/skills/bee/peaks-qa/SKILL.md +4 -2
- package/skills/bee/peaks-qa/references/qa-skill-presence.md +1 -1
- package/skills/bee/peaks-qa/references/qa-standards-preflight.md +3 -1
- package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
- package/skills/bee/peaks-rd/SKILL.md +4 -2
- package/skills/bee/peaks-rd/references/artifact-and-standards-output.md +1 -1
- package/skills/bee/peaks-rd/references/rd-runbook.md +11 -2
- package/skills/bee/peaks-rd/references/rd-standards-preflight.md +3 -1
- package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +24 -5
- package/skills/bee/peaks-rd/references/rd-transition-gates.md +49 -5
- package/skills/bee/peaks-rd/references/skill-presence-and-title.md +1 -1
- package/skills/bee/peaks-reviewer/SKILL.md +3 -1
- package/skills/bee/peaks-sc/SKILL.md +4 -2
- package/skills/bee/peaks-security-audit/SKILL.md +3 -1
- package/skills/bee/peaks-txt/SKILL.md +5 -3
- package/skills/bee/peaks-ui/SKILL.md +6 -4
- package/skills/peaks-audit/SKILL.md +3 -1
- package/skills/peaks-code/SKILL.md +4 -2
- package/skills/peaks-code/references/a2a-artifact-mapping.md +3 -3
- package/skills/peaks-code/references/completion-handoff.md +1 -1
- package/skills/peaks-code/references/local-artifact-workspace.md +10 -11
- package/skills/peaks-code/references/micro-cycle.md +2 -2
- package/skills/peaks-code/references/mode-selection-with-stale-presence.md +3 -3
- package/skills/peaks-code/references/runbook.md +4 -4
- package/skills/peaks-code/references/skill-presence-and-title.md +4 -2
- package/skills/peaks-code/references/standards-preflight.md +7 -6
- package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
- package/skills/peaks-code/references/swarm-dispatch-contract.md +5 -5
- package/skills/peaks-code/references/workflow-gates-and-types.md +37 -11
- package/skills/peaks-content/SKILL.md +3 -1
- package/skills/peaks-doctor/SKILL.md +3 -1
- package/skills/peaks-final-review/SKILL.md +3 -1
- package/skills/peaks-ide/SKILL.md +3 -1
- package/skills/peaks-issue-fix-orchestrator/SKILL.md +5 -3
- package/skills/peaks-race-code/SKILL.md +9 -4
- package/skills/peaks-resume/SKILL.md +3 -1
- package/skills/peaks-slice-decompose/SKILL.md +3 -1
- package/skills/peaks-solo/SKILL.md +3 -1
- package/skills/peaks-sop/SKILL.md +4 -2
- package/skills/peaks-status/SKILL.md +3 -1
- package/skills/peaks-test/SKILL.md +3 -1
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `gate` field of a presence lease — write-side contract.
|
|
3
|
+
*
|
|
4
|
+
* WHAT THE GATE IS. The status header the LLM is told to display —
|
|
5
|
+
* `Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <action>` —
|
|
6
|
+
* has three cells. The middle one was, until this slice, MODEL-INVENTED
|
|
7
|
+
* prose: `SetPresenceLeaseInput.gate` existed, but the lease constructor
|
|
8
|
+
* never expanded it, so the lease carried no gate and the read side had
|
|
9
|
+
* nothing to project. The gate is now persisted and projected, so the
|
|
10
|
+
* middle cell is a machine fact.
|
|
11
|
+
*
|
|
12
|
+
* ENUM OR FREE STRING? Free string with a shape check. The gate values
|
|
13
|
+
* this repository actually uses are enumerated in `KNOWN_PRESENCE_GATES`
|
|
14
|
+
* below, but they are NOT an allow-list:
|
|
15
|
+
*
|
|
16
|
+
* - `repair-cycle-<N>` is a TEMPLATE — the runtime value carries a
|
|
17
|
+
* counter (`repair-cycle-1`), so it cannot be closed over a static
|
|
18
|
+
* enumeration.
|
|
19
|
+
* - `peaks sop check --gate <gate-id>` addresses a gate id defined at
|
|
20
|
+
* runtime by an SOP, so SOP-scoped gates are not knowable at build
|
|
21
|
+
* time either.
|
|
22
|
+
* - third-party skills are free to pass their own gate token.
|
|
23
|
+
*
|
|
24
|
+
* A closed enumeration would reject those, and the CLI already accepts any
|
|
25
|
+
* `--gate <value>` string today; rejecting unknown values would break
|
|
26
|
+
* working callers for no gain. What IS rejected is a malformed value: a
|
|
27
|
+
* control character (it lands verbatim in the status header) or a value
|
|
28
|
+
* longer than `MAX_PRESENCE_GATE_LENGTH`. An empty / whitespace-only value
|
|
29
|
+
* is DROPPED, not rejected — that is the pre-existing behaviour of the
|
|
30
|
+
* `...(gate ? { gate } : {})` spread and it is kept.
|
|
31
|
+
*/
|
|
32
|
+
/** Error code for a gate value that cannot be persisted. */
|
|
33
|
+
export const PEAKS_GATE_INVALID = 'PEAKS_GATE_INVALID';
|
|
34
|
+
/** Longest gate value that may be persisted. */
|
|
35
|
+
export const MAX_PRESENCE_GATE_LENGTH = 200;
|
|
36
|
+
/**
|
|
37
|
+
* The gate vocabulary this repository uses today (enumerated 2026-10-24
|
|
38
|
+
* from `skills/**` and `src/**`).
|
|
39
|
+
*
|
|
40
|
+
* NOT an allow-list — see the module header. The list exists so the
|
|
41
|
+
* regression test can assert that every gate value the repository uses is
|
|
42
|
+
* accepted by `normalizePresenceGate`, and so a reader can see the
|
|
43
|
+
* vocabulary without grepping.
|
|
44
|
+
*/
|
|
45
|
+
export const KNOWN_PRESENCE_GATES = [
|
|
46
|
+
'startup',
|
|
47
|
+
'qa-validation',
|
|
48
|
+
'swarm-fan-out',
|
|
49
|
+
'swarm-converged',
|
|
50
|
+
'repair-cycle-<N>',
|
|
51
|
+
'review-fan-out-converged'
|
|
52
|
+
];
|
|
53
|
+
function gateError(message) {
|
|
54
|
+
const err = new Error(message);
|
|
55
|
+
err.name = 'PresenceError';
|
|
56
|
+
err.code = PEAKS_GATE_INVALID;
|
|
57
|
+
return err;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* The control-character boundaries `hasControlCharacter` tests against.
|
|
61
|
+
*
|
|
62
|
+
* C0 controls occupy code points 0x00-0x1F; DEL (0x7F) is the one control
|
|
63
|
+
* character above them. Named constants so the `no-magic-numbers` rule has
|
|
64
|
+
* nothing left to flag in the comparison.
|
|
65
|
+
*/
|
|
66
|
+
const C0_CONTROL_MAX = 0x20;
|
|
67
|
+
const DEL_CONTROL_CODE = 0x7f;
|
|
68
|
+
/** True when the value carries a C0 / DEL control character. */
|
|
69
|
+
function hasControlCharacter(value) {
|
|
70
|
+
for (const ch of value) {
|
|
71
|
+
const code = ch.codePointAt(0) ?? 0;
|
|
72
|
+
if (code < C0_CONTROL_MAX || code === DEL_CONTROL_CODE)
|
|
73
|
+
return true;
|
|
74
|
+
}
|
|
75
|
+
return false;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Normalize a gate value for persistence.
|
|
79
|
+
*
|
|
80
|
+
* Returns `undefined` when there is no gate to persist (absent, or empty
|
|
81
|
+
* after trimming). Throws a `PEAKS_GATE_INVALID` error for a value that
|
|
82
|
+
* must not be written (control characters, over-length).
|
|
83
|
+
*/
|
|
84
|
+
export function normalizePresenceGate(value) {
|
|
85
|
+
if (value === undefined || value === null)
|
|
86
|
+
return undefined;
|
|
87
|
+
if (typeof value !== 'string') {
|
|
88
|
+
throw gateError('gate must be a string');
|
|
89
|
+
}
|
|
90
|
+
const trimmed = value.trim();
|
|
91
|
+
if (trimmed.length === 0)
|
|
92
|
+
return undefined;
|
|
93
|
+
if (trimmed.length > MAX_PRESENCE_GATE_LENGTH) {
|
|
94
|
+
throw gateError(`gate is ${trimmed.length} characters long (max ${MAX_PRESENCE_GATE_LENGTH})`);
|
|
95
|
+
}
|
|
96
|
+
if (hasControlCharacter(trimmed)) {
|
|
97
|
+
throw gateError('gate must not contain control characters');
|
|
98
|
+
}
|
|
99
|
+
return trimmed;
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* Project a gate value that was READ back from disk.
|
|
103
|
+
*
|
|
104
|
+
* Tolerant by design: a hand-edited lease file, or a lease written by an
|
|
105
|
+
* older release, must never make the read throw. Anything that is not a
|
|
106
|
+
* non-empty string is reported as "no gate".
|
|
107
|
+
*/
|
|
108
|
+
export function readPresenceGate(value) {
|
|
109
|
+
if (typeof value !== 'string')
|
|
110
|
+
return undefined;
|
|
111
|
+
const trimmed = value.trim();
|
|
112
|
+
return trimmed.length === 0 ? undefined : trimmed;
|
|
113
|
+
}
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The cross-session presence read.
|
|
3
|
+
*
|
|
4
|
+
* WHAT IT SOLVES. The canonical presence read used to look at ONE session
|
|
5
|
+
* tree — the tree the caller is bound to — and answered "inactive"
|
|
6
|
+
* whenever that tree had no in-flight lease. A peaks run whose lease
|
|
7
|
+
* landed in a different tree was therefore invisible: `peaks skill
|
|
8
|
+
* presence --json` reported `{"active": false}` while a live lease sat on
|
|
9
|
+
* disk. The caller-id resolution failing (an IDE adapter that claims a
|
|
10
|
+
* harness the host runtime is not) made that the NORMAL case, not the
|
|
11
|
+
* corner case.
|
|
12
|
+
*
|
|
13
|
+
* WHAT IT DOES. It enumerates every session tree of the project, marks
|
|
14
|
+
* the bound tree against the others, and hands the candidate set to the
|
|
15
|
+
* pure selection rules in `presence-lease-selection.ts`.
|
|
16
|
+
*
|
|
17
|
+
* WHY IT IS ITS OWN MODULE. `skill-presence-service.ts` was already over
|
|
18
|
+
* the repository's 300-raw-line cap, and that cap is a ratchet: a file
|
|
19
|
+
* over it may be touched, but never grown. The read half moved here.
|
|
20
|
+
*/
|
|
21
|
+
import { type PresenceInactiveDiagnostic, type PresenceLeaseCandidate, type PresenceLeaseSelection } from './presence-lease-selection.js';
|
|
22
|
+
/**
|
|
23
|
+
* The project root the presence read runs against: the caller's override
|
|
24
|
+
* when it gave one, otherwise the project the cwd belongs to.
|
|
25
|
+
*/
|
|
26
|
+
export declare function resolveProjectRoot(override?: string): string;
|
|
27
|
+
/**
|
|
28
|
+
* The session tree this caller is bound to, or `null` when nothing is
|
|
29
|
+
* bound. Never throws: an unresolvable caller id must not blind the
|
|
30
|
+
* presence read.
|
|
31
|
+
*/
|
|
32
|
+
export declare function resolveBoundSessionId(projectRoot: string): string | null;
|
|
33
|
+
/**
|
|
34
|
+
* Every presence lease of the project, from every session tree.
|
|
35
|
+
*
|
|
36
|
+
* The session trees are enumerated from the RUNTIME ROOT, not through
|
|
37
|
+
* `listSessions`: that helper only recognises the dated-hex session id
|
|
38
|
+
* shape (`2026-10-23-session-5e40e0`), so a tree whose id has any other
|
|
39
|
+
* shape would be invisible to the presence read. What actually matters
|
|
40
|
+
* here is "a directory under `.peaks/_runtime/` that holds a `leases/`
|
|
41
|
+
* directory" — the directories without one (`callers`, `change`,
|
|
42
|
+
* `_audit`) contribute nothing.
|
|
43
|
+
*
|
|
44
|
+
* The `scope` marks the tree the caller is bound to (`bound`) against
|
|
45
|
+
* every other tree (`other`) — the bound tree keeps its precedence when
|
|
46
|
+
* it holds an eligible lease.
|
|
47
|
+
*/
|
|
48
|
+
export declare function collectPresenceLeaseCandidates(projectRoot: string, boundSessionId: string | null): PresenceLeaseCandidate[];
|
|
49
|
+
/**
|
|
50
|
+
* The lease that represents "who is driving peaks right now", across
|
|
51
|
+
* EVERY session tree of the project.
|
|
52
|
+
*
|
|
53
|
+
* The bound tree keeps its precedence: when it holds an eligible lease,
|
|
54
|
+
* only its own leases are considered. When it holds none — the caller id
|
|
55
|
+
* could not be resolved, the binding points at a tree without leases,
|
|
56
|
+
* the session rotated — the other trees' leases are considered instead.
|
|
57
|
+
*/
|
|
58
|
+
export declare function resolvePresenceLease(projectRoot: string): PresenceLeaseSelection | null;
|
|
59
|
+
/**
|
|
60
|
+
* Why the read found nothing active — the diagnostic behind
|
|
61
|
+
* `peaks skill presence --json --check-stale` on the inactive path.
|
|
62
|
+
*/
|
|
63
|
+
export declare function diagnosePresence(projectRoot: string): PresenceInactiveDiagnostic;
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The cross-session presence read.
|
|
3
|
+
*
|
|
4
|
+
* WHAT IT SOLVES. The canonical presence read used to look at ONE session
|
|
5
|
+
* tree — the tree the caller is bound to — and answered "inactive"
|
|
6
|
+
* whenever that tree had no in-flight lease. A peaks run whose lease
|
|
7
|
+
* landed in a different tree was therefore invisible: `peaks skill
|
|
8
|
+
* presence --json` reported `{"active": false}` while a live lease sat on
|
|
9
|
+
* disk. The caller-id resolution failing (an IDE adapter that claims a
|
|
10
|
+
* harness the host runtime is not) made that the NORMAL case, not the
|
|
11
|
+
* corner case.
|
|
12
|
+
*
|
|
13
|
+
* WHAT IT DOES. It enumerates every session tree of the project, marks
|
|
14
|
+
* the bound tree against the others, and hands the candidate set to the
|
|
15
|
+
* pure selection rules in `presence-lease-selection.ts`.
|
|
16
|
+
*
|
|
17
|
+
* WHY IT IS ITS OWN MODULE. `skill-presence-service.ts` was already over
|
|
18
|
+
* the repository's 300-raw-line cap, and that cap is a ratchet: a file
|
|
19
|
+
* over it may be touched, but never grown. The read half moved here.
|
|
20
|
+
*/
|
|
21
|
+
import { readdirSync } from 'node:fs';
|
|
22
|
+
import { join, resolve } from 'node:path';
|
|
23
|
+
import { findProjectRoot } from '../config/config-safety.js';
|
|
24
|
+
import { getSessionId } from '../session/session-manager.js';
|
|
25
|
+
import { listPresenceLeases } from './presence-lease-service.js';
|
|
26
|
+
import { explainInactivePresence, selectActivePresenceLease } from './presence-lease-selection.js';
|
|
27
|
+
/**
|
|
28
|
+
* The project root the presence read runs against: the caller's override
|
|
29
|
+
* when it gave one, otherwise the project the cwd belongs to.
|
|
30
|
+
*/
|
|
31
|
+
export function resolveProjectRoot(override) {
|
|
32
|
+
if (override)
|
|
33
|
+
return resolve(override);
|
|
34
|
+
return findProjectRoot(process.cwd()) ?? process.cwd();
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* The session tree this caller is bound to, or `null` when nothing is
|
|
38
|
+
* bound. Never throws: an unresolvable caller id must not blind the
|
|
39
|
+
* presence read.
|
|
40
|
+
*/
|
|
41
|
+
export function resolveBoundSessionId(projectRoot) {
|
|
42
|
+
let sessionId = null;
|
|
43
|
+
try {
|
|
44
|
+
sessionId = getSessionId(projectRoot);
|
|
45
|
+
}
|
|
46
|
+
catch {
|
|
47
|
+
// The caller id could not be resolved. That must NOT blind the
|
|
48
|
+
// presence read: the cross-session fallback works without a bound
|
|
49
|
+
// tree, so the read continues with no bound tree.
|
|
50
|
+
sessionId = null;
|
|
51
|
+
}
|
|
52
|
+
return sessionId;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Every presence lease of the project, from every session tree.
|
|
56
|
+
*
|
|
57
|
+
* The session trees are enumerated from the RUNTIME ROOT, not through
|
|
58
|
+
* `listSessions`: that helper only recognises the dated-hex session id
|
|
59
|
+
* shape (`2026-10-23-session-5e40e0`), so a tree whose id has any other
|
|
60
|
+
* shape would be invisible to the presence read. What actually matters
|
|
61
|
+
* here is "a directory under `.peaks/_runtime/` that holds a `leases/`
|
|
62
|
+
* directory" — the directories without one (`callers`, `change`,
|
|
63
|
+
* `_audit`) contribute nothing.
|
|
64
|
+
*
|
|
65
|
+
* The `scope` marks the tree the caller is bound to (`bound`) against
|
|
66
|
+
* every other tree (`other`) — the bound tree keeps its precedence when
|
|
67
|
+
* it holds an eligible lease.
|
|
68
|
+
*/
|
|
69
|
+
export function collectPresenceLeaseCandidates(projectRoot, boundSessionId) {
|
|
70
|
+
const candidates = [];
|
|
71
|
+
const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
|
|
72
|
+
let entries = [];
|
|
73
|
+
try {
|
|
74
|
+
entries = readdirSync(runtimeRoot, { withFileTypes: true })
|
|
75
|
+
.filter((entry) => entry.isDirectory())
|
|
76
|
+
.map((entry) => entry.name);
|
|
77
|
+
}
|
|
78
|
+
catch {
|
|
79
|
+
// A project with no runtime root has no session trees, and one that
|
|
80
|
+
// cannot be read has none this read can see. Either way the honest
|
|
81
|
+
// answer is "no leases", not an exception.
|
|
82
|
+
entries = [];
|
|
83
|
+
}
|
|
84
|
+
for (const sessionId of entries) {
|
|
85
|
+
const scope = sessionId === boundSessionId ? 'bound' : 'other';
|
|
86
|
+
for (const lease of listPresenceLeases(projectRoot, sessionId)) {
|
|
87
|
+
candidates.push({ lease, sessionId, scope });
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
return candidates;
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* The lease that represents "who is driving peaks right now", across
|
|
94
|
+
* EVERY session tree of the project.
|
|
95
|
+
*
|
|
96
|
+
* The bound tree keeps its precedence: when it holds an eligible lease,
|
|
97
|
+
* only its own leases are considered. When it holds none — the caller id
|
|
98
|
+
* could not be resolved, the binding points at a tree without leases,
|
|
99
|
+
* the session rotated — the other trees' leases are considered instead.
|
|
100
|
+
*/
|
|
101
|
+
export function resolvePresenceLease(projectRoot) {
|
|
102
|
+
const boundSessionId = resolveBoundSessionId(projectRoot);
|
|
103
|
+
const candidates = collectPresenceLeaseCandidates(projectRoot, boundSessionId);
|
|
104
|
+
return selectActivePresenceLease(candidates, Date.now());
|
|
105
|
+
}
|
|
106
|
+
/**
|
|
107
|
+
* Why the read found nothing active — the diagnostic behind
|
|
108
|
+
* `peaks skill presence --json --check-stale` on the inactive path.
|
|
109
|
+
*/
|
|
110
|
+
export function diagnosePresence(projectRoot) {
|
|
111
|
+
const boundSessionId = resolveBoundSessionId(projectRoot);
|
|
112
|
+
const candidates = collectPresenceLeaseCandidates(projectRoot, boundSessionId);
|
|
113
|
+
return explainInactivePresence(candidates, Date.now());
|
|
114
|
+
}
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Deterministic presence-lease selection — pure rules, no filesystem I/O.
|
|
3
|
+
*
|
|
4
|
+
* WHY THIS MODULE EXISTS. The canonical presence read used to look at ONE
|
|
5
|
+
* session tree — the tree the caller is bound to — and answered "inactive"
|
|
6
|
+
* whenever that tree had no in-flight lease. A peaks run whose lease landed
|
|
7
|
+
* in a different tree (a sibling session, a rotated session, a session the
|
|
8
|
+
* caller-id resolution could not reach) was therefore invisible:
|
|
9
|
+
* `peaks skill presence --json` reported `{"active": false}` while a live
|
|
10
|
+
* lease sat on disk. The rules live here, free of I/O, so they can be
|
|
11
|
+
* unit-tested directly against fixture lease sets.
|
|
12
|
+
*
|
|
13
|
+
* THE RULES (in order):
|
|
14
|
+
*
|
|
15
|
+
* 1. ELIGIBLE = not terminal AND not stale.
|
|
16
|
+
*
|
|
17
|
+
* - terminal: `terminalAt` is set, or `status` is outside
|
|
18
|
+
* {`running`, `preparing`} — a lease that already reached its end
|
|
19
|
+
* state is never reported as driving the work.
|
|
20
|
+
* - stale: `now - lastHeartbeat` is past the lease's OWN window
|
|
21
|
+
* (`staleThresholdMs`). Nothing refreshes a lease heartbeat on a
|
|
22
|
+
* cadence, so a lease left behind by a finished session would
|
|
23
|
+
* otherwise keep reporting "active" forever.
|
|
24
|
+
*
|
|
25
|
+
* 2. SCOPE. When the BOUND tree (the tree the caller is bound to) holds
|
|
26
|
+
* at least one eligible lease, only bound-tree leases are selectable:
|
|
27
|
+
* the bound tree is the caller's own state and keeps its precedence.
|
|
28
|
+
* Only when the bound tree has NO eligible lease do the other trees'
|
|
29
|
+
* leases become selectable — that is the cross-session fallback.
|
|
30
|
+
*
|
|
31
|
+
* 3. ORDER. Freshest heartbeat first, then freshest start, then
|
|
32
|
+
* sessionId, callerId, workflowId. The tail is a total order, so the
|
|
33
|
+
* same lease set always names the same winner — no `readdirSync`
|
|
34
|
+
* order leaks into the answer.
|
|
35
|
+
*/
|
|
36
|
+
import { type SkillPresenceLease } from './presence-lease-types.js';
|
|
37
|
+
/** Which tree a candidate lease was read from. */
|
|
38
|
+
export type PresenceLeaseScope = 'bound' | 'other';
|
|
39
|
+
export type PresenceLeaseCandidate = {
|
|
40
|
+
readonly lease: SkillPresenceLease;
|
|
41
|
+
/** The session tree the lease was read from. */
|
|
42
|
+
readonly sessionId: string;
|
|
43
|
+
readonly scope: PresenceLeaseScope;
|
|
44
|
+
};
|
|
45
|
+
export type PresenceLeaseSelection = {
|
|
46
|
+
readonly lease: SkillPresenceLease;
|
|
47
|
+
readonly sessionId: string;
|
|
48
|
+
readonly scope: PresenceLeaseScope;
|
|
49
|
+
};
|
|
50
|
+
/** Why the read found no active lease. */
|
|
51
|
+
export type PresenceInactiveReason = 'no-leases' | 'all-terminal' | 'all-stale' | 'terminal-and-stale'
|
|
52
|
+
/** Defensive: the caller passed a candidate set that DOES hold an eligible lease. */
|
|
53
|
+
| 'eligible-present';
|
|
54
|
+
export type PresenceInactiveDiagnostic = {
|
|
55
|
+
readonly reason: PresenceInactiveReason;
|
|
56
|
+
readonly leaseCount: number;
|
|
57
|
+
readonly terminalCount: number;
|
|
58
|
+
readonly staleCount: number;
|
|
59
|
+
readonly eligibleCount: number;
|
|
60
|
+
};
|
|
61
|
+
/**
|
|
62
|
+
* The stale window that applies to THIS lease.
|
|
63
|
+
*
|
|
64
|
+
* `24h` leases get the 24h run's own window (`STALE_STARTED_AFTER_MS`,
|
|
65
|
+
* 24h30m — the canonical lease-GC start predicate); every other lease
|
|
66
|
+
* gets the canonical heartbeat window (`STALE_HEARTBEAT_MS`, 1h). A 24h
|
|
67
|
+
* run must not lose its presence after one hour just because nothing
|
|
68
|
+
* refreshes the lease heartbeat while the run is in flight.
|
|
69
|
+
*/
|
|
70
|
+
export declare function staleThresholdMs(lease: SkillPresenceLease): number;
|
|
71
|
+
/** A lease that reached its end state — never reported as active. */
|
|
72
|
+
export declare function isTerminalPresenceLease(lease: SkillPresenceLease): boolean;
|
|
73
|
+
/** A lease whose heartbeat is older than its window — never reported as active. */
|
|
74
|
+
export declare function isStalePresenceLease(lease: SkillPresenceLease, nowMs: number): boolean;
|
|
75
|
+
/** A lease that may be reported as the active presence. */
|
|
76
|
+
export declare function isEligiblePresenceLease(lease: SkillPresenceLease, nowMs: number): boolean;
|
|
77
|
+
/**
|
|
78
|
+
* Pick the lease that represents "who is driving peaks right now".
|
|
79
|
+
*
|
|
80
|
+
* Returns `null` when no candidate is eligible — the caller answers
|
|
81
|
+
* "inactive" (never an optimistic default).
|
|
82
|
+
*/
|
|
83
|
+
export declare function selectActivePresenceLease(candidates: readonly PresenceLeaseCandidate[], nowMs: number): PresenceLeaseSelection | null;
|
|
84
|
+
/**
|
|
85
|
+
* Explain why the read found nothing active.
|
|
86
|
+
*
|
|
87
|
+
* Precondition: called only when `selectActivePresenceLease` returned
|
|
88
|
+
* `null` (so `eligibleCount` is 0). The `eligible-present` reason is a
|
|
89
|
+
* defensive branch for a caller that violates that precondition.
|
|
90
|
+
*/
|
|
91
|
+
export declare function explainInactivePresence(candidates: readonly PresenceLeaseCandidate[], nowMs: number): PresenceInactiveDiagnostic;
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Deterministic presence-lease selection — pure rules, no filesystem I/O.
|
|
3
|
+
*
|
|
4
|
+
* WHY THIS MODULE EXISTS. The canonical presence read used to look at ONE
|
|
5
|
+
* session tree — the tree the caller is bound to — and answered "inactive"
|
|
6
|
+
* whenever that tree had no in-flight lease. A peaks run whose lease landed
|
|
7
|
+
* in a different tree (a sibling session, a rotated session, a session the
|
|
8
|
+
* caller-id resolution could not reach) was therefore invisible:
|
|
9
|
+
* `peaks skill presence --json` reported `{"active": false}` while a live
|
|
10
|
+
* lease sat on disk. The rules live here, free of I/O, so they can be
|
|
11
|
+
* unit-tested directly against fixture lease sets.
|
|
12
|
+
*
|
|
13
|
+
* THE RULES (in order):
|
|
14
|
+
*
|
|
15
|
+
* 1. ELIGIBLE = not terminal AND not stale.
|
|
16
|
+
*
|
|
17
|
+
* - terminal: `terminalAt` is set, or `status` is outside
|
|
18
|
+
* {`running`, `preparing`} — a lease that already reached its end
|
|
19
|
+
* state is never reported as driving the work.
|
|
20
|
+
* - stale: `now - lastHeartbeat` is past the lease's OWN window
|
|
21
|
+
* (`staleThresholdMs`). Nothing refreshes a lease heartbeat on a
|
|
22
|
+
* cadence, so a lease left behind by a finished session would
|
|
23
|
+
* otherwise keep reporting "active" forever.
|
|
24
|
+
*
|
|
25
|
+
* 2. SCOPE. When the BOUND tree (the tree the caller is bound to) holds
|
|
26
|
+
* at least one eligible lease, only bound-tree leases are selectable:
|
|
27
|
+
* the bound tree is the caller's own state and keeps its precedence.
|
|
28
|
+
* Only when the bound tree has NO eligible lease do the other trees'
|
|
29
|
+
* leases become selectable — that is the cross-session fallback.
|
|
30
|
+
*
|
|
31
|
+
* 3. ORDER. Freshest heartbeat first, then freshest start, then
|
|
32
|
+
* sessionId, callerId, workflowId. The tail is a total order, so the
|
|
33
|
+
* same lease set always names the same winner — no `readdirSync`
|
|
34
|
+
* order leaks into the answer.
|
|
35
|
+
*/
|
|
36
|
+
import { comparePresenceLeases } from './presence-lease-order.js';
|
|
37
|
+
import { STALE_HEARTBEAT_MS, STALE_STARTED_AFTER_MS } from './presence-lease-types.js';
|
|
38
|
+
/**
|
|
39
|
+
* The stale window that applies to THIS lease.
|
|
40
|
+
*
|
|
41
|
+
* `24h` leases get the 24h run's own window (`STALE_STARTED_AFTER_MS`,
|
|
42
|
+
* 24h30m — the canonical lease-GC start predicate); every other lease
|
|
43
|
+
* gets the canonical heartbeat window (`STALE_HEARTBEAT_MS`, 1h). A 24h
|
|
44
|
+
* run must not lose its presence after one hour just because nothing
|
|
45
|
+
* refreshes the lease heartbeat while the run is in flight.
|
|
46
|
+
*/
|
|
47
|
+
export function staleThresholdMs(lease) {
|
|
48
|
+
return lease.mode === '24h' ? STALE_STARTED_AFTER_MS : STALE_HEARTBEAT_MS;
|
|
49
|
+
}
|
|
50
|
+
/** A lease that reached its end state — never reported as active. */
|
|
51
|
+
export function isTerminalPresenceLease(lease) {
|
|
52
|
+
if (typeof lease.terminalAt === 'string' && lease.terminalAt.length > 0)
|
|
53
|
+
return true;
|
|
54
|
+
return lease.status !== 'running' && lease.status !== 'preparing';
|
|
55
|
+
}
|
|
56
|
+
/** A lease whose heartbeat is older than its window — never reported as active. */
|
|
57
|
+
export function isStalePresenceLease(lease, nowMs) {
|
|
58
|
+
const heartbeatMs = Date.parse(lease.lastHeartbeat);
|
|
59
|
+
// An unparseable heartbeat carries no liveness signal — treat it as
|
|
60
|
+
// stale (fail closed) rather than reporting a lease we cannot date.
|
|
61
|
+
if (!Number.isFinite(heartbeatMs))
|
|
62
|
+
return true;
|
|
63
|
+
return nowMs - heartbeatMs > staleThresholdMs(lease);
|
|
64
|
+
}
|
|
65
|
+
/** A lease that may be reported as the active presence. */
|
|
66
|
+
export function isEligiblePresenceLease(lease, nowMs) {
|
|
67
|
+
return !isTerminalPresenceLease(lease) && !isStalePresenceLease(lease, nowMs);
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* Total order over candidates: freshest heartbeat, then freshest start,
|
|
71
|
+
* then sessionId, callerId, workflowId.
|
|
72
|
+
*/
|
|
73
|
+
function compareCandidates(a, b) {
|
|
74
|
+
const byLease = comparePresenceLeases(a.lease, b.lease);
|
|
75
|
+
if (byLease !== 0)
|
|
76
|
+
return byLease;
|
|
77
|
+
const bySession = a.sessionId.localeCompare(b.sessionId);
|
|
78
|
+
if (bySession !== 0)
|
|
79
|
+
return bySession;
|
|
80
|
+
const byCaller = a.lease.callerId.localeCompare(b.lease.callerId);
|
|
81
|
+
if (byCaller !== 0)
|
|
82
|
+
return byCaller;
|
|
83
|
+
return a.lease.workflowId.localeCompare(b.lease.workflowId);
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* Pick the lease that represents "who is driving peaks right now".
|
|
87
|
+
*
|
|
88
|
+
* Returns `null` when no candidate is eligible — the caller answers
|
|
89
|
+
* "inactive" (never an optimistic default).
|
|
90
|
+
*/
|
|
91
|
+
export function selectActivePresenceLease(candidates, nowMs) {
|
|
92
|
+
const eligible = candidates.filter((c) => isEligiblePresenceLease(c.lease, nowMs));
|
|
93
|
+
if (eligible.length === 0)
|
|
94
|
+
return null;
|
|
95
|
+
const bound = eligible.filter((c) => c.scope === 'bound');
|
|
96
|
+
const pool = bound.length > 0 ? bound : eligible;
|
|
97
|
+
const sorted = pool.slice().sort(compareCandidates);
|
|
98
|
+
return sorted[0] ?? null;
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Explain why the read found nothing active.
|
|
102
|
+
*
|
|
103
|
+
* Precondition: called only when `selectActivePresenceLease` returned
|
|
104
|
+
* `null` (so `eligibleCount` is 0). The `eligible-present` reason is a
|
|
105
|
+
* defensive branch for a caller that violates that precondition.
|
|
106
|
+
*/
|
|
107
|
+
export function explainInactivePresence(candidates, nowMs) {
|
|
108
|
+
let terminalCount = 0;
|
|
109
|
+
let staleCount = 0;
|
|
110
|
+
let eligibleCount = 0;
|
|
111
|
+
for (const candidate of candidates) {
|
|
112
|
+
if (isTerminalPresenceLease(candidate.lease)) {
|
|
113
|
+
terminalCount += 1;
|
|
114
|
+
continue;
|
|
115
|
+
}
|
|
116
|
+
if (isStalePresenceLease(candidate.lease, nowMs)) {
|
|
117
|
+
staleCount += 1;
|
|
118
|
+
continue;
|
|
119
|
+
}
|
|
120
|
+
eligibleCount += 1;
|
|
121
|
+
}
|
|
122
|
+
const leaseCount = candidates.length;
|
|
123
|
+
let reason;
|
|
124
|
+
if (leaseCount === 0)
|
|
125
|
+
reason = 'no-leases';
|
|
126
|
+
else if (eligibleCount > 0)
|
|
127
|
+
reason = 'eligible-present';
|
|
128
|
+
else if (terminalCount === leaseCount)
|
|
129
|
+
reason = 'all-terminal';
|
|
130
|
+
else if (staleCount === leaseCount)
|
|
131
|
+
reason = 'all-stale';
|
|
132
|
+
else
|
|
133
|
+
reason = 'terminal-and-stale';
|
|
134
|
+
return { reason, leaseCount, terminalCount, staleCount, eligibleCount };
|
|
135
|
+
}
|
|
@@ -10,17 +10,9 @@
|
|
|
10
10
|
*/
|
|
11
11
|
import { type SkillPresenceLease, type PresenceIndex, type PresenceProjection, type GcResult } from './presence-lease-types.js';
|
|
12
12
|
import { type TerminalReason } from '../workflow/workflow-graph-types.js';
|
|
13
|
-
export
|
|
14
|
-
|
|
15
|
-
}
|
|
16
|
-
export declare const STALE_HEARTBEAT_MS: number;
|
|
17
|
-
export declare const STALE_STARTED_AFTER_MS: number;
|
|
18
|
-
/** Resolve the lease directory. */
|
|
19
|
-
export declare function leaseDir(projectRoot: string, sessionId: string): string;
|
|
20
|
-
/** Resolve the caller index directory. */
|
|
21
|
-
export declare function presenceIndexDir(projectRoot: string, sessionId: string): string;
|
|
22
|
-
/** Resolve the migrations directory. */
|
|
23
|
-
export declare function migrationsDir(projectRoot: string, sessionId: string): string;
|
|
13
|
+
export { leaseDir, presenceIndexDir, migrationsDir } from './presence-lease-store.js';
|
|
14
|
+
export type { PresenceError } from './presence-lease-store.js';
|
|
15
|
+
export { STALE_HEARTBEAT_MS, STALE_STARTED_AFTER_MS } from './presence-lease-types.js';
|
|
24
16
|
export interface SetPresenceLeaseInput {
|
|
25
17
|
readonly projectRoot: string;
|
|
26
18
|
readonly sessionId?: string | null;
|