peaks-loop 4.1.7 → 4.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +72 -0
  3. package/config/eslint/tsconfig.lint.json +1 -0
  4. package/dist/cli/commands/code-gate-step-08-command.js +21 -11
  5. package/dist/cli/commands/code-gate-step-08-remedy.d.ts +17 -0
  6. package/dist/cli/commands/code-gate-step-08-remedy.js +76 -0
  7. package/dist/cli/commands/code-job-shape-commands.js +21 -5
  8. package/dist/cli/commands/dispatch-from-dag.js +17 -0
  9. package/dist/cli/commands/job-commands.js +15 -5
  10. package/dist/cli/commands/job-init-status-commands.js +45 -5
  11. package/dist/cli/commands/lint-baseline-command.d.ts +15 -0
  12. package/dist/cli/commands/lint-baseline-command.js +64 -0
  13. package/dist/cli/commands/lint-commands.js +27 -51
  14. package/dist/cli/commands/request-command-options.d.ts +6 -0
  15. package/dist/cli/commands/request-commands.js +2 -0
  16. package/dist/cli/commands/request-mark-qa-initiated-command.d.ts +3 -0
  17. package/dist/cli/commands/request-mark-qa-initiated-command.js +80 -0
  18. package/dist/cli/commands/request-transition-failures.js +1 -0
  19. package/dist/cli/commands/reviewer-commands.d.ts +6 -6
  20. package/dist/cli/commands/reviewer-commands.js +154 -56
  21. package/dist/cli/commands/reviewer-config-commands.d.ts +9 -0
  22. package/dist/cli/commands/reviewer-config-commands.js +133 -0
  23. package/dist/services/artifacts/artifact-lint-service.js +102 -27
  24. package/dist/services/artifacts/artifact-prerequisites.d.ts +1 -0
  25. package/dist/services/artifacts/artifact-prerequisites.js +13 -13
  26. package/dist/services/artifacts/artifact-template-bodies.d.ts +7 -1
  27. package/dist/services/artifacts/artifact-template-bodies.js +14 -3
  28. package/dist/services/artifacts/artifact-templates.d.ts +6 -1
  29. package/dist/services/artifacts/artifact-templates.js +8 -5
  30. package/dist/services/artifacts/backcompat-acceptance.js +7 -5
  31. package/dist/services/artifacts/prerequisite-checks.d.ts +34 -9
  32. package/dist/services/artifacts/prerequisite-checks.js +28 -9
  33. package/dist/services/artifacts/qa-initiated-marker.d.ts +24 -0
  34. package/dist/services/artifacts/qa-initiated-marker.js +36 -0
  35. package/dist/services/artifacts/request-artifact-metadata.d.ts +9 -0
  36. package/dist/services/artifacts/request-artifact-metadata.js +9 -0
  37. package/dist/services/artifacts/request-artifact-service.js +6 -10
  38. package/dist/services/artifacts/request-artifact-state-helpers.d.ts +2 -1
  39. package/dist/services/artifacts/request-artifact-state-helpers.js +6 -3
  40. package/dist/services/code/job-shape-provisional.d.ts +51 -0
  41. package/dist/services/code/job-shape-provisional.js +80 -0
  42. package/dist/services/code/step-08-gate.d.ts +24 -12
  43. package/dist/services/code/step-08-gate.js +54 -97
  44. package/dist/services/code/step-08-session-readers.d.ts +27 -0
  45. package/dist/services/code/step-08-session-readers.js +105 -0
  46. package/dist/services/dispatch/isolation-lease.d.ts +3 -2
  47. package/dist/services/dispatch/isolation-lease.js +15 -6
  48. package/dist/services/job/subagent-job-wrapper.d.ts +20 -7
  49. package/dist/services/job/subagent-job-wrapper.js +53 -5
  50. package/dist/services/lint/eslint-report.d.ts +19 -0
  51. package/dist/services/lint/eslint-report.js +60 -0
  52. package/dist/services/lint/eslint-runner-support.d.ts +18 -1
  53. package/dist/services/lint/eslint-runner-support.js +35 -2
  54. package/dist/services/lint/eslint-runner-types.d.ts +21 -1
  55. package/dist/services/lint/eslint-runner.js +43 -33
  56. package/dist/services/prd/gate-evidence-derivation.d.ts +2 -4
  57. package/dist/services/prd/gate-evidence-derivation.js +3 -1
  58. package/dist/services/qa/bdd-test-style-contract.d.ts +17 -0
  59. package/dist/services/qa/bdd-test-style-contract.js +41 -0
  60. package/dist/services/qa/bdd-test-style-verifier.d.ts +9 -6
  61. package/dist/services/qa/bdd-test-style-verifier.js +24 -37
  62. package/dist/services/rd/reviewer-dispatch-policy.d.ts +18 -14
  63. package/dist/services/rd/reviewer-dispatch-policy.js +14 -11
  64. package/dist/services/release/release-state.js +20 -5
  65. package/dist/services/reviewer/model-family.js +1 -1
  66. package/dist/services/reviewer/reviewer-artifacts.d.ts +12 -0
  67. package/dist/services/reviewer/reviewer-artifacts.js +67 -0
  68. package/dist/services/reviewer/reviewer-config-write.d.ts +18 -0
  69. package/dist/services/reviewer/reviewer-config-write.js +71 -0
  70. package/dist/services/reviewer/reviewer-config.d.ts +33 -5
  71. package/dist/services/reviewer/reviewer-config.js +102 -46
  72. package/dist/services/reviewer/reviewer-envelopes.d.ts +8 -0
  73. package/dist/services/reviewer/reviewer-envelopes.js +53 -0
  74. package/dist/services/reviewer/reviewer-service.d.ts +7 -4
  75. package/dist/services/reviewer/reviewer-service.js +46 -52
  76. package/dist/services/reviewer/reviewer-types.d.ts +9 -1
  77. package/dist/services/session/getSessionDir.js +16 -7
  78. package/dist/services/web/daemon-registry.d.ts +6 -4
  79. package/dist/services/web/daemon-registry.js +92 -17
  80. package/package.json +5 -5
  81. package/schemas/reviewer-envelope.schema.json +1 -1
  82. package/skills/bee/peaks-reviewer/SKILL.md +20 -4
  83. package/skills/bee/peaks-reviewer/references/reviewer-schema.md +12 -7
  84. package/skills/bee/peaks-security-audit/SKILL.md +20 -0
  85. package/skills/peaks-code/references/step-0-8-gate.md +2 -1
@@ -14,7 +14,10 @@
14
14
  */
15
15
  import { existsSync, readFileSync } from 'node:fs';
16
16
  import { homedir } from 'node:os';
17
- import { join } from 'node:path';
17
+ import { dirname, isAbsolute, join, resolve } from 'node:path';
18
+ import { fileURLToPath } from 'node:url';
19
+ /** A4.1 — the reviewer needs at least two provider families to be usable. */
20
+ export const MIN_REVIEWER_PROVIDERS = 2;
18
21
  const VALID_SELECTION = ['round-robin', 'hash', 'random'];
19
22
  const VALID_FALLBACK = ['skip', 'error'];
20
23
  export function defaultReviewerConfigPath() {
@@ -23,37 +26,43 @@ export function defaultReviewerConfigPath() {
23
26
  function isRecord(value) {
24
27
  return typeof value === 'object' && value !== null && !Array.isArray(value);
25
28
  }
26
- /**
27
- * Read + parse `~/.peaks/config.json` (or override path) and return the
28
- * `reviewer` section if present. NEVER throws on missing file — returns
29
- * `{ ok: false, reason: 'no-reviewer-config' }` instead so the CLI can
30
- * record the skip reason in the envelope.
31
- */
32
- export function loadReviewerConfig(options = {}) {
33
- const path = options.path ?? defaultReviewerConfigPath();
34
- if (!existsSync(path)) {
35
- return { ok: false, reason: 'no-reviewer-config' };
36
- }
29
+ function absentStatus() {
30
+ return {
31
+ ok: false,
32
+ reason: 'no-reviewer-config',
33
+ providerCount: 0,
34
+ requiredProviders: MIN_REVIEWER_PROVIDERS
35
+ };
36
+ }
37
+ function insufficientStatus(providerCount) {
38
+ return {
39
+ ok: false,
40
+ reason: 'insufficient-providers',
41
+ providerCount,
42
+ requiredProviders: MIN_REVIEWER_PROVIDERS
43
+ };
44
+ }
45
+ /** The `reviewer` object, or `{ ok: false }` when the file / section is absent or unreadable. */
46
+ function readSection(path) {
47
+ if (!existsSync(path))
48
+ return { ok: false };
37
49
  let raw;
38
50
  try {
39
51
  raw = JSON.parse(readFileSync(path, 'utf8'));
40
52
  }
41
53
  catch {
42
- return { ok: false, reason: 'no-reviewer-config' };
54
+ return { ok: false };
43
55
  }
44
56
  if (!isRecord(raw))
45
- return { ok: false, reason: 'no-reviewer-config' };
57
+ return { ok: false };
46
58
  const reviewer = raw['reviewer'];
47
- if (!isRecord(reviewer))
48
- return { ok: false, reason: 'no-reviewer-config' };
49
- const providersRaw = reviewer['providers'];
50
- if (!Array.isArray(providersRaw) || providersRaw.length < 2) {
51
- // A4.1 explicitly requires >=2 providers; with <2 we treat the
52
- // section as absent so the reviewer is skipped cleanly.
53
- return { ok: false, reason: 'no-reviewer-config' };
54
- }
59
+ return isRecord(reviewer) ? { ok: true, reviewer } : { ok: false };
60
+ }
61
+ function parseProviders(raw) {
62
+ if (!Array.isArray(raw))
63
+ return { providers: [], total: 0 };
55
64
  const providers = [];
56
- for (const entry of providersRaw) {
65
+ for (const entry of raw) {
57
66
  if (!isRecord(entry))
58
67
  continue;
59
68
  const name = entry['name'];
@@ -67,35 +76,82 @@ export function loadReviewerConfig(options = {}) {
67
76
  apiKeyEnv: typeof entry['apiKeyEnv'] === 'string' ? entry['apiKeyEnv'] : undefined
68
77
  });
69
78
  }
70
- if (providers.length < 2)
71
- return { ok: false, reason: 'no-reviewer-config' };
72
- const selectionRaw = reviewer['selection'];
73
- const selection = typeof selectionRaw === 'string' &&
74
- VALID_SELECTION.includes(selectionRaw)
75
- ? selectionRaw
79
+ return { providers, total: raw.length };
80
+ }
81
+ function readSelection(raw) {
82
+ return typeof raw === 'string' && VALID_SELECTION.includes(raw)
83
+ ? raw
76
84
  : 'round-robin';
77
- const fallbackRaw = reviewer['fallbackOnError'];
78
- const fallbackOnError = typeof fallbackRaw === 'string' &&
79
- VALID_FALLBACK.includes(fallbackRaw)
80
- ? fallbackRaw
85
+ }
86
+ function readFallback(raw) {
87
+ return typeof raw === 'string' && VALID_FALLBACK.includes(raw)
88
+ ? raw
81
89
  : 'skip';
82
- const rdProviderNameRaw = reviewer['rdProviderName'];
83
- const rdProviderName = rdProviderNameRaw === null || typeof rdProviderNameRaw === 'string' ? rdProviderNameRaw : null;
84
- const requireDistinct = reviewer['requireDistinctModelFamily'];
85
- const requireDistinctModelFamily = typeof requireDistinct === 'boolean' ? requireDistinct : true;
86
- const schemaPathRaw = reviewer['schemaPath'];
87
- const schemaPath = typeof schemaPathRaw === 'string' && schemaPathRaw.length > 0
88
- ? schemaPathRaw
89
- : 'schemas/reviewer-envelope.schema.json';
90
+ }
91
+ function readRdProviderName(raw) {
92
+ return raw === null || typeof raw === 'string' ? raw : null;
93
+ }
94
+ function readRequireDistinct(raw) {
95
+ return typeof raw === 'boolean' ? raw : true;
96
+ }
97
+ function readSchemaPath(raw) {
98
+ return typeof raw === 'string' && raw.length > 0 ? raw : 'schemas/reviewer-envelope.schema.json';
99
+ }
100
+ /** `<packageRoot>` — this file's tree is `<root>/src/services/reviewer` or `<root>/dist/services/reviewer`. */
101
+ const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
102
+ /**
103
+ * Resolve the configured ReviewerEnvelope schema: an absolute path as-is,
104
+ * else the project-root copy (a project may override), else the copy bundled
105
+ * with the peaks-loop package — a consumer project does NOT ship `schemas/`,
106
+ * so the packaged copy is what makes the default path work there. When
107
+ * nothing resolves, every candidate is returned for the refusal message.
108
+ */
109
+ export function resolveReviewerSchema(projectRoot, schemaPath) {
110
+ if (isAbsolute(schemaPath)) {
111
+ return existsSync(schemaPath)
112
+ ? { ok: true, path: schemaPath, source: 'absolute' }
113
+ : { ok: false, searched: [schemaPath] };
114
+ }
115
+ const projectCandidate = resolve(projectRoot, schemaPath);
116
+ if (existsSync(projectCandidate)) {
117
+ return { ok: true, path: projectCandidate, source: 'project' };
118
+ }
119
+ const packageCandidate = resolve(PACKAGE_ROOT, schemaPath);
120
+ if (existsSync(packageCandidate)) {
121
+ return { ok: true, path: packageCandidate, source: 'package' };
122
+ }
123
+ // Dogfooding the repo itself makes both candidates the same path; name it once.
124
+ const searched = projectCandidate === packageCandidate
125
+ ? [projectCandidate]
126
+ : [projectCandidate, packageCandidate];
127
+ return { ok: false, searched };
128
+ }
129
+ /**
130
+ * Read + parse `~/.peaks/config.json` (or override path) and return the
131
+ * `reviewer` section if present. NEVER throws on missing file — the CLI
132
+ * records the skip reason in the envelope instead.
133
+ */
134
+ export function loadReviewerConfig(options = {}) {
135
+ const path = options.path ?? defaultReviewerConfigPath();
136
+ const section = readSection(path);
137
+ if (!section.ok)
138
+ return absentStatus();
139
+ const reviewer = section.reviewer;
140
+ const { providers, total } = parseProviders(reviewer['providers']);
141
+ if (total < MIN_REVIEWER_PROVIDERS || providers.length < MIN_REVIEWER_PROVIDERS) {
142
+ // A4.1 requires >=2 valid providers. The section exists but is not
143
+ // usable; report the count rather than collapsing it into "no section".
144
+ return insufficientStatus(total < MIN_REVIEWER_PROVIDERS ? total : providers.length);
145
+ }
90
146
  return {
91
147
  ok: true,
92
148
  config: {
93
149
  providers,
94
- selection,
95
- rdProviderName,
96
- requireDistinctModelFamily,
97
- fallbackOnError,
98
- schemaPath
150
+ selection: readSelection(reviewer['selection']),
151
+ rdProviderName: readRdProviderName(reviewer['rdProviderName']),
152
+ requireDistinctModelFamily: readRequireDistinct(reviewer['requireDistinctModelFamily']),
153
+ fallbackOnError: readFallback(reviewer['fallbackOnError']),
154
+ schemaPath: readSchemaPath(reviewer['schemaPath'])
99
155
  }
100
156
  };
101
157
  }
@@ -0,0 +1,8 @@
1
+ import type { ReviewerProviderConfig } from './reviewer-config.js';
2
+ import type { ReviewerEnvelope } from './reviewer-types.js';
3
+ export declare const REVIEWER_ID = "third-party-reviewer-v2.14.0";
4
+ export declare function buildSkippedEnvelope(reason: string): ReviewerEnvelope;
5
+ export declare function buildProviderErrorEnvelope(provider: ReviewerProviderConfig, error: string): ReviewerEnvelope;
6
+ export declare function buildInvalidReplyEnvelope(provider: ReviewerProviderConfig): ReviewerEnvelope;
7
+ /** Stamp the family from the model we actually called — the LLM cannot choose it. */
8
+ export declare function stampEnvelope(validated: ReviewerEnvelope, provider: ReviewerProviderConfig): ReviewerEnvelope;
@@ -0,0 +1,53 @@
1
+ /**
2
+ * reviewer-envelopes.ts — pure builders for the ReviewerEnvelope.
3
+ *
4
+ * A skip is not a pass: every builder for a review that produced no verdict
5
+ * returns `passed: false` + `gateAction: 'warn'`, so a consumer reading only
6
+ * those two fields cannot see green (backlog §7.10 ②). `passed: true` is
7
+ * reachable only through `stampEnvelope`, which takes an already-validated
8
+ * model reply.
9
+ */
10
+ import { deriveModelFamily } from './model-family.js';
11
+ export const REVIEWER_ID = 'third-party-reviewer-v2.14.0';
12
+ export function buildSkippedEnvelope(reason) {
13
+ return {
14
+ reviewerId: REVIEWER_ID,
15
+ modelId: 'skipped',
16
+ modelFamily: 'skipped',
17
+ passed: false,
18
+ violations: [],
19
+ gateAction: 'warn',
20
+ reason
21
+ };
22
+ }
23
+ export function buildProviderErrorEnvelope(provider, error) {
24
+ return {
25
+ reviewerId: REVIEWER_ID,
26
+ modelId: provider.model,
27
+ modelFamily: deriveModelFamily(provider.model).modelFamily,
28
+ passed: false,
29
+ violations: [],
30
+ gateAction: 'warn',
31
+ reason: `skipped: provider ${provider.name} error (${error}); fallbackOnError=skip`
32
+ };
33
+ }
34
+ export function buildInvalidReplyEnvelope(provider) {
35
+ return {
36
+ reviewerId: REVIEWER_ID,
37
+ modelId: provider.model,
38
+ modelFamily: deriveModelFamily(provider.model).modelFamily,
39
+ passed: false,
40
+ violations: [],
41
+ gateAction: 'warn',
42
+ reason: `provider ${provider.name} returned non-conforming JSON; treated as warn`
43
+ };
44
+ }
45
+ /** Stamp the family from the model we actually called — the LLM cannot choose it. */
46
+ export function stampEnvelope(validated, provider) {
47
+ return {
48
+ ...validated,
49
+ modelId: provider.model,
50
+ modelFamily: deriveModelFamily(provider.model).modelFamily,
51
+ reviewerId: REVIEWER_ID
52
+ };
53
+ }
@@ -1,6 +1,6 @@
1
1
  import { type ReviewerEnvelope, type ReviewerRunInput, type ReviewerRunOutput } from './reviewer-types.js';
2
2
  export type { ReviewerViolation, ReviewerEnvelope, ReviewerRunInput, ReviewerRunOutput } from './reviewer-types.js';
3
- export declare const REVIEWER_ID = "third-party-reviewer-v2.14.0";
3
+ export { REVIEWER_ID, buildSkippedEnvelope } from './reviewer-envelopes.js';
4
4
  /**
5
5
  * Validate a parsed JSON value against the ReviewerEnvelope contract
6
6
  * (mirrors `schemas/reviewer-envelope.schema.json`). Returns the
@@ -12,10 +12,13 @@ export declare function validateReviewerEnvelope(value: unknown): ReviewerEnvelo
12
12
  * Many LLMs wrap JSON in ```json fences or surrounding prose; we
13
13
  * tolerate both. Returns null when no JSON object is present.
14
14
  */
15
- export declare function extractFirstJsonObject(text: string): unknown | null;
15
+ export declare function extractFirstJsonObject(text: string): unknown;
16
16
  export declare function runReviewer(input: ReviewerRunInput): Promise<ReviewerRunOutput>;
17
17
  /**
18
- * Compute the distinctness verdict: returns true when the third-party
19
- * mandates this is a CI gate — equality fails the build.
18
+ * The `requireDistinctModelFamily` verdict, over three inputs per side: a
19
+ * real family, an empty family, or a SKIP. Either side may be missing a
20
+ * family, and "not comparable" must NOT be reported as "distinct" — that
21
+ * would let a skip satisfy a distinctness gate. Returns true only when both
22
+ * families are present and differ.
20
23
  */
21
24
  export declare function distinctFromKarpathy(thirdPartyFamily: string, karpathyFamily: string): boolean;
@@ -16,13 +16,13 @@
16
16
  * do NOT pipe through the karpathy-reviewer path (out-of-scope per NG4).
17
17
  */
18
18
  import { createHash } from 'node:crypto';
19
- import { deriveModelFamily } from './model-family.js';
20
19
  import { selectByMode, initialState } from './selection-strategies.js';
21
20
  import { callOllama } from './providers/ollama.js';
22
21
  import { callAnthropic } from './providers/anthropic.js';
23
22
  import { callOpenAI } from './providers/openai.js';
24
- import { loadReviewerConfig } from './reviewer-config.js';
25
- export const REVIEWER_ID = 'third-party-reviewer-v2.14.0';
23
+ import { loadReviewerConfig, resolveReviewerSchema } from './reviewer-config.js';
24
+ import { buildInvalidReplyEnvelope, buildProviderErrorEnvelope, buildSkippedEnvelope, stampEnvelope } from './reviewer-envelopes.js';
25
+ export { REVIEWER_ID, buildSkippedEnvelope } from './reviewer-envelopes.js';
26
26
  const VIOLATION_KINDS = [
27
27
  'karpathy-violation',
28
28
  'code-smell',
@@ -177,33 +177,39 @@ function dispatchProvider(name, input) {
177
177
  latencyMs: 0
178
178
  });
179
179
  }
180
- function skippedEnvelope(reason) {
180
+ function skipReason(status) {
181
+ return status.reason === 'insufficient-providers'
182
+ ? `skipped: insufficient-providers (${status.providerCount} valid, >=${status.requiredProviders} required; fallbackOnError=skip)`
183
+ : 'skipped: no-reviewer-config (fallbackOnError=skip)';
184
+ }
185
+ /**
186
+ * The refusal for an unresolvable schema. Presence/configuration check only:
187
+ * the hand-rolled validator mirrors the schema, so this proves the deployment
188
+ * ships the file it mirrors. The content of the resolved file is NOT read here
189
+ * and does not drive validation — that stays `validateReviewerEnvelope`'s job.
190
+ */
191
+ function schemaMissingOutput(searched) {
181
192
  return {
182
- reviewerId: REVIEWER_ID,
183
- modelId: 'skipped',
184
- modelFamily: 'skipped',
185
- passed: true,
186
- violations: [],
187
- gateAction: 'allow',
188
- reason
193
+ ok: false,
194
+ reason: 'schema-missing',
195
+ schemaCandidates: searched,
196
+ envelope: buildSkippedEnvelope(`refused: schema-missing (searched ${searched.join(', ')})`)
189
197
  };
190
198
  }
191
199
  export async function runReviewer(input) {
192
- const status = loadReviewerConfig();
200
+ const status = loadReviewerConfig(input.configPath !== undefined ? { path: input.configPath } : {});
193
201
  if (!status.ok) {
194
- return {
195
- ok: false,
196
- reason: 'no-reviewer-config',
197
- envelope: skippedEnvelope('skipped: no-reviewer-config (fallbackOnError=skip)')
198
- };
202
+ return { ok: false, reason: status.reason, envelope: buildSkippedEnvelope(skipReason(status)) };
199
203
  }
200
204
  const config = status.config;
201
- const state = input.state ?? initialState();
202
- const { result, nextState } = selectByMode(config.selection, config.providers, input.rid, state, input.rng);
203
- const prompt = buildPrompt(input);
205
+ const projectRoot = input.projectRoot ?? process.cwd();
206
+ const schema = resolveReviewerSchema(projectRoot, config.schemaPath);
207
+ if (!schema.ok)
208
+ return schemaMissingOutput(schema.searched);
209
+ const { result, nextState } = selectByMode(config.selection, config.providers, input.rid, input.state ?? initialState(), input.rng);
204
210
  const callResult = await dispatchProvider(result.provider.name, {
205
211
  provider: result.provider,
206
- prompt,
212
+ prompt: buildPrompt(input),
207
213
  ...(input.fetchImpl !== undefined ? { fetchImpl: input.fetchImpl } : {})
208
214
  });
209
215
  if (!callResult.ok) {
@@ -212,50 +218,38 @@ export async function runReviewer(input) {
212
218
  }
213
219
  return {
214
220
  ok: true,
215
- envelope: {
216
- reviewerId: REVIEWER_ID,
217
- modelId: result.provider.model,
218
- modelFamily: deriveModelFamily(result.provider.model).modelFamily,
219
- passed: true,
220
- violations: [],
221
- gateAction: 'warn',
222
- reason: `skipped: provider ${result.provider.name} error (${callResult.error}); fallbackOnError=skip`
223
- },
221
+ skipped: true,
222
+ envelope: buildProviderErrorEnvelope(result.provider, callResult.error),
224
223
  nextState
225
224
  };
226
225
  }
227
- const parsed = extractFirstJsonObject(callResult.text);
228
- const validated = validateReviewerEnvelope(parsed);
226
+ const validated = validateReviewerEnvelope(extractFirstJsonObject(callResult.text));
229
227
  if (validated === null) {
230
228
  return {
231
229
  ok: true,
232
- envelope: {
233
- reviewerId: REVIEWER_ID,
234
- modelId: result.provider.model,
235
- modelFamily: deriveModelFamily(result.provider.model).modelFamily,
236
- passed: true,
237
- violations: [],
238
- gateAction: 'warn',
239
- reason: `provider ${result.provider.name} returned non-conforming JSON; treated as warn`
240
- },
230
+ skipped: true,
231
+ envelope: buildInvalidReplyEnvelope(result.provider),
241
232
  nextState
242
233
  };
243
234
  }
244
- // Stamp modelFamily from the actual modelId we called — prevents the LLM
245
- const stamped = {
246
- ...validated,
247
- modelId: result.provider.model,
248
- modelFamily: deriveModelFamily(result.provider.model).modelFamily,
249
- reviewerId: REVIEWER_ID
235
+ return {
236
+ ok: true,
237
+ skipped: false,
238
+ envelope: stampEnvelope(validated, result.provider),
239
+ nextState
250
240
  };
251
- return { ok: true, envelope: stamped, nextState };
252
241
  }
253
242
  /**
254
- * Compute the distinctness verdict: returns true when the third-party
255
- * mandates this is a CI gate — equality fails the build.
243
+ * The `requireDistinctModelFamily` verdict, over three inputs per side: a
244
+ * real family, an empty family, or a SKIP. Either side may be missing a
245
+ * family, and "not comparable" must NOT be reported as "distinct" — that
246
+ * would let a skip satisfy a distinctness gate. Returns true only when both
247
+ * families are present and differ.
256
248
  */
257
249
  export function distinctFromKarpathy(thirdPartyFamily, karpathyFamily) {
258
- if (thirdPartyFamily === 'skipped')
259
- return true;
250
+ if (thirdPartyFamily === 'skipped' || thirdPartyFamily === '')
251
+ return false;
252
+ if (karpathyFamily === 'skipped' || karpathyFamily === '')
253
+ return false;
260
254
  return thirdPartyFamily !== karpathyFamily;
261
255
  }
@@ -25,6 +25,10 @@ export type ReviewerRunInput = {
25
25
  rid: string;
26
26
  /** Slice context blob fed to the prompt. Plain text — no PII (A1.5). */
27
27
  context: string;
28
+ /** Optional override of the reviewer section path (`~/.peaks/config.json`). */
29
+ configPath?: string;
30
+ /** Project root the configured `schemaPath` resolves against (default `cwd`). */
31
+ projectRoot?: string;
28
32
  /** Optional override of the selection-mode state for cross-slice round-robin. */
29
33
  state?: SelectionState;
30
34
  /** Optional injected fetch (testability). */
@@ -36,8 +40,12 @@ export type ReviewerRunOutput = {
36
40
  ok: true;
37
41
  envelope: ReviewerEnvelope;
38
42
  nextState: SelectionState;
43
+ /** True when no review verdict was produced (skip, provider error, bad JSON). */
44
+ skipped: boolean;
39
45
  } | {
40
46
  ok: false;
41
- reason: 'no-reviewer-config';
47
+ reason: 'no-reviewer-config' | 'insufficient-providers' | 'schema-missing';
42
48
  envelope: ReviewerEnvelope;
49
+ /** The paths searched, set when `reason === 'schema-missing'`. */
50
+ schemaCandidates?: string[];
43
51
  };
@@ -26,11 +26,11 @@
26
26
  * re-derived at each call site: `../../x` used to be joined verbatim, and
27
27
  * the CLI wrote outside the project root while still returning `ok: true`.
28
28
  *
29
- * The predicate is `isUnsafePathInput`, NOT `SESSION_ID_PATTERN` /
30
- * `validateSessionId`. The latter are stricter than the segment axis and
31
- * reject ids that are legal today (`sid-1`, a request id reused as the
32
- * session-dir name), so adopting them would change results for
33
- * well-formed callers.
29
+ * The predicate is `isUnsafePathInput` plus a separator check, NOT
30
+ * `SESSION_ID_PATTERN` / `validateSessionId`. The latter are stricter than
31
+ * the segment axis and reject ids that are legal today (`sid-1`, a request
32
+ * id reused as the session-dir name), so adopting them would change results
33
+ * for well-formed callers.
34
34
  *
35
35
  * Not covered, recorded rather than implied: the `\0` axis
36
36
  * (`isUnsafePathInput` admits a NUL, and `execFileSync` raises EINVAL
@@ -44,12 +44,21 @@
44
44
  */
45
45
  import { join } from 'node:path';
46
46
  import { isUnsafePathInput } from '../../shared/path-safety.js';
47
+ /**
48
+ * The documented contract: one path segment. `isUnsafePathInput` is a
49
+ * traversal guard only and ADMITS `a/b`, so the separator axes are
50
+ * checked here as well. The session dir is ONE directory name under
51
+ * `_runtime/`.
52
+ */
53
+ function isSinglePathSegment(sessionId) {
54
+ return !isUnsafePathInput(sessionId) && !sessionId.includes('/') && !sessionId.includes('\\');
55
+ }
47
56
  export function getSessionDir(projectRoot, sessionId) {
48
57
  // Throwing, not `null` / a tagged result: those widen the return type
49
58
  // to `string | null` and make every call site handle a bad id — the
50
59
  // per-site slice this guard replaces. This is also the shape the repo
51
60
  // already refuses with, and a caller cannot forget to handle a throw.
52
- if (isUnsafePathInput(sessionId)) {
61
+ if (!isSinglePathSegment(sessionId)) {
53
62
  throw new Error(`Invalid session id: ${sessionId} (must be a single path segment)`);
54
63
  }
55
64
  return join(projectRoot, '.peaks', '_runtime', sessionId);
@@ -84,7 +93,7 @@ export function tryGetSessionDir(projectRoot, sessionId) {
84
93
  // Deliberately NOT `try { return {ok:true, dir: getSessionDir(...)} } catch`.
85
94
  // That would re-introduce the swallow this function exists to remove, and it
86
95
  // would also catch a throw from `join` for reasons that are not a bad id.
87
- if (isUnsafePathInput(sessionId)) {
96
+ if (!isSinglePathSegment(sessionId)) {
88
97
  return {
89
98
  ok: false,
90
99
  reason: `Invalid session id: ${sessionId} (must be a single path segment)`
@@ -26,12 +26,14 @@ export declare function removeDaemonInfo(projectRoot: string, sessionId: string)
26
26
  */
27
27
  export declare function isProcessAlive(pid: number): boolean;
28
28
  /**
29
- * Take the cold-start lock (O_EXCL create). Returns `false` when another
30
- * process holds a live lock, and reclaims a STALE one — owner pid dead, or
31
- * older than `SPAWN_LOCK_STALE_MS` — before retrying once (tech-doc §1.4).
29
+ * Take the cold-start lock. Returns `false` when another process holds a live
30
+ * lock; reclaims a STALE one by renaming it to a per-call quarantine. Unlink-
31
+ * then-create is not atomic (two callers could both return true), so the
32
+ * replacement is created and identity-verified, and a moved fresh lock is
33
+ * restored rather than replaced.
32
34
  */
33
35
  export declare function acquireSpawnLock(projectRoot: string, sessionId: string): boolean;
34
- /** Release the spawn lock, but only when this process is its owner. */
36
+ /** Release the spawn lock, but only when this process provably owns it. */
35
37
  export declare function releaseSpawnLock(projectRoot: string, sessionId: string): void;
36
38
  /**
37
39
  * The daemon instances for a session. There is one daemon per