agents-relay 2.0.158 → 2.0.159

package/dist/cli-help.js

@@ -173,7 +173,7 @@ Required: --task-id ID and the normal Job storage options.`,
 Agent submit: agents-relay plan apply --repo OWNER/REPO --pr PR_NUMBER --id JOB_ID --plan-id PLAN_ID --execution-id EXECUTION_ID --file plan.json. Validation errors reject without partial task writes and can be corrected inside the same Planner execution.
 
 Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID.
-Optional: --prompt TEXT or --prompt-file PATH|- (mutually exclusive). The prompt is additional guidance for this planning round and never replaces the durable Job objective. --force-clean-history --clean-history-file PATH requires explicit {taskId,kind,targetTaskId,evidence,reason} records for every unclassified FAILED work Task; it applies graph-authorized classifications and creates the new Plan in one SQLite mutation. Unknown execution outcomes fail closed. Planner proposals must be committed with plan apply; final text is never applied as a Plan.
+Optional: --prompt TEXT or --prompt-file PATH|- (mutually exclusive). The prompt is additional guidance for this planning round and never replaces the durable Job objective. --force-clean-history asks Planner to inspect authoritative failed Tasks, decide whether evidence supports superseded/invalid classification or cancellation of a failed review, and apply selected changes through guarded task commands before submitting the Plan. Tasks without sufficient evidence remain unresolved. The durable Plan records the cleanup assessment, and plan apply remains the required receipt. Text responses are never applied as a Plan; unknown execution outcomes are not classified without proof.
 
 The command persists one real plan-N round, materializes validated next_tasks with planner provenance, and wakes normal reconciliation. It works for zero-task DRAFT Jobs. Historical planner-N rounds remain readable, but new rounds use plan-N.
 

package/dist/cli.js

@@ -24,7 +24,6 @@ import { AgentObjectivePlanner, CommandObjectivePlanner } from './planner.js';
 import { applyTaskHoldAction, applyTaskQueueAction, dispatchTaskAction } from './task-actions.js';
 import { applyJobActivateAction, applyJobCancelAction } from './job-actions.js';
 import { classifyFailedTask } from './task-actions.js';
-import { cleanHistoryOption } from './cli-plan-clean-history.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { startServiceExternalActionFlusher } from './service-external-actions.js';
 import { handleServicePublication } from './service-publication.js';
@@ -807,8 +806,7 @@ async function main() {
             throw new Error(`${command} requires --repo and --id`);
         if (command === 'plan') {
             const guidance = hasArg(args, '--prompt') || hasArg(args, '--prompt-file') ? await textOption(args, '--prompt', '--prompt-file') : undefined;
-            const cleanHistory = await cleanHistoryOption(args);
-            console.log(JSON.stringify(await relayControlCommand(args, { command: 'job.plan', jobId, ...(guidance?.trim() ? { guidance: guidance.trim() } : {}), ...(cleanHistory ? { cleanHistory } : {}) }), null, 2));
+            console.log(JSON.stringify(await relayControlCommand(args, { command: 'job.plan', jobId, ...(guidance?.trim() ? { guidance: guidance.trim() } : {}), forceCleanHistory: hasArg(args, '--force-clean-history') }), null, 2));
             return;
         }
         if (command === 'reconcile') {
@@ -834,11 +832,10 @@ async function main() {
     const { store, job, localFile } = loaded;
     if (command === 'plan') {
         const guidance = hasArg(args, '--prompt') || hasArg(args, '--prompt-file') ? await textOption(args, '--prompt', '--prompt-file') : undefined;
-        const cleanHistory = await cleanHistoryOption(args);
         await withEventBus(args, async (bus) => {
             const reconciler = runtime(store, args, bus);
             try {
-                const result = await reconciler.planJob(job.id, guidance?.trim() || undefined, cleanHistory);
+                const result = await reconciler.planJob(job.id, guidance?.trim() || undefined, hasArg(args, '--force-clean-history'));
                 await saveLocal(localFile, result.job);
                 await publishWake(bus, result.job, result.round.id, `Planning round ${result.round.id} completed`);
                 console.log(JSON.stringify(result.round, null, 2));

package/dist/manual-plan.js

@@ -1,8 +1,9 @@
 import { dispatchJobLifecycleSync } from './workflow/lifecycle.js';
 import { createPlanRound, pendingPlan } from './planner.js';
 import { applyJobActivateAction } from './job-actions.js';
-import { classifyTaskResolution } from './workflow/task-resolution.js';
-export async function executeManualPlan(store, jobId, guidance, timeoutMs, launchPlanner, cleanHistory) {
+export async function executeManualPlan(store, jobId, guidance, timeoutMs, launchPlanner, forceCleanHistory = false) {
+    if (forceCleanHistory && !store.mutateJob)
+        throw new Error('--force-clean-history requires atomic durable SQLite mutations');
     let job = await store.load(jobId);
     if (['COMPLETED', 'CANCELLED'].includes(job.state))
         throw new Error(`Cannot plan terminal job ${job.id} (${job.state})`);
@@ -19,23 +20,8 @@ export async function executeManualPlan(store, jobId, guidance, timeoutMs, launc
             if (current.pause)
                 throw new Error(`Cannot plan paused Job ${current.id}; resume it first`);
             const concurrent = pendingPlan(current);
-            if (cleanHistory) {
-                if (concurrent)
-                    throw new Error(`--force-clean-history requires no pending Plan (${concurrent.id})`);
-                const failed = current.tasks.filter(task => task.kind !== 'planner' && task.state === 'FAILED' && !task.resolutionClassification);
-                const provided = new Map(cleanHistory.map(item => [item.taskId, item]));
-                if (provided.size !== cleanHistory.length || failed.length !== provided.size || failed.some(task => !provided.has(task.id)))
-                    throw new Error('--force-clean-history requires exactly one explicit classification for every FAILED work Task');
-                for (const task of failed) {
-                    const item = provided.get(task.id);
-                    if (item.targetTaskId === task.id || !current.tasks.some(target => target.id === item.targetTaskId))
-                        throw new Error(`Classification for ${task.id} must target a different durable Task in this Job`);
-                    classifyTaskResolution(task, item);
-                }
-                const unknown = current.tasks.filter(task => task.kind !== 'planner' && task.state === 'FAILED' && task.failureReason === 'worker_outcome_unknown');
-                if (unknown.length)
-                    throw new Error(`--force-clean-history cannot proceed while FAILED Task execution outcomes are unknown: ${unknown.map(task => task.id).join(', ')}`);
-            }
+            if (forceCleanHistory && concurrent)
+                throw new Error(`--force-clean-history requires no pending Plan (${concurrent.id})`);
             if (concurrent) {
                 if (concurrent.executionId)
                     throw new Error(`Planning round ${concurrent.id} is already PLANNING`);
@@ -43,6 +29,10 @@ export async function executeManualPlan(store, jobId, guidance, timeoutMs, launc
             }
             else {
                 round = createPlanRound(current, { guidance, manual: true, timeoutMs });
+                if (forceCleanHistory) {
+                    round.forceCleanHistory = true;
+                    round.cleanHistoryTaskIds = current.tasks.filter(task => task.kind !== 'planner' && task.state === 'FAILED' && !task.resolutionClassification).map(task => task.id);
+                }
                 current.plans = [...(current.plans ?? []), structuredClone(round)].sort((a, b) => a.round - b.round);
             }
             if (current.state === 'DRAFT') {

package/dist/planner-history-cleanup.js

@@ -0,0 +1,33 @@
+function record(value, field) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`Planner ${field} must be an object`);
+    return value;
+}
+function requiredText(value, field) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        throw new Error(`Planner ${field} must be a non-empty string`);
+    return value;
+}
+export function parsePlannerHistoryCleanup(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new Error('Planner history_cleanup must be an array when provided');
+    const ids = new Set();
+    return value.map((item, index) => {
+        const row = record(item, `history_cleanup[${index}]`);
+        const taskId = requiredText(row.taskId, `history_cleanup[${index}].taskId`);
+        const outcome = row.outcome;
+        const evidence = requiredText(row.evidence, `history_cleanup[${index}].evidence`);
+        const reason = requiredText(row.reason, `history_cleanup[${index}].reason`);
+        if (!['superseded', 'invalid', 'cancelled_review', 'unresolved'].includes(String(outcome)))
+            throw new Error(`Planner history_cleanup[${index}].outcome is invalid`);
+        if (ids.has(taskId))
+            throw new Error(`Planner history_cleanup contains duplicate Task ${taskId}`);
+        ids.add(taskId);
+        const targetTaskId = row.targetTaskId === undefined ? undefined : requiredText(row.targetTaskId, `history_cleanup[${index}].targetTaskId`);
+        if ((outcome === 'superseded' || outcome === 'invalid') && !targetTaskId)
+            throw new Error(`Planner history_cleanup[${index}].targetTaskId is required for ${String(outcome)}`);
+        return { taskId, outcome: outcome, evidence, reason, ...(targetTaskId ? { targetTaskId } : {}) };
+    });
+}

package/dist/planner-runtime.js

@@ -136,6 +136,25 @@ export async function finishPlanner(ports, jobId, planId, executionId, error, ra
     let planCommitted = false;
     try {
         const parsed = parsePlannerResult(raw);
+        if (plan.forceCleanHistory) {
+            const cleanup = parsed.history_cleanup ?? [];
+            const expected = new Set(plan.cleanHistoryTaskIds ?? []);
+            if (cleanup.length !== expected.size || cleanup.some(item => !expected.delete(item.taskId)) || expected.size)
+                throw new Error('--force-clean-history requires exactly one Planner disposition for each failed Task in its durable snapshot');
+            for (const item of cleanup) {
+                const task = job.tasks.find(candidate => candidate.id === item.taskId);
+                if (!task)
+                    throw new Error(`Clean history Task ${item.taskId} disappeared`);
+                if (task.failureReason === 'worker_outcome_unknown' && item.outcome !== 'unresolved')
+                    throw new Error(`Unknown execution outcome for ${item.taskId} must remain unresolved without graph-verified proof`);
+                if ((item.outcome === 'superseded' || item.outcome === 'invalid') && (task.resolutionClassification?.kind !== item.outcome || task.resolutionClassification.targetTaskId !== item.targetTaskId || task.resolutionClassification.evidence !== item.evidence || task.resolutionClassification.reason !== item.reason))
+                    throw new Error(`Clean history classification for ${item.taskId} was not applied through task classify with matching evidence`);
+                if (item.outcome === 'cancelled_review' && (task.agentName !== 'reviewer' || task.state !== 'CANCELLED'))
+                    throw new Error(`Failed review ${item.taskId} must be cancelled through task cancel before Plan apply`);
+                if (item.outcome === 'unresolved' && (task.state !== 'FAILED' || task.resolutionClassification))
+                    throw new Error(`Unresolved history item ${item.taskId} changed after Planner assessment`);
+            }
+        }
         const result = assignPlannerTaskIds(parsed, job.repository, job.id, plan.id);
         const executionContext = await ports.plannerContext(job, plan);
         validatePlannerHierarchy(job.tasks, result.next_tasks);
@@ -334,7 +353,7 @@ export async function launchPlanExecution(ports, job, plan) {
     let promise;
     try {
         const executionContext = await ports.plannerContext(job, plan);
-        const context = { planExecution: { planId: plan.id, executionId }, job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: plan.previousPlanId, trigger: plan.trigger, executionContext, retryFeedback: plan.retryFeedback, guidance: plan.guidance };
+        const context = { planExecution: { planId: plan.id, executionId }, forceCleanHistory: plan.forceCleanHistory, cleanHistoryTaskIds: plan.cleanHistoryTaskIds, job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: plan.previousPlanId, trigger: plan.trigger, executionContext, retryFeedback: plan.retryFeedback, guidance: plan.guidance };
         promise = planner.plan(context, controller.signal);
     }
     catch (error) {

package/dist/planner-task-context.js

@@ -0,0 +1,26 @@
+function boundedText(value, max = 4000) {
+    if (value === null || value === undefined || value.length <= max)
+        return value;
+    return value.slice(0, max) + `\n...[truncated ${value.length - max} chars]`;
+}
+export function plannerTaskContext(task) {
+    return {
+        id: task.id,
+        title: task.title,
+        kind: task.kind ?? 'work',
+        parent_task_id: task.parentTaskId,
+        dependencies: task.dependencies,
+        state: task.state,
+        failure_reason: task.failureReason,
+        input: task.kind === 'planner' ? undefined : boundedText(task.input),
+        result_summary: boundedText(task.result?.summary),
+        result_evidence: task.result?.data ? boundedText(JSON.stringify(task.result.data), 2000) : undefined,
+        execution_history: task.executionHistory?.map(item => ({ id: item.id, attempt: item.attempt, started_at: item.startedAt })),
+        platform_failure: task.platformFailure ? { classification: task.platformFailure.classification, evidence: boundedText(task.platformFailure.evidence), safe_to_reroute: task.platformFailure.safeToReroute } : undefined,
+        comments: task.comments?.slice(-10).map(comment => ({ author: comment.author, text: boundedText(comment.text, 1000), created_at: comment.createdAt })),
+        resolution_classification: task.resolutionClassification,
+        error: boundedText(task.error, 2000),
+        blocked_baseline: task.blockedBaseline,
+        unblock: task.unblock,
+    };
+}

package/dist/planner.js

@@ -13,6 +13,8 @@ import { createTaskEntity } from './workflow/entity-creation.js';
 import { prepareReviewerThreadDelivery, chatgptThreadRequirements } from './reviewer-thread.js';
 import { spawnOwnedProcess } from './owned-process.js';
 import { requiredPlannerTaskTitle } from './planner-task-title.js';
+import { parsePlannerHistoryCleanup } from './planner-history-cleanup.js';
+import { plannerTaskContext } from './planner-task-context.js';
 export function semanticTaskTree(tasks) {
     const work = tasks.filter(task => task.kind !== 'planner');
     const ids = new Set(work.map(task => task.id));
@@ -268,6 +270,7 @@ export function parsePlannerResult(value) {
         unblockKeys.add(key);
         return { repository, prNumber: Number(prNumber), jobId, taskId, resolutionMode: resolutionMode };
     });
+    const history_cleanup = parsePlannerHistoryCleanup(root.history_cleanup);
     const ids = new Set();
     const next_tasks = root.next_tasks.map((item, index) => {
         const task = record(item, `next_tasks[${index}]`);
@@ -320,7 +323,7 @@ export function parsePlannerResult(value) {
             continuation: task.continuation, maxAttempts, timeoutMs, resolution: resolutionProposal(task.resolution, `next_tasks[${index}].resolution`)
         };
     });
-    return { objective_status: status, assessment: root.assessment, next_tasks, unblocks };
+    return { objective_status: status, assessment: root.assessment, next_tasks, unblocks, ...(history_cleanup ? { history_cleanup } : {}) };
 }
 export function validatePlannerProgress(job, result) {
     if (result.objective_status !== 'in_progress' || result.next_tasks.length > 0 || result.unblocks.length > 0)
@@ -420,6 +423,8 @@ export function plannerInput(context) {
         apply_cli: context.planExecution ? `agents-relay plan apply --repo ${context.job.repository} --pr ${context.job.prNumber} --id ${context.job.id} --plan-id ${context.planExecution.planId} --execution-id ${context.planExecution.executionId} --file PATH` : undefined,
         plan_execution: context.planExecution, retry_feedback: context.retryFeedback,
         caller_prompt: context.guidance,
+        force_clean_history: context.forceCleanHistory === true,
+        clean_history_task_ids: context.cleanHistoryTaskIds ?? [],
         previous_planner_task_id: context.previousPlannerTaskId,
         plan_trigger: context.trigger,
         legacy_change_cycle: context.job.changeCycle,
@@ -438,24 +443,11 @@ export function plannerInput(context) {
         })),
         project: project ? { name: project.name, path: project.path } : undefined,
         visible_agents: visibleAgents ?? [],
-        tasks: context.tasks.map(task => ({
-            id: task.id,
-            title: task.title,
-            kind: task.kind ?? 'work',
-            parent_task_id: task.parentTaskId,
-            state: task.state,
-            input: task.kind === 'planner' ? undefined : boundedText(task.input),
-            result_summary: boundedText(task.result?.summary),
-            planner_result: task.plannerResult ? {
+        tasks: context.tasks.map(task => ({ ...plannerTaskContext(task), planner_result: task.plannerResult ? {
                 objective_status: task.plannerResult.objective_status,
                 assessment: boundedText(task.plannerResult.assessment),
                 next_task_ids: task.plannerResult.next_tasks.map(item => item.id),
-            } : undefined,
-            resolution_classification: task.resolutionClassification,
-            error: boundedText(task.error, 2000),
-            blocked_baseline: task.blockedBaseline,
-            unblock: task.unblock,
-        })),
+            } : undefined })),
     });
 }
 export class CommandObjectivePlanner {

package/dist/reconciler.js

@@ -273,8 +273,8 @@ export class Reconciler extends ReconcilerReviewBase {
         }
         return this.store.load(jobId);
     }
-    async planJob(jobId, guidance, cleanHistory) {
-        return executeManualPlan(this.store, jobId, guidance, this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M'), (job, plan) => this.launchPlanner(job, plan), cleanHistory);
+    async planJob(jobId, guidance, forceCleanHistory = false) {
+        return executeManualPlan(this.store, jobId, guidance, this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M'), (job, plan) => this.launchPlanner(job, plan), forceCleanHistory);
     }
     async maybeCreatePlanner(job) {
         const pending = pendingPlan(job);

package/dist/relayd-control.js

@@ -109,8 +109,7 @@ export function createWorkspaceControl(deps) {
         if (command === 'job.plan') {
             const reconciler = makeReconciler(store, concurrency);
             try {
-                const cleanHistory = Array.isArray(body.cleanHistory) ? body.cleanHistory : undefined;
-                const planned = await reconciler.planJob(jobId, typeof body.guidance === 'string' && body.guidance.trim() ? body.guidance : undefined, cleanHistory);
+                const planned = await reconciler.planJob(jobId, typeof body.guidance === 'string' && body.guidance.trim() ? body.guidance : undefined, body.forceCleanHistory === true);
                 await pool.reconcileLocalJob(jobId, 'control.job.plan');
                 return planned.round;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.158",
+  "version": "2.0.159",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "repository": {
     "type": "git",

package/skills/agents-relay/agents/planner.agent.md

@@ -99,6 +99,12 @@ Do not create separate Tasks merely for "analyze", "format", "call tool", "check
 - **Resolution is mandatory for replacement work:** before returning any `next_tasks`, inspect every existing `FAILED` or `BLOCKED` work Task. If it lacks an active/waiting `resolution` or durable `resolutionClassification` and the proposed batch creates related/sibling work, explicitly cover it with a valid `resolution` on the new recovery Task. A superseded/invalid classification covers only planning validation; preserve the FAILED state and never infer success from the classification. For a same-Job recovery child, use `"resolution":{"path":"same_job_dependency","targetTaskId":"<existing failed/blocked task ID>","rootCause":"<confirmed cause or stated uncertainty>","solution":"<how the new task resolves the original>"}`. `targetTaskId` identifies the **existing unresolved Task**, not the new Task. Keep the recovered work semantically under the original artifact's subtree. Do not invent a resolution or silently cancel unrelated failed work.
 - **On `retry_feedback`:** treat the feedback as Relay's authoritative validation error for the previous output in this **same Plan**. Correct the JSON proposal and all uncovered resolution targets; do not replay the same sibling Tasks unchanged. Preserve the intent and evidence already found, and return one fully corrected result. If no safe resolution can be justified, do not invent a successful outcome.
 
+### Forced failed-history cleanup
+
+When `force_clean_history` is true, inspect every ID in `clean_history_task_ids` against the authoritative Task records and dependency/evidence context before planning. Do not infer a result from text alone. For a failed review that is demonstrably stale, run the existing guarded `agents-relay task cancel` command. For a failed work Task with evidence that replacement work covers it, run the existing guarded `agents-relay task classify --classification superseded`; for proven invalid work, use `--classification invalid`. Supply a different durable `--target-task-id`, and the same concrete `--evidence` and `--reason` in your report. Use the normal repository, PR, and Job options from this invocation. Never change task state directly or claim an action succeeded unless the CLI command succeeds and a fresh `task show` confirms it.
+
+If evidence is absent or execution outcome is unknown, leave the Task unresolved and do not classify it, cancel ordinary failed work, or claim success. Do not create related replacement work for an unresolved failure. After all selected guarded commands succeed, refresh authoritative Task state and submit the Plan through the standard `plan apply` command. Include exactly one `history_cleanup` entry for each `clean_history_task_ids` item: `{ "taskId", "outcome": "superseded"|"invalid"|"cancelled_review"|"unresolved", "evidence", "reason", "targetTaskId?" }`. For unresolved items, state what evidence is missing. Relay validates that reported mutations match durable SQLite state; an ordinary text response is never a Plan receipt.
+
 - Prefer independently verifiable Tasks with stable IDs, but do not split work solely to make Tasks smaller.
 - When a Task depends on mutable repository or product state, distinguish a frozen evidence target from the current execution head. A SHA may freeze that Task's own review/source evidence, but do not copy an upstream SHA into a dependent release, deploy, publication, or other follow-on Task unless the objective explicitly requires that same frozen target. After dependencies complete, downstream Tasks must resolve and verify the current durable Job/PR head before acting.
 - When fresh UI, browser, store, runtime, or visual evidence is material to the Task outcome, say so explicitly in the Task input and require evidence from the real current state. Existing screenshots, prepared assets, or prior observations are not substitutes for fresh evidence unless the objective explicitly allows reuse.
@@ -117,7 +123,7 @@ Do not create separate Tasks merely for "analyze", "format", "call tool", "check
 
 ## Output
 
-Return exactly one JSON object with `objective_status`, `assessment`, `next_tasks`, and optional top-level `unblocks`.
+Return exactly one JSON object with `objective_status`, `assessment`, `next_tasks`, and optional top-level `unblocks`. In forced cleanup mode, also return required `history_cleanup` as specified above.
 
 For `objective_status: "in_progress"`, `assessment` must be Markdown containing:
 

package/dist/cli-plan-clean-history.js

@@ -1,16 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { arg, hasArg } from './cli-support.js';
-export async function cleanHistoryOption(args) {
-    const force = hasArg([...args], '--force-clean-history');
-    const path = arg([...args], '--clean-history-file');
-    if (!force && path)
-        throw new Error('--clean-history-file requires --force-clean-history');
-    if (force && !path)
-        throw new Error('--force-clean-history requires --clean-history-file with one classification per FAILED Task');
-    if (!path)
-        return undefined;
-    const value = JSON.parse(await readFile(path, 'utf8'));
-    if (!Array.isArray(value) || value.some(item => !item || typeof item !== 'object' || Array.isArray(item)))
-        throw new Error('--clean-history-file must contain a JSON array of classification objects');
-    return value;
-}