recess-cli 1.9.2 → 2.0.0

package/dist/cli.js

@@ -1,21 +1,38 @@
 import { createHash, randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { RecessAdminApi, unwrap } from "./api.js";
+import { RecessAdminApi, unwrap, withIdempotencyContext } from "./api.js";
 import { flagList, flagNumber, flagString, hasFlag, parseArgs, } from "./args.js";
 import { login, pollDeviceAuth, requestDeviceAuth } from "./auth.js";
-import { clearStoredSession, resolveConfig, } from "./config.js";
+import { clearStoredSession, deleteProfile, listProfiles, resolveConfig, saveProfile, useProfile, } from "./config.js";
+import { agentContext, buildCommandSchema, scopedHelp, validateInvocation, } from "./command-schema.js";
 import { CliError } from "./errors.js";
+import { listFeedback, submitFeedback } from "./feedback.js";
+import { cliRequestHeaders, requireCliRequestReason } from "./http.js";
 import { requireConfirmation } from "./safety.js";
 import { installSkill, isEphemeralInstall, readBundledSkillVersion, readCliVersion, } from "./setup.js";
 import { compareVersions, updateSkillFromServer } from "./skill-update.js";
 import { readSkillCache, writeSkillCache } from "./skills-cache.js";
+import { appendJobEvent, getJob, listJobs, pruneJobs } from "./jobs.js";
 export const HELP = `recess — safe Recess administration and family AI tools
 
 Usage:
   recess [--json] --version
+  recess [--json] agent-context
   recess [--json] setup [--skill-only]
   recess [--json] doctor
+  recess [--json] profile list
+  recess [--json] profile show <name>
+  recess [--json] profile save <name> [--api-origin URL] [--web-origin URL]
+    [--oauth-client-id ID]
+  recess [--json] profile use <name>
+  recess [--json] profile delete <name>
+  recess [--json] jobs list [--limit 20]
+  recess [--json] jobs get <operation-key>
+  recess [--json] jobs prune [--older-than-days 30]
+  recess [--json] feedback list [--limit 20]
+  recess [--json] feedback submit <text> [--confirm]
   recess [--json] auth login [--client-id ID] [--callback-port 8765]
   recess [--json] auth request [--label TEXT]
   recess [--json] auth poll [--timeout 300]
@@ -53,7 +70,8 @@ Usage:
     [--family <family-id>] [--unassign <kid-id>] (repeat) [--note TEXT] [--confirm]
   recess [--json] cohorts search <query>
   recess [--json] enrollments create --user <kid-id> --cohort <id>
-    [--first-charge-at ISO_DATETIME] [--send-email] [--force] [--confirm]
+    [--first-charge-at ISO_DATETIME] [--send-email] [--force]
+    [--confirm --approval-token TOKEN]
   recess [--json] enrollments register-cohort --enrollment <id>
     --user <id> --cohort <id> [--confirm]
   recess [--json] enrollments unregister-cohort --user <id>
@@ -65,6 +83,7 @@ Usage:
     [--immediate] [--reason TEXT] [--restore] [--confirm]
   recess [--json] payout payruns list [--status A,B] [--schedule <id>]
   recess [--json] payout recipients list [--search <name>] [--user <id>] [--id <id>]
+    [--limit 20] [--cursor <id>]
   recess [--json] payout invoices list [--payrun <id>] [--recipient <account-id>]
     [--user <id>] [--status A,B]   (at least one filter)
   recess [--json] payout invoices get <invoice-id>
@@ -132,11 +151,11 @@ Usage:
   recess [--json] content-library search <query> [--limit 8]
   recess [--json] content-library status <gem-id-or-url>
   recess [--json] content-library set-stage <gem-id-or-url...> [--file <path>]
-    --stage review|polishing|live|archived [--confirm]
+    --stage review|polishing|live|archived [--wait] [--timeout 900] [--confirm]
   recess [--json] content-library submit <url...> [--file <path>]
     [--stage review|polish] [--title TEXT] [--summary TEXT]
     [--lane web-toys|mechanics|explorables|data-stories|sims|maps-scale|sound-art|puzzles|wonder|idea-games]
-    [--confirm]
+    [--wait] [--timeout 900] [--confirm]
   recess [--json] skills guardian list [--query TEXT] [--category TEXT]
   recess [--json] skills guardian get <skill-name>
     [--reference NAME | --all-references] [--refresh]
@@ -146,12 +165,13 @@ Usage:
     [--refresh]
   recess [--json] goal-templates list [--query TEXT] [--category TEXT]
     [--kind SIMPLE|BLUEPRINT] [--starter-only] [--include-deleted]
+    [--limit 20] [--cursor <id>]
   recess [--json] goal-templates get <template-id|slug> [--spec-only]
   recess [--json] goal-templates versions <template-id> [--version N]
   recess [--json] goal-templates validate-spec --file <path/template.json>
   recess [--json] goal-templates create --file <path/template.json> [--confirm]
   recess [--json] goal-templates patch-spec <template-id|slug> --expected-version N
-    --patches-file <path/patches.json> [--confirm]
+    --patches-file <path/patches.json> [--confirm --approval-token TOKEN]
     [--confirm-destructive-changes --destructive-change-token TOKEN]
   recess [--json] goal-templates set-metadata <template-id> --expected-version N
     [--title TEXT] [--description TEXT] [--emoji X] [--category TEXT] [--tags A,B]
@@ -162,20 +182,23 @@ Usage:
   recess [--json] goal-templates delete <template-id> --expected-version N [--confirm]
   recess [--json] goal-templates snapshot-files <template-id> [--path P]
   recess [--json] goal-templates capture-snapshot <template-id|slug>
-    (--source-goal <goal-id> | --source-draft <draft-slug> --student <goal-owner-id>)
-    [--dry-run] [--confirm]
+    (--source-goal <goal-id> | --source-draft <draft-slug> --student <goal-owner-id>
+      | --source-dir <local-checkout>)
+    [--dry-run] [--confirm --approval-token TOKEN]
   recess [--json] goal-templates apply <template-id> --answers-file <path>
     [--dry-run] [--confirm --approval-token TOKEN]
   recess [--json] goal-templates apply-starter <template-id> --student <kid-id>
     [--answers-file <path>] [--confirm]
   recess [--json] goals list --student <kid-id>
-  recess [--json] goals create --student <kid-id> --title TEXT
+  recess [--json] goals create [--student <kid-id>] --title TEXT
     (--description TEXT | --description-file <path>) [--target-date <iso>]
-    [--schedule TEXT] [--draft <draft-slug>
+    [--schedule TEXT] [(--draft <draft-slug> | --source-dir <local-checkout>)
       (--enable-applet-follow-ups | --disable-applet-follow-ups)]
     [--confirm --approval-token TOKEN]
   recess [--json] goals edit <goal-id> --student <kid-id> --patch-file <path/patch.json>
     --delta TEXT [--confirm --approval-token TOKEN]
+  recess [--json] goals delete <goal-id> --student <kid-id>
+    [--confirm --approval-token TOKEN]
   recess [--json] goals queue get <goal-id> --student <kid-id>
   recess [--json] goals queue set <goal-id> --student <kid-id>
     --entries-file <path.json> --delta TEXT [--replace-description-pointer]
@@ -184,6 +207,8 @@ Usage:
     [--due-date YYYY-MM-DD] [--estimated-minutes N] [--url URL] [--confirm]
   recess [--json] todos edit <todo-id> --patch-file <path/patch.json>
     [--confirm --approval-token TOKEN]
+  recess [--json] todos delete <todo-id>
+    [--confirm --approval-token TOKEN]
   recess [--json] todos generate-applet <todo-id> --student <kid-id>
     [--due-date YYYY-MM-DD] [--confirm --approval-token TOKEN]
   recess [--json] memories context --student <kid-id>
@@ -193,6 +218,13 @@ Usage:
     --expected-updated-at ISO|none [--confirm]
   recess [--json] goals files list --student <goal-owner-id> --goal <goal-id>
   recess [--json] goals files read --student <goal-owner-id> --goal <goal-id> --path P
+  recess [--json] goals files init --student <goal-owner-id> --draft <draft-slug>
+    --output-dir <local-dir>
+  recess [--json] goals files checkout --student <goal-owner-id>
+    (--goal <goal-id> | --draft <draft-slug>)
+    --output-dir <local-dir>
+  recess [--json] goals files push --source-dir <local-checkout>
+    [--message TEXT] [--confirm --approval-token TOKEN]
   recess [--json] goals files write --student <goal-owner-id>
     (--goal <goal-id> | --draft <draft-slug>)
     (--source-dir <local-dir> | --source-file <local-file> --path P)
@@ -211,10 +243,10 @@ standard. Responses cache under ~/.recess-cli/skills-cache/ (--refresh re-fetche
 For goal workspace and PDF commands, --student names the goal owner. A
 full_admin session may use a KID or ADMIN user id, including its own ADMIN id;
 family_ai sessions remain limited to managed KID profiles.
-"goals create --draft" materializes that validated draft directly as a personal
-module-backed goal; it does not create or apply a reusable template. Its preview
-is bound to the exact workspace revision, hash, module inventory, and applet
-follow-up choice.
+"goals create --source-dir" materializes a clean, fully pushed draft checkout as
+a personal module-backed goal and retargets that checkout to the resulting live
+goal. It does not create or apply a reusable template. Its preview is bound to
+the exact workspace revision, hash, module inventory, and applet follow-up choice.
 Every template created here is setupMode DETERMINISTIC_WORKFLOW and CANNOT be
 converted back, so "validate-spec" against the same file until it passes, then
 "create". "create" runs a real server-side validation before its gate, so the
@@ -261,8 +293,14 @@ bundled copy, and an unreachable server is not an error. "doctor" reports whethe
 a newer skill exists and names the command; it never writes.
 
 Writes preview and exit 2 unless --confirm is supplied after explicit human approval.
+Every preview includes an operationKey; confirmed writes must echo it with
+--operation-key so an interrupted invocation can be retried without duplicating the write.
 Environment overrides: RECESS_CLI_API_ORIGIN, RECESS_CLI_WEB_ORIGIN,
-RECESS_CLI_OAUTH_CLIENT_ID, RECESS_CLI_COOKIE, RECESS_CLI_CONFIG.`;
+RECESS_CLI_OAUTH_CLIENT_ID, RECESS_CLI_COOKIE, RECESS_CLI_CONFIG,
+RECESS_CLI_PROFILE, RECESS_CLI_FEEDBACK_ENDPOINT.
+
+Every command that calls the Recess API, except auth commands, requires
+--reason TEXT: a non-empty human-readable purpose of at most 1024 characters.`;
 function positional(parsed, index, label) {
     const value = parsed.positionals[index];
     if (!value) {
@@ -270,6 +308,9 @@ function positional(parsed, index, label) {
     }
     return value;
 }
+function requiredRequestReason(parsed) {
+    return requireCliRequestReason(flagString(parsed, "reason", { required: true }));
+}
 async function sessionStatus(config) {
     if (!config.sessionCookie) {
         return {
@@ -291,18 +332,20 @@ async function sessionStatus(config) {
     }
     return { ...result.data, authSource: config.authSource };
 }
-async function doctor(config) {
+async function doctor(config, reason) {
     const checks = {
         config: {
             path: config.configPath,
             apiOrigin: config.apiOrigin,
             webOrigin: config.webOrigin,
             oauthClientIdConfigured: Boolean(config.oauthClientId),
+            profile: config.profileName ?? null,
         },
         auth: await sessionStatus(config),
     };
     try {
         const response = await fetch(new URL("/health", config.apiOrigin), {
+            headers: cliRequestHeaders(undefined, reason),
             signal: AbortSignal.timeout(5000),
         });
         checks.api = { reachable: response.ok, status: response.status };
@@ -313,7 +356,7 @@ async function doctor(config) {
             message: error instanceof Error ? error.message : String(error),
         };
     }
-    checks.skill = await skillStatus(config);
+    checks.skill = await skillStatus(config, reason);
     return checks;
 }
 /**
@@ -322,7 +365,7 @@ async function doctor(config) {
  * silently rewrote `~/.claude/skills` mid-session would change what the agent is
  * reading out from under it. It names the command instead.
  */
-async function skillStatus(config) {
+async function skillStatus(config, reason) {
     const cliVersion = await readCliVersion();
     const installedVersion = await readBundledSkillVersion();
     const base = { cliVersion, bundledSkillVersion: installedVersion };
@@ -331,7 +374,7 @@ async function skillStatus(config) {
     }
     try {
         const response = await fetch(new URL("/auth/admin-cli/skill/", config.apiOrigin), {
-            headers: { cookie: config.sessionCookie },
+            headers: cliRequestHeaders({ cookie: config.sessionCookie }, reason),
             signal: AbortSignal.timeout(5000),
         });
         if (!response.ok) {
@@ -366,30 +409,433 @@ async function skillStatus(config) {
     }
 }
 async function writeCommand(parsed, preview, execute) {
-    requireConfirmation(hasFlag(parsed, "confirm"), preview);
-    return execute();
+    const fingerprint = approvalTokenFor(preview);
+    const suppliedOperationKey = flagString(parsed, "operation-key");
+    if (!hasFlag(parsed, "confirm")) {
+        const operationKey = operationKeyFor(fingerprint);
+        const boundPreview = {
+            ...preview,
+            details: {
+                ...preview.details,
+                operationKey,
+                retry: "Rerun the unchanged command with --confirm --operation-key <operationKey>. Reuse that same key after an interrupted invocation.",
+            },
+        };
+        await appendJobEvent({
+            jobId: operationKey,
+            status: "awaiting_confirmation",
+            timestamp: new Date().toISOString(),
+            action: preview.action,
+            fingerprint,
+            target: preview.target,
+        });
+        requireConfirmation(false, boundPreview);
+    }
+    if (!suppliedOperationKey) {
+        throw new CliError("confirmation_required", "A confirmed write requires the operation key from its approved preview.", 2, { preview, requiredFlag: "--operation-key" });
+    }
+    assertOperationKeyMatchesPreview(suppliedOperationKey, fingerprint, preview);
+    await appendJobEvent({
+        jobId: suppliedOperationKey,
+        status: "running",
+        timestamp: new Date().toISOString(),
+        action: preview.action,
+        fingerprint,
+        target: preview.target,
+    });
+    try {
+        const result = await withIdempotencyContext({ operationKey: suppliedOperationKey, fingerprint }, execute);
+        await appendJobEvent({
+            jobId: suppliedOperationKey,
+            status: "completed",
+            timestamp: new Date().toISOString(),
+            action: preview.action,
+            fingerprint,
+            target: preview.target,
+            result,
+        });
+        return result;
+    }
+    catch (error) {
+        await appendJobEvent({
+            jobId: suppliedOperationKey,
+            status: "unknown",
+            timestamp: new Date().toISOString(),
+            action: preview.action,
+            fingerprint,
+            target: preview.target,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
 }
 const GOAL_WORKSPACE_WRITE_MAX_FILES = 1_000;
 const GOAL_WORKSPACE_WRITE_MAX_TOTAL_BYTES = 20 * 1024 * 1024;
 const GOAL_PDF_UPLOAD_MAX_BYTES = 1024 * 1024 * 1024;
 const GOAL_QUEUE_MAX_ENTRIES = 500;
 const URL_QUEUE_DESCRIPTION_POINTER = "Skill queue managed by the system.";
+const RECESS_GIT_METADATA = "recess-workspace.json";
+async function runGit(cwd, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        execFile("git", ["-C", cwd, ...args], {
+            encoding: "utf8",
+            maxBuffer: 32 * 1024 * 1024,
+            env: options.identity
+                ? {
+                    ...process.env,
+                    GIT_AUTHOR_NAME: "Recess CLI",
+                    GIT_AUTHOR_EMAIL: "cli@recess.gg",
+                    GIT_COMMITTER_NAME: "Recess CLI",
+                    GIT_COMMITTER_EMAIL: "cli@recess.gg",
+                }
+                : process.env,
+        }, (error, stdout, stderr) => {
+            if (error) {
+                reject(new CliError("git_failed", `Git command failed: git ${args.join(" ")} (${stderr.trim() || error.message})`));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+async function ensureLocalGitIdentity(root) {
+    for (const [key, fallback] of [
+        ["user.name", "Recess CLI"],
+        ["user.email", "cli@recess.gg"],
+    ]) {
+        let configured = "";
+        try {
+            configured = (await runGit(root, ["config", "--get", key])).trim();
+        }
+        catch {
+            // A missing inherited value exits 1. Install a repo-local fallback so
+            // the checkout can be committed without changing the user's global Git.
+        }
+        if (!configured)
+            await runGit(root, ["config", key, fallback]);
+    }
+}
+function resolveWorkspaceCheckoutPath(root, workspacePath) {
+    const normalized = workspacePath.replaceAll("\\", "/");
+    const segments = normalized.split("/");
+    const isGitMetadataSegment = (segment) => {
+        // NTFS canonicalizes trailing dots/spaces, supports alternate data streams,
+        // and may expose .git through an 8.3 alias such as GIT~1. Reject those
+        // spellings too so a checkout cannot write Git metadata before `git init`.
+        const ntfsName = segment
+            .split(":", 1)[0]
+            .replace(/[ .]+$/g, "")
+            .toLowerCase();
+        return ntfsName === ".git" || /^git~\d+$/.test(ntfsName);
+    };
+    if (!normalized ||
+        path.posix.isAbsolute(normalized) ||
+        segments.some((segment) => !segment ||
+            segment === "." ||
+            segment === ".." ||
+            isGitMetadataSegment(segment))) {
+        throw new CliError("invalid_workspace", `Refusing unsafe workspace path from Mesa: ${workspacePath}`);
+    }
+    const target = path.resolve(root, ...segments);
+    if (!target.startsWith(`${root}${path.sep}`)) {
+        throw new CliError("invalid_workspace", `Refusing workspace path outside checkout: ${workspacePath}`);
+    }
+    return target;
+}
+function recessGitMetadataPath(root) {
+    return path.join(root, ".git", RECESS_GIT_METADATA);
+}
+async function writeRecessGitMetadata(root, metadata) {
+    const destination = recessGitMetadataPath(root);
+    const temporary = `${destination}.${process.pid}.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(metadata, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    await fs.rename(temporary, destination);
+}
+async function readRecessGitMetadata(sourceDirectory) {
+    const requestedRoot = path.resolve(sourceDirectory);
+    const requestedRealRoot = await fs.realpath(requestedRoot).catch(() => null);
+    if (!requestedRealRoot) {
+        throw new CliError("invalid_checkout", `Recess checkout does not exist: ${requestedRoot}`);
+    }
+    const root = (await runGit(requestedRoot, ["rev-parse", "--show-toplevel"])).trim();
+    const realRoot = await fs.realpath(root);
+    if (realRoot !== requestedRealRoot) {
+        throw new CliError("invalid_checkout", `--source-dir must be the Recess checkout root: ${root}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await fs.readFile(recessGitMetadataPath(root), "utf8"));
+    }
+    catch {
+        throw new CliError("invalid_checkout", `${root} is not a Recess goal workspace checkout.`);
+    }
+    const value = parsed;
+    const candidateTarget = value.target;
+    const target = value.schemaVersion === 1 && typeof value.goalId === "string"
+        ? { kind: "goal", goalId: value.goalId }
+        : candidateTarget;
+    if (![1, 2].includes(typeof value.schemaVersion === "number" ? value.schemaVersion : 0) ||
+        typeof value.studentId !== "string" ||
+        !target ||
+        (target.kind !== "goal" && target.kind !== "draft") ||
+        (target.kind === "goal" && typeof target.goalId !== "string") ||
+        (target.kind === "draft" && typeof target.draftSlug !== "string") ||
+        typeof value.changeId !== "string" ||
+        typeof value.upstreamCommit !== "string") {
+        throw new CliError("invalid_checkout", `${root} has invalid Recess workspace metadata.`);
+    }
+    return {
+        root: realRoot,
+        metadata: {
+            schemaVersion: 2,
+            studentId: value.studentId,
+            target: target,
+            changeId: value.changeId,
+            upstreamCommit: value.upstreamCommit,
+        },
+    };
+}
+async function checkoutGoalWorkspace(input) {
+    const outputDirectory = path.resolve(input.outputDirectory);
+    if (await fs.lstat(outputDirectory).catch(() => null)) {
+        throw new CliError("destination_exists", `Checkout destination already exists: ${outputDirectory}`);
+    }
+    if (input.snapshot.files.length > GOAL_WORKSPACE_WRITE_MAX_FILES) {
+        throw new CliError("workspace_too_large", `Workspace has more than ${GOAL_WORKSPACE_WRITE_MAX_FILES} files.`);
+    }
+    const sizeBytes = input.snapshot.files.reduce((total, file) => total + file.sizeBytes, 0);
+    if (sizeBytes > GOAL_WORKSPACE_WRITE_MAX_TOTAL_BYTES) {
+        throw new CliError("workspace_too_large", `Workspace exceeds ${GOAL_WORKSPACE_WRITE_MAX_TOTAL_BYTES} decoded bytes.`);
+    }
+    const parent = path.dirname(outputDirectory);
+    await fs.mkdir(parent, { recursive: true });
+    const temporary = await fs.mkdtemp(path.join(parent, ".recess-checkout-"));
+    let moved = false;
+    try {
+        for (const file of input.snapshot.files) {
+            const destination = resolveWorkspaceCheckoutPath(temporary, file.path);
+            const bytes = Buffer.from(file.content, file.contentEncoding === "base64" ? "base64" : "utf8");
+            const sha256 = createHash("sha256").update(bytes).digest("hex");
+            if (bytes.byteLength !== file.sizeBytes || sha256 !== file.sha256) {
+                throw new CliError("invalid_workspace", `Mesa snapshot integrity check failed for ${file.path}.`);
+            }
+            await fs.mkdir(path.dirname(destination), { recursive: true });
+            await fs.writeFile(destination, bytes);
+        }
+        await runGit(temporary, ["init", "--quiet", "--initial-branch=main"]);
+        await ensureLocalGitIdentity(temporary);
+        await runGit(temporary, ["add", "-A"]);
+        await runGit(temporary, [
+            "commit",
+            "--quiet",
+            "--allow-empty",
+            "-m",
+            `Checkout Recess ${input.target.kind} workspace at ${input.snapshot.changeId}`,
+        ], { identity: true });
+        const upstreamCommit = (await runGit(temporary, ["rev-parse", "HEAD"])).trim();
+        await writeRecessGitMetadata(temporary, {
+            schemaVersion: 2,
+            studentId: input.studentId,
+            target: input.target,
+            changeId: input.snapshot.changeId,
+            upstreamCommit,
+        });
+        await fs.rename(temporary, outputDirectory);
+        moved = true;
+        return {
+            directory: outputDirectory,
+            studentId: input.studentId,
+            target: input.target,
+            changeId: input.snapshot.changeId,
+            upstreamCommit,
+            fileCount: input.snapshot.files.length,
+            sizeBytes,
+            next: `Edit with normal file tools, inspect with git -C ${JSON.stringify(outputDirectory)} diff, commit locally, then run recess --json goals files push --source-dir ${JSON.stringify(outputDirectory)} --reason <purpose>.`,
+        };
+    }
+    finally {
+        if (!moved)
+            await fs.rm(temporary, { recursive: true, force: true });
+    }
+}
+async function readRemoteWorkspaceSnapshot(api, studentId, target) {
+    return unwrap(await api.client.GET("/tutor/browser/mesa/workspace-files", {
+        params: {
+            query: {
+                studentUserId: studentId,
+                ...(target.kind === "goal"
+                    ? { goalId: target.goalId }
+                    : { draftSlug: target.draftSlug }),
+            },
+        },
+    }));
+}
+async function assertCheckoutReadyForMaterialization(checkout) {
+    const status = await runGit(checkout.root, ["status", "--porcelain=v1"]);
+    if (status.trim()) {
+        throw new CliError("uncommitted_changes", "Commit or discard all local workspace changes before creating or capturing.");
+    }
+    const head = (await runGit(checkout.root, ["rev-parse", "HEAD"])).trim();
+    if (head !== checkout.metadata.upstreamCommit) {
+        throw new CliError("unpushed_changes", "Push every local workspace commit before creating a goal or capturing a template.");
+    }
+    return head;
+}
+async function readGoalWorkspaceGitChanges(root, base) {
+    const status = await runGit(root, ["status", "--porcelain=v1"]);
+    if (status.trim()) {
+        throw new CliError("uncommitted_changes", "Commit or discard all local workspace changes before pushing.");
+    }
+    const head = (await runGit(root, ["rev-parse", "HEAD"])).trim();
+    if (head === base) {
+        throw new CliError("no_changes", "There are no local commits to push.");
+    }
+    await runGit(root, ["merge-base", "--is-ancestor", base, head]);
+    const commitLines = (await runGit(root, [
+        "log",
+        "--reverse",
+        "--format=%H%x09%s",
+        `${base}..${head}`,
+    ]))
+        .trim()
+        .split("\n")
+        .filter(Boolean);
+    const commits = commitLines.map((line) => {
+        const tab = line.indexOf("\t");
+        return { id: line.slice(0, tab), subject: line.slice(tab + 1) };
+    });
+    const raw = await runGit(root, [
+        "diff",
+        "--name-status",
+        "--no-renames",
+        "-z",
+        `${base}..${head}`,
+    ]);
+    const fields = raw.split("\0").filter((field) => field.length > 0);
+    if (fields.length % 2 !== 0) {
+        throw new CliError("git_failed", "Git returned an invalid workspace diff.");
+    }
+    const changes = [];
+    let sizeBytes = 0;
+    for (let index = 0; index < fields.length; index += 2) {
+        const statusCode = fields[index][0];
+        const workspacePath = fields[index + 1];
+        resolveWorkspaceCheckoutPath(root, workspacePath);
+        if (statusCode === "D") {
+            changes.push({ path: workspacePath, action: "delete" });
+            continue;
+        }
+        if (!["A", "M", "T"].includes(statusCode)) {
+            throw new CliError("unsupported_git_change", `Unsupported Git change ${fields[index]} for ${workspacePath}.`);
+        }
+        const absolutePath = resolveWorkspaceCheckoutPath(root, workspacePath);
+        const stat = await fs.lstat(absolutePath).catch(() => null);
+        if (!stat?.isFile() || stat.isSymbolicLink()) {
+            throw new CliError("invalid_workspace", `Refusing non-file workspace entry: ${workspacePath}`);
+        }
+        const bytes = await fs.readFile(absolutePath);
+        sizeBytes += bytes.byteLength;
+        changes.push({
+            path: workspacePath,
+            action: "upsert",
+            content: bytes.toString("base64"),
+            contentEncoding: "base64",
+            sizeBytes: bytes.byteLength,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+        });
+    }
+    if (changes.length === 0) {
+        throw new CliError("no_changes", "Local commits do not change workspace file contents.");
+    }
+    if (changes.length > GOAL_WORKSPACE_WRITE_MAX_FILES) {
+        throw new CliError("workspace_too_large", `Push changes more than ${GOAL_WORKSPACE_WRITE_MAX_FILES} files.`);
+    }
+    if (sizeBytes > GOAL_WORKSPACE_WRITE_MAX_TOTAL_BYTES) {
+        throw new CliError("workspace_too_large", `Push exceeds ${GOAL_WORKSPACE_WRITE_MAX_TOTAL_BYTES} decoded bytes.`);
+    }
+    return { head, commits, changes, sizeBytes };
+}
 function approvalTokenFor(preview) {
     return createHash("sha256").update(JSON.stringify(preview)).digest("hex");
 }
-function requirePreviewBoundConfirmation(parsed, preview) {
+function operationKeyFor(fingerprint) {
+    return `op_${randomUUID().replaceAll("-", "")}_${fingerprint}`;
+}
+function assertOperationKeyMatchesPreview(operationKey, fingerprint, preview) {
+    if (!operationKey.endsWith(`_${fingerprint}`)) {
+        throw new CliError("approval_mismatch", "The operation key does not belong to this preview. Start from a new preview and obtain approval again.", 2, { preview, requiredFlag: "--operation-key" });
+    }
+}
+async function requirePreviewBoundConfirmation(parsed, preview) {
     const approvalToken = approvalTokenFor(preview);
+    const suppliedOperationKey = flagString(parsed, "operation-key");
     const boundPreview = {
         ...preview,
-        details: { ...preview.details, approvalToken },
+        details: {
+            ...preview.details,
+            approvalToken,
+            operationKey: suppliedOperationKey ?? operationKeyFor(approvalToken),
+        },
     };
     if (!hasFlag(parsed, "confirm")) {
+        await appendJobEvent({
+            jobId: String(boundPreview.details.operationKey),
+            status: "awaiting_confirmation",
+            timestamp: new Date().toISOString(),
+            action: preview.action,
+            fingerprint: approvalToken,
+            target: preview.target,
+        });
         requireConfirmation(false, boundPreview);
     }
     const supplied = flagString(parsed, "approval-token");
     if (supplied !== approvalToken) {
         throw new CliError("approval_mismatch", "The approved preview no longer matches this request. Review the current preview and rerun with --confirm --approval-token <token>.", 2, { preview: boundPreview, requiredFlag: "--approval-token" });
     }
+    if (!suppliedOperationKey) {
+        throw new CliError("confirmation_required", "A confirmed write requires the operation key from its approved preview.", 2, { preview: boundPreview, requiredFlag: "--operation-key" });
+    }
+    assertOperationKeyMatchesPreview(suppliedOperationKey, approvalToken, boundPreview);
+    await appendJobEvent({
+        jobId: suppliedOperationKey,
+        status: "running",
+        timestamp: new Date().toISOString(),
+        action: preview.action,
+        fingerprint: approvalToken,
+        target: preview.target,
+    });
+    return { operationKey: suppliedOperationKey, fingerprint: approvalToken };
+}
+async function previewBoundWrite(parsed, preview, execute) {
+    const context = await requirePreviewBoundConfirmation(parsed, preview);
+    try {
+        const result = await withIdempotencyContext(context, execute);
+        await appendJobEvent({
+            jobId: context.operationKey,
+            status: "completed",
+            timestamp: new Date().toISOString(),
+            action: preview.action,
+            fingerprint: context.fingerprint,
+            target: preview.target,
+            result,
+        });
+        return result;
+    }
+    catch (error) {
+        await appendJobEvent({
+            jobId: context.operationKey,
+            status: "unknown",
+            timestamp: new Date().toISOString(),
+            action: preview.action,
+            fingerprint: context.fingerprint,
+            target: preview.target,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
 }
 async function cleanupPlannerUpload(api, conversationId, signed, includeDelete) {
     if (signed.kind === "multipart") {
@@ -1025,7 +1471,7 @@ function optionalDocString(doc, key) {
     return value;
 }
 /**
- * Coerce an authored template file into the exact `POST /admin/goal-templates/`
+ * Coerce an authored template file into the exact `POST /ai/goal-templates/`
  * body. Every unknown key is dropped rather than forwarded, so a stale field
  * copied from an old export cannot ride along into a create, and the shape
  * failures an agent actually makes (missing slug, spec as a string, tags as a
@@ -1253,6 +1699,48 @@ function flagDateOnly(parsed, name) {
     return raw;
 }
 const DAY_MS = 24 * 60 * 60 * 1000;
+async function waitForContentLibraryLive(api, gems, timeoutSeconds) {
+    const pending = new Set(gems);
+    const latest = new Map();
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    let delayMs = 2_000;
+    while (pending.size > 0) {
+        const targets = Array.from(pending);
+        for (let index = 0; index < targets.length; index += 3) {
+            const batch = targets.slice(index, index + 3);
+            await Promise.all(batch.map(async (gem) => {
+                const status = unwrap(await api.client.GET("/admin/content-library/status", {
+                    params: { query: { gem } },
+                }));
+                latest.set(gem, status);
+                if (status.stage === "live") {
+                    pending.delete(gem);
+                    return;
+                }
+                const errors = [
+                    status.progress.metadata,
+                    status.progress.cover,
+                    status.progress.searchIndex,
+                ].filter((step) => step.state === "error");
+                if (errors.length > 0) {
+                    throw new CliError("async_job_failed", `Content Library polishing failed for ${gem}.`, 1, { status });
+                }
+            }));
+        }
+        if (pending.size === 0)
+            break;
+        if (Date.now() + delayMs >= deadline) {
+            throw new CliError("async_timeout", `Timed out waiting for ${pending.size} Content Library resource(s) to become live. Retry the unchanged confirmed command with the same operation key to resume polling.`, 1, {
+                pending: Array.from(pending),
+                latest: Object.fromEntries(latest),
+            });
+        }
+        const jitter = Math.floor(Math.random() * Math.max(1, delayMs / 4));
+        await new Promise((resolve) => setTimeout(resolve, delayMs + jitter));
+        delayMs = Math.min(15_000, Math.round(delayMs * 1.7));
+    }
+    return { completed: true, resources: Array.from(latest.values()) };
+}
 // The cohort event routes take zoneless local wall-clock datetimes
 // (interpreted in the cohort's timezone server-side).
 function flagLocalDateTime(parsed, name, options = {}) {
@@ -1325,20 +1813,148 @@ function tierSlots(parsed) {
 export async function runCommand(argv) {
     const parsed = parseArgs(argv);
     const [noun, verb] = parsed.positionals;
+    const commands = buildCommandSchema(HELP);
     // Before the help branch: `--version` parses as a FLAG, so `noun` is
     // undefined and `!noun` would return help instead. (Found by running it.)
     if (noun === "version" || hasFlag(parsed, "version")) {
+        const unknown = Array.from(parsed.flags.keys()).filter((name) => !["deliver", "json", "version"].includes(name));
+        if (unknown.length > 0) {
+            throw new CliError("unknown_flag", `Unknown flag${unknown.length === 1 ? "" : "s"}: ${unknown
+                .map((name) => `--${name}`)
+                .join(", ")}.`, 1, { validFlags: ["--deliver", "--json", "--version"] });
+        }
         return {
             cliVersion: await readCliVersion(),
             skillVersion: await readBundledSkillVersion(),
         };
     }
-    if (!noun || noun === "help" || hasFlag(parsed, "help")) {
-        return { help: HELP };
+    if (!noun) {
+        const unknown = Array.from(parsed.flags.keys()).filter((name) => !["deliver", "help", "json", "profile"].includes(name));
+        if (unknown.length > 0) {
+            throw new CliError("unknown_flag", `Unknown flag${unknown.length === 1 ? "" : "s"}: ${unknown
+                .map((name) => `--${name}`)
+                .join(", ")}.`, 1, { validFlags: ["--deliver", "--help", "--json", "--profile"] });
+        }
+        return { help: scopedHelp(HELP, commands, []) };
+    }
+    if (noun === "help" || hasFlag(parsed, "help")) {
+        const scope = noun === "help" ? parsed.positionals.slice(1) : parsed.positionals;
+        return { help: scopedHelp(HELP, commands, scope) };
+    }
+    validateInvocation(parsed, commands);
+    if (noun === "agent-context") {
+        const profiles = await listProfiles();
+        return agentContext(commands, {
+            cliVersion: await readCliVersion(),
+            availableProfiles: profiles.profiles.map((profile) => profile.name),
+            feedbackUpstreamConfigured: Boolean(process.env.RECESS_CLI_FEEDBACK_ENDPOINT),
+        });
+    }
+    if (noun === "profile") {
+        const name = parsed.positionals[2];
+        if (verb === "list")
+            return listProfiles();
+        if (verb === "show") {
+            if (!name)
+                throw new CliError("invalid_arguments", "Missing profile name.");
+            const profiles = await listProfiles();
+            const profile = profiles.profiles.find((entry) => entry.name === name);
+            if (!profile)
+                throw new CliError("not_found", `Unknown profile ${name}.`);
+            return { ...profile, active: profiles.activeProfile === name };
+        }
+        if (verb === "save") {
+            if (!name)
+                throw new CliError("invalid_arguments", "Missing profile name.");
+            const current = await resolveConfig(flagString(parsed, "profile"));
+            const apiOrigin = flagString(parsed, "api-origin") ?? current.apiOrigin;
+            const webOrigin = flagString(parsed, "web-origin") ?? current.webOrigin;
+            const oauthClientId = flagString(parsed, "oauth-client-id") ?? current.oauthClientId;
+            for (const [label, value] of [
+                ["--api-origin", apiOrigin],
+                ["--web-origin", webOrigin],
+            ]) {
+                try {
+                    new URL(value);
+                }
+                catch {
+                    throw new CliError("invalid_arguments", `${label} must be a URL.`);
+                }
+            }
+            await saveProfile(name, { apiOrigin, webOrigin, oauthClientId });
+            return { saved: name, apiOrigin, webOrigin, oauthClientId };
+        }
+        if (verb === "use") {
+            if (!name)
+                throw new CliError("invalid_arguments", "Missing profile name.");
+            await useProfile(name);
+            return { activeProfile: name };
+        }
+        if (verb === "delete") {
+            if (!name)
+                throw new CliError("invalid_arguments", "Missing profile name.");
+            await deleteProfile(name);
+            return { deleted: name };
+        }
     }
-    const config = await resolveConfig();
+    if (noun === "jobs") {
+        if (verb === "list") {
+            const limit = flagNumber(parsed, "limit") ?? 20;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+                throw new CliError("invalid_arguments", "--limit must be an integer from 1 through 100.");
+            }
+            return listJobs(limit);
+        }
+        if (verb === "get") {
+            const jobId = positional(parsed, 2, "operation key");
+            const result = await getJob(jobId);
+            if (!result.job)
+                throw new CliError("not_found", `Unknown job ${jobId}.`);
+            return result;
+        }
+        if (verb === "prune") {
+            const olderThanDays = flagNumber(parsed, "older-than-days") ?? 30;
+            if (!Number.isInteger(olderThanDays) ||
+                olderThanDays < 1 ||
+                olderThanDays > 3650) {
+                throw new CliError("invalid_arguments", "--older-than-days must be an integer from 1 through 3650.");
+            }
+            return pruneJobs(olderThanDays);
+        }
+    }
+    if (noun === "feedback") {
+        if (verb === "list") {
+            const limit = flagNumber(parsed, "limit") ?? 20;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+                throw new CliError("invalid_arguments", "--limit must be an integer from 1 through 100.");
+            }
+            return listFeedback(limit);
+        }
+        if (verb === "submit") {
+            const feedbackText = parsed.positionals.slice(2).join(" ").trim();
+            if (!feedbackText) {
+                throw new CliError("invalid_arguments", "Feedback text must not be empty.");
+            }
+            if (feedbackText.length > 4_000) {
+                throw new CliError("invalid_arguments", "Feedback text must be 4,000 characters or fewer.");
+            }
+            return writeCommand(parsed, {
+                action: "record Recess CLI feedback locally and send it upstream when configured",
+                target: {
+                    upstreamConfigured: Boolean(process.env.RECESS_CLI_FEEDBACK_ENDPOINT),
+                },
+                request: { text: feedbackText },
+            }, () => submitFeedback({
+                id: flagString(parsed, "operation-key", { required: true }),
+                text: feedbackText,
+                createdAt: new Date().toISOString(),
+            }));
+        }
+    }
+    const config = await resolveConfig(flagString(parsed, "profile"));
+    const requestReason = noun === "auth" ? undefined : requiredRequestReason(parsed);
     if (noun === "doctor")
-        return doctor(config);
+        return doctor(config, requestReason);
     if (noun === "setup") {
         // Always lay down the bundled copy first: it is the floor, and it is the
         // only copy guaranteed to match this binary. The served upgrade below is
@@ -1348,6 +1964,7 @@ export async function runCommand(argv) {
             apiOrigin: config.apiOrigin,
             sessionCookie: config.sessionCookie,
             cliVersion: await readCliVersion(),
+            reason: requestReason,
         });
         const ephemeral = isEphemeralInstall();
         // Reuse a session that is still live; a missing or already-expired one is
@@ -1400,12 +2017,12 @@ export async function runCommand(argv) {
         if (verb === "status")
             return sessionStatus(config);
         if (verb === "logout") {
-            await clearStoredSession();
+            await clearStoredSession(config.profileName);
             return { loggedOut: true };
         }
         throw new CliError("invalid_arguments", "Use auth login, request, poll, status, or logout.");
     }
-    const api = new RecessAdminApi(config);
+    const api = new RecessAdminApi(config, requestReason);
     api.requireAuth();
     if (noun === "village") {
         const targetWorldId = flagString(parsed, "world") ?? "village-1";
@@ -2001,52 +2618,47 @@ export async function runCommand(argv) {
                 ? { firstChargeAt: new Date(firstChargeAt).toISOString() }
                 : {}),
         };
-        // Unlike other writes, the offline preview here would hide the only facts
-        // that matter — the amount charged, whether anything is charged at all, and
-        // whether the kid is over capacity or out of school slots. Ask the backend
-        // for its own dry run (read-only, writes nothing) and put that in front of
-        // the human before the confirmation gate.
-        if (!hasFlag(parsed, "confirm")) {
-            const preview = unwrap(await api.client.POST("/admin/cohorts/enroll/", {
-                body: { ...body, dryRun: true },
-            }));
-            const b = preview.plan.billing;
-            const usd = (cents) => `${(cents / 100).toFixed(2)} USD`;
-            const recurrence = b.isRecurring ? `, recurring per ${b.interval}` : "";
-            // effectivePriceCents already has the course discount applied; credits are
-            // deducted later as an invoice line, so this is an upper bound.
-            const amount = b.discountKind || b.creditBalanceCents > 0
-                ? `${usd(b.effectivePriceCents)} (list ${usd(b.listPriceCents)}${b.discountKind ? `, ${b.discountKind} discount applied` : ""}${b.creditBalanceCents > 0 ? `; up to ${usd(b.creditBalanceCents)} of Recess credits may reduce this further` : ""})`
-                : usd(b.effectivePriceCents);
-            requireConfirmation(false, {
-                action: preview.plan.reusedEnrollmentId
-                    ? "enroll kid into cohort by reusing an existing enrollment (no charge)"
-                    : b.chargesImmediately
-                        ? `enroll kid into cohort and CHARGE ${amount} NOW${recurrence}`
-                        : `enroll kid into cohort with first charge of ${amount} on ${b.firstChargeAt}${recurrence}`,
-                target: {
-                    kid: `${preview.plan.kid.firstName ?? ""} ${preview.plan.kid.lastName ?? ""}`.trim(),
-                    userId,
-                    cohort: preview.plan.cohort.name,
-                    cohortId,
-                    course: preview.plan.cohort.courseName,
-                },
-                request: { ...body, dryRun: false },
-                details: {
-                    billing: b,
-                    reusedEnrollmentId: preview.plan.reusedEnrollmentId,
-                    warnings: preview.warnings,
-                    ...(preview.warnings.length > 0 && !body.force
-                        ? {
-                            blocked: "These warnings will reject the write unless you also pass --force.",
-                        }
-                        : {}),
-                },
-            });
-        }
-        return unwrap(await api.client.POST("/admin/cohorts/enroll/", {
-            body: { ...body, dryRun: false },
+        // The backend owns the price/capacity plan. Recompute it on every run and
+        // bind the confirmation token to that exact plan before the mutation.
+        const preflight = unwrap(await api.client.POST("/admin/cohorts/enroll/", {
+            body: { ...body, dryRun: true },
         }));
+        const billing = preflight.plan.billing;
+        const usd = (cents) => `${(cents / 100).toFixed(2)} USD`;
+        const recurrence = billing.isRecurring
+            ? `, recurring per ${billing.interval}`
+            : "";
+        const amount = billing.discountKind || billing.creditBalanceCents > 0
+            ? `${usd(billing.effectivePriceCents)} (list ${usd(billing.listPriceCents)}${billing.discountKind ? `, ${billing.discountKind} discount applied` : ""}${billing.creditBalanceCents > 0 ? `; up to ${usd(billing.creditBalanceCents)} of Recess credits may reduce this further` : ""})`
+            : usd(billing.effectivePriceCents);
+        const preview = {
+            action: preflight.plan.reusedEnrollmentId
+                ? "enroll kid into cohort by reusing an existing enrollment (no charge)"
+                : billing.chargesImmediately
+                    ? `enroll kid into cohort and CHARGE ${amount} NOW${recurrence}`
+                    : `enroll kid into cohort with first charge of ${amount} on ${billing.firstChargeAt}${recurrence}`,
+            target: {
+                kid: `${preflight.plan.kid.firstName ?? ""} ${preflight.plan.kid.lastName ?? ""}`.trim(),
+                userId,
+                cohort: preflight.plan.cohort.name,
+                cohortId,
+                course: preflight.plan.cohort.courseName,
+            },
+            request: { ...body, dryRun: false },
+            details: {
+                billing,
+                reusedEnrollmentId: preflight.plan.reusedEnrollmentId,
+                warnings: preflight.warnings,
+                ...(preflight.warnings.length > 0 && !body.force
+                    ? {
+                        blocked: "These warnings will reject the write unless you also pass --force.",
+                    }
+                    : {}),
+            },
+        };
+        return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/admin/cohorts/enroll/", {
+            body: { ...body, dryRun: false },
+        })));
     }
     if (noun === "enrollments" && verb === "register-cohort") {
         const enrollmentId = flagString(parsed, "enrollment", { required: true });
@@ -2141,12 +2753,20 @@ export async function runCommand(argv) {
             const search = flagString(parsed, "search");
             const userId = flagString(parsed, "user");
             const id = flagString(parsed, "id");
+            const limit = flagNumber(parsed, "limit") ?? 20;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+                throw new CliError("invalid_arguments", "--limit must be an integer between 1 and 100.");
+            }
             return unwrap(await api.client.GET("/admin/payout/recipient/", {
                 params: {
                     query: {
                         ...(search ? { search } : {}),
                         ...(userId ? { userId } : {}),
                         ...(id ? { id } : {}),
+                        limit,
+                        ...(flagString(parsed, "cursor")
+                            ? { cursor: flagString(parsed, "cursor") }
+                            : {}),
                     },
                 },
             }));
@@ -2767,6 +3387,19 @@ export async function runCommand(argv) {
         if (verb === "set-stage") {
             const stage = assertChoice(flagString(parsed, "stage", { required: true }), CONTENT_LIBRARY_RESOURCE_STAGES, "--stage");
             const input = await readContentLibraryGemTargets(parsed);
+            const wait = hasFlag(parsed, "wait");
+            const timeoutSeconds = flagNumber(parsed, "timeout") ?? 900;
+            if (hasFlag(parsed, "timeout") && !wait) {
+                throw new CliError("invalid_arguments", "--timeout requires --wait.");
+            }
+            if (wait && stage !== "live") {
+                throw new CliError("invalid_arguments", "--wait is supported for content-library set-stage only when --stage live.");
+            }
+            if (!Number.isInteger(timeoutSeconds) ||
+                timeoutSeconds < 10 ||
+                timeoutSeconds > 7200) {
+                throw new CliError("invalid_arguments", "--timeout must be an integer number of seconds from 10 through 7200.");
+            }
             const preflightBody = {
                 gems: input.gems,
                 stage,
@@ -2783,16 +3416,39 @@ export async function runCommand(argv) {
                     resources: preflight.results,
                     lifecycle: "Uses the same lifecycle as Manage. Direct-to-Live never bypasses unfinished polishing; leaving Polishing cancels its bound run before moving.",
                     concurrency: 3,
+                    waitForLive: wait,
+                    ...(wait ? { timeoutSeconds } : {}),
                     ...(input.file ? { inputFile: input.file } : {}),
                 },
             };
-            return writeCommand(parsed, preview, async () => unwrap(await api.client.POST("/admin/content-library/transition", {
-                body: { gems: input.gems, stage, dryRun: false },
-            })));
+            return writeCommand(parsed, preview, async () => {
+                const result = unwrap(await api.client.POST("/admin/content-library/transition", {
+                    body: { gems: input.gems, stage, dryRun: false },
+                }));
+                if (!wait)
+                    return result;
+                return {
+                    ...result,
+                    wait: await waitForContentLibraryLive(api, input.gems, timeoutSeconds),
+                };
+            });
         }
         if (verb === "submit") {
             const stage = assertChoice(flagString(parsed, "stage") ?? "review", CONTENT_LIBRARY_STAGES, "--stage");
             const input = await readContentLibrarySubmitItems(parsed);
+            const wait = hasFlag(parsed, "wait");
+            const timeoutSeconds = flagNumber(parsed, "timeout") ?? 900;
+            if (hasFlag(parsed, "timeout") && !wait) {
+                throw new CliError("invalid_arguments", "--timeout requires --wait.");
+            }
+            if (wait && stage !== "polish") {
+                throw new CliError("invalid_arguments", "--wait is supported for content-library submit only when --stage polish.");
+            }
+            if (!Number.isInteger(timeoutSeconds) ||
+                timeoutSeconds < 10 ||
+                timeoutSeconds > 7200) {
+                throw new CliError("invalid_arguments", "--timeout must be an integer number of seconds from 10 through 7200.");
+            }
             const body = { stage, items: input.items };
             const preview = {
                 action: "content-library.submit",
@@ -2804,51 +3460,57 @@ export async function runCommand(argv) {
                         : "Holds each new resource in REVIEW until an admin approves it.",
                     duplicateBehavior: "Existing URLs are returned as duplicates and are not overwritten.",
                     deployOrderFence: "The server verifies the island's review/polish lifecycle capability before its first write.",
+                    waitForLive: wait,
+                    ...(wait ? { timeoutSeconds } : {}),
                     ...(input.file ? { inputFile: input.file } : {}),
                 },
             };
-            return writeCommand(parsed, preview, async () => unwrap(await api.client.POST("/admin/content-library/submit", {
-                body,
-            })));
+            return writeCommand(parsed, preview, async () => {
+                const result = unwrap(await api.client.POST("/admin/content-library/submit", {
+                    body,
+                }));
+                if (!wait)
+                    return result;
+                return {
+                    ...result,
+                    wait: await waitForContentLibraryLive(api, input.items.map((item) => item.url), timeoutSeconds),
+                };
+            });
         }
         throw new CliError("invalid_arguments", "Use content-library search, status, set-stage, or submit.");
     }
     if (noun === "goal-templates") {
         if (verb === "list") {
-            const query = flagString(parsed, "query")?.toLowerCase();
+            const query = flagString(parsed, "query");
             const kind = flagString(parsed, "kind");
-            const data = unwrap(await api.client.GET("/ai/goal-templates/", {
+            const wantedKind = kind
+                ? assertChoice(kind, GOAL_TEMPLATE_KINDS, "--kind")
+                : undefined;
+            const limit = flagNumber(parsed, "limit") ?? 20;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+                throw new CliError("invalid_arguments", "--limit must be an integer between 1 and 100.");
+            }
+            return unwrap(await api.client.GET("/ai/goal-templates/", {
                 params: {
                     query: {
                         ...(flagString(parsed, "category")
                             ? { category: flagString(parsed, "category") }
                             : {}),
+                        ...(query ? { query } : {}),
+                        ...(wantedKind ? { kind: wantedKind } : {}),
                         includeDeleted: hasFlag(parsed, "include-deleted")
                             ? "true"
                             : "false",
                         starterOnly: hasFlag(parsed, "starter-only")
                             ? "true"
                             : "false",
+                        limit,
+                        ...(flagString(parsed, "cursor")
+                            ? { cursor: flagString(parsed, "cursor") }
+                            : {}),
                     },
                 },
             }));
-            // The route filters by category/starter/deleted only; `--query` and
-            // `--kind` narrow the returned page here rather than pretending the
-            // backend supports them.
-            const wantedKind = kind
-                ? assertChoice(kind, GOAL_TEMPLATE_KINDS, "--kind")
-                : undefined;
-            const items = data.items.filter((item) => {
-                if (wantedKind && item.kind !== wantedKind)
-                    return false;
-                if (!query)
-                    return true;
-                return [item.title, item.slug, item.description, item.category ?? ""]
-                    .join("\n")
-                    .toLowerCase()
-                    .includes(query);
-            });
-            return { items, totalBeforeFilter: data.items.length };
         }
         if (verb === "get") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
@@ -2953,7 +3615,7 @@ export async function runCommand(argv) {
             // protected-inventory counting, and the token binding the approved loss
             // to this exact version + result hash. Always ask it for a fresh preview,
             // including on a confirmed run, before permitting the write request.
-            const preflight = unwrap(await api.client.POST("/admin/goal-templates/{id}/setup-workflow-spec/patch", {
+            const preflight = unwrap(await api.client.POST("/ai/goal-templates/{id}/setup-workflow-spec/patch", {
                 params: { path: { id } },
                 body: {
                     expectedVersion,
@@ -2991,7 +3653,9 @@ export async function runCommand(argv) {
                         : {}),
                 },
             };
-            requireConfirmation(hasFlag(parsed, "confirm"), preview);
+            if (!hasFlag(parsed, "confirm")) {
+                await requirePreviewBoundConfirmation(parsed, preview);
+            }
             const destructiveChangeToken = flagString(parsed, "destructive-change-token");
             if (preflight.preview.destructiveChanges &&
                 (!hasFlag(parsed, "confirm-destructive-changes") ||
@@ -3007,7 +3671,7 @@ export async function runCommand(argv) {
                     expectedDestructiveChangeToken: preflight.preview.destructiveChangeToken,
                 });
             }
-            return unwrap(await api.client.POST("/admin/goal-templates/{id}/setup-workflow-spec/patch", {
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/setup-workflow-spec/patch", {
                 params: { path: { id } },
                 body: {
                     expectedVersion,
@@ -3016,7 +3680,7 @@ export async function runCommand(argv) {
                     confirmDestructiveChanges: preflight.preview.destructiveChanges,
                     ...(destructiveChangeToken ? { destructiveChangeToken } : {}),
                 },
-            }));
+            })));
         }
         if (verb === "set-metadata") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
@@ -3085,7 +3749,7 @@ export async function runCommand(argv) {
                 action: "update goal template metadata (never its setupWorkflowSpec)",
                 target: { templateId: id, expectedVersion },
                 request: body,
-            }, async () => unwrap(await api.client.PUT("/admin/goal-templates/{id}", {
+            }, async () => unwrap(await api.client.PUT("/ai/goal-templates/{id}", {
                 params: { path: { id } },
                 body,
             })));
@@ -3096,7 +3760,7 @@ export async function runCommand(argv) {
             // Read the current version so the gate refuses a stale delete locally,
             // and so the preview names the template a human is being asked to approve
             // rather than only its UUID.
-            const current = unwrap(await api.client.GET("/admin/goal-templates/{id}", {
+            const current = unwrap(await api.client.GET("/ai/goal-templates/{id}", {
                 params: { path: { id } },
             }));
             if (current.version !== expectedVersion) {
@@ -3114,7 +3778,7 @@ export async function runCommand(argv) {
                 details: {
                     note: "Soft delete: the row keeps its deletedAt and drops out of every list. Existing goals already applied from it are unaffected.",
                 },
-            }, async () => unwrap(await api.client.DELETE("/admin/goal-templates/{id}", {
+            }, async () => unwrap(await api.client.DELETE("/ai/goal-templates/{id}", {
                 params: { path: { id } },
             })));
         }
@@ -3134,18 +3798,43 @@ export async function runCommand(argv) {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
             const sourceGoalId = flagString(parsed, "source-goal");
             const sourceDraft = flagString(parsed, "source-draft");
-            if (Boolean(sourceGoalId) === Boolean(sourceDraft)) {
-                throw new CliError("invalid_arguments", "Pass exactly one of --source-goal or --source-draft.");
+            const sourceDirectory = flagString(parsed, "source-dir");
+            if ([sourceGoalId, sourceDraft, sourceDirectory].filter(Boolean).length !==
+                1) {
+                throw new CliError("invalid_arguments", "Pass exactly one of --source-goal, --source-draft, or --source-dir.");
+            }
+            const checkout = sourceDirectory
+                ? await readRecessGitMetadata(sourceDirectory)
+                : null;
+            const checkoutHead = checkout
+                ? await assertCheckoutReadyForMaterialization(checkout)
+                : null;
+            const requestedSourceStudentId = flagString(parsed, "student");
+            if (checkout &&
+                requestedSourceStudentId &&
+                requestedSourceStudentId !== checkout.metadata.studentId) {
+                throw new CliError("invalid_arguments", `--student ${requestedSourceStudentId} does not match checkout owner ${checkout.metadata.studentId}.`);
             }
             const sourceStudentUserId = sourceDraft
                 ? flagString(parsed, "student", { required: true })
-                : undefined;
-            const source = sourceGoalId
-                ? { sourceGoalId }
-                : {
-                    sourceWorkspacePath: `drafts/${sourceDraft}/workspace`,
-                    sourceStudentUserId,
+                : checkout?.metadata.studentId;
+            let source;
+            if (sourceGoalId) {
+                source = { sourceGoalId };
+            }
+            else if (checkout?.metadata.target.kind === "goal") {
+                source = { sourceGoalId: checkout.metadata.target.goalId };
+            }
+            else {
+                const draftSlug = sourceDraft ??
+                    (checkout?.metadata.target.kind === "draft"
+                        ? checkout.metadata.target.draftSlug
+                        : undefined);
+                source = {
+                    sourceWorkspacePath: `drafts/${draftSlug}/workspace`,
+                    sourceStudentUserId: sourceStudentUserId,
                 };
+            }
             const preflight = unwrap(await api.client.POST("/ai/goal-templates/{id}/snapshot/capture", {
                 params: { path: { id } },
                 body: { ...source, dryRun: true },
@@ -3153,6 +3842,10 @@ export async function runCommand(argv) {
             if (preflight.action !== "preview_capture_snapshot") {
                 throw new CliError("unexpected_response", "Snapshot capture did not return a preview; nothing was captured.");
             }
+            if (checkout &&
+                preflight.source.changeId !== checkout.metadata.changeId) {
+                throw new CliError("stale_workspace", `Workspace changed from ${checkout.metadata.changeId} to ${preflight.source.changeId}. Check it out again before capturing; nothing was captured.`);
+            }
             if (hasFlag(parsed, "dry-run"))
                 return preflight;
             const preview = {
@@ -3169,6 +3862,13 @@ export async function runCommand(argv) {
                     fileCount: preflight.snapshot.fileCount,
                     sizeBytes: preflight.snapshot.sizeBytes,
                     sha256: preflight.snapshot.sha256,
+                    ...(checkout
+                        ? {
+                            sourceDirectory: checkout.root,
+                            localHeadCommit: checkoutHead,
+                            mesaChangeId: checkout.metadata.changeId,
+                        }
+                        : {}),
                 },
                 details: {
                     modules: preflight.snapshot.modules,
@@ -3177,8 +3877,7 @@ export async function runCommand(argv) {
                     note: "The confirmed request is fenced to both this template version and this exact source revision. Capturing bumps the template version unless the snapshot is unchanged.",
                 },
             };
-            requireConfirmation(hasFlag(parsed, "confirm"), preview);
-            return unwrap(await api.client.POST("/ai/goal-templates/{id}/snapshot/capture", {
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/snapshot/capture", {
                 params: { path: { id } },
                 body: {
                     ...source,
@@ -3186,7 +3885,7 @@ export async function runCommand(argv) {
                     expectedTemplateVersion: preflight.template.version,
                     expectedSourceChangeId: preflight.source.changeId,
                 },
-            }));
+            })));
         }
         if (verb === "apply") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
@@ -3230,15 +3929,14 @@ export async function runCommand(argv) {
                     note: "Counts come from the backend's own dry run. `skipped_existing` items are idempotent — re-applying does not duplicate them.",
                 },
             };
-            requirePreviewBoundConfirmation(parsed, preview);
-            return unwrap(await api.client.POST("/ai/goal-templates/{id}/apply-workflow", {
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/apply-workflow", {
                 params: { path: { id } },
                 body: {
                     answers,
                     dryRun: false,
                     expectedTemplateVersion: preflight.templateVersion,
                 },
-            }));
+            })));
         }
         if (verb === "apply-starter") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
@@ -3272,7 +3970,30 @@ export async function runCommand(argv) {
             }));
         }
         if (verb === "create") {
-            const userId = flagString(parsed, "student", { required: true });
+            const requestedStudentId = flagString(parsed, "student");
+            const sourceDirectory = flagString(parsed, "source-dir");
+            const explicitDraftSlug = flagString(parsed, "draft");
+            if (sourceDirectory && explicitDraftSlug) {
+                throw new CliError("invalid_arguments", "Pass either --source-dir or --draft, not both.");
+            }
+            const checkout = sourceDirectory
+                ? await readRecessGitMetadata(sourceDirectory)
+                : null;
+            if (checkout && checkout.metadata.target.kind !== "draft") {
+                throw new CliError("invalid_checkout", "A fresh module goal must be created from a draft checkout, not an existing goal checkout.");
+            }
+            const checkoutHead = checkout
+                ? await assertCheckoutReadyForMaterialization(checkout)
+                : null;
+            if (checkout &&
+                requestedStudentId &&
+                requestedStudentId !== checkout.metadata.studentId) {
+                throw new CliError("invalid_arguments", `--student ${requestedStudentId} does not match checkout owner ${checkout.metadata.studentId}.`);
+            }
+            const userId = requestedStudentId ?? checkout?.metadata.studentId;
+            if (!userId) {
+                throw new CliError("invalid_arguments", "Pass --student for a direct goal create, or use a Recess draft --source-dir.");
+            }
             const title = flagString(parsed, "title", { required: true });
             const descriptionFile = flagString(parsed, "description-file");
             const descriptionFlag = flagString(parsed, "description");
@@ -3288,14 +4009,17 @@ export async function runCommand(argv) {
                 throw new CliError("invalid_arguments", "--target-date must be an ISO 8601 datetime.");
             }
             const schedule = flagString(parsed, "schedule");
-            const draftSlug = flagString(parsed, "draft");
+            const draftSlug = explicitDraftSlug ??
+                (checkout?.metadata.target.kind === "draft"
+                    ? checkout.metadata.target.draftSlug
+                    : undefined);
             const enablesAppletFollowUps = hasFlag(parsed, "enable-applet-follow-ups");
             const disablesAppletFollowUps = hasFlag(parsed, "disable-applet-follow-ups");
             if (draftSlug && enablesAppletFollowUps === disablesAppletFollowUps) {
                 throw new CliError("invalid_arguments", "A module-backed goal requires exactly one of --enable-applet-follow-ups or --disable-applet-follow-ups.");
             }
             if (!draftSlug && (enablesAppletFollowUps || disablesAppletFollowUps)) {
-                throw new CliError("invalid_arguments", "Applet follow-up flags are used with --draft for direct module-backed goals.");
+                throw new CliError("invalid_arguments", "Applet follow-up flags are used with --draft or --source-dir for module-backed goals.");
             }
             if (draftSlug) {
                 const body = {
@@ -3313,6 +4037,10 @@ export async function runCommand(argv) {
                 if (preflight.action !== "preview_module_goal_create") {
                     throw new CliError("unexpected_response", "Direct module goal creation did not return a preview; no goal was created.");
                 }
+                if (checkout &&
+                    preflight.currentChangeId !== checkout.metadata.changeId) {
+                    throw new CliError("stale_workspace", `Draft changed from ${checkout.metadata.changeId} to ${preflight.currentChangeId}. Check it out again before creating the goal; nothing was created.`);
+                }
                 const preview = {
                     action: "create a module-backed goal directly from a validated draft workspace",
                     target: preflight.target,
@@ -3325,6 +4053,13 @@ export async function runCommand(argv) {
                         targetDate: targetDate ?? null,
                         schedule: schedule ?? null,
                         enableAppletFollowUps: enablesAppletFollowUps,
+                        ...(checkout
+                            ? {
+                                sourceDirectory: checkout.root,
+                                localHeadCommit: checkoutHead,
+                                mesaChangeId: checkout.metadata.changeId,
+                            }
+                            : {}),
                     },
                     details: {
                         currentChangeId: preflight.currentChangeId,
@@ -3338,14 +4073,35 @@ export async function runCommand(argv) {
                         note: "Creates a personal module-backed goal directly. It does not create, capture, or apply a reusable template. After success, Recess removes the draft only when no newer Mesa edit has landed; otherwise it preserves the draft.",
                     },
                 };
-                requirePreviewBoundConfirmation(parsed, preview);
-                return unwrap(await api.client.POST("/tutor/browser/mesa/goals", {
-                    body: {
-                        ...body,
-                        dryRun: false,
-                        expectedWorkspaceChangeId: preflight.currentChangeId,
-                    },
-                }));
+                return previewBoundWrite(parsed, preview, async () => {
+                    const result = unwrap(await api.client.POST("/tutor/browser/mesa/goals", {
+                        body: {
+                            ...body,
+                            dryRun: false,
+                            expectedWorkspaceChangeId: preflight.currentChangeId,
+                        },
+                    }));
+                    if (result.action !== "create_module_goal") {
+                        throw new CliError("unexpected_response", "Module goal creation returned a preview instead of creating the goal.");
+                    }
+                    if (checkout && result.mesaChangeId) {
+                        await writeRecessGitMetadata(checkout.root, {
+                            ...checkout.metadata,
+                            target: { kind: "goal", goalId: result.goalId },
+                            changeId: result.mesaChangeId,
+                            upstreamCommit: checkoutHead,
+                        });
+                        return {
+                            ...result,
+                            local: {
+                                directory: checkout.root,
+                                target: { kind: "goal", goalId: result.goalId },
+                                upstreamCommit: checkoutHead,
+                            },
+                        };
+                    }
+                    return result;
+                });
             }
             const body = {
                 title,
@@ -3363,7 +4119,7 @@ export async function runCommand(argv) {
                     schedule: schedule ?? null,
                 },
                 details: {
-                    note: "Creates a description-only goal with no modules or course workspace. Pass --draft to create a personal module-backed goal directly. A 409 GOAL_LIMIT_REACHED means the kid is at capacity and nothing was created.",
+                    note: "Creates a description-only goal with no modules or course workspace. Pass a draft checkout with --source-dir to create a personal module-backed goal. A 409 GOAL_LIMIT_REACHED means the kid is at capacity and nothing was created.",
                 },
             }, async () => unwrap(await api.client.POST("/tutor/browser/students/{userId}/goals/", {
                 params: { path: { userId } },
@@ -3392,11 +4148,39 @@ export async function runCommand(argv) {
                     patch,
                 },
             };
-            requirePreviewBoundConfirmation(parsed, preview);
-            return unwrap(await api.client.PATCH("/tutor/browser/students/goals/{goalId}/", {
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.PATCH("/tutor/browser/students/goals/{goalId}/", {
                 params: { path: { goalId } },
                 body: patch,
-            }));
+            })));
+        }
+        if (verb === "delete") {
+            const goalId = positional(parsed, 2, "goal ID");
+            const studentId = flagString(parsed, "student", { required: true });
+            const current = unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
+                params: { path: { userId: studentId } },
+            })).goals.find((goal) => goal.id === goalId);
+            if (!current) {
+                throw new CliError("not_found", `Goal ${goalId} was not found for student ${studentId}.`);
+            }
+            const preview = {
+                action: "soft-delete a goal for a managed student",
+                target: {
+                    goalId,
+                    studentUserId: studentId,
+                    title: current.title,
+                    status: current.status,
+                },
+                request: { expectedUpdatedAt: current.updatedAt },
+                details: {
+                    note: "Soft-deletes the goal and its current/future dated todos. Historical todos and the deletion audit remain available.",
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => {
+                unwrap(await api.client.DELETE("/admin/browser/students/goals/{goalId}/", {
+                    params: { path: { goalId } },
+                }));
+                return { deleted: true, goalId, studentUserId: studentId };
+            });
         }
         if (verb === "queue") {
             const subverb = positional(parsed, 2, "queue action (get|set)");
@@ -3411,7 +4195,7 @@ export async function runCommand(argv) {
                 });
                 const delta = flagString(parsed, "delta", { required: true });
                 const replaceDescriptionPointer = hasFlag(parsed, "replace-description-pointer");
-                const { absolutePath, parsed: rawEntries } = await readJsonValue(entriesFile, "Queue entries file");
+                const { absolutePath, raw: rawEntriesText, parsed: rawEntries, } = await readJsonValue(entriesFile, "Queue entries file");
                 const entries = parseGoalQueueEntries(rawEntries, "Queue entries file");
                 const goal = unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
                     params: { path: { userId: studentId } },
@@ -3422,15 +4206,36 @@ export async function runCommand(argv) {
                 const current = unwrap(await api.client.GET("/tutor/browser/students/goals/{goalId}/queue/", { params: { path: { goalId } } }));
                 const currentUrls = new Set(current.queue.map((item) => item.url));
                 const proposedUrls = new Set(entries.map((entry) => entry.url));
+                const currentByUrl = new Map(current.queue.map((item) => [item.url, item]));
+                const completionChanges = entries.flatMap((entry) => {
+                    if (entry.completed === undefined)
+                        return [];
+                    const existing = currentByUrl.get(entry.url);
+                    const currentlyCompleted = existing?.completedAt != null;
+                    if (currentlyCompleted === entry.completed)
+                        return [];
+                    return [
+                        {
+                            moduleRef: existing?.moduleRef ?? null,
+                            url: entry.url,
+                            fromCompletedAt: existing?.completedAt ?? null,
+                            toCompleted: entry.completed,
+                        },
+                    ];
+                });
                 const preview = {
                     action: "replace a goal's URL skill queue for a managed student",
                     target: { goalId, studentUserId: studentId },
                     request: {
                         entriesFile: absolutePath,
+                        entriesSha256: createHash("sha256")
+                            .update(rawEntriesText)
+                            .digest("hex"),
                         entryCount: entries.length,
                         delta,
                         replaceDescriptionPointer,
                         expectedUpdatedAt: goal.updatedAt,
+                        unchangedTitleForConcurrencyFence: goal.title,
                     },
                     details: {
                         currentQueue: current.queue.map((item) => ({
@@ -3444,26 +4249,31 @@ export async function runCommand(argv) {
                         removed: current.queue
                             .filter((item) => !proposedUrls.has(item.url))
                             .map((item) => item.url),
+                        completionChanges,
                         note: "Replaces the entire EXTERNAL_URL queue. Completion is preserved for unchanged URLs; WORKSPACE modules are untouched. Daily generation mints the head entry for a flag-on kid.",
                     },
                 };
-                requirePreviewBoundConfirmation(parsed, preview);
                 const body = {
                     delta,
                     expectedUpdatedAt: goal.updatedAt,
+                    // The deployed route's queue-only CAS reaches Prisma with an empty
+                    // scalar update, which reports zero rows and falsely trips the stale
+                    // write fence. Echoing the already-previewed title gives that CAS a
+                    // real update field without changing the title.
+                    title: goal.title,
                     queue: entries,
                     ...(replaceDescriptionPointer
                         ? { description: URL_QUEUE_DESCRIPTION_POINTER }
                         : {}),
                 };
-                return unwrap(await api.client.PATCH("/tutor/browser/students/goals/{goalId}/", {
+                return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.PATCH("/tutor/browser/students/goals/{goalId}/", {
                     params: { path: { goalId } },
                     body,
-                }));
+                })));
             }
             throw new CliError("invalid_arguments", "Use goals queue get|set.");
         }
-        throw new CliError("invalid_arguments", "Use goals list|create|edit|queue|files|pdf.");
+        throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|queue|files|pdf.");
     }
     if (noun === "students") {
         if (verb === "list") {
@@ -3559,11 +4369,37 @@ export async function runCommand(argv) {
                     patch: body,
                 },
             };
-            requirePreviewBoundConfirmation(parsed, preview);
-            return unwrap(await api.client.PATCH("/tutor/browser/todos/{id}", {
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.PATCH("/tutor/browser/todos/{id}", {
                 params: { path: { id: todoId } },
                 body,
+            })));
+        }
+        if (verb === "delete") {
+            const todoId = positional(parsed, 2, "todo ID");
+            const current = unwrap(await api.client.GET("/tutor/browser/todos/{id}/", {
+                params: { path: { id: todoId } },
             }));
+            const preview = {
+                action: "permanently delete a todo for a managed student",
+                target: {
+                    todoId,
+                    studentUserId: current.userId,
+                    title: current.title,
+                    status: current.status,
+                    goalId: current.goal?.id ?? null,
+                },
+                request: { expectedUpdatedAt: current.updatedAt },
+                details: {
+                    dueDate: current.dueDate,
+                    creationSource: current.creationSource,
+                    creationSourceId: current.creationSourceId,
+                    url: "url" in current ? current.url : null,
+                    note: "Hard-deletes this todo without awarding XP or running todo-completion side effects. This is permanent; use it only when the preview identifies a disposable todo with no work to preserve.",
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.DELETE("/admin/todos/{id}/", {
+                params: { path: { id: todoId } },
+            })));
         }
         if (verb === "generate-applet") {
             const todoId = positional(parsed, 2, "todo ID");
@@ -3601,13 +4437,12 @@ export async function runCommand(argv) {
                     versionRouting: "The server evaluates applet-gen-v2 for this student and uses v1 when the flag is off or its evaluation fails.",
                 },
             };
-            requirePreviewBoundConfirmation(parsed, preview);
-            return unwrap(await api.client.POST("/admin/learning-pipeline/{analysisId}/generate-applet/", {
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/admin/learning-pipeline/{analysisId}/generate-applet/", {
                 params: { path: { analysisId: analysis.id } },
                 body: targetDueDateISO ? { targetDueDateISO } : {},
-            }));
+            })));
         }
-        throw new CliError("invalid_arguments", "Use todos create|edit|generate-applet.");
+        throw new CliError("invalid_arguments", "Use todos create|edit|delete|generate-applet.");
     }
     if (noun === "memories") {
         const studentId = flagString(parsed, "student", { required: true });
@@ -3715,7 +4550,7 @@ export async function runCommand(argv) {
         if (preflight.action !== "preview_workspace_files_write") {
             throw new CliError("unexpected_response", "Goal PDF upload did not return a preview; nothing was uploaded.");
         }
-        requirePreviewBoundConfirmation(parsed, {
+        const preview = {
             action: "upload a textbook PDF and attach it to a student's goal",
             target: preflight.target,
             request: {
@@ -3729,111 +4564,114 @@ export async function runCommand(argv) {
                 currentChangeId: preflight.currentChangeId,
                 note: "The PDF is stored separately and the goal workspace receives a small verified reference, matching planner-authored textbook goals.",
             },
-        });
-        const conversationId = randomUUID();
-        const signed = unwrap(await api.client.POST("/os-v2-mesa/planner/uploads/sign", {
-            body: {
-                conversationId,
-                studentUserId: studentId,
-                fileName,
-                contentType: "application/pdf",
-                sizeBytes: fileStat.size,
-            },
-        }));
-        let uploaded;
-        try {
-            const uploadedSource = await uploadPdfToSignedUrls(absolutePath, "application/pdf", signed);
-            if (uploadedSource.sha256 !== sourceSha256 ||
-                uploadedSource.sizeBytes !== fileStat.size) {
-                throw new CliError("source_changed", "The source PDF changed after approval. The upload was discarded; preview the current file again.");
-            }
-            uploaded =
-                signed.kind === "multipart"
-                    ? unwrap(await api.client.POST("/os-v2-mesa/planner/uploads/complete", {
-                        body: {
-                            conversationId,
-                            fileName,
-                            contentType: "application/pdf",
-                            key: signed.key,
-                            uploadId: signed.uploadId,
-                            sizeBytes: fileStat.size,
-                        },
-                    }))
-                    : unwrap(await api.client.POST("/os-v2-mesa/planner/uploads/verify", {
-                        body: {
-                            conversationId,
-                            fileName,
-                            contentType: "application/pdf",
-                            key: signed.key,
-                            sizeBytes: fileStat.size,
-                        },
-                    }));
-        }
-        catch (error) {
-            // A failed multipart complete may already have materialized the object,
-            // so attempt both abort and delete. These are compensation attempts; the
-            // original upload error remains authoritative.
-            await cleanupPlannerUpload(api, conversationId, signed, true);
-            throw error;
-        }
-        const manifest = JSON.stringify({
-            kind: "r2-pdf",
-            version: 2,
-            r2Key: uploaded.key,
-            signature: uploaded.manifestSignature,
-            fileName,
-            contentType: uploaded.contentType,
-            sizeBytes: uploaded.sizeBytes,
-        });
-        let workspace;
-        try {
-            workspace = unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+        };
+        return previewBoundWrite(parsed, preview, async () => {
+            const conversationId = randomUUID();
+            const signed = unwrap(await api.client.POST("/os-v2-mesa/planner/uploads/sign", {
                 body: {
-                    ...body,
-                    files: [
-                        {
-                            path: workspacePath,
-                            content: manifest,
-                            contentEncoding: "utf8",
-                        },
-                    ],
-                    dryRun: false,
-                    expectedChangeId: preflight.currentChangeId,
+                    conversationId,
+                    studentUserId: studentId,
+                    fileName,
+                    contentType: "application/pdf",
+                    sizeBytes: fileStat.size,
                 },
             }));
-        }
-        catch (error) {
-            // Only a returned 4xx from this route is a definitive no-write response.
-            // A transport/5xx failure is ambiguous: the workspace commit may have landed,
-            // so keep the object rather than creating a dangling manifest.
-            const status = error instanceof CliError &&
-                error.details &&
-                typeof error.details === "object" &&
-                "status" in error.details
-                ? Number(error.details.status)
-                : 0;
-            if (status >= 400 && status < 500) {
+            let uploaded;
+            try {
+                const uploadedSource = await uploadPdfToSignedUrls(absolutePath, "application/pdf", signed);
+                if (uploadedSource.sha256 !== sourceSha256 ||
+                    uploadedSource.sizeBytes !== fileStat.size) {
+                    throw new CliError("source_changed", "The source PDF changed after approval. The upload was discarded; preview the current file again.");
+                }
+                uploaded =
+                    signed.kind === "multipart"
+                        ? unwrap(await api.client.POST("/os-v2-mesa/planner/uploads/complete", {
+                            body: {
+                                conversationId,
+                                fileName,
+                                contentType: "application/pdf",
+                                key: signed.key,
+                                uploadId: signed.uploadId,
+                                sizeBytes: fileStat.size,
+                            },
+                        }))
+                        : unwrap(await api.client.POST("/os-v2-mesa/planner/uploads/verify", {
+                            body: {
+                                conversationId,
+                                fileName,
+                                contentType: "application/pdf",
+                                key: signed.key,
+                                sizeBytes: fileStat.size,
+                            },
+                        }));
+            }
+            catch (error) {
+                // A failed multipart complete may already have materialized the object,
+                // so attempt both abort and delete. These are compensation attempts; the
+                // original upload error remains authoritative.
                 await cleanupPlannerUpload(api, conversationId, signed, true);
+                throw error;
             }
-            throw error;
-        }
-        return {
-            action: "upload_textbook_pdf",
-            sourceSha256,
-            fileName,
-            sizeBytes: uploaded.sizeBytes,
-            workspacePath,
-            workspace,
-        };
+            const manifest = JSON.stringify({
+                kind: "r2-pdf",
+                version: 2,
+                r2Key: uploaded.key,
+                signature: uploaded.manifestSignature,
+                fileName,
+                contentType: uploaded.contentType,
+                sizeBytes: uploaded.sizeBytes,
+            });
+            let workspace;
+            try {
+                workspace = unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+                    body: {
+                        ...body,
+                        files: [
+                            {
+                                path: workspacePath,
+                                content: manifest,
+                                contentEncoding: "utf8",
+                            },
+                        ],
+                        dryRun: false,
+                        expectedChangeId: preflight.currentChangeId,
+                    },
+                }));
+            }
+            catch (error) {
+                // Only a returned 4xx from this route is a definitive no-write response.
+                // A transport/5xx failure is ambiguous: the workspace commit may have landed,
+                // so keep the object rather than creating a dangling manifest.
+                const status = error instanceof CliError &&
+                    error.details &&
+                    typeof error.details === "object" &&
+                    "status" in error.details
+                    ? Number(error.details.status)
+                    : 0;
+                if (status >= 400 && status < 500) {
+                    await cleanupPlannerUpload(api, conversationId, signed, true);
+                }
+                throw error;
+            }
+            return {
+                action: "upload_textbook_pdf",
+                sourceSha256,
+                fileName,
+                sizeBytes: uploaded.sizeBytes,
+                workspacePath,
+                workspace,
+            };
+        });
     }
     if (noun === "goals" && verb === "files") {
         const action = positional(parsed, 2, "goals files action");
-        const studentId = flagString(parsed, "student", { required: true });
         if (action === "list") {
+            const studentId = flagString(parsed, "student", { required: true });
             const goalId = flagString(parsed, "goal", { required: true });
             return unwrap(await api.client.GET("/tutor/students/{studentId}/goals/{goalId}/workspace/files", { params: { path: { studentId, goalId } } }));
         }
         if (action === "read") {
+            const studentId = flagString(parsed, "student", { required: true });
             const goalId = flagString(parsed, "goal", { required: true });
             return unwrap(await api.client.GET("/tutor/students/{studentId}/goals/{goalId}/workspace/file", {
                 params: {
@@ -3842,7 +4680,115 @@ export async function runCommand(argv) {
                 },
             }));
         }
+        if (action === "init" || action === "checkout") {
+            const studentId = flagString(parsed, "student", { required: true });
+            const goalId = flagString(parsed, "goal");
+            const draftSlug = flagString(parsed, "draft");
+            if (action === "init" && (goalId || !draftSlug)) {
+                throw new CliError("invalid_arguments", "goals files init requires --draft and does not accept --goal.");
+            }
+            if (Boolean(goalId) === Boolean(draftSlug)) {
+                throw new CliError("invalid_arguments", "Pass exactly one of --goal or --draft for goals files checkout.");
+            }
+            const outputDirectory = flagString(parsed, "output-dir", {
+                required: true,
+            });
+            const target = goalId
+                ? { kind: "goal", goalId }
+                : { kind: "draft", draftSlug: draftSlug };
+            const response = await readRemoteWorkspaceSnapshot(api, studentId, target);
+            if (action === "init" && response.snapshot.fileCount > 0) {
+                throw new CliError("draft_exists", `Draft ${draftSlug} already has files. Use goals files checkout --draft to preserve them.`);
+            }
+            return checkoutGoalWorkspace({
+                outputDirectory,
+                studentId,
+                target,
+                snapshot: response.snapshot,
+            });
+        }
+        if (action === "push") {
+            const sourceDirectory = flagString(parsed, "source-dir", {
+                required: true,
+            });
+            const checkout = await readRecessGitMetadata(sourceDirectory);
+            const local = await readGoalWorkspaceGitChanges(checkout.root, checkout.metadata.upstreamCommit);
+            const defaultMessage = local.commits.length === 1
+                ? local.commits[0].subject
+                : `recess-cli: push ${local.commits.length} commits (${local.commits.at(-1).subject})`;
+            const message = (flagString(parsed, "message") ?? defaultMessage).trim();
+            if (!message || message.length > 200) {
+                throw new CliError("invalid_arguments", "--message (or the derived local commit message) must be 1 to 200 characters.");
+            }
+            const files = local.changes.map((change) => change.action === "delete"
+                ? { path: change.path, action: "delete" }
+                : {
+                    path: change.path,
+                    action: "upsert",
+                    content: change.content,
+                    contentEncoding: change.contentEncoding,
+                });
+            const body = {
+                studentUserId: checkout.metadata.studentId,
+                target: checkout.metadata.target,
+                message,
+                files,
+                expectedChangeId: checkout.metadata.changeId,
+            };
+            const preflight = unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+                body: { ...body, dryRun: true },
+            }));
+            if (preflight.action !== "preview_workspace_files_write") {
+                throw new CliError("unexpected_response", "Goal workspace push did not return a preview; nothing was written.");
+            }
+            const preview = {
+                action: `push committed Git changes to a student's Mesa ${checkout.metadata.target.kind} workspace`,
+                target: preflight.target,
+                request: {
+                    sourceDirectory: checkout.root,
+                    mesaBaseChangeId: checkout.metadata.changeId,
+                    localBaseCommit: checkout.metadata.upstreamCommit,
+                    localHeadCommit: local.head,
+                    commits: local.commits,
+                    message,
+                    changes: local.changes.map((change) => change.action === "delete"
+                        ? change
+                        : {
+                            path: change.path,
+                            action: change.action,
+                            sizeBytes: change.sizeBytes,
+                            sha256: change.sha256,
+                        }),
+                    sizeBytes: local.sizeBytes,
+                },
+                details: {
+                    currentChangeId: preflight.currentChangeId,
+                    note: "The committed local diff is published as one atomic Mesa change. Deletes and renames follow Git's diff. A changed Mesa tip refuses the push.",
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => {
+                const result = unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+                    body: { ...body, dryRun: false },
+                }));
+                if (result.action !== "write_workspace_files") {
+                    throw new CliError("unexpected_response", "Goal workspace push returned an unexpected response.");
+                }
+                await writeRecessGitMetadata(checkout.root, {
+                    ...checkout.metadata,
+                    changeId: result.changeId,
+                    upstreamCommit: local.head,
+                });
+                return {
+                    ...result,
+                    local: {
+                        directory: checkout.root,
+                        upstreamCommit: local.head,
+                    },
+                };
+            });
+        }
         if (action === "write") {
+            const studentId = flagString(parsed, "student", { required: true });
             const goalId = flagString(parsed, "goal");
             const draftSlug = flagString(parsed, "draft");
             if (Boolean(goalId) === Boolean(draftSlug)) {
@@ -3881,19 +4827,18 @@ export async function runCommand(argv) {
                     files: preflight.files,
                     note: target.kind === "draft"
                         ? "This writes a complete authoring tree under drafts/<slug>/workspace. Capture it only after the server's goal-workspace validation passes."
-                        : "Live goal modules/ and state/ are blocked here because they have database projections; use a draft + template capture for structural course changes.",
+                        : "This directly edits the live goal workspace, including modules/ and state/. The write remains bound to the previewed workspace revision.",
                 },
             };
-            requirePreviewBoundConfirmation(parsed, preview);
-            return unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
                 body: {
                     ...body,
                     dryRun: false,
                     expectedChangeId: preflight.currentChangeId,
                 },
-            }));
+            })));
         }
-        throw new CliError("invalid_arguments", "Use goals files list|read|write.");
+        throw new CliError("invalid_arguments", "Use goals files list|read|init|checkout|push|write.");
     }
     if (noun === "request" && verb === "get") {
         return api.rawGet(positional(parsed, 2, "request path"));