recess-cli 3.0.0 → 3.2.0

package/dist/cli.js

@@ -9,6 +9,7 @@ import { clearStoredSession, deleteProfile, listProfiles, resolveConfig, savePro
 import { agentContext, buildCommandSchema, findCommandSchema, remoteCommands, scopedHelp, validateInvocation, } from "./command-schema.js";
 import { runApplicationsCommand } from "./commands/applications.js";
 import { runAppsCommand } from "./commands/apps.js";
+import { readAssignmentSelection, runGoalCurriculumCommand, } from "./commands/goal-curriculum.js";
 import { runChatLogsCommand } from "./commands/chat-logs.js";
 import { runMasteryCommand } from "./commands/mastery.js";
 import { runOnboardingCommand } from "./commands/onboarding.js";
@@ -615,7 +616,7 @@ function assertOperationKeyMatchesPreview(operationKey, fingerprint, preview) {
         });
     }
 }
-async function requirePreviewBoundConfirmation(parsed, preview) {
+async function requirePreviewBoundConfirmation(parsed, preview, persistPreview = false) {
     const approvalToken = approvalTokenFor(preview);
     const suppliedOperationKey = flagString(parsed, "operation-key");
     const boundPreview = {
@@ -634,6 +635,9 @@ async function requirePreviewBoundConfirmation(parsed, preview) {
             action: preview.action,
             fingerprint: approvalToken,
             target: preview.target,
+            // Opted-in operations retain the approved receipt in the 0600 ledger so
+            // retries can reach server idempotency after their own write changed state.
+            ...(persistPreview ? { preview } : {}),
         });
         requireConfirmation(false, boundPreview);
     }
@@ -655,8 +659,46 @@ async function requirePreviewBoundConfirmation(parsed, preview) {
     });
     return { operationKey: suppliedOperationKey, fingerprint: approvalToken };
 }
-async function previewBoundWrite(parsed, preview, execute) {
-    const context = await requirePreviewBoundConfirmation(parsed, preview);
+/**
+ * A tutor template's `body` is the `## Subjects` block markdown (no `###`
+ * heading — the server renders that from `title` + `cadence`).
+ */
+async function readTutorTemplateBody(filePath) {
+    const absolutePath = path.resolve(filePath);
+    const contents = await fs.readFile(absolutePath, "utf8").catch(() => null);
+    if (contents === null) {
+        throw new CliError("invalid_arguments", `--body-file is not readable: ${absolutePath}`);
+    }
+    if (contents.trim().length === 0) {
+        throw new CliError("invalid_arguments", "--body-file is empty.");
+    }
+    return contents;
+}
+/**
+ * Every `*.md` in the directory becomes one `lessons[name]` entry, referenced
+ * from a module line as `lesson:<slug>/<name>`.
+ */
+async function readTutorTemplateLessons(directory) {
+    const absolutePath = path.resolve(directory);
+    const entries = await fs
+        .readdir(absolutePath, { withFileTypes: true })
+        .catch(() => null);
+    if (entries === null) {
+        throw new CliError("invalid_arguments", `--lessons-dir is not a readable directory: ${absolutePath}`);
+    }
+    const lessons = {};
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md"))
+            continue;
+        lessons[entry.name] = await fs.readFile(path.join(absolutePath, entry.name), "utf8");
+    }
+    if (Object.keys(lessons).length === 0) {
+        throw new CliError("invalid_arguments", `--lessons-dir contains no .md files: ${absolutePath}`);
+    }
+    return lessons;
+}
+async function previewBoundWrite(parsed, preview, execute, persistPreview = false) {
+    const context = await requirePreviewBoundConfirmation(parsed, preview, persistPreview);
     try {
         const result = await withIdempotencyContext(context, execute);
         await appendJobEvent({
@@ -688,6 +730,41 @@ async function previewBoundWrite(parsed, preview, execute) {
         throw error;
     }
 }
+async function readExecutedPreview(parsed) {
+    const key = flagString(parsed, "operation-key");
+    if (!hasFlag(parsed, "confirm") || !key)
+        return null;
+    const { history } = await getJob(key);
+    const receipt = [...history].reverse().find((event) => event.preview);
+    if (!receipt?.preview)
+        return null;
+    // First confirmation still refreshes server effects. A prior execution
+    // attempt is what makes a stale preflight an idempotent-recovery problem.
+    if (!history.some((event) => event.status !== "awaiting_confirmation" &&
+        event.fingerprint === receipt.fingerprint &&
+        event.action === receipt.action))
+        return null;
+    const saved = receipt.preview;
+    const fingerprint = approvalTokenFor(saved);
+    if (receipt.fingerprint !== fingerprint ||
+        flagString(parsed, "approval-token") !== fingerprint) {
+        throw new CliError("approval_mismatch", "This operation key does not match the approved command. Retry the original command unchanged, or review a new preview.");
+    }
+    assertOperationKeyMatchesPreview(key, fingerprint, saved);
+    return saved;
+}
+/** A retried write must retain its approved fence after changing its own source state. */
+async function recoverExecutedPreview(parsed, expected) {
+    const saved = await readExecutedPreview(parsed);
+    if (!saved)
+        return null;
+    if (saved.action !== expected.action ||
+        JSON.stringify(saved.target) !== JSON.stringify(expected.target) ||
+        JSON.stringify(saved.request) !== JSON.stringify(expected.request)) {
+        throw new CliError("approval_mismatch", "This operation key does not match the approved command. Retry the original command unchanged, or review a new preview.");
+    }
+    return saved;
+}
 async function cleanupPlannerUpload(api, conversationId, signed, includeDelete) {
     if (signed.kind === "multipart") {
         await api.client
@@ -809,6 +886,9 @@ async function readGoalWorkspaceWriteSource(parsed) {
             const entries = await fs.readdir(directory, { withFileTypes: true });
             entries.sort((a, b) => a.name.localeCompare(b.name));
             for (const entry of entries) {
+                // Git metadata is local checkout state, including worktree .git files.
+                if (entry.name === ".git")
+                    continue;
                 const relativePath = relativeRoot
                     ? path.join(relativeRoot, entry.name)
                     : entry.name;
@@ -1877,6 +1957,10 @@ export async function executeRecessCommand(argv, options = {}) {
         };
     }
     if (noun === "auth") {
+        const duration = flagString(parsed, "duration");
+        if (duration !== undefined && duration !== "12h" && duration !== "30d") {
+            throw new CliError("invalid_arguments", "--duration must be 12h or 30d (admins only).");
+        }
         if (verb === "login") {
             const oauthClientId = flagString(parsed, "client-id") ?? config.oauthClientId;
             const callbackPort = flagNumber(parsed, "callback-port") ?? 8765;
@@ -1885,11 +1969,15 @@ export async function executeRecessCommand(argv, options = {}) {
                 callbackPort > 65535) {
                 throw new CliError("invalid_arguments", "--callback-port must be an integer from 1024 through 65535.");
             }
-            return login(config, { callbackPort, oauthClientId });
+            return login(config, {
+                callbackPort,
+                oauthClientId,
+                sessionDuration: duration,
+            });
         }
         if (verb === "request") {
             const label = flagString(parsed, "label");
-            return requestDeviceAuth(config, label ? { label } : {});
+            return requestDeviceAuth(config, { label, sessionDuration: duration });
         }
         if (verb === "poll") {
             const timeoutSeconds = flagNumber(parsed, "timeout") ?? 300;
@@ -3460,6 +3548,16 @@ export async function executeRecessCommand(argv, options = {}) {
         throw new CliError("invalid_arguments", "Use content-library search, status, set-stage, or submit.");
     }
     if (noun === "goal-templates") {
+        if (verb === "curriculum") {
+            return runGoalCurriculumCommand({
+                parsed,
+                api,
+                writeCommand,
+                resolveTemplateId: (value) => resolveGoalTemplateId(api, value),
+                previewBoundWrite: (args, preview, execute) => previewBoundWrite(args, preview, execute, true),
+                recoverExecutedPreview: (expected) => recoverExecutedPreview(parsed, expected),
+            });
+        }
         const readTemplateDocument = async () => {
             if (!isRemote) {
                 return readJsonFile(flagString(parsed, "file", { required: true }), "Template file");
@@ -3618,6 +3716,174 @@ export async function executeRecessCommand(argv, options = {}) {
                 body: document,
             })));
         }
+        if (verb === "policy") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            return unwrap(await api.client.GET("/ai/goal-templates/{id}/policy", {
+                params: { path: { id } },
+            }));
+        }
+        if (verb === "set-policy") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const target = flagString(parsed, "target-modules");
+            const minimum = flagString(parsed, "required-modules");
+            for (const [flag, value] of [
+                ["target-modules", target],
+                ["required-modules", minimum],
+            ]) {
+                if (value === undefined ||
+                    (flag === "required-modules" && value === "all"))
+                    continue;
+                const count = Number(value);
+                if (!Number.isInteger(count) || count < 1 || count > 20)
+                    throw new CliError("invalid_arguments", `--${flag} must be an integer from 1 through 20${flag === "required-modules" ? " or all" : ""}.`);
+            }
+            if (target === undefined && minimum === undefined)
+                throw new CliError("invalid_arguments", "Provide --target-modules or --required-modules N|all");
+            const body = {
+                recipeKey: flagString(parsed, "recipe", { required: true }),
+                ...(target === undefined ? {} : { targetModuleCount: Number(target) }),
+                ...(minimum === undefined
+                    ? {}
+                    : {
+                        requiredModuleCount: minimum === "all" ? null : Number(minimum),
+                    }),
+                expectedVersion: requiredExpectedVersion(parsed),
+            };
+            const requestPreview = {
+                action: "edit shared goal-template assigned target or completion minimum",
+                target: { templateId: id, apiOrigin: api.config.apiOrigin },
+                request: body,
+            };
+            const receipt = await recoverExecutedPreview(parsed, requestPreview);
+            const preview = receipt ?? {
+                ...requestPreview,
+                details: unwrap(await api.client.POST("/ai/goal-templates/{id}/policy", {
+                    params: { path: { id } },
+                    body: { ...body, dryRun: true },
+                })),
+            };
+            // A recovered receipt only skips the now-stale preview. The actual write
+            // still reaches server authorization, idempotency, and expectedVersion.
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/policy", {
+                params: { path: { id } },
+                body: { ...body, dryRun: false },
+            })), true);
+        }
+        if (verb === "migrate-policy") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const studentIds = flagString(parsed, "students", { required: true })
+                .split(",")
+                .map((value) => value.trim());
+            const preflight = unwrap(await api.client.POST("/ai/goal-templates/{id}/policy-migration", {
+                params: { path: { id } },
+                body: { studentIds, dryRun: true },
+            }));
+            const preview = {
+                action: "backfill reviewed goal policy identities and migration holds",
+                target: { templateId: id, studentIds },
+                request: { studentIds, fingerprint: preflight.fingerprint },
+                details: preflight,
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/policy-migration", {
+                params: { path: { id } },
+                body: {
+                    studentIds,
+                    fingerprint: preflight.fingerprint,
+                    dryRun: false,
+                },
+            })));
+        }
+        if (verb === "retire-assignments") {
+            const [id, session] = await Promise.all([
+                resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug")),
+                api.client.GET("/auth/admin-cli/session/").then(unwrap),
+            ]);
+            if (session.user.role !== "ADMIN" || session.cliScope !== "full_admin")
+                throw new CliError("forbidden", "Assignment retirement requires a full-admin session.");
+            const goalId = flagString(parsed, "goal", { required: true });
+            const rawIds = flagString(parsed, "todos");
+            const selectionPath = flagString(parsed, "todos-file");
+            if (Boolean(rawIds) === Boolean(selectionPath))
+                throw new CliError("invalid_arguments", "Choose exactly one of --todos or --todos-file with explicit assignment IDs.");
+            const selection = selectionPath
+                ? await readAssignmentSelection(selectionPath)
+                : null;
+            const todoIds = selection?.todoIds ?? rawIds.split(",").map((id) => id.trim());
+            if (!todoIds.length ||
+                todoIds.length > 500 ||
+                todoIds.some((id) => !id) ||
+                new Set(todoIds).size !== todoIds.length)
+                throw new CliError("invalid_arguments", "Choose 1–500 distinct assignment IDs explicitly.");
+            const reason = flagString(parsed, "retirement-reason", {
+                required: true,
+            });
+            const requestPreview = {
+                action: "retire the selected curriculum assignments without completing lessons",
+                target: {
+                    templateId: id,
+                    goalId,
+                    actorId: session.user.id,
+                    apiOrigin: api.config.apiOrigin,
+                },
+                request: { todoIds, reason, selectionFile: selection?.file ?? null },
+            };
+            const receipt = await recoverExecutedPreview(parsed, requestPreview);
+            const preflight = receipt
+                ? receipt.details
+                : unwrap(await api.client.POST("/ai/goal-templates/{id}/goals/{goalId}/assignments/retire", {
+                    params: { path: { id, goalId } },
+                    body: { todoIds, reason, dryRun: true },
+                }));
+            const preview = receipt ?? {
+                ...requestPreview,
+                details: preflight,
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/goals/{goalId}/assignments/retire", {
+                params: { path: { id, goalId } },
+                body: {
+                    todoIds,
+                    reason,
+                    fingerprint: preflight.fingerprint,
+                    dryRun: false,
+                },
+            })));
+        }
+        if (verb === "student-policy") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const goalId = flagString(parsed, "goal", { required: true });
+            const filePath = path.resolve(flagString(parsed, "file", { required: true }));
+            const bytes = await fs.readFile(filePath);
+            let raw;
+            try {
+                raw = JSON.parse(bytes.toString("utf8"));
+            }
+            catch {
+                throw new CliError("invalid_arguments", "Student policy edit must contain valid JSON");
+            }
+            // Backend Zod is authoritative; preserve exact file bytes in the approval preview.
+            const body = raw;
+            const preflight = unwrap(await api.client.POST("/ai/goal-templates/{id}/goals/{goalId}/policy", {
+                params: { path: { id, goalId } },
+                body: { ...body, dryRun: true },
+            }));
+            const preview = {
+                action: "review a student policy override or migration hold",
+                target: { templateId: id, goalId },
+                request: body,
+                details: {
+                    ...preflight,
+                    file: {
+                        absolutePath: filePath,
+                        sizeBytes: bytes.byteLength,
+                        sha256: createHash("sha256").update(bytes).digest("hex"),
+                    },
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/goals/{goalId}/policy", {
+                params: { path: { id, goalId } },
+                body: { ...body, dryRun: false },
+            })));
+        }
         if (verb === "patch-spec") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
             const expectedVersion = requiredExpectedVersion(parsed);
@@ -4090,6 +4356,65 @@ export async function executeRecessCommand(argv, options = {}) {
                             .includes(query))),
             };
         }
+        // Moves ONE kid's lesson, not the template's. The daily queue serves
+        // modules by `ordinal ASC`, so pushing the one a kid is stuck on past the
+        // rest is what hands them the next lesson tomorrow — no template version,
+        // no retiring the work they have already done, nobody else's goal touched.
+        if (verb === "move-module") {
+            const moduleRef = positional(parsed, 2, "module ref (e.g. Q006)");
+            const studentId = flagString(parsed, "student", { required: true });
+            const goalId = flagString(parsed, "goal", { required: true });
+            const toEnd = hasFlag(parsed, "to-end");
+            const position = flagNumber(parsed, "position");
+            if (toEnd === (position !== undefined)) {
+                throw new CliError("invalid_arguments", "Pass exactly one of --to-end or --position <n>.");
+            }
+            const goal = unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
+                params: { path: { userId: studentId } },
+            })).goals.find((candidate) => candidate.id === goalId);
+            const modules = goal?.osV2?.modules ?? [];
+            const target = modules.find((module) => module.moduleRef.toLocaleLowerCase() === moduleRef.toLocaleLowerCase());
+            if (!target) {
+                throw new CliError("not_found", `Module ${moduleRef} was not found on goal ${goalId}. Known refs: ${modules.map((m) => m.moduleRef).join(", ") || "none"}.`);
+            }
+            // Sparse past the current maximum, so no sibling has to be renumbered.
+            const last = modules.reduce((max, m) => Math.max(max, m.ordinal), 0);
+            const ordinal = toEnd ? last + 1 : position;
+            if (ordinal === target.ordinal) {
+                throw new CliError("already_positioned", `Module ${target.moduleRef} ("${target.title}") is already at position ${ordinal}.`);
+            }
+            const collision = modules.find((m) => m.id !== target.id && m.ordinal === ordinal);
+            const preview = {
+                action: toEnd
+                    ? "move a lesson to the end of this kid's curriculum"
+                    : "move a lesson to a specific position in this kid's curriculum",
+                target: {
+                    studentUserId: studentId,
+                    goalId,
+                    goalTitle: goal?.title ?? null,
+                    moduleRef: target.moduleRef,
+                    title: target.title,
+                    from: target.ordinal,
+                    to: ordinal,
+                    completed: target.completedAt !== null,
+                },
+                request: { moduleId: target.id, ordinal },
+                details: {
+                    note: "Affects only this student's copy of the curriculum — the goal template and every other kid on it are untouched. Completion state is preserved: an unfinished lesson stays unfinished and is simply served later.",
+                    ...(collision
+                        ? {
+                            warning: `Position ${ordinal} is already held by ${collision.moduleRef} ("${collision.title}"). Both will sit at the same position and the queue will order them by creation date — pass --to-end instead if you just want this one out of the way.`,
+                        }
+                        : {}),
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.PATCH("/tutor/students/{studentId}/goals/{goalId}/modules/{moduleId}", {
+                params: {
+                    path: { studentId, goalId, moduleId: target.id },
+                },
+                body: { ordinal },
+            })));
+        }
         if (verb === "create") {
             const requestedStudentId = flagString(parsed, "student");
             const sourceDirectory = flagString(parsed, "source-dir");
@@ -4437,7 +4762,7 @@ export async function executeRecessCommand(argv, options = {}) {
             }
             throw new CliError("invalid_arguments", "Use goals queue get|set.");
         }
-        throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|restore|archive|unarchive|complete|undo-completion|queue|files|pdf.");
+        throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|restore|archive|unarchive|complete|undo-completion|move-module|queue|files|pdf.");
     }
     if (noun === "chat-logs") {
         return runChatLogsCommand({ parsed, api, writeCommand });
@@ -4864,6 +5189,156 @@ export async function executeRecessCommand(argv, options = {}) {
         }
         throw new CliError("invalid_arguments", "Use rocky get|set.");
     }
+    if (noun === "tutor-templates") {
+        if (verb === "list") {
+            const grade = flagNumber(parsed, "grade");
+            return unwrap(await api.client.GET("/tutor-templates/", {
+                params: {
+                    query: {
+                        q: flagString(parsed, "q"),
+                        subject: flagString(parsed, "subject"),
+                        ...(grade === undefined ? {} : { grade }),
+                    },
+                },
+            }));
+        }
+        if (verb === "get") {
+            const slug = positional(parsed, 2, "template slug");
+            return unwrap(await api.client.GET("/tutor-templates/{slug}", {
+                params: { path: { slug } },
+            }));
+        }
+        if (verb === "assign" || verb === "unassign") {
+            const slug = positional(parsed, 2, "template slug");
+            const studentId = flagString(parsed, "student");
+            const body = studentId ? { studentId } : {};
+            const template = unwrap(await api.client.GET("/tutor-templates/{slug}", {
+                params: { path: { slug } },
+            }));
+            return writeCommand(parsed, {
+                action: verb === "assign"
+                    ? "add a tutor template's subject block to a kid's plan"
+                    : "remove a tutor template's subject block from a kid's plan",
+                target: { slug, studentUserId: studentId ?? "the signed-in kid" },
+                request: body,
+                details: {
+                    title: template.title,
+                    cadence: template.cadence,
+                    consequence: verb === "assign"
+                        ? "Appends `### <title> — <cadence>` to rocky-v3/plan.md, rebuilds Today, and writes an ACTIVE assignment row."
+                        : "Deletes that subject block from rocky-v3/plan.md and marks the assignment REMOVED.",
+                },
+            }, async () => verb === "assign"
+                ? unwrap(await api.client.POST("/tutor-templates/{slug}/assign", {
+                    params: { path: { slug } },
+                    body,
+                }))
+                : unwrap(await api.client.POST("/tutor-templates/{slug}/unassign", {
+                    params: { path: { slug } },
+                    body,
+                })));
+        }
+        if (verb === "create" || verb === "update") {
+            const bodyFile = flagString(parsed, "body-file", {
+                required: verb === "create",
+            });
+            const lessonsDir = flagString(parsed, "lessons-dir");
+            const visibility = flagString(parsed, "visibility");
+            const emoji = flagString(parsed, "emoji");
+            const gradeMin = flagNumber(parsed, "grade-min");
+            const gradeMax = flagNumber(parsed, "grade-max");
+            const shared = {
+                ...(flagString(parsed, "title") === undefined
+                    ? {}
+                    : { title: flagString(parsed, "title") }),
+                ...(flagString(parsed, "summary") === undefined
+                    ? {}
+                    : { summary: flagString(parsed, "summary") }),
+                ...(flagString(parsed, "subject") === undefined
+                    ? {}
+                    : { subject: flagString(parsed, "subject") }),
+                ...(flagString(parsed, "cadence") === undefined
+                    ? {}
+                    : { cadence: flagString(parsed, "cadence") }),
+                ...(emoji === undefined ? {} : { emoji }),
+                ...(gradeMin === undefined ? {} : { gradeMin }),
+                ...(gradeMax === undefined ? {} : { gradeMax }),
+                ...(visibility === undefined
+                    ? {}
+                    : {
+                        visibility: assertChoice(visibility, ["PUBLIC", "STAFF"], "--visibility"),
+                    }),
+                ...(bodyFile === undefined
+                    ? {}
+                    : { body: await readTutorTemplateBody(bodyFile) }),
+                ...(lessonsDir === undefined
+                    ? {}
+                    : { lessons: await readTutorTemplateLessons(lessonsDir) }),
+            };
+            if (verb === "create") {
+                const missing = ["title", "summary", "subject", "cadence"].filter((name) => !(name in shared));
+                if (missing.length > 0) {
+                    throw new CliError("invalid_arguments", `tutor-templates create requires ${missing
+                        .map((name) => `--${name}`)
+                        .join(", ")}.`);
+                }
+                const slug = flagString(parsed, "slug", { required: true });
+                const body = { slug, ...shared };
+                return writeCommand(parsed, {
+                    action: "create a tutor template in the subject catalog",
+                    target: { slug },
+                    request: {
+                        ...body,
+                        bodyFile: bodyFile ? path.resolve(bodyFile) : null,
+                        lessonsDir: lessonsDir ? path.resolve(lessonsDir) : null,
+                    },
+                    details: {
+                        lessonNames: Object.keys(shared.lessons ?? {}),
+                        renamingNote: "`title` is the `### <heading>` join key in every kid's plan.md — renaming later orphans existing plans.",
+                    },
+                }, async () => unwrap(await api.client.POST("/tutor-templates/", { body })));
+            }
+            const slug = positional(parsed, 2, "template slug");
+            const body = shared;
+            if (Object.keys(body).length === 0) {
+                throw new CliError("invalid_arguments", "tutor-templates update needs at least one field to change.");
+            }
+            return writeCommand(parsed, {
+                action: "update a tutor template in the subject catalog",
+                target: { slug },
+                request: {
+                    ...body,
+                    bodyFile: bodyFile ? path.resolve(bodyFile) : null,
+                    lessonsDir: lessonsDir ? path.resolve(lessonsDir) : null,
+                },
+                details: {
+                    fields: Object.keys(body),
+                    renamingNote: "Changing `title` orphans the `### <heading>` in every plan.md already carrying this template.",
+                },
+            }, async () => unwrap(await api.client.PATCH("/tutor-templates/{slug}", {
+                params: { path: { slug } },
+                body,
+            })));
+        }
+        if (verb === "delete") {
+            const slug = positional(parsed, 2, "template slug");
+            const template = unwrap(await api.client.GET("/tutor-templates/{slug}", {
+                params: { path: { slug } },
+            }));
+            return writeCommand(parsed, {
+                action: "soft-delete a tutor template from the subject catalog",
+                target: { slug },
+                request: {},
+                details: {
+                    title: template.title,
+                    consequence: "The row is soft-deleted; subject blocks already written into kids' plan.md stay where they are.",
+                },
+            }, async () => unwrap(await api.client.DELETE("/tutor-templates/{slug}", {
+                params: { path: { slug } },
+            })));
+        }
+        throw new CliError("invalid_arguments", "Use tutor-templates list|get|create|update|delete|assign|unassign.");
+    }
     if (noun === "goals" && verb === "pdf") {
         const action = positional(parsed, 2, "goals pdf action");
         if (action !== "upload") {
@@ -5085,7 +5560,40 @@ export async function executeRecessCommand(argv, options = {}) {
                 required: true,
             });
             const checkout = await readRecessGitMetadata(sourceDirectory);
-            const local = await readGoalWorkspaceGitChanges(checkout.root, checkout.metadata.upstreamCommit);
+            const isGoal = checkout.metadata.target.kind === "goal";
+            const session = isGoal
+                ? unwrap(await api.client.GET("/auth/admin-cli/session/"))
+                : null;
+            const actionDescription = `push committed Git changes to a student's Mesa ${checkout.metadata.target.kind} workspace`;
+            const boundTarget = session
+                ? {
+                    studentId: checkout.metadata.studentId,
+                    workspace: checkout.metadata.target,
+                    actorId: session.user.id,
+                    apiOrigin: api.config.apiOrigin,
+                }
+                : null;
+            const receipt = isGoal ? await readExecutedPreview(parsed) : null;
+            if (receipt &&
+                (receipt.action !== actionDescription ||
+                    JSON.stringify(receipt.target) !== JSON.stringify(boundTarget) ||
+                    receipt.request.sourceDirectory !== checkout.root)) {
+                throw new CliError("approval_mismatch", "The approved push belongs to a different checkout, account, or API.");
+            }
+            const localBaseCommit = receipt
+                ? String(receipt.request.localBaseCommit)
+                : checkout.metadata.upstreamCommit;
+            const mesaBaseChangeId = receipt
+                ? String(receipt.request.mesaBaseChangeId)
+                : checkout.metadata.changeId;
+            const local = await readGoalWorkspaceGitChanges(checkout.root, localBaseCommit);
+            if (receipt &&
+                ((checkout.metadata.upstreamCommit !== localBaseCommit &&
+                    checkout.metadata.upstreamCommit !== local.head) ||
+                    (checkout.metadata.upstreamCommit === localBaseCommit &&
+                        checkout.metadata.changeId !== mesaBaseChangeId))) {
+                throw new CliError("approval_mismatch", "The checkout's upstream metadata moved outside the approved push.");
+            }
             const defaultMessage = local.commits.length === 1
                 ? local.commits[0].subject
                 : `recess-cli: push ${local.commits.length} commits (${local.commits.at(-1).subject})`;
@@ -5101,41 +5609,61 @@ export async function executeRecessCommand(argv, options = {}) {
                     content: change.content,
                     contentEncoding: change.contentEncoding,
                 });
+            const assignedEdits = hasFlag(parsed, "allow-assigned-edits")
+                ? { allowAssignedEdits: true }
+                : {};
+            const stateModification = hasFlag(parsed, "allow-state-modification")
+                ? { allowStateModification: true }
+                : {};
             const body = {
+                ...stateModification,
+                ...assignedEdits,
                 studentUserId: checkout.metadata.studentId,
                 target: checkout.metadata.target,
                 message,
                 files,
-                expectedChangeId: checkout.metadata.changeId,
+                expectedChangeId: mesaBaseChangeId,
             };
-            const preflight = unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
-                body: { ...body, dryRun: true },
-            }));
-            if (preflight.action !== "preview_workspace_files_write") {
+            const preflight = receipt
+                ? null
+                : unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+                    body: { ...body, dryRun: true },
+                }));
+            if (preflight && 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,
-                },
+            const request = {
+                ...stateModification,
+                ...assignedEdits,
+                sourceDirectory: checkout.root,
+                mesaBaseChangeId,
+                localBaseCommit,
+                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,
+            };
+            if (receipt &&
+                JSON.stringify(receipt.request) !== JSON.stringify(request)) {
+                throw new CliError("approval_mismatch", "The command or committed file bytes differ from the approved push.");
+            }
+            const preview = receipt ?? {
+                action: actionDescription,
+                target: boundTarget ?? preflight.target,
+                request,
                 details: {
+                    stateModificationPaths: preflight.stateModificationPaths ?? [],
+                    warnings: preflight.warnings ?? [],
                     currentChangeId: preflight.currentChangeId,
+                    resolvedTarget: preflight.target,
                     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.",
                 },
             };
@@ -5146,6 +5674,11 @@ export async function executeRecessCommand(argv, options = {}) {
                 if (result.action !== "write_workspace_files") {
                     throw new CliError("unexpected_response", "Goal workspace push returned an unexpected response.");
                 }
+                if (receipt &&
+                    checkout.metadata.upstreamCommit === local.head &&
+                    checkout.metadata.changeId !== result.changeId) {
+                    throw new CliError("approval_mismatch", "The acknowledged checkout revision does not match this recovered push. Its local metadata was preserved.");
+                }
                 await writeRecessGitMetadata(checkout.root, {
                     ...checkout.metadata,
                     changeId: result.changeId,
@@ -5158,7 +5691,7 @@ export async function executeRecessCommand(argv, options = {}) {
                         upstreamCommit: local.head,
                     },
                 };
-            });
+            }, isGoal);
         }
         if (action === "write") {
             const studentId = flagString(parsed, "student", { required: true });
@@ -5173,31 +5706,65 @@ export async function executeRecessCommand(argv, options = {}) {
                 : { kind: "draft", draftSlug: draftSlug };
             const message = flagString(parsed, "message") ??
                 `recess-cli: write ${input.files.length} workspace file${input.files.length === 1 ? "" : "s"}`;
+            const assignedEdits = hasFlag(parsed, "allow-assigned-edits")
+                ? { allowAssignedEdits: true }
+                : {};
+            const stateModification = hasFlag(parsed, "allow-state-modification")
+                ? { allowStateModification: true }
+                : {};
             const body = {
+                ...stateModification,
+                ...assignedEdits,
                 studentUserId: studentId,
                 target,
                 message,
                 files: input.files,
             };
-            const preflight = unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
-                body: { ...body, dryRun: true },
-            }));
-            if (preflight.action !== "preview_workspace_files_write") {
+            const session = goalId
+                ? unwrap(await api.client.GET("/auth/admin-cli/session/"))
+                : null;
+            const request = {
+                ...stateModification,
+                ...assignedEdits,
+                source: input.source,
+                sourceSha256: input.sha256,
+                fileCount: input.files.length,
+                sizeBytes: input.sizeBytes,
+                message,
+            };
+            const boundTarget = session
+                ? {
+                    studentId,
+                    goalId: goalId,
+                    actorId: session.user.id,
+                    apiOrigin: api.config.apiOrigin,
+                }
+                : null;
+            const receipt = boundTarget
+                ? await recoverExecutedPreview(parsed, {
+                    action: "batch-upsert files in a student's goal workspace",
+                    target: boundTarget,
+                    request,
+                })
+                : null;
+            const preflight = receipt
+                ? null
+                : unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+                    body: { ...body, dryRun: true },
+                }));
+            if (preflight && preflight.action !== "preview_workspace_files_write") {
                 throw new CliError("unexpected_response", "Goal workspace write did not return a preview; nothing was written.");
             }
-            const preview = {
+            const preview = receipt ?? {
                 action: "batch-upsert files in a student's goal workspace",
-                target: preflight.target,
-                request: {
-                    source: input.source,
-                    sourceSha256: input.sha256,
-                    fileCount: input.files.length,
-                    sizeBytes: input.sizeBytes,
-                    message,
-                },
+                target: boundTarget ?? preflight.target,
+                request,
                 details: {
+                    stateModificationPaths: preflight.stateModificationPaths ?? [],
+                    warnings: preflight.warnings ?? [],
                     currentChangeId: preflight.currentChangeId,
                     files: preflight.files,
+                    resolvedTarget: preflight.target,
                     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."
                         : "This directly edits the live goal workspace, including modules/ and state/. The write remains bound to the previewed workspace revision.",
@@ -5207,9 +5774,9 @@ export async function executeRecessCommand(argv, options = {}) {
                 body: {
                     ...body,
                     dryRun: false,
-                    expectedChangeId: preflight.currentChangeId,
+                    expectedChangeId: String(preview.details.currentChangeId),
                 },
-            })));
+            })), Boolean(goalId));
         }
         throw new CliError("invalid_arguments", "Use goals files list|read|init|checkout|push|write.");
     }