agentplane 0.3.7 → 0.3.9

package/dist/commands/task/plan.command.js

@@ -1,6 +1,4 @@
-import { usageError } from "../../cli/spec/errors.js";
-import { suggestOne } from "../../cli/spec/suggest.js";
-const TASK_PLAN_SUBCOMMANDS = ["set", "approve", "reject"];
+import { loadDirectSubcommandNames, parseGroupCommand, throwGroupCommandUsage, } from "../../cli/group-command.js";
 export const taskPlanSpec = {
     id: ["task", "plan"],
     group: "Task",
@@ -21,17 +19,13 @@ export const taskPlanSpec = {
             why: "Reject the current task plan with a note.",
         },
     ],
-    parse: (raw) => ({ cmd: (raw.args.cmd ?? []) }),
+    parse: (raw) => parseGroupCommand(raw),
 };
-export const runTaskPlan = (_ctx, p) => {
-    const input = p.cmd.join(" ");
-    const suggestion = suggestOne(input, [...TASK_PLAN_SUBCOMMANDS]);
-    const suffix = suggestion ? ` Did you mean: ${suggestion}?` : "";
-    const message = p.cmd.length === 0 ? "Missing subcommand." : `Unknown subcommand: ${p.cmd[0]}.`;
-    throw usageError({
+export const runTaskPlan = async (_ctx, p) => {
+    throwGroupCommandUsage({
         spec: taskPlanSpec,
+        cmd: p.cmd,
+        subcommands: await loadDirectSubcommandNames(["task", "plan"]),
         command: "task plan",
-        message: `${message}${suffix}`,
-        context: { command: "task plan" },
     });
 };

package/dist/commands/task/plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/commands/task/plan.ts"],"names":[],"mappings":"AASA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAkJnC,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8HlB;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CA2DlB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,MAAM,CAAC,CAkElB"}
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/commands/task/plan.ts"],"names":[],"mappings":"AASA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AA8InC,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAuHlB;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CAgElB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,MAAM,CAAC,CAuElB"}

package/dist/commands/task/plan.js

@@ -5,17 +5,13 @@ import { mapBackendError, mapCoreError } from "../../cli/error-map.js";
 import { backendNotSupportedMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
 import { loadCommandContext, loadTaskFromContext, } from "../shared/task-backend.js";
-import { backendIsLocalFileBackend, getTaskStore } from "../shared/task-store.js";
+import { applyTaskMutation, withTaskMutationStorage } from "../shared/task-mutation.js";
+import { setTaskFieldsIntent, setTaskSectionIntent, touchTaskDocMetaIntent, } from "../shared/task-store.js";
 import { decodeEscapedTaskTextNewlines, ensureAgentFilledRequiredDocSections, extractDocSection, extractTaskObservationSection, isVerifyStepsFilled, nowIso, normalizeTaskDocVersion, taskObservationSectionName, requiresVerifyStepsByPrimary, toStringArray, } from "./shared.js";
-async function loadPlanTask(opts) {
+async function loadPlanBackend(opts) {
     const ctx = opts.ctx ??
         (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
     const backend = ctx.taskBackend;
-    const useStore = backendIsLocalFileBackend(ctx);
-    const store = useStore ? getTaskStore(ctx) : null;
-    const task = useStore
-        ? await store.get(opts.taskId)
-        : await loadTaskFromContext({ ctx, taskId: opts.taskId });
     if (!backend.getTaskDoc || !backend.writeTask) {
         throw new CliError({
             exitCode: 2,
@@ -23,7 +19,7 @@ async function loadPlanTask(opts) {
             message: backendNotSupportedMessage("task docs"),
         });
     }
-    return { ctx, backend: backend, task, useStore, store };
+    return { ctx, backend: backend };
 }
 function normalizeForComparison(text) {
     return text.replaceAll("\r\n", "\n").trim();
@@ -92,11 +88,10 @@ function assertPlanCanBeApproved(opts) {
 }
 export async function cmdTaskPlanSet(opts) {
     try {
-        const { ctx, backend, task, useStore, store } = await loadPlanTask({
+        const { ctx, backend } = await loadPlanBackend({
             ctx: opts.ctx,
             cwd: opts.cwd,
             rootOverride: opts.rootOverride,
-            taskId: opts.taskId,
         });
         const config = ctx.config;
         const resolved = ctx.resolvedProject;
@@ -133,12 +128,15 @@ export async function cmdTaskPlanSet(opts) {
                 throw mapCoreError(err, { command: "task plan set", filePath: opts.file ?? "" });
             }
         }
-        const readmePath = path.join(resolved.gitRoot, config.paths.workflow_dir, task.id, "README.md");
-        if (useStore) {
-            let expectedCurrentPlan;
-            await store.patch(opts.taskId, (current) => {
+        const readmePath = path.join(resolved.gitRoot, config.paths.workflow_dir, opts.taskId, "README.md");
+        await applyTaskMutation({
+            ctx,
+            taskId: opts.taskId,
+            build: async (current) => {
+                const currentDocRaw = (typeof current.doc === "string" ? current.doc : "") ||
+                    (await backend.getTaskDoc(current.id));
                 const { currentPlan, nextPlan, planChanged, docChanged } = buildPlanDocUpdate({
-                    currentDocRaw: String(current.doc ?? ""),
+                    currentDocRaw,
                     text,
                     requiredSections: config.tasks.doc.required_sections,
                 });
@@ -146,67 +144,52 @@ export async function cmdTaskPlanSet(opts) {
                     return null;
                 if (!docChanged) {
                     return {
+                        intents: [
+                            ...(planChanged
+                                ? [
+                                    setTaskFieldsIntent({
+                                        plan_approval: {
+                                            state: "pending",
+                                            updated_at: null,
+                                            updated_by: null,
+                                            note: null,
+                                        },
+                                    }),
+                                ]
+                                : []),
+                            ...(updatedBy ? [touchTaskDocMetaIntent({ updatedBy })] : []),
+                        ],
+                    };
+                }
+                return {
+                    intents: [
+                        setTaskSectionIntent({
+                            section: "Plan",
+                            text: nextPlan,
+                            requiredSections: config.tasks.doc.required_sections,
+                            expectedCurrentText: currentPlan,
+                        }),
                         ...(planChanged
-                            ? {
-                                task: {
+                            ? [
+                                setTaskFieldsIntent({
                                     plan_approval: {
                                         state: "pending",
                                         updated_at: null,
                                         updated_by: null,
                                         note: null,
                                     },
-                                },
-                            }
-                            : {}),
-                        ...(updatedBy ? { docMeta: { touch: true, updatedBy } } : {}),
-                    };
-                }
-                expectedCurrentPlan ??= currentPlan;
-                return {
-                    doc: {
-                        kind: "set-section",
-                        section: "Plan",
-                        text: nextPlan,
-                        requiredSections: config.tasks.doc.required_sections,
-                        expectedCurrentText: expectedCurrentPlan,
+                                }),
+                            ]
+                            : []),
+                        ...(updatedBy ? [touchTaskDocMetaIntent({ updatedBy })] : []),
+                    ],
+                    writeOptions: {
+                        expectedCurrentText: currentPlan,
+                        expectedSection: "Plan",
                     },
-                    ...(planChanged
-                        ? {
-                            task: {
-                                plan_approval: {
-                                    state: "pending",
-                                    updated_at: null,
-                                    updated_by: null,
-                                    note: null,
-                                },
-                            },
-                        }
-                        : {}),
-                    ...(updatedBy ? { docMeta: { updatedBy } } : {}),
                 };
-            });
-        }
-        else {
-            const existingDoc = (typeof task.doc === "string" ? task.doc : "") || (await backend.getTaskDoc(task.id));
-            const { planChanged, docChanged, nextDoc } = buildPlanDocUpdate({
-                currentDocRaw: existingDoc,
-                text,
-                requiredSections: config.tasks.doc.required_sections,
-            });
-            if (!planChanged && !docChanged && !updatedBy) {
-                process.stdout.write(`${readmePath}\n`);
-                return 0;
-            }
-            const nextTask = {
-                ...task,
-                doc: nextDoc,
-                ...(planChanged
-                    ? { plan_approval: { state: "pending", updated_at: null, updated_by: null, note: null } }
-                    : {}),
-                ...(updatedBy ? { doc_updated_by: updatedBy } : {}),
-            };
-            await backend.writeTask(nextTask);
-        }
+            },
+        });
         process.stdout.write(`${readmePath}\n`);
         return 0;
     }
@@ -218,11 +201,10 @@ export async function cmdTaskPlanSet(opts) {
 }
 export async function cmdTaskPlanApprove(opts) {
     try {
-        const { ctx, backend, task, useStore, store } = await loadPlanTask({
+        const { ctx, backend } = await loadPlanBackend({
             ctx: opts.ctx,
             cwd: opts.cwd,
             rootOverride: opts.rootOverride,
-            taskId: opts.taskId,
         });
         const config = ctx.config;
         const by = String(opts.by ?? "").trim();
@@ -235,22 +217,27 @@ export async function cmdTaskPlanApprove(opts) {
         }
         const note = typeof opts.note === "string" ? opts.note.trim() : "";
         const approvedAt = nowIso();
-        await (useStore
-            ? store.patch(opts.taskId, (current) => {
-                const currentDoc = ensureDocSections(String(current.doc ?? ""), config.tasks.doc.required_sections);
-                assertPlanCanBeApproved({ task: current, config, doc: currentDoc });
-                return {
-                    task: {
-                        plan_approval: {
-                            state: "approved",
-                            updated_at: approvedAt,
-                            updated_by: by,
-                            note: note || null,
+        await withTaskMutationStorage({
+            ctx,
+            local: async (store) => {
+                await store.get(opts.taskId);
+                await store.patch(opts.taskId, (current) => {
+                    const currentDoc = ensureDocSections(String(current.doc ?? ""), config.tasks.doc.required_sections);
+                    assertPlanCanBeApproved({ task: current, config, doc: currentDoc });
+                    return {
+                        task: {
+                            plan_approval: {
+                                state: "approved",
+                                updated_at: approvedAt,
+                                updated_by: by,
+                                note: note || null,
+                            },
                         },
-                    },
-                };
-            })
-            : (async () => {
+                    };
+                });
+            },
+            remote: async () => {
+                const task = await loadTaskFromContext({ ctx, taskId: opts.taskId });
                 const existingDoc = (typeof task.doc === "string" ? task.doc : "") || (await backend.getTaskDoc(task.id));
                 const baseDoc = ensureDocSections(existingDoc ?? "", config.tasks.doc.required_sections);
                 assertPlanCanBeApproved({ task, config, doc: baseDoc });
@@ -263,7 +250,8 @@ export async function cmdTaskPlanApprove(opts) {
                         note: note || null,
                     },
                 });
-            })());
+            },
+        });
         return 0;
     }
     catch (err) {
@@ -274,11 +262,10 @@ export async function cmdTaskPlanApprove(opts) {
 }
 export async function cmdTaskPlanReject(opts) {
     try {
-        const { ctx, backend, task, useStore, store } = await loadPlanTask({
+        const { ctx, backend } = await loadPlanBackend({
             ctx: opts.ctx,
             cwd: opts.cwd,
             rootOverride: opts.rootOverride,
-            taskId: opts.taskId,
         });
         const config = ctx.config;
         const by = String(opts.by ?? "").trim();
@@ -298,22 +285,27 @@ export async function cmdTaskPlanReject(opts) {
             });
         }
         const rejectedAt = nowIso();
-        await (useStore
-            ? store.patch(opts.taskId, (current) => {
-                const currentDoc = ensureDocSections(String(current.doc ?? ""), config.tasks.doc.required_sections);
-                assertPlanSectionPresent(current.id, currentDoc, "reject");
-                return {
-                    task: {
-                        plan_approval: {
-                            state: "rejected",
-                            updated_at: rejectedAt,
-                            updated_by: by,
-                            note: note || null,
+        await withTaskMutationStorage({
+            ctx,
+            local: async (store) => {
+                await store.get(opts.taskId);
+                await store.patch(opts.taskId, (current) => {
+                    const currentDoc = ensureDocSections(String(current.doc ?? ""), config.tasks.doc.required_sections);
+                    assertPlanSectionPresent(current.id, currentDoc, "reject");
+                    return {
+                        task: {
+                            plan_approval: {
+                                state: "rejected",
+                                updated_at: rejectedAt,
+                                updated_by: by,
+                                note: note || null,
+                            },
                         },
-                    },
-                };
-            })
-            : (async () => {
+                    };
+                });
+            },
+            remote: async () => {
+                const task = await loadTaskFromContext({ ctx, taskId: opts.taskId });
                 const existingDoc = (typeof task.doc === "string" ? task.doc : "") || (await backend.getTaskDoc(task.id));
                 const baseDoc = ensureDocSections(existingDoc ?? "", config.tasks.doc.required_sections);
                 assertPlanSectionPresent(task.id, baseDoc, "reject");
@@ -326,7 +318,8 @@ export async function cmdTaskPlanReject(opts) {
                         note: note || null,
                     },
                 });
-            })());
+            },
+        });
         return 0;
     }
     catch (err) {

package/dist/commands/task/reclaim.command.d.ts

@@ -0,0 +1,11 @@
+import type { CommandCtx, CommandSpec } from "../../cli/spec/spec.js";
+export type TaskReclaimParsed = {
+    taskId: string;
+    author: string;
+    reason: string;
+    force: boolean;
+    json: boolean;
+};
+export declare const taskReclaimSpec: CommandSpec<TaskReclaimParsed>;
+export declare const runTaskReclaim: (ctx: CommandCtx, parsed: TaskReclaimParsed) => Promise<number>;
+//# sourceMappingURL=reclaim.command.d.ts.map

package/dist/commands/task/reclaim.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reclaim.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/reclaim.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAQtE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,iBAAiB,CAiD1D,CAAC;AAIF,eAAO,MAAM,cAAc,GAAU,KAAK,UAAU,EAAE,QAAQ,iBAAiB,oBA+C9E,CAAC"}

package/dist/commands/task/reclaim.command.js

@@ -0,0 +1,102 @@
+import { usageError } from "../../cli/spec/errors.js";
+import { createCliEmitter, infoMessage } from "../../cli/output.js";
+import { buildRecordedTaskHandoff, buildTaskResumeContext } from "./handoff.shared.js";
+import { resolveTaskHandoffPaths, writeTaskHandoff } from "../shared/task-handoff.js";
+export const taskReclaimSpec = {
+    id: ["task", "reclaim"],
+    group: "Task",
+    summary: "Claim an interrupted task and persist a recovery handoff snapshot.",
+    args: [{ name: "task-id", required: true, valueHint: "<task-id>" }],
+    options: [
+        {
+            kind: "string",
+            name: "author",
+            valueHint: "<role>",
+            description: "Role reclaiming the task.",
+        },
+        {
+            kind: "string",
+            name: "reason",
+            valueHint: "<text>",
+            description: "Why the task is being reclaimed.",
+        },
+        {
+            kind: "boolean",
+            name: "force",
+            default: false,
+            description: "Allow reclaim even when the latest run still appears alive.",
+        },
+        {
+            kind: "boolean",
+            name: "json",
+            default: false,
+            description: "Emit the persisted reclaim handoff as JSON.",
+        },
+    ],
+    validateRaw: (raw) => {
+        for (const key of ["author", "reason"]) {
+            const value = raw.opts[key];
+            if (typeof value !== "string" || value.trim() === "") {
+                throw usageError({
+                    spec: taskReclaimSpec,
+                    message: `Missing required option: --${key}.`,
+                });
+            }
+        }
+    },
+    parse: (raw) => ({
+        taskId: String(raw.args["task-id"]),
+        author: String(raw.opts.author),
+        reason: String(raw.opts.reason),
+        force: raw.opts.force === true,
+        json: raw.opts.json === true,
+    }),
+};
+const emitter = createCliEmitter();
+export const runTaskReclaim = async (ctx, parsed) => {
+    const resume = await buildTaskResumeContext({
+        cwd: ctx.cwd,
+        rootOverride: ctx.rootOverride ?? null,
+        task_id: parsed.taskId,
+    });
+    if (resume.runner.next_action === "wait" && !parsed.force) {
+        throw usageError({
+            spec: taskReclaimSpec,
+            message: `Refusing to reclaim ${parsed.taskId}: the latest runner still appears alive. ` +
+                `Use --force only if the handoff really is orphaned.`,
+        });
+    }
+    const built = await buildRecordedTaskHandoff({
+        cwd: ctx.cwd,
+        rootOverride: ctx.rootOverride ?? null,
+        task_id: parsed.taskId,
+        from_role: resume.latest_handoff?.to_role ?? resume.latest_handoff?.from_role ?? "UNASSIGNED",
+        to_role: parsed.author,
+        reason: parsed.reason,
+        next_actions: [
+            `Reclaim by ${parsed.author}: follow runner_next_action=${resume.runner.next_action ?? "none"}.`,
+        ],
+    });
+    const paths = resolveTaskHandoffPaths({
+        git_root: built.ctx.resolvedProject.gitRoot,
+        workflow_dir: built.ctx.config.paths.workflow_dir,
+        task_id: parsed.taskId,
+    });
+    await writeTaskHandoff({ paths, handoff: built.handoff });
+    if (parsed.json) {
+        emitter.json(built.handoff);
+        return 0;
+    }
+    const entries = [
+        { label: "author", value: parsed.author },
+        { label: "runner_next_action", value: built.handoff.runner?.next_action ?? "none" },
+    ];
+    if (built.handoff.runner?.next_command) {
+        entries.push({ label: "runner_next_command", value: built.handoff.runner.next_command });
+    }
+    entries.push({ label: "latest", value: paths.latest_path });
+    emitter.report(entries, {
+        header: infoMessage(`task reclaimed: ${parsed.taskId}`),
+    });
+    return 0;
+};

package/dist/commands/task/resume-context.command.d.ts

@@ -0,0 +1,9 @@
+import type { CommandCtx, CommandSpec } from "../../cli/spec/spec.js";
+export type TaskResumeContextParsed = {
+    taskId: string;
+    runId?: string;
+    json: boolean;
+};
+export declare const taskResumeContextSpec: CommandSpec<TaskResumeContextParsed>;
+export declare const runTaskResumeContext: (ctx: CommandCtx, parsed: TaskResumeContextParsed) => Promise<number>;
+//# sourceMappingURL=resume-context.command.d.ts.map

package/dist/commands/task/resume-context.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume-context.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/resume-context.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAKtE,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,uBAAuB,CAqBtE,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAU,KAAK,UAAU,EAAE,QAAQ,uBAAuB,oBAiC1F,CAAC"}

package/dist/commands/task/resume-context.command.js

@@ -0,0 +1,60 @@
+import { infoMessage } from "../../cli/output.js";
+import { buildTaskResumeContext } from "./handoff.shared.js";
+export const taskResumeContextSpec = {
+    id: ["task", "resume-context"],
+    group: "Task",
+    summary: "Print deterministic recovery context for continuing a task after interruption.",
+    args: [
+        { name: "task-id", required: true, valueHint: "<task-id>" },
+        { name: "run-id", required: false, valueHint: "[run-id]" },
+    ],
+    options: [
+        {
+            kind: "boolean",
+            name: "json",
+            default: false,
+            description: "Emit machine-readable resume context JSON.",
+        },
+    ],
+    parse: (raw) => ({
+        taskId: String(raw.args["task-id"]),
+        runId: typeof raw.args["run-id"] === "string" ? raw.args["run-id"] : undefined,
+        json: raw.opts.json === true,
+    }),
+};
+export const runTaskResumeContext = async (ctx, parsed) => {
+    const resume = await buildTaskResumeContext({
+        cwd: ctx.cwd,
+        rootOverride: ctx.rootOverride ?? null,
+        task_id: parsed.taskId,
+        run_id: parsed.runId,
+    });
+    if (parsed.json) {
+        process.stdout.write(`${JSON.stringify(resume, null, 2)}\n`);
+        return 0;
+    }
+    process.stdout.write(`${infoMessage(`task resume-context: ${parsed.taskId}`)}\n`);
+    process.stdout.write(`task_status: ${resume.task_status}\n`);
+    process.stdout.write(`branch: ${resume.branch ?? "<unknown>"}\n`);
+    process.stdout.write(`base_branch: ${resume.base_branch ?? "<unknown>"}\n`);
+    process.stdout.write(`head_sha: ${resume.head_sha ?? "<unknown>"}\n`);
+    if (resume.pr_branch)
+        process.stdout.write(`pr_branch: ${resume.pr_branch}\n`);
+    process.stdout.write(`runner_status: ${resume.runner.status ?? "none"}\n`);
+    process.stdout.write(`runner_next_action: ${resume.runner.next_action ?? "none"}\n`);
+    if (resume.runner.next_command)
+        process.stdout.write(`runner_next_command: ${resume.runner.next_command}\n`);
+    if (resume.runner.resume_command)
+        process.stdout.write(`runner_resume_command: ${resume.runner.resume_command}\n`);
+    if (resume.runner.retry_command)
+        process.stdout.write(`runner_retry_command: ${resume.runner.retry_command}\n`);
+    if (resume.latest_handoff) {
+        process.stdout.write(`handoff_from: ${resume.latest_handoff.from_role}\n`);
+        process.stdout.write(`handoff_to: ${resume.latest_handoff.to_role ?? "unassigned"}\n`);
+        process.stdout.write(`handoff_reason: ${resume.latest_handoff.reason}\n`);
+    }
+    else {
+        process.stdout.write("handoff: none\n");
+    }
+    return 0;
+};

package/dist/commands/task/run-cancel.command.d.ts

@@ -0,0 +1,6 @@
+import type { CommandHandler } from "../../cli/spec/spec.js";
+import type { TaskRunCancelParsed } from "./run-cancel.spec.js";
+export { taskRunCancelSpec } from "./run-cancel.spec.js";
+export type { TaskRunCancelParsed } from "./run-cancel.spec.js";
+export declare const runTaskRunCancel: CommandHandler<TaskRunCancelParsed>;
+//# sourceMappingURL=run-cancel.command.d.ts.map

package/dist/commands/task/run-cancel.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-cancel.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/run-cancel.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,cAAc,EAAE,MAAM,wBAAwB,CAAC;AASzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAIhE,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,mBAAmB,CAsChE,CAAC"}

package/dist/commands/task/run-cancel.command.js

@@ -0,0 +1,45 @@
+import { mapBackendError } from "../../cli/error-map.js";
+import { createCliEmitter, infoMessage } from "../../cli/output.js";
+import { loadCommandContext } from "../shared/task-backend.js";
+import { CliError } from "../../shared/errors.js";
+import { cancelTaskRunnerExecution } from "../../runner/usecases/task-run-lifecycle.js";
+export { taskRunCancelSpec } from "./run-cancel.spec.js";
+const emitter = createCliEmitter();
+export const runTaskRunCancel = async (ctx, parsed) => {
+    try {
+        const commandCtx = await loadCommandContext({
+            cwd: ctx.cwd,
+            rootOverride: ctx.rootOverride ?? null,
+        });
+        const cancelled = await cancelTaskRunnerExecution({
+            ctx: commandCtx,
+            cwd: ctx.cwd,
+            rootOverride: ctx.rootOverride ?? null,
+            task_id: parsed.taskId,
+            run_id: parsed.runId,
+        });
+        const entries = [
+            { label: "run_id", value: parsed.runId },
+            { label: "previous_status", value: cancelled.previous_status },
+            { label: "state", value: cancelled.invocation.state_path },
+            { label: "events", value: cancelled.invocation.events_path },
+            { label: "status", value: cancelled.state.status },
+        ];
+        if (!cancelled.changed) {
+            entries.push({ label: "note", value: "run was already cancelled" });
+        }
+        emitter.report(entries, {
+            header: infoMessage(`task run cancelled: ${parsed.taskId}`),
+        });
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapBackendError(err, {
+            command: "task run cancel",
+            task_id: parsed.taskId,
+            run_id: parsed.runId,
+        });
+    }
+};

package/dist/commands/task/run-cancel.spec.d.ts

@@ -0,0 +1,7 @@
+import type { CommandSpec } from "../../cli/spec/spec.js";
+export type TaskRunCancelParsed = {
+    taskId: string;
+    runId: string;
+};
+export declare const taskRunCancelSpec: CommandSpec<TaskRunCancelParsed>;
+//# sourceMappingURL=run-cancel.spec.d.ts.map

package/dist/commands/task/run-cancel.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-cancel.spec.d.ts","sourceRoot":"","sources":["../../../src/commands/task/run-cancel.spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,MAAM,MAAM,mBAAmB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,mBAAmB,CAoB9D,CAAC"}

package/dist/commands/task/run-cancel.spec.js

@@ -0,0 +1,20 @@
+export const taskRunCancelSpec = {
+    id: ["task", "run", "cancel"],
+    group: "Task",
+    summary: "Cancel an existing runner run and stop the supervised process when present.",
+    description: "Loads an existing runner run from its artifacts, sends a termination signal to a live supervised process when one is recorded, and persists the resulting cancelled state for later resume or retry decisions.",
+    args: [
+        { name: "task-id", required: true, valueHint: "<task-id>" },
+        { name: "run-id", required: true, valueHint: "<run-id>" },
+    ],
+    examples: [
+        {
+            cmd: "agentplane task run cancel 202602030608-F1Q8AB run_20260323_abc123",
+            why: "Cancel a prepared run or send a termination signal to a live supervised run.",
+        },
+    ],
+    parse: (raw) => ({
+        taskId: String(raw.args["task-id"]),
+        runId: String(raw.args["run-id"]),
+    }),
+};

package/dist/commands/task/run-resume.command.d.ts

@@ -0,0 +1,6 @@
+import type { CommandHandler } from "../../cli/spec/spec.js";
+import type { TaskRunResumeParsed } from "./run-resume.spec.js";
+export { taskRunResumeSpec } from "./run-resume.spec.js";
+export type { TaskRunResumeParsed } from "./run-resume.spec.js";
+export declare const runTaskRunResume: CommandHandler<TaskRunResumeParsed>;
+//# sourceMappingURL=run-resume.command.d.ts.map

package/dist/commands/task/run-resume.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-resume.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/run-resume.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAUzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAIhE,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,mBAAmB,CA+ChE,CAAC"}