agents-relay 1.0.126 → 1.0.127

package/README.md

@@ -56,12 +56,24 @@ The canonical Mermaid Graph Engine is the single authoritative Job/Task lifecycl
 Job objectives and Task inputs are Markdown. Prefer `--objective-file` / `--input-file` (use `-` for stdin) for durable long-form context; inline `--objective` / `--input` remain for short/simple text and are mutually exclusive with the file variants. When a diagram materially clarifies the work, put Mermaid first and then Markdown detail. A newly created Job must capture enough context to finish independently of the originating chat. Its PR body contains exactly one hidden `agents-relay:job:v1` metadata marker followed by the objective Markdown; there is no separate Job comment duplicating the objective. Objective and Job metadata updates rewrite that same PR body. Legacy Job-comment markers remain readable and are migrated into the PR body on the next Job save.
 
 Jobs default to `fixed`. `job create` persists only the durable job and never
-creates executable tasks. The top-level orchestrator decides whether the user's
-request should start immediately and, if so, creates the first task batch
-separately. Direct orchestrator-created tasks are persisted directly and are not wrapped in a synthetic Plan. A zero-task autonomous job remains idle;
-reconciliation does not invent its first planner. After an autonomous job has
-been explicitly started, later planning rounds may extend the work. Fixed jobs
-never grow another planning round.
+creates executable tasks. The caller can either create work directly with
+`task create` or invoke the Planner explicitly with `plan`. Direct
+orchestrator-created tasks are persisted directly and are not wrapped in a
+synthetic Plan. `agents-relay plan` works immediately on a zero-task DRAFT Job,
+activates it, persists a real `plan-N` planning round, and materializes validated
+`next_tasks`. Autonomous reconciliation still does not invent the first round
+for an untouched zero-task Job; after explicit work begins, later autonomous
+planning rounds reuse the same planning implementation. Fixed jobs never grow
+another planning round automatically.
+
+Manual planning syntax:
+
+~~~sh
+npx agents-relay plan --repo OWNER/REPO --pr 12 --id job-1 --prompt "Plan the implementation from the durable objective"
+npx agents-relay plan --repo OWNER/REPO --pr 12 --id job-1 --prompt-file guidance.md
+~~~
+
+The optional prompt is additional round guidance; it does not replace the durable Job objective. New planning rounds use `plan-N`; historical `planner-N` records remain readable.
 
 The durable status JSON and dashboard show the mode and planning provenance. An
 autonomous runtime uses the bundled `skills/agents-relay/agents/planner.agent.md` by default; `--planner-command` is an optional override

package/dist/cli-help.js

@@ -1,4 +1,4 @@
-export const usage = 'agents-relay <job|task|blocker|context|init|record|agent-register|agent-discover|status|reconcile|tick|serve> [options]';
+export const usage = 'agents-relay <job|task|plan|blocker|context|init|record|agent-register|agent-discover|status|reconcile|tick|serve> [options]';
 const help = {
     root: `Agents Relay coordinates durable asynchronous agent jobs through GitHub pull requests.
 
@@ -8,6 +8,7 @@ Usage:
 Commands:
   job create|update|show|list|merge|cancel  Manage durable GitHub-backed jobs
   task create|update|show|list|complete|retry|cancel  Manage durable tasks
+  plan                     Invoke the Planner for an existing managed Job
   blocker add|resolve|show  Manage cross-Job blocker dependencies
   context resolve          Resolve shared project instructions, skills, agents, and runtimes
   init                     Create a local demo job or initialize a GitHub job
@@ -126,6 +127,15 @@ Required: --task-id ID and the normal Job storage options.`,
     'task cancel': `Cancel one durable Task.
 
 Required: --task-id ID and the normal Job storage options.`,
+    plan: `Invoke the Planner against the current durable Job state.
+
+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.
+
+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.
+
+Example:
+  npx agents-relay plan --repo OWNER/REPO --pr 12 --id job-1 --prompt "Plan the full implementation now; keep independent work parallel."`,
     blocker: `Manage durable cross-Job blocker dependencies.
 
 Usage:

package/dist/cli.js

@@ -495,7 +495,7 @@ export async function createService(args) {
             void bus.publish(wakeEvent);
         else
             void reconciler.reconcile(loaded.job.id); } } : undefined;
-    const dashboardServer = serveDashboard(loaded.store, Number(arg(args, '--port', String(SERVICE_DEFAULTS.port))), bus, Number(arg(args, '--refresh-ms', String(SERVICE_DEFAULTS.dashboardRefreshMs))), loaded.job.id, usageRegistry, overviewProvider, webhook, undefined, undefined, {
+    const dashboardServer = serveDashboard(loaded.store, Number(arg(args, '--port', String(SERVICE_DEFAULTS.port))), bus, Number(arg(args, '--refresh-ms', String(SERVICE_DEFAULTS.dashboardRefreshMs))), loaded.job.id, usageRegistry, overviewProvider, webhook, undefined, undefined, undefined, {
         start: dashboardJobAction(loaded.store, reconciler, 'start'),
         reconcile: dashboardJobAction(loaded.store, reconciler, 'reconcile'),
         cancel: dashboardJobAction(loaded.store, reconciler, 'cancel'),
@@ -637,6 +637,19 @@ async function main() {
     }
     const loaded = await storeFor(args);
     const { store, job, localFile } = loaded;
+    if (command === 'plan') {
+        const guidance = hasArg(args, '--prompt') || hasArg(args, '--prompt-file') ? await textOption(args, '--prompt', '--prompt-file') : undefined;
+        try {
+            const result = await runtime(store, args, bus).planJob(job.id, guidance?.trim() || undefined);
+            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));
+        }
+        finally {
+            await bus?.close?.();
+        }
+        return;
+    }
     if (command === 'agent-register') {
         const now = new Date().toISOString();
         const agent = { id: arg(args, '--agent-id', randomUUID()), name: arg(args, '--name'), responsibility: arg(args, '--responsibility'), role: arg(args, '--role'), capabilities: arg(args, '--capabilities').split(',').filter(Boolean), boundaries: arg(args, '--boundaries').split('|').filter(Boolean), endpoint: { kind: arg(args, '--endpoint-kind', 'adapter'), target: arg(args, '--endpoint') }, runtime: { adapter: arg(args, '--runtime', arg(args, '--adapter', 'shell')), provider: arg(args, '--provider') || undefined, model: arg(args, '--model') || undefined }, availability: arg(args, '--availability', 'available'), routing: { labels: arg(args, '--labels').split(',').filter(Boolean).reduce((out, item) => { const [key, value] = item.split('=', 2); if (key && value)

package/dist/dashboard-html.js

@@ -367,7 +367,9 @@ function usageBar(label,windowData){const percent=Math.max(0,Math.min(100,100-wi
 function usageProvider(provider){const card=element('section','usage-provider');card.append(element('h3','',text(provider.label)));const usage=provider.usage||{};if(!usage.available||!usage.fiveHour||!usage.weekly){card.append(element('p','empty',text(usage.reason||'Account usage telemetry is unavailable.')));return card;}const bars=element('div','usage-bars');bars.append(usageBar('5-hour remaining',usage.fiveHour),usageBar('Weekly remaining',usage.weekly));card.append(bars);return card;}
 function formatCredit(value,currency){if(value===null||value===undefined||!Number.isFinite(Number(value)))return '—';const number=Number(value);if(currency==='USD')return '$'+number.toFixed(2);if(currency==='CNY')return '¥'+number.toFixed(2);return number.toFixed(2)+' '+currency;}
 function creditProvider(provider){const row=element('section','usage-provider');row.append(element('h3','',text(provider.label)));const credits=provider.credits||{};if(!credits.available||!Array.isArray(credits.balances)||!credits.balances.length){row.append(element('p','empty',text(credits.reason||'Credit balance is unavailable.')));return row;}const balance=credits.balances[0];row.append(element('div','detail-value',text(formatCredit(balance.remaining,balance.currency))));return row;}
-async function drawUsage(){try{const overview=await loadJSON('/api/usage');usageRoot.replaceChildren();usageMeta.textContent='Real account telemetry when available';const providers=Array.isArray(overview.providers)?overview.providers:[];const credits=Array.isArray(overview.credits)?overview.credits:[];if(!providers.length&&!credits.length){usageRoot.append(element('p','empty',text('Usage telemetry is unavailable.')));return;}const grid=element('div','usage-providers');for(const provider of providers)grid.append(usageProvider(provider));for(const provider of credits)grid.append(creditProvider(provider));usageRoot.append(grid);}catch(error){usageMeta.textContent='Unavailable';usageRoot.replaceChildren(element('p','error-state',text('Usage unavailable: '+error.message)));}}
+function githubBucket(label,bucket){const row=element('div','usage-row');const heading=element('div','usage-label');heading.append(element('span','',text(label)),element('span','',text(bucket.remaining+' remaining')));row.append(heading);row.append(element('div','subtle',text(bucket.used+' used / '+bucket.limit+' limit')));const reset=resetText({resetsAt:bucket.reset});if(reset)row.append(element('div','subtle',text(reset)));return row;}
+function githubUsageCard(snapshot,status){const card=element('section','usage-provider');card.append(element('h3','',text('GitHub API')));const resources=snapshot?.resources||{};const bars=element('div','usage-bars');if(resources.core)bars.append(githubBucket('REST core',resources.core));if(resources.graphql)bars.append(githubBucket('GraphQL',resources.graphql));if(resources.search)bars.append(githubBucket('Search',resources.search));if(!bars.children.length)bars.append(element('p','empty',text('GitHub quota telemetry is unavailable.')));if(status?.limited)bars.append(element('div','error-state',text('Relay cooldown active'+(status.cooldownUntil?' until '+new Date(status.cooldownUntil).toLocaleString():'')));else bars.append(element('div','subtle',text('Relay cooldown inactive')));if(status?.calls)bars.append(element('div','subtle',text('Calls since start · GraphQL '+(status.calls.graphql||0)+' · REST '+(status.calls.rest||0)+' · quota '+(status.calls.rateLimit||0))));if(status?.readPaths)bars.append(element('div','subtle',text('Read paths · workspace scans '+(status.readPaths.workspaceScans||0)+' · PR refreshes '+(status.readPaths.prRefreshes||0))));card.append(bars);return card;}
+async function drawUsage(){try{const overview=await loadJSON('/api/usage');usageRoot.replaceChildren();usageMeta.textContent='Real account telemetry when available';const providers=Array.isArray(overview.providers)?overview.providers:[];const credits=Array.isArray(overview.credits)?overview.credits:[];const grid=element('div','usage-providers');if(overview.github)grid.append(githubUsageCard(overview.github,overview.githubStatus));for(const provider of providers)grid.append(usageProvider(provider));for(const provider of credits)grid.append(creditProvider(provider));if(!grid.children.length){usageRoot.append(element('p','empty',text('Usage telemetry is unavailable.')));return;}usageRoot.append(grid);}catch(error){usageMeta.textContent='Unavailable';usageRoot.replaceChildren(element('p','error-state',text('Usage unavailable: '+error.message)));}}
 async function drawRules(){rulesStatus.textContent='';try{const rules=await loadJSON('/api/model-router-rules');rulesText.value=typeof rules.text==='string'?rules.text:'';rulesMeta.textContent=rules.hash&&rules.hash!=='none'?'Loaded · '+rules.hash.slice(0,12):'No custom rules saved';}catch(error){rulesMeta.textContent='Unavailable';rulesStatus.textContent='Could not load rules: '+error.message;}}
 async function saveRules(){rulesSave.disabled=true;rulesStatus.textContent='Saving…';try{const response=await fetch('/api/model-router-rules',{method:'PUT',headers:{'content-type':'text/plain; charset=utf-8'},body:rulesText.value});if(!response.ok)throw new Error(response.status+' '+await response.text());const rules=await response.json();rulesMeta.textContent='Saved · '+rules.hash.slice(0,12);rulesStatus.textContent='Saved. New routing decisions will load these rules.';}catch(error){rulesStatus.textContent='Save failed: '+error.message;}finally{rulesSave.disabled=false;}}
 async function drawWorkerRules(){workerRulesStatus.textContent='';try{const rules=await loadJSON('/api/worker-router-rules');workerRulesText.value=typeof rules.text==='string'?rules.text:'';workerRulesMeta.textContent=rules.hash&&rules.hash!=='none'?'Loaded · '+rules.hash.slice(0,12):'No custom rules saved';}catch(error){workerRulesMeta.textContent='Unavailable';workerRulesStatus.textContent='Could not load rules: '+error.message;}}

package/dist/dashboard.js

@@ -55,7 +55,12 @@ async function eventHistory(jobId, taskId, limit) {
 }
 export { dashboardHtml } from './dashboard-html.js';
 import { dashboardHtml } from './dashboard-html.js';
-export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobId, usageRegistry, overviewProvider, webhook, statusProvider, exactJobProvider, actions) {
+export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobId, usageRegistry, overviewProvider, webhook, statusProvider, githubUsageProvider, exactJobProvider, actions) {
+    const legacyActions = typeof exactJobProvider === 'object' && exactJobProvider !== null ? exactJobProvider : undefined;
+    const legacyExactJobProvider = !exactJobProvider && githubUsageProvider ? githubUsageProvider : undefined;
+    const resolvedExactJobProvider = typeof exactJobProvider === 'function' ? exactJobProvider : legacyExactJobProvider;
+    const resolvedGithubUsageProvider = legacyExactJobProvider ? undefined : githubUsageProvider;
+    const resolvedActions = actions ?? legacyActions;
     const webhookDeliveries = new DeliveryDeduper();
     const clients = new Set();
     const subscribedJobs = new Set();
@@ -106,8 +111,8 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
     const snapshot = async (requestedJobId = jobId, forceRefresh = false) => {
         await subscribeDiscovered();
         if (overviewProvider) {
-            if (forceRefresh && requestedJobId && exactJobProvider) {
-                const exact = await exactJobProvider(requestedJobId);
+            if (forceRefresh && requestedJobId && resolvedExactJobProvider) {
+                const exact = await resolvedExactJobProvider(requestedJobId);
                 if (exact)
                     return { id: exact.id, json: JSON.stringify(exact) };
             }
@@ -132,7 +137,16 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
     const usage = async () => {
         if (!usageRegistry)
             throw new Error('Account usage telemetry is unavailable');
-        return JSON.stringify(await readUsageSnapshot(usageRegistry));
+        const account = await readUsageSnapshot(usageRegistry);
+        const githubStatus = statusProvider ? statusProvider() : { limited: false, cooldownUntil: null };
+        let github = null;
+        if (resolvedGithubUsageProvider) {
+            try {
+                github = await resolvedGithubUsageProvider();
+            }
+            catch { /* quota telemetry is best-effort during GitHub degradation */ }
+        }
+        return JSON.stringify({ ...account, github, githubStatus });
     };
     const server = createServer(async (req, res) => {
         if (req.url === '/') {
@@ -200,19 +214,24 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
             const url = new URL(req.url ?? '/', 'http://127.0.0.1');
             const requestedJobId = url.searchParams.get('id') ?? '';
             const action = url.searchParams.get('action') ?? '';
-            const handler = action === 'start' ? actions?.start : action === 'reconcile' ? actions?.reconcile : action === 'cancel' ? actions?.cancel : undefined;
+            const handler = action === 'start' ? resolvedActions?.start : action === 'reconcile' ? resolvedActions?.reconcile : action === 'cancel' ? resolvedActions?.cancel : undefined;
             if (req.method !== 'POST' || !/^[A-Za-z0-9_-]+$/.test(requestedJobId) || !handler) {
                 res.writeHead(404);
                 res.end('Job action unavailable');
                 return;
             }
             try {
-                res.writeHead(200, { 'content-type': 'application/json' });
-                res.end(JSON.stringify(await handler(requestedJobId)));
+                const result = await handler(requestedJobId);
+                if (!res.headersSent)
+                    res.writeHead(200, { 'content-type': 'application/json' });
+                if (!res.writableEnded)
+                    res.end(JSON.stringify(result));
             }
             catch (error) {
-                res.writeHead(409);
-                res.end(error instanceof Error ? error.message : String(error));
+                if (!res.headersSent)
+                    res.writeHead(409);
+                if (!res.writableEnded)
+                    res.end(error instanceof Error ? error.message : String(error));
             }
             return;
         }
@@ -221,19 +240,24 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
             const requestedJobId = url.searchParams.get('id') ?? '';
             const requestedTaskId = url.searchParams.get('task') ?? '';
             const action = url.searchParams.get('action') ?? '';
-            const handler = action === 'retry' ? actions?.taskRetry : action === 'cancel' ? actions?.taskCancel : undefined;
+            const handler = action === 'retry' ? resolvedActions?.taskRetry : action === 'cancel' ? resolvedActions?.taskCancel : undefined;
             if (req.method !== 'POST' || !/^[A-Za-z0-9_-]+$/.test(requestedJobId) || !/^[A-Za-z0-9_-]+$/.test(requestedTaskId) || !handler) {
                 res.writeHead(404);
                 res.end('Task action unavailable');
                 return;
             }
             try {
-                res.writeHead(200, { 'content-type': 'application/json' });
-                res.end(JSON.stringify(await handler(requestedJobId, requestedTaskId)));
+                const result = await handler(requestedJobId, requestedTaskId);
+                if (!res.headersSent)
+                    res.writeHead(200, { 'content-type': 'application/json' });
+                if (!res.writableEnded)
+                    res.end(JSON.stringify(result));
             }
             catch (error) {
-                res.writeHead(409);
-                res.end(error instanceof Error ? error.message : String(error));
+                if (!res.headersSent)
+                    res.writeHead(409);
+                if (!res.writableEnded)
+                    res.end(error instanceof Error ? error.message : String(error));
             }
             return;
         }

package/dist/manual-plan.js

@@ -0,0 +1,34 @@
+import { createPlannerRoundTask } from './planner.js';
+import { transitionJobEvent } from './scheduler.js';
+export async function executeManualPlan(store, jobId, guidance, timeoutMs, launchPlanner) {
+    let job = await store.load(jobId);
+    if (['COMPLETED', 'CANCELLED'].includes(job.state))
+        throw new Error(`Cannot plan terminal job ${job.id} (${job.state})`);
+    const active = job.tasks.find(task => task.kind === 'planner' && ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state));
+    if (active)
+        throw new Error(`Planning round ${active.id} is already ${active.state}`);
+    const round = createPlannerRoundTask(job, { guidance, manual: true, timeoutMs });
+    await store.appendTask(round);
+    job = await store.load(jobId);
+    if (job.state === 'DRAFT') {
+        await transitionJobEvent(job, 'activate');
+        await store.saveJob(job);
+        job = await store.load(jobId);
+    }
+    const durableRound = job.tasks.find(task => task.id === round.id);
+    if (!durableRound)
+        throw new Error(`Planning round ${round.id} was not persisted`);
+    await launchPlanner(job, durableRound);
+    let completed = await store.load(jobId);
+    let completedRound = completed.tasks.find(task => task.id === round.id);
+    while (completedRound && ['QUEUED', 'RUNNING'].includes(completedRound.state)) {
+        await new Promise(resolve => setTimeout(resolve, 25));
+        completed = await store.load(jobId);
+        completedRound = completed.tasks.find(task => task.id === round.id);
+    }
+    if (!completedRound)
+        throw new Error(`Planning round ${round.id} disappeared`);
+    if (completedRound.state !== 'SUCCEEDED')
+        throw new Error(completedRound.error ?? `Planning round ${round.id} ended ${completedRound.state}`);
+    return { job: completed, round: completedRound };
+}

package/dist/planner.js

@@ -2,8 +2,45 @@ import { spawn } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
-import { taskOverallTimeoutMs } from './types.js';
+import { storySizeTimeoutMs, taskOverallTimeoutMs } from './types.js';
 import { executionContextPrompt } from './execution-context.js';
+export function plannerRoundNumber(task) {
+    if (task.kind !== 'planner')
+        return null;
+    if (Number.isInteger(task.planningRound) && (task.planningRound ?? 0) > 0)
+        return task.planningRound;
+    const match = /^(?:plan|planner)-(\d+)$/.exec(task.id);
+    return match ? Number(match[1]) : null;
+}
+export function createPlannerRoundTask(job, options = {}) {
+    const planners = job.tasks.filter(task => task.kind === 'planner')
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+    const used = new Set(job.tasks.map(task => task.id));
+    let round = Math.max(0, ...planners.map(task => plannerRoundNumber(task) ?? 0)) + 1;
+    let id = `plan-${round}`;
+    while (used.has(id)) {
+        round += 1;
+        id = `plan-${round}`;
+    }
+    const previousPlanner = planners.at(-1);
+    const now = options.now ?? new Date().toISOString();
+    const context = {
+        job,
+        tasks: job.tasks,
+        objective: job.objective ?? job.description ?? job.title,
+        previousPlannerTaskId: previousPlanner?.id ?? null,
+        guidance: options.guidance,
+    };
+    return {
+        jobId: job.id, id, kind: 'planner', storySize: 'M', agentName: 'planner',
+        parentTaskId: previousPlanner?.id ?? null, dependencies: [], capabilities: ['planner'], adapter: 'orchestrator',
+        input: plannerInput(context), continuation: null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0,
+        maxAttempts: options.manual ? 1 : 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null,
+        result: null, plannerResult: null, error: null, timeoutMs: options.timeoutMs ?? storySizeTimeoutMs('M'),
+        createdAt: now, updatedAt: now, planningDecisionId: id, planningSource: 'model-planner', planningRound: round,
+        plannerGuidance: options.guidance, manualPlanning: options.manual === true,
+    };
+}
 export function planningSpec(task) {
     if (!task.output && task.adapter !== 'orchestrator')
         throw new Error(`Initial task ${task.id} requires an output contract`);
@@ -156,6 +193,7 @@ export function plannerInput(context) {
     return JSON.stringify({
         objective: context.objective,
         retry_feedback: context.retryFeedback,
+        caller_prompt: context.guidance,
         previous_planner_task_id: context.previousPlannerTaskId,
         project: project ? { name: project.name, path: project.path } : undefined,
         visible_agents: visibleAgents ?? [],

package/dist/pool.js

@@ -22,15 +22,18 @@ export class RepositoryWorkerPool {
     trustedAuthors;
     concurrency;
     makeReconciler;
+    isRateLimited;
     running = false;
     pending = false;
     reconcileLocks = new Map();
+    targetedReconcileFlights = new Map();
     jobTargets = new Map();
-    constructor(client, repository, trustedAuthors, concurrency, makeReconciler) {
+    constructor(client, repository, trustedAuthors, concurrency, makeReconciler, isRateLimited = () => false) {
         this.client = client;
         this.trustedAuthors = trustedAuthors;
         this.concurrency = concurrency;
         this.makeReconciler = makeReconciler;
+        this.isRateLimited = isRateLimited;
         this.repositories = [...new Set(typeof repository === 'string' ? [repository] : repository)];
     }
     repositories;
@@ -79,6 +82,8 @@ export class RepositoryWorkerPool {
     }
     async reconcileKnown(discovered) { await this.reconcileDiscovered(discovered); }
     async reconcile() {
+        if (this.isRateLimited())
+            return;
         if (this.running) {
             this.pending = true;
             return;
@@ -95,15 +100,29 @@ export class RepositoryWorkerPool {
         }
     }
     async reconcileTarget(repository, prNumber, jobId) {
-        if (!this.repositories.includes(repository))
+        if (this.isRateLimited() || !this.repositories.includes(repository))
             return;
         this.jobTargets.set(jobId, { repository, prNumber });
-        await this.reconcileExclusive(jobId, async () => {
+        const key = `${repository}#${prNumber}:${jobId}`;
+        const existing = this.targetedReconcileFlights.get(key);
+        if (existing)
+            return existing;
+        const flight = this.reconcileExclusive(jobId, async () => {
             const store = new GitHubStore(this.client, repository, prNumber, this.trustedAuthors);
             await this.makeReconciler(store, Math.max(1, this.concurrency)).reconcile(jobId);
         });
+        this.targetedReconcileFlights.set(key, flight);
+        try {
+            await flight;
+        }
+        finally {
+            if (this.targetedReconcileFlights.get(key) === flight)
+                this.targetedReconcileFlights.delete(key);
+        }
     }
     async handleLifecycleEvent(event) {
+        if (this.isRateLimited())
+            return;
         const target = this.jobTargets.get(event.job_id);
         if (!target || !this.repositories.includes(target.repository)) {
             process.stderr.write(`warning: terminal event target unknown for job ${event.job_id}\n`);

package/dist/reconciler.js

@@ -4,10 +4,11 @@ import { dependencyReady, schedule, transitionJobEvent, transitionTaskEvent } fr
 import { implementationComplete } from './runtime-status.js';
 import { LaunchFailure, StartAckTimeout } from './adapters.js';
 import { eventFor } from './events.js';
-import { parsePlannerResult, plannerInput } from './planner.js';
+import { createPlannerRoundTask, parsePlannerResult, plannerInput } from './planner.js';
 import { agentContractPrompt, executionContextPrompt, resolveExecutionContext } from './execution-context.js';
 import { agentGraphPrompt, validateAgentSelection } from './agent-graph.js';
 import { ReconcilerReviewBase } from './reconciler-review.js';
+import { executeManualPlan } from './manual-plan.js';
 import { executionEventSource } from './reconciler-runtime.js';
 export { executionEventSource } from './reconciler-runtime.js';
 import { CallbackWorkflowEffectHandler } from './workflow/effects.js';
@@ -248,6 +249,9 @@ export class Reconciler extends ReconcilerReviewBase {
             }
         }
     }
+    async planJob(jobId, guidance) {
+        return executeManualPlan(this.store, jobId, guidance, this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M'), (job, task) => this.launchPlanner(job, task));
+    }
     async maybeCreatePlanner(job) {
         if (job.executionMode !== 'autonomous')
             return job;
@@ -274,16 +278,7 @@ export class Reconciler extends ReconcilerReviewBase {
             return job;
         if (latest && !job.schedule && job.review && job.review.outcome !== 'approved')
             return job;
-        const previousPlanner = allPlanners.at(-1);
-        const used = new Set(job.tasks.map(task => task.id));
-        let number = allPlanners.length + 1;
-        let id = `planner-${number}`;
-        while (used.has(id)) {
-            number += 1;
-            id = `planner-${number}`;
-        }
-        const now = new Date().toISOString();
-        const task = { jobId: job.id, id, kind: 'planner', storySize: 'M', agentName: 'planner', parentTaskId: previousPlanner?.id ?? null, dependencies: [], capabilities: ['planner'], adapter: 'orchestrator', input: plannerInput({ job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: previousPlanner?.id ?? null }), continuation: null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M'), createdAt: now, updatedAt: now, planningDecisionId: id, planningSource: 'model-planner', planningRound: allPlanners.length + 1 };
+        const task = createPlannerRoundTask(job, { timeoutMs: this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M') });
         await this.store.appendTask(task);
         await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.created', 'queued', `Planner task ${task.id} created`, 'orchestrator'));
         return this.store.load(job.id);
@@ -456,7 +451,7 @@ export class Reconciler extends ReconcilerReviewBase {
         let promise;
         try {
             const executionContext = await this.plannerContext(job, task);
-            const context = { job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: task.parentTaskId, executionContext, retryFeedback: task.plannerRetryFeedback };
+            const context = { job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: task.parentTaskId, executionContext, retryFeedback: task.plannerRetryFeedback, guidance: task.plannerGuidance };
             task.input = plannerInput(context);
             await this.store.saveTask(task);
             promise = planner.plan(context, controller.signal);
@@ -499,8 +494,8 @@ export class Reconciler extends ReconcilerReviewBase {
             const children = result.next_tasks.map(spec => this.plannerChild(job, task, spec, executionContext));
             for (const child of children) {
                 const existing = job.tasks.find(item => item.id === child.id);
-                if (!existing)
-                    continue;
+                if (existing && !samePlannerChildDefinition(existing, child))
+                    throw new Error(`Planner child ${child.id} already exists with a different definition`);
             }
             // Persist the completed decision before exposing executable children.
             task.plannerResult = result;
@@ -537,7 +532,8 @@ export class Reconciler extends ReconcilerReviewBase {
                 await this.emit(eventFor(job.id, task.id, task.parentTaskId, task.state === 'FAILED' ? 'planner.failed' : 'planner.retry', task.state === 'FAILED' ? 'failed' : 'queued', `Planner ${task.id}: ${message}`, 'user'));
             }
         }
-        this.detach(this.reconcile(jobId), jobId, task.id, 'planner follow-up reconciliation');
+        if (!task.manualPlanning)
+            this.detach(this.reconcile(jobId), jobId, task.id, 'planner follow-up reconciliation');
     }
     plannerChild(job, planner, spec, executionContext) {
         validateAgentSelection(executionContext, spec.agentName, spec.agentGraph);

package/dist/relayd.js

@@ -53,6 +53,26 @@ export function normalizeDaemonArguments(argv) {
         throw new Error('--pr must be positive');
     return { repository, workspaceRoot: repository ? null : workspaceRoot, pullRequest, jobId: id || null, serviceArguments: [...argv] };
 }
+export function recoveryScanRepositories(repositories, cached, dormantProbeIndex = 0) {
+    const byRepository = new Map();
+    for (const item of cached) {
+        const values = byRepository.get(item.job.repository) ?? [];
+        values.push(item);
+        byRepository.set(item.job.repository, values);
+    }
+    const activeOrUnknown = [];
+    const dormant = [];
+    for (const repository of repositories) {
+        const values = byRepository.get(repository);
+        if (!values || values.length === 0 || values.some(item => item.githubState === 'OPEN' && !['COMPLETED', 'CANCELLED'].includes(item.job.state)))
+            activeOrUnknown.push(repository);
+        else
+            dormant.push(repository);
+    }
+    if (dormant.length === 0)
+        return activeOrUnknown;
+    return [...activeOrUnknown, dormant[Math.abs(dormantProbeIndex) % dormant.length]];
+}
 export async function runDaemon(argv) {
     if (argv.includes('--help') || argv.includes('-h')) {
         console.log(daemonHelp);
@@ -76,10 +96,12 @@ export async function runDaemon(argv) {
     const usageRegistry = codexAndZaiUsageRegistry();
     const decisionAuditStore = new JsonlDecisionAuditStore(process.env.AGENTS_RELAY_DECISION_AUDIT_PATH ?? join(homedir(), '.agents-relay', 'decision-audit.jsonl'));
     let cachedOverviews = [];
+    const githubReadPaths = { workspaceScans: 0, prRefreshes: 0 };
+    let dormantProbeIndex = 0;
     const makeReconciler = (store, maxConcurrent) => new Reconciler(store, { owner: `relayd-${process.pid}`, maxConcurrent, leaseMs: Number(value(argv, '--lease-ms', '300000')), adapters: [new CodexAdapter(value(argv, '--codex', 'codex')), new ChatGptAdapter()], continuations: [new CodexThreadContinuation(value(argv, '--codex', 'codex')), new CommandContinuation(), new WebhookContinuation()], planner: runtimePlanner(argv), usageSnapshotProvider: () => usageRegistry.snapshot(), runtimeSummaryProvider: () => ({ chatgptRunning: summarizeRuntime(cachedOverviews.map(item => item.job)).workers.chatgpt }), decisionEngine: new LayaCliDecisionEngine(), decisionMode: decisionMode(), decisionAuditStore, eventBus: bus, reviewer: runtimeReviewer(), projectPathForJob: async (job) => resolveRepositoryProjectPath(repositoryPaths.get(job.repository) ?? await resolveManagedProjectPath(job.repository, explicitProjectPath, workspaceRoot), job.projectPath) });
     if (repositories.length === 0)
         throw new Error(`No Git repositories with GitHub origins found under ${normalized.workspaceRoot ?? defaultWorkspaceRoot()}`);
-    const pool = new RepositoryWorkerPool(client, repositories, trusted, concurrency, makeReconciler);
+    const pool = new RepositoryWorkerPool(client, repositories, trusted, concurrency, makeReconciler, () => client.rateLimitStatus().limited);
     const cacheDirectory = join(homedir(), '.agents-relay');
     const cacheFile = join(cacheDirectory, 'dashboard-jobs.json');
     try {
@@ -88,11 +110,17 @@ export async function runDaemon(argv) {
             cachedOverviews = parsed;
     }
     catch { /* first run or invalid cache */ }
-    const refreshAll = async () => {
+    const refreshAll = async (full = false) => {
         if (client.rateLimitStatus().limited)
             return cachedOverviews;
+        const scanRepositories = full ? repositories : recoveryScanRepositories(repositories, cachedOverviews, dormantProbeIndex++);
+        if (scanRepositories.length === 0)
+            return cachedOverviews;
         try {
-            cachedOverviews = dashboardManagedJobs(await aggregateManagedGitHubJobs(client, repositories, trusted));
+            githubReadPaths.workspaceScans += 1;
+            const refreshed = await aggregateManagedGitHubJobs(client, scanRepositories, trusted);
+            const scanned = new Set(scanRepositories);
+            cachedOverviews = dashboardManagedJobs([...cachedOverviews.filter(item => !scanned.has(item.job.repository)), ...refreshed]);
             try {
                 await mkdir(cacheDirectory, { recursive: true });
                 await writeFile(cacheFile, JSON.stringify(cachedOverviews), 'utf8');
@@ -105,7 +133,7 @@ export async function runDaemon(argv) {
             return cachedOverviews;
         }
     };
-    const overviews = async (forceRefresh = false) => forceRefresh ? refreshAll() : cachedOverviews;
+    const overviews = async (forceRefresh = false) => forceRefresh ? refreshAll(true) : cachedOverviews;
     const persistCache = async () => {
         try {
             await mkdir(cacheDirectory, { recursive: true });
@@ -113,13 +141,31 @@ export async function runDaemon(argv) {
         }
         catch { /* cache is best effort */ }
     };
+    const pullRequestRefreshFlights = new Map();
     const refreshPullRequest = async (repository, prNumber) => {
-        const refreshed = await loadManagedGitHubPullRequestGraphql(client, repository, prNumber, trusted);
-        cachedOverviews = cachedOverviews.filter(item => item.job.repository !== repository || item.job.prNumber !== prNumber);
-        cachedOverviews.push(...refreshed);
-        cachedOverviews = dashboardManagedJobs(cachedOverviews);
-        await persistCache();
-        return refreshed;
+        if (client.rateLimitStatus().limited)
+            return cachedOverviews.filter(item => item.job.repository === repository && item.job.prNumber === prNumber);
+        const key = `${repository}#${prNumber}`;
+        const existing = pullRequestRefreshFlights.get(key);
+        if (existing)
+            return existing;
+        const flight = (async () => {
+            githubReadPaths.prRefreshes += 1;
+            const refreshed = await loadManagedGitHubPullRequestGraphql(client, repository, prNumber, trusted);
+            cachedOverviews = cachedOverviews.filter(item => item.job.repository !== repository || item.job.prNumber !== prNumber);
+            cachedOverviews.push(...refreshed);
+            cachedOverviews = dashboardManagedJobs(cachedOverviews);
+            await persistCache();
+            return refreshed;
+        })();
+        pullRequestRefreshFlights.set(key, flight);
+        try {
+            return await flight;
+        }
+        finally {
+            if (pullRequestRefreshFlights.get(key) === flight)
+                pullRequestRefreshFlights.delete(key);
+        }
     };
     const initial = cachedOverviews;
     const fallback = initial[0]?.job;
@@ -170,6 +216,9 @@ export async function runDaemon(argv) {
         const cached = cachedOverviews.find(item => item.job.id === jobId);
         if (!cached)
             return null;
+        const cachedJob = () => ({ ...cached.job, githubState: cached.githubState, runtimeStatus: deriveJobRuntimeStatus(cached.job, cached.githubState), mergedAt: cached.mergedAt, closedAt: cached.closedAt, draft: cached.draft });
+        if (client.rateLimitStatus().limited)
+            return cachedJob();
         try {
             const refreshed = (await refreshPullRequest(cached.job.repository, cached.job.prNumber)).find(item => item.job.id === jobId);
             if (!refreshed)
@@ -178,10 +227,10 @@ export async function runDaemon(argv) {
         }
         catch (error) {
             process.stderr.write(`warning: selected job refresh unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
-            return null;
+            return cachedJob();
         }
     };
-    const server = serveDashboard(dashboardStore, Number(value(argv, '--port', String(SERVICE_DEFAULTS.port))), bus, Number(value(argv, '--refresh-ms', String(SERVICE_DEFAULTS.dashboardRefreshMs))), fallback?.id, usageRegistry, overviews, webhook, () => client.rateLimitStatus(), exactJob, {
+    const server = serveDashboard(dashboardStore, Number(value(argv, '--port', String(SERVICE_DEFAULTS.port))), bus, Number(value(argv, '--refresh-ms', String(SERVICE_DEFAULTS.dashboardRefreshMs))), fallback?.id, usageRegistry, overviews, webhook, () => ({ ...client.rateLimitStatus(), readPaths: { ...githubReadPaths } }), () => client.rateLimitSnapshot(), exactJob, {
         start: workspaceJobAction('start'),
         reconcile: workspaceJobAction('reconcile'),
         cancel: workspaceJobAction('cancel'),
@@ -207,7 +256,7 @@ export async function runDaemon(argv) {
     process.once('SIGINT', stop);
     process.once('SIGTERM', stop);
     console.log('Dashboard listening; repository worker pool active');
-    void refreshAll()
+    void refreshAll(true)
         .then(items => pool.reconcileKnown(items))
         .catch(error => process.stderr.write(`warning: startup reconciliation unavailable: ${error instanceof Error ? error.message : String(error)}\n`));
 }

package/dist/store-task-definition.js

@@ -5,7 +5,7 @@ function immutableTaskDefinition(task) {
     } : undefined;
     return {
         jobId: task.jobId, id: task.id, priority: task.priority, storySize: task.storySize ?? 'M', projectName: task.projectName, agentName: task.agentName, agentGraph: task.agentGraph,
-        kind: task.kind ?? 'work', planningDecisionId: task.planningDecisionId, planningSource: task.planningSource, planningRound: task.planningRound, parentTaskId: task.parentTaskId, dependencies: task.dependencies, capabilities: task.capabilities, workerRequirements: task.workerRequirements, workerSelection: task.workerSelection, adapter: task.adapter,
+        kind: task.kind ?? 'work', planningDecisionId: task.planningDecisionId, planningSource: task.planningSource, planningRound: task.planningRound, plannerGuidance: task.plannerGuidance, manualPlanning: task.manualPlanning, parentTaskId: task.parentTaskId, dependencies: task.dependencies, capabilities: task.capabilities, workerRequirements: task.workerRequirements, workerSelection: task.workerSelection, adapter: task.adapter,
         input: task.input, attachments: task.attachments, output: task.output, routing, chatgptTabClosePolicy: task.chatgptTabClosePolicy ?? 'after-start', continuation: task.continuation ?? null, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs
     };
 }

package/dist/store.js

@@ -234,12 +234,47 @@ export class GhApiClient {
     cooldownUntil = 0;
     rateLimitFailures = 0;
     installationToken = null;
+    rateLimitCache = null;
+    rateLimitFlight = null;
+    rateLimitCacheTtlMs = 5 * 60_000;
+    apiDiagnostics = { rest: 0, graphql: 0, rateLimit: 0 };
     constructor(appAuth = null) {
         this.appAuth = appAuth;
     }
     rateLimitStatus() {
         const limited = Date.now() < this.cooldownUntil;
-        return { limited, cooldownUntil: limited ? new Date(this.cooldownUntil).toISOString() : null };
+        return { limited, cooldownUntil: limited ? new Date(this.cooldownUntil).toISOString() : null, calls: { ...this.apiDiagnostics } };
+    }
+    async rateLimitSnapshot(force = false) {
+        const now = Date.now();
+        if (!force && this.rateLimitCache && now - this.rateLimitCache.cachedAt < this.rateLimitCacheTtlMs)
+            return this.rateLimitCache.snapshot;
+        if (this.rateLimitFlight)
+            return this.rateLimitFlight;
+        if (this.rateLimitStatus().limited && this.rateLimitCache)
+            return this.rateLimitCache.snapshot;
+        const flight = (async () => {
+            this.apiDiagnostics.rateLimit += 1;
+            const stdout = await this.spawnGh(['api', 'rate_limit'], undefined, await this.commandEnv());
+            const parsed = JSON.parse(stdout);
+            const resources = parsed.resources;
+            const bucket = (value) => {
+                const item = value;
+                const limit = Number(item?.limit), used = Number(item?.used), remaining = Number(item?.remaining), reset = Number(item?.reset);
+                return [limit, used, remaining, reset].every(Number.isFinite) ? { limit, used, remaining, reset } : undefined;
+            };
+            const snapshot = { observedAt: new Date().toISOString(), resources: { core: bucket(resources?.core), graphql: bucket(resources?.graphql), search: bucket(resources?.search) } };
+            this.rateLimitCache = { cachedAt: Date.now(), snapshot };
+            return snapshot;
+        })();
+        this.rateLimitFlight = flight;
+        try {
+            return await flight;
+        }
+        finally {
+            if (this.rateLimitFlight === flight)
+                this.rateLimitFlight = null;
+        }
     }
     assertAvailable() {
         if (Date.now() < this.cooldownUntil)
@@ -322,6 +357,7 @@ export class GhApiClient {
     }
     async graphql(query, variables = {}) {
         this.assertAvailable();
+        this.apiDiagnostics.graphql += 1;
         const payload = JSON.stringify({ query, variables });
         const stdout = await this.spawnGh(['api', 'graphql', '--input', '-'], payload, await this.commandEnv());
         const parsed = JSON.parse(stdout);
@@ -334,6 +370,7 @@ export class GhApiClient {
     }
     async request(path, init = {}) {
         this.assertAvailable();
+        this.apiDiagnostics.rest += 1;
         const args = ['api', path];
         const method = String(init.method ?? 'GET');
         if (method !== 'GET')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "1.0.126",
+  "version": "1.0.127",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
   "bin": {

package/skills/agents-relay/SKILL.md

@@ -96,11 +96,11 @@ ChatGPT thread identity is diagnostic only. It is not persisted as a resumable t
 
 ## Autonomous planner
 
-Direct orchestrator-created Tasks do not require a Plan. The orchestrator may create the initial batch with `task create`; those Tasks remain top-level unless the orchestrator explicitly gives them normal task parentage.
+Direct orchestrator-created Tasks do not require a Plan. The orchestrator may create the initial batch with `task create`; those Tasks remain top-level unless the orchestrator explicitly gives them normal task parentage. When planner-driven decomposition is desired instead, use `agents-relay plan --repo OWNER/REPO --pr N --id JOB_ID [--prompt TEXT | --prompt-file PATH|-]`.
 
-For autonomous continuation, Relay invokes the planner agent as a pure decision function. The planner receives durable Job/Task state, previous planner rounds, and resolved execution context, then returns structured `{ objective_status, assessment, next_tasks }` output. The planner does not call Relay CLI and does not persist Tasks itself.
+For explicit `plan` and autonomous continuation, Relay invokes the same planner agent as a pure decision function. The planner receives durable Job/Task state, previous planner rounds, and resolved execution context, then returns structured `{ objective_status, assessment, next_tasks }` output. The planner does not call Relay CLI and does not persist Tasks itself.
 
-Each successful planner invocation is one real planner round. Relay persists that planner result, then creates the returned Tasks with lineage back to that planner round. Only planner execution creates planner rounds; Relay never manufactures synthetic `plan-*` records for direct Task creation. In the dashboard, planner rounds are organizational/grouping nodes for the Tasks they produced.
+Each successful planner invocation is one real `plan-N` planning round. Relay persists that planner result, then creates the returned Tasks with lineage back to that planning round. Historical `planner-N` records remain readable. Only planner execution creates planner rounds; Relay never manufactures synthetic `plan-*` records for direct Task creation. In the dashboard, planner rounds are organizational/grouping nodes for the Tasks they produced.
 
 A zero-task autonomous Job remains idle. After a direct orchestrator-created initial batch completes, Relay may start the first real planner round. Fixed Jobs do not automatically create planner rounds.
 

package/skills/agents-relay/contracts/task-job-contract.md

@@ -139,13 +139,14 @@ Final-review routing follows the same factual worker-selection boundary as execu
 The public CLI resource surface is:
 
 - `job create|update|show|list|merge|cancel`
-- `task create|update|show|list|retry|cancel`
+- `task create|update|show|list|complete|retry|cancel`
+- `plan`
 
-`job create` persists only durable Job state. It never creates executable work. `task create` creates a real executable Task directly under the Job; direct orchestrator-created Tasks are not wrapped in synthetic planner Tasks and have no planner-round provenance.
+`job create` persists only durable Job state. It never creates executable work. `task create` creates a real executable Task directly under the Job; direct orchestrator-created Tasks are not wrapped in synthetic planner Tasks and have no planner-round provenance. `plan` is the explicit public operation for invoking the Planner against an existing Job; it is not generic CRUD for planner records.
 
-Planner rounds are internal planner output, not a general public CLI resource. Relay invokes the planner agent, validates its structured result, persists that invocation as one planner round, then materializes `next_tasks` under that planner round. The planner agent itself does not call Relay CLI or persist Tasks. Only an actual planner invocation creates a planner round.
+Relay invokes the planner agent, validates its structured result, persists that invocation as one real `plan-N` round, then materializes `next_tasks` under that planning round. `--prompt` / `--prompt-file` add caller guidance to the durable planning input without replacing the Job objective. The planner agent itself does not call Relay CLI or persist Tasks. Only an actual planner invocation creates a planning round. Historical `planner-N` rounds remain readable and participate in round numbering.
 
-A zero-task autonomous Job stays idle. An autonomous Job may begin with one or more direct orchestrator-created Tasks and no Plan. After that direct batch completes, Relay may create the first real planner round. Later planner rounds continue until the objective is satisfied. Fixed Jobs never create autonomous planner rounds.
+A zero-task autonomous Job stays idle under ordinary reconciliation, but an explicit `plan` command can start it immediately. An autonomous Job may also begin with one or more direct orchestrator-created Tasks and no Plan. After that direct batch completes, Relay may create the next real planning round through the same round-construction/execution path used by manual `plan`. Later rounds continue until the objective is satisfied. Fixed Jobs never create autonomous planner rounds automatically.
 
 Planner-produced Tasks obey this same contract, including explicit `storySize`.