@bensandee/tooling 0.95.0 → 0.97.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 CHANGED
@@ -719,6 +719,8 @@ serve one page and then be a dead surface whose every control did nothing.
719
719
 
720
720
  `docker:check` verifies that a Docker Compose stack starts correctly, passes health checks, and (optionally) survives a smoketest command. The lifecycle is: build images, compose up, poll health checks, run smoketest, compose down.
721
721
 
722
+ On a timeout or a failed `compose up`, `docker:check` dumps `docker compose ps -a` and every service's logs; on an unhealthy container, it dumps `docker compose ps -a` and that one service's logs. Each of the three then prints the **health log** of every service whose healthcheck has not passed: the last probe results Docker keeps, with each one's exit code and output. A probe's own output lives only there -- never in the container log -- so a healthcheck that is itself a test script fails visibly instead of ending in `(no log output)`.
723
+
722
724
  ### Smoketests
723
725
 
724
726
  A smoketest is a command that runs against the live Docker stack after all containers are healthy and HTTP health checks pass. This is useful for running integration tests, API contract checks, or any validation that requires the full stack to be running.
package/dist/bin.mjs CHANGED
@@ -11,13 +11,13 @@ import { z } from "zod";
11
11
  import JSON5 from "json5";
12
12
  import { applyEdits, modify, parse } from "jsonc-parser";
13
13
  import spawn$1 from "cross-spawn";
14
+ import os, { tmpdir } from "node:os";
15
+ import { createHmac, randomUUID } from "node:crypto";
14
16
  import { isMap, isScalar, isSeq, parse as parse$1, parseAllDocuments, parseDocument, stringify, visit } from "yaml";
15
17
  import { StringDecoder } from "node:string_decoder";
16
18
  import { parse as parse$2 } from "smol-toml";
17
19
  import picomatch from "picomatch";
18
- import os, { tmpdir } from "node:os";
19
20
  import net from "node:net";
20
- import { createHmac } from "node:crypto";
21
21
  import { fileURLToPath } from "node:url";
22
22
  //#region ../cli-kit/src/json.ts
23
23
  function resolveJsonMode(rawArgs) {
@@ -175,7 +175,7 @@ function loadEnvFileForBin(rawArgs, bin, io = processIo) {
175
175
  //#region src/env-file-preload.ts
176
176
  const envFileLoad = loadEnvFileForBin(process.argv.slice(2), {
177
177
  name: "bst",
178
- version: "0.95.0"
178
+ version: "0.97.0"
179
179
  });
180
180
  //#endregion
181
181
  //#region ../cli-kit/src/logger.ts
@@ -1747,7 +1747,8 @@ const LintSweepConfigSchema = z.strictObject({
1747
1747
  const AgentEgressConfigSchema = z.strictObject({ browseHosts: z.array(z.string().min(1)).optional().meta({ description: "Host patterns this repo's agent containers may fetch from, on top of the hosts every run needs: an exact host (`fastdl.mongodb.org`) or a wildcard over its leftmost label (`*.example.com`). No ports. These join the browse lane, which serves GET and HEAD only." }) });
1748
1748
  const AgentConfigSchema = z.strictObject({
1749
1749
  enabled: z.boolean().optional().meta({ description: "The repo's explicit consent to the agent (default false). Only `true`, read from the repo's **default branch**, lets the agent work the repo: claim units, run sweeps, recover orphans, merge, act on a chat proposal or start a new spec. A missing key, `false`, a missing `.tooling.json` or a read that fails all mean not enabled, and the answer is re-read within about a minute. Every other `agent.*` key below has no effect without this one; `repo:sync` warns when the block sets one of them and this key is not `true`. Where this is `true`, `repo:sync` also installs `@bensandee/agent-cli`. `pnpm exec bst setup:agent` sets it to true and runs the sync. Provisioning the agent's labels is not consent, and is never gated by this key." }),
1750
- autonomy: z.boolean().optional().meta({ description: "Opt into interior autonomy (default false). When a phase's latest rationale reports readiness \"ready\" with an empty openQuestions[] and the review phase is clean, the agent applies the existing plan -> implement -> review -> park-at-mergeable advance itself instead of parking for a human. Never applies to the design/spec gate or the final merge from the mergeable terminal -- those always wait on a human. Also arms the trunk-red detector: when this repo's default branch combined status settles red, the agent files a tracking issue naming the failing checks and labels it agent/spec, starting the fix through the ordinary spec/plan/implement/review pipeline. It also closes that issue, with a comment, if the default branch recovers on its own before a human acts on it. Also arms the world-changed retrigger sweep: a pull request labelled agent-flags/autopilot that is parked at a -stuck or -failed terminal is re-queued when the fact its park recorded stops being true (the default branch went green, or moved past a conflicted base)." }),
1750
+ autonomy: z.boolean().optional().meta({ description: "Retired and ignored -- it armed neither the advance rung nor the sweeps it once did. Advance is now the unit's own `agent-flags/advance` or `agent-flags/autopilot` label, and the trunk-red detector and world-changed retrigger sweep read `agent.trunkRed`. The key is still accepted so an existing config keeps syncing; the agent warns once per launch for a repo that still sets it." }),
1751
+ trunkRed: z.boolean().optional().meta({ description: "Whether this repo's trunk-red detector and world-changed retrigger sweep run (default: on). The detector files a tracking issue when the default branch's combined status settles red and labels it agent/spec, and closes that issue with a comment if the branch recovers on its own before a human acts on it. The retrigger sweep re-queues a pull request labelled agent-flags/autopilot parked at a -stuck or -failed terminal when the fact its park recorded stops being true (the default branch went green, or moved past a conflicted base). A missing key means on; false disarms both." }),
1751
1752
  preRunRebase: z.boolean().optional().meta({ description: "Merge the current default branch into the work branch before the container starts (default true) -- for an implement (execute) run, and for a spec or plan rerun on an existing branch. A clean merge or an already-up-to-date branch runs the container as is; a conflicting merge is aborted, recorded on the run's status comment, and the run proceeds on the un-synced branch -- a conflict, timeout or failed merge never fails the run, for any phase. Only the execute phase keeps the two-strike rule: two consecutive conflicting attempts hand the unit to agent/repair before any container runs, while a docs run just tries again on its next slice. Set false to skip the attempt entirely for this repo, in every phase: no fetch, no merge, no abort, and the branch is worked exactly as cloned." }),
1752
1753
  backlog: z.boolean().optional().meta({ description: "Whether the agent may self-trigger backlog runs consuming this repo's .agent/findings/ ledger (default: on wherever the ledger exists, which only happens in a repo whose own review loop wrote it). A backlog run opens a pull request that fixes or refutes the pending findings; false disarms it, leaving the ledger to accumulate for a human. A run starts only once at least three findings are pending or one is older than seven days." }),
1753
1754
  lintSweep: LintSweepConfigSchema.optional().meta({ description: "The lint-warning sweep: a periodic agent job that measures this repo's oxlint warnings on its default branch in a container and, past minWarnings, opens a pull request carrying a generated plan for an agent/implement run to work off." }),
@@ -1829,7 +1830,7 @@ const ToolingConfigSchema = z.strictObject({
1829
1830
  ]).optional().meta({ description: "What compiles the project. Detected from the package.json build script, then config-file presence. Setting this key pins its value, even one that equals detection, and repo:sync keeps it until the key is deleted." }),
1830
1831
  checks: ChecksConfigSchema.optional().meta({ description: "Check-pipeline overrides: extra steps to add, and steps to skip (unioned with CI defaults)." }),
1831
1832
  lint: LintConfigSchema.optional().meta({ description: "bst lint:types (the type-aware oxlint gate) overrides. See lint.strictTypeAware." }),
1832
- agent: AgentConfigSchema.optional().meta({ description: "agent:start behaviour overrides. Opt-in: see agent.autonomy for the interior-autonomy gate." }),
1833
+ agent: AgentConfigSchema.optional().meta({ description: "agent:start behaviour overrides. Opt-in: agent.enabled is the consent gate -- every other key in the block does nothing without it." }),
1833
1834
  branchPrune: BranchPruneConfigSchema.optional().meta({ description: "bst branch:prune overrides: mergedDays/backupDays windows, and extra never-touch exclusions layered on top of the hard-coded list." }),
1834
1835
  issues: IssuesConfigSchema.optional().meta({ description: "Repo-level issue policy -- currently just the default reviewer(s) `bst issue:create` assigns. The natural home for any future issue-policy key." })
1835
1836
  });
@@ -2246,6 +2247,55 @@ function loadRegistryHostOverride(cwd) {
2246
2247
  }
2247
2248
  }
2248
2249
  //#endregion
2250
+ //#region src/release/docker-bake.ts
2251
+ function uniqueTargetName(taken, imageName) {
2252
+ const root = imageName.replace(/[^A-Za-z0-9_-]/gu, "_");
2253
+ const candidate = (suffix) => suffix === 1 ? root : `${root}_${String(suffix)}`;
2254
+ let suffix = 1;
2255
+ while (taken.has(candidate(suffix))) suffix++;
2256
+ return candidate(suffix);
2257
+ }
2258
+ function buildBakeDefinition(images) {
2259
+ const targetByImageName = /* @__PURE__ */ new Map();
2260
+ const takenTargetNames = /* @__PURE__ */ new Set();
2261
+ const named = [];
2262
+ for (const image of images) {
2263
+ const target = uniqueTargetName(takenTargetNames, image.imageName);
2264
+ takenTargetNames.add(target);
2265
+ targetByImageName.set(image.imageName, target);
2266
+ named.push({
2267
+ image,
2268
+ target
2269
+ });
2270
+ }
2271
+ const target = {};
2272
+ const targets = [];
2273
+ for (const { image, target: name } of named) {
2274
+ const entry = {
2275
+ context: image.context,
2276
+ dockerfile: image.dockerfile,
2277
+ tags: [`${image.imageName}:latest`],
2278
+ args: image.args,
2279
+ labels: image.labels
2280
+ };
2281
+ if (image.bases.length > 0) {
2282
+ const contexts = {};
2283
+ for (const base of image.bases) {
2284
+ const baseTarget = targetByImageName.get(base);
2285
+ if (baseTarget === void 0) throw new UnexpectedError(`Docker bake definition: image "${image.imageName}" FROMs "${base}", which is not in the set of images being built`);
2286
+ contexts[base] = `target:${baseTarget}`;
2287
+ }
2288
+ entry.contexts = contexts;
2289
+ }
2290
+ target[name] = entry;
2291
+ targets.push(name);
2292
+ }
2293
+ return {
2294
+ group: { default: { targets } },
2295
+ target
2296
+ };
2297
+ }
2298
+ //#endregion
2249
2299
  //#region src/utils/debug.ts
2250
2300
  const verboseLogger = createLogger({ level: "trace" });
2251
2301
  function isEnvVerbose() {
@@ -2613,6 +2663,13 @@ function resolveComposeFileSet(readFile, projectRoot, composeFiles) {
2613
2663
  //#endregion
2614
2664
  //#region ../forgejo/src/fetcher.ts
2615
2665
  const LONG_FETCH_TIMEOUT_MS = 6e5;
2666
+ function morePagesFollow(res, pageLength, received, pageSize) {
2667
+ if (pageLength === 0) return false;
2668
+ const raw = res.headers.get("x-total-count")?.trim() ?? "";
2669
+ const total = raw === "" ? NaN : Number(raw);
2670
+ if (!Number.isSafeInteger(total) || total < 0) return pageLength >= pageSize;
2671
+ return received < total;
2672
+ }
2616
2673
  //#endregion
2617
2674
  //#region ../forgejo/src/fetch-retry.ts
2618
2675
  const DEFAULT_RETRY_POLICY = {
@@ -3676,17 +3733,28 @@ function extractFromRefs(dockerfileContent) {
3676
3733
  }
3677
3734
  return refs;
3678
3735
  }
3736
+ function localBaseImages(packages, executor, cwd) {
3737
+ const imageNames = new Set(packages.map((pkg) => pkg.imageName));
3738
+ const basesByImageName = /* @__PURE__ */ new Map();
3739
+ for (const pkg of packages) {
3740
+ const content = executor.readFile(path.join(cwd, pkg.docker.dockerfile));
3741
+ const bases = [];
3742
+ if (content !== null) {
3743
+ for (const ref of extractFromRefs(content)) if (ref !== pkg.imageName && imageNames.has(ref) && !bases.includes(ref)) bases.push(ref);
3744
+ }
3745
+ basesByImageName.set(pkg.imageName, bases);
3746
+ }
3747
+ return basesByImageName;
3748
+ }
3679
3749
  function sortPackagesByDependency(packages, executor, cwd) {
3680
3750
  const indexByImageName = new Map(packages.map((pkg, index) => [pkg.imageName, index]));
3751
+ const basesByImageName = localBaseImages(packages, executor, cwd);
3681
3752
  const dependencyIndexes = [];
3682
- for (let selfIndex = 0; selfIndex < packages.length; selfIndex++) {
3683
- const pkg = packages[selfIndex];
3684
- if (pkg === void 0) continue;
3685
- const content = executor.readFile(path.join(cwd, pkg.docker.dockerfile));
3753
+ for (const pkg of packages) {
3686
3754
  const deps = [];
3687
- if (content !== null) for (const ref of extractFromRefs(content)) {
3688
- const depIndex = indexByImageName.get(ref);
3689
- if (depIndex !== void 0 && depIndex !== selfIndex) deps.push(depIndex);
3755
+ for (const base of basesByImageName.get(pkg.imageName) ?? []) {
3756
+ const depIndex = indexByImageName.get(base);
3757
+ if (depIndex !== void 0) deps.push(depIndex);
3690
3758
  }
3691
3759
  dependencyIndexes.push(deps);
3692
3760
  }
@@ -3829,18 +3897,15 @@ function interpolate(value, env, onMissing) {
3829
3897
  }
3830
3898
  function resolveBuildArgs(pkg, env) {
3831
3899
  const entries = Object.entries(pkg.docker.buildArgs ?? {});
3832
- if (entries.length === 0) return [];
3900
+ if (entries.length === 0) return {};
3833
3901
  const warned = /* @__PURE__ */ new Set();
3834
- const pairs = [];
3835
- for (const [k, rawValue] of entries) {
3836
- const resolved = interpolate(rawValue, env, (missing) => {
3837
- if (warned.has(missing)) return;
3838
- warned.add(missing);
3839
- log$1.warn(`docker build arg "${k}" for ${pkg.dir}: env var ${missing} is not set; using empty string`);
3840
- });
3841
- pairs.push(`${k}=${resolved}`);
3842
- }
3843
- return pairs;
3902
+ const args = {};
3903
+ for (const [k, rawValue] of entries) args[k] = interpolate(rawValue, env, (missing) => {
3904
+ if (warned.has(missing)) return;
3905
+ warned.add(missing);
3906
+ log$1.warn(`docker build arg "${k}" for ${pkg.dir}: env var ${missing} is not set; using empty string`);
3907
+ });
3908
+ return args;
3844
3909
  }
3845
3910
  const IMAGE_REVISION_LABEL = "org.opencontainers.image.revision";
3846
3911
  const IMAGE_VERSION_LABEL = "org.opencontainers.image.version";
@@ -3848,14 +3913,14 @@ const IMAGE_CONTEXT_TREE_LABEL = "com.bensandee.tooling.context-tree";
3848
3913
  function resolveProvenanceLabels(executor, cwd, contextRelPath) {
3849
3914
  const headResult = executor.exec("git", ["rev-parse", "HEAD"], { cwd });
3850
3915
  const revision = headResult.stdout.trim();
3851
- if (headResult.exitCode !== 0 || revision === "") return [];
3916
+ if (headResult.exitCode !== 0 || revision === "") return {};
3852
3917
  const prefixResult = executor.exec("git", ["rev-parse", "--show-prefix"], { cwd });
3853
- if (prefixResult.exitCode !== 0) return [];
3918
+ if (prefixResult.exitCode !== 0) return {};
3854
3919
  const contextFromRoot = [prefixResult.stdout.trim().replace(/\/$/, ""), path.relative(cwd, path.resolve(cwd, contextRelPath)).split(path.sep).join("/")].filter((part) => part !== "").join("/");
3855
3920
  const treeTarget = contextFromRoot === "" ? "HEAD^{tree}" : `HEAD:${contextFromRoot}`;
3856
3921
  const treeResult = executor.exec("git", ["rev-parse", treeTarget], { cwd });
3857
3922
  const tree = treeResult.stdout.trim();
3858
- if (treeResult.exitCode !== 0 || tree === "") return [];
3923
+ if (treeResult.exitCode !== 0 || tree === "") return {};
3859
3924
  const statusResult = executor.exec("git", [
3860
3925
  "status",
3861
3926
  "--porcelain",
@@ -3863,22 +3928,24 @@ function resolveProvenanceLabels(executor, cwd, contextRelPath) {
3863
3928
  contextRelPath
3864
3929
  ], { cwd });
3865
3930
  const dirty = statusResult.exitCode === 0 && statusResult.stdout.trim() !== "";
3866
- return [
3867
- "--label",
3868
- `${IMAGE_REVISION_LABEL}=${revision}`,
3869
- "--label",
3870
- `${IMAGE_CONTEXT_TREE_LABEL}=${tree}${dirty ? "-dirty" : ""}`
3871
- ];
3931
+ return {
3932
+ [IMAGE_REVISION_LABEL]: revision,
3933
+ [IMAGE_CONTEXT_TREE_LABEL]: `${tree}${dirty ? "-dirty" : ""}`
3934
+ };
3935
+ }
3936
+ function resolveImageLabels(executor, pkg, cwd) {
3937
+ const labels = resolveProvenanceLabels(executor, cwd, pkg.docker.context);
3938
+ if (pkg.version) labels[IMAGE_VERSION_LABEL] = pkg.version;
3939
+ return labels;
3872
3940
  }
3873
3941
  function buildImage(executor, pkg, cwd, extraArgs) {
3874
3942
  const dockerfilePath = path.resolve(cwd, pkg.docker.dockerfile);
3875
3943
  const contextPath = path.resolve(cwd, pkg.docker.context);
3876
- const configuredPairs = resolveBuildArgs(pkg, process.env);
3877
- log$1.info(` build args: ${configuredPairs.length > 0 ? configuredPairs.join(" ") : "(none)"}`);
3944
+ const pairs = Object.entries(resolveBuildArgs(pkg, process.env)).map(([key, value]) => `${key}=${value}`);
3945
+ log$1.info(` build args: ${pairs.length > 0 ? pairs.join(" ") : "(none)"}`);
3878
3946
  log$1.info(` extra args: ${extraArgs.length > 0 ? extraArgs.join(" ") : "(none)"}`);
3879
- const buildArgFlags = configuredPairs.flatMap((pair) => ["--build-arg", pair]);
3880
- const provenanceLabels = resolveProvenanceLabels(executor, cwd, pkg.docker.context);
3881
- const versionLabel = pkg.version ? ["--label", `${IMAGE_VERSION_LABEL}=${pkg.version}`] : [];
3947
+ const buildArgFlags = pairs.flatMap((pair) => ["--build-arg", pair]);
3948
+ const labelFlags = Object.entries(resolveImageLabels(executor, pkg, cwd)).flatMap(([key, value]) => ["--label", `${key}=${value}`]);
3882
3949
  executor.execInherit("docker", [
3883
3950
  "build",
3884
3951
  "-f",
@@ -3886,12 +3953,46 @@ function buildImage(executor, pkg, cwd, extraArgs) {
3886
3953
  "-t",
3887
3954
  `${pkg.imageName}:latest`,
3888
3955
  ...buildArgFlags,
3889
- ...provenanceLabels,
3890
- ...versionLabel,
3956
+ ...labelFlags,
3891
3957
  ...extraArgs,
3892
3958
  contextPath
3893
3959
  ]);
3894
3960
  }
3961
+ function bakeImages(executor, packages, config) {
3962
+ const cwd = config.cwd;
3963
+ const basesByImageName = localBaseImages(packages, executor, cwd);
3964
+ const images = [];
3965
+ for (const pkg of packages) {
3966
+ log$1.info(`Building image for ${pkg.dir} (${pkg.imageName}:latest)...`);
3967
+ debug(config, `Dockerfile: ${pkg.docker.dockerfile}, context: ${pkg.docker.context}`);
3968
+ const buildArgs = resolveBuildArgs(pkg, process.env);
3969
+ const pairs = Object.entries(buildArgs).map(([key, value]) => `${key}=${value}`);
3970
+ log$1.info(` build args: ${pairs.length > 0 ? pairs.join(" ") : "(none)"}`);
3971
+ images.push({
3972
+ imageName: pkg.imageName,
3973
+ dockerfile: path.resolve(cwd, pkg.docker.dockerfile),
3974
+ context: path.resolve(cwd, pkg.docker.context),
3975
+ args: buildArgs,
3976
+ labels: resolveImageLabels(executor, pkg, cwd),
3977
+ bases: basesByImageName.get(pkg.imageName) ?? []
3978
+ });
3979
+ }
3980
+ const definitionDir = path.join(os.tmpdir(), `bst-docker-bake-${randomUUID()}`);
3981
+ const definitionPath = path.join(definitionDir, "docker-bake.json");
3982
+ executor.makeDir(definitionDir);
3983
+ try {
3984
+ executor.writeFile(definitionPath, JSON.stringify(buildBakeDefinition(images)));
3985
+ executor.execInherit("docker", [
3986
+ "buildx",
3987
+ "bake",
3988
+ "--file",
3989
+ definitionPath,
3990
+ "--load"
3991
+ ], { cwd });
3992
+ } finally {
3993
+ executor.removeDir(definitionDir);
3994
+ }
3995
+ }
3895
3996
  function runDockerBuild(executor, config) {
3896
3997
  const repoName = readRepoName(executor, config.cwd);
3897
3998
  if (config.packageDir) {
@@ -3908,7 +4009,16 @@ function runDockerBuild(executor, config) {
3908
4009
  return { packages: [] };
3909
4010
  }
3910
4011
  log$1.info(`Found ${String(packages.length)} Docker package(s): ${packages.map((p) => p.dir).join(", ")}`);
3911
- for (const pkg of packages) {
4012
+ let useBake = true;
4013
+ if (config.extraArgs.length > 0) {
4014
+ log$1.info("Building one image at a time: the extra arguments go to `docker build`, and bake does not take them.");
4015
+ useBake = false;
4016
+ } else if (executor.exec("docker", ["buildx", "version"]).exitCode !== 0) {
4017
+ log$1.info("Building one image at a time: `docker buildx` is not available on this host.");
4018
+ useBake = false;
4019
+ }
4020
+ if (useBake) bakeImages(executor, packages, config);
4021
+ else for (const pkg of packages) {
3912
4022
  log$1.info(`Building image for ${pkg.dir} (${pkg.imageName}:latest)...`);
3913
4023
  debug(config, `Dockerfile: ${pkg.docker.dockerfile}, context: ${pkg.docker.context}`);
3914
4024
  buildImage(executor, pkg, config.cwd, config.extraArgs);
@@ -5524,7 +5634,7 @@ function buildManagedDevDeps(ctx) {
5524
5634
  const devDeps = { ...rootDevDeps(ctx.config) };
5525
5635
  if (!isMonorepo) Object.assign(devDeps, perPackageDevDeps(ctx.config));
5526
5636
  if (ctx.config.stack !== "none") devDeps["@bensandee/config"] = isWorkspacePackage(ctx, "@bensandee/config") ? "workspace:*" : "0.15.0";
5527
- if (!isWorkspacePackage(ctx, "@bensandee/tooling")) devDeps["@bensandee/tooling"] = "0.95.0";
5637
+ if (!isWorkspacePackage(ctx, "@bensandee/tooling")) devDeps["@bensandee/tooling"] = "0.97.0";
5528
5638
  if (ctx.config.useEslintPlugin && ctx.config.stack !== "none") devDeps["@bensandee/eslint-plugin"] = isWorkspacePackage(ctx, "@bensandee/eslint-plugin") ? "workspace:*" : "0.17.0";
5529
5639
  if (wantsAgentCli(ctx)) devDeps[AGENT_CLI_PACKAGE] = "0.1.3";
5530
5640
  if (ctx.config.formatter === "oxfmt") devDeps["oxfmt"] = {
@@ -9448,7 +9558,7 @@ const GIT_GUIDE_BODY = [
9448
9558
  "",
9449
9559
  "## Claiming work by hand",
9450
9560
  "",
9451
- "If the bst agent drives this repo, claim an issue or pull request before you work it by hand, so the agent does not start a run beside you: run `pnpm exec bst work:start <n>`. It prints the same orientation `work:status` does and then puts `agent-flags/hand-authored` on the object. It claims only where the repo's default branch sets `agent.enabled: true`, and does nothing anywhere else. **Exit 1 means do not start**: a run is live on the pair, or the agent holds it -- the output names which. Exit 0 means the pair is yours, whether the command wrote the flag or found it there already.",
9561
+ "If the bst agent drives this repo, claim an issue or pull request before you work it by hand, so the agent does not start a run beside you: run `pnpm exec bst work:start <n>`. It prints the same orientation `work:status` does and then puts `agent-flags/hand-authored` on the object. It claims only where the repo's default branch sets `agent.enabled: true`, and does nothing anywhere else. **Exit 1 means do not start**: a run is live on the pair, or one is queued on it -- the output names which. An object the agent parked at a terminal such as `agent/implement-blocked` is claimed, since nothing runs there until a person acts. Exit 0 means the pair is yours, whether the command wrote the flag or found it there already.",
9452
9562
  "",
9453
9563
  "The flag records who is working an object now, not who wrote it. Do not claim an issue or pull request you only file or open for later, even one a person or a coding session wrote by hand: leave it unclaimed so the agent can take it if asked. Claim it when you are about to work it.",
9454
9564
  "",
@@ -9535,11 +9645,12 @@ const PLANNING_GUIDE_BODY = [
9535
9645
  "",
9536
9646
  "## Working through a plan",
9537
9647
  "",
9538
- `Do the tasks in order, commit after each, and tick a box only once its result is verified. Each task starts red -- write its test, watch it fail, make it pass -- and its commit body carries the testing guide's \`${TEST_EVIDENCE_PREFIXES.red}\` or \`${TEST_EVIDENCE_PREFIXES.noTest}\` line. A box you cannot finish keeps its text exactly as written and gets one note underneath:`,
9648
+ `Do the tasks in order, commit after each, and tick a box only once its result is verified. Each task starts red -- write its test, watch it fail, make it pass -- and its commit body carries the testing guide's \`${TEST_EVIDENCE_PREFIXES.red}\` or \`${TEST_EVIDENCE_PREFIXES.noTest}\` line. A box you cannot finish, or cannot finish in full, keeps its text exactly as written and gets one of four notes underneath:`,
9539
9649
  "",
9540
9650
  "- `**Progress:**` -- partly done: what landed, what remains, where to pick up. The next pass resumes it.",
9541
9651
  "- `**Blocked:**` -- tried and failing: the error. The next pass retries it.",
9542
9652
  "- `**Declined:**` -- must not be done, with the reason: a standing rule, a repo convention, or a check that found it moot. No pass touches it again. \"Too hard\" or \"out of budget\" is Progress, not Declined.",
9653
+ "- `**Deferred:** Task <n> -- <reason>` -- part of the box waits on a later task. Split that box first, so the work that waits is a box of its own, and defer only that one; deferring the whole box drops the part that does not wait. The note says which task and what in it the box waits on, both on that one line. The same plan-only commit adds `- [ ] **Carried from Task <source>:** <the work>` to that task, which is the work going on there; the target cannot be the retire task. The deferral then resolves the box: it says \"later\", not \"never\". With no carried box in the target, nothing is deferred and the box stays outstanding, counted against every later pass.",
9543
9654
  "",
9544
9655
  "To run a plan through subagents, see the subagents guide."
9545
9656
  ].join("\n");
@@ -10163,7 +10274,7 @@ function reportFailures(failed, command) {
10163
10274
  function generateMigratePrompt(results, config, detected) {
10164
10275
  const sections = [];
10165
10276
  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
10166
- sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.95.0 repo:sync\` on ${timestamp}_\n`);
10277
+ sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.97.0 repo:sync\` on ${timestamp}_\n`);
10167
10278
  const changed = results.filter((r) => r.action === "created" || r.action === "updated" || r.action === "archived");
10168
10279
  if (changed.length > 0) {
10169
10280
  const items = changed.map((r) => {
@@ -14139,7 +14250,7 @@ const LabelSchema$1 = z.object({
14139
14250
  exclusive: z.boolean().optional()
14140
14251
  });
14141
14252
  const LabelListSchema = z.array(LabelSchema$1);
14142
- const LABELS_PAGE_SIZE = 100;
14253
+ const LABELS_PAGE_SIZE = 50;
14143
14254
  const LABELS_MAX_PAGES = 20;
14144
14255
  async function fetchAllForgejoLabels(executor, conn) {
14145
14256
  const labels = [];
@@ -14152,7 +14263,7 @@ async function fetchAllForgejoLabels(executor, conn) {
14152
14263
  const parsed = LabelListSchema.safeParse(await res.json());
14153
14264
  if (!parsed.success) throw new UnexpectedError(`Unexpected label-list response: ${parsed.error.message}`);
14154
14265
  labels.push(...parsed.data);
14155
- if (parsed.data.length < LABELS_PAGE_SIZE) break;
14266
+ if (!morePagesFollow(res, parsed.data.length, labels.length, LABELS_PAGE_SIZE)) break;
14156
14267
  }
14157
14268
  return labels;
14158
14269
  }
@@ -14276,7 +14387,7 @@ async function listForgejoComments(executor, conn, number, options = {}) {
14276
14387
  }, issueNotFoundMessage(conn, number));
14277
14388
  const parsed = parseCommentListOrThrow(await res.json());
14278
14389
  comments.push(...parsed.map(normalizeComment));
14279
- if (parsed.length < COMMENTS_PAGE_SIZE) break;
14390
+ if (!morePagesFollow(res, parsed.length, comments.length, COMMENTS_PAGE_SIZE)) break;
14280
14391
  if (page === COMMENTS_MAX_PAGES) {
14281
14392
  log.warn(`Comment listing for #${String(number)} hit the ${String(COMMENTS_MAX_PAGES)}-page cap; results may be truncated`);
14282
14393
  options.onPageCap?.();
@@ -14392,7 +14503,10 @@ async function fetchIssueListPage(executor, conn, params) {
14392
14503
  verb: "list issues",
14393
14504
  resource: conn.repository
14394
14505
  }, repoNotFoundMessage(conn));
14395
- return parseIssueListOrThrow(await res.json());
14506
+ return {
14507
+ raw: parseIssueListOrThrow(await res.json()),
14508
+ res
14509
+ };
14396
14510
  }
14397
14511
  function normalizeDetailedIssues(raw, type) {
14398
14512
  const normalized = raw.map(normalizeIssue);
@@ -14403,7 +14517,7 @@ const DETAILED_LIST_MAX_PAGES = 20;
14403
14517
  async function listForgejoIssuesDetailedPaged(executor, conn, query, options) {
14404
14518
  const issues = [];
14405
14519
  for (let page = 1; page <= DETAILED_LIST_MAX_PAGES; page++) {
14406
- const raw = await fetchIssueListPage(executor, conn, issueListParams(query.type, {
14520
+ const { raw } = await fetchIssueListPage(executor, conn, issueListParams(query.type, {
14407
14521
  ...query,
14408
14522
  limit: DETAILED_LIST_PAGE_SIZE,
14409
14523
  page
@@ -14779,6 +14893,7 @@ function groupLabels(names, descriptions) {
14779
14893
  return groups;
14780
14894
  }
14781
14895
  const RUNNING_LABEL = /^agent\/[a-z-]+-running$/;
14896
+ const QUEUED_LABEL = /^agent\/[a-z]+$/;
14782
14897
  const HAND_AUTHORED_LABEL = "agent-flags/hand-authored";
14783
14898
  function liftedFacts(names) {
14784
14899
  return {
@@ -14797,20 +14912,26 @@ function ownerOf(names) {
14797
14912
  if (running !== void 0) return {
14798
14913
  owner: "agent",
14799
14914
  label: running,
14800
- running: true
14915
+ hold: "running"
14801
14916
  };
14802
14917
  if (names.includes("agent-flags/hand-authored")) return { owner: "person" };
14803
- const held = agent[0];
14804
- if (held !== void 0) return {
14918
+ const queued = agent.find((name) => QUEUED_LABEL.test(name));
14919
+ if (queued !== void 0) return {
14805
14920
  owner: "agent",
14806
- label: held,
14807
- running: false
14921
+ label: queued,
14922
+ hold: "queued"
14923
+ };
14924
+ const parked = agent[0];
14925
+ if (parked !== void 0) return {
14926
+ owner: "agent",
14927
+ label: parked,
14928
+ hold: "parked"
14808
14929
  };
14809
14930
  return { owner: "unclaimed" };
14810
14931
  }
14811
14932
  //#endregion
14812
14933
  //#region src/work-status/claim.ts
14813
- const HANDOVER_ROUTES = "Claim it from the control panel's \"Claim for hand work\", or remove the agent label by hand and run pnpm exec bst work:start again.";
14934
+ const HANDOVER_ROUTES = "Claim it from the control panel's \"Claim for hand work\", which strips the trigger, or remove the agent label by hand and run pnpm exec bst work:start again.";
14814
14935
  function decideClaim(report, enabled) {
14815
14936
  if (!enabled) return {
14816
14937
  kind: "answer",
@@ -14843,7 +14964,7 @@ function decideClaim(report, enabled) {
14843
14964
  exitCode: 0,
14844
14965
  result: { outcome: "already-claimed" }
14845
14966
  };
14846
- if (held.kind === "agent") return {
14967
+ if (held.kind === "agent" && held.hold !== "parked") return {
14847
14968
  kind: "answer",
14848
14969
  exitCode: 1,
14849
14970
  result: {
@@ -14852,17 +14973,26 @@ function decideClaim(report, enabled) {
14852
14973
  reason: `The agent holds this object (${held.label}). ${HANDOVER_ROUTES}`
14853
14974
  }
14854
14975
  };
14976
+ if (held.kind === "agent" && report.runLive === null) return {
14977
+ kind: "answer",
14978
+ exitCode: 1,
14979
+ result: {
14980
+ outcome: "failed",
14981
+ reason: `A label read failed, so a run may be live or queued beside ${held.label} unseen. Nothing was claimed; retry once the forge read works.`
14982
+ }
14983
+ };
14855
14984
  return { kind: "write" };
14856
14985
  }
14857
14986
  function ownershipOf(report) {
14858
14987
  if (report.labels.state === "ok") {
14859
14988
  const ownership = ownerOf(labelNamesOf(report.labels));
14860
- if (ownership.owner === "agent") return ownership.running ? {
14989
+ if (ownership.owner === "agent") return ownership.hold === "running" ? {
14861
14990
  kind: "running",
14862
14991
  label: ownership.label
14863
14992
  } : {
14864
14993
  kind: "agent",
14865
- label: ownership.label
14994
+ label: ownership.label,
14995
+ hold: ownership.hold
14866
14996
  };
14867
14997
  if (ownership.owner === "person") return { kind: "person" };
14868
14998
  return { kind: "unclaimed" };
@@ -14871,7 +15001,8 @@ function ownershipOf(report) {
14871
15001
  const live = report.runLive?.[0];
14872
15002
  return live === void 0 ? {
14873
15003
  kind: "agent",
14874
- label: "an agent label"
15004
+ label: "an agent label",
15005
+ hold: "unread"
14875
15006
  } : {
14876
15007
  kind: "running",
14877
15008
  label: live
@@ -16452,7 +16583,17 @@ const INVISIBLE_OFFENDERS = [
16452
16583
  char: "ᅠ",
16453
16584
  group: "invisible"
16454
16585
  },
16455
- ...rangeOffenders(917504, 917631, "TAG CHARACTER", "invisible")
16586
+ ...rangeOffenders(917504, 917631, "TAG CHARACTER", "invisible"),
16587
+ ...rangeOffenders(0, 8, "C0 CONTROL", "invisible"),
16588
+ ...rangeOffenders(11, 12, "C0 CONTROL", "invisible"),
16589
+ ...rangeOffenders(14, 31, "C0 CONTROL", "invisible"),
16590
+ {
16591
+ codepoint: "U+007F",
16592
+ name: "DELETE",
16593
+ tier: 1,
16594
+ char: "",
16595
+ group: "invisible"
16596
+ }
16456
16597
  ];
16457
16598
  const SCRIPT_DEPENDENT_OFFENDERS = [
16458
16599
  {
@@ -18316,22 +18457,90 @@ function taskLabelId(text) {
18316
18457
  return `${digits}${match?.[2] ?? ""}`;
18317
18458
  }
18318
18459
  //#endregion
18460
+ //#region src/plan-workspace/plan-units.ts
18461
+ const AFTER_LABEL = /^[ \t]*(?::|\.|--?)?[ \t]*/;
18462
+ function planTask(headingText, label) {
18463
+ const unwrapped = headingText.replace(/^(\*\*|__)/, "").replace(/(\*\*|__)$/, "");
18464
+ return {
18465
+ label,
18466
+ title: unwrapped.slice(unwrapped.indexOf(label) + label.length).replace(AFTER_LABEL, "").trim()
18467
+ };
18468
+ }
18469
+ function groupPlanUnits(text, boxes) {
18470
+ const lines = text.split("\n");
18471
+ const fenced = fencedLines(lines);
18472
+ const boxAtLine = /* @__PURE__ */ new Map();
18473
+ for (const box of boxes) boxAtLine.set(box.line, box);
18474
+ const units = [];
18475
+ const open = [];
18476
+ for (const [index, rawLine] of lines.entries()) {
18477
+ if (fenced[index] === true) continue;
18478
+ const line = rawLine ?? "";
18479
+ const heading = HEADING.exec(line);
18480
+ if (heading !== null) {
18481
+ const level = (heading[1] ?? "").length;
18482
+ while (open.length > 0 && (open[open.length - 1]?.level ?? 0) >= level) open.pop();
18483
+ const headingText = (heading[2] ?? "").trim();
18484
+ const label = taskLabelId(headingText);
18485
+ if (label === null) continue;
18486
+ const unit = {
18487
+ key: headingText,
18488
+ task: planTask(headingText, label),
18489
+ boxes: []
18490
+ };
18491
+ units.push(unit);
18492
+ open.push({
18493
+ level,
18494
+ unit
18495
+ });
18496
+ continue;
18497
+ }
18498
+ const box = boxAtLine.get(index);
18499
+ if (box === void 0) continue;
18500
+ const section = open[open.length - 1];
18501
+ if (section !== void 0) {
18502
+ section.unit.boxes.push(box);
18503
+ continue;
18504
+ }
18505
+ units.push({
18506
+ key: box.title,
18507
+ task: null,
18508
+ boxes: [box]
18509
+ });
18510
+ }
18511
+ return units;
18512
+ }
18513
+ //#endregion
18319
18514
  //#region src/plan-workspace/plan-boxes.ts
18320
18515
  const BOX_LINE_REGEX = /^[ \t]*[-*] \[([ xX])\][ \t]*(.*)$/;
18321
18516
  const HEADING_REGEX = /^#{1,6} /;
18322
18517
  const DECLINED_LINE_REGEX = /^[ \t]*(?:[-*][ \t]+)?\*\*Declined:\*\*[ \t]*(.*)$/;
18323
- const NOTE_LINE_REGEX = /^[ \t]*(?:[-*][ \t]+)?\*\*(Progress|Blocked|Declined):\*\*[ \t]*(.*)$/;
18518
+ const NOTE_LINE_REGEX = /^[ \t]*(?:[-*][ \t]+)?\*\*(Progress|Blocked|Declined|Deferred):\*\*[ \t]*(.*)$/;
18519
+ const DEFERRED_LINE_REGEX = /^[ \t]*(?:[-*][ \t]+)?\*\*Deferred:\*\*[ \t]*(.*)$/;
18520
+ const DEFERRAL_SEPARATOR_REGEX = /^[ \t]*(?::|\.|--|-)?[ \t]*/;
18324
18521
  const RETIRE_TASK_REGEX = /^(?:\*\*|__)?Retire this plan(?![A-Za-z0-9])/;
18522
+ function describeDeferralCheck(check) {
18523
+ switch (check) {
18524
+ case "empty-reason": return "the note names no reason";
18525
+ case "no-target-label": return "the note names no target task";
18526
+ case "no-own-task": return "the box names no task of its own";
18527
+ case "target-not-found": return "no task in the plan carries that label";
18528
+ case "target-not-later": return "the target task does not come later in the plan";
18529
+ case "target-is-retire": return "the target is the retire task";
18530
+ case "no-carried-box": return "the target task holds no box carried from this one";
18531
+ }
18532
+ }
18325
18533
  function isOutstanding(box, options) {
18326
- if (box.checked || box.declined) return false;
18534
+ if (box.checked || box.declined || box.deferred) return false;
18327
18535
  return !(box.retireTask && options?.planRetired === true);
18328
18536
  }
18329
18537
  function noteKind(label) {
18330
18538
  if (label === "Progress") return "progress";
18331
18539
  if (label === "Blocked") return "blocked";
18540
+ if (label === "Deferred") return "deferred";
18332
18541
  return "declined";
18333
18542
  }
18334
- const PARAGRAPH_BREAK_REGEX = /^[ \t]*(?:[-*+][ \t]|[0-9]+[.)][ \t]|\*\*(?:Progress|Blocked|Declined):\*\*|<!--)/;
18543
+ const PARAGRAPH_BREAK_REGEX = /^[ \t]*(?:[-*+][ \t]|[0-9]+[.)][ \t]|\*\*(?:Progress|Blocked|Declined|Deferred):\*\*|<!--)/;
18335
18544
  const ABBREVIATION_REGEX = /(?:^|[^A-Za-z])(?:e\.g|i\.e|etc|vs|cf)$/i;
18336
18545
  function boxParagraph(lines, fenced, start, end, first) {
18337
18546
  const parts = [first];
@@ -18365,6 +18574,100 @@ function unwrapEmphasis(rawTitle) {
18365
18574
  if (emphasis === void 0 || !rawTitle.endsWith(emphasis)) return rawTitle;
18366
18575
  return rawTitle.slice(emphasis.length, -emphasis.length).trim();
18367
18576
  }
18577
+ function deferredLineOf(lines, fenced, start, blockEnd) {
18578
+ for (let index = start + 1; index < blockEnd; index++) {
18579
+ if (fenced[index] === true) continue;
18580
+ const match = DEFERRED_LINE_REGEX.exec(lines[index] ?? "");
18581
+ if (match === null) continue;
18582
+ return (match[1] ?? "").trim();
18583
+ }
18584
+ return null;
18585
+ }
18586
+ function readDeferralNote(text) {
18587
+ if (text === "") return {
18588
+ target: null,
18589
+ reason: "",
18590
+ failed: "empty-reason"
18591
+ };
18592
+ const target = taskLabelId(text);
18593
+ if (target === null) return {
18594
+ target: null,
18595
+ reason: "",
18596
+ failed: "no-target-label"
18597
+ };
18598
+ const reason = text.slice(text.indexOf(target) + target.length).replace(DEFERRAL_SEPARATOR_REGEX, "").trim();
18599
+ if (reason === "") return {
18600
+ target,
18601
+ reason: "",
18602
+ failed: "empty-reason"
18603
+ };
18604
+ return {
18605
+ target,
18606
+ reason,
18607
+ failed: null
18608
+ };
18609
+ }
18610
+ function ownTaskLabel(box, units) {
18611
+ const unit = units.find((candidate) => candidate.boxes.some((other) => other.line === box.line));
18612
+ const fromSection = unit?.task?.label ?? null;
18613
+ if (fromSection !== null) return fromSection;
18614
+ return unit?.task === void 0 ? null : taskLabelId(box.title);
18615
+ }
18616
+ function holdsCarriedBox(unit, sourceLabel) {
18617
+ const escaped = sourceLabel.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
18618
+ const carried = new RegExp(`^Carried from Task ${escaped}(?![0-9A-Za-z]):`);
18619
+ return unit.boxes.some((box) => carried.test(box.title));
18620
+ }
18621
+ function resolveDeferrals(boxes, units) {
18622
+ for (const { box, deferredLine } of boxes) {
18623
+ if (deferredLine === null || box.checked || box.declined) continue;
18624
+ const deferral = readDeferralNote(deferredLine);
18625
+ box.deferral = deferral;
18626
+ if (deferral.failed !== null || deferral.target === null) continue;
18627
+ const ownIndex = units.findIndex((unit) => unit.boxes.some((other) => other.line === box.line));
18628
+ const sourceLabel = ownTaskLabel(box, units);
18629
+ if (sourceLabel === null) {
18630
+ box.deferral = {
18631
+ ...deferral,
18632
+ failed: "no-own-task"
18633
+ };
18634
+ continue;
18635
+ }
18636
+ const targetIndexes = units.flatMap((unit, index) => unit.task?.label === deferral.target ? [index] : []);
18637
+ if (targetIndexes.length !== 1) {
18638
+ box.deferral = {
18639
+ ...deferral,
18640
+ failed: "target-not-found"
18641
+ };
18642
+ continue;
18643
+ }
18644
+ const targetIndex = targetIndexes[0] ?? -1;
18645
+ if (targetIndex <= ownIndex) {
18646
+ box.deferral = {
18647
+ ...deferral,
18648
+ failed: "target-not-later"
18649
+ };
18650
+ continue;
18651
+ }
18652
+ const target = units[targetIndex];
18653
+ if (target === void 0) continue;
18654
+ if (target.boxes.some((other) => other.retireTask) || target.task !== null && RETIRE_TASK_REGEX.test(target.task.title)) {
18655
+ box.deferral = {
18656
+ ...deferral,
18657
+ failed: "target-is-retire"
18658
+ };
18659
+ continue;
18660
+ }
18661
+ if (!holdsCarriedBox(target, sourceLabel)) {
18662
+ box.deferral = {
18663
+ ...deferral,
18664
+ failed: "no-carried-box"
18665
+ };
18666
+ continue;
18667
+ }
18668
+ box.deferred = true;
18669
+ }
18670
+ }
18368
18671
  function parsePlanBoxes(planText) {
18369
18672
  const lines = planText.split("\n");
18370
18673
  const fenced = fencedLines(lines);
@@ -18379,7 +18682,7 @@ function parsePlanBoxes(planText) {
18379
18682
  rawTitle: (match[2] ?? "").trim()
18380
18683
  });
18381
18684
  }
18382
- return boxStarts.map((box, position) => {
18685
+ const built = boxStarts.map((box, position) => {
18383
18686
  const nextBoxIndex = boxStarts[position + 1]?.index ?? lines.length;
18384
18687
  let blockEnd = nextBoxIndex;
18385
18688
  for (let index = box.index + 1; index < nextBoxIndex; index++) {
@@ -18392,13 +18695,18 @@ function parsePlanBoxes(planText) {
18392
18695
  const title = stripStrong(unwrapEmphasis(firstSentence$1(boxParagraph(lines, fenced, box.index, blockEnd, box.rawTitle))));
18393
18696
  const retireTask = RETIRE_TASK_REGEX.test(title);
18394
18697
  if (box.checked) return {
18395
- line: box.index,
18396
- checked: true,
18397
- declined: false,
18398
- reason: null,
18399
- title,
18400
- retireTask,
18401
- notes: []
18698
+ box: {
18699
+ line: box.index,
18700
+ checked: true,
18701
+ declined: false,
18702
+ reason: null,
18703
+ title,
18704
+ retireTask,
18705
+ notes: [],
18706
+ deferred: false,
18707
+ deferral: null
18708
+ },
18709
+ deferredLine: null
18402
18710
  };
18403
18711
  const notes = [];
18404
18712
  for (let index = box.index + 1; index < blockEnd; index++) {
@@ -18423,15 +18731,22 @@ function parsePlanBoxes(planText) {
18423
18731
  }
18424
18732
  }
18425
18733
  return {
18426
- line: box.index,
18427
- checked: false,
18428
- declined: reason !== null,
18429
- reason,
18430
- title,
18431
- retireTask,
18432
- notes
18734
+ box: {
18735
+ line: box.index,
18736
+ checked: false,
18737
+ declined: reason !== null,
18738
+ reason,
18739
+ title,
18740
+ retireTask,
18741
+ notes,
18742
+ deferred: false,
18743
+ deferral: null
18744
+ },
18745
+ deferredLine: deferredLineOf(lines, fenced, box.index, blockEnd)
18433
18746
  };
18434
18747
  });
18748
+ if (built.some((entry) => entry.deferredLine !== null)) resolveDeferrals(built, groupPlanUnits(planText, built.map((entry) => entry.box)));
18749
+ return built.map((entry) => entry.box);
18435
18750
  }
18436
18751
  function countOutstandingBoxes(planText, options) {
18437
18752
  return parsePlanBoxes(planText).filter((box) => isOutstanding(box, options)).length;
@@ -18462,6 +18777,11 @@ function planStatus(planText, planPath) {
18462
18777
  kind: note.kind,
18463
18778
  text: note.text
18464
18779
  })));
18780
+ const deferrals = boxes.flatMap((box) => box.deferral === null ? [] : [{
18781
+ task: box.title,
18782
+ target: box.deferral.target,
18783
+ failed: box.deferral.failed
18784
+ }]);
18465
18785
  const nextBox = open[0];
18466
18786
  return {
18467
18787
  plan: planPath,
@@ -18469,6 +18789,8 @@ function planStatus(planText, planPath) {
18469
18789
  checked: boxes.filter((box) => box.checked).length,
18470
18790
  outstanding: open.length,
18471
18791
  declined: boxes.filter((box) => box.declined).length,
18792
+ deferred: boxes.filter((box) => box.deferred).length,
18793
+ deferrals,
18472
18794
  next: nextBox === void 0 || nextBox.title === "" ? null : nextBox.title,
18473
18795
  nextTask: nextBox === void 0 ? null : enclosingTaskLabel(planText, nextBox.line),
18474
18796
  onlyRetireLeft: open.length > 0 && open.every((box) => box.retireTask),
@@ -18821,7 +19143,7 @@ async function docsSection({ git, docsExtraDirs, resolved }) {
18821
19143
  path,
18822
19144
  status: {
18823
19145
  ...status,
18824
- total: status.checked + status.outstanding + status.declined
19146
+ total: status.checked + status.outstanding + status.declined + status.deferred
18825
19147
  }
18826
19148
  });
18827
19149
  }
@@ -19041,7 +19363,7 @@ const workStartCommand = defineCommand({
19041
19363
  },
19042
19364
  json: {
19043
19365
  type: "boolean",
19044
- description: "Emit one JSON document: the whole work:status report plus a claim member {outcome, label?, reason?}. outcome is claimed (the flag was written), already-claimed (it was already on the object, nothing written), not-agent-repo (the default branch does not set agent.enabled, nothing written), refused (a live run or an agent label holds it; exit 1), or failed (a read or write could not be done; exit 1). refused and failed carry ok: false and an error member of kind runtime, and the report survives beside them."
19366
+ description: "Emit one JSON document: the whole work:status report plus a claim member {outcome, label?, reason?}. outcome is claimed (the flag was written), already-claimed (it was already on the object, nothing written), not-agent-repo (the default branch does not set agent.enabled, nothing written), refused (a live run or a queued agent trigger holds it; exit 1), or failed (a read or write could not be done; exit 1). refused and failed carry ok: false and an error member of kind runtime, and the report survives beside them."
19045
19367
  },
19046
19368
  verbose: {
19047
19369
  type: "boolean",
@@ -21251,6 +21573,73 @@ function composePsDump(executor, config) {
21251
21573
  if (!result.stdout.trim() && !result.stderr.trim()) executor.log("(no ps output)");
21252
21574
  } catch (_error) {}
21253
21575
  }
21576
+ const HealthStateSchema = z.object({
21577
+ Status: z.string(),
21578
+ FailingStreak: z.number(),
21579
+ Log: z.array(z.object({
21580
+ Start: z.string(),
21581
+ ExitCode: z.number(),
21582
+ Output: z.string()
21583
+ }))
21584
+ });
21585
+ const HEALTH_INSPECT_FORMAT = "{{json .State.Health}}";
21586
+ function parseHealthState(stdout) {
21587
+ let raw;
21588
+ try {
21589
+ raw = JSON.parse(stdout);
21590
+ } catch (_error) {
21591
+ return;
21592
+ }
21593
+ const parsed = HealthStateSchema.safeParse(raw);
21594
+ return parsed.success ? parsed.data : void 0;
21595
+ }
21596
+ function printServiceHealthLog(executor, config, service, id) {
21597
+ executor.log(`-- ${service} health log --`);
21598
+ try {
21599
+ if (!id) {
21600
+ executor.log("(health log unavailable: compose reported no container id)");
21601
+ return;
21602
+ }
21603
+ const result = executor.exec("docker", [
21604
+ "inspect",
21605
+ "--format",
21606
+ HEALTH_INSPECT_FORMAT,
21607
+ id
21608
+ ], {
21609
+ cwd: config.cwd,
21610
+ env: config.env
21611
+ });
21612
+ const health = parseHealthState(result.stdout);
21613
+ if (result.exitCode !== 0 || !health) {
21614
+ executor.log("(health log unavailable)");
21615
+ if (result.stderr.trim()) executor.logError(result.stderr);
21616
+ return;
21617
+ }
21618
+ executor.log(`status ${health.Status}, failing streak ${String(health.FailingStreak)}`);
21619
+ if (health.Log.length === 0) {
21620
+ executor.log("(no health checks have run yet)");
21621
+ return;
21622
+ }
21623
+ for (const entry of health.Log) {
21624
+ executor.log(`[exit ${String(entry.ExitCode)}] ${entry.Start}`);
21625
+ const output = entry.Output.trimEnd();
21626
+ executor.log(output.length > 0 ? output : "(no output)");
21627
+ }
21628
+ } catch (_error) {
21629
+ executor.log("(health log unavailable)");
21630
+ }
21631
+ }
21632
+ function composeHealthLogs(executor, config) {
21633
+ try {
21634
+ const containers = composePs(executor, config);
21635
+ for (const service of config.services) {
21636
+ const container = containers.find((c) => c.Service === service);
21637
+ if (!container) continue;
21638
+ if (container.Health !== "unhealthy" && container.Health !== "starting") continue;
21639
+ printServiceHealthLog(executor, config, service, container.ID);
21640
+ }
21641
+ } catch (_error) {}
21642
+ }
21254
21643
  function composePs(executor, config) {
21255
21644
  const output = executor.exec("docker", [
21256
21645
  ...composeArgs(config),
@@ -21429,6 +21818,7 @@ async function runDockerCheck(executor, rawConfig) {
21429
21818
  executor.logError(`Compose stack failed to start -- dumping logs`);
21430
21819
  composePsDump(executor, compose);
21431
21820
  for (const service of compose.services) composeLogs(executor, compose, service);
21821
+ composeHealthLogs(executor, compose);
21432
21822
  cleanup();
21433
21823
  return {
21434
21824
  success: false,
@@ -21454,6 +21844,7 @@ async function runDockerCheck(executor, rawConfig) {
21454
21844
  executor.logError(`Container ${service} is unhealthy`);
21455
21845
  composePsDump(executor, compose);
21456
21846
  composeLogs(executor, compose, service);
21847
+ composeHealthLogs(executor, compose);
21457
21848
  cleanup();
21458
21849
  return {
21459
21850
  success: false,
@@ -21507,6 +21898,7 @@ async function runDockerCheck(executor, rawConfig) {
21507
21898
  executor.logError("Timeout waiting for stack to become healthy");
21508
21899
  composePsDump(executor, compose);
21509
21900
  for (const service of compose.services) composeLogs(executor, compose, service);
21901
+ composeHealthLogs(executor, compose);
21510
21902
  cleanup();
21511
21903
  return {
21512
21904
  success: false,
@@ -24528,6 +24920,7 @@ function handleMissingBaseline(state, updateBaseline, failOnMissingBaseline) {
24528
24920
  metrics: current,
24529
24921
  sources: details.sources
24530
24922
  });
24923
+ reportCarriedRaises(state.referenceFields.raises, out);
24531
24924
  process.exitCode = 1;
24532
24925
  return;
24533
24926
  }
@@ -24539,6 +24932,7 @@ function handleMissingBaseline(state, updateBaseline, failOnMissingBaseline) {
24539
24932
  metrics: current,
24540
24933
  sources: details.sources
24541
24934
  });
24935
+ reportCarriedRaises(state.referenceFields.raises, out);
24542
24936
  return;
24543
24937
  }
24544
24938
  const message = `${BASELINE_FILE} not found. Run with --update-baseline to create one from the current run.`;
@@ -24550,8 +24944,10 @@ function handleMissingBaseline(state, updateBaseline, failOnMissingBaseline) {
24550
24944
  metrics: current,
24551
24945
  sources: details.sources
24552
24946
  });
24947
+ reportCarriedRaises(state.referenceFields.raises, out);
24553
24948
  return;
24554
24949
  }
24950
+ reportCarriedRaises(state.referenceFields.raises, out);
24555
24951
  throw new FatalError(message);
24556
24952
  }
24557
24953
  function applyBaselineUpdate(state, baseline, reset) {
@@ -29006,7 +29402,12 @@ function renderStatus(report) {
29006
29402
  const next = report.next ?? "(none)";
29007
29403
  const task = report.nextTask === null || taskLabelId(next) === report.nextTask ? "" : `Task ${report.nextTask} -- `;
29008
29404
  const lines = [`${report.plan}${report.retired ? " (retired)" : ""}: ${String(report.checked)} done, ${String(report.outstanding)} outstanding, ${String(report.declined)} declined`, `next: ${task}${next}${report.onlyRetireLeft ? " -- only the retire task is left" : ""}`];
29405
+ if (report.deferred > 0) lines.splice(1, 0, `${String(report.deferred)} deferred to a later task`);
29009
29406
  for (const note of report.notes) lines.push(` [${note.kind}] ${note.task}: ${note.text}`);
29407
+ for (const deferral of report.deferrals) {
29408
+ if (deferral.failed === null) continue;
29409
+ lines.push(` [deferred -- not counted] ${deferral.task}: ${describeDeferralCheck(deferral.failed)}.`);
29410
+ }
29010
29411
  return lines.join("\n");
29011
29412
  }
29012
29413
  const planStatusCommand = defineCommand({
@@ -29018,7 +29419,7 @@ const planStatusCommand = defineCommand({
29018
29419
  plan: PLAN_ARG,
29019
29420
  json: {
29020
29421
  type: "boolean",
29021
- description: "Emit one JSON document: plan, retired, checked, outstanding, declined, next (or null), nextTask (a task label string such as \"3\" or \"18a\", or null), onlyRetireLeft, notes ([{task, kind (progress | blocked | declined), text}]). next is null when there is none; nextTask is null when no task label encloses it."
29422
+ description: "Emit one JSON document: plan, retired, checked, outstanding, declined, deferred, deferrals ([{task, target (a task label string or null), failed (empty-reason | no-target-label | no-own-task | target-not-found | target-not-later | target-is-retire | no-carried-box, or null when valid)}]), next (or null), nextTask (a task label string such as \"3\" or \"18a\", or null), onlyRetireLeft, notes ([{task, kind (progress | blocked | declined | deferred), text}]). next is null when there is none; nextTask is null when no task label encloses it."
29022
29423
  }
29023
29424
  },
29024
29425
  run({ args }) {
@@ -29191,7 +29592,7 @@ async function runCli(config) {
29191
29592
  //#region src/cli-main.ts
29192
29593
  setLogLevel(resolveLogLevel({}));
29193
29594
  setForgejoLogger(log$1);
29194
- const displayVersion = "0.95.0";
29595
+ const displayVersion = "0.97.0";
29195
29596
  const bstSubCommands = {
29196
29597
  "repo:sync": syncCommand,
29197
29598
  "checks:run": runChecksCommand,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bensandee/tooling",
3
- "version": "0.95.0",
3
+ "version": "0.97.0",
4
4
  "description": "CLI tool to bootstrap and maintain standardized TypeScript project tooling",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -698,7 +698,7 @@
698
698
  "additionalProperties": false
699
699
  },
700
700
  "agent": {
701
- "description": "agent:start behaviour overrides. Opt-in: see agent.autonomy for the interior-autonomy gate.",
701
+ "description": "agent:start behaviour overrides. Opt-in: agent.enabled is the consent gate -- every other key in the block does nothing without it.",
702
702
  "type": "object",
703
703
  "properties": {
704
704
  "enabled": {
@@ -706,7 +706,11 @@
706
706
  "type": "boolean"
707
707
  },
708
708
  "autonomy": {
709
- "description": "Opt into interior autonomy (default false). When a phase's latest rationale reports readiness \"ready\" with an empty openQuestions[] and the review phase is clean, the agent applies the existing plan -> implement -> review -> park-at-mergeable advance itself instead of parking for a human. Never applies to the design/spec gate or the final merge from the mergeable terminal -- those always wait on a human. Also arms the trunk-red detector: when this repo's default branch combined status settles red, the agent files a tracking issue naming the failing checks and labels it agent/spec, starting the fix through the ordinary spec/plan/implement/review pipeline. It also closes that issue, with a comment, if the default branch recovers on its own before a human acts on it. Also arms the world-changed retrigger sweep: a pull request labelled agent-flags/autopilot that is parked at a -stuck or -failed terminal is re-queued when the fact its park recorded stops being true (the default branch went green, or moved past a conflicted base).",
709
+ "description": "Retired and ignored -- it armed neither the advance rung nor the sweeps it once did. Advance is now the unit's own `agent-flags/advance` or `agent-flags/autopilot` label, and the trunk-red detector and world-changed retrigger sweep read `agent.trunkRed`. The key is still accepted so an existing config keeps syncing; the agent warns once per launch for a repo that still sets it.",
710
+ "type": "boolean"
711
+ },
712
+ "trunkRed": {
713
+ "description": "Whether this repo's trunk-red detector and world-changed retrigger sweep run (default: on). The detector files a tracking issue when the default branch's combined status settles red and labels it agent/spec, and closes that issue with a comment if the branch recovers on its own before a human acts on it. The retrigger sweep re-queues a pull request labelled agent-flags/autopilot parked at a -stuck or -failed terminal when the fact its park recorded stops being true (the default branch went green, or moved past a conflicted base). A missing key means on; false disarms both.",
710
714
  "type": "boolean"
711
715
  },
712
716
  "preRunRebase": {