@jagreehal/shepherd 0.3.0 → 0.5.0

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 (55) hide show
  1. package/AGENTS.md +5 -0
  2. package/README.md +41 -419
  3. package/THIRD_PARTY_NOTICES.md +11 -0
  4. package/lenses/dotnet/SKILL.md +32 -0
  5. package/lenses/go/SKILL.md +30 -0
  6. package/lenses/java/SKILL.md +31 -0
  7. package/lenses/nextjs/SKILL.md +33 -0
  8. package/lenses/node-api/SKILL.md +32 -0
  9. package/lenses/nx-monorepo/SKILL.md +30 -0
  10. package/lenses/observability/SKILL.md +18 -11
  11. package/lenses/owasp-asvs/SKILL.md +50 -0
  12. package/lenses/owasp-llm/SKILL.md +44 -0
  13. package/lenses/python/SKILL.md +32 -0
  14. package/lenses/react/SKILL.md +33 -0
  15. package/lenses/rust/SKILL.md +31 -0
  16. package/package.json +17 -8
  17. package/packs/dotnet.yml +6 -0
  18. package/packs/go.yml +6 -0
  19. package/packs/java.yml +6 -0
  20. package/packs/nextjs.yml +7 -0
  21. package/packs/node-api.yml +7 -0
  22. package/packs/nx-monorepo.yml +6 -0
  23. package/packs/observability.yml +6 -0
  24. package/packs/owasp-asvs.yml +6 -0
  25. package/packs/owasp-llm.yml +8 -0
  26. package/packs/python.yml +6 -0
  27. package/packs/react.yml +6 -0
  28. package/packs/rust.yml +6 -0
  29. package/skills/ci-repair/SKILL.md +6 -1
  30. package/skills/garden/SKILL.md +28 -3
  31. package/skills/garden/references/telemetry.md +50 -0
  32. package/skills/incident/SKILL.md +6 -1
  33. package/skills/lens-import/SKILL.md +185 -0
  34. package/skills/lens-import/references/conversion.md +96 -0
  35. package/skills/lens-import/scripts/check-import.mjs +154 -0
  36. package/skills/shepherd/SKILL.md +121 -6
  37. package/skills/shepherd/references/dispatch.md +12 -0
  38. package/skills/shepherd/references/models.md +20 -7
  39. package/skills/shepherd/references/policy.md +9 -5
  40. package/skills/shepherd/references/stories.md +102 -0
  41. package/skills/swarm/SKILL.md +16 -1
  42. package/skills/swarm/references/custom-lenses.md +50 -7
  43. package/skills/triage/SKILL.md +19 -0
  44. package/src/cli.ts +210 -16
  45. package/src/config.ts +137 -21
  46. package/src/garden-traces.ts +461 -0
  47. package/src/garden.ts +2 -1
  48. package/src/install.ts +3 -0
  49. package/src/lens.ts +159 -8
  50. package/src/notify.ts +138 -0
  51. package/src/stack.ts +121 -0
  52. package/src/trace.ts +180 -0
  53. package/templates/shepherd-audit.yml +178 -0
  54. package/templates/shepherd-incident.yml +180 -0
  55. package/templates/shepherd.yml +427 -0
@@ -0,0 +1,461 @@
1
+ // Optional measurements for garden. Only known span names and numeric measurements leave this module;
2
+ // prompts, tool arguments, logs and arbitrary span attributes never become gardener instructions.
3
+ import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
4
+ import { z } from "zod";
5
+ import type { PrRecord } from "./garden.ts";
6
+ import { STAGES } from "./trace.ts";
7
+
8
+ const MAX_BYTES = 10_000_000;
9
+
10
+ const MAX_TRACES = 100;
11
+
12
+ const MAX_SPANS = 50_000;
13
+
14
+ const MAX_MEASUREMENTS = 50_000_000;
15
+
16
+ const KEYS = new Set(["vcs.repository.name", "vcs.change.id", "vcs.ref.head.revision", "shepherd.retries", "shepherd.stage", "shepherd.outcome", "stamp.cost_usd", "stamp.cost_complete"]);
17
+
18
+ const Id = z.string().transform((s) => /^[0-9a-f]{1,32}$/.test(s) ? s.padStart(32, "0") : /^[A-Za-z0-9+/]{22}==$/.test(s) ? Buffer.from(s, "base64").toString("hex") : s)
19
+ .pipe(z.string().regex(/^[0-9a-f]{32}$/).refine((s) => /[1-9a-f]/.test(s)));
20
+
21
+ const SpanId = z.string().transform((s) => /^[A-Za-z0-9+/]{11}=$/.test(s) ? Buffer.from(s, "base64").toString("hex") : s).pipe(z.string().regex(/^[0-9a-f]{16}$/));
22
+
23
+ const Integer = z.union([z.string().regex(/^\d{1,20}$/), z.number().int().nonnegative().safe()]);
24
+
25
+ const Attribute = z.object({ key: z.string(), value: z.object({ stringValue: z.string().optional(), intValue: Integer.optional(), doubleValue: z.number().finite().optional(), boolValue: z.boolean().optional() }) });
26
+
27
+ const Span = z.object({
28
+ name: z.string(), traceId: Id, spanId: SpanId, parentSpanId: z.union([SpanId, z.literal("")]).optional().transform((s) => s || undefined),
29
+ startTimeUnixNano: Integer, endTimeUnixNano: Integer,
30
+ attributes: z.array(Attribute).default([]),
31
+ status: z.object({ code: z.union([z.number(), z.string()]).optional() }).optional(),
32
+ }).transform((s) => ({ ...s, attributes: s.attributes.filter((a) => KEYS.has(a.key)) }));
33
+
34
+ const Resource = z.object({ scopeSpans: z.array(z.object({ spans: z.array(Span) })).default([]) });
35
+
36
+ // Tempo calls resourceSpans `batches`; collector file exports use resourceSpans, one JSON object per line.
37
+ const Envelope = z.object({ resourceSpans: z.array(Resource).optional(), batches: z.array(Resource).optional() })
38
+ .refine((e) => e.resourceSpans !== undefined || e.batches !== undefined);
39
+
40
+ type Span = z.infer<typeof Span>;
41
+
42
+ export type TraceInput = { spans: Span[]; sources: number; unavailable: number; limited: boolean; bytes?: number };
43
+
44
+ export const traceLimits = { retries: 3, waitMs: 300_000, costUsd: 5 };
45
+
46
+ export type TraceLimits = typeof traceLimits;
47
+
48
+ export function traceHeaders(raw: string): Record<string, string> {
49
+ try {
50
+ return z.record(z.string(), z.string()).parse(JSON.parse(raw));
51
+ } catch {
52
+ throw new Error("GARDEN_TEMPO_HEADERS must be a JSON object of header strings");
53
+ }
54
+ }
55
+
56
+ /**
57
+ * The credential headers for one Tempo endpoint. GARDEN_TEMPO_HEADERS belongs to GARDEN_TEMPO_URL, so an
58
+ * endpoint on any other origin, such as a `--tempo-url` pointing elsewhere, gets no headers.
59
+ */
60
+ export function tempoHeaders(endpoint: string | undefined, configured: string | undefined, raw: string | undefined): Record<string, string> {
61
+ if (!endpoint || !configured || !raw) return {};
62
+
63
+ const origin = (u: string) => {
64
+ try {
65
+ return new URL(u).origin;
66
+ } catch {
67
+ return null;
68
+ }
69
+ };
70
+
71
+ return origin(endpoint) !== null && origin(endpoint) === origin(configured) ? traceHeaders(raw) : {};
72
+ }
73
+
74
+ export type TraceSignal = "trace_stage_failed" | "trace_retries" | "trace_approval_wait" | "trace_review_cost";
75
+
76
+ /** Decode OTLP JSON or a collector's JSON-lines file. A malformed source contributes no measurements. */
77
+ export function parseTraces(text: string): Span[] {
78
+ let envelopes: z.infer<typeof Envelope>[];
79
+
80
+ try {
81
+ envelopes = [Envelope.parse(JSON.parse(text))];
82
+ } catch {
83
+ envelopes = text.split("\n").filter((s) => s.trim()).map((s) => Envelope.parse(JSON.parse(s)));
84
+ }
85
+
86
+ return envelopes.flatMap((e) => (e.resourceSpans ?? e.batches ?? []).flatMap((r) => r.scopeSpans.flatMap((s) => s.spans)));
87
+ }
88
+
89
+ /** Open without following symlinks and bound the same descriptor that gets read. */
90
+ export function readTraceFile(file: string): Span[] {
91
+ const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
92
+
93
+ try {
94
+ const stat = fstatSync(fd);
95
+
96
+ if (!stat.isFile() || stat.size > MAX_BYTES) throw new Error("trace input must be a regular file of at most 10 MB");
97
+
98
+ const bytes = Buffer.alloc(MAX_BYTES + 1);
99
+ let length = 0;
100
+
101
+ while (length <= MAX_BYTES) {
102
+ const read = readSync(fd, bytes, length, bytes.length - length, null);
103
+
104
+ if (!read) break;
105
+ length += read;
106
+ }
107
+
108
+ if (length > MAX_BYTES) throw new Error("trace input exceeds 10 MB");
109
+
110
+ return parseTraces(bytes.subarray(0, length).toString("utf8"));
111
+ } finally {
112
+ closeSync(fd);
113
+ }
114
+ }
115
+
116
+ /** Read a response under a byte cap, keeping the timeout active until its body has finished. */
117
+ async function readResponse(response: Response): Promise<string> {
118
+ if (!response.ok || !response.body) throw new Error("trace backend request failed");
119
+
120
+ const reader = response.body.getReader();
121
+ const chunks: Uint8Array[] = [];
122
+ let bytes = 0;
123
+
124
+ try {
125
+ for (;;) {
126
+ const next = await reader.read();
127
+
128
+ if (next.done) break;
129
+ bytes += next.value.byteLength;
130
+
131
+ if (bytes > MAX_BYTES) throw new Error("trace response exceeds 10 MB");
132
+ chunks.push(next.value);
133
+ }
134
+ } finally {
135
+ await reader.cancel();
136
+ }
137
+
138
+ return Buffer.concat(chunks).toString("utf8");
139
+ }
140
+
141
+ const Search = z.object({ traces: z.array(z.object({ traceID: Id })).default([]) });
142
+
143
+ const appendSpans = (input: TraceInput, spans: Span[]) => {
144
+ const bytes = Buffer.byteLength(JSON.stringify(spans));
145
+
146
+ if ((input.bytes ?? 0) + bytes > MAX_MEASUREMENTS) {
147
+ input.limited = true;
148
+
149
+ return;
150
+ }
151
+
152
+ const available = MAX_SPANS - input.spans.length;
153
+ input.spans.push(...spans.slice(0, available));
154
+ input.bytes = (input.bytes ?? 0) + bytes;
155
+ input.limited ||= spans.length > available;
156
+ };
157
+
158
+ /** Tempo's read-only search and trace-by-id APIs. No URL from a span or search result is ever followed. */
159
+ export async function readTempo(endpoint: string, headers: Record<string, string>, repo: string, since: string, now = Date.now()): Promise<TraceInput> {
160
+ const base = new URL(endpoint.endsWith("/") ? endpoint : endpoint + "/");
161
+
162
+ if (!["http:", "https:"].includes(base.protocol) || base.username || base.password || base.search || base.hash) throw new Error("invalid Tempo endpoint");
163
+
164
+ const signal = AbortSignal.timeout(30_000);
165
+ const get = async (url: URL) => readResponse(await fetch(url, { headers: { ...headers, Accept: "application/json" }, redirect: "error", signal }));
166
+ const search = new URL("api/search", base);
167
+ search.searchParams.set("q", `{ (name = "shepherd.iteration" || name = "stamp.review") && span.vcs.repository.name = ${JSON.stringify(repo)} }`);
168
+ search.searchParams.set("start", String(Math.floor(Date.parse(since) / 1000)));
169
+ search.searchParams.set("end", String(Math.floor(now / 1000)));
170
+ search.searchParams.set("limit", String(MAX_TRACES));
171
+
172
+ const found = Search.parse(JSON.parse(await get(search))).traces;
173
+ const input: TraceInput = { spans: [], sources: 1, unavailable: 0, limited: found.length >= MAX_TRACES };
174
+
175
+ for (const id of new Set(found.map((t) => t.traceID))) {
176
+ try {
177
+ appendSpans(input, parseTraces(await get(new URL(`api/traces/${id}`, base))));
178
+ } catch {
179
+ input.unavailable++;
180
+ }
181
+ }
182
+
183
+ return input;
184
+ }
185
+
186
+ // Datadog keeps OTLP attributes nested under `custom` and span IDs in decimal; the trace ID stays 128-bit hex.
187
+ // Each field falls back to absent, so one odd attribute drops that measurement, not the span.
188
+ const str = z.string().optional().catch(undefined);
189
+
190
+ const num = z.number().optional().catch(undefined);
191
+
192
+ const DatadogCustom = z.object({
193
+ vcs: z.object({
194
+ repository: z.object({ name: str }).optional().catch(undefined),
195
+ change: z.object({ id: str }).optional().catch(undefined),
196
+ ref: z.object({ head: z.object({ revision: str }).optional().catch(undefined) }).optional().catch(undefined),
197
+ }).optional().catch(undefined),
198
+ shepherd: z.object({ retries: num, stage: str, outcome: str }).optional().catch(undefined),
199
+ // Datadog stores a boolean attribute as the string "true" or "false".
200
+ stamp: z.object({ cost_usd: num, cost_complete: z.enum(["true", "false"]).optional().catch(undefined) }).optional().catch(undefined),
201
+ otel: z.object({ status_code: str }).optional().catch(undefined),
202
+ }).catch({});
203
+
204
+ const DatadogSpan = z.object({
205
+ attributes: z.object({
206
+ trace_id: z.string(), span_id: z.string().regex(/^\d{1,20}$/), parent_id: z.string().regex(/^\d{1,20}$/),
207
+ start_timestamp: z.iso.datetime(), end_timestamp: z.iso.datetime(), resource_name: z.string(),
208
+ custom: DatadogCustom.default({}),
209
+ }),
210
+ });
211
+
212
+ type DatadogSpan = z.infer<typeof DatadogSpan>;
213
+
214
+ const DatadogPage = z.object({
215
+ data: z.array(DatadogSpan.nullable().catch(null)).default([]),
216
+ // Datadog sends `page: null` on the last page, and a status other than `done` or any warning when the
217
+ // results are partial, such as a query that timed out.
218
+ meta: z.object({
219
+ page: z.object({ after: z.string() }).nullish(),
220
+ status: z.string().nullish(),
221
+ warnings: z.array(z.unknown()).nullish(),
222
+ }).nullish(),
223
+ });
224
+
225
+ const partial = (page: z.infer<typeof DatadogPage>) => (page.meta?.status ?? "done") !== "done" || Boolean(page.meta?.warnings?.length);
226
+
227
+ /** Datadog's API hosts, so its keys only ever go to Datadog. */
228
+ export const DATADOG_SITES = ["datadoghq.com", "datadoghq.eu", "us3.datadoghq.com", "us5.datadoghq.com", "ap1.datadoghq.com", "ap2.datadoghq.com", "ddog-gov.com"];
229
+
230
+ const toNano = (iso: string) => String(BigInt(Date.parse(iso)) * 1_000_000n);
231
+
232
+ const decimalId = (id: string) => BigInt(id).toString(16).padStart(16, "0");
233
+
234
+ const asText = (key: string, v: string | undefined) => (v === undefined ? [] : [{ key, value: { stringValue: v } }]);
235
+
236
+ const asDouble = (key: string, v: number | undefined) => (v === undefined ? [] : [{ key, value: { doubleValue: v } }]);
237
+
238
+ /** One Datadog span in the OTLP shape the scorer reads, keeping only the known attribute keys. */
239
+ export function fromDatadog(span: DatadogSpan): Span | null {
240
+ const a = span.attributes;
241
+ const c = a.custom;
242
+
243
+ const attributes = [
244
+ ...asText("vcs.repository.name", c.vcs?.repository?.name),
245
+ ...asText("vcs.change.id", c.vcs?.change?.id),
246
+ ...asText("vcs.ref.head.revision", c.vcs?.ref?.head?.revision),
247
+ ...asDouble("shepherd.retries", c.shepherd?.retries),
248
+ ...asText("shepherd.stage", c.shepherd?.stage),
249
+ ...asText("shepherd.outcome", c.shepherd?.outcome),
250
+ ...asDouble("stamp.cost_usd", c.stamp?.cost_usd),
251
+ ...(c.stamp?.cost_complete === undefined ? [] : [{ key: "stamp.cost_complete", value: { boolValue: c.stamp.cost_complete === "true" } }]),
252
+ ];
253
+
254
+ const parsed = Span.safeParse({
255
+ name: a.resource_name, traceId: a.trace_id, spanId: decimalId(a.span_id), parentSpanId: a.parent_id === "0" ? "" : decimalId(a.parent_id),
256
+ startTimeUnixNano: toNano(a.start_timestamp), endTimeUnixNano: toNano(a.end_timestamp), attributes,
257
+ status: c.otel?.status_code === "Error" ? { code: 2 } : undefined,
258
+ });
259
+
260
+ return parsed.success ? parsed.data : null;
261
+ }
262
+
263
+ /**
264
+ * Datadog's span search: the repository's `shepherd.iteration` and `stamp.review` roots, then every span in those
265
+ * traces, since stage spans carry no repository. The endpoint rate-limits at 300 requests an hour, so the reader
266
+ * batches trace IDs and stops at the trace and span caps.
267
+ */
268
+ export async function readDatadog(site: string, apiKey: string, appKey: string, repo: string, since: string, now = Date.now(), get: (url: string, init: RequestInit) => Promise<Response> = fetch): Promise<TraceInput> {
269
+ if (!DATADOG_SITES.includes(site)) throw new Error("invalid Datadog site");
270
+
271
+ const signal = AbortSignal.timeout(30_000);
272
+
273
+ const search = async (query: string, cursor?: string) =>
274
+ DatadogPage.parse(JSON.parse(await readResponse(await get(`https://api.${site}/api/v2/spans/events/search`, {
275
+ method: "POST",
276
+ headers: { "DD-API-KEY": apiKey, "DD-APPLICATION-KEY": appKey, "Content-Type": "application/json", Accept: "application/json" },
277
+ body: JSON.stringify({ data: { type: "search_request", attributes: { filter: { query, from: new Date(Date.parse(since)).toISOString(), to: new Date(now).toISOString() }, page: { limit: 1000, cursor }, sort: "timestamp" } } }),
278
+ redirect: "error",
279
+ signal,
280
+ }))));
281
+
282
+ const roots = await search(`@vcs.repository.name:${JSON.stringify(repo)} resource_name:(shepherd.iteration OR stamp.review)`);
283
+ const ids = [...new Set(roots.data.flatMap((s) => (s ? [s.attributes.trace_id] : [])).filter((id) => /^[0-9a-f]{32}$/.test(id)))].slice(0, MAX_TRACES);
284
+ // Here `limited` tracks only the span budget, so a truncated root search still pages through every trace it found.
285
+ const input: TraceInput = { spans: [], sources: 1, unavailable: 0, limited: false };
286
+ let incomplete = ids.length >= MAX_TRACES || Boolean(roots.meta?.page) || partial(roots);
287
+
288
+ for (let i = 0; i < ids.length && !input.limited; i += 50) {
289
+ let cursor: string | undefined;
290
+
291
+ do {
292
+ try {
293
+ const page = await search(`trace_id:(${ids.slice(i, i + 50).join(" OR ")})`, cursor);
294
+ appendSpans(input, page.data.flatMap((s) => (s ? (fromDatadog(s) ?? []) : [])));
295
+ incomplete ||= partial(page);
296
+ cursor = page.meta?.page?.after;
297
+ } catch {
298
+ input.unavailable++;
299
+ cursor = undefined;
300
+ }
301
+ } while (cursor && !input.limited);
302
+ }
303
+
304
+ input.limited ||= incomplete;
305
+
306
+ return input;
307
+ }
308
+
309
+ /** Only operator-selected files and backend configuration enter here; errors never include URLs, headers or bodies. */
310
+ export type DatadogConfig = { site: string; apiKey: string; appKey: string };
311
+
312
+ export async function collectTraces(files: string[], endpoint: string | undefined, headers: Record<string, string>, repo: string, since: string, datadog?: DatadogConfig): Promise<TraceInput> {
313
+ const input: TraceInput = { spans: [], sources: files.length + (endpoint ? 1 : 0) + (datadog ? 1 : 0), unavailable: 0, limited: false };
314
+
315
+ if (files.length > MAX_TRACES) throw new Error("at most 100 trace files may be read");
316
+
317
+ for (const file of files) {
318
+ try {
319
+ appendSpans(input, readTraceFile(file));
320
+ } catch {
321
+ input.unavailable++;
322
+ }
323
+ }
324
+
325
+ const remotes = [endpoint ? () => readTempo(endpoint, headers, repo, since) : null, datadog ? () => readDatadog(datadog.site, datadog.apiKey, datadog.appKey, repo, since) : null];
326
+
327
+ for (const read of remotes) {
328
+ if (!read) continue;
329
+
330
+ try {
331
+ const remote = await read();
332
+ appendSpans(input, remote.spans);
333
+ input.unavailable += remote.unavailable;
334
+ input.limited ||= remote.limited;
335
+ } catch {
336
+ input.unavailable++;
337
+ }
338
+ }
339
+
340
+ return input;
341
+ }
342
+
343
+ const value = (s: Span, key: string) => s.attributes.find((a) => a.key === key)?.value;
344
+
345
+ const text = (s: Span, key: string) => value(s, key)?.stringValue;
346
+
347
+ const number = (s: Span, key: string): number | undefined => {
348
+ const v = value(s, key);
349
+ const parsed = z.coerce.number().finite().nonnegative().safeParse(v?.doubleValue ?? v?.intValue);
350
+
351
+ return parsed.success ? parsed.data : undefined;
352
+ };
353
+
354
+ const startMs = (s: Span) => Number(BigInt(s.startTimeUnixNano)) / 1e6;
355
+
356
+ const duration = (s: Span) => Number(BigInt(s.endTimeUnixNano) - BigInt(s.startTimeUnixNano)) / 1e6;
357
+
358
+ const unionMs = (intervals: [number, number][]) => {
359
+ let end = 0;
360
+ let total = 0;
361
+
362
+ for (const [from, to] of intervals.sort((a, b) => a[0] - b[0])) {
363
+ total += Math.max(0, to - Math.max(from, end));
364
+ end = Math.max(end, to);
365
+ }
366
+
367
+ return total;
368
+ };
369
+
370
+ export type TraceSummary = {
371
+ iterations: number; reviews: number; failedStages: number; retries: number; iterationMs: number; approvalWaitMs: number;
372
+ reviewMs: number; knownCostUsd: number; pricedReviews: number; unpricedReviews: number;
373
+ stages: { stage: typeof STAGES[number]; durationMs: number; runs: number; failed: number }[];
374
+ signals: TraceSignal[];
375
+ evidence: { traceId: string; spanId: string; headSha: string; kind: "shepherd.iteration" | "stamp.review" }[];
376
+ };
377
+
378
+ const Kind = z.enum(["shepherd.iteration", "stamp.review"]);
379
+
380
+ /** Deduplicate exports, then correlate only known PR commits inside the requested window. These are observed samples, not a complete history. */
381
+ export function traceScores(input: TraceInput, repo: string, prs: PrRecord[], since: string, limits = traceLimits, now = Date.now()) {
382
+ const spans = [...new Map(input.spans.map((s) => [`${s.traceId}:${s.spanId}`, s])).values()];
383
+ const byPr = new Map(prs.map((pr) => [pr.number, pr]));
384
+ const summaries = new Map<number, TraceSummary>();
385
+ const children = new Map<string, Span[]>();
386
+ let unmatched = 0;
387
+
388
+ for (const s of spans) {
389
+ const key = `${s.traceId}:${s.parentSpanId}`;
390
+ const group = children.get(key) ?? [];
391
+ group.push(s);
392
+ children.set(key, group);
393
+ }
394
+
395
+ for (const root of spans) {
396
+ const kind = Kind.safeParse(root.name);
397
+
398
+ if (!kind.success || text(root, "vcs.repository.name")?.toLowerCase() !== repo.toLowerCase() || startMs(root) < Date.parse(since) || startMs(root) > now) continue;
399
+ const n = Number(text(root, "vcs.change.id") ?? number(root, "vcs.change.id"));
400
+ const pr = byPr.get(n);
401
+ const head = text(root, "vcs.ref.head.revision") ?? "";
402
+
403
+ if (!pr || !/^[0-9a-f]{40}$/.test(head) || ![pr.headSha, ...pr.commits.map((c) => c.sha)].includes(head) || duration(root) < 0 || duration(root) > 7 * 864e5) {
404
+ unmatched++;
405
+ continue;
406
+ }
407
+
408
+ const summary = summaries.get(n) ?? { iterations: 0, reviews: 0, failedStages: 0, retries: 0, iterationMs: 0, approvalWaitMs: 0, reviewMs: 0, knownCostUsd: 0, pricedReviews: 0, unpricedReviews: 0, stages: [], signals: [], evidence: [] };
409
+
410
+ if (summary.evidence.length < 20) summary.evidence.push({ traceId: root.traceId, spanId: root.spanId, headSha: head, kind: kind.data });
411
+
412
+ if (kind.data === "stamp.review") {
413
+ summary.reviews++;
414
+ summary.reviewMs += duration(root);
415
+ const cost = number(root, "stamp.cost_usd");
416
+
417
+ if (cost !== undefined) summary.knownCostUsd += cost;
418
+
419
+ if (cost !== undefined && value(root, "stamp.cost_complete")?.boolValue === true) summary.pricedReviews++;
420
+ else summary.unpricedReviews++;
421
+ } else {
422
+ summary.iterations++;
423
+ summary.iterationMs += duration(root);
424
+ summary.retries += number(root, "shepherd.retries") ?? 0;
425
+ const waits: [number, number][] = [];
426
+
427
+ for (const child of children.get(`${root.traceId}:${root.spanId}`) ?? []) {
428
+ const stage = z.enum(STAGES).safeParse(text(child, "shepherd.stage"));
429
+ const elapsed = duration(child);
430
+
431
+ if (!stage.success || elapsed < 0 || startMs(child) < startMs(root) || startMs(child) + elapsed > startMs(root) + duration(root)) continue;
432
+ const failed = ["failed", "unfinished"].includes(text(child, "shepherd.outcome") ?? "") || child.status?.code === 2 || child.status?.code === "STATUS_CODE_ERROR";
433
+ const record = summary.stages.find((s) => s.stage === stage.data) ?? { stage: stage.data, durationMs: 0, runs: 0, failed: 0 };
434
+ record.durationMs += elapsed;
435
+ record.runs++;
436
+ record.failed += Number(failed);
437
+ summary.failedStages += Number(failed);
438
+
439
+ if (stage.data === "stamp") waits.push([startMs(child), startMs(child) + elapsed]);
440
+
441
+ if (!summary.stages.includes(record)) summary.stages.push(record);
442
+ }
443
+
444
+ summary.approvalWaitMs += unionMs(waits);
445
+ }
446
+
447
+ summaries.set(n, summary);
448
+ }
449
+
450
+ for (const s of summaries.values()) {
451
+ if (s.failedStages) s.signals.push("trace_stage_failed");
452
+
453
+ if (s.retries >= limits.retries) s.signals.push("trace_retries");
454
+
455
+ if (s.approvalWaitMs >= limits.waitMs && s.approvalWaitMs >= s.iterationMs / 2) s.signals.push("trace_approval_wait");
456
+
457
+ if (s.knownCostUsd >= limits.costUsd) s.signals.push("trace_review_cost");
458
+ }
459
+
460
+ return { summaries, coverage: { sources: input.sources, unavailable: input.unavailable, limited: input.limited, unmatchedRoots: unmatched, observedOnly: true }, limits };
461
+ }
package/src/garden.ts CHANGED
@@ -12,6 +12,7 @@ export type Commit = { sha: string; headline: string; skill: string | null; lens
12
12
 
13
13
  export type PrRecord = {
14
14
  number: number;
15
+ headSha?: string;
15
16
  title: string;
16
17
  state: string;
17
18
  threads: Thread[];
@@ -218,6 +219,6 @@ export function collect(repo: string, since: string): PrRecord[] {
218
219
  const status = Statuses.parse(JSON.parse(gh(["api", `repos/${repo}/commits/${pr.headRefOid}/status`]))).statuses.find((s) => s.context === "shepherd");
219
220
  const summary = Comments.parse(JSON.parse(gh(["api", "--paginate", "--slurp", `repos/${repo}/issues/${pr.number}/comments`])).flat()).find((c) => c.body.includes("<!-- shepherd-swarm-summary -->"));
220
221
 
221
- return { number: pr.number, title: pr.title, state: pr.state, threads, commits, status: status ? { state: status.state, description: status.description ?? "", updatedAt: status.updated_at } : null, rounds: roundsOf(summary?.body), trusted: trusted(pr.author.login) };
222
+ return { number: pr.number, headSha: pr.headRefOid, title: pr.title, state: pr.state, threads, commits, status: status ? { state: status.state, description: status.description ?? "", updatedAt: status.updated_at } : null, rounds: roundsOf(summary?.body), trusted: trusted(pr.author.login) };
222
223
  });
223
224
  }
package/src/install.ts CHANGED
@@ -6,6 +6,9 @@ import path from "node:path";
6
6
 
7
7
  export const MARKER = ".shepherd-installed";
8
8
 
9
+ /** A workflow template with every `SHEPHERD_VERSION:` pin set to `version`, so each job runs the CLI that wrote it. */
10
+ export const pinWorkflow = (text: string, version: string) => text.replaceAll(/SHEPHERD_VERSION: \S+/g, `SHEPHERD_VERSION: ${version}`);
11
+
9
12
  // Command files are single files, so they carry the marker as a comment line instead.
10
13
  const COMMAND_MARKER = "<!-- shepherd-installed -->";
11
14