vouchington-tooling 0.78.2 → 0.80.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.
- package/README.md +58 -3
- package/dist/agent-blackboard/feedback-journal-sandbox.d.mts +1 -1
- package/dist/agent-blackboard/feedback-journal-sandbox.mjs +11 -2
- package/dist/audit-journal/audit-block.d.mts +8 -2
- package/dist/audit-journal/audit-block.mjs +35 -5
- package/dist/audit-journal/ci-failures.mjs +11 -1
- package/dist/cli/index.mjs +3 -0
- package/dist/cli/parse-forwarded-commands.d.mts +1 -1
- package/dist/cli/parse-forwarded-commands.mjs +1 -0
- package/dist/cli/parse.d.mts +3 -0
- package/dist/cli/usage-text.d.mts +1 -1
- package/dist/cli/usage-text.mjs +2 -0
- package/dist/mcp-server/dispatch.d.mts +3 -0
- package/dist/mcp-server/dispatch.mjs +7 -1
- package/dist/mcp-server/install-info.d.mts +11 -0
- package/dist/mcp-server/install-info.mjs +45 -0
- package/dist/mcp-server/retrospective-facts-input.d.mts +2 -0
- package/dist/mcp-server/retrospective-facts-input.mjs +8 -2
- package/dist/mcp-server/retrospective-input.mjs +6 -2
- package/dist/mcp-server/run.mjs +2 -0
- package/dist/retrospective-transcript/codex-segment.d.mts +7 -0
- package/dist/retrospective-transcript/codex-segment.mjs +14 -10
- package/dist/retrospective-transcript/index.mjs +16 -11
- package/dist/runner-policy/cli.d.mts +6 -0
- package/dist/runner-policy/cli.mjs +45 -0
- package/dist/runner-policy/config.d.mts +3 -0
- package/dist/runner-policy/config.mjs +97 -0
- package/dist/runner-policy/discover.d.mts +9 -0
- package/dist/runner-policy/discover.mjs +34 -0
- package/dist/runner-policy/evaluate.d.mts +7 -0
- package/dist/runner-policy/evaluate.mjs +61 -0
- package/dist/runner-policy/index.d.mts +6 -0
- package/dist/runner-policy/index.mjs +4 -0
- package/dist/runner-policy/matrix.d.mts +13 -0
- package/dist/runner-policy/matrix.mjs +45 -0
- package/dist/runner-policy/rules.d.mts +6 -0
- package/dist/runner-policy/rules.mjs +87 -0
- package/dist/runner-policy/types.d.mts +38 -0
- package/dist/runner-policy/types.mjs +1 -0
- package/dist/runner-policy/workflow.d.mts +24 -0
- package/dist/runner-policy/workflow.mjs +37 -0
- package/dist/sql-ast/no-mistakes-peer.d.mts +54 -49
- package/package.json +7 -2
- package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
package/README.md
CHANGED
|
@@ -86,6 +86,7 @@ vouchington harness-assert-gates HARNESS_DISPATCH_ENABLED HARNESS_SHEPHERD_ENABL
|
|
|
86
86
|
echo '[{"login":"octocat","type":"User"}]' | vouchington gha-collaborator-trust owner/repo --allow-bot github-actions[bot]
|
|
87
87
|
vouchington nuget-central-version trusted.props candidate.props metadata.json out.props
|
|
88
88
|
vouchington verify-workflow-secrets --repo owner/name --inventory .github/workflows/workflow-secrets-inventory.mts
|
|
89
|
+
vouchington runner-policy --config .github/runner-policy.json --root .github/workflows
|
|
89
90
|
vouchington tmux up --config tmux.json --no-attach
|
|
90
91
|
vouchington tmux name my-topic
|
|
91
92
|
vouchington tmux read-title
|
|
@@ -704,6 +705,7 @@ import { runAstGrepExamples } from 'vouchington-tooling/ast-grep-examples'
|
|
|
704
705
|
import { astGrepPackPaths } from 'vouchington-tooling/ast-grep-pack'
|
|
705
706
|
import { validateNugetUpdate } from 'vouchington-tooling/nuget-central-version'
|
|
706
707
|
import { runVerifyWorkflowSecretsCli } from 'vouchington-tooling/workflow-secrets-drift'
|
|
708
|
+
import { evaluateRunnerPolicy } from 'vouchington-tooling/runner-policy'
|
|
707
709
|
import { launchSession, loadTmuxConfig } from 'vouchington-tooling/tmux'
|
|
708
710
|
import { runDeadCodeGate } from 'vouchington-tooling/dead-code'
|
|
709
711
|
import { normalizeSwiftSource } from 'vouchington-tooling/swift-semantic-equal'
|
|
@@ -1163,9 +1165,14 @@ await composeRetrospective({ ...input, journal: { journalLoader } })
|
|
|
1163
1165
|
`journalLoader` is a `JournalLoader`; `JournalLoader`, `JournalLoadResult`,
|
|
1164
1166
|
`JournalEntry`, and `JournalAuditOptions` are exported as types from
|
|
1165
1167
|
`vouchington-tooling/agent-blackboard`. The `## CI Failures` block grammar has three status
|
|
1166
|
-
lines (`failures observed`, `none observed`, `unavailable (<reason>)`).
|
|
1167
|
-
|
|
1168
|
-
|
|
1168
|
+
lines (`failures observed`, `none observed`, `unavailable (<reason>)`). An entry may hold several
|
|
1169
|
+
CI-failure blocks, and each top-level block line (`` - ` ``) starts one. A block that names
|
|
1170
|
+
`recurring` or `one-off` with `GitHub Actions` but does not match the grammar is reported as one
|
|
1171
|
+
`unparsed` note counting such blocks, never silently dropped.
|
|
1172
|
+
Journal-only sandbox and permission entries are journal Markdown entries that hold one or more
|
|
1173
|
+
blocks, split the same way, escaped and length-bounded like CI failures. A block that names
|
|
1174
|
+
`sandbox-escalation`, `sandbox-failure`, or `ambiguous-failure` but does not match the grammar is
|
|
1175
|
+
reported as an `unparsed` note; other text is ignored:
|
|
1169
1176
|
|
|
1170
1177
|
```markdown
|
|
1171
1178
|
- `sandbox-escalation` — git push — network write blocked
|
|
@@ -1439,3 +1446,51 @@ const { result, error } = await withPostgresQueryFailureForTest(
|
|
|
1439
1446
|
The package's own tests start a throwaway cluster with `initdb`/`pg_ctl` found through
|
|
1440
1447
|
`POSTGRES_BIN_DIR`, `PATH` or a standard install location. They skip where no server can run and
|
|
1441
1448
|
fail under `CI`.
|
|
1449
|
+
|
|
1450
|
+
## Runner policy
|
|
1451
|
+
|
|
1452
|
+
`vouchington runner-policy [--config <file>] [--root <directory>]` checks GitHub Actions runner
|
|
1453
|
+
policy for a consumer's workflows. `--config` defaults to `.github/runner-policy.json` and `--root`
|
|
1454
|
+
to `.github/workflows` (only `*.yml` / `*.yaml` files directly under the root are read). It prints
|
|
1455
|
+
each violation and exits 1 on any violation, 0 when clean, and 2 on a usage error. The library
|
|
1456
|
+
subpath `vouchington-tooling/runner-policy` exports the pure
|
|
1457
|
+
`evaluateRunnerPolicy(inputs: {path, text}[], config)` plus `parseRunnerPolicyConfig`,
|
|
1458
|
+
`discoverWorkflows` and `loadRunnerPolicyConfig`. A workflow is identified by its path relative to
|
|
1459
|
+
the root (for example `checks.yml`).
|
|
1460
|
+
|
|
1461
|
+
```json
|
|
1462
|
+
{
|
|
1463
|
+
"allowedLabels": ["runner-small", "runner-large"],
|
|
1464
|
+
"requiredJobs": [{ "workflow": "ci.yml", "job": "gate", "runsOn": "runner-large" }],
|
|
1465
|
+
"exactLabelJobs": [{ "label": "runner-arm", "jobs": ["ci.yml#build", "ci.yml#test"] }],
|
|
1466
|
+
"restrictedLabels": [
|
|
1467
|
+
{
|
|
1468
|
+
"label": "runner-small",
|
|
1469
|
+
"forbidServices": true,
|
|
1470
|
+
"forbiddenActions": {
|
|
1471
|
+
"prefixes": ["docker/"],
|
|
1472
|
+
"contains": ["/docker/"],
|
|
1473
|
+
"exact": ["./.github/actions/setup-db"]
|
|
1474
|
+
}
|
|
1475
|
+
}
|
|
1476
|
+
]
|
|
1477
|
+
}
|
|
1478
|
+
```
|
|
1479
|
+
|
|
1480
|
+
Only `allowedLabels` (non-empty) is required; unknown keys are rejected and every config problem is
|
|
1481
|
+
reported at once. Policies:
|
|
1482
|
+
|
|
1483
|
+
- `allowedLabels`: every non-delegate job's `runs-on` must be a literal string in the set, or
|
|
1484
|
+
`${{ matrix.<field> }}` resolving from `strategy.matrix.<field>` plus `strategy.matrix.include[].<field>`
|
|
1485
|
+
to a non-empty candidate list whose members are all in the set. Missing `runs-on`, unresolved or
|
|
1486
|
+
expression matrices, other computed expressions, array label sets and object forms are rejected.
|
|
1487
|
+
- Jobs with `uses:` (reusable-workflow delegates) must not set `runs-on`.
|
|
1488
|
+
- `requiredJobs`: each job must exist in its workflow and use exactly the literal `runsOn`.
|
|
1489
|
+
- `exactLabelJobs`: the `workflow#job` entries running on `label` (literally or through any matrix
|
|
1490
|
+
candidate) must equal `jobs`; missing and extra entries are both reported.
|
|
1491
|
+
- `restrictedLabels`: jobs using `label` literally must not declare non-empty `services`
|
|
1492
|
+
(`forbidServices`, default `true`) nor use a step `uses` value matching `forbiddenActions`
|
|
1493
|
+
`prefixes`, `contains` substrings or `exact` values.
|
|
1494
|
+
|
|
1495
|
+
The check fails closed: no discovered workflows, a missing root, an unreadable config or workflow,
|
|
1496
|
+
a YAML parse error, or a config entry naming an undiscovered workflow is a failure, never a pass.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { AuditRedactor } from '../audit-journal/text.mts';
|
|
2
2
|
import type { JournalEntry } from '../audit-journal/types.mts';
|
|
3
|
-
/** Journal entries that hold
|
|
3
|
+
/** Journal entries that hold sandbox or permission blocks (several per entry), made paste-safe. */
|
|
4
4
|
export declare function getConformingSandboxBlocks(entries: Iterable<JournalEntry>, redact?: AuditRedactor, maxBytes?: number): string[];
|
|
5
5
|
export declare function unavailableSandboxSection(reason: string, blocks?: string[]): string;
|
|
6
6
|
export declare function journalSandboxSection(blocks: string[]): string;
|
|
@@ -44,9 +44,18 @@ function omissionBlock(count) {
|
|
|
44
44
|
' - Disposition: see journal for the omitted blocks',
|
|
45
45
|
].join('\n');
|
|
46
46
|
}
|
|
47
|
-
/** Journal
|
|
47
|
+
/** Journal text that names a sandbox block type but does not match its grammar. */
|
|
48
|
+
const UNPARSED = {
|
|
49
|
+
marker: /`(?:sandbox-escalation|sandbox-failure|ambiguous-failure)`/,
|
|
50
|
+
note: (count) => [
|
|
51
|
+
`- \`ambiguous-failure\` — unparsed — ${count} journal blocks named a sandbox event but did not match the block grammar; see journal`,
|
|
52
|
+
' - Evidence: unparsed blocks remain in the session journal',
|
|
53
|
+
' - Disposition: see journal for the unparsed sandbox blocks',
|
|
54
|
+
].join('\n'),
|
|
55
|
+
};
|
|
56
|
+
/** Journal entries that hold sandbox or permission blocks (several per entry), made paste-safe. */
|
|
48
57
|
export function getConformingSandboxBlocks(entries, redact, maxBytes = SANDBOX_BLOCKS_MAX_BYTES) {
|
|
49
|
-
return conformingBlocks(entries, matchBlock, Math.min(maxBytes, SANDBOX_BLOCKS_MAX_BYTES), redact, omissionBlock);
|
|
58
|
+
return conformingBlocks(entries, matchBlock, Math.min(maxBytes, SANDBOX_BLOCKS_MAX_BYTES), redact, omissionBlock, UNPARSED);
|
|
50
59
|
}
|
|
51
60
|
export function unavailableSandboxSection(reason, blocks = []) {
|
|
52
61
|
return [`${SANDBOX_SECTION_HEADER}\nStatus: unavailable (${reason})`, ...blocks].join('\n\n');
|
|
@@ -5,9 +5,15 @@ import { type AuditRedactor } from './text.mts';
|
|
|
5
5
|
export declare function matchAuditBlock(markdown: string, patterns: readonly RegExp[], prefixes: readonly string[], render: AuditRender & {
|
|
6
6
|
shrinkOrder: readonly number[];
|
|
7
7
|
}): string | null;
|
|
8
|
+
/** What counts as an audit block that failed to parse, and how to report that many of them. */
|
|
9
|
+
export type UnparsedReport = {
|
|
10
|
+
marker: RegExp;
|
|
11
|
+
note: (count: number) => string;
|
|
12
|
+
};
|
|
8
13
|
/**
|
|
9
14
|
* Matches every journal block whole while together they fit `totalBudgetBytes`. Otherwise it keeps
|
|
10
15
|
* the leading blocks that fit an equal share of the total and appends `omission(count)` — itself a
|
|
11
|
-
* conforming block — so dropped groups are always reported, never silent.
|
|
16
|
+
* conforming block — so dropped groups are always reported, never silent. Blocks that name an
|
|
17
|
+
* audit type but do not match the grammar are counted and reported by `unparsed`, never ignored.
|
|
12
18
|
*/
|
|
13
|
-
export declare function conformingBlocks(entries: Iterable<JournalEntry>, match: (markdown: string, render: AuditRender) => string | null, totalBudgetBytes: number, redact: AuditRedactor | undefined, omission: (count: number) => string): string[];
|
|
19
|
+
export declare function conformingBlocks(entries: Iterable<JournalEntry>, match: (markdown: string, render: AuditRender) => string | null, totalBudgetBytes: number, redact: AuditRedactor | undefined, omission: (count: number) => string, unparsed?: UnparsedReport): string[];
|
|
@@ -43,18 +43,48 @@ export function matchAuditBlock(markdown, patterns, prefixes, render) {
|
|
|
43
43
|
const contents = fitFields(safe.map(({ units }) => units), overhead, render.budgetBytes ?? Infinity, render.shrinkOrder);
|
|
44
44
|
return safe.map(({ prefix }, index) => `${prefix}${contents[index]}`).join('\n');
|
|
45
45
|
}
|
|
46
|
+
const BLOCK_START = '- `';
|
|
47
|
+
/**
|
|
48
|
+
* One entry may hold several blocks: each top-level block line starts one. Text that does not
|
|
49
|
+
* open with a block is returned whole, so it either matches as a single block or is reported.
|
|
50
|
+
*/
|
|
51
|
+
function splitBlocks(markdown) {
|
|
52
|
+
const lines = markdown.replace(/\r\n?/g, '\n').split('\n');
|
|
53
|
+
const first = lines.find((line) => !BLANK.test(line));
|
|
54
|
+
if (first === undefined || !first.startsWith(BLOCK_START))
|
|
55
|
+
return [markdown];
|
|
56
|
+
const chunks = [];
|
|
57
|
+
for (const line of lines.slice(lines.indexOf(first))) {
|
|
58
|
+
if (line.startsWith(BLOCK_START))
|
|
59
|
+
chunks.push([line]);
|
|
60
|
+
else
|
|
61
|
+
chunks.at(-1).push(line);
|
|
62
|
+
}
|
|
63
|
+
return chunks.map((chunk) => chunk.join('\n'));
|
|
64
|
+
}
|
|
46
65
|
/**
|
|
47
66
|
* Matches every journal block whole while together they fit `totalBudgetBytes`. Otherwise it keeps
|
|
48
67
|
* the leading blocks that fit an equal share of the total and appends `omission(count)` — itself a
|
|
49
|
-
* conforming block — so dropped groups are always reported, never silent.
|
|
68
|
+
* conforming block — so dropped groups are always reported, never silent. Blocks that name an
|
|
69
|
+
* audit type but do not match the grammar are counted and reported by `unparsed`, never ignored.
|
|
50
70
|
*/
|
|
51
|
-
export function conformingBlocks(entries, match, totalBudgetBytes, redact, omission) {
|
|
71
|
+
export function conformingBlocks(entries, match, totalBudgetBytes, redact, omission, unparsed) {
|
|
72
|
+
let unparsedCount = 0;
|
|
52
73
|
const markdowns = [...entries]
|
|
53
74
|
.flatMap((entry) => {
|
|
54
75
|
const data = entry?.data;
|
|
55
|
-
return data?.type === 'journal' && typeof data.markdown === 'string'
|
|
76
|
+
return data?.type === 'journal' && typeof data.markdown === 'string'
|
|
77
|
+
? splitBlocks(data.markdown)
|
|
78
|
+
: [];
|
|
56
79
|
})
|
|
57
|
-
.filter((markdown) =>
|
|
80
|
+
.filter((markdown) => {
|
|
81
|
+
if (match(markdown, { redact }) !== null)
|
|
82
|
+
return true;
|
|
83
|
+
if (unparsed?.marker.test(markdown))
|
|
84
|
+
unparsedCount++;
|
|
85
|
+
return false;
|
|
86
|
+
});
|
|
58
87
|
const { rendered, omitted } = selectWithin(markdowns, totalBudgetBytes, byteLength(omission(markdowns.length)) + 2, 2, MIN_BLOCK_SHARE_BYTES, (markdown, budgetBytes) => match(markdown, { redact, budgetBytes }));
|
|
59
|
-
|
|
88
|
+
const blocks = omitted ? [...rendered, omission(omitted)] : rendered;
|
|
89
|
+
return unparsed && unparsedCount ? [...blocks, unparsed.note(unparsedCount)] : blocks;
|
|
60
90
|
}
|
|
@@ -28,6 +28,16 @@ function omissionGroup(count) {
|
|
|
28
28
|
' - Disposition: see journal for the omitted failure groups',
|
|
29
29
|
].join('\n');
|
|
30
30
|
}
|
|
31
|
+
/** Journal text that names a CI failure group but does not match the block grammar. */
|
|
32
|
+
const UNPARSED = {
|
|
33
|
+
marker: /`(?:recurring|one-off)` — `GitHub Actions`/,
|
|
34
|
+
note: (count) => [
|
|
35
|
+
`- \`one-off\` — \`GitHub Actions\` — ${count} journal blocks named a CI failure but did not match the block grammar; see journal`,
|
|
36
|
+
' - Evidence: unparsed blocks remain in the session journal',
|
|
37
|
+
' - Root diagnostic: not parsed; the journal text did not match the documented block grammar',
|
|
38
|
+
' - Disposition: see journal for the unparsed failure blocks',
|
|
39
|
+
].join('\n'),
|
|
40
|
+
};
|
|
31
41
|
export function isConformingCiFailureBlock(markdown) {
|
|
32
42
|
if (markdown.length > CI_FAILURE_BLOCK_MAX_BYTES ||
|
|
33
43
|
Buffer.byteLength(markdown) > CI_FAILURE_BLOCK_MAX_BYTES)
|
|
@@ -35,7 +45,7 @@ export function isConformingCiFailureBlock(markdown) {
|
|
|
35
45
|
return matchBlock(markdown) !== null;
|
|
36
46
|
}
|
|
37
47
|
export function getConformingGroups(entries, redact, maxBytes = CI_SECTION_MAX_BYTES) {
|
|
38
|
-
return conformingBlocks(entries, matchBlock, Math.min(maxBytes, CI_SECTION_MAX_BYTES), redact, omissionGroup);
|
|
48
|
+
return conformingBlocks(entries, matchBlock, Math.min(maxBytes, CI_SECTION_MAX_BYTES), redact, omissionGroup, UNPARSED);
|
|
39
49
|
}
|
|
40
50
|
export function incompleteCiSection(markdownBlocks) {
|
|
41
51
|
return [
|
package/dist/cli/index.mjs
CHANGED
|
@@ -16,6 +16,7 @@ import { runScript } from "./commands/spawn-script.mjs";
|
|
|
16
16
|
import { runNugetCentralVersionCommand } from "./commands/nuget-central-version.mjs";
|
|
17
17
|
import { runDeadCodeCli } from "../dead-code/cli.mjs";
|
|
18
18
|
import { runVerifyWorkflowSecretsCli } from "../workflow-secrets-drift/cli.mjs";
|
|
19
|
+
import { runRunnerPolicyCli } from "../runner-policy/cli.mjs";
|
|
19
20
|
import { runVitestBlobManifestCommand } from "./commands/vitest-blob-manifest.mjs";
|
|
20
21
|
import { runVitestReportAttemptCommand } from "./commands/vitest-report-attempt.mjs";
|
|
21
22
|
import { runPrepareVitestReportsCommand } from "./commands/prepare-vitest-reports.mjs";
|
|
@@ -83,6 +84,8 @@ export function runCli(argv = process.argv) {
|
|
|
83
84
|
return runNugetCentralVersionCommand(parsed.args);
|
|
84
85
|
case 'verify-workflow-secrets':
|
|
85
86
|
return runVerifyWorkflowSecretsCli(parsed.args);
|
|
87
|
+
case 'runner-policy':
|
|
88
|
+
return runRunnerPolicyCli(parsed.args);
|
|
86
89
|
case 'dead-code':
|
|
87
90
|
return runDeadCodeCli(parsed.args);
|
|
88
91
|
case 'swift-semantic-equal':
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
declare const FORWARDED: readonly ["with-host-lock", "host-storage", "pnpm-install", "vitest-blob-manifest", "vitest-report-attempt", "prepare-vitest-reports", "nuget-central-version", "verify-workflow-secrets", "dead-code", "swift-semantic-equal", "post-review", "stage-review-payload", "retrospective-transcript", "retrospective-facts", "agent-blackboard", "mcp", "hook", "worktree", "transient-retry", "sandbox-command-audit", "cloc", "coverage-scope-check", "trivy-policy", "docker-image-mirror", "workspace-registry-check", "storybook-browser-runner", "tmux"];
|
|
1
|
+
declare const FORWARDED: readonly ["with-host-lock", "host-storage", "pnpm-install", "vitest-blob-manifest", "vitest-report-attempt", "prepare-vitest-reports", "nuget-central-version", "verify-workflow-secrets", "runner-policy", "dead-code", "swift-semantic-equal", "post-review", "stage-review-payload", "retrospective-transcript", "retrospective-facts", "agent-blackboard", "mcp", "hook", "worktree", "transient-retry", "sandbox-command-audit", "cloc", "coverage-scope-check", "trivy-policy", "docker-image-mirror", "workspace-registry-check", "storybook-browser-runner", "tmux"];
|
|
2
2
|
type Name = (typeof FORWARDED)[number];
|
|
3
3
|
type ForwardedCommand = {
|
|
4
4
|
[K in Name]: {
|
package/dist/cli/parse.d.mts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n runner-port-policy Print or validate a runner port policy\n with-host-lock Run a command under a host-wide lock\n host-storage Check free space on caller-supplied paths\n gha-runtime-audit Audit successful GitHub Actions job runtimes\n require-up-to-date Require HEAD to include a fetched remote branch\n fresh-base Classify the worktree against a remote base branch\n gitleaks-directory-scan Scan a directory with Gitleaks\n ast-grep-examples Run AST-grep rule examples\n ast-grep-pack Print shipped unconditional AST-grep pack paths as JSON\n gha-workspace-policy Check GitHub Actions workspace safety policy\n gha-output Write a collision-safe multiline GITHUB_OUTPUT record\n gha-needs-results Fail if required GitHub Actions job results failed\n download-with-diagnostics Download a URL and report HTTP status on failure\n download-optional-run-artifacts Download optional artifacts from the current run\n host-pressure-diagnostics Print a bounded host memory/OOM/PSI snapshot\n allocate-browser-safe-ports Allocate Fetch-safe localhost ports\n diagnose-port-collision Capture bounded localhost port diagnostics\n prepare-trivy-db Download the Trivy vulnerability database\n gha-artifacts-cleanup Delete classified GitHub Actions artifacts\n agent-issue-labels Map changed paths to labels; create missing repository labels\n http-origin Validate an optional HTTP(S) origin\n vitest-blob-manifest Stamp a vitest-blob-manifest:v1 identity file\n vitest-report-attempt Write or read a Vitest report-attempt marker\n prepare-vitest-reports Validate and select Vitest report JSON files\n pnpm-install Install a pnpm workspace with retry and release-age fail-fast\n check-cache-size Measure a path and decide whether to save a GHA cache\n make-shard-matrix Emit a [1..N] GitHub Actions shard matrix\n load-runner-env Overlay a runner env file onto GITHUB_ENV with injection guards\n clean-workspace Reset a persistent-runner workspace with a fork-PR trust gate\n install-github-release Download a checksum-verified GitHub Release binary\n run-with-timeout Run a command with GNU timeout or a Perl fallback\n lint-links Two-pass lychee: internal links fail, external warn\n materialize-pr-context Dump PR title/body/files/diff/comments and #N crawl\n wait-for-apt-locks Wait until apt/dpkg lock files are free\n install-playwright-chromium-arm64 Install Playwright Chromium from browsers.json\n ghcr-package-retention Delete old GHCR package versions (KEEP_MIN or --main-history)\n harness-admission-lane Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n harness-assert-gates Fail if any named HARNESS_*_ENABLED gate is enabled\n gha-collaborator-trust Classify authors as write-access collaborators or not\n nuget-central-version Validate a Directory.Packages.props PackageVersion delta\n verify-workflow-secrets Check a secret inventory against live repository and environment secrets\n dead-code Gate unused code against a committed jscpd baseline\n swift-semantic-equal Compare Swift sources ignoring comments and whitespace\n post-review Post one COMMENT review from a staged payload file\n stage-review-payload Validate a review payload file into a staging directory\n retrospective-transcript Format facts from Claude-compatible, Codex, or Grok transcripts\n link-skill Link one packaged skill into an explicit consumer directory\n retrospective-facts Gather immutable facts for a retrospective\n agent-blackboard Probe an Agent Blackboard deployment, classify distill sessions, manage snapshots\n mcp Serve the agent-blackboard journal tools over stdio (MCP)\n hook Run a repository policy module as a pre/post tool-use hook\n worktree Reclaim finished git worktrees (dry run unless --yes)\n tmux Run configured dev windows in tmux; name panes; agent reminders\n story-coverage Check component exports are imported by stories\n transient-retry Rerun a failed GitHub Actions run when an injected rule matches\n sandbox-command-audit Audit agent transcripts for sandbox escalations and denials\n cloc Count tracked lines of code by category and service with scc\n coverage-scope-check Check positive-threshold coverage rules against the Vitest scope\n trivy-policy Check tracked Trivy workflow scans and the exception registry\n docker-image-mirror Require tracked Docker images to come from a Docker Hub mirror\n workspace-registry-check Check syncpack, pnpm workspace and CI path-filter registries against tracked manifests\n storybook-browser-runner Run the Storybook Vitest browser project with cache, retry and watchdog\n\nOptions:\n -h, --help Show this help\n -v, --version Print the package version\n\nrunner-port-policy\n (no args) Print the shipped policy as JSON\n --file <path> Validate and print a policy file\n --reserved <port> Print true if the port is reserved\n\nwith-host-lock\n --name <family>\n [--slots <n>]\n --timeout-seconds <n>\n [--command-timeout-seconds <n>]\n [--failure-diagnostics <absolute-script>]\n [--on-acquire-timeout fail|run-unlocked]\n -- <command> [args...]\n\nhost-storage --path <path> [--path <path>...] [--minimum-free-bytes <bytes>] [--pnpm-store] [--docker-root] [--docker-desktop-path <path>] [--discovery-timeout-ms <ms>]\n\ngha-runtime-audit\n [--repository owner/name] Default GITHUB_REPOSITORY\n [--branch main]\n [--median-threshold-floor <seconds>] Off unless set. Must be below the ceiling\n [--median-threshold-ceiling <seconds>] Default 360. Flags a five-sample median above this\n --pr-workflow <name|/regex/> Repeatable\n --push-workflow <name|/regex/> Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nagent-issue-labels labels-from-paths [--labeler <path>] <path>...\nagent-issue-labels ensure-labels [--repo owner/name] [--policy-file json] [--update] <label>...\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nverify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]\ndead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir> Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)\nagent-blackboard distill classify <partition.jsonl> --retro-cutoff ISO8601 --session-cutoff ISO8601\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n (no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,\n session_ensure, retrospective_check, retrospective_save,\n pr_validate, pr_create, pr_update,\n snapshot_export, snapshot_partition, snapshot_cleanup, and session_archive over stdio.\n Needs the optional @modelcontextprotocol/sdk peer (and zod).\n Launch it from inside the repository's git worktree.\n\nhook pre-tool-use|post-tool-use --harness claude|codex|cursor|grok --policy <module> [--root <dir>] [--automation-env NAME]...\n Reads the harness hook payload on stdin. <module> default-exports a policy object (or a function\n of the hook context returning one) with a command rule table, post-tool-use checkers, and an\n optional reminder. pre-tool-use exits 2 to block, and also when the policy cannot load.\n post-tool-use is advisory and always exits 0. --root defaults to the working directory.\n Each --automation-env NAME (repeatable) marks the run unattended when that environment variable\n is set, non-empty, and not 0 or false; CI markers and claude -p are always unattended.\n\nworktree reclaim [--yes] [--json] [--max-worktrees N] [--timeout-ms N] [--pr-limit N] [--after PATH]\n Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the\n branch is merged or closed at exactly HEAD, using git worktree remove (never forced).\n Skips the main checkout, the current worktree, and locked, bare or detached worktrees.\n\ntransient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run] <run-id>\n Loads a module exporting \"rules\" (and optionally \"limits\"), evaluates them against the failed run,\n and reruns only on a match. Exits 0 on rerun, 2 when none is warranted, 1 on error.\n\nsandbox-command-audit --rules <module> [--settings-path <file>] [--repo-root <dir>]... [--worktree-glob <glob>]... [--projects-dir <dir>] [--codex-sessions-dir <dir>] [--session-id <id>] [--limit N] [--since DAYS] [--json] [--raw]\n Scans Claude and Codex transcripts scoped to this repository (git roots plus any --worktree-glob\n layouts) and reports Bash escalations, denials and permission failures by command prefix.\n <module> exports an object (default or \"rules\") with loadPolicy({ settingsPath, cwd }), which\n returns { covers(list, commandOrPrefix) } for the allow/deny/excluded lists or { error }, and\n optionally classifyFailure(command, text, source), limits and worktreeGlobs. Transcript roots\n default to CLAUDE_CONFIG_DIR/projects and CODEX_HOME/sessions. --raw prints full command text.\n\ncloc --config <file> [--scc-bin <path>] [--json]\n Counts git-tracked lines with scc (SCC_BIN or --scc-bin, else \"scc\"), classified into\n source/tests/tooling and by service, and prints an aligned table (--json: rows). <file> is a .json\n file or a module whose default (or \"config\") export is the layout: services [{ name, match }],\n defaultService, categories, testPatterns, toolingPatterns, countedRoots, countedRootFiles,\n excludedDirs, ignoredDirs, sccBin, missingSccHint.\n\ncoverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]... [--exclude <glob>]...\n Fails (exit 1) when a git-tracked file that a coverage rules file (default .coverage-rules.yml)\n gives a patch_coverage_min above 0, and its scope does not ignore, is outside the collector's\n scope. The collector scope is the repeated --include/--exclude globs plus, optionally, the\n include/exclude string arrays of a --scope-file JSON written from the Vitest coverage config.\n At least one include glob is required.\n\ntrivy-policy [--root <dir>] [--ignore-file <path>] [--findings-exit-code-env <NAME>] [--cleanup-url-prefix <url>] [--min-gates N] [--min-sboms N] [--max-expiry-days N]\n Reads git-tracked workflows, composite actions and shell scripts and prints each violation (exit 1).\n Every Trivy package scan must be an auditable CLI run block (no action, wrapper, substitution or\n background). Vulnerability gates need --scanners vuln, --pkg-types os, --severity CRITICAL,HIGH,\n --ignore-unfixed, --skip-db-update, --quiet, table output to a file, --ignorefile <ignore-file>\n (default .trivyignore.yaml) and --exit-code \"$<NAME>\" (default TRIVY_FINDINGS_EXIT_CODE).\n CycloneDX SBOM scans must be unfiltered with --exit-code 0. At least --min-gates gates and\n --min-sboms SBOM scans (default 2 each) must exist. The tracked ignore registry needs purl-exact OS\n packages, a \"Not exploitable: ... Cleanup: <issue URL>\" statement (URL must start with\n --cleanup-url-prefix when given) and an expired_at between tomorrow and --max-expiry-days (30).\n\ndocker-image-mirror [--root <dir>] [--mirror <host>] [--allow-registry <prefix>]... [--require-digest]\n [--allow-ref-expression <text>]...\n Prints each Docker Hub image in git-tracked workflows, composite actions and Dockerfiles (exit 1):\n run, pull and create commands, containers, services, docker:// references, buildx drivers, FROM,\n COPY --from and # syntax. Images must name a registry host; --mirror (default mirror.gcr.io) is\n the host the message tells you to use. --allow-registry (repeatable) instead requires every image,\n including FROM and COPY --from, to start with one of the prefixes; a reference that expands a\n variable passes only when its literal text before the variable starts with a prefix. --require-digest\n requires @sha256: plus 64 lowercase hex characters. Stage aliases and scratch stay exempt.\n --allow-ref-expression (repeatable) is an audited escape hatch for dynamic job outputs: a reference\n whose raw text exactly equals the value is accepted. Images the same file builds locally are exempt.\n\nworkspace-registry-check [--root <dir>] [--syncpack-config <path>] [--workspace-file <path>]\n [--path-filters <path>] [--tooling-group <name>] [--trigger-only-glob <glob>] [--runtime-prefix <prefix>]\n Reconciles git-tracked package.json manifests with the syncpack \"source\" globs (default\n .syncpackrc.json), the pnpm \"packages\" globs (pnpm-workspace.yaml) and the dorny/paths-filter groups\n (.github/ci-path-filters.yml) and prints one line per violation (exit 1). The --tooling-group group\n (default tooling) must reach every manifest and wildcard workspace glob, and its --trigger-only-glob\n (default **/package.json) does not count as registering a manifest. Each group named with\n --runtime-prefix (default runtime-) must mirror the primary group of the same name.\n\nstorybook-browser-runner --project <name> [--command <cmd>] [--result-file <path>]... [--completion-file <path>] [--coverage-arg=<arg>]... [--optimize-deps-config <path>] [--env-prefix <PREFIX>] [--progress-prefix <text>] [-- <argv>...]\n Spawns <cmd> (default pnpm) in its own process group with <argv> (default \"exec vitest run\n --project <name>\") plus the coverage args (default --coverage) and supervises it: a Vite optimizer\n cache, retries on known Vite and browser start-up flakes, and stall, hang and session-budget\n watchdogs. --result-file paths are removed before each attempt and --completion-file is the one\n whose appearance is recorded. Tuned by <PREFIX>_STARTUP_ATTEMPTS, _OPTIMIZER_STALL_MS, _HANG_MS,\n _SESSION_BUDGET_MS, _DIAGNOSTICS_FILE, _PERSISTENT_CACHE, _PERSISTENT_CACHE_DIR and _COVERAGE\n (PREFIX defaults to STORYBOOK_BROWSER). Exits with the resolved test exit code.\n\ntmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]\ntmux name [--socket PATH --pane %ID --worktree PATH] <name> | read-title | post-tool | agent-reminder <event>\n Environment: TMUX_TARGET_BIN, TMUX_TARGET_ROOT, TMUX_NAME_COMMAND, AGENT_TMUX_SOCKET/PANE/WORKTREE.\n\nstory-coverage --root <dir> --component-root <rel> --story-root <rel> --source-extension <ext> --component-extension <ext> --marker <regex> --story-pattern <regex> [--alias <prefix>=<path>] [--exclusions <json>] [--exclusions-label <text>]\n";
|
|
1
|
+
export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n runner-port-policy Print or validate a runner port policy\n with-host-lock Run a command under a host-wide lock\n host-storage Check free space on caller-supplied paths\n gha-runtime-audit Audit successful GitHub Actions job runtimes\n require-up-to-date Require HEAD to include a fetched remote branch\n fresh-base Classify the worktree against a remote base branch\n gitleaks-directory-scan Scan a directory with Gitleaks\n ast-grep-examples Run AST-grep rule examples\n ast-grep-pack Print shipped unconditional AST-grep pack paths as JSON\n gha-workspace-policy Check GitHub Actions workspace safety policy\n gha-output Write a collision-safe multiline GITHUB_OUTPUT record\n gha-needs-results Fail if required GitHub Actions job results failed\n download-with-diagnostics Download a URL and report HTTP status on failure\n download-optional-run-artifacts Download optional artifacts from the current run\n host-pressure-diagnostics Print a bounded host memory/OOM/PSI snapshot\n allocate-browser-safe-ports Allocate Fetch-safe localhost ports\n diagnose-port-collision Capture bounded localhost port diagnostics\n prepare-trivy-db Download the Trivy vulnerability database\n gha-artifacts-cleanup Delete classified GitHub Actions artifacts\n agent-issue-labels Map changed paths to labels; create missing repository labels\n http-origin Validate an optional HTTP(S) origin\n vitest-blob-manifest Stamp a vitest-blob-manifest:v1 identity file\n vitest-report-attempt Write or read a Vitest report-attempt marker\n prepare-vitest-reports Validate and select Vitest report JSON files\n pnpm-install Install a pnpm workspace with retry and release-age fail-fast\n check-cache-size Measure a path and decide whether to save a GHA cache\n make-shard-matrix Emit a [1..N] GitHub Actions shard matrix\n load-runner-env Overlay a runner env file onto GITHUB_ENV with injection guards\n clean-workspace Reset a persistent-runner workspace with a fork-PR trust gate\n install-github-release Download a checksum-verified GitHub Release binary\n run-with-timeout Run a command with GNU timeout or a Perl fallback\n lint-links Two-pass lychee: internal links fail, external warn\n materialize-pr-context Dump PR title/body/files/diff/comments and #N crawl\n wait-for-apt-locks Wait until apt/dpkg lock files are free\n install-playwright-chromium-arm64 Install Playwright Chromium from browsers.json\n ghcr-package-retention Delete old GHCR package versions (KEEP_MIN or --main-history)\n harness-admission-lane Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n harness-assert-gates Fail if any named HARNESS_*_ENABLED gate is enabled\n gha-collaborator-trust Classify authors as write-access collaborators or not\n nuget-central-version Validate a Directory.Packages.props PackageVersion delta\n verify-workflow-secrets Check a secret inventory against live repository and environment secrets\n runner-policy Check workflow runner labels and jobs against a config\n dead-code Gate unused code against a committed jscpd baseline\n swift-semantic-equal Compare Swift sources ignoring comments and whitespace\n post-review Post one COMMENT review from a staged payload file\n stage-review-payload Validate a review payload file into a staging directory\n retrospective-transcript Format facts from Claude-compatible, Codex, or Grok transcripts\n link-skill Link one packaged skill into an explicit consumer directory\n retrospective-facts Gather immutable facts for a retrospective\n agent-blackboard Probe an Agent Blackboard deployment, classify distill sessions, manage snapshots\n mcp Serve the agent-blackboard journal tools over stdio (MCP)\n hook Run a repository policy module as a pre/post tool-use hook\n worktree Reclaim finished git worktrees (dry run unless --yes)\n tmux Run configured dev windows in tmux; name panes; agent reminders\n story-coverage Check component exports are imported by stories\n transient-retry Rerun a failed GitHub Actions run when an injected rule matches\n sandbox-command-audit Audit agent transcripts for sandbox escalations and denials\n cloc Count tracked lines of code by category and service with scc\n coverage-scope-check Check positive-threshold coverage rules against the Vitest scope\n trivy-policy Check tracked Trivy workflow scans and the exception registry\n docker-image-mirror Require tracked Docker images to come from a Docker Hub mirror\n workspace-registry-check Check syncpack, pnpm workspace and CI path-filter registries against tracked manifests\n storybook-browser-runner Run the Storybook Vitest browser project with cache, retry and watchdog\n\nOptions:\n -h, --help Show this help\n -v, --version Print the package version\n\nrunner-port-policy\n (no args) Print the shipped policy as JSON\n --file <path> Validate and print a policy file\n --reserved <port> Print true if the port is reserved\n\nwith-host-lock\n --name <family>\n [--slots <n>]\n --timeout-seconds <n>\n [--command-timeout-seconds <n>]\n [--failure-diagnostics <absolute-script>]\n [--on-acquire-timeout fail|run-unlocked]\n -- <command> [args...]\n\nhost-storage --path <path> [--path <path>...] [--minimum-free-bytes <bytes>] [--pnpm-store] [--docker-root] [--docker-desktop-path <path>] [--discovery-timeout-ms <ms>]\n\ngha-runtime-audit\n [--repository owner/name] Default GITHUB_REPOSITORY\n [--branch main]\n [--median-threshold-floor <seconds>] Off unless set. Must be below the ceiling\n [--median-threshold-ceiling <seconds>] Default 360. Flags a five-sample median above this\n --pr-workflow <name|/regex/> Repeatable\n --push-workflow <name|/regex/> Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nagent-issue-labels labels-from-paths [--labeler <path>] <path>...\nagent-issue-labels ensure-labels [--repo owner/name] [--policy-file json] [--update] <label>...\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nverify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]\nrunner-policy [--config FILE] [--root DIR]\ndead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir> Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)\nagent-blackboard distill classify <partition.jsonl> --retro-cutoff ISO8601 --session-cutoff ISO8601\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n (no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,\n session_ensure, retrospective_check, retrospective_save,\n pr_validate, pr_create, pr_update,\n snapshot_export, snapshot_partition, snapshot_cleanup, and session_archive over stdio.\n Needs the optional @modelcontextprotocol/sdk peer (and zod).\n Launch it from inside the repository's git worktree.\n\nhook pre-tool-use|post-tool-use --harness claude|codex|cursor|grok --policy <module> [--root <dir>] [--automation-env NAME]...\n Reads the harness hook payload on stdin. <module> default-exports a policy object (or a function\n of the hook context returning one) with a command rule table, post-tool-use checkers, and an\n optional reminder. pre-tool-use exits 2 to block, and also when the policy cannot load.\n post-tool-use is advisory and always exits 0. --root defaults to the working directory.\n Each --automation-env NAME (repeatable) marks the run unattended when that environment variable\n is set, non-empty, and not 0 or false; CI markers and claude -p are always unattended.\n\nworktree reclaim [--yes] [--json] [--max-worktrees N] [--timeout-ms N] [--pr-limit N] [--after PATH]\n Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the\n branch is merged or closed at exactly HEAD, using git worktree remove (never forced).\n Skips the main checkout, the current worktree, and locked, bare or detached worktrees.\n\ntransient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run] <run-id>\n Loads a module exporting \"rules\" (and optionally \"limits\"), evaluates them against the failed run,\n and reruns only on a match. Exits 0 on rerun, 2 when none is warranted, 1 on error.\n\nsandbox-command-audit --rules <module> [--settings-path <file>] [--repo-root <dir>]... [--worktree-glob <glob>]... [--projects-dir <dir>] [--codex-sessions-dir <dir>] [--session-id <id>] [--limit N] [--since DAYS] [--json] [--raw]\n Scans Claude and Codex transcripts scoped to this repository (git roots plus any --worktree-glob\n layouts) and reports Bash escalations, denials and permission failures by command prefix.\n <module> exports an object (default or \"rules\") with loadPolicy({ settingsPath, cwd }), which\n returns { covers(list, commandOrPrefix) } for the allow/deny/excluded lists or { error }, and\n optionally classifyFailure(command, text, source), limits and worktreeGlobs. Transcript roots\n default to CLAUDE_CONFIG_DIR/projects and CODEX_HOME/sessions. --raw prints full command text.\n\ncloc --config <file> [--scc-bin <path>] [--json]\n Counts git-tracked lines with scc (SCC_BIN or --scc-bin, else \"scc\"), classified into\n source/tests/tooling and by service, and prints an aligned table (--json: rows). <file> is a .json\n file or a module whose default (or \"config\") export is the layout: services [{ name, match }],\n defaultService, categories, testPatterns, toolingPatterns, countedRoots, countedRootFiles,\n excludedDirs, ignoredDirs, sccBin, missingSccHint.\n\ncoverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]... [--exclude <glob>]...\n Fails (exit 1) when a git-tracked file that a coverage rules file (default .coverage-rules.yml)\n gives a patch_coverage_min above 0, and its scope does not ignore, is outside the collector's\n scope. The collector scope is the repeated --include/--exclude globs plus, optionally, the\n include/exclude string arrays of a --scope-file JSON written from the Vitest coverage config.\n At least one include glob is required.\n\ntrivy-policy [--root <dir>] [--ignore-file <path>] [--findings-exit-code-env <NAME>] [--cleanup-url-prefix <url>] [--min-gates N] [--min-sboms N] [--max-expiry-days N]\n Reads git-tracked workflows, composite actions and shell scripts and prints each violation (exit 1).\n Every Trivy package scan must be an auditable CLI run block (no action, wrapper, substitution or\n background). Vulnerability gates need --scanners vuln, --pkg-types os, --severity CRITICAL,HIGH,\n --ignore-unfixed, --skip-db-update, --quiet, table output to a file, --ignorefile <ignore-file>\n (default .trivyignore.yaml) and --exit-code \"$<NAME>\" (default TRIVY_FINDINGS_EXIT_CODE).\n CycloneDX SBOM scans must be unfiltered with --exit-code 0. At least --min-gates gates and\n --min-sboms SBOM scans (default 2 each) must exist. The tracked ignore registry needs purl-exact OS\n packages, a \"Not exploitable: ... Cleanup: <issue URL>\" statement (URL must start with\n --cleanup-url-prefix when given) and an expired_at between tomorrow and --max-expiry-days (30).\n\ndocker-image-mirror [--root <dir>] [--mirror <host>] [--allow-registry <prefix>]... [--require-digest]\n [--allow-ref-expression <text>]...\n Prints each Docker Hub image in git-tracked workflows, composite actions and Dockerfiles (exit 1):\n run, pull and create commands, containers, services, docker:// references, buildx drivers, FROM,\n COPY --from and # syntax. Images must name a registry host; --mirror (default mirror.gcr.io) is\n the host the message tells you to use. --allow-registry (repeatable) instead requires every image,\n including FROM and COPY --from, to start with one of the prefixes; a reference that expands a\n variable passes only when its literal text before the variable starts with a prefix. --require-digest\n requires @sha256: plus 64 lowercase hex characters. Stage aliases and scratch stay exempt.\n --allow-ref-expression (repeatable) is an audited escape hatch for dynamic job outputs: a reference\n whose raw text exactly equals the value is accepted. Images the same file builds locally are exempt.\n\nworkspace-registry-check [--root <dir>] [--syncpack-config <path>] [--workspace-file <path>]\n [--path-filters <path>] [--tooling-group <name>] [--trigger-only-glob <glob>] [--runtime-prefix <prefix>]\n Reconciles git-tracked package.json manifests with the syncpack \"source\" globs (default\n .syncpackrc.json), the pnpm \"packages\" globs (pnpm-workspace.yaml) and the dorny/paths-filter groups\n (.github/ci-path-filters.yml) and prints one line per violation (exit 1). The --tooling-group group\n (default tooling) must reach every manifest and wildcard workspace glob, and its --trigger-only-glob\n (default **/package.json) does not count as registering a manifest. Each group named with\n --runtime-prefix (default runtime-) must mirror the primary group of the same name.\n\nstorybook-browser-runner --project <name> [--command <cmd>] [--result-file <path>]... [--completion-file <path>] [--coverage-arg=<arg>]... [--optimize-deps-config <path>] [--env-prefix <PREFIX>] [--progress-prefix <text>] [-- <argv>...]\n Spawns <cmd> (default pnpm) in its own process group with <argv> (default \"exec vitest run\n --project <name>\") plus the coverage args (default --coverage) and supervises it: a Vite optimizer\n cache, retries on known Vite and browser start-up flakes, and stall, hang and session-budget\n watchdogs. --result-file paths are removed before each attempt and --completion-file is the one\n whose appearance is recorded. Tuned by <PREFIX>_STARTUP_ATTEMPTS, _OPTIMIZER_STALL_MS, _HANG_MS,\n _SESSION_BUDGET_MS, _DIAGNOSTICS_FILE, _PERSISTENT_CACHE, _PERSISTENT_CACHE_DIR and _COVERAGE\n (PREFIX defaults to STORYBOOK_BROWSER). Exits with the resolved test exit code.\n\ntmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]\ntmux name [--socket PATH --pane %ID --worktree PATH] <name> | read-title | post-tool | agent-reminder <event>\n Environment: TMUX_TARGET_BIN, TMUX_TARGET_ROOT, TMUX_NAME_COMMAND, AGENT_TMUX_SOCKET/PANE/WORKTREE.\n\nstory-coverage --root <dir> --component-root <rel> --story-root <rel> --source-extension <ext> --component-extension <ext> --marker <regex> --story-pattern <regex> [--alias <prefix>=<path>] [--exclusions <json>] [--exclusions-label <text>]\n";
|
package/dist/cli/usage-text.mjs
CHANGED
|
@@ -43,6 +43,7 @@ Commands:
|
|
|
43
43
|
gha-collaborator-trust Classify authors as write-access collaborators or not
|
|
44
44
|
nuget-central-version Validate a Directory.Packages.props PackageVersion delta
|
|
45
45
|
verify-workflow-secrets Check a secret inventory against live repository and environment secrets
|
|
46
|
+
runner-policy Check workflow runner labels and jobs against a config
|
|
46
47
|
dead-code Gate unused code against a committed jscpd baseline
|
|
47
48
|
swift-semantic-equal Compare Swift sources ignoring comments and whitespace
|
|
48
49
|
post-review Post one COMMENT review from a staged payload file
|
|
@@ -129,6 +130,7 @@ harness-assert-gates <gate>...
|
|
|
129
130
|
gha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json
|
|
130
131
|
nuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>
|
|
131
132
|
verify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]
|
|
133
|
+
runner-policy [--config FILE] [--root DIR]
|
|
132
134
|
dead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...
|
|
133
135
|
swift-semantic-equal <base> <head> <file.swift>
|
|
134
136
|
post-review
|
|
@@ -3,6 +3,7 @@ import type { RunTextCommand } from '../gh-cli/exec.mts';
|
|
|
3
3
|
import type { GhRunner } from './pr-gh.mts';
|
|
4
4
|
import type { PolicySpawner } from './policy-spawn.mts';
|
|
5
5
|
import { type SnapshotRegistry } from './snapshot-registry.mts';
|
|
6
|
+
import { type InstallInfo } from './install-info.mts';
|
|
6
7
|
export type ServerEnvironment = {
|
|
7
8
|
/** The launch directory's worktree top level, or undefined when it is not inside one. */
|
|
8
9
|
launchRoot: string | undefined;
|
|
@@ -25,6 +26,8 @@ export type ServerEnvironment = {
|
|
|
25
26
|
};
|
|
26
27
|
/** Test seam: a fresh registry stands in for a server restart. Defaults to the process's own. */
|
|
27
28
|
snapshots?: SnapshotRegistry;
|
|
29
|
+
/** The server's own version and install location, captured at startup. */
|
|
30
|
+
install?: InstallInfo;
|
|
28
31
|
};
|
|
29
32
|
export type ToolCallResult = {
|
|
30
33
|
content: Array<{
|
|
@@ -10,9 +10,11 @@ import { snapshotPartition } from "./handlers-snapshot-partition.mjs";
|
|
|
10
10
|
import { sessionArchive, sessionEnsure, snapshotExport } from "./handlers-session.mjs";
|
|
11
11
|
import { handlePrCreate, handlePrUpdate, handlePrValidate } from "./handlers-pr.mjs";
|
|
12
12
|
import { createSnapshotRegistry } from "./snapshot-registry.mjs";
|
|
13
|
+
import { captureInstall, installSuffix } from "./install-info.mjs";
|
|
13
14
|
import { TOOLS } from "./tools.mjs";
|
|
14
15
|
import { resolveWorktree } from "./worktree.mjs";
|
|
15
16
|
const PROCESS_SNAPSHOTS = createSnapshotRegistry();
|
|
17
|
+
const PROCESS_INSTALL = captureInstall();
|
|
16
18
|
const HANDLERS = {
|
|
17
19
|
journal_append: journalAppend,
|
|
18
20
|
journal_entries: journalEntries,
|
|
@@ -81,6 +83,10 @@ export async function callTool(name, rawArguments, environment) {
|
|
|
81
83
|
return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
|
|
82
84
|
}
|
|
83
85
|
catch (error) {
|
|
84
|
-
|
|
86
|
+
const install = environment.install ?? PROCESS_INSTALL;
|
|
87
|
+
return {
|
|
88
|
+
isError: true,
|
|
89
|
+
content: [{ type: 'text', text: describeError(error) + installSuffix(error, install) }],
|
|
90
|
+
};
|
|
85
91
|
}
|
|
86
92
|
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/** What the running server knows about its own install, captured once at startup. */
|
|
2
|
+
export type InstallInfo = {
|
|
3
|
+
name: string;
|
|
4
|
+
version: string;
|
|
5
|
+
/** Absolute path of the package directory this server was loaded from. */
|
|
6
|
+
location: string;
|
|
7
|
+
};
|
|
8
|
+
export declare function captureInstall(version?: string): InstallInfo;
|
|
9
|
+
export declare function describeInstall(install: InstallInfo): string;
|
|
10
|
+
/** The suffix appended to every tool error so a stale or swapped install is obvious. */
|
|
11
|
+
export declare function installSuffix(error: unknown, install: InstallInfo): string;
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { isAbsolute, relative, sep } from 'node:path';
|
|
2
|
+
import { fileURLToPath } from 'node:url';
|
|
3
|
+
import { readInstalledVersion } from "../cli/installed-version.mjs";
|
|
4
|
+
const PACKAGE_NAME = 'vouchington-tooling';
|
|
5
|
+
export function captureInstall(version = readInstalledVersion()) {
|
|
6
|
+
return {
|
|
7
|
+
name: PACKAGE_NAME,
|
|
8
|
+
version,
|
|
9
|
+
location: fileURLToPath(new URL('../../', import.meta.url)).replace(/\/$/, ''),
|
|
10
|
+
};
|
|
11
|
+
}
|
|
12
|
+
export function describeInstall(install) {
|
|
13
|
+
return `${install.name} ${install.version} (${install.location})`;
|
|
14
|
+
}
|
|
15
|
+
const MISSING_FILE = /ERR_MODULE_NOT_FOUND|Cannot find module|ENOENT|no such file/i;
|
|
16
|
+
/**
|
|
17
|
+
* The missing target only: the ENOENT `path`, else the first quoted specifier in the message
|
|
18
|
+
* (`Cannot find module '<x>'`, `Cannot find package '<x>'`), never the "imported from" importer.
|
|
19
|
+
*/
|
|
20
|
+
function missingTarget(error, message) {
|
|
21
|
+
const path = error?.path;
|
|
22
|
+
if (typeof path === 'string')
|
|
23
|
+
return path;
|
|
24
|
+
return /'([^']+)'/.exec(message)?.[1];
|
|
25
|
+
}
|
|
26
|
+
/** True only for a missing-file failure whose missing target is inside the server's own install. */
|
|
27
|
+
function isInstallSwapped(error, install) {
|
|
28
|
+
const code = error?.code;
|
|
29
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
30
|
+
const text = `${typeof code === 'string' ? code : ''} ${message}`;
|
|
31
|
+
if (!MISSING_FILE.test(text))
|
|
32
|
+
return false;
|
|
33
|
+
const target = missingTarget(error, message);
|
|
34
|
+
if (target === undefined || !isAbsolute(target))
|
|
35
|
+
return false;
|
|
36
|
+
const rel = relative(install.location, target);
|
|
37
|
+
return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
|
|
38
|
+
}
|
|
39
|
+
/** The suffix appended to every tool error so a stale or swapped install is obvious. */
|
|
40
|
+
export function installSuffix(error, install) {
|
|
41
|
+
const swapped = isInstallSwapped(error, install)
|
|
42
|
+
? ' The server install changed underneath it: reconnect the server (`/mcp` in Claude Code, or restart Codex).'
|
|
43
|
+
: '';
|
|
44
|
+
return `${swapped}\n[${describeInstall(install)}]`;
|
|
45
|
+
}
|
|
@@ -1,4 +1,6 @@
|
|
|
1
1
|
import type { Args } from './args.mts';
|
|
2
|
+
/** A pull request number as digits, from a digit string or a positive safe integer. */
|
|
3
|
+
export declare function prNumber(value: unknown): string | undefined;
|
|
2
4
|
/**
|
|
3
5
|
* Checks `compose.facts`: either `{ status, reason }` (unassessed) or a live collection selector,
|
|
4
6
|
* never both. Returns whether live collection was requested.
|
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
/** A plain branch name: no scheme or colon, no leading dash, no `..`. */
|
|
2
2
|
const BRANCH = /^(?!-)(?!.*\.\.)[A-Za-z0-9._/-]+$/;
|
|
3
|
+
/** A pull request number as digits, from a digit string or a positive safe integer. */
|
|
4
|
+
export function prNumber(value) {
|
|
5
|
+
if (typeof value === 'number')
|
|
6
|
+
return Number.isSafeInteger(value) && value > 0 ? String(value) : undefined;
|
|
7
|
+
return typeof value === 'string' && /^\d+$/.test(value) ? value : undefined;
|
|
8
|
+
}
|
|
3
9
|
/**
|
|
4
10
|
* Checks `compose.facts`: either `{ status, reason }` (unassessed) or a live collection selector,
|
|
5
11
|
* never both. Returns whether live collection was requested.
|
|
@@ -15,8 +21,8 @@ export function checkFactsInput(facts) {
|
|
|
15
21
|
throw new Error('compose.facts.reason requires a status');
|
|
16
22
|
// The collector trusts these types; a string "false" must not read as noPr: true.
|
|
17
23
|
// gh accepts a pull request URL for either, which would reach another repository.
|
|
18
|
-
if ('pr' in facts && (
|
|
19
|
-
throw new Error('compose.facts.pr must be a pull request number string');
|
|
24
|
+
if ('pr' in facts && prNumber(facts.pr) === undefined)
|
|
25
|
+
throw new Error('compose.facts.pr must be a pull request number (positive integer or string)');
|
|
20
26
|
if ('branch' in facts && (typeof facts.branch !== 'string' || !BRANCH.test(facts.branch)))
|
|
21
27
|
throw new Error('compose.facts.branch must be a branch name');
|
|
22
28
|
if ('noPr' in facts && typeof facts.noPr !== 'boolean')
|
|
@@ -3,7 +3,7 @@ import { rejectUnknown } from "./args.mjs";
|
|
|
3
3
|
import { inspectHarnessEnvironment, selectHarnessSession, } from "../agent-harness-identity/index.mjs";
|
|
4
4
|
import { SESSION_ID } from "../retrospective-transcript/resolve-transcript-file.mjs";
|
|
5
5
|
import { serverJournalLoader } from "./journal-read.mjs";
|
|
6
|
-
import { checkFactsInput } from "./retrospective-facts-input.mjs";
|
|
6
|
+
import { checkFactsInput, prNumber } from "./retrospective-facts-input.mjs";
|
|
7
7
|
import { spawnPolicy } from "./policy-spawn.mjs";
|
|
8
8
|
const HARNESSES = ['codex', 'claude', 'cursor', 'grok'];
|
|
9
9
|
const COMPOSE_KEYS = [
|
|
@@ -117,7 +117,11 @@ function transcriptInput(transcript, base) {
|
|
|
117
117
|
}
|
|
118
118
|
function factsInput(facts, base) {
|
|
119
119
|
return checkFactsInput(facts)
|
|
120
|
-
? {
|
|
120
|
+
? {
|
|
121
|
+
...facts,
|
|
122
|
+
...('pr' in facts ? { pr: prNumber(facts.pr) } : {}),
|
|
123
|
+
execute: worktreeExecutor(base.worktree, base.env),
|
|
124
|
+
}
|
|
121
125
|
: facts;
|
|
122
126
|
}
|
|
123
127
|
/** Builds the retrospective markdown with `composeRetrospective`, rejecting unknown input keys. */
|
package/dist/mcp-server/run.mjs
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { assertBlackboardInstalled, loadMcpSdk } from "./sdk.mjs";
|
|
2
|
+
import { captureInstall } from "./install-info.mjs";
|
|
2
3
|
import { createMcpServer } from "./server.mjs";
|
|
3
4
|
import { launchWorktreeRoot, runIsolatedGit } from "./worktree.mjs";
|
|
4
5
|
/**
|
|
@@ -15,6 +16,7 @@ export async function runMcpServer(options) {
|
|
|
15
16
|
launchRoot,
|
|
16
17
|
env: options.env,
|
|
17
18
|
runGit,
|
|
19
|
+
install: captureInstall(options.version),
|
|
18
20
|
...(options.resolveFrom === undefined ? {} : { resolveFrom: options.resolveFrom }),
|
|
19
21
|
...(options.blackboard === undefined ? {} : { blackboard: options.blackboard }),
|
|
20
22
|
};
|
|
@@ -1,2 +1,9 @@
|
|
|
1
1
|
import { type CodexSegment } from './shared.mts';
|
|
2
|
+
export type CodexSegmentOutcome = {
|
|
3
|
+
segment: CodexSegment;
|
|
4
|
+
} | {
|
|
5
|
+
reason: string;
|
|
6
|
+
};
|
|
7
|
+
/** Segments a Codex rollout, or says why its owned boundary cannot be established. */
|
|
8
|
+
export declare function explainCodexSegment(lines: string[]): CodexSegmentOutcome;
|
|
2
9
|
export declare function segmentCodex(lines: string[]): CodexSegment | undefined;
|
|
@@ -42,17 +42,18 @@ function retainHighWater(previous, current) {
|
|
|
42
42
|
cacheCreation: 0,
|
|
43
43
|
};
|
|
44
44
|
}
|
|
45
|
-
|
|
45
|
+
/** Segments a Codex rollout, or says why its owned boundary cannot be established. */
|
|
46
|
+
export function explainCodexSegment(lines) {
|
|
46
47
|
const content = lines.filter(Boolean);
|
|
47
48
|
const sessionMeta = parseLines(content.slice(0, 1))[0];
|
|
48
49
|
if (sessionMeta?.type !== 'session_meta')
|
|
49
|
-
return { lines: content, baseline: emptyTokens() };
|
|
50
|
+
return { segment: { lines: content, baseline: emptyTokens() } };
|
|
50
51
|
if (!hasInheritedParent(sessionMeta))
|
|
51
|
-
return { lines: content.slice(1), baseline: emptyTokens() };
|
|
52
|
+
return { segment: { lines: content.slice(1), baseline: emptyTokens() } };
|
|
52
53
|
const timestamp = asRecord(sessionMeta.payload)?.timestamp;
|
|
53
54
|
const timestampMs = typeof timestamp === 'string' ? Date.parse(timestamp) : Number.NaN;
|
|
54
55
|
if (!Number.isFinite(timestampMs))
|
|
55
|
-
return
|
|
56
|
+
return { reason: 'the inherited child session_meta has no valid timestamp' };
|
|
56
57
|
const ownedIndex = content.findIndex((line, index) => {
|
|
57
58
|
if (index === 0)
|
|
58
59
|
return false;
|
|
@@ -60,14 +61,17 @@ export function segmentCodex(lines) {
|
|
|
60
61
|
return record ? isOwnedTaskStart(record, timestampMs) : false;
|
|
61
62
|
});
|
|
62
63
|
if (ownedIndex === -1)
|
|
63
|
-
return
|
|
64
|
-
|
|
64
|
+
return { reason: 'no task_started at or after the child session start was recorded' };
|
|
65
|
+
// A child that inherited no token totals starts from zero, as a fresh subagent does.
|
|
66
|
+
let baseline = emptyTokens();
|
|
65
67
|
for (const record of parseLines(content.slice(1, ownedIndex))) {
|
|
66
68
|
const current = usage(record);
|
|
67
69
|
if (current)
|
|
68
|
-
baseline = retainHighWater(baseline
|
|
70
|
+
baseline = retainHighWater(baseline, current);
|
|
69
71
|
}
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
72
|
+
return { segment: { lines: content.slice(ownedIndex), baseline } };
|
|
73
|
+
}
|
|
74
|
+
export function segmentCodex(lines) {
|
|
75
|
+
const outcome = explainCodexSegment(lines);
|
|
76
|
+
return 'segment' in outcome ? outcome.segment : undefined;
|
|
73
77
|
}
|