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

package/dist/workflows/dag/node-execution.js

@@ -10,7 +10,7 @@ import { resolveContextPolicy } from "./context-policy.js";
 import { buildDagNodePromptEnvelope, formatConvergenceFeedbackBlock, } from "./prompt.js";
 import { persistLongNodeOutputArtifacts } from "./upstream-artifacts.js";
 import { buildOutputLimitRecoverySection, loadBackendTestWriterProgressForRetry, } from "./backend-test-writer-completeness.js";
-import { computeBackoffDelayMs, isRetryablePiFailureCategory, isSafeReadOnlyPiRetryCandidate, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, } from "./retry-policy.js";
+import { computeBackoffDelayMs, isCanonicalFinalVerifyShellRetryCandidate, isRetryablePiFailureCategory, isSafeReadOnlyPiRetryCandidate, isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, VERIFY_SHELL_RETRY_POLICY, } from "./retry-policy.js";
 import { applyNodeActivity, evaluateNodeLiveness, resolveLivenessPolicy, } from "./liveness-policy.js";
 import { buildProtocolRetryInstruction, normalizeReviewVerdictAfterRetries, parseJsonReviewVerdict, validateOutputProtocol, } from "./output-protocol.js";
 import { getStructuredContractValidator } from "./contract-output-registry.js";
@@ -260,6 +260,16 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
             "</retry_instruction>",
         ].join("\n");
     }
+    if (previousFailureCategory === "writer-clean-timeout") {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Previous attempt ended in a clean provider/transport failure with zero attributed workspace writes and zero write/edit tool calls.",
+            "Do not invent existing implementation progress. Continue from the original task only if the workspace is still unchanged.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
     if (previousFailureCategory !== "output-too-large") {
         return basePrompt;
     }
@@ -696,12 +706,18 @@ export async function executeDagNode(input) {
             // Invalid or missing harness preserves the previous no-override behavior.
         }
     }
-    const retryPolicy = task.retryPolicy &&
+    const specRetryPolicy = task.retryPolicy &&
         (isSafeReadOnlyPiRetryCandidate(task) ||
             isWriterEmptyDiffRetryCandidate(task) ||
             isWriterTransportRetryCandidate(task))
         ? task.retryPolicy
         : undefined;
+    const implicitVerifyRetryPolicy = specRetryPolicy === undefined &&
+        isCanonicalFinalVerifyShellRetryCandidate(task) &&
+        isTargetTemplateTransientRetryNode(task)
+        ? VERIFY_SHELL_RETRY_POLICY
+        : undefined;
+    const retryPolicy = specRetryPolicy ?? implicitVerifyRetryPolicy;
     const maxAttempts = retryPolicy?.maxAttempts ?? 1;
     const attempts = [];
     let totalAttemptWallDurationMs = 0;
@@ -943,6 +959,7 @@ export async function executeDagNode(input) {
         const attemptFinishedAt = new Date().toISOString();
         const attemptWallDurationMs = durationBetween(attemptStartedAt, attemptFinishedAt);
         totalAttemptWallDurationMs += attemptWallDurationMs;
+        const rawFailureCategory = result.rawFailureCategory ?? result.failureCategory;
         const attemptRecord = {
             attempt: attemptNumber,
             startedAt: attemptStartedAt,
@@ -954,6 +971,7 @@ export async function executeDagNode(input) {
             stderr: result.stderr,
             assistantText: result.assistantText,
             failureCategory: result.failureCategory,
+            ...(rawFailureCategory ? { rawFailureCategory } : {}),
             backend: result.backend,
             sdkAttempted: result.sdkAttempted,
             tokensUsed: result.tokensUsed,

package/dist/workflows/dag/retry-policy.js

@@ -165,6 +165,36 @@ export const WRITER_TRANSPORT_RETRY_POLICY = {
     maxDelayMs: 30000,
     retryCategories: [WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY],
 };
+/**
+ * Implicit runtime retry for canonical final verify shells. Not a DagRetryPolicy:
+ * `spawn-error` / `test-timeout` are runtime command categories and must not enter
+ * `dagRetryPolicySchema` / `ALL_DAG_RETRY_CATEGORIES`.
+ */
+export const VERIFY_SHELL_RETRY_CATEGORIES = [
+    "timeout",
+    "spawn-error",
+    "test-timeout",
+];
+export const VERIFY_SHELL_RETRY_POLICY = {
+    maxAttempts: 2,
+    backoff: "exponential",
+    initialDelayMs: 2000,
+    maxDelayMs: 30000,
+    retryCategories: VERIFY_SHELL_RETRY_CATEGORIES,
+};
+export const TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE = "standard-reviewed-supervised-v1";
+/**
+ * Target-template exclusive implement-pi transport retry. Same schema category
+ * as frontend (`writer-clean-timeout`) so DagSpec validation stays unchanged;
+ * only the delay cap is wider. Do not mutate {@link WRITER_TRANSPORT_RETRY_POLICY}.
+ */
+export const TARGET_TEMPLATE_WRITER_TRANSPORT_RETRY_POLICY = {
+    maxAttempts: 2,
+    backoff: "exponential",
+    initialDelayMs: 5000,
+    maxDelayMs: 60000,
+    retryCategories: [WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY],
+};
 /**
  * Backend-test generation writers: empty-diff once, plus bounded incomplete-write-set
  * recovery attempts driven by Completeness Gate (missing/broken target files).
@@ -238,6 +268,67 @@ export function isWriterTransportRetryCandidate(task) {
         task.writerOutcomePolicy?.type === "implementation-outcome-v1" &&
         task.writerOutcomePolicy.requireChangedFiles !== true);
 }
+/**
+ * Canonical standard exclusive `implement-pi` only. Frontend designers and
+ * completeness writers stay on the existing timeout-only transport candidate.
+ */
+export function isTargetTemplateImplementPi(task) {
+    return isWriterTransportRetryCandidate(task) && task.id === "implement-pi";
+}
+export function hasTargetTemplateTransientRetryProfile(task) {
+    return (task?.transientRetryProfile === TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE);
+}
+/**
+ * Dual-condition eligibility: canonical shape AND generated-path stamp.
+ * Custom / other-template nodes that only match id or shape stay ineligible.
+ */
+export function isTargetTemplateTransientRetryNode(task) {
+    if (!hasTargetTemplateTransientRetryProfile(task))
+        return false;
+    return (isCanonicalFinalVerifyShellRetryCandidate(task) ||
+        isTargetTemplateImplementPi(task));
+}
+/**
+ * Shape-based eligibility for implicit canonical final verify-shell retry.
+ * Does not consult node id or a template field.
+ */
+export function isCanonicalFinalVerifyShellRetryCandidate(task) {
+    if (task.executor !== "shell")
+        return false;
+    if (task.role !== "verifier")
+        return false;
+    if (task.writePolicy !== undefined &&
+        task.writePolicy !== "read-only" &&
+        task.writePolicy !== "none") {
+        return false;
+    }
+    if ((task.writeSet?.length ?? 0) > 0)
+        return false;
+    const shell = task.shell;
+    if (!shell || (shell.commands?.length ?? 0) === 0)
+        return false;
+    const evidence = shell.verifyEvidence;
+    if (!evidence)
+        return false;
+    if (evidence.phase !== "final")
+        return false;
+    if (evidence.quota !== "full")
+        return false;
+    if (evidence.commandSource !== "adapter")
+        return false;
+    if (evidence.finalFullRequired !== true)
+        return false;
+    if (shell.frontendPrewriteGate ||
+        shell.frontendVerificationBundle ||
+        shell.frontendBrowserToolPreflight ||
+        shell.backendTestPipeline ||
+        shell.jacocoCoverage ||
+        shell.repairArtifactGate ||
+        shell.verdictGate) {
+        return false;
+    }
+    return true;
+}
 export function isSafeReadOnlyPiRetryCandidate(task) {
     if (task.executor !== "pi")
         return false;

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"]);
@@ -849,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/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/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.27",
+  "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();
+}