@12ui/design 0.2.27 → 0.2.28

package/dist/cli-auth-command.js

@@ -1,8 +1,10 @@
 import { readStoredConversionCredentials, removeStoredConversionCredentials, resolveCredentialFile, } from './credential-store.js';
+import { MissingTwelveUiCredentialError } from './cli-auth-onboarding.js';
 import { setUpConversionCredentials } from './credential-setup.js';
 import { booleanFlag, stringFlag } from './cli-arguments.js';
 import { declareClientVersion } from './client-version.js';
 import { usageRefusal } from './cli-usage.js';
+import { hasConfiguredConversionCredential } from './config.js';
 import { revokeConvertApiKey, TWELVE_UI_DEVICE_SCOPES, verifyTwelveUiCredential, } from './login-auth.js';
 const readQuota = async (origin, apiKey) => {
     const response = await fetch(`${origin}/api/v1/convert/quota`, {
@@ -57,6 +59,9 @@ export const runAuthCommand = async (action, flags) => {
     }
     const stored = await readStoredConversionCredentials();
     if (!stored) {
+        if (!hasConfiguredConversionCredential(stringFlag(flags, 'api-key'))) {
+            throw new MissingTwelveUiCredentialError();
+        }
         throw new Error(`12ui credentials are not configured at ${resolveCredentialFile()}`);
     }
     if (action === 'status') {

package/dist/cli-auth-command.js.map

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

package/dist/cli-auth-onboarding.d.ts

@@ -0,0 +1,12 @@
+export declare const TWELVE_UI_CONNECT_CLI_URL = "https://12ui.com/connect-cli";
+export declare const authOnboardingMessage: (options?: {
+    agentFacing?: boolean;
+    approvalUrl?: string;
+}) => string;
+export declare const printAuthOnboarding: (options?: {
+    approvalUrl?: string;
+}) => void;
+export declare class MissingTwelveUiCredentialError extends Error {
+    constructor(approvalUrl?: string);
+}
+//# sourceMappingURL=cli-auth-onboarding.d.ts.map

package/dist/cli-auth-onboarding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-auth-onboarding.d.ts","sourceRoot":"","sources":["../src/cli-auth-onboarding.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,yBAAyB,iCAAiC,CAAC;AASxE,eAAO,MAAM,qBAAqB,GAAI,UAAS;IAC7C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACjB,KAAG,MAGG,CAAC;AAEb,eAAO,MAAM,mBAAmB,GAAI,UAAS;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;CACjB,KAAG,IAIR,CAAC;AAEF,qBAAa,8BAA+B,SAAQ,KAAK;gBAC3C,WAAW,CAAC,EAAE,MAAM;CAIjC"}

package/dist/cli-auth-onboarding.js

@@ -0,0 +1,21 @@
+export const TWELVE_UI_CONNECT_CLI_URL = 'https://12ui.com/connect-cli';
+const ownerAuthOnboardingLines = (approvalUrl) => [
+    `Sign in/Create an account with this magic link: ${approvalUrl}`,
+    'Takes 5 seconds and you can use 12ui for free.',
+];
+const AGENT_AUTH_ONBOARDING_LINE = 'Agent: Give this link to your user, then retry after they connect 12ui.';
+export const authOnboardingMessage = (options = {}) => [
+    ...ownerAuthOnboardingLines(options.approvalUrl ?? TWELVE_UI_CONNECT_CLI_URL),
+    ...(options.agentFacing ? [AGENT_AUTH_ONBOARDING_LINE] : []),
+].join('\n');
+export const printAuthOnboarding = (options = {}) => {
+    for (const line of ownerAuthOnboardingLines(options.approvalUrl ?? TWELVE_UI_CONNECT_CLI_URL))
+        console.log(line);
+};
+export class MissingTwelveUiCredentialError extends Error {
+    constructor(approvalUrl) {
+        super(authOnboardingMessage({ agentFacing: true, approvalUrl }));
+        this.name = 'MissingTwelveUiCredentialError';
+    }
+}
+//# sourceMappingURL=cli-auth-onboarding.js.map

package/dist/cli-auth-onboarding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-auth-onboarding.js","sourceRoot":"","sources":["../src/cli-auth-onboarding.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,yBAAyB,GAAG,8BAA8B,CAAC;AAExE,MAAM,wBAAwB,GAAG,CAAC,WAAmB,EAAqB,EAAE,CAAC;IAC3E,mDAAmD,WAAW,EAAE;IAChE,gDAAgD;CACjD,CAAC;AAEF,MAAM,0BAA0B,GAAG,yEAAyE,CAAC;AAE7G,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,UAGlC,EAAE,EAAU,EAAE,CAAC;IACjB,GAAG,wBAAwB,CAAC,OAAO,CAAC,WAAW,IAAI,yBAAyB,CAAC;IAC7E,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;CAC7D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,UAEhC,EAAE,EAAQ,EAAE;IACd,KAAK,MAAM,IAAI,IAAI,wBAAwB,CACzC,OAAO,CAAC,WAAW,IAAI,yBAAyB,CACjD;QAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC,CAAC;AAEF,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IACvD,YAAY,WAAoB;QAC9B,KAAK,CAAC,qBAAqB,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;QACjE,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;IAC/C,CAAC;CACF"}

package/dist/cli-branch-command.d.ts

@@ -17,10 +17,9 @@ export type ResolvedBranchDirectory = {
     runDir: string | null;
 };
 /**
- * `12ui branch execute <run-dir>` takes the DRAFT run directory and keeps its
- * own records in `<run-dir>/branch`, which is where the skill says the pages
- * land. `--out-dir` stays an alias that names the branch directory outright,
- * for a branch run with no draft behind it.
+ * Execute creates a run directory when none is supplied. `--out-dir` and the
+ * positional used by resume both name the run directory; records live beneath
+ * it in `<run-dir>/branch`.
  *
  * `branch status` accepts either spelling: a directory that already holds
  * branch records is one, and otherwise `<dir>/branch` is tried, so a caller who
@@ -31,26 +30,22 @@ export declare const resolveBranchDirectory: (args: {
     runDirArgument?: string;
     outDirFlag?: string;
 }) => Promise<ResolvedBranchDirectory>;
-/**
- * The opening line is the only estimate a caller has before anything moves, so
- * it is derived from the run's phases rather than asserted. Pages now convert as
- * their own screens land and several at a time, which is why the old sentence —
- * one package per page, serial, ~20m for a site — would now overstate a normal
- * run by roughly a factor of two, and an overstated wait is what makes a caller
- * abandon a run that is on time.
- */
-export declare const branchExecuteBanner: (args: {
-    scope: "page" | "site";
-    outDir: string;
-    convert: boolean;
-    concurrency?: number;
-}) => string;
+/** Validate every execute input before a detached parent creates its workspace. */
+export declare const prepareDetachedBranchDirectory: (args: {
+    flags: CliFlags;
+    workspaceRoot?: string;
+}) => Promise<ResolvedBranchDirectory>;
 export declare const runBranchCommand: (action: string | undefined, flags: CliFlags, dependencies?: {
     readConfig?: typeof readConversionConfig;
     createBranchClient?: (config: ReturnType<typeof readConversionConfig>) => TwelveUiBranchClient;
     createPackageClient?: (config: ReturnType<typeof readConversionConfig>) => TwelveUiConversionPackageClient;
-    /** The positional `<run-dir>` from `12ui branch execute <run-dir>`. */
+    /** Internal detached-worker positional, or the public resume run directory. */
     runDirArgument?: string;
+    /** Test-only root for an automatically created run directory. */
+    workspaceRoot?: string;
+    /** Receives the run directory as the command's first output line. */
+    write?: (line: string) => void;
+    onRunDirectory?: (runDir: string) => void;
     /** Where this command writes down what it did. */
     journal?: RunJournalNotes;
 }) => Promise<void>;

package/dist/cli-branch-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-branch-command.d.ts","sourceRoot":"","sources":["../src/cli-branch-command.ts"],"names":[],"mappings":"AAIA,OAAO,EAA2B,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAG5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAqB,MAAM,oBAAoB,CAAC;AAyB7E,OAAO,EAAE,+BAA+B,EAAE,MAAM,qBAAqB,CAAC;AAQtE;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,QAAQ,MAAM,KAAG,MAAM,GAAG,IAOnE,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,GAAU,MAAM;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,KAAG,OAAO,CAAC,uBAAuB,CAwBlC,CAAC;AAyFF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM;IACxC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,KAAG,MA4BH,CAAC;AAaF,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,MAAM,GAAG,SAAS,EAC1B,OAAO,QAAQ,EACf,eAAc;IACZ,UAAU,CAAC,EAAE,OAAO,oBAAoB,CAAC;IACzC,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,KAAK,oBAAoB,CAAC;IAC/F,mBAAmB,CAAC,EAAE,CACpB,MAAM,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,KAC5C,+BAA+B,CAAC;IACrC,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,OAAO,CAAC,EAAE,eAAe,CAAC;CACtB,KACL,OAAO,CAAC,IAAI,CAsPd,CAAC"}
+{"version":3,"file":"cli-branch-command.d.ts","sourceRoot":"","sources":["../src/cli-branch-command.ts"],"names":[],"mappings":"AAIA,OAAO,EAA2B,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAI5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAqB,MAAM,oBAAoB,CAAC;AAsB7E,OAAO,EAAE,+BAA+B,EAAE,MAAM,qBAAqB,CAAC;AAMtE;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,QAAQ,MAAM,KAAG,MAAM,GAAG,IAOnE,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,GAAU,MAAM;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,KAAG,OAAO,CAAC,uBAAuB,CAuBlC,CAAC;AAoGF,mFAAmF;AACnF,eAAO,MAAM,8BAA8B,GAAU,MAAM;IACzD,KAAK,EAAE,QAAQ,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,KAAG,OAAO,CAAC,uBAAuB,CAoBlC,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,MAAM,GAAG,SAAS,EAC1B,OAAO,QAAQ,EACf,eAAc;IACZ,UAAU,CAAC,EAAE,OAAO,oBAAoB,CAAC;IACzC,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,KAAK,oBAAoB,CAAC;IAC/F,mBAAmB,CAAC,EAAE,CACpB,MAAM,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,KAC5C,+BAA+B,CAAC;IACrC,+EAA+E;IAC/E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,kDAAkD;IAClD,OAAO,CAAC,EAAE,eAAe,CAAC;CACtB,KACL,OAAO,CAAC,IAAI,CA2Ud,CAAC"}

package/dist/cli-branch-command.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { booleanFlag, stringFlag } from './cli-arguments.js';
 import { CliRefusal } from './cli-refusal.js';
 import { usageRefusal } from './cli-usage.js';
+import { prepareOutputDirectory } from './cli-output-paths.js';
 import { readConversionConfig } from './config.js';
 import { TwelveUiBranchClient } from './branch-client.js';
 import { deriveBranchRunKey, executeBranchRun } from './branch-execution.js';
@@ -11,13 +12,12 @@ import { resolveBranchWinner } from './branch-winner.js';
 import { MAX_CONCEPT_CHARACTERS, readConceptValue } from './concept-input.js';
 import { BRANCH_ATTEMPT_FILENAME, BRANCH_COMPLETION_FILENAME, branchAttemptPath, readBranchAttempt, } from './branch-run-record.js';
 import { BRANCH_PROGRESS_FILENAME } from './branch-progress.js';
-import { DRAFT_BRANCH_DIRECTORY } from './draft-workspace.js';
-import { BRANCH_PAGE_CONCURRENCY_DEFAULT, BRANCH_TYPICAL_SITE_PAGES, OPERATION_DURATION_HINTS, branchRunEstimateSeconds, createPackageProgressReporter, formatDuration, narrateCounts, nextActionLine, } from './cli-progress.js';
+import { createDraftWorkspace, DRAFT_BRANCH_DIRECTORY } from './draft-workspace.js';
+import { BRANCH_PAGE_CONCURRENCY_DEFAULT, BRANCH_TYPICAL_SITE_PAGES, branchRunEstimateSeconds, createLongRunningProgress, packageStageUnit, } from './cli-progress.js';
 import { isConversionModel } from './conversion-models.js';
 import { normalizeOptionalIdempotencyKey } from './idempotency-key.js';
 import { TwelveUiConversionPackageClient } from './package-client.js';
 import { isResponsiveConversionQuality, } from './responsive-quality.js';
-const HEARTBEAT_MS = 15_000;
 /**
  * `.12ui/site/.12ui/site/candidates/D.png` — measured in the harness pass, from
  * an agent that resolved the run-directory convention against a cwd that was
@@ -34,10 +34,9 @@ export const nestedRunDirectoryWarning = (target) => {
         + ' working directory — check the run directory you meant before the next command.';
 };
 /**
- * `12ui branch execute <run-dir>` takes the DRAFT run directory and keeps its
- * own records in `<run-dir>/branch`, which is where the skill says the pages
- * land. `--out-dir` stays an alias that names the branch directory outright,
- * for a branch run with no draft behind it.
+ * Execute creates a run directory when none is supplied. `--out-dir` and the
+ * positional used by resume both name the run directory; records live beneath
+ * it in `<run-dir>/branch`.
  *
  * `branch status` accepts either spelling: a directory that already holds
  * branch records is one, and otherwise `<dir>/branch` is tried, so a caller who
@@ -45,13 +44,11 @@ export const nestedRunDirectoryWarning = (target) => {
  * answer instead of a lecture.
  */
 export const resolveBranchDirectory = async (args) => {
-    if (args.outDirFlag)
-        return { branchDir: path.resolve(args.outDirFlag), runDir: null };
-    if (!args.runDirArgument) {
-        throw new CliRefusal('A run directory is required: `12ui branch execute <run-dir>` (the directory `12ui draft`'
-            + ' printed), or `--out-dir <directory>` to name the branch directory outright.', 'branch_run_directory_missing');
+    const named = args.outDirFlag ?? args.runDirArgument;
+    if (!named) {
+        throw new CliRefusal('A run directory is required for resume: `12ui branch resume <run-dir>`.', 'branch_run_directory_missing');
     }
-    const given = path.resolve(args.runDirArgument);
+    const given = path.resolve(named);
     const holdsBranchRecords = await Promise.all([
         BRANCH_ATTEMPT_FILENAME,
         BRANCH_COMPLETION_FILENAME,
@@ -66,7 +63,7 @@ export const resolveBranchDirectory = async (args) => {
         }
     }));
     if (holdsBranchRecords.some(Boolean))
-        return { branchDir: given, runDir: null };
+        return { branchDir: given, runDir: path.dirname(given) };
     return { branchDir: path.join(given, DRAFT_BRANCH_DIRECTORY), runDir: given };
 };
 const warnOnNestedRunDirectory = (targets) => {
@@ -141,43 +138,6 @@ const runEstimate = (args) => branchRunEstimateSeconds({
     concurrency: args.concurrency,
     convert: args.convert,
 });
-/**
- * The opening line is the only estimate a caller has before anything moves, so
- * it is derived from the run's phases rather than asserted. Pages now convert as
- * their own screens land and several at a time, which is why the old sentence —
- * one package per page, serial, ~20m for a site — would now overstate a normal
- * run by roughly a factor of two, and an overstated wait is what makes a caller
- * abandon a run that is on time.
- */
-export const branchExecuteBanner = (args) => {
-    const concurrency = args.concurrency ?? BRANCH_PAGE_CONCURRENCY_DEFAULT;
-    const exact = runEstimate({ scope: args.scope, convert: args.convert, concurrency });
-    // An estimate quoted to the second reads as a promise. The machine-readable
-    // figure stays exact in `--dry-run`; the sentence rounds to the minute.
-    const minutes = (seconds) => Math.max(60, Math.round(seconds / 60) * 60);
-    const estimate = { floor: minutes(exact.floor), ceiling: minutes(exact.ceiling) };
-    const pages = plannedPages(args.scope);
-    return [
-        `12ui branch execute — scope ${args.scope}, blocking until the whole run finishes.`,
-        `Claim and plan ~${formatDuration(OPERATION_DURATION_HINTS.branchClaim)} (buys no image), then`
-            + ` each screen ~${formatDuration(OPERATION_DURATION_HINTS.branchScreen)}`
-            + ` (server budget ${formatDuration(OPERATION_DURATION_HINTS.branchScreenBudget)})`
-            + `${args.convert
-                ? `, then each page converts as its own screens land, up to ${concurrency} at a time`
-                    + ` ~${formatDuration(OPERATION_DURATION_HINTS.branchPackage)} each`
-                    + ` — about ${estimate.floor === estimate.ceiling
-                        ? formatDuration(estimate.ceiling)
-                        : `${formatDuration(estimate.floor)} to ${formatDuration(estimate.ceiling)}`}`
-                    + `${args.scope === 'page' ? ' for one page' : ` for a ${pages}-page site`}`
-                : ''}.`,
-        nextActionLine({
-            what: `A --scope ${args.scope} run`,
-            typicalSeconds: estimate.ceiling,
-            statusCommand: `12ui next ${args.outDir}`,
-            waitHint: 'or leave this command running, which is what --wait already does by default',
-        }),
-    ].join('\n');
-};
 const readPageConcurrency = (flags) => {
     const value = stringFlag(flags, 'page-concurrency');
     if (value === undefined)
@@ -189,6 +149,29 @@ const readPageConcurrency = (flags) => {
     }
     return parsed;
 };
+/** Validate every execute input before a detached parent creates its workspace. */
+export const prepareDetachedBranchDirectory = async (args) => {
+    const existing = stringFlag(args.flags, 'out-dir')?.trim();
+    if (existing)
+        return resolveBranchDirectory({ outDirFlag: existing });
+    await resolveBranchWinner({ flags: args.flags });
+    readScope(args.flags);
+    const concept = await readConcept(args.flags);
+    readConvert(args.flags);
+    readMaxScreens(args.flags);
+    readPageConcurrency(args.flags);
+    const aspect = stringFlag(args.flags, 'aspect')?.trim();
+    if (aspect !== undefined && !['landscape', 'portrait', 'square'].includes(aspect)) {
+        throw new CliRefusal('--aspect must be landscape, portrait, or square', 'branch_aspect_invalid');
+    }
+    normalizeOptionalIdempotencyKey(stringFlag(args.flags, 'idempotency-key'), '--idempotency-key');
+    const paths = await createDraftWorkspace({
+        query: concept,
+        ...(args.workspaceRoot ? { root: args.workspaceRoot } : {}),
+    });
+    await prepareOutputDirectory(paths.branchDir);
+    return { runDir: paths.runDir, branchDir: paths.branchDir };
+};
 export const runBranchCommand = async (action, flags, dependencies = {}) => {
     if (action === 'status') {
         // Merged into `12ui next` in 0.2.20, along with the other three status
@@ -206,14 +189,21 @@ export const runBranchCommand = async (action, flags, dependencies = {}) => {
         });
     }
     const outDirFlag = stringFlag(flags, 'out-dir')?.trim();
-    const resolvedDirectory = await resolveBranchDirectory({
-        ...(outDirFlag ? { outDirFlag } : {}),
-        ...(dependencies.runDirArgument ? { runDirArgument: dependencies.runDirArgument } : {}),
-    });
-    const outDir = resolvedDirectory.branchDir;
+    let resolvedDirectory = outDirFlag || dependencies.runDirArgument
+        ? await resolveBranchDirectory({
+            ...(outDirFlag ? { outDirFlag } : {}),
+            ...(dependencies.runDirArgument ? { runDirArgument: dependencies.runDirArgument } : {}),
+        })
+        : undefined;
+    if (action === 'resume' && !resolvedDirectory) {
+        await resolveBranchDirectory({});
+    }
+    let outDir = resolvedDirectory?.branchDir;
+    if (outDir)
+        await prepareOutputDirectory(outDir);
     warnOnNestedRunDirectory([
         outDirFlag ?? dependencies.runDirArgument,
-        stringFlag(flags, 'winner-image'),
+        stringFlag(flags, 'start'),
     ]);
     const readConfig = dependencies.readConfig ?? readConversionConfig;
     const quiet = booleanFlag(flags, 'quiet');
@@ -221,11 +211,12 @@ export const runBranchCommand = async (action, flags, dependencies = {}) => {
     const pageConcurrency = readPageConcurrency(flags) ?? BRANCH_PAGE_CONCURRENCY_DEFAULT;
     let inputs;
     if (action === 'resume') {
-        const attempt = await readBranchAttempt(branchAttemptPath(outDir));
+        const resumeOutDir = outDir;
+        const attempt = await readBranchAttempt(branchAttemptPath(resumeOutDir));
         if (!attempt) {
             throw new CliRefusal(`This branch run has never been started — there is nothing to resume, and nothing has`
-                + ` failed. There is no branch attempt at ${branchAttemptPath(outDir)}. Start it with`
-                + ' `12ui branch execute --winner-run <crt-id> --winner-slot <slot>'
+                + ` failed. There is no branch attempt at ${branchAttemptPath(resumeOutDir)}. Start it with`
+                + ' `12ui branch execute --start <image.png>'
                 + ` --concept <text,1-${MAX_CONCEPT_CHARACTERS}-chars>`
                 + ' --scope page|site --out-dir <directory>`.', 'branch_nothing_to_resume');
         }
@@ -244,7 +235,7 @@ export const runBranchCommand = async (action, flags, dependencies = {}) => {
             winner = { kind: 'image', imagePath: recorded.imagePath, bytes, mediaType: recorded.mediaType, sha256 };
         }
         inputs = {
-            outDir,
+            outDir: resumeOutDir,
             scope: attempt.scope,
             concept: attempt.concept,
             winner,
@@ -276,15 +267,25 @@ export const runBranchCommand = async (action, flags, dependencies = {}) => {
          * this image before any screen is dispatched. Scope and concept are cheap
          * to re-ask for; a plan call on the wrong design is not.
          */
-        const winner = await resolveBranchWinner({
-            flags,
-            runDir: resolvedDirectory.runDir,
-            outDir,
-        });
+        const winner = await resolveBranchWinner({ flags, ...(outDir ? { outDir } : {}) });
+        const scope = readScope(flags);
+        const concept = await readConcept(flags);
+        if (!resolvedDirectory) {
+            const paths = await createDraftWorkspace({
+                query: concept,
+                ...(dependencies.workspaceRoot ? { root: dependencies.workspaceRoot } : {}),
+            });
+            resolvedDirectory = { runDir: paths.runDir, branchDir: paths.branchDir };
+            outDir = paths.branchDir;
+            await prepareOutputDirectory(outDir);
+            (dependencies.write ?? ((line) => { process.stdout.write(`${line}\n`); }))(paths.runDir);
+            dependencies.onRunDirectory?.(paths.runDir);
+            dependencies.journal?.note({ workspace: paths.branchDir });
+        }
         inputs = {
-            outDir,
-            scope: readScope(flags),
-            concept: await readConcept(flags),
+            outDir: outDir,
+            scope,
+            concept,
             winner,
             ...(aspect ? { aspect: aspect } : {}),
             ...(readMaxScreens(flags) === undefined ? {} : { maxScreens: readMaxScreens(flags) }),
@@ -305,7 +306,7 @@ export const runBranchCommand = async (action, flags, dependencies = {}) => {
         dependencies.journal?.note({ terminal: false });
         console.log(JSON.stringify({
             dryRun: true,
-            outDir,
+            outDir: outDir,
             origin: config.origin,
             scope: inputs.scope,
             concept: inputs.concept,
@@ -327,75 +328,121 @@ export const runBranchCommand = async (action, flags, dependencies = {}) => {
     }
     const branchClient = (dependencies.createBranchClient ?? ((value) => (new TwelveUiBranchClient(value))))(config);
     const packageClient = (dependencies.createPackageClient ?? ((value) => (new TwelveUiConversionPackageClient(value))))(config);
-    const startedAt = Date.now();
-    const write = (line) => {
-        if (!quiet)
-            process.stderr.write(`${line}\n`);
-    };
-    if (!quiet) {
-        write(branchExecuteBanner({
-            scope: inputs.scope,
-            outDir,
-            convert: Boolean(inputs.convert),
-            concurrency: pageConcurrency,
-        }));
-    }
-    let lastHeartbeat = 0;
-    const elapsed = () => formatDuration((Date.now() - startedAt) / 1000);
-    const reportPackage = createPackageProgressReporter({ write, elapsed });
-    const result = await executeBranchRun({
-        branchClient,
-        packageClient,
-        inputs,
-        origin: config.origin,
-        resume,
-        pageConcurrency,
-        onEvent: (event) => {
-            if (quiet)
-                return;
-            if (event.kind === 'progress') {
-                // A heartbeat even when nothing changed: silence is what a caller reads
-                // as a stall.
-                if (Date.now() - lastHeartbeat < HEARTBEAT_MS)
-                    return;
-                lastHeartbeat = Date.now();
-                const counts = event.screens.reduce((totals, screen) => ({
-                    ...totals,
-                    [screen.status]: (totals[screen.status] ?? 0) + 1,
-                }), {});
-                write(`[${elapsed()}] ${event.phase}: ${narrateCounts([
-                    { label: 'complete', count: counts.succeeded ?? 0 },
-                    { label: 'generating', count: counts.dispatched ?? 0 },
-                    { label: 'waiting on dependencies', count: counts.pending ?? 0 },
-                    { label: 'blocked', count: counts.blocked ?? 0 },
-                    { label: 'failed', count: counts.failed ?? 0 },
-                ])}`);
-                return;
-            }
-            if (event.kind === 'phase') {
-                write(`[${elapsed()}] ${event.phase}${event.detail ? `: ${event.detail}` : ''}`);
-                return;
-            }
-            if (event.kind === 'package') {
-                reportPackage(event.pageId, event.progress);
-                return;
-            }
-            if (event.kind === 'blocked') {
-                write(`[${elapsed()}] screen ${event.slot}: blocked — ${event.waitingOn} failed, so this screen`
-                    + ' can never run. It is terminal, not pending.');
-                return;
-            }
-            if (event.kind === 'failed') {
-                write(`[${elapsed()}] screen ${event.slot}: failed (${event.code})`);
-                return;
-            }
-            if (event.kind === 'succeeded' || event.kind === 'dispatched' || event.kind === 'held' || event.kind === 'in-flight') {
-                write(`[${elapsed()}] screen ${event.slot}: ${event.kind}`);
-                return;
-            }
-            write(`[${elapsed()}] stopped: ${event.code} — ${event.message}`);
+    const estimate = runEstimate({
+        scope: inputs.scope,
+        convert: Boolean(inputs.convert),
+        concurrency: pageConcurrency,
+    });
+    const progress = createLongRunningProgress({
+        label: action === 'resume' ? 'branch resume' : 'branch execute',
+        typicalSeconds: estimate.ceiling,
+        quiet,
+    });
+    progress.brief({
+        request: `${action === 'resume' ? 'branch resume' : 'branch execute'}:`
+            + ` scope ${inputs.scope}${inputs.convert ? `, converting pages to ${inputs.convert.output}` : ''}`,
+        ...(resume
+            ? { free: 'already-settled screens replay free; only unfinished work continues' }
+            : {
+                paid: 'one branch screen per planned slot, plus one package conversion per exported page;'
+                    + ' each complete app state is an exported page',
+            }),
+        done: `screens in ${outDir}/branch/screens${inputs.convert ? `, pages in ${outDir}/branch/pages` : ''}`,
+        expectation: {
+            typicalSeconds: estimate.ceiling,
+            basis: `measured phase medians; a run whose page conversions all overlap generation`
+                + ` finishes nearer ${Math.round(estimate.floor / 60)}m`,
         },
+        blocking: true,
+    });
+    progress.update({
+        stage: resume ? 'resuming' : 'claiming',
     });
+    let result;
+    try {
+        result = await executeBranchRun({
+            branchClient,
+            packageClient,
+            inputs,
+            origin: config.origin,
+            resume,
+            pageConcurrency,
+            onEvent: (event) => {
+                if (event.kind === 'progress') {
+                    // The completion sentinel below owns the one terminal line. The
+                    // orchestrator publishes its terminal phase just before returning;
+                    // rendering that observation as an update says "running | stage
+                    // complete" and then prints completion again.
+                    if (event.phase === 'terminal')
+                        return;
+                    const counts = event.screens.reduce((totals, screen) => ({
+                        ...totals,
+                        [screen.status]: (totals[screen.status] ?? 0) + 1,
+                    }), {});
+                    progress.update({
+                        stage: event.phase,
+                        completed: counts.succeeded ?? 0,
+                        total: event.screens.length,
+                        unit: 'screens generated',
+                        running: counts.dispatched ?? 0,
+                        detail: `${counts.pending ?? 0} waiting, ${counts.blocked ?? 0} blocked,`
+                            + ` ${counts.failed ?? 0} failed`,
+                    });
+                    return;
+                }
+                if (event.kind === 'phase') {
+                    progress.update({
+                        stage: event.phase,
+                        ...(event.detail ? { detail: event.detail } : {}),
+                    });
+                    return;
+                }
+                if (event.kind === 'package') {
+                    // A child package may be terminal while the branch that owns it is
+                    // still live. Do not render the contradictory "running | stage
+                    // succeeded" pair: publishing the child's artifacts is the current
+                    // work from the branch caller's point of view.
+                    const childTerminal = event.progress.stage === 'succeeded';
+                    progress.update({
+                        stage: childTerminal ? 'collecting' : event.progress.stage,
+                        ...(event.progress.completed === undefined ? {} : {
+                            completed: event.progress.completed,
+                            total: event.progress.total,
+                            unit: packageStageUnit(event.progress.stage),
+                        }),
+                        ...(event.progress.running === undefined ? {} : { running: event.progress.running }),
+                        detail: `page ${event.pageId}`,
+                    });
+                    return;
+                }
+                if (event.kind === 'blocked') {
+                    progress.update({
+                        stage: 'dispatching',
+                        detail: `screen ${event.slot} blocked by failed dependency ${event.waitingOn}`,
+                    });
+                    return;
+                }
+                if (event.kind === 'failed') {
+                    progress.update({ stage: 'dispatching', detail: `screen ${event.slot} failed (${event.code})` });
+                    return;
+                }
+                if (event.kind === 'succeeded' || event.kind === 'dispatched' || event.kind === 'held' || event.kind === 'in-flight') {
+                    progress.update({ stage: 'dispatching', detail: `screen ${event.slot} ${event.kind}` });
+                    return;
+                }
+                progress.update({ stage: 'stopped', detail: `${event.code}: ${event.message}` });
+            },
+        });
+    }
+    catch (error) {
+        // The CLI's outer error boundary prints the actionable failure once.
+        // Repeating it here after a structured terminal line is the same noise
+        // class as printing a success terminal twice.
+        progress.finish('stopped', {
+            next: `12ui branch resume ${outDir} continues this run, replaying settled screens free`,
+        });
+        throw error;
+    }
     // The completion sentinel names every screen and page; the journal names the
     // sentinel. A run is terminal here whatever its status: `partial` and
     // `failed` are settled answers, not states to keep polling.
@@ -409,6 +456,29 @@ export const runBranchCommand = async (action, flags, dependencies = {}) => {
         ],
         terminal: true,
     });
+    progress.finish(result.completion.status === 'succeeded' ? 'succeeded' : 'partial', {
+        ...(result.completion.status === 'succeeded'
+            ? {}
+            : {
+                detail: `${result.completion.failedCount} failed,`
+                    + ` ${result.completion.blockedCount} blocked`,
+            }),
+        artifacts: [
+            {
+                name: `${result.completion.succeededCount} of ${result.completion.screenCount} screen(s)`,
+                state: 'generated',
+                path: `${result.completion.outDir}/branch/screens`,
+            },
+            ...result.completion.pages.map((page) => ({
+                name: `page ${page.id}`,
+                state: page.conversion?.status ?? 'not converted',
+                ...(page.conversion && 'outFile' in page.conversion && page.conversion.outFile
+                    ? { path: String(page.conversion.outFile) }
+                    : {}),
+            })),
+        ],
+        next: `completion record: ${result.completionPath}`,
+    });
     console.log(JSON.stringify({
         completionPath: result.completionPath,
         ...result.completion,