orizu 0.5.1 → 0.5.3

package/dist/artifact-pull.js

@@ -0,0 +1,157 @@
+/**
+ * Runner/optimizer artifact pull (symmetric with `runners push` /
+ * `optimizers push`): resolve the artifact by id or name, download the
+ * content-addressed zip from storage, and extract it into --out. Version
+ * metadata is written to .orizu/pull.json — .orizu/ is excluded from artifact
+ * zips (see artifact-archive.ts), so a pulled directory re-pushes with an
+ * identical content hash.
+ *
+ * Lives outside index.ts per the CLI index line ratchet (ALI-976): this module
+ * owns its own argument parsing and printing via injected io.
+ */
+import { spawnSync } from 'child_process';
+import { createHash } from 'crypto';
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { dirname, join } from 'path';
+import { authedFetch } from './http.js';
+// Shared with the runners exec download path in index.ts.
+export const ARTIFACT_MAX_BYTES = 25 * 1024 * 1024;
+function sanitizeTerminalText(value) {
+    return String(value).replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, '');
+}
+function expandHomePath(path) {
+    if (path.startsWith('~/')) {
+        const home = process.env.HOME || '';
+        return `${home}/${path.slice(2)}`;
+    }
+    return path;
+}
+function argValue(args, flag) {
+    const index = args.indexOf(flag);
+    if (index === -1 || index + 1 >= args.length || args[index + 1].startsWith('--')) {
+        return null;
+    }
+    return args[index + 1];
+}
+async function parseJsonPayload(response, context) {
+    const contentType = response.headers.get('content-type') || '';
+    const rawBody = await response.text();
+    if (!contentType.includes('application/json')) {
+        throw new Error(`${context} returned non-JSON response (status ${response.status}). ` +
+            `Body preview: ${sanitizeTerminalText(rawBody.slice(0, 180))}`);
+    }
+    try {
+        return JSON.parse(rawBody);
+    }
+    catch {
+        throw new Error(`${context} returned invalid JSON (status ${response.status}). ` +
+            `Body preview: ${sanitizeTerminalText(rawBody.slice(0, 180))}`);
+    }
+}
+export async function pullArtifactCommand(args, io) {
+    const kind = args[0] === 'runners' ? 'runner' : 'optimizer';
+    const fetcher = io.fetcher || authedFetch;
+    const positionalRef = args[2];
+    const artifactRef = positionalRef && !positionalRef.startsWith('--') ? positionalRef : null;
+    const outDir = argValue(args, '--out');
+    const label = argValue(args, '--label');
+    const version = argValue(args, '--version');
+    // Argument errors surface before project resolution, which may prompt
+    // interactively when --project is omitted.
+    const plural = kind === 'runner' ? 'runners' : 'optimizers';
+    if (!artifactRef || !outDir) {
+        throw new Error(`Usage: orizu ${plural} pull <${kind}-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <version-id>] [--json]`);
+    }
+    if (label && version) {
+        throw new Error('Use either --label or --version, not both');
+    }
+    const project = argValue(args, '--project') || await io.resolveProjectSlug(null);
+    const params = new URLSearchParams({ project });
+    if (label)
+        params.set('label', label);
+    if (version)
+        params.set('version', version);
+    const response = await fetcher(`/api/cli/${plural}/${encodeURIComponent(artifactRef)}?${params.toString()}`);
+    if (!response.ok) {
+        throw new Error(`Failed to pull ${kind}: ${await response.text()}`);
+    }
+    const data = await parseJsonPayload(response, `${kind} pull`);
+    const artifact = kind === 'runner' ? data.runner : data.optimizer;
+    if (!artifact) {
+        throw new Error(`Failed to pull ${kind}: malformed response`);
+    }
+    // Every stored version is content-addressed; a missing hash would silently
+    // void the integrity check and the pull.json anchor, so fail instead.
+    if (!data.version.contentSha256) {
+        throw new Error(`Failed to pull ${kind}: version ${data.version.id} has no content hash`);
+    }
+    const downloadResponse = await fetcher(`/api/cli/${kind}-versions/${encodeURIComponent(data.version.id)}/download`);
+    if (!downloadResponse.ok) {
+        throw new Error(`Failed to download ${kind} artifact: ${await downloadResponse.text()}`);
+    }
+    const zipBytes = new Uint8Array(await downloadResponse.arrayBuffer());
+    if (zipBytes.byteLength > ARTIFACT_MAX_BYTES) {
+        throw new Error(`${kind} artifact exceeds ${ARTIFACT_MAX_BYTES} bytes`);
+    }
+    // Versions are content-addressed by zip SHA256 (see the push routes), so a
+    // corrupted or mismatched download is detectable before anything is written.
+    const actualSha256 = createHash('sha256').update(zipBytes).digest('hex');
+    if (actualSha256 !== data.version.contentSha256.toLowerCase()) {
+        throw new Error(`${kind} artifact hash mismatch: expected ${data.version.contentSha256}, got ${actualSha256}`);
+    }
+    // Extraction is additive, so a dirty directory would mix files from other
+    // versions and break the pull -> identical re-push hash guarantee.
+    const targetDir = expandHomePath(outDir);
+    mkdirSync(targetDir, { recursive: true });
+    if (readdirSync(targetDir).length > 0) {
+        throw new Error(`Output directory is not empty: ${targetDir}`);
+    }
+    const tempDir = mkdtempSync(join(tmpdir(), `orizu-${kind}-pull-`));
+    try {
+        const zipPath = join(tempDir, 'artifact.zip');
+        writeFileSync(zipPath, zipBytes);
+        // Artifacts are self-authored, hash-verified above, and served only to
+        // authenticated project members; Info-ZIP additionally strips ../ path
+        // components on extraction (same trust model as materializeRunnerVersion).
+        const result = spawnSync('unzip', ['-q', zipPath, '-d', targetDir], {
+            encoding: 'utf8',
+        });
+        if (result.error || result.status !== 0) {
+            // targetDir was verified empty above, so everything in it came from
+            // this extraction — clear it so a re-pull isn't rejected as non-empty.
+            for (const entry of readdirSync(targetDir)) {
+                rmSync(join(targetDir, entry), { recursive: true, force: true });
+            }
+            if (result.error) {
+                throw result.error;
+            }
+            throw new Error(`unzip failed: ${sanitizeTerminalText(result.stderr || result.stdout || '')}`);
+        }
+    }
+    finally {
+        rmSync(tempDir, { recursive: true, force: true });
+    }
+    const versionLabels = (data.labels || [])
+        .filter(item => (kind === 'runner' ? item.runnerVersionId : item.optimizerVersionId) === data.version.id)
+        .map(item => item.label);
+    const pullMetadataPath = join(targetDir, '.orizu', 'pull.json');
+    mkdirSync(dirname(pullMetadataPath), { recursive: true });
+    writeFileSync(pullMetadataPath, `${JSON.stringify({
+        schema_version: `orizu.${kind}-pull.v1`,
+        name: artifact.name,
+        [`${kind}_id`]: artifact.id,
+        version_id: data.version.id,
+        content_sha256: data.version.contentSha256,
+        labels: versionLabels,
+    }, null, 2)}\n`);
+    if (io.json) {
+        io.print(JSON.stringify({
+            [`${kind}_id`]: artifact.id,
+            [`${kind}_version_id`]: data.version.id,
+            path: targetDir,
+        }));
+        return;
+    }
+    io.print(`Pulled ${kind} ${sanitizeTerminalText(artifact.name)} to ${sanitizeTerminalText(targetDir)}`);
+}

package/dist/github-setup.js

@@ -17,6 +17,16 @@ import { spawnSync } from 'child_process';
 import { mkdirSync } from 'fs';
 import { join } from 'path';
 import { authedFetch } from './http.js';
+import { assertWorkspaceDirUsable } from './workspace.js';
+/**
+ * Strip terminal control characters from server-supplied strings before they
+ * are printed (mirrors index.ts `sanitizeTerminalText`), so a hostile or
+ * mangled provisioning `warnings[]`/`defaultBranch` value can't inject escape
+ * sequences into the user's terminal.
+ */
+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;
 function defaultSleep(ms) {
@@ -178,6 +188,12 @@ export async function runHostedAttach(options, io) {
         const data = (await response.json());
         repoFullName = data.repo;
         provisioned = true;
+        if (data.rulesetApplied === true) {
+            io.print(`   Default-branch protection applied (ruleset "orizu-default-branch-protection"${data.defaultBranch ? ` on ${sanitizeServerText(data.defaultBranch)}` : ''}).`);
+        }
+        for (const warning of data.warnings ?? []) {
+            io.print(`   ⚠ ${sanitizeServerText(warning)}`);
+        }
     }
     const cleanUrl = `https://github.com/${repoFullName}.git`;
     io.print(`   Cloning ${repoFullName}...`);
@@ -243,6 +259,14 @@ export async function runInteractiveHostedSetup(input, io) {
     if (mode === 'local') {
         return { mode, attached: false, repoFullName: null };
     }
+    // The hosted paths (attach / provision-then-attach) clone the workbench repo
+    // into targetDir, and `git clone` refuses ANY non-empty directory. Fail fast
+    // here — before the provision call and the clone's git invocation, so no
+    // partial server/git state is created — with a friendly, actionable message
+    // (including the `--local` escape hatch). Only this real-clone path is gated;
+    // --local, --skip-login (not signed in), and a declined connect prompt never
+    // reach here, so they scaffold locally unblocked.
+    assertWorkspaceDirUsable(input.targetDir);
     const result = await runHostedAttach({ workspaceId: workspace.id, repoFullName, targetDir: input.targetDir }, { print: io.print, fetcher, git: io.git ?? defaultGitRunner, ensureOrizuDir: io.ensureOrizuDir });
     return { mode, attached: true, repoFullName: result.repoFullName };
 }

package/dist/help.js

@@ -344,6 +344,12 @@ export const COMMAND_DOCS = [
         summary: 'Push a local runner artifact directory.',
         group: 'Scorers and runners',
     },
+    {
+        path: ['runners', 'pull'],
+        usage: 'orizu runners pull <runner-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <version-id>] [--json]',
+        summary: 'Pull a runner artifact version to a local directory.',
+        group: 'Scorers and runners',
+    },
     {
         path: ['runners', 'exec'],
         usage: 'orizu runners exec (--prompt <prompt-version-id> | --prompt-version <id> --runner-version <id> | --scorer-version <id>) --dataset-version <id> --split-set <id-or-name> --split <name> [--runner-dir <dir>] --out <results.jsonl|results.jsonl.gz>',
@@ -356,6 +362,12 @@ export const COMMAND_DOCS = [
         summary: 'Push a local optimizer artifact directory.',
         group: 'Optimizations',
     },
+    {
+        path: ['optimizers', 'pull'],
+        usage: 'orizu optimizers pull <optimizer-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <version-id>] [--json]',
+        summary: 'Pull an optimizer artifact version to a local directory.',
+        group: 'Optimizations',
+    },
     {
         path: ['runs', 'submit'],
         usage: 'orizu runs submit <results.jsonl|results.jsonl.gz> --prompt-version <id> --runner-version <id> --dataset-version <id> --split-set <id> --split <name> [--project <team/project>]',

package/dist/index.js

@@ -27,6 +27,7 @@ import { formatTaskCreateError } from './task-create-error.js';
 import { renderAgentSetupPrompt } from './setup-prompt.js';
 import { getWorkspaceRoot, initOrizuWorkspace, workspaceExists, } from './workspace.js';
 import { connectorsCommand } from './connectors-cli.js';
+import { ARTIFACT_MAX_BYTES, pullArtifactCommand } from './artifact-pull.js';
 import { killSwitchCommand } from './kill-switch-cli.js';
 import { egressAllowlistCommand } from './egress-allowlist-cli.js';
 import { manifestsCommand } from './manifests-cli.js';
@@ -2862,7 +2863,7 @@ async function setupCommand() {
     const skipConfirm = hasArg('--yes');
     const noInput = hasArg('--no-input') || hasArg('--non-interactive') || !isInteractiveTerminal();
     const workspaceArg = getOptionalArgValue('--workspace');
-    const workspaceRoot = workspaceArg ? resolve(expandHomePath(workspaceArg)) : process.cwd();
+    const workspaceRoot = workspaceArg ? resolve(expandHomePath(workspaceArg)) : process.cwd(); // non-empty-dir guard now lives next to the hosted clone in runInteractiveHostedSetup, so --skip-login / decline-connect / local scaffolds are never blocked
     const teamArg = getOptionalArgValue('--team');
     const projectArg = getOptionalArgValue('--project');
     const setupSkillHome = resolveSetupSkillHome();
@@ -4595,7 +4596,6 @@ function readRunnerManifest(runnerDir) {
 }
 const RUNNER_TIMEOUT_MS = 120_000;
 const RUNNER_OUTPUT_MAX_BYTES = 2 * 1024 * 1024;
-const RUNNER_ARTIFACT_MAX_BYTES = 25 * 1024 * 1024;
 const RUNNER_ENV_ALLOWLIST = new Set([
     'PATH',
     'SystemRoot',
@@ -4643,9 +4643,9 @@ async function materializeRunnerVersion(runnerVersionId) {
     const zipPath = join(tempDir, 'runner.zip');
     const runnerDir = join(tempDir, 'runner');
     const zipBytes = new Uint8Array(await response.arrayBuffer());
-    if (zipBytes.byteLength > RUNNER_ARTIFACT_MAX_BYTES) {
+    if (zipBytes.byteLength > ARTIFACT_MAX_BYTES) {
         rmSync(tempDir, { recursive: true, force: true });
-        throw new Error(`Runner artifact exceeds ${RUNNER_ARTIFACT_MAX_BYTES} bytes`);
+        throw new Error(`Runner artifact exceeds ${ARTIFACT_MAX_BYTES} bytes`);
     }
     writeFileSync(zipPath, zipBytes);
     const result = spawnSync('unzip', ['-q', zipPath, '-d', runnerDir], {
@@ -4997,16 +4997,16 @@ export async function main(rawArgs = process.argv.slice(2)) {
         await execScorer();
         return;
     }
-    if (command === 'runners' && subcommand === 'push') {
-        await pushRunnerArtifact('runner');
+    if ((command === 'runners' || command === 'optimizers') && subcommand === 'push') {
+        await pushRunnerArtifact(command === 'runners' ? 'runner' : 'optimizer');
         return;
     }
-    if (command === 'runners' && subcommand === 'exec') {
-        await runnersExec();
+    if ((command === 'runners' || command === 'optimizers') && subcommand === 'pull') {
+        await pullArtifactCommand(cliArgs, { json: hasJsonFlag(), print: printLine, resolveProjectSlug });
         return;
     }
-    if (command === 'optimizers' && subcommand === 'push') {
-        await pushRunnerArtifact('optimizer');
+    if (command === 'runners' && subcommand === 'exec') {
+        await runnersExec();
         return;
     }
     if (command === 'runs' && subcommand === 'submit') {

package/dist/workspace.js

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, mkdirSync, readlinkSync, readdirSync, readFileSync, renameSync, symlinkSync, unlinkSync, writeFileSync, } from 'fs';
+import { existsSync, lstatSync, mkdirSync, readlinkSync, readdirSync, readFileSync, renameSync, statSync, symlinkSync, unlinkSync, writeFileSync, } from 'fs';
 import { dirname, join, relative, resolve } from 'path';
 export const WORKSPACE_DIR_NAME = '.orizu';
 export const WORKSPACE_SCHEMA_VERSION = 'orizu.workspace.v0';
@@ -82,6 +82,61 @@ export function getWorkspaceRoot(cwd) {
 export function workspaceExists(cwd) {
     return existsSync(join(getWorkspaceRoot(cwd), 'orizu.team.json'));
 }
+/**
+ * `orizu setup`'s hosted path clones the workbench repo into the resolved
+ * workspace root; `git clone` refuses to write into ANY non-empty directory —
+ * including one holding only macOS `.DS_Store` cruft — and fails late with a
+ * raw git error (ALI QA: founder ran `orizu setup` from an existing folder).
+ * Call this right before the hosted clone so the failure is immediate and
+ * actionable instead of surfacing mid-clone.
+ *
+ * A directory is usable only when it doesn't exist yet, is STRICTLY empty
+ * (`readdirSync(...).length === 0` — no `.DS_Store` allowance, since git itself
+ * grants none), or is already a recognized Orizu workspace for a re-run
+ * (`workspaceExists`, i.e. it has `orizu.team.json`) — the legitimate
+ * idempotent-setup case, which must proceed. Symlinks are followed (a symlink
+ * to an empty dir is fine); a file, an unreadable dir, and a non-empty dir each
+ * get a distinct, friendly message.
+ */
+export function assertWorkspaceDirUsable(root) {
+    const resolvedRoot = resolve(root);
+    if (!existsSync(resolvedRoot))
+        return;
+    if (workspaceExists(resolvedRoot))
+        return;
+    let stat;
+    try {
+        // statSync (not lstatSync) follows symlinks, so a symlink to an empty dir
+        // is treated as the empty dir it points at.
+        stat = statSync(resolvedRoot);
+    }
+    catch {
+        // Broken symlink / vanished between checks — nothing to clone over.
+        return;
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`The path ${resolvedRoot} is a file, but \`orizu setup\` needs a directory to clone your workbench repo into. `
+            + 'Choose an empty directory (or pass `--workspace <empty-path>`, or `--local` to scaffold a local-only workspace elsewhere), then re-run `orizu setup`.');
+    }
+    let entries;
+    try {
+        entries = readdirSync(resolvedRoot);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'EACCES' || code === 'EPERM') {
+            throw new Error(`The directory ${resolvedRoot} can't be read (permission denied). `
+                + 'Fix its permissions, or pass `--workspace <empty-path>` (or `--local`), then re-run `orizu setup`.');
+        }
+        throw error;
+    }
+    if (entries.length === 0)
+        return;
+    throw new Error(`The directory ${resolvedRoot} is not empty. \`orizu setup\` clones your workbench repo here and needs an empty directory. `
+        + 'Create and enter an empty sub-directory (for example: `mkdir orizu-workbench && cd orizu-workbench`), '
+        + 'pass `--workspace <empty-path>`, or pass `--local` to scaffold a local-only workspace in place, '
+        + 'then re-run `orizu setup`.');
+}
 function formatJson(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }

package/package.json

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

package/src/artifact-pull.ts

@@ -0,0 +1,203 @@
+/**
+ * Runner/optimizer artifact pull (symmetric with `runners push` /
+ * `optimizers push`): resolve the artifact by id or name, download the
+ * content-addressed zip from storage, and extract it into --out. Version
+ * metadata is written to .orizu/pull.json — .orizu/ is excluded from artifact
+ * zips (see artifact-archive.ts), so a pulled directory re-pushes with an
+ * identical content hash.
+ *
+ * Lives outside index.ts per the CLI index line ratchet (ALI-976): this module
+ * owns its own argument parsing and printing via injected io.
+ */
+
+import { spawnSync } from 'child_process'
+import { createHash } from 'crypto'
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { dirname, join } from 'path'
+
+import { authedFetch } from './http.js'
+
+export type PullableArtifactKind = 'runner' | 'optimizer'
+
+export interface PullArtifactIo {
+  json: boolean
+  print: (line: string) => void
+  resolveProjectSlug: (projectArg: string | null) => Promise<string>
+  fetcher?: (path: string, init?: RequestInit) => Promise<Response>
+}
+
+// Shared with the runners exec download path in index.ts.
+export const ARTIFACT_MAX_BYTES = 25 * 1024 * 1024
+
+function sanitizeTerminalText(value: unknown): string {
+  return String(value).replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, '')
+}
+
+function expandHomePath(path: string): string {
+  if (path.startsWith('~/')) {
+    const home = process.env.HOME || ''
+    return `${home}/${path.slice(2)}`
+  }
+
+  return path
+}
+
+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
+  }
+  return args[index + 1]
+}
+
+async function parseJsonPayload<T>(response: Response, context: string): Promise<T> {
+  const contentType = response.headers.get('content-type') || ''
+  const rawBody = await response.text()
+
+  if (!contentType.includes('application/json')) {
+    throw new Error(
+      `${context} returned non-JSON response (status ${response.status}). ` +
+      `Body preview: ${sanitizeTerminalText(rawBody.slice(0, 180))}`
+    )
+  }
+
+  try {
+    return JSON.parse(rawBody) as T
+  } catch {
+    throw new Error(
+      `${context} returned invalid JSON (status ${response.status}). ` +
+      `Body preview: ${sanitizeTerminalText(rawBody.slice(0, 180))}`
+    )
+  }
+}
+
+interface PullArtifactResponse {
+  runner?: { id: string; name: string }
+  optimizer?: { id: string; name: string }
+  version: {
+    id: string
+    contentSha256?: string
+    manifest?: Record<string, unknown>
+    uploadedAt?: string
+  }
+  labels?: Array<{ label: string; runnerVersionId?: string; optimizerVersionId?: string }>
+}
+
+export async function pullArtifactCommand(args: string[], io: PullArtifactIo) {
+  const kind: PullableArtifactKind = args[0] === 'runners' ? 'runner' : 'optimizer'
+  const fetcher = io.fetcher || authedFetch
+  const positionalRef = args[2]
+  const artifactRef = positionalRef && !positionalRef.startsWith('--') ? positionalRef : null
+  const outDir = argValue(args, '--out')
+  const label = argValue(args, '--label')
+  const version = argValue(args, '--version')
+
+  // Argument errors surface before project resolution, which may prompt
+  // interactively when --project is omitted.
+  const plural = kind === 'runner' ? 'runners' : 'optimizers'
+  if (!artifactRef || !outDir) {
+    throw new Error(`Usage: orizu ${plural} pull <${kind}-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <version-id>] [--json]`)
+  }
+  if (label && version) {
+    throw new Error('Use either --label or --version, not both')
+  }
+
+  const project = argValue(args, '--project') || await io.resolveProjectSlug(null)
+
+  const params = new URLSearchParams({ project })
+  if (label) params.set('label', label)
+  if (version) params.set('version', version)
+
+  const response = await fetcher(`/api/cli/${plural}/${encodeURIComponent(artifactRef)}?${params.toString()}`)
+  if (!response.ok) {
+    throw new Error(`Failed to pull ${kind}: ${await response.text()}`)
+  }
+
+  const data = await parseJsonPayload<PullArtifactResponse>(response, `${kind} pull`)
+  const artifact = kind === 'runner' ? data.runner : data.optimizer
+  if (!artifact) {
+    throw new Error(`Failed to pull ${kind}: malformed response`)
+  }
+  // Every stored version is content-addressed; a missing hash would silently
+  // void the integrity check and the pull.json anchor, so fail instead.
+  if (!data.version.contentSha256) {
+    throw new Error(`Failed to pull ${kind}: version ${data.version.id} has no content hash`)
+  }
+
+  const downloadResponse = await fetcher(`/api/cli/${kind}-versions/${encodeURIComponent(data.version.id)}/download`)
+  if (!downloadResponse.ok) {
+    throw new Error(`Failed to download ${kind} artifact: ${await downloadResponse.text()}`)
+  }
+
+  const zipBytes = new Uint8Array(await downloadResponse.arrayBuffer())
+  if (zipBytes.byteLength > ARTIFACT_MAX_BYTES) {
+    throw new Error(`${kind} artifact exceeds ${ARTIFACT_MAX_BYTES} bytes`)
+  }
+
+  // Versions are content-addressed by zip SHA256 (see the push routes), so a
+  // corrupted or mismatched download is detectable before anything is written.
+  const actualSha256 = createHash('sha256').update(zipBytes).digest('hex')
+  if (actualSha256 !== data.version.contentSha256.toLowerCase()) {
+    throw new Error(`${kind} artifact hash mismatch: expected ${data.version.contentSha256}, got ${actualSha256}`)
+  }
+
+  // Extraction is additive, so a dirty directory would mix files from other
+  // versions and break the pull -> identical re-push hash guarantee.
+  const targetDir = expandHomePath(outDir)
+  mkdirSync(targetDir, { recursive: true })
+  if (readdirSync(targetDir).length > 0) {
+    throw new Error(`Output directory is not empty: ${targetDir}`)
+  }
+
+  const tempDir = mkdtempSync(join(tmpdir(), `orizu-${kind}-pull-`))
+  try {
+    const zipPath = join(tempDir, 'artifact.zip')
+    writeFileSync(zipPath, zipBytes)
+    // Artifacts are self-authored, hash-verified above, and served only to
+    // authenticated project members; Info-ZIP additionally strips ../ path
+    // components on extraction (same trust model as materializeRunnerVersion).
+    const result = spawnSync('unzip', ['-q', zipPath, '-d', targetDir], {
+      encoding: 'utf8',
+    })
+    if (result.error || result.status !== 0) {
+      // targetDir was verified empty above, so everything in it came from
+      // this extraction — clear it so a re-pull isn't rejected as non-empty.
+      for (const entry of readdirSync(targetDir)) {
+        rmSync(join(targetDir, entry), { recursive: true, force: true })
+      }
+      if (result.error) {
+        throw result.error
+      }
+      throw new Error(`unzip failed: ${sanitizeTerminalText(result.stderr || result.stdout || '')}`)
+    }
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true })
+  }
+
+  const versionLabels = (data.labels || [])
+    .filter(item => (kind === 'runner' ? item.runnerVersionId : item.optimizerVersionId) === data.version.id)
+    .map(item => item.label)
+
+  const pullMetadataPath = join(targetDir, '.orizu', 'pull.json')
+  mkdirSync(dirname(pullMetadataPath), { recursive: true })
+  writeFileSync(pullMetadataPath, `${JSON.stringify({
+    schema_version: `orizu.${kind}-pull.v1`,
+    name: artifact.name,
+    [`${kind}_id`]: artifact.id,
+    version_id: data.version.id,
+    content_sha256: data.version.contentSha256,
+    labels: versionLabels,
+  }, null, 2)}\n`)
+
+  if (io.json) {
+    io.print(JSON.stringify({
+      [`${kind}_id`]: artifact.id,
+      [`${kind}_version_id`]: data.version.id,
+      path: targetDir,
+    }))
+    return
+  }
+
+  io.print(`Pulled ${kind} ${sanitizeTerminalText(artifact.name)} to ${sanitizeTerminalText(targetDir)}`)
+}

package/src/github-setup.ts

@@ -19,9 +19,20 @@ import { mkdirSync } from 'fs'
 import { join } from 'path'
 
 import { authedFetch } from './http.js'
+import { assertWorkspaceDirUsable } from './workspace.js'
 
 export type SetupFetcher = (path: string, init?: RequestInit) => Promise<Response>
 
+/**
+ * Strip terminal control characters from server-supplied strings before they
+ * are printed (mirrors index.ts `sanitizeTerminalText`), so a hostile or
+ * mangled provisioning `warnings[]`/`defaultBranch` value can't inject escape
+ * sequences into the user's terminal.
+ */
+function sanitizeServerText(value: unknown): string {
+  return String(value).replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, '')
+}
+
 export interface GithubLinkIo {
   print: (line: string) => void
   fetcher?: SetupFetcher
@@ -278,9 +289,25 @@ export async function runHostedAttach(
     if (!response.ok) {
       throw new Error(`Failed to provision workbench repo: ${await readError(response)}`)
     }
-    const data = (await response.json()) as { repo: string }
+    const data = (await response.json()) as {
+      repo: string
+      defaultBranch?: string
+      rulesetApplied?: boolean
+      warnings?: string[]
+    }
     repoFullName = data.repo
     provisioned = true
+
+    if (data.rulesetApplied === true) {
+      io.print(
+        `   Default-branch protection applied (ruleset "orizu-default-branch-protection"${
+          data.defaultBranch ? ` on ${sanitizeServerText(data.defaultBranch)}` : ''
+        }).`
+      )
+    }
+    for (const warning of data.warnings ?? []) {
+      io.print(`   ⚠ ${sanitizeServerText(warning)}`)
+    }
   }
 
   const cleanUrl = `https://github.com/${repoFullName}.git`
@@ -388,6 +415,15 @@ export async function runInteractiveHostedSetup(
     return { mode, attached: false, repoFullName: null }
   }
 
+  // The hosted paths (attach / provision-then-attach) clone the workbench repo
+  // into targetDir, and `git clone` refuses ANY non-empty directory. Fail fast
+  // here — before the provision call and the clone's git invocation, so no
+  // partial server/git state is created — with a friendly, actionable message
+  // (including the `--local` escape hatch). Only this real-clone path is gated;
+  // --local, --skip-login (not signed in), and a declined connect prompt never
+  // reach here, so they scaffold locally unblocked.
+  assertWorkspaceDirUsable(input.targetDir)
+
   const result = await runHostedAttach(
     { workspaceId: workspace.id, repoFullName, targetDir: input.targetDir },
     { print: io.print, fetcher, git: io.git ?? defaultGitRunner, ensureOrizuDir: io.ensureOrizuDir }

package/src/help.ts

@@ -369,6 +369,12 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
     summary: 'Push a local runner artifact directory.',
     group: 'Scorers and runners',
   },
+  {
+    path: ['runners', 'pull'],
+    usage: 'orizu runners pull <runner-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <version-id>] [--json]',
+    summary: 'Pull a runner artifact version to a local directory.',
+    group: 'Scorers and runners',
+  },
   {
     path: ['runners', 'exec'],
     usage: 'orizu runners exec (--prompt <prompt-version-id> | --prompt-version <id> --runner-version <id> | --scorer-version <id>) --dataset-version <id> --split-set <id-or-name> --split <name> [--runner-dir <dir>] --out <results.jsonl|results.jsonl.gz>',
@@ -381,6 +387,12 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
     summary: 'Push a local optimizer artifact directory.',
     group: 'Optimizations',
   },
+  {
+    path: ['optimizers', 'pull'],
+    usage: 'orizu optimizers pull <optimizer-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <version-id>] [--json]',
+    summary: 'Pull an optimizer artifact version to a local directory.',
+    group: 'Optimizations',
+  },
   {
     path: ['runs', 'submit'],
     usage: 'orizu runs submit <results.jsonl|results.jsonl.gz> --prompt-version <id> --runner-version <id> --dataset-version <id> --split-set <id> --split <name> [--project <team/project>]',

package/src/index.ts

@@ -59,6 +59,7 @@ import {
   workspaceExists,
 } from './workspace.js'
 import { connectorsCommand } from './connectors-cli.js'
+import { ARTIFACT_MAX_BYTES, pullArtifactCommand } from './artifact-pull.js'
 import { killSwitchCommand } from './kill-switch-cli.js'
 import { egressAllowlistCommand } from './egress-allowlist-cli.js'
 import { manifestsCommand } from './manifests-cli.js'
@@ -3820,7 +3821,7 @@ async function setupCommand() {
   const skipConfirm = hasArg('--yes')
   const noInput = hasArg('--no-input') || hasArg('--non-interactive') || !isInteractiveTerminal()
   const workspaceArg = getOptionalArgValue('--workspace')
-  const workspaceRoot = workspaceArg ? resolve(expandHomePath(workspaceArg)) : process.cwd()
+  const workspaceRoot = workspaceArg ? resolve(expandHomePath(workspaceArg)) : process.cwd() // non-empty-dir guard now lives next to the hosted clone in runInteractiveHostedSetup, so --skip-login / decline-connect / local scaffolds are never blocked
   const teamArg = getOptionalArgValue('--team')
   const projectArg = getOptionalArgValue('--project')
   const setupSkillHome = resolveSetupSkillHome()
@@ -5994,7 +5995,6 @@ function readRunnerManifest(runnerDir: string): { command: string[]; supports_bo
 
 const RUNNER_TIMEOUT_MS = 120_000
 const RUNNER_OUTPUT_MAX_BYTES = 2 * 1024 * 1024
-const RUNNER_ARTIFACT_MAX_BYTES = 25 * 1024 * 1024
 const RUNNER_ENV_ALLOWLIST = new Set([
   'PATH',
   'SystemRoot',
@@ -6045,9 +6045,9 @@ async function materializeRunnerVersion(runnerVersionId: string): Promise<{ runn
   const zipPath = join(tempDir, 'runner.zip')
   const runnerDir = join(tempDir, 'runner')
   const zipBytes = new Uint8Array(await response.arrayBuffer())
-  if (zipBytes.byteLength > RUNNER_ARTIFACT_MAX_BYTES) {
+  if (zipBytes.byteLength > ARTIFACT_MAX_BYTES) {
     rmSync(tempDir, { recursive: true, force: true })
-    throw new Error(`Runner artifact exceeds ${RUNNER_ARTIFACT_MAX_BYTES} bytes`)
+    throw new Error(`Runner artifact exceeds ${ARTIFACT_MAX_BYTES} bytes`)
   }
   writeFileSync(zipPath, zipBytes)
 
@@ -6462,18 +6462,17 @@ export async function main(rawArgs = process.argv.slice(2)) {
     return
   }
 
-  if (command === 'runners' && subcommand === 'push') {
-    await pushRunnerArtifact('runner')
+  if ((command === 'runners' || command === 'optimizers') && subcommand === 'push') {
+    await pushRunnerArtifact(command === 'runners' ? 'runner' : 'optimizer')
     return
   }
 
-  if (command === 'runners' && subcommand === 'exec') {
-    await runnersExec()
-    return
+  if ((command === 'runners' || command === 'optimizers') && subcommand === 'pull') {
+    await pullArtifactCommand(cliArgs, { json: hasJsonFlag(), print: printLine, resolveProjectSlug }); return
   }
 
-  if (command === 'optimizers' && subcommand === 'push') {
-    await pushRunnerArtifact('optimizer')
+  if (command === 'runners' && subcommand === 'exec') {
+    await runnersExec()
     return
   }
 

package/src/workspace.ts

@@ -6,6 +6,7 @@ import {
   readdirSync,
   readFileSync,
   renameSync,
+  statSync,
   symlinkSync,
   unlinkSync,
   writeFileSync,
@@ -185,6 +186,67 @@ export function workspaceExists(cwd?: string): boolean {
   return existsSync(join(getWorkspaceRoot(cwd), 'orizu.team.json'))
 }
 
+/**
+ * `orizu setup`'s hosted path clones the workbench repo into the resolved
+ * workspace root; `git clone` refuses to write into ANY non-empty directory —
+ * including one holding only macOS `.DS_Store` cruft — and fails late with a
+ * raw git error (ALI QA: founder ran `orizu setup` from an existing folder).
+ * Call this right before the hosted clone so the failure is immediate and
+ * actionable instead of surfacing mid-clone.
+ *
+ * A directory is usable only when it doesn't exist yet, is STRICTLY empty
+ * (`readdirSync(...).length === 0` — no `.DS_Store` allowance, since git itself
+ * grants none), or is already a recognized Orizu workspace for a re-run
+ * (`workspaceExists`, i.e. it has `orizu.team.json`) — the legitimate
+ * idempotent-setup case, which must proceed. Symlinks are followed (a symlink
+ * to an empty dir is fine); a file, an unreadable dir, and a non-empty dir each
+ * get a distinct, friendly message.
+ */
+export function assertWorkspaceDirUsable(root: string): void {
+  const resolvedRoot = resolve(root)
+  if (!existsSync(resolvedRoot)) return
+  if (workspaceExists(resolvedRoot)) return
+
+  let stat
+  try {
+    // statSync (not lstatSync) follows symlinks, so a symlink to an empty dir
+    // is treated as the empty dir it points at.
+    stat = statSync(resolvedRoot)
+  } catch {
+    // Broken symlink / vanished between checks — nothing to clone over.
+    return
+  }
+
+  if (!stat.isDirectory()) {
+    throw new Error(
+      `The path ${resolvedRoot} is a file, but \`orizu setup\` needs a directory to clone your workbench repo into. `
+      + 'Choose an empty directory (or pass `--workspace <empty-path>`, or `--local` to scaffold a local-only workspace elsewhere), then re-run `orizu setup`.'
+    )
+  }
+
+  let entries: string[]
+  try {
+    entries = readdirSync(resolvedRoot)
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code
+    if (code === 'EACCES' || code === 'EPERM') {
+      throw new Error(
+        `The directory ${resolvedRoot} can't be read (permission denied). `
+        + 'Fix its permissions, or pass `--workspace <empty-path>` (or `--local`), then re-run `orizu setup`.'
+      )
+    }
+    throw error
+  }
+  if (entries.length === 0) return
+
+  throw new Error(
+    `The directory ${resolvedRoot} is not empty. \`orizu setup\` clones your workbench repo here and needs an empty directory. `
+    + 'Create and enter an empty sub-directory (for example: `mkdir orizu-workbench && cd orizu-workbench`), '
+    + 'pass `--workspace <empty-path>`, or pass `--local` to scaffold a local-only workspace in place, '
+    + 'then re-run `orizu setup`.'
+  )
+}
+
 function formatJson(value: Record<string, unknown>): string {
   return `${JSON.stringify(value, null, 2)}\n`
 }