agentplane 0.3.6 → 0.3.8

package/dist/runner/run-repository.js

@@ -0,0 +1,222 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { CliError } from "../shared/errors.js";
+import { appendRunnerEvent, readRunnerRunState, writePreparedRunnerArtifacts, writeRunnerRunState, } from "./artifacts.js";
+import { resolveTaskRunnerPaths } from "./task-run-paths.js";
+import { readTraceArtifactText } from "./trace-artifacts.js";
+function parseTimestamp(value) {
+    const parsed = typeof value === "string" ? Date.parse(value) : Number.NaN;
+    return Number.isNaN(parsed) ? Number.NEGATIVE_INFINITY : parsed;
+}
+export function parseRunnerEventsText(text) {
+    return text
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .flatMap((line) => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+async function readOptionalJson(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+async function readRequiredText(opts) {
+    try {
+        return await readFile(opts.file_path, "utf8");
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT") {
+            throw new CliError({
+                exitCode: 4,
+                code: "E_IO",
+                message: `Runner artifact not found for ${opts.task_id}:${opts.run_id} ` +
+                    `(${opts.artifact_label} at ${opts.file_path})`,
+            });
+        }
+        throw err;
+    }
+}
+export function assertRunnerBundleMatchesTask(bundle, taskId, runId) {
+    const bundleTaskId = bundle.task?.task_id ??
+        (bundle.target.kind === "task" ? bundle.target.task_id : (bundle.target.task_id ?? null));
+    if (bundle.execution.run_id !== runId) {
+        throw new CliError({
+            exitCode: 4,
+            code: "E_IO",
+            message: `Runner bundle/run mismatch for ${taskId}:${runId} (bundle.run_id=${bundle.execution.run_id})`,
+        });
+    }
+    if (!bundleTaskId || bundleTaskId !== taskId) {
+        throw new CliError({
+            exitCode: 4,
+            code: "E_IO",
+            message: `Runner bundle/task mismatch for ${taskId}:${runId}`,
+        });
+    }
+}
+export class RunnerRunRepository {
+    paths;
+    constructor(paths) {
+        this.paths = paths;
+    }
+    static forTaskRun(opts) {
+        return new RunnerRunRepository(resolveTaskRunnerPaths({
+            git_root: opts.git_root,
+            workflow_dir: opts.workflow_dir,
+            task_id: opts.task_id,
+            run_id: opts.run_id,
+        }));
+    }
+    static fromBundle(bundle) {
+        return new RunnerRunRepository(bundle.execution.artifact_paths);
+    }
+    static fromInvocation(invocation) {
+        return new RunnerRunRepository({
+            run_dir: invocation.run_dir,
+            bundle_path: invocation.bundle_path,
+            bootstrap_path: invocation.bootstrap_path ?? "",
+            state_path: invocation.state_path,
+            events_path: invocation.events_path,
+            result_path: invocation.result_path,
+            trace_path: invocation.trace_path,
+            stderr_path: invocation.stderr_path,
+        });
+    }
+    async writePrepared(opts) {
+        return await writePreparedRunnerArtifacts(opts);
+    }
+    async readBundle() {
+        return await readOptionalJson(this.paths.bundle_path);
+    }
+    async readState() {
+        return await readRunnerRunState(this.paths.state_path);
+    }
+    async readRecord() {
+        const [bundle, state] = await Promise.all([this.readBundle(), this.readState()]);
+        if (!bundle || !state)
+            return null;
+        return {
+            bundle,
+            state,
+            result: state.result ?? null,
+        };
+    }
+    async readRequiredRecord(opts) {
+        const record = await this.readRecord();
+        if (!record) {
+            throw new CliError({
+                exitCode: 4,
+                code: "E_IO",
+                message: `Runner artifact not found for ${opts.task_id}:${opts.run_id}`,
+            });
+        }
+        assertRunnerBundleMatchesTask(record.bundle, opts.task_id, opts.run_id);
+        return record;
+    }
+    async writeState(state) {
+        await writeRunnerRunState({
+            state_path: this.paths.state_path,
+            state,
+        });
+    }
+    async appendEvent(event) {
+        await appendRunnerEvent({
+            events_path: this.paths.events_path,
+            event,
+        });
+    }
+    async readEventsTextRequired(opts) {
+        return await readRequiredText({
+            file_path: this.paths.events_path,
+            task_id: opts.task_id,
+            run_id: opts.run_id,
+            artifact_label: "events",
+        });
+    }
+    async readEventsRequired(opts) {
+        const events_text = await this.readEventsTextRequired(opts);
+        return {
+            events_text,
+            events: parseRunnerEventsText(events_text),
+        };
+    }
+    async readTraceTextRequired(opts) {
+        try {
+            return await readTraceArtifactText(this.paths.trace_path);
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code === "ENOENT") {
+                throw new CliError({
+                    exitCode: 4,
+                    code: "E_IO",
+                    message: `Runner artifact not found for ${opts.task_id}:${opts.run_id} ` +
+                        `(trace at ${this.paths.trace_path} or ${this.paths.trace_path}.gz)`,
+                });
+            }
+            throw err;
+        }
+    }
+}
+export async function resolveLatestRunnerRunId(opts) {
+    const runsDir = path.join(opts.git_root, opts.workflow_dir, opts.task_id, "runs");
+    let entries = [];
+    try {
+        const runEntries = await readdir(runsDir, { withFileTypes: true });
+        entries = runEntries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT") {
+            throw new CliError({
+                exitCode: 4,
+                code: "E_IO",
+                message: `No runner runs found for task ${opts.task_id}`,
+            });
+        }
+        throw err;
+    }
+    const candidates = await Promise.all(entries.map(async (runId) => {
+        const repository = RunnerRunRepository.forTaskRun({
+            git_root: opts.git_root,
+            workflow_dir: opts.workflow_dir,
+            task_id: opts.task_id,
+            run_id: runId,
+        });
+        const state = await repository.readState();
+        if (!state)
+            return null;
+        return {
+            run_id: runId,
+            updated_at: parseTimestamp(state.updated_at),
+            created_at: parseTimestamp(state.created_at),
+        };
+    }));
+    const latest = candidates
+        .filter((entry) => entry !== null)
+        .toSorted((left, right) => right.updated_at - left.updated_at ||
+        right.created_at - left.created_at ||
+        right.run_id.localeCompare(left.run_id))[0];
+    if (!latest) {
+        throw new CliError({
+            exitCode: 4,
+            code: "E_IO",
+            message: `No runner runs found for task ${opts.task_id}`,
+        });
+    }
+    return latest.run_id;
+}

package/dist/runner/task-run-paths.d.ts

@@ -0,0 +1,19 @@
+import type { RunnerArtifactPaths } from "./types.js";
+export declare const RUNNER_BUNDLE_FILENAME = "bundle.json";
+export declare const RUNNER_BOOTSTRAP_FILENAME = "bootstrap.md";
+export declare const RUNNER_STATE_FILENAME = "run-state.json";
+export declare const RUNNER_EVENTS_FILENAME = "events.jsonl";
+export declare const RUNNER_RESULT_FILENAME = "result.json";
+export declare const RUNNER_TRACE_FILENAME = "agent-trace.jsonl";
+export declare const RUNNER_STDERR_FILENAME = "stderr.log";
+export type TaskRunnerPaths = RunnerArtifactPaths & {
+    task_dir: string;
+    runs_dir: string;
+};
+export declare function resolveTaskRunnerPaths(opts: {
+    git_root: string;
+    workflow_dir: string;
+    task_id: string;
+    run_id: string;
+}): TaskRunnerPaths;
+//# sourceMappingURL=task-run-paths.d.ts.map

package/dist/runner/task-run-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-run-paths.d.ts","sourceRoot":"","sources":["../../src/runner/task-run-paths.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AACpD,eAAO,MAAM,yBAAyB,iBAAiB,CAAC;AACxD,eAAO,MAAM,qBAAqB,mBAAmB,CAAC;AACtD,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AACrD,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AACpD,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AACzD,eAAO,MAAM,sBAAsB,eAAe,CAAC;AAEnD,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,eAAe,CAgBlB"}

package/dist/runner/task-run-paths.js

@@ -0,0 +1,25 @@
+import path from "node:path";
+export const RUNNER_BUNDLE_FILENAME = "bundle.json";
+export const RUNNER_BOOTSTRAP_FILENAME = "bootstrap.md";
+export const RUNNER_STATE_FILENAME = "run-state.json";
+export const RUNNER_EVENTS_FILENAME = "events.jsonl";
+export const RUNNER_RESULT_FILENAME = "result.json";
+export const RUNNER_TRACE_FILENAME = "agent-trace.jsonl";
+export const RUNNER_STDERR_FILENAME = "stderr.log";
+export function resolveTaskRunnerPaths(opts) {
+    const task_dir = path.join(opts.git_root, opts.workflow_dir, opts.task_id);
+    const runs_dir = path.join(task_dir, "runs");
+    const run_dir = path.join(runs_dir, opts.run_id);
+    return {
+        task_dir,
+        runs_dir,
+        run_dir,
+        bundle_path: path.join(run_dir, RUNNER_BUNDLE_FILENAME),
+        bootstrap_path: path.join(run_dir, RUNNER_BOOTSTRAP_FILENAME),
+        state_path: path.join(run_dir, RUNNER_STATE_FILENAME),
+        events_path: path.join(run_dir, RUNNER_EVENTS_FILENAME),
+        result_path: path.join(run_dir, RUNNER_RESULT_FILENAME),
+        trace_path: path.join(run_dir, RUNNER_TRACE_FILENAME),
+        stderr_path: path.join(run_dir, RUNNER_STDERR_FILENAME),
+    };
+}

package/dist/runner/task-state.d.ts

@@ -0,0 +1,9 @@
+import { type CommandContext } from "../commands/shared/task-backend.js";
+import type { RunnerContextBundle, RunnerRunState } from "./types.js";
+export declare function persistRunnerOutcomeToTask(opts: {
+    ctx: CommandContext;
+    task_id: string;
+    state: RunnerRunState;
+    bundle?: RunnerContextBundle;
+}): Promise<void>;
+//# sourceMappingURL=task-state.d.ts.map

package/dist/runner/task-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-state.d.ts","sourceRoot":"","sources":["../../src/runner/task-state.ts"],"names":[],"mappings":"AAQA,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAgB9F,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAgB,MAAM,YAAY,CAAC;AAgTpF,wBAAsB,0BAA0B,CAAC,IAAI,EAAE;IACrD,GAAG,EAAE,cAAc,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CA8FhB"}

package/dist/runner/task-state.js

@@ -0,0 +1,354 @@
+import { ensureDocSections, setMarkdownSection } from "@agentplaneorg/core";
+import { backendNotSupportedMessage } from "../cli/output.js";
+import { loadTaskFromContext } from "../commands/shared/task-backend.js";
+import { backendIsLocalFileBackend, getTaskStore, setTaskFieldsIntent, setTaskSectionIntent, touchTaskDocMetaIntent, } from "../commands/shared/task-store.js";
+import { extractDocSection, normalizeTaskDocVersion, resolveWritableDocSections, taskObservationSectionName, } from "../commands/task/shared.js";
+import { CliError } from "../shared/errors.js";
+const RUNNER_OUTCOME_BEGIN = "<!-- BEGIN RUNNER OUTCOME -->";
+const RUNNER_OUTCOME_END = "<!-- END RUNNER OUTCOME -->";
+const MAX_TASK_RUNNER_HISTORY = 5;
+function formatRunnerTarget(target) {
+    if (target.kind === "task")
+        return `task ${target.task_id}`;
+    const base = `recipe ${target.recipe_id}:${target.scenario_id}`;
+    return target.task_id ? `${base} -> task ${target.task_id}` : base;
+}
+function normalizeRunnerOutcomeSection(sectionText) {
+    const normalized = (sectionText ?? "").replaceAll("\r\n", "\n").trimEnd();
+    if (!normalized)
+        return [RUNNER_OUTCOME_BEGIN, RUNNER_OUTCOME_END].join("\n");
+    const hasBegin = normalized.includes(RUNNER_OUTCOME_BEGIN);
+    const hasEnd = normalized.includes(RUNNER_OUTCOME_END);
+    if (hasBegin && hasEnd)
+        return normalized;
+    return [normalized, "", RUNNER_OUTCOME_BEGIN, RUNNER_OUTCOME_END].join("\n");
+}
+function replaceRunnerOutcomeSection(sectionText, entryText) {
+    const normalized = normalizeRunnerOutcomeSection(sectionText);
+    const beginIdx = normalized.indexOf(RUNNER_OUTCOME_BEGIN);
+    const endIdx = normalized.indexOf(RUNNER_OUTCOME_END);
+    if (beginIdx === -1 || endIdx === -1 || endIdx <= beginIdx) {
+        throw new Error("Runner outcome markers are malformed");
+    }
+    const beforeBegin = normalized.slice(0, beginIdx).trimEnd();
+    const afterEnd = normalized.slice(endIdx + RUNNER_OUTCOME_END.length).trimStart();
+    const parts = [];
+    if (beforeBegin)
+        parts.push(beforeBegin, "");
+    parts.push(RUNNER_OUTCOME_BEGIN);
+    if (entryText.trim())
+        parts.push("", entryText.trimEnd());
+    parts.push("", RUNNER_OUTCOME_END);
+    if (afterEnd)
+        parts.push("", afterEnd);
+    return parts.join("\n").trimEnd();
+}
+function runArtifactsDirForTask(taskId, runId) {
+    return `.agentplane/tasks/${taskId}/runs/${runId}`;
+}
+function formatRunnerAdapterLabel(adapterId) {
+    const normalized = adapterId.trim();
+    if (!normalized)
+        return "Runner";
+    return normalized.slice(0, 1).toUpperCase() + normalized.slice(1);
+}
+function renderTaskRunnerSummary(opts) {
+    const adapter = formatRunnerAdapterLabel(opts.adapter_id);
+    if (opts.status === "prepared")
+        return `${adapter} runner is prepared.`;
+    if (opts.status === "running")
+        return `${adapter} runner is running.`;
+    if (opts.status === "success")
+        return `${adapter} runner completed successfully.`;
+    if (opts.status === "cancelled")
+        return `${adapter} runner was cancelled.`;
+    return `${adapter} runner failed; inspect run artifacts for details.`;
+}
+function stripRunnerHistory(outcome) {
+    return {
+        run_id: outcome.run_id,
+        status: outcome.status,
+        adapter_id: outcome.adapter_id,
+        mode: outcome.mode,
+        updated_at: outcome.updated_at,
+        ...(outcome.started_at ? { started_at: outcome.started_at } : {}),
+        ...(outcome.ended_at ? { ended_at: outcome.ended_at } : {}),
+        exit_code: outcome.exit_code,
+        target: { ...outcome.target },
+        ...(outcome.summary ? { summary: outcome.summary } : {}),
+        ...(outcome.output_paths?.length ? { output_paths: [...outcome.output_paths] } : {}),
+        ...(outcome.metrics ? { metrics: { ...outcome.metrics } } : {}),
+        ...(outcome.evidence ? { evidence: { ...outcome.evidence } } : {}),
+    };
+}
+function runnerHistoryFromTask(outcome) {
+    if (!outcome)
+        return [];
+    if (outcome.history?.length)
+        return outcome.history.map((entry) => stripRunnerHistory(entry));
+    return [stripRunnerHistory(outcome)];
+}
+function renderRunnerMetrics(metrics) {
+    if (!metrics)
+        return null;
+    const pairs = [];
+    if (typeof metrics.duration_ms === "number")
+        pairs.push(`duration_ms=${metrics.duration_ms}`);
+    if (typeof metrics.stdout_bytes === "number")
+        pairs.push(`stdout_bytes=${metrics.stdout_bytes}`);
+    if (typeof metrics.stderr_bytes === "number")
+        pairs.push(`stderr_bytes=${metrics.stderr_bytes}`);
+    if (metrics.output_last_message_bytes === null ||
+        typeof metrics.output_last_message_bytes === "number") {
+        pairs.push(`output_last_message_bytes=${metrics.output_last_message_bytes ?? "null"}`);
+    }
+    return pairs.length > 0 ? pairs.join(", ") : null;
+}
+function renderVerificationHint(status) {
+    if (status === "success") {
+        return "runner completed successfully; human verification and closure remain explicit lifecycle steps.";
+    }
+    if (status === "failed") {
+        return "runner failed; inspect artifacts before retrying or recording verification evidence.";
+    }
+    if (status === "cancelled") {
+        return "runner was cancelled; verification evidence is incomplete until a later run succeeds.";
+    }
+    if (status === "running") {
+        return "runner is still executing; verification evidence is not complete yet.";
+    }
+    return "runner is prepared but has not produced verification-relevant output yet.";
+}
+function renderRunnerEvidence(evidence) {
+    if (!evidence)
+        return [];
+    const lines = [];
+    if (evidence.evidence_paths?.length) {
+        lines.push(`EvidencePaths: ${evidence.evidence_paths.join(", ")}`);
+    }
+    if (evidence.changed_paths?.length) {
+        lines.push(`ChangedPaths: ${evidence.changed_paths.join(", ")}`);
+    }
+    if (typeof evidence.files_changed_count === "number") {
+        lines.push(`FilesChangedCount: ${evidence.files_changed_count}`);
+    }
+    if (evidence.tests_run?.length) {
+        lines.push(`TestsRun: ${evidence.tests_run.join(" | ")}`);
+    }
+    if (evidence.verification_candidates?.length) {
+        lines.push(`VerificationCandidates: ${evidence.verification_candidates.join(" | ")}`);
+    }
+    return lines;
+}
+function renderRunnerOutcomeEntry(opts) {
+    const summary = opts.entry.summary ??
+        renderTaskRunnerSummary({
+            adapter_id: opts.entry.adapter_id,
+            status: opts.entry.status,
+        });
+    const capabilitiesUsed = opts.projection?.result?.capabilities_used;
+    const entryOutputPaths = opts.entry.output_paths;
+    const entryMetrics = opts.entry.metrics;
+    const entryEvidence = opts.entry.evidence;
+    const lines = [
+        `#### ${opts.entry.updated_at} — RUNNER — ${opts.entry.status}`,
+        "",
+        `RunId: ${opts.entry.run_id}`,
+        "",
+        `Adapter: ${opts.entry.adapter_id}`,
+        "",
+        `Mode: ${opts.entry.mode}`,
+        "",
+        `Target: ${formatRunnerTarget(opts.entry.target)}`,
+        "",
+        `UpdatedAt: ${opts.entry.updated_at}`,
+        "",
+        `RunArtifacts: ${runArtifactsDirForTask(opts.task_id, opts.entry.run_id)}`,
+        "",
+        `ExitCode: ${opts.entry.exit_code ?? "null"}`,
+    ];
+    if (opts.entry.started_at) {
+        lines.push("", `StartedAt: ${opts.entry.started_at}`);
+    }
+    if (opts.entry.ended_at) {
+        lines.push("", `EndedAt: ${opts.entry.ended_at}`);
+    }
+    if (summary) {
+        lines.push("", `Summary: ${summary}`);
+    }
+    if (opts.projection?.result?.artifacts?.length) {
+        lines.push("", `Artifacts: ${opts.projection.result.artifacts
+            .map((artifact) => (artifact.label ? `${artifact.label}=${artifact.path}` : artifact.path))
+            .join(", ")}`);
+    }
+    if (!opts.projection?.result?.artifacts?.length && entryOutputPaths?.length) {
+        lines.push("", `Outputs: ${entryOutputPaths.join(", ")}`);
+    }
+    if (capabilitiesUsed?.length) {
+        lines.push("", `Capabilities: ${capabilitiesUsed.join(", ")}`);
+    }
+    const metrics = renderRunnerMetrics(entryMetrics);
+    if (metrics) {
+        lines.push("", `Metrics: ${metrics}`);
+    }
+    const evidenceLines = renderRunnerEvidence(entryEvidence);
+    if (evidenceLines.length > 0) {
+        lines.push("", ...evidenceLines);
+    }
+    lines.push("", `VerificationHint: ${renderVerificationHint(opts.entry.status)}`);
+    return `${lines.join("\n").trimEnd()}\n`;
+}
+function buildTaskRunnerHistoryEntry(projection) {
+    const { state, result } = projection;
+    const outcome = {
+        run_id: state.run_id,
+        status: state.status,
+        adapter_id: state.adapter_id,
+        mode: state.mode,
+        updated_at: state.updated_at,
+        exit_code: state.result?.exit_code ?? null,
+        target: { ...state.target },
+    };
+    if (result?.started_at)
+        outcome.started_at = result.started_at;
+    if (result?.ended_at)
+        outcome.ended_at = result.ended_at;
+    outcome.summary = renderTaskRunnerSummary({
+        adapter_id: state.adapter_id,
+        status: state.status,
+    });
+    if (result?.output_paths?.length)
+        outcome.output_paths = [...result.output_paths];
+    if (result?.metrics)
+        outcome.metrics = { ...result.metrics };
+    if (result?.evidence)
+        outcome.evidence = { ...result.evidence };
+    return outcome;
+}
+function mergeTaskRunnerHistory(opts) {
+    const merged = [];
+    const seen = new Set();
+    for (const entry of [opts.latest, ...runnerHistoryFromTask(opts.previous)]) {
+        if (seen.has(entry.run_id))
+            continue;
+        seen.add(entry.run_id);
+        merged.push(stripRunnerHistory(entry));
+        if (merged.length >= MAX_TASK_RUNNER_HISTORY)
+            break;
+    }
+    return merged;
+}
+function buildTaskRunnerOutcome(opts) {
+    const latest = buildTaskRunnerHistoryEntry(opts.projection);
+    const history = mergeTaskRunnerHistory({ latest, previous: opts.previous });
+    return history.length > 1 ? { ...latest, history } : latest;
+}
+function renderRunnerOutcomeHistory(opts) {
+    const history = opts.outcome.history?.length
+        ? opts.outcome.history
+        : [stripRunnerHistory(opts.outcome)];
+    const [latest, ...previous] = history;
+    return [
+        renderRunnerOutcomeEntry({
+            task_id: opts.task_id,
+            entry: latest,
+            projection: opts.projection,
+        }),
+        ...previous.map((entry) => renderRunnerOutcomeEntry({ task_id: opts.task_id, entry })),
+    ]
+        .join("\n")
+        .trimEnd();
+}
+function resolveRunnerUpdatedBy(task) {
+    const owner = typeof task.owner === "string" ? task.owner.trim() : "";
+    if (owner)
+        return owner;
+    const docUpdatedBy = typeof task.doc_updated_by === "string" ? task.doc_updated_by.trim() : "";
+    if (docUpdatedBy)
+        return docUpdatedBy;
+    return "agentplane";
+}
+export async function persistRunnerOutcomeToTask(opts) {
+    if (opts.bundle?.execution.mode === "dry_run" || opts.state.mode === "dry_run")
+        return;
+    const backend = opts.ctx.taskBackend;
+    if (!backend.writeTask) {
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: backendNotSupportedMessage("task writes"),
+        });
+    }
+    const useStore = backendIsLocalFileBackend(opts.ctx);
+    if (useStore) {
+        const store = getTaskStore(opts.ctx);
+        await store.mutate(opts.task_id, (current) => {
+            const projection = {
+                state: opts.state,
+                result: opts.state.result ?? null,
+            };
+            const outcome = buildTaskRunnerOutcome({
+                projection,
+                previous: current.runner ?? null,
+            });
+            const docVersion = normalizeTaskDocVersion(current.doc_version);
+            const observationSection = taskObservationSectionName(docVersion);
+            const writableSections = resolveWritableDocSections({
+                allowedSections: opts.ctx.config.tasks.doc.sections,
+                requiredSections: opts.ctx.config.tasks.doc.required_sections,
+                targetSection: observationSection,
+            });
+            const baseDoc = ensureDocSections(String(current.doc ?? ""), writableSections);
+            const currentObservation = extractDocSection(baseDoc, observationSection);
+            const nextObservation = replaceRunnerOutcomeSection(currentObservation, renderRunnerOutcomeHistory({
+                task_id: opts.task_id,
+                outcome,
+                projection,
+            }));
+            return [
+                setTaskFieldsIntent({ runner: outcome }),
+                setTaskSectionIntent({
+                    section: observationSection,
+                    text: nextObservation,
+                    requiredSections: writableSections,
+                }),
+                touchTaskDocMetaIntent({
+                    updatedBy: resolveRunnerUpdatedBy(current),
+                    version: docVersion,
+                }),
+            ];
+        });
+        return;
+    }
+    const task = await loadTaskFromContext({ ctx: opts.ctx, taskId: opts.task_id });
+    const projection = {
+        state: opts.state,
+        result: opts.state.result ?? null,
+    };
+    const outcome = buildTaskRunnerOutcome({
+        projection,
+        previous: task.runner ?? null,
+    });
+    const writableSections = resolveWritableDocSections({
+        allowedSections: opts.ctx.config.tasks.doc.sections,
+        requiredSections: opts.ctx.config.tasks.doc.required_sections,
+        targetSection: taskObservationSectionName(normalizeTaskDocVersion(task.doc_version)),
+    });
+    const baseDoc = ensureDocSections(String(task.doc ?? ""), writableSections);
+    const docVersion = normalizeTaskDocVersion(task.doc_version);
+    const observationSection = taskObservationSectionName(docVersion);
+    const currentObservation = extractDocSection(baseDoc, observationSection);
+    const nextObservation = replaceRunnerOutcomeSection(currentObservation, renderRunnerOutcomeHistory({
+        task_id: opts.task_id,
+        outcome,
+        projection,
+    }));
+    const nextDoc = ensureDocSections(setMarkdownSection(baseDoc, observationSection, nextObservation), writableSections);
+    await backend.writeTask({
+        ...task,
+        runner: outcome,
+        doc: nextDoc,
+        doc_updated_at: opts.state.updated_at,
+        doc_updated_by: resolveRunnerUpdatedBy(task),
+    });
+}

package/dist/runner/test-helpers.d.ts

@@ -0,0 +1,30 @@
+import type { RunnerContextBundle } from "./types.js";
+type MakeRunnerContextBundleOptions = {
+    adapterId?: string;
+    taskId?: string;
+    runId?: string;
+    gitRoot?: string;
+    workflowDir?: string;
+    title?: string;
+    description?: string;
+    status?: string;
+    owner?: string;
+    priority?: string;
+    tags?: string[];
+    mode?: RunnerContextBundle["execution"]["mode"];
+    doc?: string;
+    sections?: Record<string, string>;
+    basePrompts?: RunnerContextBundle["base_prompts"];
+    target?: RunnerContextBundle["target"];
+    recipe?: RunnerContextBundle["recipe"];
+    repository?: Partial<RunnerContextBundle["repository"]>;
+    task?: Partial<RunnerContextBundle["task"]>;
+    execution?: Partial<Omit<RunnerContextBundle["execution"], "artifact_paths">> & {
+        artifact_paths?: Partial<RunnerContextBundle["execution"]["artifact_paths"]>;
+    };
+};
+export declare function setRunnerBundleRunDir(bundle: RunnerContextBundle, runDir: string): void;
+export declare function makeRunnerContextBundle(opts?: MakeRunnerContextBundleOptions): RunnerContextBundle;
+export declare function writeRunnerExecutable(root: string, commandName: string, content: string | readonly string[]): Promise<string>;
+export {};
+//# sourceMappingURL=test-helpers.d.ts.map

package/dist/runner/test-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["../../src/runner/test-helpers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAItD,KAAK,8BAA8B,GAAG;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,WAAW,CAAC,EAAE,mBAAmB,CAAC,cAAc,CAAC,CAAC;IAClD,MAAM,CAAC,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,YAAY,CAAC,CAAC,CAAC;IACxD,IAAI,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5C,SAAS,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC,CAAC,GAAG;QAC9E,cAAc,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC;KAC9E,CAAC;CACH,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CASvF;AAED,wBAAgB,uBAAuB,CACrC,IAAI,GAAE,8BAAmC,GACxC,mBAAmB,CA8ErB;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAClC,OAAO,CAAC,MAAM,CAAC,CAEjB"}