@tea-agent/loop-agent 0.39.0-next.26 → 0.39.0-next.28

package/dist/workflows/dag/types.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { isOpenspecSpecFilePath } from "../../shared/openspec-spec.js";
 import { campaignBudgetSchema, } from "../../application/evaluation/budget.js";
 import { assertDagPromptSourceRule } from "./prompt-source.js";
-import { dagRetryPolicySchema } from "./retry-policy.js";
+import { dagRetryPolicySchema, TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE, } from "./retry-policy.js";
 import { dagLivenessPolicySchema, } from "./liveness-policy.js";
 import { dagOutputProtocolSchema } from "./output-protocol.js";
 export const dagComplexitySchema = z.enum(["HIGH", "MED", "LOW"]);
@@ -10,6 +10,18 @@ export const dagNodeExecutorSchema = z.enum(["pi", "shell", "static"]);
 export const CURSOR_DAG_EXECUTOR_REMOVED_ERROR = 'executor "cursor" is no longer supported; regenerate the DAG with Pi-only writers (implement-pi / repair-pi)';
 export const CURSOR_EXECUTOR_MODELS_REMOVED_ERROR = "executorModels.cursor is no longer supported; use executorModels.pi only";
 export const dagToolProfileSchema = z.enum(["read-only", "write"]);
+/**
+ * Frozen Pi extension short ids for backend implementation DAGs (plan
+ * 2026-08-21 D2): the DAG carries only these ids; the executor resolves them
+ * against the Pi settings package inventory at run time. Adding a package
+ * requires changing this enum and the plan.
+ */
+export const dagPiExtensionIdSchema = z.enum(["pi-codegraph", "pi-lens"]);
+/** Node-level explicit Pi extension allowlist (omitted = all off, R8.1). */
+export const dagPiExtensionsSchema = z
+    .array(dagPiExtensionIdSchema)
+    .min(1)
+    .transform((ids) => Array.from(new Set(ids)));
 /** Static command capabilities only; tasks cannot inject executables or shell prefixes. */
 export const dagCommandCapabilitySchema = z.enum(["playwright-cli"]);
 export const dagCommandPolicySchema = z.discriminatedUnion("mode", [
@@ -753,6 +765,13 @@ export const dagTaskSchema = z.object({ id: z.string().regex(/^[a-z][a-z0-9-]*$/
     role: dagRoleSchema.optional(),
     skills: z.array(z.string()).optional(),
     toolProfile: dagToolProfileSchema.optional(),
+    /**
+     * Explicit Pi extension allowlist (backend implementation DAGs only):
+     * frozen short ids resolved at run time against the Pi settings package
+     * inventory. Omitted = extension discovery stays fully closed (R8.1).
+     * Only `executor: "pi"` nodes may declare it (validated fail-closed).
+     */
+    piExtensions: dagPiExtensionsSchema.optional(),
     /** Default deny: file write (toolProfile=write) does not grant command execution. */
     commandPolicy: dagCommandPolicySchema.optional(),
     writePolicy: dagWritePolicySchema.optional(),
@@ -830,6 +849,14 @@ export const dagTaskSchema = z.object({ id: z.string().regex(/^[a-z][a-z0-9-]*$/
     forbiddenPaths: z.array(z.string()).optional().default([]),
     decisionGate: dagDecisionGateSchema.optional(),
     retryPolicy: dagRetryPolicySchema.optional(),
+    /**
+     * Generation-path stamp for implicit same-run transient retry. Only the
+     * three target templates stamp canonical final verify shells and
+     * exclusive `implement-pi`. Zod-declared so parseDagSpec does not strip it.
+     */
+    transientRetryProfile: z
+        .literal(TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE)
+        .optional(),
     /** Optional per-node adaptive liveness override (merged over defaults). */
     livenessPolicy: dagLivenessPolicySchema,
     dynamicExpansion: dagDynamicExpansionSchema.optional(),

package/dist/workflows/dag/validate.js

@@ -1,4 +1,4 @@
-import { DEFAULT_DAG_EXECUTOR_MODELS, ENV_VAR_NAME_PATTERN, dagCommandPolicyAllows, resolveDagCommandPolicy, } from "./types.js";
+import { DEFAULT_DAG_EXECUTOR_MODELS, ENV_VAR_NAME_PATTERN, dagCommandPolicyAllows, dagPiExtensionIdSchema, resolveDagCommandPolicy, } from "./types.js";
 import { resolveShellCommands } from "../../executors/shell-executor.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { resolveRepairTaskForGate } from "./repair-artifact.js";
@@ -955,6 +955,7 @@ export function validateDagSpec(spec) {
         validateCommandPolicyTaskConfig(task, issues);
         validateDynamicChildCommandPolicy(task, issues);
         validateProjectGovernanceTaskConfig(task, spec, issues);
+        validatePiExtensionsTaskConfig(task, issues);
         validateFailureAwareDependsOn(task, spec, issues);
     }
     validateSameRankWriteSetConflicts(spec, ranks, issues);
@@ -965,6 +966,43 @@ export function validateDagSpec(spec) {
     }
     return issues;
 }
+/**
+ * Fail-closed `piExtensions` validation (plan 2026-08-21 D1/D2):
+ * - only `executor: "pi"` nodes may declare it (shell/static reject);
+ * - unknown ids outside the frozen enum are rejected at parse time by zod,
+ *   and here for task objects that bypass schema parsing;
+ * - closeout nodes must stay fully closed (extension-free) — the two-bucket
+ *   generator never assigns it there, so any appearance is contract drift.
+ */
+function validatePiExtensionsTaskConfig(task, issues) {
+    const ids = task.piExtensions;
+    if (ids === undefined)
+        return;
+    if (task.executor !== "pi") {
+        issues.push({
+            type: "invalid-pi-extensions-config",
+            message: `task ${task.id} piExtensions requires executor "pi" (found ${task.executor})`,
+        });
+        return;
+    }
+    const allowed = new Set(dagPiExtensionIdSchema.options);
+    for (const id of ids) {
+        if (!allowed.has(id)) {
+            issues.push({
+                type: "invalid-pi-extensions-config",
+                message: `task ${task.id} piExtensions has unknown id "${id}"; allowed: ${[
+                    ...allowed,
+                ].join(", ")}`,
+            });
+        }
+    }
+    if (task.id === "closeout-pi" && ids.length > 0) {
+        issues.push({
+            type: "invalid-pi-extensions-config",
+            message: "closeout-pi must stay extension-free (read buckets exclude closeout)",
+        });
+    }
+}
 function validateProjectGovernanceTaskConfig(task, spec, issues) {
     if (task.governanceStandardReview) {
         if (task.executor !== "pi" ||

package/docs/init-surface.manifest.json

@@ -50,6 +50,9 @@
     "scripts/kb-graph-materialize.mjs",
     "scripts/kb-graph-promote.mjs",
     "scripts/kb-graph-incremental-prepare.mjs",
+    "scripts/next-info.mjs",
+    "scripts/next-publish-gate.mjs",
+    "scripts/release-source-binding.mjs",
     "docs/templates/agent-dag.schema.json",
     "examples/example-dag.json",
     "skills/agent-worker/SKILL.md",
@@ -277,6 +280,7 @@
     "harness.json",
     "package.json",
     "src/commands/init.ts",
+    "src/commands/init-model-catalog.ts",
     "src/commands/client-recovery.ts",
     "src/commands/init-upgrade.ts",
     "src/cli.ts",
@@ -302,6 +306,7 @@
         "description": "Changes that may alter target-project initialization behavior, default DAG role skills, skill resolution, or package/init contracts.",
         "patterns": [
           "src/commands/init.ts",
+          "src/commands/init-model-catalog.ts",
           "src/commands/client-recovery.ts",
           "src/commands/init-upgrade.ts",
           "src/cli.ts",

package/docs/operations/README.md

@@ -7,7 +7,7 @@
 - [`local-development-environment.md`](local-development-environment.md)：本地环境、Windows 差异和常见排障。
 - [`branch-merge-guideline.md`](branch-merge-guideline.md)：按风险选择合并模式并留下 source-SHA 证据。
 - [`github-collaboration.md`](github-collaboration.md)：仓库内 GitHub 协作约定及发布通道。
-- [`version-and-release-management.md`](version-and-release-management.md)：版本发布管理——next / release-x.y / latest 渠道、workflow 与 promote 手册。
+- [`version-and-release-management.md`](version-and-release-management.md)：版本发布管理——next / release-x.y / latest 渠道、移动式 `npm-next` ref、`inspect next` 查询入口、workflow 与 promote 手册。
 - [`production-readiness.md`](production-readiness.md)：交付前的生产就绪判断。
 - [`agent-worker-production-readiness.md`](agent-worker-production-readiness.md)：agent-worker Feature/Task Pool 外层编排的 Production Readiness v1 操作合同。
 - [`backend-test-jacoco-coverage.md`](backend-test-jacoco-coverage.md)：Java 被测服务挂载 JaCoCo tcpserver agent 的 Maven、`java -jar` 与 Docker 操作手册。

package/docs/templates/agent-dag.schema.json

@@ -130,6 +130,18 @@
     "toolProfile": {
       "enum": ["read-only", "write"]
     },
+    "piExtensionId": {
+      "type": "string",
+      "enum": ["pi-codegraph", "pi-lens"],
+      "description": "Frozen Pi extension short id resolved at run time against the Pi settings package inventory. Adding a package requires changing the plan and this enum."
+    },
+    "piExtensions": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/piExtensionId" },
+      "description": "Node-level explicit Pi extension allowlist (backend implementation DAGs only). Omitted = extension discovery stays fully closed (R8.1). Only executor 'pi' nodes may declare it."
+    },
     "role": {
       "enum": ["planner", "scout", "implementer", "reviewer", "supervisor", "verifier", "closeout"]
     },
@@ -516,6 +528,7 @@
           "items": { "type": "string", "minLength": 1 }
         },
         "toolProfile": { "$ref": "#/$defs/toolProfile" },
+        "piExtensions": { "$ref": "#/$defs/piExtensions" },
         "governanceStandardReview": {
           "type": "boolean",
           "description": "Explicitly opts this node into writer-change-scoped AGENTS.md and repository-local code-standard review. Never inferred from node id or role."

package/docs/templates/init-managed-agents.md

@@ -80,9 +80,19 @@ loop-agent init update --repo-root . --apply-safe
 当用户要求初始化 loop-agent（“初始化 loop-agent”“loop agent 初始化”“loop agent初始化”“loop-agent 初始化”），或发现 `README.md` / `__LOOP_AGENT_GOVERNANCE_ROOT__/verification-matrix.md` 仍停留在通用初始化状态时，模型应在同一轮工作中完成初始化闭环，不要把补全文档和验证矩阵留给用户交互。
 
 1. 运行 `loop-agent init instructions --repo-root .`。
-2. 运行 `loop-agent init --repo-root . --profile full --merge`。
-3. 基于真实项目文件补全根 `README.md`、`__LOOP_AGENT_GOVERNANCE_ROOT__/verification-matrix.md`，必要时适配 `scripts/ci-tests.sh`。
-4. 运行 `loop-agent init doctor --repo-root .`、`loop-agent inspect`、`loop-agent docs audit` 并完成 quick verification。
+2. 运行 `loop-agent init model-catalog --repo-root . --json`。loop-agent 不直接打开或解析认证文件原文，只让 Pi/OpenCode 自己的 runtime 加载其配置，并输出白名单模型元数据、Pi setup 状态、Pi 兼容性与 credential-ready 布尔值；token、headers、URL、原始命令输出和认证路径不会进入 catalog。
+3. 先处理 `piSetup`：如果没有模型定义，向用户索取无法推断的 provider/model id、API/base URL、上下文窗口、最大输出、输入/推理能力、成本约束和凭据方式，帮助按 Pi 原生 schema 合并 `~/.pi/agent/models.json`；不得让用户把凭据值写入对话、harness 或报告，优先 Pi 登录/auth storage 或环境变量引用。如果已有定义但凭据未就绪，只修复认证。随后重跑 catalog，未出现 credential-ready Pi model 前不得继续初始化。
+4. 对已有 `harness.json`，逐档保留仍存在于 Pi 的 LOW/MED/HIGH 原值；只为已移除或缺失的档位重新选择。结合目标项目实际技术栈、模型能力、成本与上下文窗口，从 `eligibleForHarness=true` 的候选中自主选择，并直接运行带完整三档参数的 init/update；代码会拒绝改动仍有效的档位。三档可以相同。只有凭据、成本、合规或可用性存在无法推断的实质歧义时才询问用户；OpenCode-only 候选不能证明 Pi executor 可用。
+5. 基于真实项目文件补全根 `README.md`、`__LOOP_AGENT_GOVERNANCE_ROOT__/verification-matrix.md`，必要时适配 `scripts/ci-tests.sh`。
+6. 运行 `loop-agent init doctor --repo-root .`、`loop-agent inspect`、`loop-agent docs audit` 并完成 quick verification；doctor 未确认 Pi model matrix 时不得开始 DAG。
+
+```bash
+loop-agent init --repo-root . --profile full --merge \
+  --low-model <provider/model> --med-model <provider/model> --high-model <provider/model>
+# 已初始化项目只替换失效档位；仍有效档位在完整参数中保持当前引用
+loop-agent init update --repo-root . --apply-safe \
+  --low-model <current-or-selected> --med-model <current-or-selected> --high-model <current-or-selected>
+```
 
 信息不足时写明尚未识别到的事实；不要留下泛化占位符。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.39.0-next.26",
+  "version": "0.39.0-next.28",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",
@@ -33,6 +33,9 @@
     "scripts/kb-graph-materialize.mjs",
     "scripts/kb-graph-promote.mjs",
     "scripts/kb-graph-incremental-prepare.mjs",
+    "scripts/next-info.mjs",
+    "scripts/next-publish-gate.mjs",
+    "scripts/release-source-binding.mjs",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -58,6 +61,7 @@
     "test": "node scripts/run-tests.mjs",
     "test:host": "vitest run test/init-upgrade.test.ts --maxWorkers=1 -t \"records and reuses|controller-authorized semantic merge|authority-sensitive\"",
     "test:fast": "vitest run --config vitest.fast.config.ts",
+    "test:io-heavy": "vitest run --config vitest.io-heavy.config.ts",
     "test:integration": "vitest run --config vitest.integration.config.ts",
     "docs:dev": "npm --prefix website start",
     "docs:build": "npm --prefix website run build",

package/scripts/next-info.mjs

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+/**
+ * next-info: read-only report of the current npm `next` binding.
+ *
+ * Resolves the moving git ref `npm-next` (local, then origin) and the
+ * published tarball build stamp. Does not write the repo, move dist-tags,
+ * or call GitHub APIs.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+import {
+	commandLaunch,
+	defaultRun,
+	isAncestor,
+	normalizeCommandArgs,
+	npmViewDistTags,
+} from "./next-publish-gate.mjs";
+import {
+	downloadNpmTarball,
+	readTarballBuildStamp,
+} from "./release-source-binding.mjs";
+
+export const UNPUBLISHED_COMMIT_LIMIT_DEFAULT = 50;
+const GIT_REF_CANDIDATES = ["refs/heads/npm-next", "origin/npm-next"];
+
+/**
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {string} [cwd]
+ */
+function runWithCwd(cmd, args, cwd) {
+	const launch = commandLaunch(cmd, normalizeCommandArgs(cmd, args));
+	return execFileSync(launch.cmd, launch.args, {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+		cwd,
+	});
+}
+
+function scriptEntryHref(argv1) {
+	try {
+		return argv1 ? new URL(`file://${argv1}`).href : "";
+	} catch {
+		return "";
+	}
+}
+
+function trimSha(value) {
+	if (typeof value !== "string") return null;
+	const sha = value.trim();
+	return sha ? sha : null;
+}
+
+function equalSha(left, right) {
+	if (!left || !right) return false;
+	return left.toLowerCase() === right.toLowerCase();
+}
+
+function tryRevParse(run, ref) {
+	try {
+		return trimSha(run("git", ["rev-parse", ref]));
+	} catch {
+		return null;
+	}
+}
+
+function resolveGitRefSha(run) {
+	for (const ref of GIT_REF_CANDIDATES) {
+		const sha = tryRevParse(run, ref);
+		if (sha) return { ref, sha };
+	}
+	return null;
+}
+
+function readStampBuiltAt(tarballPath, run) {
+	try {
+		const listing = run("tar", ["-tzf", tarballPath]);
+		const stampEntry = String(listing)
+			.split("\n")
+			.map((line) => line.trim())
+			.find((line) => /\/dist\/build-stamp\.json$/.test(line));
+		if (!stampEntry) return null;
+		const stampJson = run("tar", ["-xzf", tarballPath, "-O", stampEntry]);
+		const parsed = JSON.parse(String(stampJson));
+		return typeof parsed.builtAt === "string" ? parsed.builtAt : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Download the published next tarball and read gitSha + builtAt. */
+export function defaultNextStampProbe(version, run = defaultRun) {
+	const dir = mkdtempSync(join(tmpdir(), "loop-agent-next-info-"));
+	try {
+		const tarball = downloadNpmTarball(version, dir, run);
+		const stamp = readTarballBuildStamp(tarball, run);
+		return {
+			gitSha: stamp.gitSha,
+			version: stamp.version ?? null,
+			builtAt: readStampBuiltAt(tarball, run),
+		};
+	} catch {
+		return null;
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+}
+
+function emptyResult(overrides) {
+	return {
+		ok: false,
+		exitCode: 1,
+		npmNextVersion: null,
+		gitSha: null,
+		gitRef: null,
+		gitRefSha: null,
+		stampSha: null,
+		builtAt: null,
+		source: null,
+		aheadBy: null,
+		aheadByReason: null,
+		unpublishedCommits: [],
+		unpublishedTruncated: false,
+		unpublishedLimit: UNPUBLISHED_COMMIT_LIMIT_DEFAULT,
+		drift: false,
+		error: null,
+		...overrides,
+	};
+}
+
+function collectAheadState(gitSha, run) {
+	if (!gitSha) {
+		return {
+			aheadBy: null,
+			aheadByReason: "no gitSha to compare against HEAD",
+			unpublishedCommits: [],
+			unpublishedTruncated: false,
+		};
+	}
+	const headSha = tryRevParse(run, "HEAD");
+	if (!headSha) {
+		return {
+			aheadBy: null,
+			aheadByReason: "HEAD is unavailable",
+			unpublishedCommits: [],
+			unpublishedTruncated: false,
+		};
+	}
+	let unpublishedCommits = [];
+	let unpublishedTruncated = false;
+	try {
+		const log = run("git", ["log", "--oneline", `${gitSha}..HEAD`]);
+		const lines = String(log ?? "")
+			.split("\n")
+			.map((line) => line.trim())
+			.filter(Boolean);
+		unpublishedTruncated = lines.length > UNPUBLISHED_COMMIT_LIMIT_DEFAULT;
+		unpublishedCommits = lines.slice(0, UNPUBLISHED_COMMIT_LIMIT_DEFAULT);
+	} catch {
+		unpublishedCommits = [];
+	}
+	if (!isAncestor(gitSha, headSha, run)) {
+		return {
+			aheadBy: null,
+			aheadByReason: "gitSha is not an ancestor of HEAD",
+			unpublishedCommits,
+			unpublishedTruncated,
+		};
+	}
+	try {
+		const count = Number(
+			String(run("git", ["rev-list", "--count", `${gitSha}..HEAD`])).trim(),
+		);
+		if (!Number.isFinite(count)) {
+			return {
+				aheadBy: null,
+				aheadByReason: "rev-list count is not a number",
+				unpublishedCommits,
+				unpublishedTruncated,
+			};
+		}
+		return {
+			aheadBy: count,
+			aheadByReason: null,
+			unpublishedCommits,
+			unpublishedTruncated,
+		};
+	} catch {
+		return {
+			aheadBy: null,
+			aheadByReason: "rev-list failed",
+			unpublishedCommits,
+			unpublishedTruncated,
+		};
+	}
+}
+
+/**
+ * Pure-ish collector. Tests inject `run` / `viewDistTags` / `stampProbe`
+ * so this never hits the real npm registry.
+ *
+ * @param {{
+ *   cwd?: string,
+ *   run?: (cmd: string, args: string[]) => string,
+ *   viewDistTags?: () => Record<string, string>,
+ *   stampProbe?: (version: string) =>
+ *     | { gitSha?: string, builtAt?: string | null }
+ *     | null,
+ * }} [deps]
+ */
+export function collectNextInfo(deps = {}) {
+	const run =
+		deps.run ??
+		((cmd, args) =>
+			deps.cwd ? runWithCwd(cmd, args, deps.cwd) : defaultRun(cmd, args));
+	const viewDistTags = deps.viewDistTags ?? (() => npmViewDistTags(run));
+	const stampProbe =
+		deps.stampProbe ?? ((version) => defaultNextStampProbe(version, run));
+
+	let distTags = {};
+	try {
+		distTags = viewDistTags() ?? {};
+	} catch {
+		distTags = {};
+	}
+	const npmNextVersion = distTags.next ? String(distTags.next) : null;
+	const gitRef = resolveGitRefSha(run);
+	const gitRefSha = gitRef?.sha ?? null;
+	let stamp = null;
+	if (npmNextVersion) {
+		try {
+			stamp = stampProbe(npmNextVersion);
+		} catch {
+			stamp = null;
+		}
+	}
+	const stampSha = trimSha(stamp?.gitSha);
+	const builtAt = typeof stamp?.builtAt === "string" ? stamp.builtAt : null;
+
+	if (!gitRefSha && !stampSha) {
+		const error = npmNextVersion
+			? `no npm-next git ref and tarball stamp unreadable for next=${npmNextVersion}`
+			: "no npm-next git ref and no dist-tags.next";
+		return emptyResult({ error, npmNextVersion });
+	}
+
+	let source;
+	let gitSha;
+	let drift = false;
+	let error = null;
+	let ok = true;
+	let exitCode = 0;
+
+	if (gitRefSha && stampSha) {
+		source = "both";
+		if (!equalSha(gitRefSha, stampSha)) {
+			drift = true;
+			ok = false;
+			exitCode = 1;
+			error =
+				`npm-next git ref (${gitRefSha}) does not match tarball stamp gitSha (${stampSha})`;
+		}
+		gitSha = gitRefSha;
+	} else if (gitRefSha) {
+		source = "git-ref";
+		gitSha = gitRefSha;
+	} else {
+		source = "tarball-stamp";
+		gitSha = stampSha;
+	}
+
+	const ahead = collectAheadState(gitSha, run);
+	return {
+		ok,
+		exitCode,
+		npmNextVersion,
+		gitSha,
+		gitRef: gitRef?.ref ?? null,
+		gitRefSha,
+		stampSha,
+		builtAt,
+		source,
+		aheadBy: ahead.aheadBy,
+		aheadByReason: ahead.aheadByReason,
+		unpublishedCommits: ahead.unpublishedCommits,
+		unpublishedTruncated: ahead.unpublishedTruncated,
+		unpublishedLimit: UNPUBLISHED_COMMIT_LIMIT_DEFAULT,
+		drift,
+		error,
+	};
+}
+
+export function formatNextInfo(result, { json = false } = {}) {
+	if (json) {
+		return `${JSON.stringify(result, null, 2)}\n`;
+	}
+	const lines = [];
+	if (result.npmNextVersion) {
+		lines.push(`npm next: ${result.npmNextVersion}`);
+	} else {
+		lines.push("npm next: (no dist-tags.next)");
+	}
+	if (result.gitSha) {
+		lines.push(`gitSha: ${result.gitSha} (source: ${result.source})`);
+	} else {
+		lines.push("gitSha: (unavailable)");
+	}
+	if (result.gitRefSha && result.stampSha && result.drift) {
+		lines.push(`git-ref SHA: ${result.gitRefSha}`);
+		lines.push(`tarball stamp SHA: ${result.stampSha}`);
+	}
+	if (result.builtAt) {
+		lines.push(`builtAt: ${result.builtAt}`);
+	}
+	if (result.aheadBy === null) {
+		lines.push(
+			`aheadBy: null${result.aheadByReason ? ` (${result.aheadByReason})` : ""}`,
+		);
+	} else {
+		lines.push(`aheadBy: ${result.aheadBy}`);
+	}
+	const commits = result.unpublishedCommits ?? [];
+	if (commits.length === 0) {
+		lines.push("unpublishedCommits: (none)");
+	} else {
+		lines.push("unpublishedCommits:");
+		for (const commit of commits) lines.push(`  ${commit}`);
+		if (result.unpublishedTruncated) {
+			lines.push(
+				`  … truncated to ${result.unpublishedLimit} commits`,
+			);
+		}
+	}
+	if (result.error) {
+		lines.push(`error: ${result.error}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+function main(argv = process.argv.slice(2)) {
+	const json = argv.includes("--json");
+	const result = collectNextInfo();
+	process.stdout.write(formatNextInfo(result, { json }));
+	process.exit(result.ok ? 0 : result.exitCode || 1);
+}
+
+const invokedAsScript =
+	Boolean(process.argv[1]) &&
+	import.meta.url === scriptEntryHref(process.argv[1]);
+
+if (invokedAsScript) {
+	main();
+}