peaks-loop 4.1.4 → 4.1.6
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 +7 -2
- package/CHANGELOG.md +148 -0
- package/README-en.md +47 -183
- package/README.md +24 -188
- package/dist/cli/cli-helpers.d.ts +20 -0
- package/dist/cli/cli-helpers.js +34 -0
- package/dist/cli/commands/_register.js +2 -0
- package/dist/cli/commands/best-practice-scan-command.d.ts +11 -6
- package/dist/cli/commands/best-practice-scan-command.js +35 -20
- package/dist/cli/commands/best-practice-scan-helpers.d.ts +47 -0
- package/dist/cli/commands/best-practice-scan-helpers.js +88 -5
- package/dist/cli/commands/best-practice-scan-lookup-results.d.ts +13 -0
- package/dist/cli/commands/best-practice-scan-lookup-results.js +237 -0
- package/dist/cli/commands/code-commands.d.ts +6 -4
- package/dist/cli/commands/code-commands.js +6 -4
- package/dist/cli/commands/code-gate-command.d.ts +5 -5
- package/dist/cli/commands/code-gate-command.js +49 -9
- package/dist/cli/commands/code-mode-gate-plan-command.d.ts +1 -1
- package/dist/cli/commands/code-mode-gate-plan-command.js +2 -2
- package/dist/cli/commands/core/memory-extract-command.js +10 -5
- package/dist/cli/commands/dispatch-cli-invocation-check.d.ts +108 -0
- package/dist/cli/commands/dispatch-cli-invocation-check.js +87 -0
- package/dist/cli/commands/dispatch-cli-invocation-scan.d.ts +66 -0
- package/dist/cli/commands/dispatch-cli-invocation-scan.js +162 -0
- package/dist/cli/commands/dispatch-command-spec.js +1 -1
- package/dist/cli/commands/dispatch-commands.js +12 -5
- package/dist/cli/commands/dispatch-isolation-lease.d.ts +1 -1
- package/dist/cli/commands/dispatch-isolation-lease.js +6 -53
- package/dist/cli/commands/dispatch-preflight.js +46 -0
- package/dist/cli/commands/dispatch-prompt-blocks.d.ts +1 -1
- package/dist/cli/commands/dispatch-prompt-composition.d.ts +7 -1
- package/dist/cli/commands/dispatch-prompt-composition.js +29 -7
- package/dist/cli/commands/dispatch-record-write.d.ts +1 -1
- package/dist/cli/commands/dispatch-tool-call.d.ts +1 -1
- package/dist/cli/commands/doc-commands.js +1 -1
- package/dist/cli/commands/feedback-commands-helpers.js +1 -1
- package/dist/cli/commands/final-review-prepare-command.js +22 -1
- package/dist/cli/commands/gate-commands-enforce.js +3 -3
- package/dist/cli/commands/hook-handle.js +41 -20
- package/dist/cli/commands/lint-commands.js +3 -1
- package/dist/cli/commands/loop-eval-capture-index.js +2 -4
- package/dist/cli/commands/openspec-command-shared.js +2 -2
- package/dist/cli/commands/perf-audit-commands.js +15 -5
- package/dist/cli/commands/project-commands.js +9 -6
- package/dist/cli/commands/race-commands.d.ts +15 -0
- package/dist/cli/commands/race-commands.js +65 -0
- package/dist/cli/commands/race-pilot-gate-record-command.d.ts +3 -0
- package/dist/cli/commands/race-pilot-gate-record-command.js +81 -0
- package/dist/cli/commands/request-command-options.d.ts +8 -0
- package/dist/cli/commands/request-commands.js +2 -0
- package/dist/cli/commands/request-init-command.js +67 -12
- package/dist/cli/commands/{vm-status-command.d.ts → request-retag-command.d.ts} +1 -1
- package/dist/cli/commands/request-retag-command.js +50 -0
- package/dist/cli/commands/request-show-command.d.ts +8 -0
- package/dist/cli/commands/request-show-command.js +14 -1
- package/dist/cli/commands/request-transition-command.js +12 -4
- package/dist/cli/commands/request-transition-failures.d.ts +14 -0
- package/dist/cli/commands/request-transition-failures.js +76 -7
- package/dist/cli/commands/request-transition-preflight.js +1 -1
- package/dist/cli/commands/scan-scope-commands.js +2 -2
- package/dist/cli/commands/security-audit-commands.js +26 -6
- package/dist/cli/commands/slice-decompose-artifacts.js +2 -1
- package/dist/cli/commands/verdict-aggregate-command.js +2 -1
- package/dist/cli/commands/workflow-gate-commands.js +4 -4
- package/dist/cli/commands/worktree-lease-gc-command.js +1 -1
- package/dist/cli/program.js +0 -2
- package/dist/services/artifacts/artifact-contract-block.d.ts +53 -0
- package/dist/services/artifacts/artifact-contract-block.js +231 -0
- package/dist/services/artifacts/artifact-prerequisites.d.ts +27 -19
- package/dist/services/artifacts/artifact-prerequisites.js +65 -135
- package/dist/services/artifacts/artifact-templates.d.ts +1 -1
- package/dist/services/artifacts/artifact-templates.js +17 -10
- package/dist/services/artifacts/prerequisite-checks.d.ts +87 -0
- package/dist/services/artifacts/prerequisite-checks.js +198 -0
- package/dist/services/artifacts/prerequisite-transition-event.d.ts +20 -0
- package/dist/services/artifacts/prerequisite-transition-event.js +27 -0
- package/dist/services/artifacts/rd-transition-gates.d.ts +33 -0
- package/dist/services/artifacts/rd-transition-gates.js +71 -0
- package/dist/services/artifacts/request-artifact-metadata.d.ts +31 -0
- package/dist/services/artifacts/request-artifact-metadata.js +44 -0
- package/dist/services/artifacts/request-artifact-service.d.ts +5 -0
- package/dist/services/artifacts/request-artifact-service.js +43 -69
- package/dist/services/artifacts/request-artifact-state-helpers.d.ts +21 -1
- package/dist/services/artifacts/request-artifact-state-helpers.js +34 -8
- package/dist/services/artifacts/request-retag-service.d.ts +68 -0
- package/dist/services/artifacts/request-retag-service.js +125 -0
- package/dist/services/artifacts/request-state-order.d.ts +38 -0
- package/dist/services/artifacts/request-state-order.js +99 -0
- package/dist/services/artifacts/request-type-demand.d.ts +44 -0
- package/dist/services/artifacts/request-type-demand.js +71 -0
- package/dist/services/audit/audit-goal-service.d.ts +7 -0
- package/dist/services/audit/enforcers/active-skill-resolver.d.ts +18 -0
- package/dist/services/audit/enforcers/active-skill-resolver.js +48 -1
- package/dist/services/audit/enforcers/code-ban.d.ts +11 -2
- package/dist/services/audit/enforcers/code-ban.js +21 -1
- package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.d.ts +17 -0
- package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.js +24 -7
- package/dist/services/audit-independent/handoff-missing-refusal.d.ts +26 -0
- package/dist/services/audit-independent/handoff-missing-refusal.js +109 -0
- package/dist/services/audit-independent/handoff-readers.d.ts +37 -0
- package/dist/services/audit-independent/handoff-readers.js +81 -0
- package/dist/services/audit-independent/index.d.ts +6 -1
- package/dist/services/audit-independent/index.js +6 -1
- package/dist/services/audit-independent/judged-declaration-build.d.ts +48 -0
- package/dist/services/audit-independent/judged-declaration-build.js +73 -0
- package/dist/services/audit-independent/judged-declaration-check.d.ts +80 -0
- package/dist/services/audit-independent/judged-declaration-check.js +216 -0
- package/dist/services/audit-independent/judged-declaration.d.ts +94 -0
- package/dist/services/audit-independent/judged-declaration.js +218 -0
- package/dist/services/audit-independent/perf-audit-service.js +12 -14
- package/dist/services/audit-independent/security-audit-artifact.d.ts +28 -0
- package/dist/services/audit-independent/security-audit-artifact.js +90 -0
- package/dist/services/audit-independent/security-audit-service.d.ts +6 -53
- package/dist/services/audit-independent/security-audit-service.js +34 -178
- package/dist/services/capability-guard-runner/contracts/J05.js +60 -14
- package/dist/services/codegraph/codegraph-index-integrity.js +2 -0
- package/dist/services/context/build-dispatch-system-prompt.d.ts +8 -12
- package/dist/services/context/build-dispatch-system-prompt.js +18 -18
- package/dist/services/context/collector.js +5 -1
- package/dist/services/context/post-compact-reinjection.js +1 -1
- package/dist/services/dispatch/active-dispatch-index.d.ts +36 -0
- package/dist/services/dispatch/active-dispatch-index.js +118 -0
- package/dist/services/dispatch/batch-counter.js +1 -2
- package/dist/services/dispatch/dispatch-record-writer.d.ts +29 -16
- package/dist/services/dispatch/dispatch-record-writer.js +58 -100
- package/dist/services/dispatch/dispatch-sub-agent.js +1 -1
- package/dist/services/dispatch/karpathy-block.d.ts +55 -0
- package/dist/services/dispatch/karpathy-block.js +101 -0
- package/dist/services/dispatch/ledger-reaper.d.ts +80 -0
- package/dist/services/dispatch/ledger-reaper.js +131 -0
- package/dist/services/dispatch/test-tool-detection.d.ts +17 -1
- package/dist/services/dispatch/test-tool-detection.js +12 -1
- package/dist/services/evidence/evidence-generator.js +23 -12
- package/dist/services/feedback/feedback-promotion-service.d.ts +8 -11
- package/dist/services/feedback/feedback-promotion-service.js +30 -35
- package/dist/services/feedback/promotion-artifact-json-evidence.d.ts +18 -0
- package/dist/services/feedback/promotion-artifact-missing.d.ts +22 -0
- package/dist/services/feedback/promotion-artifact-missing.js +63 -0
- package/dist/services/final-review/final-review-contract.d.ts +95 -4
- package/dist/services/final-review/final-review-contract.js +64 -0
- package/dist/services/final-review/final-review-delivery.d.ts +13 -0
- package/dist/services/final-review/final-review-delivery.js +26 -12
- package/dist/services/final-review/final-review-evidence-collect.js +8 -53
- package/dist/services/final-review/final-review-evidence-records.d.ts +21 -0
- package/dist/services/final-review/final-review-evidence-records.js +67 -0
- package/dist/services/final-review/final-review-evidence-sources.d.ts +22 -0
- package/dist/services/final-review/final-review-evidence-sources.js +28 -4
- package/dist/services/final-review/final-review-prompt.js +19 -6
- package/dist/services/final-review/final-review-runner.js +5 -0
- package/dist/services/final-review/final-review-service.d.ts +2 -2
- package/dist/services/final-review/index.d.ts +1 -1
- package/dist/services/final-review/pre-post-diff.d.ts +2 -75
- package/dist/services/final-review/pre-post-diff.js +60 -59
- package/dist/services/hooks/pre-tool-code-gate.d.ts +7 -1
- package/dist/services/hooks/pre-tool-code-gate.js +21 -2
- package/dist/services/hooks/worktree-authorization-gate.js +6 -31
- package/dist/services/hooks/worktree-refusal-messages.d.ts +74 -0
- package/dist/services/hooks/worktree-refusal-messages.js +102 -0
- package/dist/services/lint/eslint-runner-support.d.ts +1 -1
- package/dist/services/lint/eslint-runner-support.js +2 -1
- package/dist/services/lint/eslint-runner-types.d.ts +8 -0
- package/dist/services/lint/eslint-runner.js +17 -4
- package/dist/services/llm/anthropic-runner.js +24 -7
- package/dist/services/loop/loop-observability.d.ts +39 -0
- package/dist/services/loop/loop-observability.js +55 -0
- package/dist/services/loop/monotonic-guard.js +6 -9
- package/dist/services/loop/monotonic-runner.js +8 -7
- package/dist/services/loop/run-driver.js +18 -22
- package/dist/services/memory/project-memory-service/index/kind-dispatch.js +14 -1
- package/dist/services/memory/project-memory-service/index/project-memory-plan-exec.js +13 -2
- package/dist/services/memory/project-memory-service/index.d.ts +2 -2
- package/dist/services/memory/project-memory-service/index.js +1 -1
- package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.d.ts +36 -0
- package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.js +48 -2
- package/dist/services/memory/project-memory-service/parsers/markdown-pure.d.ts +23 -1
- package/dist/services/memory/project-memory-service/parsers/markdown-pure.js +37 -0
- package/dist/services/memory/project-memory-service/types.d.ts +32 -0
- package/dist/services/observability/observability-service.d.ts +7 -0
- package/dist/services/observability/observability-service.js +2 -1
- package/dist/services/openspec/coverage-evidence-reader.d.ts +9 -9
- package/dist/services/openspec/coverage-evidence-reader.js +8 -8
- package/dist/services/openspec/openspec-archive-service.d.ts +1 -1
- package/dist/services/openspec/openspec-archive-service.js +6 -6
- package/dist/services/prd/gate-evidence-derivation.d.ts +4 -3
- package/dist/services/prd/gate-evidence-derivation.js +4 -3
- package/dist/services/qa/bdd-test-style-verifier.js +22 -8
- package/dist/services/race/gate2-evaluator.d.ts +58 -0
- package/dist/services/race/gate2-evaluator.js +111 -0
- package/dist/services/race/gate2-policy.d.ts +17 -0
- package/dist/services/race/gate2-policy.js +31 -0
- package/dist/services/race/lane-phase.d.ts +19 -0
- package/dist/services/race/lane-phase.js +113 -0
- package/dist/services/race/pilot-gate-store.d.ts +67 -0
- package/dist/services/race/pilot-gate-store.js +227 -0
- package/dist/services/scan/file-size-baseline.d.ts +33 -0
- package/dist/services/scan/file-size-baseline.js +173 -0
- package/dist/services/scan/file-size-scan.d.ts +35 -3
- package/dist/services/scan/file-size-scan.js +63 -42
- package/dist/services/scan/type-corroboration.d.ts +32 -0
- package/dist/services/scan/type-corroboration.js +51 -0
- package/dist/services/scan/type-sanity-service.d.ts +14 -0
- package/dist/services/scan/type-sanity-service.js +23 -22
- package/dist/services/security/safe-settings-path.d.ts +5 -0
- package/dist/services/security/safe-settings-path.js +64 -8
- package/dist/services/skill/resume-detector.js +11 -11
- package/dist/services/skills/hooks-codegate-superpowers.d.ts +5 -6
- package/dist/services/skills/hooks-codegate-superpowers.js +7 -8
- package/dist/services/skills/hooks-settings-service.d.ts +1 -1
- package/dist/services/skills/hooks-settings-service.js +1 -1
- package/dist/services/skills/presence-lease-order.d.ts +13 -0
- package/dist/services/skills/presence-lease-order.js +24 -0
- package/dist/services/skills/skill-conformance-service.js +1 -0
- package/dist/services/skills/skill-statusline-service.js +4 -7
- package/dist/services/slice/slice-check-service.js +8 -8
- package/dist/services/workflow/pipeline-verify-gate-support.d.ts +24 -8
- package/dist/services/workflow/pipeline-verify-gate-support.js +34 -39
- package/dist/services/workflow/pipeline-verify-qa-phase.d.ts +102 -0
- package/dist/services/workflow/pipeline-verify-qa-phase.js +176 -0
- package/dist/services/workflow/pipeline-verify-service.js +27 -28
- package/dist/services/workflow/request-type-resolution.d.ts +99 -0
- package/dist/services/workflow/request-type-resolution.js +130 -0
- package/dist/services/workflow/workflow-skip-service.d.ts +1 -20
- package/dist/services/workflow/workflow-skip-service.js +22 -25
- package/dist/services/workflow/workflow-state-store.d.ts +9 -0
- package/dist/services/workflow/workflow-state-store.js +26 -1
- package/dist/services/workspace/claude-settings-retirements.d.ts +54 -0
- package/dist/services/workspace/claude-settings-retirements.js +112 -0
- package/dist/services/workspace/claude-settings-template-merge.d.ts +35 -15
- package/dist/services/workspace/claude-settings-template-merge.js +33 -53
- package/dist/services/workspace/claude-settings-template.d.ts +62 -12
- package/dist/services/workspace/claude-settings-template.js +58 -58
- package/dist/services/workspace/migrate-1-4-1-service.js +3 -0
- package/dist/services/workspace/reconcile-service.js +0 -1
- package/dist/shared/incrementing-number.d.ts +33 -2
- package/dist/shared/incrementing-number.js +72 -3
- package/package.json +5 -7
- package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
- package/skills/bee/peaks-prd/SKILL.md +4 -3
- package/skills/bee/peaks-qa/SKILL.md +1 -1
- package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
- package/skills/bee/peaks-qa/references/qa-transition-gates.md +1 -1
- package/skills/bee/peaks-rd/SKILL.md +2 -2
- package/skills/bee/peaks-rd/references/rd-fanout-contracts.md +1 -1
- package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +8 -4
- package/skills/bee/peaks-rd/references/rd-transition-gates.md +3 -3
- package/skills/bee/peaks-rd/references/v2-12-fanout-collapse.md +2 -2
- package/skills/bee/peaks-rd/references/writing-handoff-frontmatter.md +1 -1
- package/skills/bee/peaks-reviewer/SKILL.md +1 -1
- package/skills/bee/peaks-sc/SKILL.md +1 -1
- package/skills/bee/peaks-security-audit/SKILL.md +10 -2
- package/skills/bee/peaks-txt/SKILL.md +4 -3
- package/skills/bee/peaks-ui/SKILL.md +3 -3
- package/skills/peaks-audit/SKILL.md +29 -1
- package/skills/peaks-code/SKILL.md +37 -17
- package/skills/peaks-code/references/fast-lane-norm.md +42 -0
- package/skills/peaks-code/references/fast-mode.md +3 -2
- package/skills/peaks-code/references/local-artifact-workspace.md +3 -3
- package/skills/peaks-code/references/micro-cycle.md +3 -3
- package/skills/peaks-code/references/resume-detection.md +1 -1
- package/skills/peaks-code/references/runbook.md +12 -6
- package/skills/peaks-code/references/step-11-memory-sediment.md +4 -0
- package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
- package/skills/peaks-code/references/swarm-dispatch-contract.md +40 -16
- package/skills/peaks-code/references/workflow-gates-and-types.md +6 -6
- package/skills/peaks-code/references/worktree-governance.md +4 -4
- package/skills/peaks-content/SKILL.md +1 -1
- package/skills/peaks-doctor/SKILL.md +1 -1
- package/skills/peaks-final-review/SKILL.md +31 -11
- package/skills/peaks-ide/SKILL.md +1 -1
- package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
- package/skills/peaks-race-code/SKILL.md +185 -0
- package/skills/peaks-resume/SKILL.md +1 -1
- package/skills/peaks-slice-decompose/SKILL.md +1 -1
- package/skills/peaks-solo/SKILL.md +1 -1
- package/skills/peaks-sop/SKILL.md +1 -1
- package/skills/peaks-status/SKILL.md +1 -1
- package/skills/peaks-test/SKILL.md +7 -4
- package/dist/cli/commands/vm-command-shared.d.ts +0 -23
- package/dist/cli/commands/vm-command-shared.js +0 -23
- package/dist/cli/commands/vm-commands.d.ts +0 -3
- package/dist/cli/commands/vm-commands.js +0 -45
- package/dist/cli/commands/vm-hypervisor-probe.d.ts +0 -27
- package/dist/cli/commands/vm-hypervisor-probe.js +0 -78
- package/dist/cli/commands/vm-hypervisor-runtime.d.ts +0 -15
- package/dist/cli/commands/vm-hypervisor-runtime.js +0 -64
- package/dist/cli/commands/vm-release-command.d.ts +0 -5
- package/dist/cli/commands/vm-release-command.js +0 -101
- package/dist/cli/commands/vm-spawn-command.d.ts +0 -5
- package/dist/cli/commands/vm-spawn-command.js +0 -177
- package/dist/cli/commands/vm-status-command.js +0 -50
- package/dist/services/audit/enforcers/lint-peaks-skill-runtime.d.ts +0 -23
- package/dist/services/audit/enforcers/lint-peaks-skill-runtime.js +0 -64
- package/dist/services/vm/vm-lease.d.ts +0 -40
- package/dist/services/vm/vm-lease.js +0 -160
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The per-session active-dispatches index
|
|
3
|
+
* (`.peaks/_sub_agents/<sid>/active-dispatches.json`): its path, its
|
|
4
|
+
* `Map<recordPath, ActiveDispatchEntry>` shape, and its register / unregister /
|
|
5
|
+
* read operations. The POLICY that bounds it lives in `./ledger-reaper.ts`.
|
|
6
|
+
*
|
|
7
|
+
* Split out of `./dispatch-record-writer.ts`, which was already over its
|
|
8
|
+
* file-size cap: the writer keeps the on-disk RECORD format, this module owns
|
|
9
|
+
* the INDEX — the hint the LLM-side runner and the status line read
|
|
10
|
+
* (`readActiveLeaf` in `src/services/skills/skill-statusline-model.ts`). The
|
|
11
|
+
* moved functions are byte-identical to their previous bodies apart from the
|
|
12
|
+
* terminal-status chain, which became a lookup set; `dispatch-record-writer.ts`
|
|
13
|
+
* re-exports the two public names so no importer changed.
|
|
14
|
+
*/
|
|
15
|
+
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
|
|
16
|
+
import { dirname, resolve } from 'node:path';
|
|
17
|
+
export function activeDispatchIndexPath(projectRoot, sessionId) {
|
|
18
|
+
return resolve(projectRoot, '.peaks', '_sub_agents', sessionId, 'active-dispatches.json');
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Read the index file into a plain map. A missing or corrupt file yields the
|
|
22
|
+
* empty map: the on-disk record is the source of truth and a corrupt index is
|
|
23
|
+
* rebuilt from the records rather than trusted.
|
|
24
|
+
*/
|
|
25
|
+
function readIndexMap(indexPath) {
|
|
26
|
+
const index = {};
|
|
27
|
+
if (!existsSync(indexPath))
|
|
28
|
+
return index;
|
|
29
|
+
try {
|
|
30
|
+
const raw = readFileSync(indexPath, 'utf8');
|
|
31
|
+
const parsed = JSON.parse(raw);
|
|
32
|
+
if (typeof parsed === 'object' && parsed !== null) {
|
|
33
|
+
for (const [k, v] of Object.entries(parsed)) {
|
|
34
|
+
if (typeof v === 'object' && v !== null && 'recordPath' in v) {
|
|
35
|
+
index[k] = v;
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
catch (error) {
|
|
41
|
+
// Rebuilt from the empty map. `error` is held so the block is not an empty
|
|
42
|
+
// catch; the reason is that a corrupt index is not a fact worth reporting,
|
|
43
|
+
// only a reason to re-read the records.
|
|
44
|
+
void error;
|
|
45
|
+
}
|
|
46
|
+
return index;
|
|
47
|
+
}
|
|
48
|
+
export function registerActiveDispatch(input) {
|
|
49
|
+
const indexPath = activeDispatchIndexPath(input.projectRoot, input.sessionId);
|
|
50
|
+
const dir = dirname(indexPath);
|
|
51
|
+
if (!existsSync(dir)) {
|
|
52
|
+
mkdirSync(dir, { recursive: true });
|
|
53
|
+
}
|
|
54
|
+
const index = readIndexMap(indexPath);
|
|
55
|
+
index[input.recordPath] = {
|
|
56
|
+
recordPath: input.recordPath,
|
|
57
|
+
requestId: input.requestId,
|
|
58
|
+
role: input.role,
|
|
59
|
+
batchId: input.batchId,
|
|
60
|
+
createdAt: input.now().toISOString(),
|
|
61
|
+
status: 'queued'
|
|
62
|
+
};
|
|
63
|
+
const tmp = `${indexPath}.tmp-${process.pid}-${Date.now()}`;
|
|
64
|
+
writeFileSync(tmp, JSON.stringify(index, null, 2) + '\n', 'utf8');
|
|
65
|
+
renameSync(tmp, indexPath);
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Statuses that mean the dispatch is over. The startup-timeout service writes
|
|
69
|
+
* the last two as terminal markers, and the finalize CLI writes the rest;
|
|
70
|
+
* unregister must remove the row on all of them.
|
|
71
|
+
*
|
|
72
|
+
* A set rather than a six-way `||` chain: the chain cost the function five
|
|
73
|
+
* branches for a lookup that is data, and pushed its complexity over the
|
|
74
|
+
* eslint ceiling on the way into this module.
|
|
75
|
+
*/
|
|
76
|
+
const TERMINAL_INDEX_STATUSES = new Set([
|
|
77
|
+
'done',
|
|
78
|
+
'failed',
|
|
79
|
+
'cancelled',
|
|
80
|
+
'no-execution',
|
|
81
|
+
'never-started',
|
|
82
|
+
'unreadable'
|
|
83
|
+
]);
|
|
84
|
+
export function unregisterActiveDispatch(input) {
|
|
85
|
+
const indexPath = activeDispatchIndexPath(input.projectRoot, input.sessionId);
|
|
86
|
+
if (!existsSync(indexPath))
|
|
87
|
+
return;
|
|
88
|
+
const index = readIndexMap(indexPath);
|
|
89
|
+
const existing = index[input.recordPath];
|
|
90
|
+
if (existing === undefined)
|
|
91
|
+
return;
|
|
92
|
+
if (TERMINAL_INDEX_STATUSES.has(input.status)) {
|
|
93
|
+
delete index[input.recordPath];
|
|
94
|
+
}
|
|
95
|
+
else {
|
|
96
|
+
index[input.recordPath] = { ...existing, status: input.status };
|
|
97
|
+
}
|
|
98
|
+
const tmp = `${indexPath}.tmp-${process.pid}-${Date.now()}`;
|
|
99
|
+
writeFileSync(tmp, JSON.stringify(index, null, 2) + '\n', 'utf8');
|
|
100
|
+
renameSync(tmp, indexPath);
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* for a session. Returns the current map<recordPath, entry>. Used
|
|
104
|
+
* by the LLM-side runner to discover in-flight records on restart.
|
|
105
|
+
* Returns an empty map when the index file is missing or corrupt
|
|
106
|
+
* (the on-disk records directory is the next fallback).
|
|
107
|
+
*/
|
|
108
|
+
export function readActiveDispatchIndex(projectRoot, sessionId) {
|
|
109
|
+
const indexPath = activeDispatchIndexPath(projectRoot, sessionId);
|
|
110
|
+
const index = readIndexMap(indexPath);
|
|
111
|
+
const out = {};
|
|
112
|
+
for (const [k, v] of Object.entries(index)) {
|
|
113
|
+
if ('role' in v) {
|
|
114
|
+
out[k] = v;
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
return out;
|
|
118
|
+
}
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
* that's your call". A warning is the right surface — let the LLM /
|
|
22
22
|
* human read the reason and decide.
|
|
23
23
|
*/
|
|
24
|
-
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
24
|
+
import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
|
|
25
25
|
import { dirname, resolve } from 'node:path';
|
|
26
26
|
import { withFileLockSync } from 'peaks-loop-shared-channel';
|
|
27
27
|
export const BATCH_LIMIT = 6;
|
|
@@ -91,7 +91,6 @@ export function resetBatch(projectRoot, sid, batchId) {
|
|
|
91
91
|
const path = batchCounterPath(projectRoot, sid, batchId);
|
|
92
92
|
if (existsSync(path)) {
|
|
93
93
|
try {
|
|
94
|
-
const { unlinkSync } = require('node:fs');
|
|
95
94
|
unlinkSync(path);
|
|
96
95
|
}
|
|
97
96
|
catch {
|
|
@@ -8,25 +8,38 @@ export declare function writeInitialDispatchRecord(input: WriteInitialDispatchIn
|
|
|
8
8
|
record: DispatchRecord;
|
|
9
9
|
};
|
|
10
10
|
/**
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
11
|
+
* Bound the dispatch ledger before a new record registers: index rows left
|
|
12
|
+
* `queued` past the bound, whose record is still `queued`, are finalized by the
|
|
13
|
+
* tooling rather than by a remembered `peaks sub-agent finalize` call (measured:
|
|
14
|
+
* 39/39, 2/2, 9/9, 23/23 rows across four sessions had never been finalized).
|
|
15
|
+
*
|
|
16
|
+
* The RECORD decides, not the index row. Nothing writes a mid-flight status into
|
|
17
|
+
* a row — `registerActiveDispatch` hardcodes `queued` and the only unregister
|
|
18
|
+
* caller deletes the row — so a row reads `queued` for a sub-agent that is
|
|
19
|
+
* heartbeating right now, and a row-keyed guard would reap a live dispatch.
|
|
20
|
+
* `no-execution` is terminal for the heartbeat pollers, so that would stop a
|
|
21
|
+
* watcher waiting on work that is still running.
|
|
22
|
+
*
|
|
23
|
+
* The clock passed in is the SAME one that stamps this dispatch's `createdAt`,
|
|
24
|
+
* so the bound is judged on one clock and a caller that injects a clock (every
|
|
25
|
+
* test, and any replay) sees a consistent frame.
|
|
26
|
+
*/
|
|
27
|
+
/**
|
|
28
|
+
* The record's own status, or `null` when the record file is absent. An
|
|
29
|
+
* unparseable file reports `unreadable` — a real terminal status — rather than
|
|
30
|
+
* `null`, so a caller can tell "no record here" from "a record I may not
|
|
31
|
+
* rewrite"; the reaper drops a row only for the first.
|
|
32
|
+
*
|
|
33
|
+
* Exported because the reaper takes it as its reader, so production and its
|
|
34
|
+
* tests judge on the same implementation rather than on two copies of it.
|
|
14
35
|
*/
|
|
15
|
-
export
|
|
16
|
-
readonly recordPath: string;
|
|
17
|
-
readonly requestId: string;
|
|
18
|
-
readonly role: string;
|
|
19
|
-
readonly batchId: string;
|
|
20
|
-
readonly createdAt: string;
|
|
21
|
-
readonly status: 'queued' | 'running' | 'finalizing' | 'done' | 'failed' | 'cancelled' | 'stale' | 'no-execution' | 'never-started' | 'unreadable';
|
|
22
|
-
}
|
|
36
|
+
export declare function readRecordStatus(recordPath: string): string | null;
|
|
23
37
|
/**
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
* (the on-disk records directory is the next fallback).
|
|
38
|
+
* The active-dispatches index lives in `./active-dispatch-index.ts` (split out
|
|
39
|
+
* to keep this file under its size cap). Re-exported here so every existing
|
|
40
|
+
* importer keeps its path.
|
|
28
41
|
*/
|
|
29
|
-
export
|
|
42
|
+
export { readActiveDispatchIndex, type ActiveDispatchEntry } from './active-dispatch-index.js';
|
|
30
43
|
export declare const DISPATCH_RECORD_TTL_DAYS = 30;
|
|
31
44
|
/**
|
|
32
45
|
* (older than DISPATCH_RECORD_TTL_DAYS or already GC'd)? Mirrors
|
|
@@ -25,6 +25,8 @@ import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSyn
|
|
|
25
25
|
import { dirname, resolve } from 'node:path';
|
|
26
26
|
import { assertSafeDispatchRecordPath, dispatchRecordPath } from '../security/safe-settings-path.js';
|
|
27
27
|
import { withFileLockSync } from 'peaks-loop-shared-channel';
|
|
28
|
+
import { registerActiveDispatch, unregisterActiveDispatch } from './active-dispatch-index.js';
|
|
29
|
+
import { reapStaleQueuedEntries } from './ledger-reaper.js';
|
|
28
30
|
import { isStageLabel } from './stage-enum.js';
|
|
29
31
|
import { emitLeaseEvent } from '../observability/observability-service.js';
|
|
30
32
|
import { upgradeRecord } from './dispatch-record-upgrade.js';
|
|
@@ -50,6 +52,8 @@ export function writeInitialDispatchRecord(input) {
|
|
|
50
52
|
// source of truth; the index is purely a hint for the LLM-side
|
|
51
53
|
// runner. A crash between writeAtomic and the index write is
|
|
52
54
|
// non-fatal — the next restart scans the directory anyway.
|
|
55
|
+
// Bound the ledger BEFORE this dispatch registers (see the helper below).
|
|
56
|
+
reapLedgerBeforeRegister({ projectRoot, sessionId, now });
|
|
53
57
|
registerActiveDispatch({
|
|
54
58
|
projectRoot,
|
|
55
59
|
sessionId,
|
|
@@ -61,6 +65,56 @@ export function writeInitialDispatchRecord(input) {
|
|
|
61
65
|
});
|
|
62
66
|
return { path: safePath, record };
|
|
63
67
|
}
|
|
68
|
+
/**
|
|
69
|
+
* Bound the dispatch ledger before a new record registers: index rows left
|
|
70
|
+
* `queued` past the bound, whose record is still `queued`, are finalized by the
|
|
71
|
+
* tooling rather than by a remembered `peaks sub-agent finalize` call (measured:
|
|
72
|
+
* 39/39, 2/2, 9/9, 23/23 rows across four sessions had never been finalized).
|
|
73
|
+
*
|
|
74
|
+
* The RECORD decides, not the index row. Nothing writes a mid-flight status into
|
|
75
|
+
* a row — `registerActiveDispatch` hardcodes `queued` and the only unregister
|
|
76
|
+
* caller deletes the row — so a row reads `queued` for a sub-agent that is
|
|
77
|
+
* heartbeating right now, and a row-keyed guard would reap a live dispatch.
|
|
78
|
+
* `no-execution` is terminal for the heartbeat pollers, so that would stop a
|
|
79
|
+
* watcher waiting on work that is still running.
|
|
80
|
+
*
|
|
81
|
+
* The clock passed in is the SAME one that stamps this dispatch's `createdAt`,
|
|
82
|
+
* so the bound is judged on one clock and a caller that injects a clock (every
|
|
83
|
+
* test, and any replay) sees a consistent frame.
|
|
84
|
+
*/
|
|
85
|
+
/**
|
|
86
|
+
* The record's own status, or `null` when the record file is absent. An
|
|
87
|
+
* unparseable file reports `unreadable` — a real terminal status — rather than
|
|
88
|
+
* `null`, so a caller can tell "no record here" from "a record I may not
|
|
89
|
+
* rewrite"; the reaper drops a row only for the first.
|
|
90
|
+
*
|
|
91
|
+
* Exported because the reaper takes it as its reader, so production and its
|
|
92
|
+
* tests judge on the same implementation rather than on two copies of it.
|
|
93
|
+
*/
|
|
94
|
+
export function readRecordStatus(recordPath) {
|
|
95
|
+
if (!existsSync(recordPath))
|
|
96
|
+
return null;
|
|
97
|
+
try {
|
|
98
|
+
return readRecord(recordPath).status;
|
|
99
|
+
}
|
|
100
|
+
catch {
|
|
101
|
+
return 'unreadable';
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
function reapLedgerBeforeRegister(input) {
|
|
105
|
+
reapStaleQueuedEntries({
|
|
106
|
+
projectRoot: input.projectRoot,
|
|
107
|
+
sessionId: input.sessionId,
|
|
108
|
+
now: input.now,
|
|
109
|
+
readStatus: readRecordStatus,
|
|
110
|
+
finalize: (recordPath) => markCompleted({
|
|
111
|
+
recordPath,
|
|
112
|
+
outcome: 'no-execution',
|
|
113
|
+
status: 'no-execution',
|
|
114
|
+
projectRoot: input.projectRoot
|
|
115
|
+
})
|
|
116
|
+
});
|
|
117
|
+
}
|
|
64
118
|
/**
|
|
65
119
|
* Construct the initial `DispatchRecord` from a `WriteInitialDispatchInput`.
|
|
66
120
|
* PRD-002b slice 6: extracted from `writeInitialDispatchRecord` so the
|
|
@@ -149,108 +203,12 @@ function buildInitialDispatchRecord(input, now) {
|
|
|
149
203
|
: null
|
|
150
204
|
};
|
|
151
205
|
}
|
|
152
|
-
function activeDispatchIndexPath(projectRoot, sessionId) {
|
|
153
|
-
return resolve(projectRoot, '.peaks', '_sub_agents', sessionId, 'active-dispatches.json');
|
|
154
|
-
}
|
|
155
|
-
function registerActiveDispatch(input) {
|
|
156
|
-
const indexPath = activeDispatchIndexPath(input.projectRoot, input.sessionId);
|
|
157
|
-
const dir = dirname(indexPath);
|
|
158
|
-
if (!existsSync(dir)) {
|
|
159
|
-
mkdirSync(dir, { recursive: true });
|
|
160
|
-
}
|
|
161
|
-
let index = {};
|
|
162
|
-
try {
|
|
163
|
-
if (existsSync(indexPath)) {
|
|
164
|
-
const raw = readFileSync(indexPath, 'utf8');
|
|
165
|
-
const parsed = JSON.parse(raw);
|
|
166
|
-
if (typeof parsed === 'object' && parsed !== null) {
|
|
167
|
-
for (const [k, v] of Object.entries(parsed)) {
|
|
168
|
-
if (typeof v === 'object' && v !== null && 'recordPath' in v) {
|
|
169
|
-
index[k] = v;
|
|
170
|
-
}
|
|
171
|
-
}
|
|
172
|
-
}
|
|
173
|
-
}
|
|
174
|
-
}
|
|
175
|
-
catch {
|
|
176
|
-
// Corrupt index — start fresh. The on-disk record is the source of truth.
|
|
177
|
-
index = {};
|
|
178
|
-
}
|
|
179
|
-
index[input.recordPath] = {
|
|
180
|
-
recordPath: input.recordPath,
|
|
181
|
-
requestId: input.requestId,
|
|
182
|
-
role: input.role,
|
|
183
|
-
batchId: input.batchId,
|
|
184
|
-
createdAt: input.now().toISOString(),
|
|
185
|
-
status: 'queued'
|
|
186
|
-
};
|
|
187
|
-
const tmp = `${indexPath}.tmp-${process.pid}-${Date.now()}`;
|
|
188
|
-
writeFileSync(tmp, JSON.stringify(index, null, 2) + '\n', 'utf8');
|
|
189
|
-
renameSync(tmp, indexPath);
|
|
190
|
-
}
|
|
191
|
-
function unregisterActiveDispatch(input) {
|
|
192
|
-
const indexPath = activeDispatchIndexPath(input.projectRoot, input.sessionId);
|
|
193
|
-
if (!existsSync(indexPath))
|
|
194
|
-
return;
|
|
195
|
-
let index = {};
|
|
196
|
-
try {
|
|
197
|
-
const raw = readFileSync(indexPath, 'utf8');
|
|
198
|
-
const parsed = JSON.parse(raw);
|
|
199
|
-
if (typeof parsed === 'object' && parsed !== null) {
|
|
200
|
-
for (const [k, v] of Object.entries(parsed)) {
|
|
201
|
-
if (typeof v === 'object' && v !== null && 'recordPath' in v) {
|
|
202
|
-
index[k] = v;
|
|
203
|
-
}
|
|
204
|
-
}
|
|
205
|
-
}
|
|
206
|
-
}
|
|
207
|
-
catch {
|
|
208
|
-
return;
|
|
209
|
-
}
|
|
210
|
-
if (input.recordPath in index) {
|
|
211
|
-
index[input.recordPath] = { ...index[input.recordPath], status: input.status };
|
|
212
|
-
// and `unreadable` are terminal (the startup-timeout service writes
|
|
213
|
-
// them as terminal markers). Unregister on the full terminal set.
|
|
214
|
-
if (input.status === 'done' ||
|
|
215
|
-
input.status === 'failed' ||
|
|
216
|
-
input.status === 'cancelled' ||
|
|
217
|
-
input.status === 'no-execution' ||
|
|
218
|
-
input.status === 'never-started' ||
|
|
219
|
-
input.status === 'unreadable') {
|
|
220
|
-
delete index[input.recordPath];
|
|
221
|
-
}
|
|
222
|
-
const tmp = `${indexPath}.tmp-${process.pid}-${Date.now()}`;
|
|
223
|
-
writeFileSync(tmp, JSON.stringify(index, null, 2) + '\n', 'utf8');
|
|
224
|
-
renameSync(tmp, indexPath);
|
|
225
|
-
}
|
|
226
|
-
}
|
|
227
206
|
/**
|
|
228
|
-
*
|
|
229
|
-
*
|
|
230
|
-
*
|
|
231
|
-
* (the on-disk records directory is the next fallback).
|
|
207
|
+
* The active-dispatches index lives in `./active-dispatch-index.ts` (split out
|
|
208
|
+
* to keep this file under its size cap). Re-exported here so every existing
|
|
209
|
+
* importer keeps its path.
|
|
232
210
|
*/
|
|
233
|
-
export
|
|
234
|
-
const indexPath = activeDispatchIndexPath(projectRoot, sessionId);
|
|
235
|
-
if (!existsSync(indexPath))
|
|
236
|
-
return {};
|
|
237
|
-
try {
|
|
238
|
-
const raw = readFileSync(indexPath, 'utf8');
|
|
239
|
-
const parsed = JSON.parse(raw);
|
|
240
|
-
if (typeof parsed !== 'object' || parsed === null)
|
|
241
|
-
return {};
|
|
242
|
-
const out = {};
|
|
243
|
-
for (const [k, v] of Object.entries(parsed)) {
|
|
244
|
-
if (typeof v === 'object' && v !== null && 'recordPath' in v && 'role' in v) {
|
|
245
|
-
out[k] = v;
|
|
246
|
-
}
|
|
247
|
-
}
|
|
248
|
-
return out;
|
|
249
|
-
}
|
|
250
|
-
catch {
|
|
251
|
-
return {};
|
|
252
|
-
}
|
|
253
|
-
}
|
|
211
|
+
export { readActiveDispatchIndex } from './active-dispatch-index.js';
|
|
254
212
|
export const DISPATCH_RECORD_TTL_DAYS = 30;
|
|
255
213
|
/**
|
|
256
214
|
* (older than DISPATCH_RECORD_TTL_DAYS or already GC'd)? Mirrors
|
|
@@ -19,9 +19,9 @@
|
|
|
19
19
|
* The export is intentional — the helper has zero side effects and
|
|
20
20
|
* keeps the dispatch action handler small.
|
|
21
21
|
*/
|
|
22
|
+
import { execFileSync } from 'node:child_process';
|
|
22
23
|
export function runGitLsFiles(projectRoot, glob) {
|
|
23
24
|
try {
|
|
24
|
-
const { execFileSync } = require('node:child_process');
|
|
25
25
|
const stdout = execFileSync('git', ['ls-files', '--', glob], {
|
|
26
26
|
cwd: projectRoot,
|
|
27
27
|
encoding: 'utf8',
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Karpathy-guidelines context block, machine-injected into every sub-agent
|
|
3
|
+
* prompt by the dispatch prompt composer
|
|
4
|
+
* (`src/cli/commands/dispatch-prompt-composition.ts`), the same way the Test
|
|
5
|
+
* Tool Detection block is injected by `./test-tool-detection.ts`.
|
|
6
|
+
*
|
|
7
|
+
* Why this module exists: the obligation to deliver this block lived only as
|
|
8
|
+
* prose in `skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md`, addressed
|
|
9
|
+
* to the orchestrator. Measured 2026-10-12: four RD dispatch prompts in one
|
|
10
|
+
* session carried zero occurrences of `Karpathy`, and the one block that WAS
|
|
11
|
+
* appended had a word wrong — which the verbatim requirement makes a defect.
|
|
12
|
+
* An obligation a busy caller can forget is not an executor; this is.
|
|
13
|
+
*
|
|
14
|
+
* SOURCE OF TRUTH: the fenced block in the reference file's
|
|
15
|
+
* §"Karpathy-guidelines context" section is the canonical human-facing text;
|
|
16
|
+
* `KARPATHY_GUIDELINES_BLOCK` below is its machine copy, and
|
|
17
|
+
* `tests/unit/services/dispatch/karpathy-block.test.ts` asserts the two are
|
|
18
|
+
* byte-equal, so the copy cannot drift silently. A second copy that CAN drift
|
|
19
|
+
* is the same defect class as the dropped block; a pinned one is not.
|
|
20
|
+
*
|
|
21
|
+
* Why a static constant rather than a per-call read of the reference file
|
|
22
|
+
* (same reasoning as `./test-tool-detection.ts`): dispatch is a hot path, and
|
|
23
|
+
* the skill tree is not guaranteed to be present in an installed bundle.
|
|
24
|
+
*/
|
|
25
|
+
/**
|
|
26
|
+
* The canonical block, verbatim. Byte-for-byte the fenced block under
|
|
27
|
+
* §"Karpathy-guidelines context" in the RD dispatch reference, including its
|
|
28
|
+
* trailing newline.
|
|
29
|
+
*/
|
|
30
|
+
export declare const KARPATHY_GUIDELINES_BLOCK = "Karpathy-guidelines context (REQUIRED \u2014 read before any code action)\n\nThe 4 Karpathy guidelines are mandatory for every planning, implementation, refactor, and review action you take. If 200 lines could be 50, rewrite. Touch only what the request requires. Surface assumptions, do not hide them. Define verifiable success criteria.\n\n1. Think Before Coding\n\nDon't assume. Don't hide confusion. Surface tradeoffs. Before implementing: state assumptions explicitly; if multiple interpretations exist, present them; if a simpler approach exists, say so; if unclear, stop and ask.\n\n2. Simplicity First\n\nMinimum code that solves the problem. Nothing speculative. No features beyond what was asked. No abstractions for single-use code. No \"flexibility\" or \"configurability\" that wasn't requested. No error handling for impossible scenarios. If you write 200 lines and it could be 50, rewrite it. Ask yourself: \"Would a senior engineer say this is overcomplicated?\" If yes, simplify.\n\n3. Surgical Changes\n\nTouch only what you must. Clean up only your own mess. When editing existing code: don't \"improve\" adjacent code, comments, or formatting; don't refactor things that aren't broken; match existing style. When your changes create orphans: remove imports/variables/functions that YOUR changes made unused. The test: every changed line should trace directly to the user's request.\n\n4. Goal-Driven Execution\n\nDefine success criteria. Loop until verified. \"Add validation\" \u2192 write tests for invalid inputs, then make them pass. \"Fix the bug\" \u2192 write a test that reproduces it, then make it pass. For multi-step tasks, state a brief plan with verify checkpoints. Strong success criteria let you loop independently. Weak criteria require constant clarification.\n";
|
|
31
|
+
/** True when `text` already carries the canonical block (see the boundary note above). */
|
|
32
|
+
export declare function hasKarpathyBlock(text: string): boolean;
|
|
33
|
+
/**
|
|
34
|
+
* Ensure `text` carries the canonical block. Pure and idempotent.
|
|
35
|
+
*
|
|
36
|
+
* - `text` already carries the block (per {@link hasKarpathyBlock}) → returned
|
|
37
|
+
* unchanged, byte for byte. This is the compliant caller's guarantee: no
|
|
38
|
+
* double-append and no reflow of a prompt that already has the block.
|
|
39
|
+
* - otherwise → `text` with the block appended, and `text` itself untouched.
|
|
40
|
+
*
|
|
41
|
+
* Near-miss policy, stated rather than left implicit: when the caller carries a
|
|
42
|
+
* copy whose body differs, the canonical block is injected anyway and the
|
|
43
|
+
* caller's copy is left in place. Deleting text a caller wrote is not this
|
|
44
|
+
* function's job; delivering the canonical text is. The cost is two
|
|
45
|
+
* "Karpathy-guidelines context" headings in that prompt — visible, and the one
|
|
46
|
+
* the child must obey is the canonical one.
|
|
47
|
+
*
|
|
48
|
+
* The caller applies this to the assembled prompt, not to the caller's draft —
|
|
49
|
+
* see `composeDispatchPrompt`, which runs it on `effectivePrompt` (the exact
|
|
50
|
+
* string handed to the sub-agent as `toolCall.args.prompt` and recorded as the
|
|
51
|
+
* dispatch record's `prompt`). The caller's draft is inside that string
|
|
52
|
+
* verbatim, so a draft-side copy is matched too, and the check also catches a
|
|
53
|
+
* block some other contributor put in the assembled text.
|
|
54
|
+
*/
|
|
55
|
+
export declare function ensureKarpathyBlock(text: string): string;
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Karpathy-guidelines context block, machine-injected into every sub-agent
|
|
3
|
+
* prompt by the dispatch prompt composer
|
|
4
|
+
* (`src/cli/commands/dispatch-prompt-composition.ts`), the same way the Test
|
|
5
|
+
* Tool Detection block is injected by `./test-tool-detection.ts`.
|
|
6
|
+
*
|
|
7
|
+
* Why this module exists: the obligation to deliver this block lived only as
|
|
8
|
+
* prose in `skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md`, addressed
|
|
9
|
+
* to the orchestrator. Measured 2026-10-12: four RD dispatch prompts in one
|
|
10
|
+
* session carried zero occurrences of `Karpathy`, and the one block that WAS
|
|
11
|
+
* appended had a word wrong — which the verbatim requirement makes a defect.
|
|
12
|
+
* An obligation a busy caller can forget is not an executor; this is.
|
|
13
|
+
*
|
|
14
|
+
* SOURCE OF TRUTH: the fenced block in the reference file's
|
|
15
|
+
* §"Karpathy-guidelines context" section is the canonical human-facing text;
|
|
16
|
+
* `KARPATHY_GUIDELINES_BLOCK` below is its machine copy, and
|
|
17
|
+
* `tests/unit/services/dispatch/karpathy-block.test.ts` asserts the two are
|
|
18
|
+
* byte-equal, so the copy cannot drift silently. A second copy that CAN drift
|
|
19
|
+
* is the same defect class as the dropped block; a pinned one is not.
|
|
20
|
+
*
|
|
21
|
+
* Why a static constant rather than a per-call read of the reference file
|
|
22
|
+
* (same reasoning as `./test-tool-detection.ts`): dispatch is a hot path, and
|
|
23
|
+
* the skill tree is not guaranteed to be present in an installed bundle.
|
|
24
|
+
*/
|
|
25
|
+
/**
|
|
26
|
+
* The canonical block, verbatim. Byte-for-byte the fenced block under
|
|
27
|
+
* §"Karpathy-guidelines context" in the RD dispatch reference, including its
|
|
28
|
+
* trailing newline.
|
|
29
|
+
*/
|
|
30
|
+
export const KARPATHY_GUIDELINES_BLOCK = `Karpathy-guidelines context (REQUIRED — read before any code action)
|
|
31
|
+
|
|
32
|
+
The 4 Karpathy guidelines are mandatory for every planning, implementation, refactor, and review action you take. If 200 lines could be 50, rewrite. Touch only what the request requires. Surface assumptions, do not hide them. Define verifiable success criteria.
|
|
33
|
+
|
|
34
|
+
1. Think Before Coding
|
|
35
|
+
|
|
36
|
+
Don't assume. Don't hide confusion. Surface tradeoffs. Before implementing: state assumptions explicitly; if multiple interpretations exist, present them; if a simpler approach exists, say so; if unclear, stop and ask.
|
|
37
|
+
|
|
38
|
+
2. Simplicity First
|
|
39
|
+
|
|
40
|
+
Minimum code that solves the problem. Nothing speculative. No features beyond what was asked. No abstractions for single-use code. No "flexibility" or "configurability" that wasn't requested. No error handling for impossible scenarios. If you write 200 lines and it could be 50, rewrite it. Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
|
|
41
|
+
|
|
42
|
+
3. Surgical Changes
|
|
43
|
+
|
|
44
|
+
Touch only what you must. Clean up only your own mess. When editing existing code: don't "improve" adjacent code, comments, or formatting; don't refactor things that aren't broken; match existing style. When your changes create orphans: remove imports/variables/functions that YOUR changes made unused. The test: every changed line should trace directly to the user's request.
|
|
45
|
+
|
|
46
|
+
4. Goal-Driven Execution
|
|
47
|
+
|
|
48
|
+
Define success criteria. Loop until verified. "Add validation" → write tests for invalid inputs, then make them pass. "Fix the bug" → write a test that reproduces it, then make it pass. For multi-step tasks, state a brief plan with verify checkpoints. Strong success criteria let you loop independently. Weak criteria require constant clarification.
|
|
49
|
+
`;
|
|
50
|
+
/**
|
|
51
|
+
* The block as the presence test compares it: line endings normalized to `\n`
|
|
52
|
+
* and trailing whitespace trimmed.
|
|
53
|
+
*
|
|
54
|
+
* The trailing boundary is NOT part of the block's identity, and treating it as
|
|
55
|
+
* part of it is a measured defect, not a hypothetical one. A caller that passes
|
|
56
|
+
* its prompt through a shell round-trip (`--prompt "$(cat prompt.txt)"`) or
|
|
57
|
+
* through any tool that trims the last newline hands the CLI the block MINUS
|
|
58
|
+
* its final `\n`; a byte-exact `includes()` then read that as "no block" and
|
|
59
|
+
* appended a second, identical copy — the double-append the contract forbids,
|
|
60
|
+
* reproduced end to end on 2026-10-13. The same normalization answers a Windows
|
|
61
|
+
* checkout, where the reference file the caller copies from may carry CRLF
|
|
62
|
+
* while the constant does not.
|
|
63
|
+
*
|
|
64
|
+
* What is deliberately NOT normalized: the block's BODY. A copy with one word
|
|
65
|
+
* wrong is still treated as absent and the canonical text is added, because the
|
|
66
|
+
* requirement is verbatim delivery and the measured 2026-10-12 failure was
|
|
67
|
+
* exactly a block appended with a word wrong. A header line alone is likewise
|
|
68
|
+
* not evidence: matching the header would accept the wrong body.
|
|
69
|
+
*/
|
|
70
|
+
const KARPATHY_GUIDELINES_BLOCK_FOR_PRESENCE = KARPATHY_GUIDELINES_BLOCK.replace(/\r\n/g, '\n').trimEnd();
|
|
71
|
+
/** True when `text` already carries the canonical block (see the boundary note above). */
|
|
72
|
+
export function hasKarpathyBlock(text) {
|
|
73
|
+
return text.replace(/\r\n/g, '\n').includes(KARPATHY_GUIDELINES_BLOCK_FOR_PRESENCE);
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Ensure `text` carries the canonical block. Pure and idempotent.
|
|
77
|
+
*
|
|
78
|
+
* - `text` already carries the block (per {@link hasKarpathyBlock}) → returned
|
|
79
|
+
* unchanged, byte for byte. This is the compliant caller's guarantee: no
|
|
80
|
+
* double-append and no reflow of a prompt that already has the block.
|
|
81
|
+
* - otherwise → `text` with the block appended, and `text` itself untouched.
|
|
82
|
+
*
|
|
83
|
+
* Near-miss policy, stated rather than left implicit: when the caller carries a
|
|
84
|
+
* copy whose body differs, the canonical block is injected anyway and the
|
|
85
|
+
* caller's copy is left in place. Deleting text a caller wrote is not this
|
|
86
|
+
* function's job; delivering the canonical text is. The cost is two
|
|
87
|
+
* "Karpathy-guidelines context" headings in that prompt — visible, and the one
|
|
88
|
+
* the child must obey is the canonical one.
|
|
89
|
+
*
|
|
90
|
+
* The caller applies this to the assembled prompt, not to the caller's draft —
|
|
91
|
+
* see `composeDispatchPrompt`, which runs it on `effectivePrompt` (the exact
|
|
92
|
+
* string handed to the sub-agent as `toolCall.args.prompt` and recorded as the
|
|
93
|
+
* dispatch record's `prompt`). The caller's draft is inside that string
|
|
94
|
+
* verbatim, so a draft-side copy is matched too, and the check also catches a
|
|
95
|
+
* block some other contributor put in the assembled text.
|
|
96
|
+
*/
|
|
97
|
+
export function ensureKarpathyBlock(text) {
|
|
98
|
+
if (hasKarpathyBlock(text))
|
|
99
|
+
return text;
|
|
100
|
+
return `${text}\n\n${KARPATHY_GUIDELINES_BLOCK}`;
|
|
101
|
+
}
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How long a row may sit in the index still `queued` before the next dispatch
|
|
3
|
+
* write reaps it.
|
|
4
|
+
*
|
|
5
|
+
* Six hours, from the ledger's own data rather than a round number: the ACTIVE
|
|
6
|
+
* session's index spans 8.6 hours and holds 18 entries, all `queued`; the
|
|
7
|
+
* largest gap between two dispatches in it is 4h19m. The bound must clear the
|
|
8
|
+
* longest dispatch a session can legitimately still be running, and 6h is above
|
|
9
|
+
* every dispatch interval this ledger records while staying two orders of
|
|
10
|
+
* magnitude tighter than the 30-day `DISPATCH_RECORD_TTL_DAYS` file GC.
|
|
11
|
+
*
|
|
12
|
+
* Only a row whose RECORD is still `queued` is reaped. The residual risk is
|
|
13
|
+
* recorded rather than hidden: a sub-agent still running when the session
|
|
14
|
+
* dispatches again after a longer-than-six-hour gap has its bookkeeping cleared
|
|
15
|
+
* early. Its work is unaffected; its later finalize call finds nothing `queued`
|
|
16
|
+
* and reports that.
|
|
17
|
+
*
|
|
18
|
+
* One thing the reap inherits rather than causes, recorded because it is
|
|
19
|
+
* invisible otherwise: `markCompleted` also attempts a graph `envelope-received`
|
|
20
|
+
* transition, and the reaped records are graph-bound. That transition is inert —
|
|
21
|
+
* measured 2026-10-13, 54/54 nodes in `.peaks/_runtime/<sessionId>/graphs/` are
|
|
22
|
+
* still `prepared` — so the reap changes no graph state. Documented, not fixed.
|
|
23
|
+
*/
|
|
24
|
+
export declare const LEDGER_REAP_BOUND_MS: number;
|
|
25
|
+
export interface ReapStaleQueuedEntriesInput {
|
|
26
|
+
projectRoot: string;
|
|
27
|
+
sessionId: string;
|
|
28
|
+
/**
|
|
29
|
+
* The RECORD's own status — the source of truth — or `null` when the record
|
|
30
|
+
* file is absent. Injected rather than read here so this module does not
|
|
31
|
+
* import the writer that imports it.
|
|
32
|
+
*
|
|
33
|
+
* Why the record and not the index row: no production path ever writes a
|
|
34
|
+
* mid-flight status into a row. `registerActiveDispatch` hardcodes `queued`,
|
|
35
|
+
* and the only unregister caller is `markCompleted`, whose terminal statuses
|
|
36
|
+
* DELETE the row. So every row reads `queued` — measured 20/20 rows of the
|
|
37
|
+
* active session — and a guard that read the row would reap a sub-agent that
|
|
38
|
+
* is heartbeating right now. `no-execution` is terminal for the heartbeat
|
|
39
|
+
* pollers, so that would stop a watcher waiting on live work.
|
|
40
|
+
*/
|
|
41
|
+
readStatus: (recordPath: string) => string | null;
|
|
42
|
+
/**
|
|
43
|
+
* Terminal transition for the on-disk record (`markCompleted` in
|
|
44
|
+
* `./dispatch-record-writer.ts`, injected to keep this module free of a
|
|
45
|
+
* cycle back into the writer). It is expected to unregister the row as a
|
|
46
|
+
* side effect, which is what removes it from the index.
|
|
47
|
+
*/
|
|
48
|
+
finalize: (recordPath: string) => void;
|
|
49
|
+
/** Test seam; defaults to the real clock. */
|
|
50
|
+
now?: () => Date;
|
|
51
|
+
/** Override {@link LEDGER_REAP_BOUND_MS}; the CLI never does. */
|
|
52
|
+
boundMs?: number;
|
|
53
|
+
}
|
|
54
|
+
/** What the reaper did, so the caller (and a test) can see it rather than infer it. */
|
|
55
|
+
export interface ReapStaleQueuedEntriesResult {
|
|
56
|
+
/**
|
|
57
|
+
* Rows removed from the index. A row is removed when its record was
|
|
58
|
+
* finalized, and also when the row named no usable record — a path outside
|
|
59
|
+
* `.peaks/_sub_agents/`, or one whose file is absent. Both leave the index
|
|
60
|
+
* smaller; only the first changes a record.
|
|
61
|
+
*/
|
|
62
|
+
readonly reaped: readonly string[];
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Finalize every index row whose RECORD is still `queued` past the bound, and
|
|
66
|
+
* drop it from the index. Called at the start of `writeInitialDispatchRecord`,
|
|
67
|
+
* i.e. at the next dispatch write — the exact moment the index would grow.
|
|
68
|
+
*
|
|
69
|
+
* A row is dropped without finalizing when it names no usable record: a path
|
|
70
|
+
* outside `.peaks/_sub_agents/`, or a file that is absent. A row pointing at no
|
|
71
|
+
* record is stale by definition.
|
|
72
|
+
*
|
|
73
|
+
* The row is only a hint. The RECORD decides: `running` / `finalizing` is a live
|
|
74
|
+
* dispatch and is left alone however old it is, and a record the writer already
|
|
75
|
+
* terminated is left to that writer. Only a record still `queued` — never
|
|
76
|
+
* started AND never finalized — is reaped. (This is the distinction that
|
|
77
|
+
* matters: `no-execution` is terminal for the heartbeat pollers, so reaping a
|
|
78
|
+
* live record would stop a watcher waiting on it.)
|
|
79
|
+
*/
|
|
80
|
+
export declare function reapStaleQueuedEntries(input: ReapStaleQueuedEntriesInput): ReapStaleQueuedEntriesResult;
|