@withandeo/cli 0.19.7 → 0.19.9

package/dist/main.js

@@ -20,6 +20,7 @@ import { initializeStarter } from "./starter.js";
 import { normalizeAndeoEnvironment } from "./andeo-environment.js";
 import { DOC_TOPICS, readDocumentation, installDocumentation, installedSkillCheck } from "./documentation.js";
 import { capabilityPreflight } from "./capability-preflight.js";
+import { flagEnvironment, flagKey, rolloutPercentage, customerIds } from "./flagship-contract.js";
 const packageMetadata = createRequire(import.meta.url)("../package.json");
 if (typeof packageMetadata.version !== "string" || packageMetadata.version.length === 0) {
     throw new Error("Andeo CLI package version is missing.");
@@ -101,6 +102,8 @@ async function execute(topic, options, cwd, runtime) {
         return { value: await workflowCommand(topic.slice(10), cwd, options, runtime) };
     if (topic.startsWith("email "))
         return { value: await emailCommand(topic.slice(6), cwd, options, runtime) };
+    if (topic.startsWith("flagship "))
+        return { value: await flagshipCommand(topic.slice(9), cwd, options, runtime) };
     switch (topic) {
         case "docs": {
             const name = options.positionals[0];
@@ -223,6 +226,65 @@ async function execute(topic, options, cwd, runtime) {
             return { value: await sourceOperationRetry(cwd, options, runtime) };
         case "source change create":
             return { value: await sourceChangeCreate(cwd, options, runtime) };
+        case "source merge": {
+            const value = await sourceMerge(cwd, options, runtime);
+            return { value, exitCode: value.status === "timeout" ? 3 : value.merge && ["awaiting_approval", "needs_attention", "superseded", "authorization_required", "reconciliation_required", "cancelled"].includes(value.merge.stage) ? 2 : 0 };
+        }
+        case "source merge status":
+        case "source merge resume":
+        case "source merge cancel":
+        case "source merge take-over": {
+            const mergeId = requiredFlag(options, "merge");
+            if (!/^smi_[A-Za-z0-9_-]+$/.test(mergeId))
+                throw new CliError("argument_invalid", "--merge must be a merge intent ID (smi_...).");
+            const key = topic === "source merge take-over" ? requiredFlag(options, "idempotency-key") : undefined;
+            if (key && !/^[A-Za-z0-9:_-]{8,128}$/.test(key))
+                throw new CliError("argument_invalid", "--idempotency-key must contain 8–128 letters, numbers, colons, underscores or hyphens.");
+            const access = await sourceReadAccess(cwd, options, runtime);
+            const current = await access.client.sourceMergeStatus(mergeId);
+            requireLinkedSourceChange(access.projectId, current.merge.projectId);
+            if (current.merge.id !== mergeId || current.merge.repositoryId !== access.repository.id)
+                throw new CliError("source_merge_changed", "The returned merge does not match this repository and intent.");
+            if (topic === "source merge status")
+                return { value: current };
+            return { value: topic === "source merge resume" ? await access.client.resumeSourceMergeById(mergeId)
+                    : key ? await access.client.takeOverSourceMergeById(mergeId, key) : await access.client.cancelSourceMergeById(mergeId) };
+        }
+        case "source change resume": {
+            const access = await sourceReadAccess(cwd, options, runtime);
+            const changeId = requiredSourceChangeRequestId(requiredFlag(options, "change"));
+            const current = await access.client.sourceChangeRequest(changeId);
+            requireLinkedSourceChange(access.projectId, current.changeRequest.projectId);
+            return { value: await access.client.resumeSourceMerge(changeId) };
+        }
+        case "source change cancel":
+        case "source change take-over": {
+            const changeId = requiredSourceChangeRequestId(requiredFlag(options, "change"));
+            const key = topic === "source change take-over" ? requiredFlag(options, "idempotency-key") : null;
+            const access = await sourceReadAccess(cwd, options, runtime);
+            const current = await access.client.sourceChangeRequest(changeId);
+            requireLinkedSourceChange(access.projectId, current.changeRequest.projectId);
+            return { value: key ? await access.client.takeOverSourceMerge(changeId, key) : await access.client.cancelSourceMerge(changeId) };
+        }
+        case "source merge-policy show":
+        case "source merge-policy set": {
+            const access = await sourceReadAccess(cwd, options, runtime);
+            if (topic === "source merge-policy show")
+                return { value: await access.client.sourceMergePolicy(access.repository.id) };
+            const mode = requiredFlag(options, "mode");
+            if (!["human-review", "agent", "administrator-authorized"].includes(mode))
+                throw new CliError("source_merge_policy_invalid", "--mode must be human-review, agent or administrator-authorized.");
+            const principalIds = (options.flags.get("principals") ?? "").split(",").filter(Boolean);
+            if (mode === "administrator-authorized" && principalIds.length)
+                throw new CliError("source_merge_policy_invalid", "Administrator-authorized mode requires exact per-operation approval; omit --principals.");
+            const executionSeconds = options.flags.has("execution-seconds") ? Number(options.flags.get("execution-seconds")) : undefined;
+            if (executionSeconds !== undefined && (!Number.isSafeInteger(executionSeconds) || executionSeconds < 300 || executionSeconds > 86400))
+                throw new CliError("argument_invalid", "--execution-seconds must be between 300 and 86400.");
+            return { value: await access.client.sourceMergePolicy(access.repository.id, { enabled: mode === "agent",
+                    principalIds, validationMode: mode === "administrator-authorized" ? "administrator_authorized" : "native_preview",
+                    buildAdmission: mode === "administrator-authorized" ? "source_only" : "native",
+                    expectedRevision: Number(requiredFlag(options, "expected-revision")), idempotencyKey: requiredFlag(options, "idempotency-key"), executionSeconds }) };
+        }
         case "source change list":
             return { value: await sourceChangeList(cwd, options, runtime) };
         case "source change show":
@@ -1271,6 +1333,86 @@ async function submitProtectedSourcePush(gitRoot, projectId, repository, branch,
         await rm(temporary, { recursive: true, force: true });
     }
 }
+async function sourceMerge(cwd, options, runtime) {
+    if (options.booleans.has("wait") && options.booleans.has("no-wait"))
+        throw new CliError("argument_invalid", "Choose --wait or --no-wait.");
+    const changeId = options.flags.get("change");
+    if (changeId && (options.flags.has("head") || options.flags.has("title")))
+        throw new CliError("argument_invalid", "Choose --change or --head with --title.");
+    const idempotencyKey = requiredFlag(options, "idempotency-key");
+    if (!/^[A-Za-z0-9:_-]{8,128}$/.test(idempotencyKey))
+        throw new CliError("argument_invalid", "--idempotency-key must contain 8–128 letters, numbers, colons, underscores or hyphens.");
+    const timeout = Number(options.flags.get("timeout-seconds") ?? "1200");
+    if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 3600)
+        throw new CliError("argument_invalid", "--timeout-seconds must be between 1 and 3600.");
+    const headBranch = changeId ? undefined : requiredFlag(options, "head");
+    if (headBranch)
+        assertGitBranchName(headBranch);
+    const title = changeId ? undefined : requiredFlag(options, "title");
+    if (changeId)
+        requiredSourceChangeRequestId(changeId);
+    const expectedHead = options.flags.get("expected-head"), expectedSnapshot = options.flags.get("expected-snapshot");
+    if (expectedHead && !/^[a-f0-9]{40}$/.test(expectedHead))
+        throw new CliError("argument_invalid", "--expected-head must be a commit SHA.");
+    if (expectedSnapshot && (!changeId || !Number.isSafeInteger(Number(expectedSnapshot)) || Number(expectedSnapshot) < 1))
+        throw new CliError("argument_invalid", "--expected-snapshot requires --change and a positive integer.");
+    const expectedBase = options.flags.get("expected-base"), policyRevision = options.flags.get("expected-policy-revision");
+    const validationMode = options.flags.get("validation-mode"), continuation = options.flags.get("continuation");
+    const authorize = options.booleans.has("authorize"), dryRun = options.booleans.has("dry-run"), note = options.flags.get("note");
+    if (expectedBase && !/^[a-f0-9]{40}$/.test(expectedBase))
+        throw new CliError("argument_invalid", "--expected-base must be a commit SHA.");
+    if (policyRevision !== undefined && (!/^\d+$/.test(policyRevision) || !Number.isSafeInteger(Number(policyRevision))))
+        throw new CliError("argument_invalid", "--expected-policy-revision must be a nonnegative integer.");
+    if (validationMode !== undefined && validationMode !== "native_preview" && validationMode !== "administrator_authorized")
+        throw new CliError("argument_invalid", "--validation-mode must be native_preview or administrator_authorized.");
+    if (continuation !== undefined && continuation !== "source_only")
+        throw new CliError("argument_invalid", "--continuation must be source_only.");
+    if (note !== undefined && (note.length < 1 || note.length > 1000))
+        throw new CliError("argument_invalid", "--note must contain 1–1000 characters.");
+    if (validationMode === "administrator_authorized") {
+        if (changeId || expectedSnapshot)
+            throw new CliError("argument_invalid", "Administrator-authorized merges use --head and --title without a native change request.");
+        if (!dryRun && (!authorize || !expectedBase || !expectedHead || policyRevision === undefined))
+            throw new CliError("argument_invalid", "Administrator-authorized merges require --authorize, --expected-base, --expected-head and --expected-policy-revision. Use --dry-run to inspect the exact snapshot first.");
+    }
+    else if (authorize || expectedBase !== undefined || policyRevision !== undefined || continuation !== undefined || note !== undefined) {
+        throw new CliError("argument_invalid", "Administrator authorization flags require --validation-mode administrator_authorized.");
+    }
+    const access = await sourceReadAccess(cwd, options, runtime);
+    const result = await access.client.sourceMerge(access.repository.id, { headBranch, title, changeId, idempotencyKey,
+        expectedHead, expectedSnapshot: expectedSnapshot ? Number(expectedSnapshot) : undefined, dryRun,
+        expectedBase, expectedPolicyRevision: policyRevision === undefined ? undefined : Number(policyRevision),
+        validationMode, authorize: validationMode === "administrator_authorized" ? authorize : undefined,
+        continuation: validationMode === "administrator_authorized" ? "source_only" : undefined, note });
+    if (result.merge) {
+        requireLinkedSourceChange(access.projectId, result.merge.projectId);
+        if (result.merge.repositoryId !== access.repository.id)
+            throw new CliError("source_merge_changed", "The returned merge belongs to another repository.");
+    }
+    if (!result.merge || !options.booleans.has("wait"))
+        return result;
+    let merge = result.merge;
+    for (let poll = 0; poll < Math.ceil(timeout / 5); poll++) {
+        if (merge.terminal || ["merged", "deployed", "needs_attention", "publication_not_enabled", "superseded", "authorization_required", "reconciliation_required", "cancelled"].includes(merge.stage))
+            return { ...result, merge };
+        if (merge.stage === "awaiting_approval")
+            return { ...result, merge };
+        await runtime.sleep(Math.min(5000, timeout * 1000 - poll * 5000));
+        const current = merge.changeId ? await access.client.sourceChangeRequest(merge.changeId) : await access.client.sourceMergeStatus(merge.id);
+        if ("changeRequest" in current)
+            requireLinkedSourceChange(access.projectId, current.changeRequest.projectId);
+        if (!current.merge || current.merge.id !== merge.id)
+            throw new CliError("source_merge_changed", "The merge intent changed. Inspect this exact change before continuing.");
+        requireLinkedSourceChange(access.projectId, current.merge.projectId);
+        if (current.merge.repositoryId !== access.repository.id)
+            throw new CliError("source_merge_changed", "The returned merge belongs to another repository.");
+        merge = current.merge;
+    }
+    if (merge.terminal || ["merged", "deployed", "awaiting_approval", "needs_attention", "publication_not_enabled", "superseded", "authorization_required", "reconciliation_required", "cancelled"].includes(merge.stage))
+        return { ...result, merge };
+    return { ...result, status: "timeout", merge: { ...merge, waitTimedOut: true }, next: merge.changeId
+            ? `andeo source change show --change ${merge.changeId} --json` : `andeo source merge status --merge ${merge.id} --json` };
+}
 async function sourceChangeCreate(cwd, options, runtime) {
     const access = await sourceReadAccess(cwd, options, runtime);
     if (access.repository.changeRequestProtection !== "enabled") {
@@ -2324,7 +2466,82 @@ function exampleConfig() {
         returnPath: "/account",
     };
 }
+async function flagshipCommand(command, cwd, options, runtime) {
+    let environment;
+    try {
+        environment = flagEnvironment(requiredFlag(options, "env"));
+    }
+    catch {
+        throw new CliError("flagship_environment_invalid", "Use --env development, preview, or production explicitly.");
+    }
+    const context = await optionalContext(cwd);
+    const projectId = options.flags.get("project") ?? context?.link?.projectId;
+    if (!projectId)
+        throw new CliError("project_required", "Link a project or pass --project.");
+    const { client } = await authenticatedClient(cwd, context?.link ?? null, options, runtime);
+    if (command.startsWith("apps "))
+        return client.flagship(projectId, ["apps", ...(command === "apps ensure" ? ["ensure"] : [])], environment, command === "apps ensure" ? { body: {} } : {});
+    const action = command.slice(6), app = options.positionals[0], key = options.positionals[1];
+    const segments = ["flags", app, ...(key ? [flagKey(key)] : [])];
+    if (action === "list" || action === "get")
+        return client.flagship(projectId, segments, environment);
+    segments.push(action);
+    if (action === "changelog")
+        return client.flagship(projectId, segments, environment);
+    if (action === "evaluate") {
+        const context = requiredFlag(options, "context");
+        if (!context.startsWith("customerId="))
+            throw new CliError("flagship_context_invalid", "Use --context customerId=IDENTIFIER.");
+        const [customerId] = customerIds([context.slice(11)]);
+        return client.flagship(projectId, segments, environment, { customerId });
+    }
+    const revision = options.flags.get("expected-revision");
+    // Read before mutation by default. Server rechecks this revision inside serialization.
+    let expectedRevision;
+    if (revision !== undefined) {
+        expectedRevision = Number(revision);
+        if (!/^\d+$/.test(revision) || !Number.isSafeInteger(expectedRevision))
+            throw new CliError("flagship_revision_invalid", "Expected revision must be a nonnegative integer.");
+    }
+    else if (action === "create")
+        expectedRevision = 0;
+    else
+        expectedRevision = (await client.flagship(projectId, segments.slice(0, -1), environment)).revision;
+    const body = { expectedRevision };
+    if (action === "audience") {
+        const all = options.booleans.has("all"), file = options.flags.get("customer-ids-file");
+        if (all === !!file)
+            throw new CliError("flagship_audience_invalid", "Choose --all or --customer-ids-file.");
+        if (all)
+            body.all = true;
+        else {
+            let value;
+            try {
+                value = JSON.parse(new TextDecoder().decode(await readBoundedFile(resolve(cwd, file), 192 * 1024)));
+            }
+            catch {
+                throw new CliError("flagship_audience_invalid", "The customer ID file must contain a bounded JSON array.");
+            }
+            body.customerIds = customerIds(value);
+        }
+    }
+    if (action === "rollout") {
+        if (requiredFlag(options, "to") !== "on" || requiredFlag(options, "by") !== "customerId")
+            throw new CliError("flagship_rollout_invalid", "V1 supports --to on --by customerId.");
+        const percentage = requiredFlag(options, "percentage");
+        if (!/^(?:\d+)(?:\.\d{1,2})?$/.test(percentage))
+            throw new CliError("flagship_percentage_invalid", "Use a percentage from 0 to 100 with at most two decimals.");
+        body.percentage = rolloutPercentage(Number(percentage));
+    }
+    return client.flagship(projectId, segments, environment, { body });
+}
 function commandTopic(argv) {
+    if (argv[0] === "flagship") {
+        const topic = argv.slice(0, 3).join(" ");
+        if (argv.length < 3 || argv.includes("--help") || argv.includes("-h"))
+            return { topic: "help", values: ["flagship"] };
+        return { topic, values: argv.slice(3) };
+    }
     if (argv.length === 0 || argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
         return { topic: "help", values: argv.slice(1) };
     }
@@ -2339,7 +2556,11 @@ function commandTopic(argv) {
         const child = argv[1];
         if (!child || child.startsWith("--"))
             return { topic: "help", values: [parent] };
-        if (parent === "source" && (child === "default" || child === "history" || child === "operation" || child === "change" || child === "policy" || child === "reconnect" || child === "branch")) {
+        if (parent === "source" && child === "merge" && argv[2] && !argv[2].startsWith("-")) {
+            const topic = `source merge ${argv[2]}`;
+            return argv.includes("--help") || argv.includes("-h") ? { topic: "help", values: [topic] } : { topic, values: argv.slice(3) };
+        }
+        if (parent === "source" && (child === "default" || child === "history" || child === "operation" || child === "change" || child === "policy" || child === "merge-policy" || child === "reconnect" || child === "branch")) {
             const grandchild = argv[2];
             if (!grandchild || grandchild.startsWith("--"))
                 return { topic: "help", values: [`${parent} ${child}`] };
@@ -2374,7 +2595,7 @@ function parseOptions(values) {
     const booleans = new Set();
     const positionals = [];
     const booleanNames = new Set([
-        "json", "token-stdin", "dry-run", "no-wait", "force", "reauthorize",
+        "json", "token-stdin", "dry-run", "no-wait", "force", "reauthorize", "authorize",
         "device", "wait", "no-open", "local", "all", "production",
     ]);
     for (let index = 0; index < values.length; index += 1) {
@@ -2404,6 +2625,20 @@ function parseOptions(values) {
     return { flags, booleans, positionals, json: booleans.has("json") };
 }
 function assertAllowedOptions(topic, options) {
+    if (topic.startsWith("flagship ")) {
+        const common = ["cwd", "json", "api-url", "token-stdin", "profile", "project", "env"];
+        const extras = { "flags create": ["expected-revision"], "flags enable": ["expected-revision"], "flags disable": ["expected-revision"],
+            "flags audience": ["expected-revision", "customer-ids-file", "all"], "flags rollout": ["expected-revision", "to", "percentage", "by"], "flags evaluate": ["context"], "flags reconcile": ["expected-revision"] };
+        const sub = topic.slice(9);
+        if (!["apps ensure", "apps list", "flags list", "flags get", "flags create", "flags enable", "flags disable", "flags audience", "flags rollout", "flags evaluate", "flags changelog", "flags reconcile"].includes(sub))
+            throw new CliError("argument_unknown", "Unknown flagship command.");
+        if ([...options.flags.keys(), ...options.booleans].some(k => ![...common, ...(extras[sub] ?? [])].includes(k)))
+            throw new CliError("argument_unknown", "Unsupported flagship option.");
+        const length = sub.startsWith("apps") ? 0 : sub === "flags list" ? 1 : 2;
+        if (options.positionals.length !== length)
+            throw new CliError("argument_required", `Expected ${length} positional arguments for ${topic}.`);
+        return;
+    }
     const common = ["cwd", "json"];
     const authentication = ["api-url", "token-stdin", "profile"];
     const allowed = {
@@ -2502,6 +2737,17 @@ function assertAllowedOptions(topic, options) {
         "source operation status": [...common, ...authentication, "operation"],
         "source operation retry": [...common, ...authentication, "operation", "no-wait", "timeout-seconds"],
         "source change create": [...common, ...authentication, "project", "title", "description", "base", "head"],
+        "source merge": [...common, ...authentication, "project", "head", "title", "change", "expected-head", "expected-snapshot", "idempotency-key", "dry-run", "wait", "no-wait", "timeout-seconds",
+            "expected-base", "expected-policy-revision", "validation-mode", "authorize", "continuation", "note"],
+        "source merge status": [...common, ...authentication, "project", "merge"],
+        "source merge resume": [...common, ...authentication, "project", "merge"],
+        "source merge cancel": [...common, ...authentication, "project", "merge"],
+        "source merge take-over": [...common, ...authentication, "project", "merge", "idempotency-key"],
+        "source change resume": [...common, ...authentication, "project", "change"],
+        "source change cancel": [...common, ...authentication, "project", "change"],
+        "source change take-over": [...common, ...authentication, "project", "change", "idempotency-key"],
+        "source merge-policy show": [...common, ...authentication, "project"],
+        "source merge-policy set": [...common, ...authentication, "project", "mode", "principals", "expected-revision", "idempotency-key", "execution-seconds"],
         "source change list": [...common, ...authentication, "project", "state"],
         "source change show": [...common, ...authentication, "change"],
         "source change close": [...common, ...authentication, "change"],
@@ -2634,6 +2880,8 @@ function writeOutput(value, options, runtime) {
     runtime.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 function helpText(topic) {
+    if (topic === "flagship")
+        return "Usage: andeo flagship apps ensure|list --env development|preview|production [--project ID] [--json]\n       andeo flagship flags list APP_ID --env ENV\n       andeo flagship flags create|get|enable|disable|changelog|reconcile APP_ID KEY --env ENV [--expected-revision N]\n       andeo flagship flags audience APP_ID KEY --env ENV --customer-ids-file FILE|--all\n       andeo flagship flags rollout APP_ID KEY --env ENV --to on --percentage 5 --by customerId\n       andeo flagship flags evaluate APP_ID KEY --env ENV --context customerId=synthetic-customer-a\n\nDefaults off. Audience and percentage edits preserve each other and do not enable a disabled flag. Changes propagate; pending writes must be reconciled.";
     if (topic === "email" || topic?.startsWith("email "))
         return `Usage: andeo email <capabilities|create|list|cursor|wait|read|messages|retire> [options]
 
@@ -2710,7 +2958,18 @@ Account workflow entitlement is required for new starts. Run status is authorita
         "source operation": "Usage: andeo source operation <status|retry> --operation sop_... [--json]",
         "source operation status": "Usage: andeo source operation status --operation sop_... [--json]\n\nRead durable status and safe evidence for one exact source operation.",
         "source operation retry": "Usage: andeo source operation retry --operation sop_... [--no-wait] [--timeout-seconds N] [--json]\n\nRetry or resume the same durable source operation without changing its reviewed intent. This never publishes production.",
-        "source change": "Usage: andeo source change <create|list|show|close> [options]\n\nCreate and inspect exact preview-backed changes. Approval and landing stay merchant-admin actions in Andeo.",
+        "source change": "Usage: andeo source change <create|list|show|close|resume|cancel|take-over> [options]\n\nCreate and inspect exact preview-backed changes, or recover an accepted merge intent.",
+        "source change cancel": "Usage: andeo source change cancel --change scr_... [--json]\n\nWithdraw new work for an accepted intent. Already-issued effects require readback; source may already be merged.",
+        "source change take-over": "Usage: andeo source change take-over --change scr_... --idempotency-key KEY [--json]\n\nAdministrator only. Records a new bounded authorization for the same exact inputs; then use source change resume.",
+        "source merge": "Usage: andeo source merge --head BRANCH --title TITLE --idempotency-key KEY [--dry-run] [--wait] [--timeout-seconds N] [--json]\n       andeo source merge --change scr_... --idempotency-key KEY [--wait] [--json]\n       andeo source merge --head BRANCH --title TITLE --validation-mode administrator_authorized --expected-base SHA --expected-head SHA --expected-policy-revision N --authorize --idempotency-key KEY [--continuation source_only] [--note TEXT] [--wait] [--json]\n       andeo source merge <status|resume|cancel|take-over> --merge smi_... [options]\n\nRequest exact fast-forward landing. Native review remains the default. Administrator-authorized source-only mode requires saved policy and a current administrator; Andeo does not independently verify checks. Inspect refs and blockers with --dry-run before authorizing. Waiting is bounded and never cancels hosted work.\n\nExamples:\n  andeo source merge --head feature/copy --title \"Update copy\" --idempotency-key account-copy-v1 --dry-run --json\n  andeo source merge --head feature/copy --title \"Update copy\" --idempotency-key account-copy-v1 --wait --json",
+        "source merge status": "Usage: andeo source merge status --merge smi_... [--json]\n\nRead the retained source, validation, authorization, continuation and cleanup outcomes. Source-only merged is successful completion.",
+        "source merge resume": "Usage: andeo source merge resume --merge smi_... [--json]\n\nResume the same exact eligible intent after revalidating authority. Never substitutes a new source snapshot.",
+        "source merge cancel": "Usage: andeo source merge cancel --merge smi_... [--json]\n\nWithdraw new work. Already-issued effects require readback; cancellation cannot undo a merge.",
+        "source merge take-over": "Usage: andeo source merge take-over --merge smi_... --idempotency-key KEY [--json]\n\nAdministrator only. Take ownership of the retained exact source snapshot before resuming.",
+        "source merge-policy": "Usage: andeo source merge-policy <show|set> [options]",
+        "source change resume": "Usage: andeo source change resume --change scr_... [--json]\n\nResume the same eligible merge intent or exact failed publication. Revalidates authority and retained lineage; never creates a replacement build.\n\nExample:\n  andeo source change resume --change scr_... --json",
+        "source merge-policy show": "Usage: andeo source merge-policy show [--json]\n\nRead the saved merge policy and explicit principal grants.",
+        "source merge-policy set": "Usage: andeo source merge-policy set --mode human-review|agent|administrator-authorized [--principals PRINCIPAL_IDS] --expected-revision N --idempotency-key KEY [--json]\n\nAdministrator only. Agent grants are comma-separated stable principal IDs. Administrator-authorized mode requires controlled transport, source-only continuation and exact per-operation approval; omit --principals. This never changes publication policy.\n\nExample:\n  andeo source merge-policy set --mode agent --principals principal_example --expected-revision 0 --idempotency-key merge-policy-v1 --json",
         "source change create": "Usage: andeo source change create --head BRANCH --title TITLE [--description TEXT] [--base BRANCH] [--json]\n\nOpen a review for the exact protected-base and feature-branch SHAs. Andeo binds checks and approval to this immutable snapshot.",
         "source change list": "Usage: andeo source change list [--state open|closed|all] [--json]\n\nList reviewed source changes for this exact linked project.",
         "source change show": "Usage: andeo source change show --change scr_... [--json]\n\nRead exact snapshot, preview, decision, and landing state.",