orizu 0.5.10 → 0.5.12

package/dist/credentials.js

@@ -206,6 +206,43 @@ export function resolveEnvBearerToken() {
     }
     return null;
 }
+/**
+ * THE uniform bearer resolution for every CLI command (ALI-1090). Exactly the
+ * order `authedFetch` uses: `ORIZU_TOKEN` env → `ORIZU_TOKEN_FILE` (both via
+ * resolveEnvBearerToken, read FRESH per call — never cached, so hosted token
+ * rotations are picked up) → stored credentials.json. Commands that need a raw
+ * bearer (`orizu env`, the run-gepa wrapper) MUST use this instead of reading
+ * credentials.json directly, or they break in hosted sandboxes that are
+ * pre-authenticated via ORIZU_TOKEN_FILE and never ran `orizu login`.
+ */
+export function resolveAuthTokenForBaseUrl(baseUrl) {
+    const envBearer = resolveEnvBearerToken();
+    if (envBearer) {
+        return envBearer;
+    }
+    const credentials = getServerCredentials(baseUrl);
+    if (!credentials) {
+        throw new Error(`Not logged in for ${baseUrl}. Run \`orizu login --server ${baseUrl}\` (or \`--local\`) first.`);
+    }
+    return 'accessToken' in credentials ? credentials.accessToken : credentials.apiKey;
+}
+/**
+ * Non-throwing "is any auth available?" check (login --no-prompt-if-logged-in,
+ * setup status). Mirrors resolveAuthTokenForBaseUrl's order so an env bearer
+ * counts as signed in. A misconfigured ORIZU_TOKEN_FILE reports false here —
+ * actual requests still fail loudly via resolveEnvBearerToken.
+ */
+export function hasResolvableAuth(baseUrl) {
+    try {
+        if (resolveEnvBearerToken()) {
+            return true;
+        }
+    }
+    catch {
+        // fall through to stored credentials
+    }
+    return getServerCredentials(baseUrl) !== null;
+}
 export function setActiveBaseUrl(baseUrl) {
     const config = loadCredentialsConfigForWrite();
     config.activeBaseUrl = baseUrl;

package/dist/daytona-slice-rehearsal.js

@@ -51,17 +51,17 @@ export function seedLocalBareRepo(baseDir, config) {
     const work = mkdtempSync(join(baseDir, 'seed-'));
     gitOrThrow(['init', '--initial-branch=main', work]);
     const ident = ['-c', 'user.email=seed@orizu.local', '-c', 'user.name=Seed'];
+    // ALI-1075: no `canonical`/`repoState` liveness fields — manifests carry
+    // machine-readable ids only; the DB label is the sole production pointer.
     const teamManifest = {
         schemaVersion: WORKSPACE_SCHEMA_VERSION,
         kind: 'team',
         slug: config.teamSlug,
-        canonical: { owner: 'repo', repoState: 'source', objectRef: null },
     };
     const projectManifest = {
         schemaVersion: WORKSPACE_SCHEMA_VERSION,
         kind: 'project',
         slug: config.projectSlug,
-        canonical: { owner: 'repo', repoState: 'draft', objectRef: null },
     };
     writeFileSync(join(work, 'orizu.team.json'), `${JSON.stringify(teamManifest, null, 2)}\n`);
     writeFileSync(join(work, '.gitignore'), '# Orizu workspace policy\n.orizu/\n');

package/dist/deploy-key-merge-core.js

@@ -0,0 +1,230 @@
+/**
+ * Transport-agnostic deploy-key merge core (ALI-1084, merge-sandbox-job
+ * Phase 0). Extracted VERBATIM from `lib/git-ssh-merge.ts` so both the server
+ * (`lib/`) and the published CLI (`orizu internal merge-job`, Phase 2) run the
+ * EXACT SAME merge logic — no forked implementations, one place where the
+ * ADR-007 §4 `--no-ff` invariant is asserted on the exact argv.
+ *
+ * DELIBERATELY NO `import 'server-only'`: this module runs inside the one-shot
+ * merge sandbox (a plain Node process) as well as on the server. It must not
+ * import anything outside the CLI package root (bun-bundled) — node builtins
+ * only. `lib/git-ssh-merge.ts` re-exports everything here so every existing
+ * server import path and test keeps working unchanged.
+ *
+ * SECURITY PROPERTIES (unchanged from the lib original):
+ *   - throwaway temp worktree + isolated SSH identity (key file mode 0600);
+ *   - pinned GitHub host keys (StrictHostKeyChecking=yes, own known_hosts);
+ *   - expected-head verification: the merge targets the REVIEWED SHA, never a
+ *     branch name;
+ *   - `merge-base --is-ancestor` alreadyMerged idempotency check;
+ *   - argv-asserted commit-preserving `--no-ff` merge (ADR-007 §4).
+ */
+import { spawn } from 'node:child_process';
+import { chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * ADR-007 §4 merge-strategy invariant: the seal merge must stay a COMMIT-
+ * PRESERVING merge. `--no-ff` keeps the session-branch head as a parent of the
+ * merge commit, so every create-time `commit_sha` pinned by a draft version
+ * row stays reachable on the default branch forever. A squash or rebase would
+ * rewrite/discard those commits and orphan the pins — "what the label says is
+ * live" could then dangle. These flags must never appear in the seal merge.
+ */
+const FORBIDDEN_SEAL_MERGE_FLAGS = ['--squash', '--ff-only', '--ff', 'rebase'];
+const REQUIRED_SEAL_MERGE_FLAG = '--no-ff';
+/**
+ * Assert a git invocation is the commit-preserving seal merge ADR-007 §4
+ * requires. Called on the exact argv the merge runs with, so the invariant is
+ * enforced where the merge happens rather than by reviewer vigilance.
+ */
+export function assertCommitPreservingMergeArgs(args) {
+    if (!args.includes('merge')) {
+        throw new Error('seal merge invariant: expected a git merge invocation');
+    }
+    if (!args.includes(REQUIRED_SEAL_MERGE_FLAG)) {
+        throw new Error(`seal merge invariant violated: ${REQUIRED_SEAL_MERGE_FLAG} is required (ADR-007 §4 — the merge must keep the session head as a parent)`);
+    }
+    for (const flag of FORBIDDEN_SEAL_MERGE_FLAGS) {
+        if (args.includes(flag)) {
+            throw new Error(`seal merge invariant violated: ${flag} would rewrite or drop session commits and orphan draft version pins (ADR-007 §4)`);
+        }
+    }
+}
+const LOCAL_BASE_REF = 'refs/heads/__orizu_merge_base';
+const LOCAL_SOURCE_REF = 'refs/remotes/origin/__orizu_merge_source';
+// GitHub's published SSH host keys:
+// https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints
+const GITHUB_KNOWN_HOSTS = [
+    'github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl',
+    'github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=',
+    'github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=',
+].join('\n') + '\n';
+/**
+ * Strip git's repo-context env vars from a child git's environment. Git
+ * EXPORTS these into hook subprocesses (from a linked worktree, GIT_DIR is an
+ * ABSOLUTE path into the shared .git), so any descendant git command that
+ * inherits the parent env operates on THAT repo instead of its own cwd —
+ * `git config` writes land in the shared .git/config and `git init` flips it
+ * to core.bare=true (both observed when the pre-push hook ran the test suite
+ * from a worktree). Every real-git spawn must build its env through this.
+ */
+export function scrubGitRepoContextEnv(env = process.env) {
+    const scrubbed = { ...env };
+    delete scrubbed.GIT_DIR;
+    delete scrubbed.GIT_WORK_TREE;
+    delete scrubbed.GIT_INDEX_FILE;
+    delete scrubbed.GIT_OBJECT_DIRECTORY;
+    delete scrubbed.GIT_COMMON_DIR;
+    delete scrubbed.GIT_NAMESPACE;
+    return scrubbed;
+}
+// Exported: the ADR-007 P3 read path (lib/artifact-git-read.ts) runs its
+// verified reads through the same spawn.
+export function defaultRunGit(args, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', args, {
+            cwd: options.cwd,
+            env: options.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', chunk => { stdout += chunk; });
+        child.stderr.on('data', chunk => { stderr += chunk; });
+        child.on('error', reject);
+        child.on('close', code => resolve({ exitCode: code ?? 1, stdout, stderr }));
+    });
+}
+export function sshRemote(repoFullName) {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repoFullName)) {
+        throw new Error(`Invalid repo full name: ${repoFullName}`);
+    }
+    return `git@github.com:${repoFullName}.git`;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+/** Exported for `lib/git-ssh-merge.ts` (pushFilesWithDeployKey keeps living
+ *  there — D9 scopes the push path as a follow-on, not part of the core). */
+export function assertGitOk(result, operation) {
+    if (result.exitCode === 0)
+        return;
+    const detail = (result.stderr || result.stdout).trim();
+    throw new Error(detail ? `${operation} failed: ${detail}` : `${operation} failed`);
+}
+function looksLikeMergeConflict(result) {
+    const output = `${result.stdout}\n${result.stderr}`;
+    return /CONFLICT|Automatic merge failed|Merge conflict/i.test(output);
+}
+/**
+ * Run a callback inside a throwaway git worktree wired to the repo's merge
+ * deploy key (isolated SSH identity + pinned GitHub host keys). Exported for
+ * the ADR-007 read path (lib/artifact-git-read.ts), which reuses the same
+ * clone/pack infrastructure for bulk artifact reads.
+ */
+export async function withDeployKeyGit(privateKeyPem, runGit, tempPrefix, callback) {
+    const tempRoot = await mkdtemp(join(tmpdir(), tempPrefix));
+    const dir = join(tempRoot, 'worktree');
+    const sshDir = join(tempRoot, 'ssh');
+    await mkdir(dir);
+    await mkdir(sshDir);
+    const keyPath = join(sshDir, 'merge_deploy_key');
+    const knownHostsPath = join(sshDir, 'known_hosts');
+    const env = {
+        // Scrubbed: a leaked GIT_DIR (git exports it into hooks) must never
+        // redirect this temp-worktree clone/merge onto another repo.
+        ...scrubGitRepoContextEnv(process.env),
+        GIT_TERMINAL_PROMPT: '0',
+        GIT_SSH_COMMAND: [
+            'ssh',
+            '-i',
+            shellQuote(keyPath),
+            '-o',
+            'IdentitiesOnly=yes',
+            '-o',
+            'StrictHostKeyChecking=yes',
+            '-o',
+            shellQuote(`UserKnownHostsFile=${knownHostsPath}`),
+        ].join(' '),
+    };
+    const git = (args) => runGit(args, { cwd: dir, env });
+    const gitOk = async (args, operation) => {
+        const result = await git(args);
+        assertGitOk(result, operation);
+        return result;
+    };
+    try {
+        await writeFile(keyPath, privateKeyPem, { mode: 0o600 });
+        await chmod(keyPath, 0o600);
+        await writeFile(knownHostsPath, GITHUB_KNOWN_HOSTS, { mode: 0o600 });
+        return await callback({ dir, git, gitOk });
+    }
+    finally {
+        await rm(tempRoot, { recursive: true, force: true });
+    }
+}
+/**
+ * Merge a reviewed session/revert branch head into the default branch using the
+ * server-only merge deploy key. The source branch is fetched only so GitHub can
+ * prove the reviewed SHA is still the branch tip; the merge itself targets the
+ * expected SHA, preserving the manifest CAS guarantee.
+ */
+export async function mergeBranchWithDeployKey(repoFullName, input, deps = {}) {
+    const runGit = deps.runGit ?? defaultRunGit;
+    return withDeployKeyGit(input.privateKeyPem, runGit, 'orizu-merge-', async ({ git, gitOk }) => {
+        await gitOk(['init'], 'git init');
+        await gitOk(['remote', 'add', 'origin', sshRemote(repoFullName)], 'git remote add');
+        await gitOk(['fetch', '--no-tags', 'origin', `refs/heads/${input.base}:${LOCAL_BASE_REF}`], 'git fetch default branch');
+        await gitOk(['checkout', '-B', '__orizu_merge_base', LOCAL_BASE_REF], 'git checkout default branch');
+        await gitOk(['fetch', '--no-tags', 'origin', `refs/heads/${input.sourceBranch}:${LOCAL_SOURCE_REF}`], 'git fetch reviewed source branch');
+        const sourceHead = (await gitOk(['rev-parse', LOCAL_SOURCE_REF], 'git rev-parse source')).stdout.trim();
+        if (sourceHead !== input.expectedHeadSha) {
+            throw new Error('branch moved since manifest creation; re-finish the session');
+        }
+        const ancestor = await git(['merge-base', '--is-ancestor', input.expectedHeadSha, 'HEAD']);
+        if (ancestor.exitCode === 0) {
+            const head = (await gitOk(['rev-parse', 'HEAD'], 'git rev-parse default')).stdout.trim();
+            return { merged: false, sha: head, alreadyMerged: true, conflict: false, status: 204 };
+        }
+        if (ancestor.exitCode !== 1) {
+            assertGitOk(ancestor, 'git merge-base');
+        }
+        // ADR-007 §4: the seal is a commit-preserving --no-ff merge — never squash,
+        // never rebase — so every draft version's create-time commit_sha stays
+        // reachable once the branch reaches the default branch.
+        const mergeArgs = [
+            '-c',
+            'user.name=Orizu',
+            '-c',
+            'user.email=bot@orizu.ai',
+            'merge',
+            '--no-ff',
+            '-m',
+            input.commitMessage,
+            input.expectedHeadSha,
+        ];
+        assertCommitPreservingMergeArgs(mergeArgs);
+        const merge = await git(mergeArgs);
+        if (merge.exitCode !== 0) {
+            if (looksLikeMergeConflict(merge)) {
+                return { merged: false, sha: null, alreadyMerged: false, conflict: true, status: 409 };
+            }
+            assertGitOk(merge, 'git merge');
+        }
+        const mergeSha = (await gitOk(['rev-parse', 'HEAD'], 'git rev-parse merge')).stdout.trim();
+        // D8 pre-push gate: the LAST check before anything reaches the default
+        // branch. A refused gate aborts with superseded — no push, no side effect
+        // (the temp worktree dies with this callback).
+        if (deps.prePushGate) {
+            const proceed = await deps.prePushGate();
+            if (!proceed) {
+                return { merged: false, sha: null, alreadyMerged: false, conflict: false, superseded: true, status: 409 };
+            }
+        }
+        await gitOk(['push', 'origin', `HEAD:refs/heads/${input.base}`], 'git push default branch');
+        return { merged: true, sha: mergeSha, alreadyMerged: false, conflict: false, status: 201 };
+    });
+}

package/dist/git-credential.js

@@ -45,17 +45,20 @@ export function resolveAttachedWorkspaceId(cwd) {
         const manifestPath = join(dir, 'orizu.team.json');
         if (existsSync(manifestPath)) {
             const manifest = readJsonManifest(manifestPath);
-            const canonical = manifest?.canonical;
-            const serviceId = canonical && typeof canonical === 'object' && !Array.isArray(canonical)
-                ? canonical.serviceId
-                : null;
-            if (typeof serviceId === 'string' && serviceId)
-                return serviceId;
+            // `setup.attachedWorkspaceId` is the attachment id; `canonical.serviceId`
+            // is a legacy duplicate kept only as a read fallback for old repos
+            // (ALI-1075: fresh manifests carry no `canonical` block).
             const setup = manifest?.setup;
             const attached = setup && typeof setup === 'object' && !Array.isArray(setup)
                 ? setup.attachedWorkspaceId
                 : null;
-            return typeof attached === 'string' && attached ? attached : null;
+            if (typeof attached === 'string' && attached)
+                return attached;
+            const canonical = manifest?.canonical;
+            const serviceId = canonical && typeof canonical === 'object' && !Array.isArray(canonical)
+                ? canonical.serviceId
+                : null;
+            return typeof serviceId === 'string' && serviceId ? serviceId : null;
         }
         const parent = dirname(dir);
         if (parent === dir)

package/dist/github-setup.js

@@ -14,7 +14,7 @@
  *      is immediately rewritten to a clean origin.
  */
 import { spawnSync } from 'child_process';
-import { mkdirSync } from 'fs';
+import { existsSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { authedFetch } from './http.js';
 import { assertWorkspaceDirUsable } from './workspace.js';
@@ -196,6 +196,23 @@ export async function runHostedAttach(options, io) {
         }
     }
     const cleanUrl = `https://github.com/${repoFullName}.git`;
+    const ensureOrizuDir = io.ensureOrizuDir ?? ((repoDir) => mkdirSync(join(repoDir, '.orizu'), { recursive: true }));
+    // Idempotent re-run (ALI-1069): `orizu setup` in an ALREADY-attached workspace
+    // reaches here with `targetDir` holding the prior clone (its `.git` plus the
+    // committed orizu.team.json — `assertWorkspaceDirUsable` deliberately exempts
+    // that dir as the idempotent case). `git clone` refuses ANY non-empty dir, so
+    // an unconditional clone would abort the re-run with a misleading "not an empty
+    // directory" error. Short-circuit: re-affirm the credential helper config
+    // (idempotent) and return without recloning.
+    const repoAlreadyCloned = io.repoAlreadyCloned ?? ((dir) => existsSync(join(dir, '.git')));
+    if (repoAlreadyCloned(options.targetDir)) {
+        io.print('   Workbench repo already attached — skipping clone.');
+        gitOrThrow(io.git, ['config', 'credential.helper', CREDENTIAL_HELPER], { cwd: options.targetDir });
+        gitOrThrow(io.git, ['config', 'credential.useHttpPath', 'true'], { cwd: options.targetDir });
+        ensureOrizuDir(options.targetDir);
+        io.print('   Attached. Configured the Orizu credential helper for git.');
+        return { repoFullName, provisioned, targetDir: options.targetDir };
+    }
     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.
@@ -211,7 +228,6 @@ export async function runHostedAttach(options, io) {
     // 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 });
-    const ensureOrizuDir = io.ensureOrizuDir ?? ((repoDir) => mkdirSync(join(repoDir, '.orizu'), { recursive: true }));
     ensureOrizuDir(options.targetDir);
     io.print('   Attached. Configured the Orizu credential helper for git.');
     return { repoFullName, provisioned, targetDir: options.targetDir };

package/dist/help.js

@@ -318,8 +318,8 @@ export const COMMAND_DOCS = [
     },
     {
         path: ['prompts', 'push'],
-        usage: 'orizu prompts push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]',
-        summary: 'Push a local prompt artifact directory as a new version.',
+        usage: 'orizu prompts push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--session <session-id>] [--json]',
+        summary: 'Push a local prompt artifact directory as a new version (with --session: a commit-first git draft).',
         group: 'Prompts and judges',
     },
     {
@@ -354,8 +354,8 @@ export const COMMAND_DOCS = [
     },
     {
         path: ['judges', 'push'],
-        usage: 'orizu judges push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]',
-        summary: 'Push a local judge artifact directory as a new version.',
+        usage: 'orizu judges push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--session <session-id>] [--json]',
+        summary: 'Push a local judge artifact directory as a new version (with --session: a commit-first git draft).',
         group: 'Prompts and judges',
     },
     {
@@ -747,23 +747,25 @@ export const COMMAND_DOCS = [
     },
     {
         path: ['session', 'start'],
-        usage: 'orizu session start [--project <team/project>] [--json]',
-        summary: 'Start a durable workspace session for the attached workspace and print the session id for later resume.',
+        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.',
         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: '--json', help: 'Emit the machine-readable session payload.' },
         ],
         examples: ['orizu session start', 'orizu session start --project highlight/hip --json'],
     },
     {
         path: ['session', 'status'],
-        usage: 'orizu session status [--session <id> | --status active|ended] [--json]',
-        summary: 'Inspect one session by id, including run summaries, or list sessions for the attached workspace.',
+        usage: 'orizu session status [--session <id> | --status active|ended] [--workspace <dir>] [--json]',
+        summary: 'Inspect one session by id (including run summaries and, when run inside the workbench clone, the session branch with local ahead/behind vs origin), or list sessions for the attached workspace.',
         group: 'Sessions',
         options: [
             { name: '--session <id>', help: 'Resume by session id; does not require the original terminal.' },
             { name: '--status <status>', help: 'Filter attached-workspace sessions when --session is omitted.', choices: ['active', 'ended'] },
+            { name: '--workspace <dir>', help: 'Workbench clone directory when not running from inside it.' },
             { name: '--json', help: 'Emit the machine-readable session or session-list payload.' },
         ],
         examples: ['orizu session status --session sess_123 --json', 'orizu session status --status active'],
@@ -781,15 +783,18 @@ export const COMMAND_DOCS = [
     },
     {
         path: ['session', 'finish'],
-        usage: 'orizu session finish --session <id> [--project <team/project>] [--json]',
-        summary: 'Finish a hosted session branch: no changes deletes the branch; changes create a repo_merge promotion manifest to review and approve (no GitHub PR).',
+        usage: 'orizu session finish --session <id> [--project <team/project>] [--push [--message <text>]] [--workspace <dir>] [--json]',
+        summary: 'Finish a hosted session branch: no changes deletes the branch; changes create a repo_merge promotion manifest to review and approve (no GitHub PR). Warns when your local session-branch checkout has uncommitted/unpushed work; --push stages, commits, and pushes it first.',
         group: 'Sessions',
         options: [
             { name: '--session <id>', help: 'Session id whose branch to finish.', required: true },
             { name: '--project <team/project>', help: 'Project scope for the manifest when the session is not already project-scoped.' },
+            { name: '--push', help: 'Opt-in: stage, commit, and push local session-branch work before finishing (raw git stays the default workflow).' },
+            { name: '--message <text>', help: 'Commit message for --push (a default is used when omitted).' },
+            { name: '--workspace <dir>', help: 'Workbench clone directory when not running from inside it.' },
             { name: '--json', help: 'Emit the machine-readable outcome (no-changes or the created manifest).' },
         ],
-        examples: ['orizu session finish --session sess_123', 'orizu session finish --session sess_123 --project highlight/hip --json'],
+        examples: ['orizu session finish --session sess_123', 'orizu session finish --session sess_123 --push --message "tune judge prompt"'],
     },
     {
         path: ['run', 'start'],