mergestorm 0.3.9 → 0.3.13

package/dist/commands/review.js

@@ -1,14 +1,194 @@
-import { apiFetch, getMe } from "../api.js";
+import { getMe } from "../api.js";
 import { loadConfig } from "../config.js";
-import { CommandError, DetachedError, isCommandErrorCode } from "../errors.js";
-import { collectChangedFiles, git, parseGithubOriginRepo } from "../git.js";
+import { CommandError, DetachedError, REVIEW_EXIT, isCommandErrorCode, rateLimitedMessage, } from "../errors.js";
 import { discoverTrunk } from "../git-stack.js";
 import { ansi } from "../ui/ansi.js";
 import { renderFindings } from "../ui/findings.js";
-/**
- * Diff base when the user omits args[0]. Prefers origin/HEAD / main / master
- * via discoverTrunk (same as stack create) instead of hardcoding "main".
- */
+import { toReviewJobEnvelope, } from "../ui/job-envelope.js";
+import { MAX_IDEMPOTENCY_KEY_CHARS, REVIEW_POLL_DEFAULT_TIMEOUT_MS, REVIEW_POLL_MAX_TRANSIENT_RETRIES, REVIEW_THREAD_SLUG_RE, ReviewPollTimeoutError, collectReviewInput, isTransientReviewPollError, isTransientReviewPollStatus, loadReviewContext, pollReview, submitReview, } from "./review-client.js";
+export { REVIEW_POLL_MAX_TRANSIENT_RETRIES, isTransientReviewPollError, isTransientReviewPollStatus, };
+/** Same public specialist allowlist as the API contract and migration 117. */
+export const VORTEX_ROUTER_MODES = ["off", "standard", "max", "manual"];
+/** Standard/Max fleet caps; Manual is capped at Max. */
+export const VORTEX_ROUTER_CAPS = { standard: 3, max: 5 };
+export const VORTEX_SPECIALIST_IDS = [
+    "security",
+    "performance",
+    "architecture",
+    "tests",
+    "data",
+    "api",
+    "frontend",
+];
+function isVortexRouterMode(value) {
+    return typeof value === "string" && VORTEX_ROUTER_MODES.includes(value);
+}
+function isVortexSpecialistId(value) {
+    return typeof value === "string" && VORTEX_SPECIALIST_IDS.includes(value);
+}
+function normalizeVortexSpecialistIds(value) {
+    if (!Array.isArray(value))
+        return [];
+    const selected = new Set(value.filter((id) => typeof id === "string" && VORTEX_SPECIALIST_IDS.includes(id)));
+    return VORTEX_SPECIALIST_IDS.filter((id) => selected.has(id));
+}
+const REVIEW_USAGE = "usage: mergestorm review [base] [head] [--json] [--wait|--no-wait] [--timeout seconds] [--router off|standard|max|manual] [--specialists id,id] [--context text] [--context-file path] [--idempotency-key k] [--webhook-url https://…] [--thread slug]";
+function usageError(message = REVIEW_USAGE) {
+    return new CommandError(message, REVIEW_EXIT.usage, "usage");
+}
+function takeFlagValue(args, i, name) {
+    const a = args[i];
+    const prefix = `--${name}=`;
+    const value = a === `--${name}` ? args[i + 1] : a.slice(prefix.length);
+    if (value === undefined || (a === `--${name}` && value.startsWith("--"))) {
+        throw usageError(`--${name} requires a value`);
+    }
+    return { value, i: a === `--${name}` ? i + 1 : i };
+}
+/** Parse the human and machine-safe `review` flags. */
+export function parseReviewArgs(args) {
+    const positional = [];
+    let router;
+    let specialists = [];
+    let format = "pretty";
+    let wait = true;
+    let waitFlag = null;
+    let timeoutMs = REVIEW_POLL_DEFAULT_TIMEOUT_MS;
+    let context;
+    const contextFiles = [];
+    let idempotencyKey;
+    let webhookUrl;
+    let thread;
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === "--json") {
+            format = "json";
+            continue;
+        }
+        if (a === "--wait" || a === "--no-wait") {
+            if (waitFlag && waitFlag !== a)
+                throw usageError("--wait and --no-wait cannot be combined");
+            waitFlag = a;
+            wait = a === "--wait";
+            continue;
+        }
+        if (a === "--timeout" || a.startsWith("--timeout=")) {
+            const value = a === "--timeout" ? args[++i] : a.slice("--timeout=".length);
+            const seconds = Number(value);
+            if (!value || !Number.isFinite(seconds) || seconds <= 0) {
+                throw usageError("--timeout must be a positive number of seconds");
+            }
+            timeoutMs = Math.round(seconds * 1_000);
+            continue;
+        }
+        if (a === "--router" || a.startsWith("--router=")) {
+            const value = a === "--router" ? args[++i] : a.slice("--router=".length);
+            if (!isVortexRouterMode(value)) {
+                throw usageError();
+            }
+            router = value;
+            continue;
+        }
+        if (a === "--specialists" || a.startsWith("--specialists=")) {
+            const value = a === "--specialists" ? args[++i] : a.slice("--specialists=".length);
+            if (!value?.trim()) {
+                throw usageError();
+            }
+            const raw = value.split(",").map((s) => s.trim()).filter(Boolean);
+            if (raw.length === 0)
+                throw usageError();
+            const unknown = raw.filter((id) => !isVortexSpecialistId(id));
+            if (unknown.length > 0) {
+                throw usageError(`Unknown specialist: ${[...new Set(unknown)].join(", ")}`);
+            }
+            specialists = normalizeVortexSpecialistIds(raw);
+            continue;
+        }
+        if (a === "--context-file" || a.startsWith("--context-file=")) {
+            const taken = takeFlagValue(args, i, "context-file");
+            i = taken.i;
+            if (!taken.value.trim())
+                throw usageError("--context-file requires a path");
+            contextFiles.push(taken.value);
+            continue;
+        }
+        if (a === "--context" || a.startsWith("--context=")) {
+            const taken = takeFlagValue(args, i, "context");
+            i = taken.i;
+            context = taken.value;
+            continue;
+        }
+        if (a === "--idempotency-key" || a.startsWith("--idempotency-key=")) {
+            const taken = takeFlagValue(args, i, "idempotency-key");
+            i = taken.i;
+            const key = taken.value.trim();
+            if (!key)
+                throw usageError("--idempotency-key requires a value");
+            if (key.length > MAX_IDEMPOTENCY_KEY_CHARS) {
+                throw usageError(`--idempotency-key is ${key.length} chars; max is ${MAX_IDEMPOTENCY_KEY_CHARS}`);
+            }
+            idempotencyKey = key;
+            continue;
+        }
+        if (a === "--webhook-url" || a.startsWith("--webhook-url=")) {
+            const taken = takeFlagValue(args, i, "webhook-url");
+            i = taken.i;
+            let parsedUrl;
+            try {
+                parsedUrl = new URL(taken.value);
+            }
+            catch {
+                throw usageError("--webhook-url must be an https URL");
+            }
+            if (parsedUrl.protocol !== "https:") {
+                throw usageError("--webhook-url must be an https URL");
+            }
+            webhookUrl = parsedUrl.toString();
+            continue;
+        }
+        if (a === "--thread" || a.startsWith("--thread=")) {
+            const taken = takeFlagValue(args, i, "thread");
+            i = taken.i;
+            const slug = taken.value.trim();
+            if (!REVIEW_THREAD_SLUG_RE.test(slug)) {
+                throw usageError("--thread must be 1–120 chars [A-Za-z0-9._/-]");
+            }
+            thread = slug;
+            continue;
+        }
+        if (a.startsWith("-")) {
+            throw usageError(`unknown flag: ${a}`);
+        }
+        positional.push(a);
+    }
+    if (positional.length > 2)
+        throw usageError();
+    if (specialists.length > 0 && router == null)
+        router = "manual";
+    if (router === "manual" && specialists.length === 0) {
+        throw usageError("usage: mergestorm review [base] [head] --router manual --specialists id,id");
+    }
+    if (router === "manual" && specialists.length > VORTEX_ROUTER_CAPS.max) {
+        throw usageError("usage: mergestorm review [base] [head] --router manual --specialists id,id (manual runs at most 5 specialists)");
+    }
+    if (router === "off" && specialists.length > 0) {
+        throw usageError("--router off cannot be combined with --specialists");
+    }
+    return {
+        base: positional[0],
+        head: positional[1],
+        router,
+        specialists,
+        format,
+        wait,
+        timeoutMs,
+        context,
+        contextFiles,
+        idempotencyKey,
+        webhookUrl,
+        thread,
+    };
+}
 export function resolveReviewBase(explicit, cwd = process.cwd()) {
     if (explicit)
         return explicit;
@@ -16,25 +196,9 @@ export function resolveReviewBase(explicit, cwd = process.cwd()) {
         return discoverTrunk(cwd);
     }
     catch {
-        throw new CommandError("Could not discover trunk branch. Pass an explicit base: mergestorm review <base> [head]");
+        throw new CommandError("Could not discover trunk branch. Pass an explicit base: mergestorm review <base> [head]", REVIEW_EXIT.usage, "usage");
     }
 }
-function sleep(ms, signal) {
-    return new Promise((resolve, reject) => {
-        if (signal?.aborted) {
-            reject(Object.assign(new Error("Aborted"), { name: "AbortError" }));
-            return;
-        }
-        const t = setTimeout(resolve, ms);
-        const onAbort = () => {
-            clearTimeout(t);
-            reject(Object.assign(new Error("Aborted"), { name: "AbortError" }));
-        };
-        signal?.addEventListener("abort", onAbort, { once: true });
-    });
-}
-/** Max consecutive transient poll failures before surfacing an error. */
-export const REVIEW_POLL_MAX_TRANSIENT_RETRIES = 3;
 export function reviewStatusHint(jobId) {
     return `Check: mergestorm status ${jobId}`;
 }
@@ -45,149 +209,224 @@ export function withReviewJobRecovery(message, jobId) {
         return message;
     return `${message.replace(/\s+$/, "")}\n${hint}`;
 }
-/** HTTP statuses worth retrying during review poll (not 401/402/404). */
-export function isTransientReviewPollStatus(status) {
-    return status === 408 || status === 429 || status >= 500;
-}
-/** Network / request-timeout errors worth retrying during review poll. */
-export function isTransientReviewPollError(err) {
-    if (!(err instanceof Error))
-        return false;
-    if (err.name === "AbortError")
-        return false;
-    if (err instanceof CommandError) {
-        return err.code === "api_timeout";
-    }
-    if (err instanceof TypeError && /fetch|network|connection/i.test(err.message))
-        return true;
-    return /fetch failed|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|socket hang up/i.test(err.message);
-}
 function asPollCommandError(err, jobId) {
     if (err instanceof CommandError) {
-        return new CommandError(withReviewJobRecovery(err.message, jobId), err.exitCode, err.code);
+        return new CommandError(withReviewJobRecovery(err.message, jobId), err.exitCode, err.code, err.retryAfterSeconds !== undefined
+            ? { retryAfterSeconds: err.retryAfterSeconds }
+            : undefined);
     }
     const detail = err instanceof Error ? err.message : String(err);
     return new CommandError(withReviewJobRecovery(`Poll failed: ${detail}`, jobId));
 }
 export async function cmdReview(args, opts = {}) {
-    const base = resolveReviewBase(args[0]);
-    const head = args[1] || "HEAD";
-    const cfg = await loadConfig();
-    const meBefore = opts.interactive ? await getMe(cfg) : null;
-    console.log(`Collecting diff ${base}...${head} …`);
-    let diff;
-    try {
-        diff = git(["diff", `${base}...${head}`]);
-    }
-    catch (err) {
-        const detail = err instanceof Error ? err.message : String(err);
-        throw new CommandError(`Could not diff ${base}...${head}: ${detail}. Try \`mergestorm review <base>\` with your trunk branch.`);
-    }
-    if (!diff.trim()) {
-        console.log("No changes to review.");
-        return;
-    }
-    const files = await collectChangedFiles(base, head);
-    const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]).trim() || "local";
-    const thread = `local/${branch}`.replace(/[^a-zA-Z0-9._/-]/g, "-").slice(0, 120);
-    const originRepo = parseGithubOriginRepo();
-    console.log(`Submitting review (${Buffer.byteLength(diff, "utf8")} byte diff, ${files.length} file(s))…`);
-    const { status, body } = await apiFetch(cfg, "/api/v1/reviews", {
-        method: "POST",
-        json: {
-            thread,
-            branch,
-            ...(originRepo ? { repo: `${originRepo.owner}/${originRepo.repo}` } : {}),
-            base_label: base,
-            head_label: head,
-            diff,
-            files,
-        },
-        signal: opts.signal,
-    });
-    if (status === 402) {
-        throw new CommandError("Monthly review limit reached. Upgrade at https://mergestorm.ai/billing");
-    }
-    if (status !== 202 && status !== 200) {
-        throw new CommandError(`Failed: ${JSON.stringify(body, null, 2)}`);
-    }
-    const job = body;
-    const waitHint = opts.interactive
-        ? ` Waiting… (${ansi.dim("ctrl+c to detach — job keeps running")})`
-        : " Waiting…";
-    console.log(`Job ${job.job_id} (${job.status}).${waitHint}`);
-    let transientFailures = 0;
+    const parsed = parseReviewArgs(args);
+    const base = resolveReviewBase(parsed.base);
+    const head = parsed.head || "HEAD";
+    const json = parsed.format === "json";
+    const interactive = Boolean(opts.interactive && !json);
+    const fallback = {
+        baseLabel: base,
+        headLabel: head,
+        routerMode: parsed.router ?? null,
+        specialistsRequested: parsed.specialists,
+    };
+    let jsonPrinted = false;
+    let webhookSecret = null;
+    const printJson = (row, extra = {}) => {
+        const rowWithSecret = {
+            ...(row ?? {}),
+            ...(webhookSecret ? { webhook_secret: webhookSecret } : {}),
+        };
+        console.log(JSON.stringify(toReviewJobEnvelope(rowWithSecret, { ...fallback, ...extra })));
+        jsonPrinted = true;
+    };
+    const progress = (message) => {
+        if (json)
+            console.error(message);
+        else
+            console.log(message);
+    };
     try {
-        for (let i = 0; i < 90; i += 1) {
-            await sleep(2000, opts.signal);
-            let poll;
-            try {
-                poll = await apiFetch(cfg, `/api/v1/reviews/${job.job_id}`, { signal: opts.signal });
+        const cfg = await loadConfig();
+        const meBefore = interactive ? await getMe(cfg) : null;
+        progress(`Collecting diff ${base}...${head} …`);
+        const input = await collectReviewInput(base, head);
+        if (!input) {
+            if (json)
+                printJson(null, { status: "no_changes" });
+            else
+                console.log("No changes to review.");
+            return;
+        }
+        if (parsed.thread)
+            input.thread = parsed.thread;
+        fallback.threadSlug = input.thread;
+        const extras = await loadReviewContext({
+            context: parsed.context,
+            contextFiles: parsed.contextFiles,
+        });
+        progress(`Submitting review (${Buffer.byteLength(input.diff, "utf8")} byte diff, ${input.files.length} file(s))…`);
+        if (parsed.router) {
+            progress(`Fleet router=${parsed.router}${parsed.specialists.length ? ` specialists=${parsed.specialists.join(",")}` : ""}`);
+        }
+        let submitted;
+        try {
+            submitted = await submitReview(cfg, input, {
+                routerMode: parsed.router,
+                specialists: parsed.specialists,
+                context: extras.context,
+                contextFiles: extras.contextFiles,
+                idempotencyKey: parsed.idempotencyKey,
+                webhookUrl: parsed.webhookUrl,
+                signal: opts.signal,
+            });
+        }
+        catch (err) {
+            if (!isTransientReviewPollError(err))
+                throw err;
+            const message = err instanceof Error ? err.message : String(err);
+            if (json)
+                printJson(null, { status: "in_progress", error: message });
+            throw new CommandError(message, REVIEW_EXIT.timeout, "review_timeout");
+        }
+        const jobId = submitted.row.job_id ?? submitted.row.id ?? null;
+        fallback.jobId = jobId;
+        webhookSecret = submitted.row.webhook_secret ?? null;
+        if (submitted.status === 402) {
+            const message = "Review limit reached for this period. Upgrade at https://mergestorm.ai/billing";
+            if (json)
+                printJson(submitted.row, { status: "quota_exceeded", error: message });
+            throw new CommandError(message, REVIEW_EXIT.quota, "review_quota");
+        }
+        if (submitted.status === 429) {
+            const retryAfterSeconds = submitted.retryAfterSeconds;
+            const message = rateLimitedMessage(retryAfterSeconds);
+            if (json) {
+                printJson(submitted.row, {
+                    status: "rate_limited",
+                    error: message,
+                    retryAfterSeconds,
+                });
             }
-            catch (err) {
-                if (opts.interactive && err instanceof Error && err.name === "AbortError") {
-                    throw err;
-                }
-                if (opts.interactive && isCommandErrorCode(err, "api_timeout")) {
-                    throw err;
-                }
-                if (isTransientReviewPollError(err) &&
-                    transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES) {
-                    transientFailures += 1;
-                    if (opts.interactive)
-                        process.stdout.write("?");
-                    continue;
-                }
-                throw asPollCommandError(err, job.job_id);
+            throw new CommandError(message, REVIEW_EXIT.rate_limited, "rate_limited", {
+                retryAfterSeconds,
+            });
+        }
+        if (submitted.status !== 202 && submitted.status !== 200) {
+            const message = `Failed: ${JSON.stringify(submitted.row, null, 2)}`;
+            if (json)
+                printJson(submitted.row, { status: "failed", error: message });
+            throw new CommandError(message, REVIEW_EXIT.failed, "review_failed");
+        }
+        if (!jobId) {
+            const message = "Review API returned no job_id";
+            if (json)
+                printJson(submitted.row, { status: "failed", error: message });
+            throw new CommandError(message, REVIEW_EXIT.failed, "review_failed");
+        }
+        if (!parsed.wait) {
+            if (json)
+                printJson(submitted.row, { jobId });
+            else
+                console.log(`Job ${jobId} (${submitted.row.status ?? "queued"}).`);
+            return;
+        }
+        if (!json) {
+            const waitHint = interactive
+                ? ` Waiting… (${ansi.dim("ctrl+c to detach — job keeps running")})`
+                : " Waiting…";
+            console.log(`Job ${jobId} (${submitted.row.status ?? "queued"}).${waitHint}`);
+        }
+        let row;
+        try {
+            row = await pollReview(cfg, jobId, {
+                timeoutMs: parsed.timeoutMs,
+                intervalMs: opts.pollIntervalMs,
+                signal: opts.signal,
+                propagateTimeout: interactive,
+                onTick(kind) {
+                    if (json)
+                        console.error(kind === "retry" ? "?" : ".");
+                    else
+                        process.stdout.write(kind === "retry" ? "?" : ".");
+                },
+            });
+        }
+        catch (err) {
+            if (opts.interactive && err instanceof Error && err.name === "AbortError") {
+                throw new DetachedError(jobId);
             }
-            if (poll.status !== 200) {
-                if (isTransientReviewPollStatus(poll.status) &&
-                    transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES) {
-                    transientFailures += 1;
-                    if (opts.interactive)
-                        process.stdout.write("?");
-                    continue;
+            if (interactive && isCommandErrorCode(err, "api_timeout")) {
+                throw new DetachedError(jobId);
+            }
+            if (err instanceof ReviewPollTimeoutError) {
+                const message = withReviewJobRecovery("Timed out waiting for review.", jobId);
+                if (json) {
+                    printJson(err.lastRow, {
+                        jobId,
+                        status: err.lastRow.status ?? "in_progress",
+                        error: "Timed out waiting for review.",
+                    });
                 }
-                throw new CommandError(withReviewJobRecovery(`Poll failed: ${JSON.stringify(poll.body, null, 2)}`, job.job_id));
+                throw new CommandError(message, REVIEW_EXIT.timeout, "review_timeout");
             }
-            transientFailures = 0;
-            const row = poll.body;
-            if (row.status === "queued" || row.status === "in_progress") {
-                process.stdout.write(".");
-                continue;
+            if (isCommandErrorCode(err, "rate_limited")) {
+                if (json) {
+                    printJson(null, {
+                        status: "rate_limited",
+                        error: err.message,
+                        retryAfterSeconds: err.retryAfterSeconds,
+                    });
+                }
+                throw asPollCommandError(err, jobId);
             }
+            throw asPollCommandError(err, jobId);
+        }
+        if (!json)
             console.log("");
-            if (row.status === "failed" || row.status === "quota_exceeded") {
-                throw new CommandError(withReviewJobRecovery(`Review ${row.status}: ${row.error ?? ""}`, job.job_id));
-            }
-            console.log(`\nVerdict: ${ansi.bold(row.verdict ?? "comment")}`);
-            console.log(row.summary ?? "");
-            renderFindings(row.findings, { emptyMessage: true });
-            if (opts.interactive && meBefore) {
-                const meAfter = await getMe(cfg);
-                if (meAfter) {
-                    const beforeLeft = meBefore.usage.standard.remaining ?? 0;
-                    const afterLeft = meAfter.usage.standard.remaining ?? 0;
-                    const used = Math.max(0, beforeLeft - afterLeft);
-                    if (used > 0) {
-                        console.log(ansi.dim(`\n${used} credit${used === 1 ? "" : "s"} used · ${afterLeft} remaining`));
-                    }
+        if (row.status === "failed" || row.status === "quota_exceeded") {
+            const message = withReviewJobRecovery(`Review ${row.status}: ${row.error ?? ""}`, jobId);
+            if (json)
+                printJson(row, { jobId });
+            throw new CommandError(message, row.status === "quota_exceeded" ? REVIEW_EXIT.quota : REVIEW_EXIT.failed, row.status === "quota_exceeded" ? "review_quota" : "review_failed");
+        }
+        if (json) {
+            printJson(row, { jobId });
+            return;
+        }
+        console.log(`\nVerdict: ${ansi.bold(row.verdict ?? "comment")}`);
+        const ran = row.specialists_run ?? row.findings?.specialists_run ?? [];
+        if (ran.length > 0)
+            console.log(ansi.dim(`Specialists: ${ran.join(", ")}`));
+        console.log(row.summary ?? "");
+        renderFindings(row.findings, {
+            emptyMessage: true,
+        });
+        if (interactive && meBefore) {
+            const meAfter = await getMe(cfg);
+            if (meAfter) {
+                const beforeLeft = meBefore.usage.standard.remaining ?? 0;
+                const afterLeft = meAfter.usage.standard.remaining ?? 0;
+                const used = Math.max(0, beforeLeft - afterLeft);
+                if (used > 0) {
+                    console.log(ansi.dim(`\n${used} credit${used === 1 ? "" : "s"} used · ${afterLeft} remaining`));
                 }
             }
-            return;
         }
     }
     catch (err) {
-        if (opts.interactive && err instanceof Error && err.name === "AbortError") {
-            throw new DetachedError(job.job_id);
-        }
-        if (opts.interactive && isCommandErrorCode(err, "api_timeout")) {
-            throw new DetachedError(job.job_id);
+        if (err instanceof DetachedError)
+            throw err;
+        if (json &&
+            !jsonPrinted &&
+            !(err instanceof Error && err.name === "AbortError")) {
+            const message = err instanceof Error ? err.message : String(err);
+            printJson(null, { status: "failed", error: message });
         }
-        if (err instanceof CommandError) {
-            throw new CommandError(withReviewJobRecovery(err.message, job.job_id), err.exitCode, err.code);
+        if (err instanceof CommandError &&
+            (err.code === "auth_invalid" || err.code === "missing_api_key")) {
+            throw new CommandError(err.message, REVIEW_EXIT.auth, err.code);
         }
         throw err;
     }
-    throw new CommandError(withReviewJobRecovery("Timed out waiting for review.", job.job_id));
 }

package/dist/commands/stack.d.ts

@@ -1,10 +1,26 @@
-import { adoptStack } from "../api.js";
+import { adoptStack, ensureUpperPark, listStacks, type StackDto } from "../api.js";
 import { loadConfig } from "../config.js";
 import { createPr, findOpenPrNumber } from "../gh.js";
 import { parseGithubOriginRepo } from "../git.js";
-import { branchExists, commitsAheadOf, pushBranch, tipCommitMessage, tipCommitSubject } from "../git-stack.js";
+import { branchExists, commitsAheadOf, fetchRemoteBranch, pushBranch, tipCommitMessage, tipCommitSubject } from "../git-stack.js";
 import { buildPrBodyFromCommit } from "../pr-body.js";
 import { loadStackMeta, saveStackMeta } from "../stack-meta.js";
+/** A registered stack layer that would become the parent of a new layer. */
+export type RegisteredParentHit = {
+    stackId: string;
+    owner: string;
+    repo: string;
+    branch: string;
+    prNumber: number;
+    position: number;
+};
+/** Find a registered stack layer whose branch matches `parentBranch`. */
+export declare function findRegisteredParent(stacks: StackDto[], parentBranch: string, owner?: string, repo?: string): RegisteredParentHit | null;
+/**
+ * Refuse silently growing an already-registered stack.
+ * Local unsubmitted parents are fine; only API-listed layers trip this.
+ */
+export declare function assertMayParentOntoRegistered(parentBranch: string, stacks: StackDto[], extend: boolean, verb: "create" | "submit", owner?: string, repo?: string): RegisteredParentHit | null;
 export declare function requireStackId(raw: string | undefined, usage: string): string;
 /** Parse `owner/repo#12` or `owner/repo 12`. */
 export declare function parseAdoptTarget(args: string[]): {
@@ -17,9 +33,22 @@ export declare function parseStackCreateArgs(args: string[]): {
     name?: string;
     onto?: string;
     trunk?: string;
+    extend: boolean;
+    asJson: boolean;
+};
+/** Parse `stack submit` argv. Exported for tests. */
+export declare function parseStackSubmitArgs(args: string[]): {
+    extend: boolean;
     asJson: boolean;
 };
 export declare function parseStackResetArgs(args: string[]): void;
+/** Injectable seams for unit tests. Production callers omit deps. */
+export type StackCreateDeps = {
+    cwd?: string;
+    listStacks?: typeof listStacks;
+    loadConfig?: typeof loadConfig;
+    parseGithubOriginRepo?: typeof parseGithubOriginRepo;
+};
 /** Injectable seams for unit tests (STRUCT-04). Production callers omit deps. */
 export type StackSubmitDeps = {
     cwd?: string;
@@ -29,6 +58,7 @@ export type StackSubmitDeps = {
     parseGithubOriginRepo?: typeof parseGithubOriginRepo;
     requireGh?: (cwd?: string) => void;
     branchExists?: typeof branchExists;
+    fetchRemoteBranch?: typeof fetchRemoteBranch;
     pushBranch?: typeof pushBranch;
     findOpenPrNumber?: typeof findOpenPrNumber;
     commitsAheadOf?: typeof commitsAheadOf;
@@ -37,7 +67,9 @@ export type StackSubmitDeps = {
     buildPrBodyFromCommit?: typeof buildPrBodyFromCommit;
     createPr?: typeof createPr;
     loadConfig?: typeof loadConfig;
+    listStacks?: typeof listStacks;
     adoptStack?: typeof adoptStack;
+    ensureUpperPark?: typeof ensureUpperPark;
 };
 export declare function cmdStackSubmit(args: string[], deps?: StackSubmitDeps): Promise<void>;
 export declare function cmdStack(args: string[]): Promise<void>;