orizu 0.5.14 → 0.5.15

package/dist/github-setup.js

@@ -17,7 +17,7 @@ import { spawnSync } from 'child_process';
 import { existsSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { authedFetch } from './http.js';
-import { assertWorkspaceDirUsable } from './workspace.js';
+import { assertWorkspaceDirUsable, workspaceExists } from './workspace.js';
 /**
  * Strip terminal control characters from server-supplied strings before they
  * are printed (mirrors index.ts `sanitizeTerminalText`), so a hostile or
@@ -28,7 +28,36 @@ function sanitizeServerText(value) {
     return String(value).replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, '');
 }
 const DEFAULT_POLL_INTERVAL_MS = 2000;
-const DEFAULT_POLL_TIMEOUT_MS = 180000;
+// ALI-1141: long enough for a slow org-picker + repo-selection walk, but the
+// wait MUST be finite — when the App is already installed in the target org,
+// GitHub only offers "Configure" and never redirects to our setup callback, so
+// an unbounded poll would spin forever. (Still under the server's 15-minute
+// nonce TTL, so the poll times out before the server would report `expired`.)
+const DEFAULT_POLL_TIMEOUT_MS = 600000;
+// ALI-1141: after this long with no callback, the likeliest cause is the
+// already-installed org above — surface it instead of heartbeating silently.
+const ALREADY_INSTALLED_HINT_MS = 90000;
+/**
+ * Why the poll can never succeed when the App is already installed in the org
+ * (ALI-1141): GitHub's `installations/new?state=` page then only offers
+ * "Configure", and completing configuration does NOT redirect to the App's
+ * Setup URL with our state nonce — the callback that flips the row out of
+ * `pending` never fires. Printed as a mid-poll hint and folded into the
+ * timeout error so the user is never left with an unexplained hang.
+ */
+function alreadyInstalledHintLines(teamSlug) {
+    return [
+        '   ⚠ GitHub has not called back yet. The most likely cause: the Orizu GitHub',
+        '     App is ALREADY INSTALLED in that org — GitHub then only offers',
+        '     "Configure", and finishing configuration never notifies Orizu, so this',
+        '     wait cannot succeed. Remedies:',
+        '     • Install the App into a DIFFERENT GitHub org for this team (each org',
+        '       installation can be linked to exactly one Orizu team).',
+        '     • If the org is not linked to any Orizu team, uninstall the Orizu App',
+        '       from the org (GitHub → org Settings → GitHub Apps) and re-run',
+        `       \`orizu github link --team ${teamSlug}\` to do a fresh install.`,
+    ];
+}
 function defaultSleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -83,10 +112,12 @@ export async function runGithubLink(teamSlug, io) {
     const sleep = io.sleep ?? defaultSleep;
     const interval = io.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
     const timeout = io.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
-    const deadline = now() + timeout;
+    const started = now();
+    const deadline = started + timeout;
     // Periodic heartbeat so a long install does not look hung; never echoes state.
     const HEARTBEAT_MS = 15000;
-    let lastHeartbeat = now();
+    let lastHeartbeat = started;
+    let printedAlreadyInstalledHint = false;
     for (;;) {
         const poll = await fetcher(`/api/cli/github/link?state=${encodeURIComponent(state)}`);
         if (poll.ok) {
@@ -107,9 +138,20 @@ export async function runGithubLink(teamSlug, io) {
             // status 'pending' → keep waiting.
         }
         if (now() >= deadline) {
-            throw new Error('Timed out waiting for the GitHub App install to complete. ' +
+            // Same actionable message as the mid-poll hint: an already-installed org
+            // is the one known way to reach this timeout with nothing else wrong.
+            throw new Error(`Timed out waiting for the GitHub App install to complete after ${Math.round(timeout / 60000)} minutes. ` +
+                'If the Orizu GitHub App is already installed in that org, GitHub never notifies Orizu when you finish the "Configure" flow — ' +
+                'install the App into a DIFFERENT GitHub org for this team (or uninstall it from the org first if no other Orizu team uses it). ' +
                 `Resume with \`orizu github link --team ${teamSlug}\` after finishing the install.`);
         }
+        if (!printedAlreadyInstalledHint && now() - started >= ALREADY_INSTALLED_HINT_MS) {
+            for (const line of alreadyInstalledHintLines(teamSlug))
+                io.print(line);
+            io.print(`   Still waiting (Ctrl+C to abort; resume later with \`orizu github link --team ${teamSlug}\`)…`);
+            printedAlreadyInstalledHint = true;
+            lastHeartbeat = now();
+        }
         if (now() - lastHeartbeat >= HEARTBEAT_MS) {
             io.print('   …still waiting for the GitHub install to complete.');
             lastHeartbeat = now();
@@ -216,7 +258,7 @@ export async function runHostedAttach(options, io) {
     io.print(`   Cloning ${repoFullName}...`);
     // Clone with the helper inline + the workspace id in the env so the token is
     // brokered on demand and never materializes in the URL or on disk.
-    gitOrThrow(io.git, [
+    const clone = io.git([
         '-c',
         `credential.helper=${CREDENTIAL_HELPER}`,
         '-c',
@@ -225,6 +267,18 @@ export async function runHostedAttach(options, io) {
         cleanUrl,
         options.targetDir,
     ], { env: { ORIZU_WORKSPACE_ID: options.workspaceId } });
+    if (clone.status !== 0) {
+        const detail = clone.stderr || `exit ${clone.status}`;
+        // A local-only workspace (`orizu setup --local`) has orizu.team.json but no
+        // `.git`, so it passes `assertWorkspaceDirUsable` yet fails the clone —
+        // `git clone` refuses the non-empty dir up front and writes nothing, so
+        // every byte in there is the user's workspace, not an incomplete clone.
+        // Never advise deleting it.
+        if (workspaceExists(options.targetDir)) {
+            throw new Error(`git clone failed: ${detail} ${options.targetDir} already holds a local Orizu workspace (orizu.team.json) without a hosted clone, so the workbench repo can't be cloned into it. Don't delete it — move it aside or re-run \`orizu setup\` with \`--workspace <empty-path>\` (or keep it local with \`--local\`).`);
+        }
+        throw new Error(`git clone failed: ${detail} Remove or empty the incomplete clone directory ${options.targetDir}, then re-run \`orizu setup\`.`);
+    }
     // Persist the helper repo-locally for future pull/push (cwd-resolved).
     gitOrThrow(io.git, ['config', 'credential.helper', CREDENTIAL_HELPER], { cwd: options.targetDir });
     gitOrThrow(io.git, ['config', 'credential.useHttpPath', 'true'], { cwd: options.targetDir });

package/dist/help.js

@@ -747,15 +747,27 @@ export const COMMAND_DOCS = [
     },
     {
         path: ['session', 'start'],
-        usage: 'orizu session start [--project <team/project>] [--workspace <dir>] [--json]',
-        summary: 'Start a durable workspace session and print the session id. When run inside the workbench clone (or with --workspace), the remote session branch is fetched and checked out locally, and the exact next git commands are printed.',
+        usage: 'orizu session start [--project <team/project>] [--workspace <dir>] [--json] | orizu session start --hosted (--task <prompt> | --task-file <path>) [--duration <min>] [--project <team/project>] [--tail]',
+        summary: 'Start a durable workspace session, or add --hosted with a task prompt to start a coordinator-managed hosted agent. Plain sessions check out their remote session branch locally when run inside the workbench clone (or with --workspace).',
         group: 'Sessions',
         options: [
             { name: '--project <team/project>', help: 'Optionally scope the session to a project in the attached workspace.' },
             { name: '--workspace <dir>', help: 'Workbench clone directory when not running from inside it.' },
+            { name: '--hosted', help: 'Start a coordinator-managed hosted agent session instead of a plain durable session.' },
+            { name: '--task <prompt>', help: 'Hosted agent task prompt. Mutually exclusive with --task-file.' },
+            { name: '--task-file <path>', help: 'Read the hosted agent task prompt from a UTF-8 file. Mutually exclusive with --task.' },
+            { name: '--duration <min>', help: 'Hosted sandbox duration in minutes (default 60, maximum 1440).' },
+            { name: '--model <provider/model>', help: 'Optional hosted model override.' },
+            { name: '--reasoning-effort <level>', help: 'Optional hosted model reasoning-effort override.' },
+            { name: '--title <title>', help: 'Optional hosted run title.' },
+            { name: '--tail', help: 'Follow the hosted run until it reaches a terminal state.' },
             { name: '--json', help: 'Emit the machine-readable session payload.' },
         ],
-        examples: ['orizu session start', 'orizu session start --project highlight/hip --json'],
+        examples: [
+            'orizu session start',
+            'orizu session start --project highlight/hip --json',
+            'orizu session start --hosted --task-file ./task.md --project highlight/hip --duration 90',
+        ],
     },
     {
         path: ['session', 'status'],

package/dist/hosted-session-cli.js

@@ -34,6 +34,7 @@
  * is injectable, so the whole flow runs in-process against fakes in the
  * local-sim end-to-end test.
  */
+import { readFileSync } from 'fs';
 import { createLocalSimProvider, } from './sandbox-provider.js';
 import { bootstrapHostedSandbox, createBootstrapRunEventSink, } from './hosted-bootstrap.js';
 import { resumeRunEventSink } from './hosted-run-event-sink.js';
@@ -45,6 +46,7 @@ import { hostedBootCommand } from './hosted-boot.js';
 import { mergeJobCommand } from './merge-job.js';
 import { authedFetch } from './http.js';
 import { resolveBaseUrl } from './http.js';
+import { findUnknownOption } from './option-validation.js';
 import { getWorkspaceRoot } from './workspace.js';
 import { attachedWorkspaceId } from './workspace-sync.js';
 import { tailWorkbenchRun } from './workbench-cli.js';
@@ -62,6 +64,13 @@ export const DEFAULT_AGENT_TOKEN_TTL_MINUTES = 60;
  *  before declaring the detached launch a failure. */
 export const DEFAULT_READINESS_TIMEOUT_MS = 30 * 1000;
 export const DEFAULT_READINESS_POLL_MS = 500;
+/** Must match the coordinator Worker's session-start request ceiling. */
+export const MAX_HOSTED_START_BODY_BYTES = 128 * 1024;
+/** `workspace_sessions.id` and `workbench_runs.id` are PostgreSQL UUIDs. The
+ *  server creates both before its coordinator poke, and the Worker injects the
+ *  session id into the final DO body. A representative UUID makes the local
+ *  projection byte-exact without creating either server-side row. */
+const GENERATED_HOSTED_UUID_PLACEHOLDER = '00000000-0000-4000-8000-000000000000';
 /** Non-secret placeholder OpenCode uses to form requests; the firewall proxy
  *  overrides the real Anthropic header (model-key brokering). NEVER a real key. */
 export const ANTHROPIC_DUMMY_KEY = 'sk-ant-orizu-proxy-broker-placeholder';
@@ -590,6 +599,10 @@ export async function startHostedSession(opts) {
     return base;
 }
 function argVal(args, flag) {
+    const inlinePrefix = `${flag}=`;
+    const inlineArg = args.find(arg => arg.startsWith(inlinePrefix));
+    if (inlineArg)
+        return inlineArg.slice(inlinePrefix.length);
     const index = args.indexOf(flag);
     if (index === -1 || index + 1 >= args.length)
         return null;
@@ -597,7 +610,7 @@ function argVal(args, flag) {
     return value.startsWith('--') ? null : value;
 }
 function hasFlag(args, flag) {
-    return args.includes(flag);
+    return args.some(arg => arg === flag || arg.startsWith(`${flag}=`));
 }
 function numFlag(args, flag) {
     const raw = argVal(args, flag);
@@ -606,7 +619,7 @@ function numFlag(args, flag) {
     const parsed = Number(raw);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
-const HOSTED_USAGE = 'Usage: orizu session start --hosted --task "<prompt>" [--duration <min> (default 60, max 1440)] ' +
+const HOSTED_USAGE = 'Usage: orizu session start --hosted (--task "<prompt>" | --task-file <path>) [--duration <min> (default 60, max 1440)] ' +
     '[--model <provider/model>] [--reasoning-effort <level>] [--project <team/project>] ' +
     '[--title <title>] [--tail]\n' +
     'Default: the Orizu server provisions the sandbox (no VERCEL_* or model key needed on your machine); ' +
@@ -616,6 +629,40 @@ const HOSTED_USAGE = 'Usage: orizu session start --hosted --task "<prompt>" [--d
     'Removal is planned after DO-coordinator validation (ALI-1055).\n' +
     'Note (v0, --operator only): if you disconnect, the agent token expires within its TTL (<=60m) and the run ' +
     'finishes cleanly; reconnect with `orizu run tail --run <id>`. The sandbox timeout is independent (up to 24h).';
+const HOSTED_START_OPTIONS = new Set([
+    '--hosted',
+    '--task',
+    '--task-file',
+    '--workspace',
+    '--duration',
+    '--model',
+    '--reasoning-effort',
+    '--project',
+    '--title',
+    '--tail',
+    '--operator',
+    '--provider',
+    '--runtime',
+    '--image',
+    '--snapshot',
+    '--model-key',
+    '--json',
+]);
+const HOSTED_START_VALUE_OPTIONS = new Set([
+    '--task',
+    '--task-file',
+    '--workspace',
+    '--duration',
+    '--model',
+    '--reasoning-effort',
+    '--project',
+    '--title',
+    '--provider',
+    '--runtime',
+    '--image',
+    '--snapshot',
+    '--model-key',
+]);
 /** Printed on EVERY `--operator` use (founder-locked: deprecate NOW, remove
  *  after Phase 6 validation). Loud on purpose. */
 export const OPERATOR_DEPRECATION_WARNING = '! DEPRECATED: --operator (operator-provisioned hosted sessions) is deprecated; ' +
@@ -627,21 +674,65 @@ export const OPERATOR_DEPRECATION_WARNING = '! DEPRECATED: --operator (operator-
  * CLI never reads VERCEL_* or a model key on this path — the server holds them.
  */
 export async function startHostedViaServer(args, workspaceId, task, tail, io, fetcher = (path, init) => authedFetch(path, init)) {
+    const durationMinutes = numFlag(args, '--duration');
+    const model = argVal(args, '--model') ?? undefined;
+    const reasoningEffort = argVal(args, '--reasoning-effort') ?? undefined;
+    const projectSlug = argVal(args, '--project') ?? undefined;
+    const title = argVal(args, '--title') ?? undefined;
     const payload = {
         workspaceId,
         task,
-        durationMinutes: numFlag(args, '--duration'),
-        model: argVal(args, '--model') ?? undefined,
-        reasoningEffort: argVal(args, '--reasoning-effort') ?? undefined,
-        projectSlug: argVal(args, '--project') ?? undefined,
-        title: argVal(args, '--title') ?? undefined,
+        durationMinutes,
+        model,
+        reasoningEffort,
+        projectSlug,
+        title,
     };
+    const serializedPayload = JSON.stringify(payload);
+    const payloadBytes = new TextEncoder().encode(serializedPayload).byteLength;
+    if (payloadBytes > MAX_HOSTED_START_BODY_BYTES) {
+        const message = `Hosted task prompt is too large: request body is ${payloadBytes} bytes; ` +
+            `maximum is ${MAX_HOSTED_START_BODY_BYTES} bytes (128 KiB).`;
+        if (io.json)
+            io.print(JSON.stringify({ ok: false, error: message }));
+        else
+            io.printErr?.(message);
+        return 1;
+    }
+    // Mirror the exact JSON shape that reaches the session Durable Object after
+    // the API creates its UUID run/session rows, normalizes optional strings, and
+    // the Worker injects sessionId. This second guard keeps near-boundary prompts
+    // from triggering server-side state that would only be compensated after a
+    // coordinator 413. Keep this field list in sync with pokeCoordinatorStart in
+    // app/api/cli/hosted-sessions/route.ts.
+    const normalizedModel = model?.trim() || undefined;
+    const normalizedReasoningEffort = reasoningEffort?.trim() || undefined;
+    const coordinatorPayload = JSON.stringify({
+        runId: GENERATED_HOSTED_UUID_PLACEHOLDER,
+        task,
+        durationMinutes: durationMinutes !== undefined && durationMinutes > 0
+            ? durationMinutes
+            : undefined,
+        model: normalizedModel,
+        reasoningEffort: normalizedReasoningEffort,
+        sessionId: GENERATED_HOSTED_UUID_PLACEHOLDER,
+    });
+    const coordinatorPayloadBytes = new TextEncoder().encode(coordinatorPayload).byteLength;
+    if (coordinatorPayloadBytes > MAX_HOSTED_START_BODY_BYTES) {
+        const message = `Hosted task prompt is too large: coordinator request body would be ${coordinatorPayloadBytes} bytes ` +
+            `after generated run/session IDs; maximum is ${MAX_HOSTED_START_BODY_BYTES} bytes (128 KiB).`;
+        if (io.json)
+            io.print(JSON.stringify({ ok: false, error: message }));
+        else
+            io.printErr?.(message);
+        return 1;
+    }
     let response;
     try {
         response = await fetcher('/api/cli/hosted-sessions', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(payload),
+            body: serializedPayload,
         });
     }
     catch (error) {
@@ -709,7 +800,36 @@ export async function hostedCommand(args, io, deps = {}) {
         io.printErr?.('Usage: orizu internal <hosted-loop --context <path> | hosted-boot | merge-job>');
         return 1;
     }
-    const task = argVal(args, '--task');
+    const unknownOption = findUnknownOption(args, HOSTED_START_OPTIONS, HOSTED_START_VALUE_OPTIONS);
+    if (unknownOption) {
+        const followsTaskFlag = args.some((arg, index) => arg === '--task' &&
+            (args[index + 1] === unknownOption || args[index + 1]?.startsWith(`${unknownOption}=`)));
+        const taskValueHint = followsTaskFlag
+            ? '\nTask text beginning with a dash must use --task=<prompt> or --task-file <path>.'
+            : '';
+        io.printErr?.(`unknown option ${unknownOption}${taskValueHint}\n${HOSTED_USAGE}`);
+        return 1;
+    }
+    const inlineTask = argVal(args, '--task');
+    const taskFile = argVal(args, '--task-file');
+    if (hasFlag(args, '--task') && hasFlag(args, '--task-file')) {
+        io.printErr?.(`Use either --task or --task-file, not both.\n${HOSTED_USAGE}`);
+        return 1;
+    }
+    let task = inlineTask;
+    if (taskFile) {
+        try {
+            task = readFileSync(taskFile, 'utf8');
+        }
+        catch (error) {
+            io.printErr?.(`Could not read task file '${taskFile}': ${error instanceof Error ? error.message : String(error)}`);
+            return 1;
+        }
+        if (task.trim().length === 0) {
+            io.printErr?.(`Task file '${taskFile}' is empty or contains only whitespace. Add a task prompt and try again.`);
+            return 1;
+        }
+    }
     if (!task) {
         io.printErr?.(HOSTED_USAGE);
         return 1;

package/dist/index.js

@@ -2718,12 +2718,25 @@ async function resolveSetupTeam(teamSlugArg, noInput, dryRun) {
     }
     return createTeamOnServer(name);
 }
-async function resolveSetupProjects(team) {
+async function resolveSetupProjects(team, noInput, dryRun) {
     const projects = await fetchProjects(team.slug);
-    if (projects.length === 0) {
-        throw new Error(`Team '${team.slug}' has no projects. Create a project before running setup.`);
+    if (projects.length > 0) {
+        return projects;
+    }
+    // ALI-1140: a just-created team (or a pre-existing empty one) has no projects
+    // by definition — continue the wizard into creating the first project instead
+    // of dead-ending on the path setup itself offered.
+    if (noInput || dryRun) {
+        throw new Error(`Team '${team.slug}' has no projects. Create one with \`orizu projects create --name <name> --team ${team.slug}\`, then re-run setup.`);
     }
-    return projects;
+    printLine(`   Team '${sanitizeTerminalText(team.slug)}' has no projects yet. Let's create the first one.`);
+    const name = await askText('   Project name?', '');
+    if (!name) {
+        throw new Error('Project name is required to create a project.');
+    }
+    const project = await createProjectOnServer(team.slug, name);
+    printLine(`   Created project ${sanitizeTerminalText(`${project.teamSlug}/${project.slug}`)}`);
+    return [project];
 }
 function projectSeedsFromProjects(projects) {
     return projects.map(project => ({
@@ -2848,7 +2861,7 @@ async function setupCommand() {
             let projects;
             if (auth.state === 'signed-in' && !validateOnly) {
                 const team = await resolveSetupTeam(teamSlug, noInput, dryRun);
-                const serverProjects = await resolveSetupProjects(team);
+                const serverProjects = await resolveSetupProjects(team, noInput, dryRun);
                 teamSlug = team.slug;
                 teamId = team.id;
                 projects = projectSeedsFromProjects(serverProjects);
@@ -2866,10 +2879,10 @@ async function setupCommand() {
                             hostedAttached = (await runInteractiveHostedSetup({ teamSlug: team.slug, targetDir: workspaceRoot, local: hasArg('--local'), activeInstallation: link.status === 'active' }, { print: printLine, fetcher: authedFetch })).attached;
                         }
                         catch (error) {
-                            throw new Error(`Hosted setup failed: ${getErrorMessage(error)} Remove any partial clone in ${workspaceRoot} if one exists, then re-run \`orizu setup\` (or pass --local to scaffold a local-only workspace).`);
+                            throw new Error(`Hosted setup failed: ${getErrorMessage(error)} Re-running \`orizu setup\` is safe — provisioning adopts the existing workbench repo and resumes where it left off (or pass --local to scaffold a local-only workspace).`);
                         }
                     }
-                }
+                } // hint must not blame local state (ALI-1143): provisioning failures are server-side, and both provisioning (adopt) and the clone step (skip-if-cloned, ALI-1069) are idempotent on re-run
             }
             else if (!teamSlug && !noInput && !validateOnly) {
                 teamSlug = await askText('   Team slug?', 'local-team');

package/dist/merge-job.js

@@ -39,6 +39,7 @@
  * (plus the shape-pattern net). Nothing here ever logs a secret.
  */
 import { mergeBranchWithDeployKey, } from './deploy-key-merge-core.js';
+import { assertSecureTokenTransport } from './http.js';
 import { redactSecrets } from './secret-redaction.js';
 // -- Frozen env contract --------------------------------------------------------
 export const REQUIRED_MERGE_JOB_ENV_VARS = [
@@ -60,7 +61,27 @@ export function resolveMergeJobEnv(env) {
     const coordinatorUrl = req('ORIZU_COORDINATOR_URL');
     const baseUrl = req('ORIZU_BASE_URL');
     if (missing.length > 0)
-        return { ok: false, missing };
+        return { ok: false, missing, invalid: [] };
+    const origins = [
+        ['ORIZU_COORDINATOR_URL', coordinatorUrl],
+        ['ORIZU_BASE_URL', baseUrl],
+    ];
+    const invalid = origins.flatMap(([name, value]) => {
+        try {
+            const parsed = new URL(value);
+            // Userinfo is never accepted, including on loopback: rejecting it at the
+            // env boundary keeps configured credentials out of every retry/error path.
+            if (parsed.username || parsed.password)
+                return [name];
+            assertSecureTokenTransport(value);
+            return [];
+        }
+        catch {
+            return [name];
+        }
+    });
+    if (invalid.length > 0)
+        return { ok: false, missing: [], invalid };
     return {
         ok: true,
         value: {
@@ -312,8 +333,10 @@ export async function runMergeJob(opts) {
 export async function mergeJobCommand(io) {
     const resolved = resolveMergeJobEnv(process.env);
     if (!resolved.ok) {
-        io.printErr?.(`merge-job: missing required env: ${resolved.missing.join(', ')} ` +
-            '(the MergeJobCoordinator sandbox env contract)');
+        const detail = resolved.missing.length > 0
+            ? `missing required env: ${resolved.missing.join(', ')}`
+            : `invalid or insecure origin env: ${resolved.invalid.join(', ')}`;
+        io.printErr?.(`merge-job: ${detail} (the MergeJobCoordinator sandbox env contract)`);
         return 1;
     }
     const log = (line) => io.printErr?.(`[merge-job] ${line}`);

package/dist/option-validation.js

@@ -0,0 +1,54 @@
+function optionName(arg) {
+    const equalsIndex = arg.indexOf('=');
+    return equalsIndex === -1 ? arg : arg.slice(0, equalsIndex);
+}
+function isNegativeNumericValue(arg) {
+    return arg.length > 1 && !arg.startsWith('--') && Number.isFinite(Number(arg));
+}
+function isUnambiguouslySingleDashValue(arg) {
+    // A short option cannot contain whitespace immediately after its dash. This
+    // keeps Markdown-list prompts such as `--task "- fix the test"` available
+    // without letting a misspelled option such as `--task -taks` get swallowed.
+    return /^-\s/.test(arg) || isNegativeNumericValue(arg);
+}
+function followsValueOption(args, index, valueOptions) {
+    if (index === 0)
+        return false;
+    const previous = args[index - 1];
+    return previous.startsWith('--') && !previous.includes('=') && valueOptions.has(previous);
+}
+/**
+ * Return the first dash-prefixed option that is not in a command's explicit
+ * allowlist. An unambiguously value-like single-dash token immediately
+ * following a value-taking option is data: this keeps inputs such as
+ * `--duration -5` and `--task "- fix the test"` available without allowing a
+ * stray token or mistyped short option.
+ *
+ * `valueOptions` permits the unambiguous `--option=value` form. A separate
+ * token beginning with `--`, or an option-like single-dash word, is parsed as
+ * an option so a missing value cannot swallow a typo. Callers whose value is
+ * itself option-like can use the inline form; Markdown list markers and finite
+ * negative numbers remain safe as separate values.
+ */
+export function findUnknownOption(args, allowedOptions, valueOptions = new Set()) {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg.startsWith('-') || arg === '-')
+            continue;
+        if (!arg.startsWith('--')) {
+            if (isUnambiguouslySingleDashValue(arg) && followsValueOption(args, index, valueOptions))
+                continue;
+            return arg;
+        }
+        const name = optionName(arg);
+        if (!allowedOptions.has(name))
+            return name;
+        const hasInlineValue = arg.length > name.length;
+        if (hasInlineValue) {
+            if (!valueOptions.has(name))
+                return arg;
+            continue;
+        }
+    }
+    return null;
+}

package/dist/workbench-cli.js

@@ -7,6 +7,7 @@
  */
 import { spawnSync } from 'child_process';
 import { authedFetch } from './http.js';
+import { findUnknownOption } from './option-validation.js';
 import { getWorkspaceRoot, workspaceExists } from './workspace.js';
 import { attachedWorkspaceId, stringOrNull } from './workspace-sync.js';
 function defaultSessionGit(args, opts) {
@@ -41,6 +42,19 @@ const DEFAULT_TAIL_INTERVAL_SECONDS = 2;
 // hot-spin against the API while a non-terminal run is quiet. Draining full
 // pages intentionally skips the sleep — that is catch-up, not polling.
 const MIN_TAIL_INTERVAL_MS = 500;
+const SESSION_START_OPTIONS = new Set(['--project', '--workspace', '--json']);
+const WORKBENCH_VALUE_OPTIONS = new Set([
+    '--after',
+    '--interval',
+    '--message',
+    '--project',
+    '--run',
+    '--session',
+    '--status',
+    '--summary',
+    '--title',
+    '--workspace',
+]);
 function defaultSleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -475,11 +489,19 @@ function hasFlag(args, flag) {
     return args.includes(flag);
 }
 function argValue(args, flag) {
-    const index = args.indexOf(flag);
-    if (index === -1 || index + 1 >= args.length || args[index + 1].startsWith('--')) {
-        return null;
+    const inlinePrefix = `${flag}=`;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg.startsWith(inlinePrefix)) {
+            return arg.slice(inlinePrefix.length);
+        }
+        if (arg === flag) {
+            return index + 1 < args.length && !args[index + 1].startsWith('--')
+                ? args[index + 1]
+                : null;
+        }
     }
-    return args[index + 1];
+    return null;
 }
 function numberArg(args, flag) {
     const raw = argValue(args, flag);
@@ -494,7 +516,7 @@ function positionalArgs(args) {
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg.startsWith('--')) {
-            if (argValue(args, arg) !== null) {
+            if (!arg.includes('=') && WORKBENCH_VALUE_OPTIONS.has(arg) && argValue(args.slice(i), arg) !== null) {
                 i += 1;
             }
             continue;
@@ -700,6 +722,10 @@ async function dispatchWorkbenchCommand(args, io) {
         // not run from inside it (defaults to cwd).
         const workspaceDir = argValue(args, '--workspace') ?? undefined;
         if (subcommand === 'start') {
+            const unknownOption = findUnknownOption(args, SESSION_START_OPTIONS, WORKBENCH_VALUE_OPTIONS);
+            if (unknownOption) {
+                return emitJsonError(io, `unknown option ${unknownOption}\nUsage: orizu session start [--project <team/project>] [--workspace <dir>] [--json]`);
+            }
             const result = await runSessionStart({
                 fetcher,
                 cwd: workspaceDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orizu",
-  "version": "0.5.14",
+  "version": "0.5.15",
   "private": false,
   "type": "module",
   "bin": {

package/src/github-setup.ts

@@ -19,7 +19,7 @@ import { existsSync, mkdirSync } from 'fs'
 import { join } from 'path'
 
 import { authedFetch } from './http.js'
-import { assertWorkspaceDirUsable } from './workspace.js'
+import { assertWorkspaceDirUsable, workspaceExists } from './workspace.js'
 
 export type SetupFetcher = (path: string, init?: RequestInit) => Promise<Response>
 
@@ -56,7 +56,37 @@ export interface GithubLinkResult {
 }
 
 const DEFAULT_POLL_INTERVAL_MS = 2000
-const DEFAULT_POLL_TIMEOUT_MS = 180000
+// ALI-1141: long enough for a slow org-picker + repo-selection walk, but the
+// wait MUST be finite — when the App is already installed in the target org,
+// GitHub only offers "Configure" and never redirects to our setup callback, so
+// an unbounded poll would spin forever. (Still under the server's 15-minute
+// nonce TTL, so the poll times out before the server would report `expired`.)
+const DEFAULT_POLL_TIMEOUT_MS = 600000
+// ALI-1141: after this long with no callback, the likeliest cause is the
+// already-installed org above — surface it instead of heartbeating silently.
+const ALREADY_INSTALLED_HINT_MS = 90000
+
+/**
+ * Why the poll can never succeed when the App is already installed in the org
+ * (ALI-1141): GitHub's `installations/new?state=` page then only offers
+ * "Configure", and completing configuration does NOT redirect to the App's
+ * Setup URL with our state nonce — the callback that flips the row out of
+ * `pending` never fires. Printed as a mid-poll hint and folded into the
+ * timeout error so the user is never left with an unexplained hang.
+ */
+function alreadyInstalledHintLines(teamSlug: string): string[] {
+  return [
+    '   ⚠ GitHub has not called back yet. The most likely cause: the Orizu GitHub',
+    '     App is ALREADY INSTALLED in that org — GitHub then only offers',
+    '     "Configure", and finishing configuration never notifies Orizu, so this',
+    '     wait cannot succeed. Remedies:',
+    '     • Install the App into a DIFFERENT GitHub org for this team (each org',
+    '       installation can be linked to exactly one Orizu team).',
+    '     • If the org is not linked to any Orizu team, uninstall the Orizu App',
+    '       from the org (GitHub → org Settings → GitHub Apps) and re-run',
+    `       \`orizu github link --team ${teamSlug}\` to do a fresh install.`,
+  ]
+}
 
 function defaultSleep(ms: number): Promise<void> {
   return new Promise(resolve => setTimeout(resolve, ms))
@@ -118,10 +148,12 @@ export async function runGithubLink(teamSlug: string, io: GithubLinkIo): Promise
   const sleep = io.sleep ?? defaultSleep
   const interval = io.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS
   const timeout = io.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS
-  const deadline = now() + timeout
+  const started = now()
+  const deadline = started + timeout
   // Periodic heartbeat so a long install does not look hung; never echoes state.
   const HEARTBEAT_MS = 15000
-  let lastHeartbeat = now()
+  let lastHeartbeat = started
+  let printedAlreadyInstalledHint = false
 
   for (;;) {
     const poll = await fetcher(`/api/cli/github/link?state=${encodeURIComponent(state)}`)
@@ -149,11 +181,23 @@ export async function runGithubLink(teamSlug: string, io: GithubLinkIo): Promise
       // status 'pending' → keep waiting.
     }
     if (now() >= deadline) {
+      // Same actionable message as the mid-poll hint: an already-installed org
+      // is the one known way to reach this timeout with nothing else wrong.
       throw new Error(
-        'Timed out waiting for the GitHub App install to complete. ' +
+        `Timed out waiting for the GitHub App install to complete after ${Math.round(timeout / 60000)} minutes. ` +
+          'If the Orizu GitHub App is already installed in that org, GitHub never notifies Orizu when you finish the "Configure" flow — ' +
+          'install the App into a DIFFERENT GitHub org for this team (or uninstall it from the org first if no other Orizu team uses it). ' +
           `Resume with \`orizu github link --team ${teamSlug}\` after finishing the install.`
       )
     }
+    if (!printedAlreadyInstalledHint && now() - started >= ALREADY_INSTALLED_HINT_MS) {
+      for (const line of alreadyInstalledHintLines(teamSlug)) io.print(line)
+      io.print(
+        `   Still waiting (Ctrl+C to abort; resume later with \`orizu github link --team ${teamSlug}\`)…`
+      )
+      printedAlreadyInstalledHint = true
+      lastHeartbeat = now()
+    }
     if (now() - lastHeartbeat >= HEARTBEAT_MS) {
       io.print('   …still waiting for the GitHub install to complete.')
       lastHeartbeat = now()
@@ -338,8 +382,7 @@ export async function runHostedAttach(
   io.print(`   Cloning ${repoFullName}...`)
   // Clone with the helper inline + the workspace id in the env so the token is
   // brokered on demand and never materializes in the URL or on disk.
-  gitOrThrow(
-    io.git,
+  const clone = io.git(
     [
       '-c',
       `credential.helper=${CREDENTIAL_HELPER}`,
@@ -351,6 +394,22 @@ export async function runHostedAttach(
     ],
     { env: { ORIZU_WORKSPACE_ID: options.workspaceId } }
   )
+  if (clone.status !== 0) {
+    const detail = clone.stderr || `exit ${clone.status}`
+    // A local-only workspace (`orizu setup --local`) has orizu.team.json but no
+    // `.git`, so it passes `assertWorkspaceDirUsable` yet fails the clone —
+    // `git clone` refuses the non-empty dir up front and writes nothing, so
+    // every byte in there is the user's workspace, not an incomplete clone.
+    // Never advise deleting it.
+    if (workspaceExists(options.targetDir)) {
+      throw new Error(
+        `git clone failed: ${detail} ${options.targetDir} already holds a local Orizu workspace (orizu.team.json) without a hosted clone, so the workbench repo can't be cloned into it. Don't delete it — move it aside or re-run \`orizu setup\` with \`--workspace <empty-path>\` (or keep it local with \`--local\`).`
+      )
+    }
+    throw new Error(
+      `git clone failed: ${detail} Remove or empty the incomplete clone directory ${options.targetDir}, then re-run \`orizu setup\`.`
+    )
+  }
   // Persist the helper repo-locally for future pull/push (cwd-resolved).
   gitOrThrow(io.git, ['config', 'credential.helper', CREDENTIAL_HELPER], { cwd: options.targetDir })
   gitOrThrow(io.git, ['config', 'credential.useHttpPath', 'true'], { cwd: options.targetDir })

package/src/help.ts

@@ -772,16 +772,28 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
   },
   {
     path: ['session', 'start'],
-    usage: 'orizu session start [--project <team/project>] [--workspace <dir>] [--json]',
+    usage: 'orizu session start [--project <team/project>] [--workspace <dir>] [--json] | orizu session start --hosted (--task <prompt> | --task-file <path>) [--duration <min>] [--project <team/project>] [--tail]',
     summary:
-      'Start a durable workspace session and print the session id. When run inside the workbench clone (or with --workspace), the remote session branch is fetched and checked out locally, and the exact next git commands are printed.',
+      'Start a durable workspace session, or add --hosted with a task prompt to start a coordinator-managed hosted agent. Plain sessions check out their remote session branch locally when run inside the workbench clone (or with --workspace).',
     group: 'Sessions',
     options: [
       { name: '--project <team/project>', help: 'Optionally scope the session to a project in the attached workspace.' },
       { name: '--workspace <dir>', help: 'Workbench clone directory when not running from inside it.' },
+      { name: '--hosted', help: 'Start a coordinator-managed hosted agent session instead of a plain durable session.' },
+      { name: '--task <prompt>', help: 'Hosted agent task prompt. Mutually exclusive with --task-file.' },
+      { name: '--task-file <path>', help: 'Read the hosted agent task prompt from a UTF-8 file. Mutually exclusive with --task.' },
+      { name: '--duration <min>', help: 'Hosted sandbox duration in minutes (default 60, maximum 1440).' },
+      { name: '--model <provider/model>', help: 'Optional hosted model override.' },
+      { name: '--reasoning-effort <level>', help: 'Optional hosted model reasoning-effort override.' },
+      { name: '--title <title>', help: 'Optional hosted run title.' },
+      { name: '--tail', help: 'Follow the hosted run until it reaches a terminal state.' },
       { name: '--json', help: 'Emit the machine-readable session payload.' },
     ],
-    examples: ['orizu session start', 'orizu session start --project highlight/hip --json'],
+    examples: [
+      'orizu session start',
+      'orizu session start --project highlight/hip --json',
+      'orizu session start --hosted --task-file ./task.md --project highlight/hip --duration 90',
+    ],
   },
   {
     path: ['session', 'status'],

package/src/hosted-session-cli.ts

@@ -35,6 +35,8 @@
  * local-sim end-to-end test.
  */
 
+import { readFileSync } from 'fs'
+
 import {
   createLocalSimProvider,
   type SandboxEgressPolicy,
@@ -57,6 +59,7 @@ import { hostedBootCommand } from './hosted-boot.js'
 import { mergeJobCommand } from './merge-job.js'
 import { authedFetch } from './http.js'
 import { resolveBaseUrl } from './http.js'
+import { findUnknownOption } from './option-validation.js'
 import { getWorkspaceRoot } from './workspace.js'
 import { attachedWorkspaceId } from './workspace-sync.js'
 import { tailWorkbenchRun } from './workbench-cli.js'
@@ -75,6 +78,13 @@ export const DEFAULT_AGENT_TOKEN_TTL_MINUTES = 60
  *  before declaring the detached launch a failure. */
 export const DEFAULT_READINESS_TIMEOUT_MS = 30 * 1000
 export const DEFAULT_READINESS_POLL_MS = 500
+/** Must match the coordinator Worker's session-start request ceiling. */
+export const MAX_HOSTED_START_BODY_BYTES = 128 * 1024
+/** `workspace_sessions.id` and `workbench_runs.id` are PostgreSQL UUIDs. The
+ *  server creates both before its coordinator poke, and the Worker injects the
+ *  session id into the final DO body. A representative UUID makes the local
+ *  projection byte-exact without creating either server-side row. */
+const GENERATED_HOSTED_UUID_PLACEHOLDER = '00000000-0000-4000-8000-000000000000'
 /** Non-secret placeholder OpenCode uses to form requests; the firewall proxy
  *  overrides the real Anthropic header (model-key brokering). NEVER a real key. */
 export const ANTHROPIC_DUMMY_KEY = 'sk-ant-orizu-proxy-broker-placeholder'
@@ -787,6 +797,10 @@ export interface HostedCommandIo {
 }
 
 function argVal(args: readonly string[], flag: string): string | null {
+  const inlinePrefix = `${flag}=`
+  const inlineArg = args.find(arg => arg.startsWith(inlinePrefix))
+  if (inlineArg) return inlineArg.slice(inlinePrefix.length)
+
   const index = args.indexOf(flag)
   if (index === -1 || index + 1 >= args.length) return null
   const value = args[index + 1]
@@ -794,7 +808,7 @@ function argVal(args: readonly string[], flag: string): string | null {
 }
 
 function hasFlag(args: readonly string[], flag: string): boolean {
-  return args.includes(flag)
+  return args.some(arg => arg === flag || arg.startsWith(`${flag}=`))
 }
 
 function numFlag(args: readonly string[], flag: string): number | undefined {
@@ -805,7 +819,7 @@ function numFlag(args: readonly string[], flag: string): number | undefined {
 }
 
 const HOSTED_USAGE =
-  'Usage: orizu session start --hosted --task "<prompt>" [--duration <min> (default 60, max 1440)] ' +
+  'Usage: orizu session start --hosted (--task "<prompt>" | --task-file <path>) [--duration <min> (default 60, max 1440)] ' +
   '[--model <provider/model>] [--reasoning-effort <level>] [--project <team/project>] ' +
   '[--title <title>] [--tail]\n' +
   'Default: the Orizu server provisions the sandbox (no VERCEL_* or model key needed on your machine); ' +
@@ -816,6 +830,42 @@ const HOSTED_USAGE =
   'Note (v0, --operator only): if you disconnect, the agent token expires within its TTL (<=60m) and the run ' +
   'finishes cleanly; reconnect with `orizu run tail --run <id>`. The sandbox timeout is independent (up to 24h).'
 
+const HOSTED_START_OPTIONS = new Set([
+  '--hosted',
+  '--task',
+  '--task-file',
+  '--workspace',
+  '--duration',
+  '--model',
+  '--reasoning-effort',
+  '--project',
+  '--title',
+  '--tail',
+  '--operator',
+  '--provider',
+  '--runtime',
+  '--image',
+  '--snapshot',
+  '--model-key',
+  '--json',
+])
+
+const HOSTED_START_VALUE_OPTIONS = new Set([
+  '--task',
+  '--task-file',
+  '--workspace',
+  '--duration',
+  '--model',
+  '--reasoning-effort',
+  '--project',
+  '--title',
+  '--provider',
+  '--runtime',
+  '--image',
+  '--snapshot',
+  '--model-key',
+])
+
 /** Printed on EVERY `--operator` use (founder-locked: deprecate NOW, remove
  *  after Phase 6 validation). Loud on purpose. */
 export const OPERATOR_DEPRECATION_WARNING =
@@ -836,21 +886,65 @@ export async function startHostedViaServer(
   io: HostedCommandIo,
   fetcher: HostFetcher = (path, init) => authedFetch(path, init)
 ): Promise<number> {
+  const durationMinutes = numFlag(args, '--duration')
+  const model = argVal(args, '--model') ?? undefined
+  const reasoningEffort = argVal(args, '--reasoning-effort') ?? undefined
+  const projectSlug = argVal(args, '--project') ?? undefined
+  const title = argVal(args, '--title') ?? undefined
   const payload: Record<string, unknown> = {
     workspaceId,
     task,
-    durationMinutes: numFlag(args, '--duration'),
-    model: argVal(args, '--model') ?? undefined,
-    reasoningEffort: argVal(args, '--reasoning-effort') ?? undefined,
-    projectSlug: argVal(args, '--project') ?? undefined,
-    title: argVal(args, '--title') ?? undefined,
+    durationMinutes,
+    model,
+    reasoningEffort,
+    projectSlug,
+    title,
+  }
+  const serializedPayload = JSON.stringify(payload)
+  const payloadBytes = new TextEncoder().encode(serializedPayload).byteLength
+  if (payloadBytes > MAX_HOSTED_START_BODY_BYTES) {
+    const message =
+      `Hosted task prompt is too large: request body is ${payloadBytes} bytes; ` +
+      `maximum is ${MAX_HOSTED_START_BODY_BYTES} bytes (128 KiB).`
+    if (io.json) io.print(JSON.stringify({ ok: false, error: message }))
+    else io.printErr?.(message)
+    return 1
+  }
+
+  // Mirror the exact JSON shape that reaches the session Durable Object after
+  // the API creates its UUID run/session rows, normalizes optional strings, and
+  // the Worker injects sessionId. This second guard keeps near-boundary prompts
+  // from triggering server-side state that would only be compensated after a
+  // coordinator 413. Keep this field list in sync with pokeCoordinatorStart in
+  // app/api/cli/hosted-sessions/route.ts.
+  const normalizedModel = model?.trim() || undefined
+  const normalizedReasoningEffort = reasoningEffort?.trim() || undefined
+  const coordinatorPayload = JSON.stringify({
+    runId: GENERATED_HOSTED_UUID_PLACEHOLDER,
+    task,
+    durationMinutes:
+      durationMinutes !== undefined && durationMinutes > 0
+        ? durationMinutes
+        : undefined,
+    model: normalizedModel,
+    reasoningEffort: normalizedReasoningEffort,
+    sessionId: GENERATED_HOSTED_UUID_PLACEHOLDER,
+  })
+  const coordinatorPayloadBytes = new TextEncoder().encode(coordinatorPayload).byteLength
+  if (coordinatorPayloadBytes > MAX_HOSTED_START_BODY_BYTES) {
+    const message =
+      `Hosted task prompt is too large: coordinator request body would be ${coordinatorPayloadBytes} bytes ` +
+      `after generated run/session IDs; maximum is ${MAX_HOSTED_START_BODY_BYTES} bytes (128 KiB).`
+    if (io.json) io.print(JSON.stringify({ ok: false, error: message }))
+    else io.printErr?.(message)
+    return 1
   }
   let response: Response
   try {
     response = await fetcher('/api/cli/hosted-sessions', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(payload),
+      body: serializedPayload,
     })
   } catch (error) {
     io.printErr?.(`hosted session request failed: ${error instanceof Error ? error.message : String(error)}`)
@@ -937,7 +1031,44 @@ export async function hostedCommand(
     return 1
   }
 
-  const task = argVal(args, '--task')
+  const unknownOption = findUnknownOption(args, HOSTED_START_OPTIONS, HOSTED_START_VALUE_OPTIONS)
+  if (unknownOption) {
+    const followsTaskFlag = args.some(
+      (arg, index) =>
+        arg === '--task' &&
+        (args[index + 1] === unknownOption || args[index + 1]?.startsWith(`${unknownOption}=`))
+    )
+    const taskValueHint = followsTaskFlag
+      ? '\nTask text beginning with a dash must use --task=<prompt> or --task-file <path>.'
+      : ''
+    io.printErr?.(`unknown option ${unknownOption}${taskValueHint}\n${HOSTED_USAGE}`)
+    return 1
+  }
+
+  const inlineTask = argVal(args, '--task')
+  const taskFile = argVal(args, '--task-file')
+  if (hasFlag(args, '--task') && hasFlag(args, '--task-file')) {
+    io.printErr?.(`Use either --task or --task-file, not both.\n${HOSTED_USAGE}`)
+    return 1
+  }
+
+  let task = inlineTask
+  if (taskFile) {
+    try {
+      task = readFileSync(taskFile, 'utf8')
+    } catch (error) {
+      io.printErr?.(
+        `Could not read task file '${taskFile}': ${error instanceof Error ? error.message : String(error)}`
+      )
+      return 1
+    }
+    if (task.trim().length === 0) {
+      io.printErr?.(
+        `Task file '${taskFile}' is empty or contains only whitespace. Add a task prompt and try again.`
+      )
+      return 1
+    }
+  }
   if (!task) {
     io.printErr?.(HOSTED_USAGE)
     return 1

package/src/index.ts

@@ -3607,14 +3607,30 @@ async function resolveSetupTeam(teamSlugArg: string | null, noInput: boolean, dr
   return createTeamOnServer(name)
 }
 
-async function resolveSetupProjects(team: Team): Promise<Project[]> {
+async function resolveSetupProjects(team: Team, noInput: boolean, dryRun: boolean): Promise<Project[]> {
   const projects = await fetchProjects(team.slug)
 
-  if (projects.length === 0) {
-    throw new Error(`Team '${team.slug}' has no projects. Create a project before running setup.`)
+  if (projects.length > 0) {
+    return projects
+  }
+
+  // ALI-1140: a just-created team (or a pre-existing empty one) has no projects
+  // by definition — continue the wizard into creating the first project instead
+  // of dead-ending on the path setup itself offered.
+  if (noInput || dryRun) {
+    throw new Error(
+      `Team '${team.slug}' has no projects. Create one with \`orizu projects create --name <name> --team ${team.slug}\`, then re-run setup.`
+    )
   }
 
-  return projects
+  printLine(`   Team '${sanitizeTerminalText(team.slug)}' has no projects yet. Let's create the first one.`)
+  const name = await askText('   Project name?', '')
+  if (!name) {
+    throw new Error('Project name is required to create a project.')
+  }
+  const project = await createProjectOnServer(team.slug, name)
+  printLine(`   Created project ${sanitizeTerminalText(`${project.teamSlug}/${project.slug}`)}`)
+  return [project]
 }
 
 function projectSeedsFromProjects(projects: Project[]): WorkspaceProjectSeed[] {
@@ -3757,13 +3773,13 @@ async function setupCommand() {
 
       if (auth.state === 'signed-in' && !validateOnly) {
         const team = await resolveSetupTeam(teamSlug, noInput, dryRun)
-        const serverProjects = await resolveSetupProjects(team)
+        const serverProjects = await resolveSetupProjects(team, noInput, dryRun)
         teamSlug = team.slug
         teamId = team.id
         projects = projectSeedsFromProjects(serverProjects)
         printLine(`   ${formatProjectSetupProgress(projects.length)}`)
         if (!hasArg('--local') && !noInput && !dryRun) { let link: GithubLinkResult | null = null; try { link = await runGithubLink(team.slug, { print: printLine, fetcher: authedFetch, openUrl: openInBrowser, confirm: (org) => askYesNo(`   Connect this team to GitHub org '${org}'?`, true) }) } catch (error) { printLine(`   GitHub link skipped: ${getErrorMessage(error)} Run \`orizu github link --team ${team.slug}\` to finish.`) }
-        if (link) { try { hostedAttached = (await runInteractiveHostedSetup({ teamSlug: team.slug, targetDir: workspaceRoot, local: hasArg('--local'), activeInstallation: link.status === 'active' }, { print: printLine, fetcher: authedFetch })).attached } catch (error) { throw new Error(`Hosted setup failed: ${getErrorMessage(error)} Remove any partial clone in ${workspaceRoot} if one exists, then re-run \`orizu setup\` (or pass --local to scaffold a local-only workspace).`) } } }
+        if (link) { try { hostedAttached = (await runInteractiveHostedSetup({ teamSlug: team.slug, targetDir: workspaceRoot, local: hasArg('--local'), activeInstallation: link.status === 'active' }, { print: printLine, fetcher: authedFetch })).attached } catch (error) { throw new Error(`Hosted setup failed: ${getErrorMessage(error)} Re-running \`orizu setup\` is safe — provisioning adopts the existing workbench repo and resumes where it left off (or pass --local to scaffold a local-only workspace).`) } } } // hint must not blame local state (ALI-1143): provisioning failures are server-side, and both provisioning (adopt) and the clone step (skip-if-cloned, ALI-1069) are idempotent on re-run
       } else if (!teamSlug && !noInput && !validateOnly) {
         teamSlug = await askText('   Team slug?', 'local-team')
       }

package/src/merge-job.ts

@@ -44,6 +44,7 @@ import {
   type DeployKeyMergeResult,
   type GitCommandRunner,
 } from './deploy-key-merge-core.js'
+import { assertSecureTokenTransport } from './http.js'
 import { redactSecrets } from './secret-redaction.js'
 
 export type MergeJobFetch = (url: string, init?: RequestInit) => Promise<Response>
@@ -67,7 +68,7 @@ export interface MergeJobEnv {
 
 export function resolveMergeJobEnv(
   env: Record<string, string | undefined>
-): { ok: true; value: MergeJobEnv } | { ok: false; missing: string[] } {
+): { ok: true; value: MergeJobEnv } | { ok: false; missing: string[]; invalid: string[] } {
   const missing: string[] = []
   const req = (name: string): string => {
     const value = env[name]?.trim()
@@ -78,7 +79,25 @@ export function resolveMergeJobEnv(
   const jobKey = req('ORIZU_MERGE_JOB_ID')
   const coordinatorUrl = req('ORIZU_COORDINATOR_URL')
   const baseUrl = req('ORIZU_BASE_URL')
-  if (missing.length > 0) return { ok: false, missing }
+  if (missing.length > 0) return { ok: false, missing, invalid: [] }
+
+  const origins = [
+    ['ORIZU_COORDINATOR_URL', coordinatorUrl],
+    ['ORIZU_BASE_URL', baseUrl],
+  ] as const
+  const invalid = origins.flatMap(([name, value]) => {
+    try {
+      const parsed = new URL(value)
+      // Userinfo is never accepted, including on loopback: rejecting it at the
+      // env boundary keeps configured credentials out of every retry/error path.
+      if (parsed.username || parsed.password) return [name]
+      assertSecureTokenTransport(value)
+      return []
+    } catch {
+      return [name]
+    }
+  })
+  if (invalid.length > 0) return { ok: false, missing: [], invalid }
   return {
     ok: true,
     value: {
@@ -445,10 +464,10 @@ export interface MergeJobCommandIo {
 export async function mergeJobCommand(io: MergeJobCommandIo): Promise<number> {
   const resolved = resolveMergeJobEnv(process.env)
   if (!resolved.ok) {
-    io.printErr?.(
-      `merge-job: missing required env: ${resolved.missing.join(', ')} ` +
-        '(the MergeJobCoordinator sandbox env contract)'
-    )
+    const detail = resolved.missing.length > 0
+      ? `missing required env: ${resolved.missing.join(', ')}`
+      : `invalid or insecure origin env: ${resolved.invalid.join(', ')}`
+    io.printErr?.(`merge-job: ${detail} (the MergeJobCoordinator sandbox env contract)`)
     return 1
   }
   const log = (line: string): void => io.printErr?.(`[merge-job] ${line}`)

package/src/option-validation.ts

@@ -0,0 +1,63 @@
+function optionName(arg: string): string {
+  const equalsIndex = arg.indexOf('=')
+  return equalsIndex === -1 ? arg : arg.slice(0, equalsIndex)
+}
+
+function isNegativeNumericValue(arg: string): boolean {
+  return arg.length > 1 && !arg.startsWith('--') && Number.isFinite(Number(arg))
+}
+
+function isUnambiguouslySingleDashValue(arg: string): boolean {
+  // A short option cannot contain whitespace immediately after its dash. This
+  // keeps Markdown-list prompts such as `--task "- fix the test"` available
+  // without letting a misspelled option such as `--task -taks` get swallowed.
+  return /^-\s/.test(arg) || isNegativeNumericValue(arg)
+}
+
+function followsValueOption(
+  args: readonly string[],
+  index: number,
+  valueOptions: ReadonlySet<string>
+): boolean {
+  if (index === 0) return false
+  const previous = args[index - 1]
+  return previous.startsWith('--') && !previous.includes('=') && valueOptions.has(previous)
+}
+
+/**
+ * Return the first dash-prefixed option that is not in a command's explicit
+ * allowlist. An unambiguously value-like single-dash token immediately
+ * following a value-taking option is data: this keeps inputs such as
+ * `--duration -5` and `--task "- fix the test"` available without allowing a
+ * stray token or mistyped short option.
+ *
+ * `valueOptions` permits the unambiguous `--option=value` form. A separate
+ * token beginning with `--`, or an option-like single-dash word, is parsed as
+ * an option so a missing value cannot swallow a typo. Callers whose value is
+ * itself option-like can use the inline form; Markdown list markers and finite
+ * negative numbers remain safe as separate values.
+ */
+export function findUnknownOption(
+  args: readonly string[],
+  allowedOptions: ReadonlySet<string>,
+  valueOptions: ReadonlySet<string> = new Set()
+): string | null {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (!arg.startsWith('-') || arg === '-') continue
+    if (!arg.startsWith('--')) {
+      if (isUnambiguouslySingleDashValue(arg) && followsValueOption(args, index, valueOptions)) continue
+      return arg
+    }
+
+    const name = optionName(arg)
+    if (!allowedOptions.has(name)) return name
+
+    const hasInlineValue = arg.length > name.length
+    if (hasInlineValue) {
+      if (!valueOptions.has(name)) return arg
+      continue
+    }
+  }
+  return null
+}

package/src/workbench-cli.ts

@@ -9,6 +9,7 @@
 import { spawnSync } from 'child_process'
 
 import { authedFetch } from './http.js'
+import { findUnknownOption } from './option-validation.js'
 import { getWorkspaceRoot, workspaceExists } from './workspace.js'
 import { attachedWorkspaceId, stringOrNull } from './workspace-sync.js'
 
@@ -269,6 +270,19 @@ const DEFAULT_TAIL_INTERVAL_SECONDS = 2
 // hot-spin against the API while a non-terminal run is quiet. Draining full
 // pages intentionally skips the sleep — that is catch-up, not polling.
 const MIN_TAIL_INTERVAL_MS = 500
+const SESSION_START_OPTIONS = new Set(['--project', '--workspace', '--json'])
+const WORKBENCH_VALUE_OPTIONS = new Set([
+  '--after',
+  '--interval',
+  '--message',
+  '--project',
+  '--run',
+  '--session',
+  '--status',
+  '--summary',
+  '--title',
+  '--workspace',
+])
 
 function defaultSleep(ms: number): Promise<void> {
   return new Promise(resolve => setTimeout(resolve, ms))
@@ -774,11 +788,19 @@ function hasFlag(args: string[], flag: string): boolean {
 }
 
 function argValue(args: string[], flag: string): string | null {
-  const index = args.indexOf(flag)
-  if (index === -1 || index + 1 >= args.length || args[index + 1].startsWith('--')) {
-    return null
+  const inlinePrefix = `${flag}=`
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg.startsWith(inlinePrefix)) {
+      return arg.slice(inlinePrefix.length)
+    }
+    if (arg === flag) {
+      return index + 1 < args.length && !args[index + 1].startsWith('--')
+        ? args[index + 1]
+        : null
+    }
   }
-  return args[index + 1]
+  return null
 }
 
 function numberArg(args: string[], flag: string): number | undefined {
@@ -795,7 +817,7 @@ function positionalArgs(args: string[]): string[] {
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i]
     if (arg.startsWith('--')) {
-      if (argValue(args, arg) !== null) {
+      if (!arg.includes('=') && WORKBENCH_VALUE_OPTIONS.has(arg) && argValue(args.slice(i), arg) !== null) {
         i += 1
       }
       continue
@@ -1017,6 +1039,13 @@ async function dispatchWorkbenchCommand(args: string[], io: WorkbenchCommandIo):
     // not run from inside it (defaults to cwd).
     const workspaceDir = argValue(args, '--workspace') ?? undefined
     if (subcommand === 'start') {
+      const unknownOption = findUnknownOption(args, SESSION_START_OPTIONS, WORKBENCH_VALUE_OPTIONS)
+      if (unknownOption) {
+        return emitJsonError(
+          io,
+          `unknown option ${unknownOption}\nUsage: orizu session start [--project <team/project>] [--workspace <dir>] [--json]`
+        )
+      }
       const result = await runSessionStart({
         fetcher,
         cwd: workspaceDir,

package/vendor/skills/orizu-cli/SKILL.md

@@ -199,5 +199,5 @@ Detailed walkthrough — GEPA mechanics, Orizu-tracked optimization, optional DS
 
 - **Orizu is the source of truth for run metadata and pointers**: production/default prompt/scorer/runner pointers, version lineage, score runs, optimization runs, and report history all live in Orizu — query them with `orizu ...` commands (e.g. `orizu prompts list`, `orizu prompts versions`, `orizu runs ...`), never by reading repo files.
 - **The repo is the working set (files only)**: source, configs, `App.tsx`, schemas, and local traces under `logs/<run-id>`. It is the scratch space you edit and commit; it does NOT hold the canonical pointer/run state — that is in Orizu.
-- **Hosted sessions ship a pre-authenticated CLI**: inside a hosted agent sandbox the `orizu` CLI is already authenticated via `ORIZU_TOKEN_FILE` (with `ORIZU_BASE_URL` pointing at the API). You do NOT run `orizu login` — just call `orizu ...`. The bearer carries a **team-curator READ scope**: you can read projects, datasets (+ content/artifact bytes), prompts, scorers, runners/optimizers, runs, and reports across your own team, and execute runs / submit scores / create artifacts / create promotion manifests as the agent actor.
-- **Human-only actions will 403**: manifest approve / reject / apply, production and default pointer flips, and team/member/billing/integration admin are deliberately outside the agent envelope. Do not attempt them from a hosted session — they return 403 by design. Prepare a promotion manifest and hand it to a human curator to approve and apply.
+- **Hosted sessions ship a pre-authenticated CLI**: inside a hosted agent sandbox the `orizu` CLI is already authenticated via `ORIZU_TOKEN_FILE` (with `ORIZU_BASE_URL` pointing at the API). You do NOT run `orizu login` — just call `orizu ...`. The bearer carries **full team-curator authority while your session is active** (ADR-008): anything a curator-role human can read or write in your team — create/read/update projects, datasets (+ rows/artifact bytes), prompts, scorers, runners/optimizers, apps, tasks, runs, score runs, reports, and promotion-manifest proposals — you can too, across the whole team. (The full per-role access matrix lives in the Orizu repo at `docs/authorization-matrix.md`.)
+- **Human-only actions will 403**: promotion-manifest **approval / apply / reject**, production and default pointer flips, session/credential lifecycle (starting or ending hosted sessions, minting tokens, deploy keys), integration/connector credential reads (secrets reach your sandbox only as environment variables resolved at boot — never via API/DB), and team/member/installation/billing management. Do not attempt them from a hosted session — they return 403 by design. Prepare a promotion manifest and hand it to a human curator to approve and apply.