agentplane 0.3.7 → 0.3.9

package/dist/commands/task/handoff-record.command.js

@@ -0,0 +1,140 @@
+import { usageError } from "../../cli/spec/errors.js";
+import { createCliEmitter, infoMessage } from "../../cli/output.js";
+import { buildRecordedTaskHandoff } from "./handoff.shared.js";
+import { resolveTaskHandoffPaths, writeTaskHandoff } from "../shared/task-handoff.js";
+export const taskHandoffRecordSpec = {
+    id: ["task", "handoff", "record"],
+    group: "Task",
+    summary: "Record a task handoff snapshot with runner recovery hints.",
+    args: [{ name: "task-id", required: true, valueHint: "<task-id>" }],
+    options: [
+        {
+            kind: "string",
+            name: "from",
+            valueHint: "<role>",
+            description: "Role handing off the task.",
+        },
+        {
+            kind: "string",
+            name: "to",
+            valueHint: "<role>",
+            description: "Optional. Intended receiving role.",
+        },
+        {
+            kind: "string",
+            name: "reason",
+            valueHint: "<text>",
+            description: "Why the handoff is happening.",
+        },
+        {
+            kind: "string",
+            name: "note",
+            valueHint: "<text>",
+            description: "Optional. Free-form handoff note.",
+        },
+        {
+            kind: "string",
+            name: "run-id",
+            valueHint: "<run-id>",
+            description: "Optional. Pin handoff hints to a specific runner run.",
+        },
+        {
+            kind: "string",
+            name: "next-action",
+            valueHint: "<text>",
+            repeatable: true,
+            description: "Repeatable. Human next actions for the receiving agent.",
+        },
+        {
+            kind: "string",
+            name: "risk",
+            valueHint: "<text>",
+            repeatable: true,
+            description: "Repeatable. Risks or watch-outs that remain open.",
+        },
+        {
+            kind: "string",
+            name: "question",
+            valueHint: "<text>",
+            repeatable: true,
+            description: "Repeatable. Open questions for the next agent.",
+        },
+        {
+            kind: "string",
+            name: "evidence-path",
+            valueHint: "<path>",
+            repeatable: true,
+            description: "Repeatable. Relevant evidence or artifact paths.",
+        },
+        {
+            kind: "boolean",
+            name: "json",
+            default: false,
+            description: "Emit the persisted handoff snapshot as JSON.",
+        },
+    ],
+    validateRaw: (raw) => {
+        for (const key of ["from", "reason"]) {
+            const value = raw.opts[key];
+            if (typeof value !== "string" || value.trim() === "") {
+                throw usageError({
+                    spec: taskHandoffRecordSpec,
+                    message: `Missing required option: --${key}.`,
+                });
+            }
+        }
+    },
+    parse: (raw) => ({
+        taskId: String(raw.args["task-id"]),
+        fromRole: String(raw.opts.from),
+        toRole: typeof raw.opts.to === "string" ? raw.opts.to : undefined,
+        reason: String(raw.opts.reason),
+        note: typeof raw.opts.note === "string" ? raw.opts.note : undefined,
+        runId: typeof raw.opts["run-id"] === "string" ? raw.opts["run-id"] : undefined,
+        nextActions: raw.opts["next-action"] ?? [],
+        risks: raw.opts.risk ?? [],
+        openQuestions: raw.opts.question ?? [],
+        evidencePaths: raw.opts["evidence-path"] ?? [],
+        json: raw.opts.json === true,
+    }),
+};
+const emitter = createCliEmitter();
+export const runTaskHandoffRecord = async (ctx, parsed) => {
+    const built = await buildRecordedTaskHandoff({
+        cwd: ctx.cwd,
+        rootOverride: ctx.rootOverride ?? null,
+        task_id: parsed.taskId,
+        from_role: parsed.fromRole,
+        to_role: parsed.toRole,
+        reason: parsed.reason,
+        note: parsed.note,
+        run_id: parsed.runId,
+        next_actions: parsed.nextActions,
+        risks: parsed.risks,
+        open_questions: parsed.openQuestions,
+        evidence_paths: parsed.evidencePaths,
+    });
+    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: "from", value: built.handoff.from_role },
+        { label: "to", value: built.handoff.to_role ?? "unassigned" },
+        { label: "reason", value: built.handoff.reason },
+    ];
+    if (built.handoff.runner?.run_id) {
+        entries.push({ label: "run_id", value: built.handoff.runner.run_id }, { label: "runner_status", value: built.handoff.runner.status ?? "unknown" }, { label: "runner_next_action", value: built.handoff.runner.next_action ?? "none" });
+    }
+    entries.push({ label: "latest", value: paths.latest_path });
+    emitter.report(entries, {
+        header: infoMessage(`task handoff recorded: ${parsed.taskId}`),
+    });
+    return 0;
+};

package/dist/commands/task/handoff-show.command.d.ts

@@ -0,0 +1,8 @@
+import type { CommandCtx, CommandSpec } from "../../cli/spec/spec.js";
+export type TaskHandoffShowParsed = {
+    taskId: string;
+    json: boolean;
+};
+export declare const taskHandoffShowSpec: CommandSpec<TaskHandoffShowParsed>;
+export declare const runTaskHandoffShow: (ctx: CommandCtx, parsed: TaskHandoffShowParsed) => Promise<number>;
+//# sourceMappingURL=handoff-show.command.d.ts.map

package/dist/commands/task/handoff-show.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-show.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/handoff-show.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAOtE,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,qBAAqB,CAiBlE,CAAC;AAIF,eAAO,MAAM,kBAAkB,GAAU,KAAK,UAAU,EAAE,QAAQ,qBAAqB,oBAsDtF,CAAC"}

package/dist/commands/task/handoff-show.command.js

@@ -0,0 +1,77 @@
+import { createCliEmitter, infoMessage } from "../../cli/output.js";
+import { loadCommandContext } from "../shared/task-backend.js";
+import { readTaskHandoffLatestRequired, resolveTaskHandoffPaths } from "../shared/task-handoff.js";
+export const taskHandoffShowSpec = {
+    id: ["task", "handoff", "show"],
+    group: "Task",
+    summary: "Show the latest persisted task handoff snapshot.",
+    args: [{ name: "task-id", required: true, valueHint: "<task-id>" }],
+    options: [
+        {
+            kind: "boolean",
+            name: "json",
+            default: false,
+            description: "Emit machine-readable handoff JSON.",
+        },
+    ],
+    parse: (raw) => ({
+        taskId: String(raw.args["task-id"]),
+        json: raw.opts.json === true,
+    }),
+};
+const emitter = createCliEmitter();
+export const runTaskHandoffShow = async (ctx, parsed) => {
+    const commandCtx = await loadCommandContext({
+        cwd: ctx.cwd,
+        rootOverride: ctx.rootOverride ?? null,
+    });
+    const paths = resolveTaskHandoffPaths({
+        git_root: commandCtx.resolvedProject.gitRoot,
+        workflow_dir: commandCtx.config.paths.workflow_dir,
+        task_id: parsed.taskId,
+    });
+    const handoff = await readTaskHandoffLatestRequired({
+        task_id: parsed.taskId,
+        paths,
+    });
+    if (parsed.json) {
+        emitter.json(handoff);
+        return 0;
+    }
+    const entries = [
+        { label: "from", value: handoff.from_role },
+        { label: "to", value: handoff.to_role ?? "unassigned" },
+        { label: "created_at", value: handoff.created_at },
+        { label: "reason", value: handoff.reason },
+    ];
+    if (handoff.branch)
+        entries.push({ label: "branch", value: handoff.branch });
+    if (handoff.base_branch)
+        entries.push({ label: "base_branch", value: handoff.base_branch });
+    if (handoff.head_sha)
+        entries.push({ label: "head_sha", value: handoff.head_sha });
+    if (handoff.pr_branch)
+        entries.push({ label: "pr_branch", value: handoff.pr_branch });
+    if (handoff.runner?.run_id) {
+        entries.push({ label: "run_id", value: handoff.runner.run_id }, { label: "runner_status", value: handoff.runner.status ?? "unknown" }, { label: "runner_next_action", value: handoff.runner.next_action ?? "none" });
+        if (handoff.runner.next_command) {
+            entries.push({ label: "runner_next_command", value: handoff.runner.next_command });
+        }
+    }
+    for (const action of handoff.next_actions ?? []) {
+        entries.push({ label: "next_action", value: action });
+    }
+    for (const risk of handoff.risks ?? []) {
+        entries.push({ label: "risk", value: risk });
+    }
+    for (const question of handoff.open_questions ?? []) {
+        entries.push({ label: "open_question", value: question });
+    }
+    for (const evidence of handoff.evidence_paths ?? []) {
+        entries.push({ label: "evidence_path", value: evidence });
+    }
+    emitter.report(entries, {
+        header: infoMessage(`task handoff show: ${parsed.taskId}`),
+    });
+    return 0;
+};

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

@@ -0,0 +1,7 @@
+import type { CommandCtx, CommandSpec } from "../../cli/spec/spec.js";
+export type TaskHandoffParsed = {
+    subcommand?: string;
+};
+export declare const taskHandoffSpec: CommandSpec<TaskHandoffParsed>;
+export declare function runTaskHandoff(_ctx: CommandCtx, p: TaskHandoffParsed): Promise<number>;
+//# sourceMappingURL=handoff.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/handoff.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGtE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,iBAAiB,CAY1D,CAAC;AAEF,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5F"}

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

@@ -0,0 +1,21 @@
+import { loadDirectSubcommandNames, throwGroupCommandUsage } from "../../cli/group-command.js";
+export const taskHandoffSpec = {
+    id: ["task", "handoff"],
+    group: "Task",
+    summary: "Task handoff commands (record/show).",
+    synopsis: [
+        "agentplane task handoff record <task-id> --from <role> --reason <text> [--to <role>] [--run-id <id>]",
+        "agentplane task handoff show <task-id> [--json]",
+    ],
+    args: [{ name: "subcommand", required: false, valueHint: "<record|show>" }],
+    parse: (raw) => ({
+        subcommand: typeof raw.args.subcommand === "string" ? raw.args.subcommand : undefined,
+    }),
+};
+export async function runTaskHandoff(_ctx, p) {
+    throwGroupCommandUsage({
+        spec: taskHandoffSpec,
+        cmd: p.subcommand ? [p.subcommand] : [],
+        subcommands: await loadDirectSubcommandNames(["task", "handoff"]),
+    });
+}

package/dist/commands/task/handoff.shared.d.ts

@@ -0,0 +1,39 @@
+import { type CommandContext } from "../shared/task-backend.js";
+import { type TaskHandoffArtifact, type TaskHandoffRunnerHint } from "../shared/task-handoff.js";
+export type TaskResumeContext = {
+    task_id: string;
+    task_status: string;
+    branch: string | null;
+    base_branch: string | null;
+    head_sha: string | null;
+    workspace_root: string;
+    pr_branch: string | null;
+    latest_handoff: TaskHandoffArtifact | null;
+    runner: TaskHandoffRunnerHint;
+};
+export declare function buildTaskResumeContext(opts: {
+    ctx?: CommandContext;
+    cwd: string;
+    rootOverride?: string | null;
+    task_id: string;
+    run_id?: string;
+}): Promise<TaskResumeContext>;
+export declare function buildRecordedTaskHandoff(opts: {
+    ctx?: CommandContext;
+    cwd: string;
+    rootOverride?: string | null;
+    task_id: string;
+    from_role: string;
+    to_role?: string | null;
+    reason: string;
+    note?: string;
+    next_actions?: string[];
+    risks?: string[];
+    open_questions?: string[];
+    evidence_paths?: string[];
+    run_id?: string;
+}): Promise<{
+    ctx: CommandContext;
+    handoff: TaskHandoffArtifact;
+}>;
+//# sourceMappingURL=handoff.shared.d.ts.map

package/dist/commands/task/handoff.shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.shared.d.ts","sourceRoot":"","sources":["../../../src/commands/task/handoff.shared.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAOL,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC3B,MAAM,2BAA2B,CAAC;AAKnC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC3C,MAAM,EAAE,qBAAqB,CAAC;CAC/B,CAAC;AAaF,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAsF7B;AAED,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAiCjE"}

package/dist/commands/task/handoff.shared.js

@@ -0,0 +1,134 @@
+import { resolveBaseBranch } from "@agentplaneorg/core";
+import { loadCommandContext, loadTaskFromContext, } from "../shared/task-backend.js";
+import { buildRunnerHintCommands, buildTaskHandoffArtifact, currentGitBranch, readTaskHandoffLatest, readTaskPrMetaSummary, resolveTaskHandoffPaths, } from "../shared/task-handoff.js";
+import { isProcessAlive } from "../../runner/process-supervision.js";
+import { loadTaskRunnerInspection } from "../../runner/usecases/task-run-inspect.js";
+import { CliError } from "../../shared/errors.js";
+function taskStatus(task) {
+    return String(task.status || "TODO")
+        .trim()
+        .toUpperCase();
+}
+function nullIfCliIo(err) {
+    if (err instanceof CliError && err.code === "E_IO")
+        return null;
+    throw err;
+}
+export async function buildTaskResumeContext(opts) {
+    const ctx = opts.ctx ??
+        (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+    const task = await loadTaskFromContext({ ctx, taskId: opts.task_id });
+    const handoffPaths = resolveTaskHandoffPaths({
+        git_root: ctx.resolvedProject.gitRoot,
+        workflow_dir: ctx.config.paths.workflow_dir,
+        task_id: opts.task_id,
+    });
+    const [branch, latest_handoff, prMeta] = await Promise.all([
+        currentGitBranch(ctx.resolvedProject.gitRoot),
+        readTaskHandoffLatest(handoffPaths),
+        readTaskPrMetaSummary({ ctx, task_id: opts.task_id }),
+    ]);
+    const head_sha = await ctx.git.headCommit().catch(() => null);
+    const base_branch = prMeta.base ??
+        (await resolveBaseBranch({
+            cwd: ctx.resolvedProject.gitRoot,
+            rootOverride: ctx.resolvedProject.gitRoot,
+            mode: ctx.config.workflow_mode,
+        }).catch(() => null));
+    let runner;
+    try {
+        const inspection = await loadTaskRunnerInspection({
+            ctx,
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride ?? null,
+            task_id: opts.task_id,
+            run_id: opts.run_id,
+        });
+        const commands = buildRunnerHintCommands({
+            task_id: opts.task_id,
+            run_id: inspection.run_id,
+            status: inspection.state.status,
+        });
+        runner = {
+            run_id: inspection.run_id,
+            status: inspection.state.status,
+            heartbeat_at: inspection.state.supervision?.heartbeat_at ?? null,
+            state_path: inspection.paths.state_path,
+            trace_path: inspection.paths.trace_path,
+            ...commands,
+        };
+        if (inspection.state.status === "running") {
+            const pid = inspection.state.supervision?.pid;
+            if (typeof pid === "number") {
+                const alive = isProcessAlive(pid);
+                runner.next_action = alive ? "wait" : "cancel_then_resume";
+                runner.next_command = alive
+                    ? null
+                    : `agentplane task run cancel ${opts.task_id} ${inspection.run_id} && agentplane task run resume ${opts.task_id} ${inspection.run_id}`;
+            }
+            else {
+                runner.next_action = "cancel_then_resume";
+                runner.next_command = `agentplane task run cancel ${opts.task_id} ${inspection.run_id} && agentplane task run resume ${opts.task_id} ${inspection.run_id}`;
+            }
+        }
+    }
+    catch (err) {
+        const noRun = nullIfCliIo(err);
+        runner = {
+            run_id: null,
+            status: null,
+            heartbeat_at: null,
+            state_path: null,
+            trace_path: null,
+            ...buildRunnerHintCommands({
+                task_id: opts.task_id,
+                run_id: noRun,
+                status: null,
+            }),
+        };
+    }
+    return {
+        task_id: opts.task_id,
+        task_status: taskStatus(task),
+        branch,
+        base_branch,
+        head_sha,
+        workspace_root: ctx.resolvedProject.gitRoot,
+        pr_branch: prMeta.branch,
+        latest_handoff,
+        runner,
+    };
+}
+export async function buildRecordedTaskHandoff(opts) {
+    const ctx = opts.ctx ??
+        (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+    await loadTaskFromContext({ ctx, taskId: opts.task_id });
+    const resume = await buildTaskResumeContext({
+        ctx,
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride ?? null,
+        task_id: opts.task_id,
+        run_id: opts.run_id,
+    });
+    return {
+        ctx,
+        handoff: buildTaskHandoffArtifact({
+            task_id: opts.task_id,
+            created_at: new Date().toISOString(),
+            from_role: opts.from_role,
+            to_role: opts.to_role,
+            reason: opts.reason,
+            note: opts.note,
+            branch: resume.branch,
+            base_branch: resume.base_branch,
+            head_sha: resume.head_sha,
+            workspace_root: resume.workspace_root,
+            pr_branch: resume.pr_branch,
+            runner: resume.runner,
+            next_actions: opts.next_actions,
+            risks: opts.risks,
+            open_questions: opts.open_questions,
+            evidence_paths: opts.evidence_paths,
+        }),
+    };
+}

package/dist/commands/task/hosted-close.command.d.ts

@@ -0,0 +1,9 @@
+import type { CommandCtx, CommandSpec } from "../../cli/spec/spec.js";
+import { type CommandContext } from "../shared/task-backend.js";
+export type TaskHostedCloseParsed = {
+    eventJson: string;
+    quiet: boolean;
+};
+export declare const taskHostedCloseSpec: CommandSpec<TaskHostedCloseParsed>;
+export declare function makeRunTaskHostedCloseHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, parsed: TaskHostedCloseParsed) => Promise<number>;
+//# sourceMappingURL=hosted-close.command.d.ts.map

package/dist/commands/task/hosted-close.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-close.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/hosted-close.command.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAStE,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAKrF,MAAM,MAAM,qBAAqB,GAAG;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,qBAAqB,CAqClE,CAAC;AAyIF,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IAC9E,KAAK,UAAU,EAAE,QAAQ,qBAAqB,KAAG,OAAO,CAAC,MAAM,CAAC,CA2B/E"}

package/dist/commands/task/hosted-close.command.js

@@ -0,0 +1,190 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { usageError } from "../../cli/spec/errors.js";
+import { infoMessage, successMessage } from "../../cli/output.js";
+import { mapBackendError } from "../../cli/error-map.js";
+import { fileExists } from "../../cli/fs-utils.js";
+import { CliError } from "../../shared/errors.js";
+import { writeJsonStableIfChanged } from "../../shared/write-if-changed.js";
+import { execFileAsync } from "../shared/git.js";
+import { buildIntegratedPrMeta, parsePrMeta } from "../shared/pr-meta.js";
+import { loadTaskFromContext } from "../shared/task-backend.js";
+import { createTaskCloseCommit, writeFinishedTasks } from "./finish-shared.js";
+import { resolveHostedMergeTargetFromEvent } from "./hosted-merge-sync.js";
+import { readCommitInfo } from "./shared.js";
+export const taskHostedCloseSpec = {
+    id: ["task", "hosted-close"],
+    group: "Task",
+    summary: "Close a branch_pr task on the current branch from a merged hosted PR event payload.",
+    options: [
+        {
+            kind: "string",
+            name: "event-json",
+            valueHint: "<path>",
+            description: "Path to the GitHub pull_request closed event payload.",
+        },
+        {
+            kind: "boolean",
+            name: "quiet",
+            default: false,
+            description: "Suppress normal output (still prints errors).",
+        },
+    ],
+    validateRaw: (raw) => {
+        const value = raw.opts["event-json"];
+        if (typeof value !== "string" || value.trim() === "") {
+            throw usageError({
+                spec: taskHostedCloseSpec,
+                message: "Missing required option: --event-json.",
+            });
+        }
+    },
+    examples: [
+        {
+            cmd: 'agentplane task hosted-close --event-json "$GITHUB_EVENT_PATH"',
+            why: "Apply the canonical branch_pr closure payload on an automation branch after a hosted PR merge.",
+        },
+    ],
+    parse: (raw) => ({
+        eventJson: String(raw.opts["event-json"]),
+        quiet: raw.opts.quiet === true,
+    }),
+};
+async function hasTaskArtifactChanges(opts) {
+    const { stdout } = await execFileAsync("git", ["status", "--short", "--", opts.taskDirRelative], {
+        cwd: opts.gitRoot,
+        env: process.env,
+    });
+    return stdout.trim().length > 0;
+}
+async function closeHostedTask(opts) {
+    const rawEvent = await readFile(opts.eventJson, "utf8");
+    const parsedEvent = JSON.parse(rawEvent);
+    const target = resolveHostedMergeTargetFromEvent({
+        event: parsedEvent,
+        branchPrefix: opts.ctx.config.branch.task_prefix,
+    });
+    if (!target?.mergedPr.mergeCommit?.oid) {
+        return { outcome: "noop", detail: "event is not a merged task PR" };
+    }
+    const gitRoot = opts.ctx.resolvedProject.gitRoot;
+    const taskDirRelative = path.join(opts.ctx.config.paths.workflow_dir, target.taskId);
+    const task = await loadTaskFromContext({ ctx: opts.ctx, taskId: target.taskId });
+    const metaPath = path.join(gitRoot, taskDirRelative, "pr", "meta.json");
+    if (!(await fileExists(metaPath))) {
+        throw new CliError({
+            exitCode: 3,
+            code: "E_VALIDATION",
+            message: `Hosted task closure could not find pr/meta.json for ${target.taskId}`,
+        });
+    }
+    const rawMeta = await readFile(metaPath, "utf8");
+    const meta = parsePrMeta(rawMeta, target.taskId);
+    const alreadyClosed = String(task.status || "TODO").toUpperCase() === "DONE" &&
+        (task.commit?.hash ?? "") === target.mergedPr.mergeCommit.oid &&
+        meta.status === "MERGED" &&
+        (meta.merge_commit ?? "") === target.mergedPr.mergeCommit.oid;
+    if (String(task.status || "TODO").toUpperCase() === "DONE" &&
+        (task.commit?.hash ?? "") !== "" &&
+        (task.commit?.hash ?? "") !== target.mergedPr.mergeCommit.oid) {
+        throw new CliError({
+            exitCode: 3,
+            code: "E_VALIDATION",
+            message: `Hosted task closure found a conflicting DONE commit for ${target.taskId}: ` +
+                `${task.commit?.hash} != ${target.mergedPr.mergeCommit.oid}`,
+        });
+    }
+    const nextMeta = buildIntegratedPrMeta({
+        meta,
+        branch: target.branch,
+        base: target.mergedPr.baseRefName ?? meta.base ?? "main",
+        mergeStrategy: meta.merge_strategy ?? "squash",
+        mergeHash: target.mergedPr.mergeCommit.oid,
+        branchHeadSha: target.mergedPr.headRefOid ?? meta.head_sha ?? target.mergedPr.mergeCommit.oid,
+        at: target.mergedPr.mergedAt ?? new Date().toISOString(),
+        verifyCommands: [],
+        shouldRunVerify: false,
+        alreadyVerifiedSha: null,
+    });
+    await writeJsonStableIfChanged(metaPath, nextMeta);
+    if (alreadyClosed) {
+        if (!(await hasTaskArtifactChanges({ gitRoot, taskDirRelative }))) {
+            return {
+                outcome: "noop",
+                detail: `${target.taskId} is already closed for merge ${target.mergedPr.mergeCommit.oid.slice(0, 12)}`,
+            };
+        }
+        await createTaskCloseCommit({
+            ctx: opts.ctx,
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride,
+            taskId: target.taskId,
+            baseBranchOverride: target.mergedPr.baseRefName ?? meta.base ?? "main",
+            quiet: opts.quiet,
+        });
+        return {
+            outcome: "meta-only",
+            taskId: target.taskId,
+            mergeHash: target.mergedPr.mergeCommit.oid,
+        };
+    }
+    const taskCommitInfo = await readCommitInfo(gitRoot, target.mergedPr.mergeCommit.oid);
+    const prLabel = `PR #${target.mergedPr.number}`;
+    const finishBody = `Verified: ${prLabel} merged on GitHub ${target.mergedPr.baseRefName ?? "main"}; ` +
+        "hosted closure automation recorded canonical task artifacts.";
+    await writeFinishedTasks({
+        ctx: opts.ctx,
+        loadedTasks: [{ taskId: target.taskId, task }],
+        metaTaskId: target.taskId,
+        author: "INTEGRATOR",
+        body: finishBody,
+        force: false,
+        resultProvided: true,
+        resultSummary: `Merged via ${prLabel}.`,
+        riskLevel: undefined,
+        breaking: false,
+        taskCommitInfo,
+    });
+    await createTaskCloseCommit({
+        ctx: opts.ctx,
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride,
+        taskId: target.taskId,
+        baseBranchOverride: target.mergedPr.baseRefName ?? meta.base ?? "main",
+        quiet: opts.quiet,
+    });
+    return {
+        outcome: "closed",
+        taskId: target.taskId,
+        mergeHash: target.mergedPr.mergeCommit.oid,
+    };
+}
+export function makeRunTaskHostedCloseHandler(getCtx) {
+    return async (ctx, parsed) => {
+        try {
+            const commandCtx = await getCtx("task hosted-close");
+            const outcome = await closeHostedTask({
+                ctx: commandCtx,
+                cwd: ctx.cwd,
+                rootOverride: ctx.rootOverride ?? undefined,
+                eventJson: parsed.eventJson,
+                quiet: parsed.quiet,
+            });
+            if (parsed.quiet)
+                return 0;
+            if (outcome.outcome === "noop") {
+                process.stdout.write(`${infoMessage(`hosted close skipped: ${outcome.detail}`)}\n`);
+                return 0;
+            }
+            const detail = `merge=${outcome.mergeHash.slice(0, 12)}`;
+            process.stdout.write(`${successMessage("task hosted close", outcome.taskId, detail)}\n`);
+            if (outcome.outcome === "meta-only") {
+                process.stdout.write(`${infoMessage("task was already DONE; committed only the missing hosted PR metadata")}\n`);
+            }
+            return 0;
+        }
+        catch (err) {
+            throw mapBackendError(err, { command: "task hosted-close", root: ctx.rootOverride ?? null });
+        }
+    };
+}