@aui.io/apollo 0.1.89 → 0.1.91

package/README.md

@@ -147,6 +147,7 @@ Exit codes: `0` success · `1` runtime/API failure · `2` validation failure ·
 apollo login                               # browser sign-in via the Playground (default)
 apollo login --email you@example.com       # email one-time code, then prompts for it
 apollo login --token "$ACCESS_TOKEN"       # store a pre-issued access token
+apollo whoami                              # who this session acts as, checked with identity
 apollo logout
 ```
 
@@ -156,6 +157,8 @@ Use profiles to keep several accounts side by side (`apollo profile use work`, o
 
 **CI and automation:** set `APOLLO_TOKEN` in the environment and run with
 `--json --no-input`; nothing prompts, and every result is a machine-readable envelope.
+An `APOLLO_TOKEN` run never touches the saved login: an expired token fails with
+`AUTH_ERROR` instead of refreshing into whoever is stored on disk.
 
 ## Working with coding agents
 

package/node_modules/@aui.io/apollo-cli/dist/src/commands/auth.js

@@ -1,7 +1,7 @@
 import { homedir } from "node:os";
 import { environmentDefinition, readCredentials, writeCredentials, } from "@aui.io/apollo-core/config/index.js";
 import { ConfigError } from "@aui.io/apollo-core/errors/index.js";
-import { loginWithBrowser, loginWithOtp, loginWithToken, logout, requestOtp, } from "@aui.io/apollo-core/services/auth.js";
+import { assertSavedSession, loginWithBrowser, loginWithOtp, loginWithToken, logout, requestOtp, whoami, } from "@aui.io/apollo-core/services/auth.js";
 import { createClients } from "@aui.io/apollo-core/services/clients.js";
 import { prompt } from "./prompts.js";
 export function registerAuth(program, runtime) {
@@ -53,6 +53,14 @@ export function registerAuth(program, runtime) {
             "Next: `apollo agent use` to enter a known agent, or `apollo agent import` to pull one.",
         ].join("\n"));
     });
+    program
+        .command("whoami")
+        .description("Show who this session acts as — checked with identity — and where its token came from")
+        .action(async () => {
+        const { context, output } = runtime();
+        const result = await whoami(context, createClients(context).identity);
+        output.result(result, () => renderWhoAmI(result));
+    });
     program
         .command("logout")
         .description("Remove the active Apollo session")
@@ -66,6 +74,7 @@ export function registerAuth(program, runtime) {
     });
 }
 export async function persistSwitchedToken(runtime, token, refreshToken) {
+    assertSavedSession(runtime.context, "an organization switch");
     const credentials = await readCredentials(homedir());
     const current = credentials[runtime.context.profile]?.[runtime.context.environment];
     credentials[runtime.context.profile] ??= {};
@@ -80,4 +89,30 @@ export async function persistSwitchedToken(runtime, token, refreshToken) {
     };
     await writeCredentials(homedir(), credentials);
 }
+function renderWhoAmI(who) {
+    const organization = who.organization_id && who.token_organization_id && who.organization_id !== who.token_organization_id
+        ? `${who.organization_id} (token is scoped to ${who.token_organization_id})`
+        : (who.organization_id ?? "not selected");
+    const source = who.token_source === "env"
+        ? "APOLLO_TOKEN — it never refreshes; set a new one when it expires"
+        : who.refreshable
+            ? "saved login (`apollo login`), refreshes itself"
+            : "saved login (`apollo login`), no refresh token — log in again when it expires";
+    return [
+        `${who.email ?? "unknown email"} (user ${who.user_id ?? "unknown"})`,
+        `Environment:   ${who.environment} (profile "${who.profile}")`,
+        `Organization:  ${organization}`,
+        `Project:       ${who.project_id ?? "not selected"}`,
+        `Token:         ${source}`,
+        `Expires:       ${who.expires_at ? expiry(who.expires_at) : "unknown"}`,
+    ].join("\n");
+}
+function expiry(at, now = Date.now()) {
+    const minutes = Math.round((Date.parse(at) - now) / 60_000);
+    if (Number.isNaN(minutes))
+        return at;
+    if (minutes <= 0)
+        return `${at} (expired)`;
+    return minutes < 120 ? `${at} (in ${minutes}m)` : `${at} (in ${Math.round(minutes / 60)}h)`;
+}
 //# sourceMappingURL=auth.js.map

package/node_modules/@aui.io/apollo-cli/dist/src/commands/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../src/commands/auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../src/commands/auth.ts"],"names":[],"mappings":"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"}

package/node_modules/@aui.io/apollo-cli/dist/src/commands/bundles.d.ts

@@ -12,4 +12,8 @@ export declare function renderRun(view: EvaluationView): string;
  *  judge alone, and says so in the block's title. Rows settled before the
  *  grades existed carry none, and the block stays away. */
 export declare function renderGrades(view: EvaluationView): string[];
+/** A pulled or imported commit that still carries a secret file on the server
+ *  (pushed before secret files stayed local): the file was not written and a
+ *  local copy is untouched, but the values are stored with that commit. */
+export declare function warnServerSecrets(run: CommandRuntime, files: string[] | undefined, tag: string): void;
 export declare function registerBundles(program: Command, runtime: () => CommandRuntime): void;

package/node_modules/@aui.io/apollo-cli/dist/src/commands/bundles.js

@@ -3,20 +3,25 @@ import { homedir } from "node:os";
 import path from "node:path";
 import { renderBundleAudit, renderValidation } from "@aui.io/apollo-core/bundle/validate.js";
 import { defaultCheckoutDir, listCheckouts, registerCheckout, } from "@aui.io/apollo-core/checkouts/registry.js";
-import { branchName, branchState, continuedName, parseVersionTag } from "@aui.io/apollo-core/api/management.js";
+import { branchName, branchState, continuedName, findLiveVersion, liveCommitTag, parseVersionTag, } from "@aui.io/apollo-core/api/management.js";
 import { requireUserId } from "@aui.io/apollo-core/config/index.js";
 import { ConfigError, ValidationError } from "@aui.io/apollo-core/errors/index.js";
 import { assertRuntimeAvailable } from "@aui.io/apollo-core/runtime-version/availability.js";
+import { compareRuntimeFamilies, familyOf } from "@aui.io/apollo-core/runtime-version/index.js";
 import { adviseLocalBundle } from "@aui.io/apollo-core/services/advisor.js";
 import { buildAgent } from "@aui.io/apollo-core/services/builds.js";
 import { annotateRun, awaitRun, pullRun, receiptId, resolveRunId, startEvaluation, startRegression, } from "@aui.io/apollo-core/services/runs.js";
 import { branchLog, importBundle, listVersions, localDiff, pullCheckout, pushBundle, remoteDiff, applyBundleFixes, bundleSourceRoot, validateLocalBundle, } from "@aui.io/apollo-core/services/bundles.js";
-import { describeMerge, diffAgainst, fetchVersion, mergeFrom, } from "@aui.io/apollo-core/services/versions.js";
+import { abortMerge, describeMerge, diffAgainst, fetchVersion, mergeFrom, } from "@aui.io/apollo-core/services/versions.js";
+import { commitDiff, localContentDiff, restoreFiles, showCommit, showCommitFile, } from "@aui.io/apollo-core/services/content.js";
 import { checkoutSchemasDir, installSchemas, } from "@aui.io/apollo-core/schemas/install.js";
 import { createClients } from "@aui.io/apollo-core/services/clients.js";
 import { agentRuntimeVersion, listAgents, useVersion, } from "@aui.io/apollo-core/services/hierarchy.js";
 import { installAgentsPage } from "@aui.io/apollo-core/skills/agents-page.js";
 import { installSkills, } from "@aui.io/apollo-core/skills/install.js";
+import pc from "picocolors";
+import { confirmConsequence } from "./confirm.js";
+import { readStdin } from "./prompts.js";
 import { resolvePickerId } from "./picker.js";
 /** `branch log`'s default page, and apollo's internal page cap. */
 const COMMIT_PAGE = 20;
@@ -29,6 +34,51 @@ function renderDiff(diff) {
     ];
     return rows.length ? rows.join("\n") : "No changes.";
 }
+/** A diff's paths, without its patches — what `--name-only` returns. */
+function pathsOf(diff) {
+    return { added: diff.added, changed: diff.changed, removed: diff.removed };
+}
+/** The paths (A/M/D), then each patch — `git diff`'s order, colored at a terminal. */
+function renderContentDiff(diff, nameOnly, color) {
+    const summary = renderDiff(diff);
+    if (nameOnly)
+        return summary;
+    const patches = Object.keys(diff.patches)
+        .sort()
+        .map((file) => colorPatch((diff.patches[file] ?? "").replace(/^=+\n/, "").replace(/\n$/, ""), color));
+    const byName = diff.nameOnly?.length ? [`Listed by name only: ${diff.nameOnly.join(", ")}.`] : [];
+    return [summary, ...(patches.length > 0 ? ["", patches.join("\n\n")] : []), ...byName].join("\n");
+}
+function colorPatch(patch, color) {
+    if (!color)
+        return patch;
+    return patch
+        .split("\n")
+        .map((line) => line.startsWith("+++") || line.startsWith("---")
+        ? pc.bold(line)
+        : line.startsWith("@@")
+            ? pc.cyan(line)
+            : line.startsWith("+")
+                ? pc.green(line)
+                : line.startsWith("-")
+                    ? pc.red(line)
+                    : line)
+        .join("\n");
+}
+function describeRestore(result) {
+    const verb = result.dryRun ? "Would restore" : "Restored";
+    return [
+        result.restored.length > 0
+            ? `${verb} ${result.restored.length} file(s) as ${result.source} has them:`
+            : `Nothing to restore — the files already match ${result.source}.`,
+        ...result.restored.map((file) => `   ${file}`),
+        ...(result.unchanged.length > 0 ? [`Already as ${result.source} has them: ${result.unchanged.join(", ")}.`] : []),
+        ...(result.kept.length > 0
+            ? [`Kept (not in ${result.source}): ${result.kept.join(", ")} — delete them yourself to discard them.`]
+            : []),
+        ...(result.backup ? [`Your versions are in ${result.backup}/.`] : []),
+    ].join("\n");
+}
 /** The two advisory censuses that ride every green validation — one line
  *  each when quiet, itemized when they have something to say. */
 function censusLines(result) {
@@ -179,10 +229,26 @@ async function runAction(run, builder, kind, root, options) {
     }
     return true;
 }
+/**
+ * A pull that landed on a branch last pushed for a newer runtime family than
+ * this checkout's pin — or a stamped branch in an unpinned checkout — says so:
+ * the next push would move the branch backwards, and `push` refuses that (R6).
+ */
+function runtimeDrift(tag, recorded, pinned) {
+    if (recorded === undefined)
+        return undefined;
+    const family = familyOf(recorded) ?? recorded;
+    if (pinned === undefined) {
+        return `${tag} was pushed for runtime ${recorded}, and this checkout has no runtime pin. Pin it before you push: \`apollo runtime use ${family}\`.`;
+    }
+    return (compareRuntimeFamilies(recorded, pinned) ?? 0) > 0
+        ? `${tag} was pushed for runtime ${recorded}; this checkout is pinned to ${pinned}, an older family. Move the pin before you push: \`apollo runtime use ${family}\`.`
+        : undefined;
+}
 /** A pulled or imported commit that still carries a secret file on the server
  *  (pushed before secret files stayed local): the file was not written and a
  *  local copy is untouched, but the values are stored with that commit. */
-function warnServerSecrets(run, files, tag) {
+export function warnServerSecrets(run, files, tag) {
     if (!files?.length)
         return;
     run.output.warn(`${tag} still carries ${files.join(", ")} on the server, pushed before secret files stayed local. ` +
@@ -384,7 +450,8 @@ export function registerBundles(program, runtime) {
         .option("--max-turns <n>", "most customer messages per conversation")
         .option("--seed <n>", "base seed for the world draws — same seed, same callers")
         .option("--world <pins>", "slot=value pins applied to every simulation, e.g. persona=irate,subject=vase")
-        .option("--return <shape>", "the report structure wanted back, in your words")).action(async (first, second, options) => {
+        .option("--return <shape>", "the report structure wanted back, in your words")
+        .option("--plan-from <evaluation-id>", "replay that evaluation's banked plan against this checkout: the same simulated callers (its seed, turns and pins travel with it), no planning — pairs two runs on identical callers")).action(async (first, second, options) => {
         const run = runtime();
         const clients = createClients(run.context);
         const builder = clients.builder;
@@ -419,6 +486,7 @@ export function registerBundles(program, runtime) {
             config,
             ...(options.message ? { message: options.message } : {}),
             ...(options.versionTag ? { versionTag: options.versionTag } : {}),
+            ...(options.planFrom ? { planFrom: options.planFrom } : {}),
         });
         const runId = receiptId(receipt);
         if (!options.follow) {
@@ -546,34 +614,116 @@ export function registerBundles(program, runtime) {
     });
     program
         .command("diff")
-        .description("Compare local files with the last baseline, or with another version (a tag, a name, or live)")
-        .argument("[ref]", "a version to compare bundle/src with (fetched into bundle/tmp/versions/<tag>)")
-        .option("--remote", "compare with the selected remote version")
-        .action(async (ref, options) => {
+        .description("Show what changed, line by line: local edits against the commit the checkout started from, the checkout against a commit, or two commits")
+        .argument("[ref]", "a commit to compare bundle/src with (fetched into bundle/tmp/versions/<tag>)")
+        .argument("[other]", "a second commit: compares ref → other, nothing local involved")
+        .option("--remote", "compare with the bound branch's newest commit")
+        .option("--name-only", "list the changed paths only (A/M/D), no lines")
+        .addHelpText("after", "\nExamples:\n  apollo diff                 your edits since the last pull or push\n  apollo diff v3.5            v3.5 → your checkout\n  apollo diff v3.4 v3.5       what v3.5 changed\n  apollo diff --name-only     paths only")
+        .action(async (ref, other, options) => {
         const run = runtime();
         const management = createClients(run.context).management;
+        const nameOnly = options.nameOnly === true;
+        const color = Boolean(process.stdout.isTTY) && !run.output.options.json;
+        if (ref && other) {
+            const result = await commitDiff(run.context, management, ref, other);
+            run.output.result(nameOnly ? { from: result.from, to: result.to, ...pathsOf(result) } : result, () => [`${result.from} → ${result.to}`, renderContentDiff(result, nameOnly, color)].join("\n"));
+            return;
+        }
         if (ref) {
             const result = await diffAgainst(run.context, management, ref);
-            run.output.result(result, () => [
+            run.output.result(nameOnly ? { ...result, diff: pathsOf(result.diff) } : result, () => [
                 `${result.fetched.tag} → bundle/src${result.fetched.relation ? ` (${result.fetched.relation}${result.fetched.base ? `; common base ${result.fetched.base}` : ""})` : ""}; their copy: bundle/tmp/versions/${result.fetched.tag}/`,
-                renderDiff(result.diff),
+                renderContentDiff(result.diff, nameOnly, color),
             ].join("\n"));
             return;
         }
-        const diff = options.remote
-            ? await remoteDiff(run.context, management)
-            : await localDiff(run.context);
-        run.output.result(diff, (value) => renderDiff(value));
+        if (options.remote) {
+            const diff = await remoteDiff(run.context, management);
+            run.output.result(nameOnly ? pathsOf(diff) : diff, () => renderContentDiff(diff, nameOnly, color));
+            return;
+        }
+        if (nameOnly) {
+            const diff = await localDiff(run.context);
+            run.output.result(diff, () => renderDiff(diff));
+            return;
+        }
+        const diff = await localContentDiff(run.context, management);
+        if (diff.note)
+            run.output.warn(diff.note);
+        run.output.result(diff, () => renderContentDiff(diff, false, color));
+    });
+    program
+        .command("show")
+        .description("Show one commit: its branch and files — or, with a path, that file's text as the commit has it")
+        .argument("<ref>", "a commit (v3.7), a branch (v3 = its newest commit), a branch name, or live")
+        .argument("[file]", "a program path, as `apollo diff` prints it")
+        .addHelpText("after", "\nExamples:\n  apollo show v3.5                      its files\n  apollo show v3.5 program.yaml         the file, verbatim\n  apollo show live program.yaml > live.yaml")
+        .action(async (ref, file) => {
+        const run = runtime();
+        const management = createClients(run.context).management;
+        if (file !== undefined) {
+            const shown = await showCommitFile(run.context, management, ref, file);
+            run.output.result(shown, () => shown.content.replace(/\n$/, ""));
+            return;
+        }
+        const shown = await showCommit(run.context, management, ref);
+        run.output.result(shown, () => [
+            `${shown.commit} — branch v${shown.branch.number}${shown.branch.label ? ` ("${shown.branch.label}")` : ""}, ${branchState(shown.branch.status)}; ${shown.files.length} file(s)`,
+            ...shown.files.map((item) => `${String(item.bytes).padStart(8)}  ${item.path}`),
+            `\`apollo show ${shown.commit} <file>\` prints one; \`apollo diff ${shown.commit}\` compares it with your checkout.`,
+        ].join("\n"));
+    });
+    program
+        .command("restore")
+        .description("Put program files back the way the checkout's base commit has them — or another commit, with --source")
+        .argument("[files...]", "program paths, as `apollo diff` prints them")
+        .option("--all", "every changed or deleted program file (files the commit does not have are kept)")
+        .option("--source <ref>", "take the text from this commit instead of the checkout's base")
+        .option("--dry-run", "say what would be restored and write nothing")
+        .addHelpText("after", "\nExamples:\n  apollo restore program.yaml                 discard your edits to one file\n  apollo restore --all                        discard every program edit\n  apollo restore policies/refunds.yaml --source v3.5")
+        .action(async (files, options) => {
+        const run = runtime();
+        if (options.all === true && files.length > 0) {
+            throw new ConfigError("Name files or pass --all, not both.");
+        }
+        if (options.all !== true && files.length === 0) {
+            throw new ConfigError("Name the files to restore, or pass --all.", "`apollo diff --name-only` lists what changed.");
+        }
+        const result = await restoreFiles(run.context, createClients(run.context).management, options.all === true ? "all" : files, {
+            ...(options.source ? { source: options.source } : {}),
+            dryRun: options.dryRun === true,
+        });
+        run.output.result(result, () => describeRestore(result));
     });
     program
         .command("merge-from")
         .description("Bring another branch's changes into bundle/src (three-way over the commit both came from); disputed regions keep your text and are listed")
-        .argument("<ref>", "the version to bring in — a tag, a line (v2), a name, or live")
+        .argument("[ref]", "the version to bring in — a tag, a line (v2), a name, or live")
         .option("--only <paths...>", "bring in only these program paths (a cherry-pick)")
         .option("--dry-run", "report what would change without writing")
         .option("--resolved", "every disputed region is decided at your text: a newer commit of your own branch becomes the checkout's base")
+        .option("--abort", "undo the last merge: its files go back, and a base it moved moves back")
+        .option("--force", "with --abort: undo even files edited since the merge (those edits are lost)")
         .action(async (ref, options) => {
         const run = runtime();
+        if (options.abort === true) {
+            if (ref !== undefined || options.only || options.dryRun || options.resolved) {
+                throw new ConfigError("--abort takes no ref and no other option but --force.");
+            }
+            const aborted = await abortMerge(run.context, { force: options.force === true });
+            run.output.result(aborted, () => [
+                `Undid the merge of ${aborted.ref}: ${aborted.restored.length} file(s) put back, ${aborted.removed.length} it created removed.`,
+                ...aborted.restored.map((item) => `M  ${item}`),
+                ...aborted.removed.map((item) => `D  ${item}`),
+                ...(aborted.baselineRestored ? [`The checkout starts from ${aborted.baselineRestored} again.`] : []),
+            ].join("\n"));
+            return;
+        }
+        if (ref === undefined)
+            throw new ConfigError("Name the commit to bring in, or pass --abort.");
+        if (options.force === true)
+            throw new ConfigError("--force goes with --abort.");
         const clients = createClients(run.context);
         const merged = await mergeFrom(run.context, clients, ref, {
             ...(options.only ? { only: options.only } : {}),
@@ -602,6 +752,9 @@ export function registerBundles(program, runtime) {
             schemas: options.schemas,
         });
         warnServerSecrets(run, result.serverSecretFiles, result.pull.version_tag);
+        const drift = runtimeDrift(result.pull.version_tag, result.recordedRuntime, run.context.runtimeVersion);
+        if (drift)
+            run.output.warn(drift);
         run.output.result(result, () => {
             const removed = result.removed.length > 0
                 ? ` Removed ${result.removed.length} local file(s) not in the remote bundle.`
@@ -638,6 +791,8 @@ export function registerBundles(program, runtime) {
         .option("-m, --message <message>", "commit message — recorded on the revision the push mints (not the version's label)")
         .option("--dry-run", "validate and show the diff without pushing")
         .option("--new-version [name]", "push these changes as a new branch cut from the commit they are based on (the way out when the branch moved)")
+        .option("--allow-runtime-downgrade", "push even when that moves the branch to an older runtime family, or strips its runtime stamp")
+        .option("--restamp", "commit the program even if unchanged, so the branch records this checkout's runtime pin (after `apollo runtime use`)")
         .action(async (options) => {
         const run = runtime();
         const clients = createClients(run.context);
@@ -647,6 +802,8 @@ export function registerBundles(program, runtime) {
             ...(options.message ? { commitMessage: options.message } : {}),
             dryRun: options.dryRun === true,
             ...(options.newVersion !== undefined ? { newVersion: options.newVersion } : {}),
+            ...(options.allowRuntimeDowngrade === true ? { allowRuntimeDowngrade: true } : {}),
+            ...(options.restamp === true ? { restamp: true } : {}),
         });
         run.output.result(result, () => {
             // One report, both lanes: program paths bare, build paths prefixed —
@@ -672,6 +829,9 @@ export function registerBundles(program, runtime) {
                         // one place the CLI shows it, since `version list` lists versions
                         // (label, notes) and a revision's commit message lives elsewhere.
                         `Pushed ${result.push.new_version_tag}${result.runtimeVersion ? ` on runtime ${result.runtimeVersion}` : ""}${result.push.commit_message ? ` — "${result.push.commit_message}"` : ""}.`,
+                        ...(result.recovered
+                            ? [`The push's answer was lost on the way back; ${result.push.new_version_tag} is confirmed on the branch with exactly your files.`]
+                            : []),
                         ...(result.newBranch ? [newBranchLine(result.newBranch)] : []),
                         ...(result.live
                             ? [
@@ -680,6 +840,7 @@ export function registerBundles(program, runtime) {
                             : []),
                     ]
                     : []),
+                ...(result.restamp ? [restampLine(result.restamp)] : []),
                 ...(result.buildPush
                     ? [
                         `Pushed build bundle v${result.buildPush.version}` +
@@ -757,14 +918,20 @@ export function registerBundles(program, runtime) {
         // runtime the agent itself records. Pinned before anything the
         // runtime serves is fetched, so the schemas and skills below come
         // from that engine rather than the gateway default.
-        const runtimeVersion = await agentRuntimeVersion(clients, resolvedId);
-        const pinned = runtimeVersion
-            ? createClients({ ...run.context, runtimeVersion })
-            : clients;
+        // An explicit --runtime-version / APOLLO_RUNTIME_VERSION wins; else the
+        // imported branch's own record (resolved inside the import), else the
+        // agent's — the same order `agent create` honours (R6).
+        const explicit = run.context.runtimeVersionSource === "flag" || run.context.runtimeVersionSource === "env";
+        const fallback = explicit ? run.context.runtimeVersion : await agentRuntimeVersion(clients, resolvedId);
         const imported = await importBundle(run.context, clients, resolvedId, destination, {
             ...(options.tag ? { tag: options.tag } : {}),
-            ...(runtimeVersion ? { runtimeVersion } : {}),
+            ...(fallback ? { runtimeVersion: fallback } : {}),
+            runtimeVersionExplicit: explicit,
         });
+        const runtimeVersion = imported.binding.runtime_version;
+        const pinned = runtimeVersion
+            ? createClients({ ...run.context, runtimeVersion })
+            : clients;
         warnServerSecrets(run, imported.serverSecretFiles, imported.pull.version_tag);
         // The public floor, filtered by the wire: the index the install
         // fetches carries only public skills, and its sweep deletes managed
@@ -906,9 +1073,32 @@ function registerVersions(program, runtime) {
         const run = runtime();
         const management = createClients(run.context).management;
         const agentId = requiredAgent(run);
-        const selected = await management.resolveVersion(agentId, ref);
+        const { version: selected, tag } = await management.resolveRef(agentId, ref);
         const result = await management.updateVersion(agentId, selected.id, { label: name });
-        run.output.result(result, () => `Renamed ${result.version_tag} to "${result.label ?? name}".`);
+        run.output.result(result, () => `Renamed ${branchName(result)} to "${result.label ?? name}".${wholeBranch(tag, selected)}`);
+    });
+    version
+        .command("notes")
+        .argument("<ref>", "a branch (v2, its name, any of its commits, or live)")
+        .argument("[text]", "the notes; - reads them from stdin")
+        .option("--clear", "remove the branch's notes")
+        .description("Set a branch's notes — what it is for and what to know before using it")
+        .action(async (ref, text, options) => {
+        const run = runtime();
+        if (options.clear === true && text !== undefined) {
+            throw new ConfigError("--clear takes no text.", `\`apollo branch notes ${ref} --clear\` removes them.`);
+        }
+        // Notes from a file or a heredoc end in a newline the branch should not keep.
+        const notes = options.clear === true ? "" : (text === "-" ? await readStdin() : text)?.trimEnd();
+        if (notes === undefined || (notes === "" && options.clear !== true)) {
+            throw new ConfigError("No notes given.", `Pass them as text, \`-\` to read them from stdin, or --clear to remove them.`);
+        }
+        const management = createClients(run.context).management;
+        const agentId = requiredAgent(run);
+        const { version: selected, tag } = await management.resolveRef(agentId, ref);
+        const result = await management.updateVersion(agentId, selected.id, { notes });
+        run.output.result(result, () => `${notes ? `Notes set on ${branchName(result)}` : `Cleared the notes on ${branchName(result)}`}.${wholeBranch(tag, selected)}` +
+            (notes ? ` \`apollo branch get ${branchName(result)}\` shows them.` : ""));
     });
     version
         .command("lock")
@@ -918,9 +1108,9 @@ function registerVersions(program, runtime) {
         const run = runtime();
         const management = createClients(run.context).management;
         const agentId = requiredAgent(run);
-        const selected = await management.resolveVersion(agentId, ref);
+        const { version: selected, tag } = await management.resolveRef(agentId, ref);
         const result = await management.lockVersion(agentId, selected.id, run.context.userId ?? "apollo-cli");
-        run.output.result(result, () => `Locked ${result.version_tag} — no more commits land on it, and what customers get has not changed. ` +
+        run.output.result(result, () => `Locked ${result.version_tag} — no more commits land on it, and what customers get has not changed.${wholeBranch(tag, selected)} ` +
             `\`apollo branch live <ref>\` picks the commit they get; \`apollo branch unlock ${branchName(result)}\` reopens this one; ` +
             `\`apollo branch create --from ${branchName(result)}\` continues the work in a new draft.`);
     });
@@ -932,22 +1122,34 @@ function registerVersions(program, runtime) {
         const run = runtime();
         const management = createClients(run.context).management;
         const agentId = requiredAgent(run);
-        const selected = await management.resolveVersion(agentId, ref);
+        const { version: selected, tag } = await management.resolveRef(agentId, ref);
         const result = await management.unlockVersion(agentId, selected.id);
-        run.output.result(result, () => `Unlocked ${result.version_tag} — commits land on it again. ` +
+        run.output.result(result, () => `Unlocked ${result.version_tag} — commits land on it again.${wholeBranch(tag, selected)} ` +
             `What customers get is unchanged: live is a commit, not a branch's status.`);
     });
     version
         .command("live")
         .argument("<ref>")
+        .option("--dry-run", "say what would change for customers, and change nothing")
         .description("Make one COMMIT live — the exact bundle customers get (also how you roll back)")
-        .action(async (ref) => {
+        .action(async (ref, options) => {
         const run = runtime();
         const management = createClients(run.context).management;
         const agentId = requiredAgent(run);
         // A ref like `v3.7` names a COMMIT; `v3` or a label names the branch,
         // and its newest commit goes live. `resolveRef` keeps the difference.
         const { version: selected, tag } = await management.resolveRef(agentId, ref);
+        const now = await customersGet(management, agentId);
+        if (now.commit === tag) {
+            run.output.result({ live: tag, changed: false }, () => `${tag} is already live for "${now.name}" — nothing to do.`);
+            return;
+        }
+        const move = `customers of "${now.name}" (${run.context.environment}) move from ${now.commit ?? "nothing live"} to ${tag}`;
+        if (options.dryRun === true) {
+            run.output.result({ dry_run: true, from: now.commit ?? null, to: tag }, () => `Dry run: ${move}. Nothing changed.`);
+            return;
+        }
+        await confirmConsequence(program, run.output, { summary: `Make ${tag} live: ${move}`, typed: tag });
         const live = await management.activateSave(agentId, selected.id, tag);
         run.output.result(live, () => {
             const got = live.active_version_tag ?? tag;
@@ -988,11 +1190,23 @@ function registerVersions(program, runtime) {
         .option("--notes <notes>")
         .action(async (options) => {
         const run = runtime();
-        const management = createClients(run.context).management;
+        const clients = createClients(run.context);
+        const management = clients.management;
         const agentId = requiredAgent(run);
         const from = options.from ? await management.resolveRef(agentId, options.from) : undefined;
+        // An empty or template branch is seeded by the registry, and the seed
+        // follows the runtime it is told: say nothing and a runtime v2 agent
+        // gets a runtime v1 skeleton (R15). The checkout's pin wins, else the
+        // agent's own runtime; a cut from a commit keeps that commit's.
+        const runtimeVersion = from
+            ? undefined
+            : (run.context.runtimeVersion ?? (await agentRuntimeVersion(clients, agentId)));
+        if (!from && runtimeVersion === undefined) {
+            throw new ConfigError("Cannot tell which engine the new branch should target.", "Pass --runtime-version <build> (see `apollo runtime list`).");
+        }
         const created = await management.createVersion(agentId, {
             source: from ? "version" : options.template ? "template" : "empty",
+            ...(runtimeVersion === undefined ? {} : { runtimeVersion }),
             createdBy: requireUserId(run.context, "branch"),
             ...(from ? { fromVersion: from.version.id, fromVersionTag: from.tag } : {}),
             ...(options.template ? { fromTemplate: options.template } : {}),
@@ -1009,12 +1223,25 @@ function registerVersions(program, runtime) {
     version
         .command("publish")
         .argument("<tag>")
+        .option("--dry-run", "say what would change for customers, and change nothing")
         .description("The old one-verb ladder: lock the branch AND ship its newest commit. Prefer `branch live`")
-        .action(async (tag) => {
+        .action(async (tag, options) => {
         const run = runtime();
         const management = createClients(run.context).management;
         const agentId = requiredAgent(run);
-        const selected = await management.resolveVersion(agentId, tag);
+        const { version: selected, tag: commit } = await management.resolveRef(agentId, tag);
+        // publish ships the branch's NEWEST commit. Naming an older one used to
+        // ship the newest anyway, with no word (R12).
+        if (commit !== selected.version_tag) {
+            throw new ConfigError(`publish ships ${selected.version_tag}, the newest commit of ${branchName(selected)} — not ${commit}.`, `To ship ${commit}, run \`apollo branch live ${commit}\`: it ships that exact commit and locks nothing.`);
+        }
+        const now = await customersGet(management, agentId);
+        const move = `lock ${branchName(selected)}; customers of "${now.name}" (${run.context.environment}) move from ${now.commit ?? "nothing live"} to ${selected.version_tag}`;
+        if (options.dryRun === true) {
+            run.output.result({ dry_run: true, from: now.commit ?? null, to: selected.version_tag }, () => `Dry run: ${move}. Nothing changed.`);
+            return;
+        }
+        await confirmConsequence(program, run.output, { summary: `Publish ${branchName(selected)}: ${move}`, typed: selected.version_tag });
         const result = await management.publishVersion(agentId, selected.id);
         run.output.result(result, () => `Published ${result.version_tag} — locked the branch and shipped its newest commit. ` +
             `\`apollo branch live <ref>\` ships a commit without locking anything, and can ship an older one.`);
@@ -1022,20 +1249,53 @@ function registerVersions(program, runtime) {
     version
         .command("archive")
         .argument("<tag>")
-        .action(async (tag) => {
+        .option("--force", "archive it even when customers are on it")
+        .description("Retire a branch — it takes no more commits and leaves the list")
+        .action(async (tag, options) => {
         const run = runtime();
         const management = createClients(run.context).management;
         const agentId = requiredAgent(run);
-        const selected = await management.resolveVersion(agentId, tag);
+        const [{ version: selected, tag: commit }, agent] = await Promise.all([
+            management.resolveRef(agentId, tag),
+            management.getAgent(agentId),
+        ]);
+        if (findLiveVersion(agent, [selected]) && options.force !== true) {
+            throw new ConfigError(`${branchName(selected)} serves what customers get (${liveCommitTag(agent, selected)}) — archiving it would retire the live branch.`, "Make another commit live first (`apollo branch live <ref>`), or pass --force to archive it anyway.");
+        }
+        await confirmConsequence(program, run.output, {
+            summary: `Archive ${branchName(selected)}${selected.label ? ` ("${selected.label}")` : ""} of "${agent.name}" (${run.context.environment})`,
+            ...(options.force === true ? { force: true } : {}),
+        });
         const result = await management.archiveVersion(agentId, selected.id);
-        run.output.result(result, () => `Archived ${result.version_tag}.`);
+        run.output.result(result, () => `Archived ${branchName(result)}.${wholeBranch(commit, selected)}`);
     });
 }
+/** What customers get right now, and the agent's name — for a confirmation that says both. */
+async function customersGet(management, agentId) {
+    const [agent, all] = await Promise.all([management.getAgent(agentId), management.listVersions(agentId)]);
+    const live = findLiveVersion(agent, all.results);
+    return { name: agent.name, commit: live ? liveCommitTag(agent, live) : undefined };
+}
+/** A note when an older commit named a branch-wide action: the whole branch is what changed. */
+function wholeBranch(ref, branch) {
+    return ref !== branch.version_tag && parseVersionTag(ref)?.revision !== undefined
+        ? ` (${ref} is one of its commits — this acts on branch ${branchName(branch)}, all of its commits.)`
+        : "";
+}
 function requiredAgent(run) {
     if (!run.context.agentId)
         throw new ConfigError("Select or import an agent first.");
     return run.context.agentId;
 }
+/** What `push --restamp` did with an unchanged program; unpushed and still different is a dry run. */
+function restampLine(restamp) {
+    const was = restamp.from ?? "no runtime";
+    if (restamp.pushed)
+        return `Re-stamped: the branch now records runtime ${restamp.to} (was ${was}); the program did not change.`;
+    if (restamp.from === restamp.to)
+        return `The branch already records runtime ${restamp.to} — nothing to re-stamp.`;
+    return `Dry run: --restamp would commit the unchanged program so the branch records runtime ${restamp.to} (now ${was}).`;
+}
 /** What a push that started a branch says: which branch, cut from where, and why. */
 function newBranchLine(started) {
     const why = started.closed