agents-relay 1.0.0 → 1.0.1

package/README.md

@@ -20,7 +20,7 @@ npx agents-relay status --repo OWNER/REPO --pr 12 --id job-1
 Jobs default to `fixed`, preserving the original submit-and-run behavior. Use
 `--mode autonomous` with `init` or `job create` to make reconciliation own
 planner progress. The durable status JSON and dashboard show the mode. An
-autonomous runtime needs `--planner-command`; it receives the objective/task
+autonomous runtime uses the bundled `skills/agents-relay/agents/planner.agent.md` by default; `--planner-command` is an optional override
 snapshot as JSON on stdin and must return `{ "objective_status": "in_progress"|"satisfied", "assessment": "...", "next_tasks": [...] }`.
 Planner-created tasks use stable IDs and the existing parent/subtask tree, so
 retries and daemon restarts do not create duplicate work.

package/dist/cli.js

@@ -263,7 +263,8 @@ async function runJobCommand(action, args) {
     });
     console.log(JSON.stringify({ repository: repo, pr: result.pr.number, job: result.job.id, executionMode: result.job.executionMode, state: result.job.state }, null, 2));
 }
-export function runtime(store, args, bus) { const emit = (event) => { process.stderr.write(`${JSON.stringify(event)}\n`); }; const plannerCommand = arg(args, '--planner-command'); const modelRuntime = arg(args, '--codex', 'codex'); const planner = plannerCommand ? new CommandObjectivePlanner(plannerCommand) : new AgentObjectivePlanner(modelRuntime); return new Reconciler(store, { owner: arg(args, '--owner', `cli-${process.pid}`), maxConcurrent: Number(arg(args, '--concurrency', '4')), leaseMs: Number(arg(args, '--lease-ms', '300000')), adapters: [new ShellAdapter(), new CodexAdapter(modelRuntime), new ChatGptAdapter({ endpoint: arg(args, '--macbridge-url') || undefined, tokenFile: arg(args, '--macbridge-token-file') || undefined })], continuations: [new CodexThreadContinuation(modelRuntime), new CommandContinuation(), new WebhookContinuation()], planner, eventBus: bus, emit }); }
+export function runtimePlanner(args) { const plannerCommand = arg([...args], '--planner-command'); const modelRuntime = arg([...args], '--codex', 'codex'); return plannerCommand ? new CommandObjectivePlanner(plannerCommand) : new AgentObjectivePlanner(modelRuntime); }
+export function runtime(store, args, bus) { const emit = (event) => { process.stderr.write(`${JSON.stringify(event)}\n`); }; const modelRuntime = arg(args, '--codex', 'codex'); const planner = runtimePlanner(args); return new Reconciler(store, { owner: arg(args, '--owner', `cli-${process.pid}`), maxConcurrent: Number(arg(args, '--concurrency', '4')), leaseMs: Number(arg(args, '--lease-ms', '300000')), adapters: [new ShellAdapter(), new CodexAdapter(modelRuntime), new ChatGptAdapter({ endpoint: arg(args, '--macbridge-url') || undefined, tokenFile: arg(args, '--macbridge-token-file') || undefined })], continuations: [new CodexThreadContinuation(modelRuntime), new CommandContinuation(), new WebhookContinuation()], planner, eventBus: bus, emit }); }
 export async function createService(args) {
     const loaded = await storeFor(args);
     const upstream = eventBus(args);

package/dist/relayd.js

@@ -11,7 +11,7 @@ import { RepositoryWorkerPool, aggregateManagedGitHubJobs } from './pool.js';
 import { Reconciler } from './reconciler.js';
 import { dashboardManagedJobs, GitHubStore, InMemoryStore, loadManagedGitHubPullRequestGraphql } from './store.js';
 import { githubAuthContext } from './github-auth.js';
-import { isEntrypoint, startService, SERVICE_DEFAULTS } from './cli.js';
+import { isEntrypoint, runtimePlanner, startService, SERVICE_DEFAULTS } from './cli.js';
 import { codexAndZaiUsageRegistry } from './usage.js';
 import { defaultWorkspaceRoot, discoverWorkspaceRepositories } from './workspace.js';
 export const daemonHelp = `Agents Relay daemon runs the dashboard and worker pool.
@@ -64,7 +64,7 @@ export async function runDaemon(argv) {
     const trusted = auth.trustedAuthors;
     const concurrency = Number(value(argv, '--concurrency', '4'));
     const bus = value(argv, '--events') === 'nats' ? new NatsEventBus(value(argv, '--nats-url', 'nats://127.0.0.1:4222'), value(argv, '--subject-prefix', 'agents-relay.events.job')) : undefined;
-    const makeReconciler = (store, maxConcurrent) => new Reconciler(store, { owner: `relayd-${process.pid}`, maxConcurrent, leaseMs: Number(value(argv, '--lease-ms', '300000')), adapters: [new ShellAdapter(), new CodexAdapter(value(argv, '--codex', 'codex')), new ChatGptAdapter({ endpoint: value(argv, '--macbridge-url') || undefined, tokenFile: value(argv, '--macbridge-token-file') || undefined })], continuations: [new CodexThreadContinuation(value(argv, '--codex', 'codex')), new CommandContinuation(), new WebhookContinuation()], eventBus: bus });
+    const makeReconciler = (store, maxConcurrent) => new Reconciler(store, { owner: `relayd-${process.pid}`, maxConcurrent, leaseMs: Number(value(argv, '--lease-ms', '300000')), adapters: [new ShellAdapter(), new CodexAdapter(value(argv, '--codex', 'codex')), new ChatGptAdapter({ endpoint: value(argv, '--macbridge-url') || undefined, tokenFile: value(argv, '--macbridge-token-file') || undefined })], continuations: [new CodexThreadContinuation(value(argv, '--codex', 'codex')), new CommandContinuation(), new WebhookContinuation()], planner: runtimePlanner(argv), eventBus: bus });
     const repositories = normalized.repository
         ? [normalized.repository]
         : (await discoverWorkspaceRepositories(normalized.workspaceRoot ?? defaultWorkspaceRoot())).map(item => item.repository);

package/dist/store.js

@@ -99,20 +99,35 @@ function repositoryParts(repository) {
 }
 async function headHasNoAheadCommits(client, repository, base, head) {
     const path = `repos/${repository}/compare/${encodeURIComponent(base)}...${encodeURIComponent(head)}`;
-    const comparison = await client.request(path);
-    return Number(comparison.ahead_by) === 0;
+    try {
+        const comparison = await client.request(path);
+        return Number(comparison.ahead_by) === 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (/404|Not Found/i.test(message))
+            return true;
+        throw error;
+    }
 }
-async function bootstrapEmptyHeadCommit(client, repository, head) {
+async function bootstrapEmptyHeadCommit(client, repository, base, head) {
     const { owner, name } = repositoryParts(repository);
-    const data = await githubGraphql(client, 'query($owner:String!,$name:String!,$qualified:String!){repository(owner:$owner,name:$name){ref(qualifiedName:$qualified){target{... on Commit{oid tree{oid}}}}}}', { owner, name, qualified: `refs/heads/${head}` });
+    const data = await githubGraphql(client, 'query($owner:String!,$name:String!,$head:String!,$base:String!){repository(owner:$owner,name:$name){head:ref(qualifiedName:$head){target{... on Commit{oid tree{oid}}}} base:ref(qualifiedName:$base){target{... on Commit{oid tree{oid}}}}}}', { owner, name, head: `refs/heads/${head}`, base: `refs/heads/${base}` });
     const repo = data.repository;
-    const ref = repo?.ref;
-    const target = ref?.target;
+    const headRef = repo?.head;
+    const baseRef = repo?.base;
+    const target = (headRef?.target ?? baseRef?.target);
     const tree = target?.tree;
     const expectedHeadOid = typeof target?.oid === 'string' ? target.oid : '';
     const treeOid = typeof tree?.oid === 'string' ? tree.oid : '';
     if (!expectedHeadOid || !treeOid)
-        throw new Error(`Unable to resolve head branch ${head}`);
+        throw new Error(`Unable to resolve head branch ${head} or base branch ${base}`);
+    if (!headRef) {
+        await client.request(`repos/${repository}/git/refs`, {
+            method: 'POST',
+            body: JSON.stringify({ ref: `refs/heads/${head}`, sha: expectedHeadOid }),
+        });
+    }
     const created = await client.request(`repos/${repository}/git/commits`, {
         method: 'POST',
         body: JSON.stringify({
@@ -167,7 +182,7 @@ export async function resolvePullRequest(client, repository, options) {
     if (!options.title)
         throw new Error('--title is required when creating a pull request');
     if (await headHasNoAheadCommits(client, repository, base, options.head)) {
-        await bootstrapEmptyHeadCommit(client, repository, options.head);
+        await bootstrapEmptyHeadCommit(client, repository, base, options.head);
         const afterBootstrap = await find();
         if (afterBootstrap)
             return afterBootstrap;
@@ -192,7 +207,7 @@ export async function resolvePullRequest(client, repository, options) {
             return raced;
         const message = error instanceof Error ? error.message : String(error);
         if (/No commits between|no commits between/i.test(message)) {
-            await bootstrapEmptyHeadCommit(client, repository, options.head);
+            await bootstrapEmptyHeadCommit(client, repository, base, options.head);
             const afterBootstrap = await find();
             if (afterBootstrap)
                 return afterBootstrap;

package/package.json

@@ -1,14 +1,29 @@
 {
   "name": "agents-relay",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
-  "bin": { "agents-relay": "dist/cli.js", "agents-relayd": "dist/relayd.js" },
+  "bin": {
+    "agents-relay": "dist/cli.js",
+    "agents-relayd": "dist/relayd.js"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/cli.js dist/relayd.js",
     "test": "npm run build && node --test test/*.test.js",
     "dev": "tsx src/cli.ts"
   },
-  "devDependencies": { "@types/node": "^22.10.2", "tsx": "^4.19.2", "typescript": "^5.7.2" },
-  "optionalDependencies": { "nats": "^2.29.0" }
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "optionalDependencies": {
+    "nats": "^2.29.0"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ]
 }

package/.github/workflows/publish.yml

@@ -1,91 +0,0 @@
-name: Build, test, and publish
-
-on:
-  push:
-    branches: [main]
-
-permissions:
-  contents: write
-
-concurrency:
-  group: npm-publish-main
-  cancel-in-progress: false
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          registry-url: https://registry.npmjs.org
-      - run: npm ci
-      - run: npm test
-      - run: chmod +x dist/cli.js dist/relayd.js
-      - name: Select next package version
-        id: version
-        shell: bash
-        run: |
-          error_file="$(mktemp)"
-          trap 'rm -f "$error_file"' EXIT
-          if current="$(npm view agents-relay version --registry=https://registry.npmjs.org 2>"$error_file")"; then
-            :
-          elif grep -q 'E404' "$error_file"; then
-            current=""
-          else
-            cat "$error_file" >&2
-            exit 1
-          fi
-          for attempt in 1 2 3 4 5; do
-            next="$(node scripts/npm-version.mjs "$current")"
-            if npm view "agents-relay@$next" version --registry=https://registry.npmjs.org >/dev/null 2>&1; then
-              current="$next"
-              continue
-            fi
-            break
-          done
-          if npm view "agents-relay@$next" version --registry=https://registry.npmjs.org >/dev/null 2>&1; then
-            echo 'Unable to find an unused npm patch version after five attempts' >&2
-            exit 1
-          fi
-          package_version="$(node -p "require('./package.json').version")"
-          if [ "$package_version" != "$next" ]; then
-            npm version "$next" --no-git-tag-version --ignore-scripts
-          else
-            echo "package.json is already $next; publishing the initial version without rewriting it."
-          fi
-          echo "version=$next" >> "$GITHUB_OUTPUT"
-      - name: Verify package contents
-        run: |
-          test -x dist/cli.js
-          test -x dist/relayd.js
-          npm pack --dry-run --json > pack.json
-          node -e 'const pack = require("./pack.json")[0]; const bins = new Map(pack.files.map(file => [file.path, file.mode])); for (const file of ["dist/cli.js", "dist/relayd.js"]) { if (bins.get(file) !== 0o755) throw new Error(`${file} is not executable in the package`); }'
-      - name: Publish package
-        shell: bash
-        run: |
-          set -o pipefail
-          publish_error="$(mktemp)"
-          trap 'rm -f "$publish_error"' EXIT
-          if npm publish --access public 2> >(tee "$publish_error" >&2); then
-            exit 0
-          fi
-          if grep -Eq 'EPUBLISH|previously published|cannot publish over' "$publish_error" \
-            && [ "$(npm view agents-relay version --registry=https://registry.npmjs.org 2>/dev/null || true)" = "${{ steps.version.outputs.version }}" ]; then
-            echo "agents-relay@${{ steps.version.outputs.version }} is already published; treating this run as idempotent."
-            exit 0
-          fi
-          exit 1
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-      - name: Tag published version
-        shell: bash
-        run: |
-          tag="v${{ steps.version.outputs.version }}"
-          if git ls-remote --exit-code --refs origin "refs/tags/$tag" >/dev/null 2>&1; then
-            echo "$tag already exists; leaving the existing release tag in place."
-            exit 0
-          fi
-          git tag "$tag"
-          git push origin "refs/tags/$tag"

package/AGENTS.md

@@ -1,16 +0,0 @@
-# Working on Agents Relay
-
-Agents Relay is a generic, shareable async-agent runtime and skill.
-
-## Principles
-
-- GitHub PR state is durable truth. Events are wake-up/observability signals, never durable truth.
-- Reconcile desired durable state into ephemeral worker executions.
-- One top-level objective maps to one PR; child tasks live inside that PR.
-- Agents may submit child tasks; task lineage is explicit.
-- Workers are replaceable and recoverable. Results and state must survive worker or daemon death.
-- Keep provider/model routing separate from roles and capabilities.
-- Prefer standard library and small dependencies; do not build a second database when GitHub already holds the durable state.
-- TypeScript must use explicit types and avoid `any`.
-- UI must remain usable without a frontend framework unless a framework becomes necessary.
-- Tests must cover state transitions, parser/serialization, reconciliation, and recovery-sensitive logic.

package/docs/agent-network.md

@@ -1,34 +0,0 @@
-# Agent Network enhancement
-
-## Objective
-
-Evolve Agents Relay from task adapters into a minimal network of independently registered, result-owning agents while retaining GitHub PR state as durable truth and preserving shell/Codex/ChatGPT worker support.
-
-## Scope shipped
-
-- Typed agent registration distinguishes identity, role/responsibility, boundaries, claimed capabilities, endpoint/runtime, availability, and routing metadata.
-- Trusted `agents-relay:agent:v1` markers persist registrations in the existing GitHub PR comment store; no second database is introduced.
-- `agent-register` and `agent-discover` are machine-driven CLI/core surfaces.
-- Discovery applies hard requirements first, then returns explainable evidence and a small policy ranking with optional exploration of unobserved agents.
-- Evidence models representative evaluations, historical outcomes, reliability inputs, latency, and cost without fabricating a universal score.
-- Documentation defines the single-orchestrator UX, durable task/lease/retry/reconciliation model, and a narrow future authenticated remote job/status contract.
-
-## Non-goals
-
-This PR does not build a public marketplace, broad multi-owner control plane, unauthenticated HTTP endpoint, private-data/credential routing, isolation/billing/trust enforcement, or automatic final agent selection. Adapters remain execution runtimes; events remain live observability and never durable truth.
-
-## Acceptance criteria
-
-- Existing task, scheduler, lease/recovery, continuation, dashboard, and ChatGPT adapter behavior remains green.
-- Agents can be registered and discovered from the same durable PR-backed store.
-- Discovery rejects unmet capabilities/runtime/trust/availability requirements and exposes evidence rather than an opaque score.
-- Registration and discovery work without a human web form.
-- The future remote surface is explicitly limited to authenticated create/submit and status operations, with intention-only/public jobs separated from private-data jobs.
-
-## Validation
-
-Run `npm test`, `npm run build`, and `git diff --check`. The implementation adds registry/discovery tests and store round-trip/forgery tests while retaining the existing test suite.
-
-## Future direction
-
-Add authenticated remote submission only when the host has a concrete identity and trust boundary. Then add durable remote task leases/heartbeats and recovery integration, richer evidence aggregation, policy-pluggable matching, and security/isolation gates for private jobs. Keep GitHub PR markers authoritative throughout.

package/docs/architecture.md

@@ -1,120 +0,0 @@
-# Agents Relay v1 architecture
-
-## Goal
-
-Provide a generic, shareable async agent job system where agents can submit durable child tasks, specialized workers execute them asynchronously, results are persisted, and the parent agent can continue when dependencies become ready.
-
-## Core model
-
-- **GitHub pull request** — durable top-level job container and audit surface.
-- **Job marker comment** — durable job metadata and continuation state.
-- **Task marker comments** — append-friendly durable child-task records.
-- **Agents Relay daemon** — reconciler, scheduler, dispatcher, lease/recovery manager, continuation engine, and dashboard server.
-- **Agent adapters** — pluggable execution backends such as Codex and shell commands.
-- **Event adapter** — optional low-latency notification/wake channel; events never replace durable PR state.
-- **Periodic watchdog** — low-frequency recovery sweep that re-reads durable PR/job state to repair missed wakeups and recover stale execution state (30 minutes with webhook mode by default; 5 minutes without webhooks for compatibility).
-- **Artifact references** — large/private outputs stay outside GitHub comments; task records store references.
-
-## Agent network slice
-
-An agent is a registered, result-owning worker/social role with a responsibility boundary. It is not the same thing as a skill (a callable capability) or an execution adapter (shell, Codex, or ChatGPT). Registration is machine-driven through the CLI/core API and is stored as a trusted `agents-relay:agent:v1` marker comment on the same PR.
-
-Registration records identity/name, role and responsibility, claimed capabilities, explicit boundaries/non-goals, endpoint/runtime, availability, and routing metadata. `agent-register` and `agent-discover` provide the smallest useful registry surface. Discovery applies hard filters first and returns observed evidence and reasons rather than a universal score. Evidence can include representative evaluations, outcomes, reliability, latency, and cost. `--explore` allows new/unobserved agents to be considered first; the orchestrator still owns the final choice.
-
-The registry does not yet execute remote agents or expose a public marketplace. A constrained ChatGPT/voice/mobile runtime should eventually use a small authenticated service surface with only `POST /jobs` (intention-only/public jobs) and `GET /jobs/:id`; credentials and private payloads must stay out of PR markers and events. Private-data/credential jobs, multi-owner trust, isolation, billing, and public discovery are future security-gated work.
-
-## Execution modes
-
-Jobs persist `executionMode` as `fixed` or `autonomous`; missing mode in legacy
-markers is read as `fixed`. Fixed is the default and keeps the v1 submit flow
-unchanged. Autonomous jobs use the existing task records and parent hierarchy:
-when all currently runnable work is settled and no planner task is active,
-reconciliation appends one durable `kind: "planner"` task. The planner returns
-typed `objective_status`, `assessment`, and `next_tasks` values. Each
-`next_tasks` item becomes a normal child task of that planner task.
-
-Stable task IDs and append-if-same-definition behavior make planner retries
-idempotent. Leases, owner recovery, and completion decisions remain in the
-reconciler; planner output never directly marks a job complete.
-
-## Reconciliation rule
-
-Every wake-up means only: "the durable state may have changed." The daemon reloads the PR and task records, derives desired actions, and reconciles actual execution state. It never advances a job solely because an event claimed something happened. Event-driven and periodic reconciles are single-flight within one process; a periodic sweep may create the next autonomous planner task only from durable settled state.
-
-## State
-
-Job states:
-
-OPEN -> RUNNING -> WAITING|BLOCKED -> COMPLETED|FAILED|CANCELLED
-
-Task states:
-
-QUEUED -> READY -> RUNNING -> WAITING|BLOCKED -> SUCCEEDED|FAILED|CANCELLED
-
-A task becomes READY when all declared dependencies have succeeded and any approval gate is satisfied. Autonomous completion additionally requires a durable planner result of `satisfied`, every planner/work task to be `SUCCEEDED`, and no unresolved failure or blocked task.
-
-## Task record
-
-Each task is one GitHub PR comment containing a human-readable summary plus a hidden `agents-relay:task:v1` JSON marker. Minimum durable fields:
-
-- task id and parent task id
-- dependencies
-- capabilities
-- adapter + execution input
-- routing decision for model-backed workers
-- state + attempt
-- lease owner and expiry
-- execution id/thread id
-- result summary and artifact references
-- timestamps
-
-Task submission is append-only at creation time, which avoids a single giant mutable manifest and makes agent-to-agent delegation natural.
-
-## Execution
-
-1. An agent submits a task to the PR.
-2. A task comment is created durably.
-3. The relay wakes and reloads the PR.
-4. Scheduler marks dependency-satisfied tasks ready.
-5. Dispatcher validates routing/capabilities and claims a lease.
-6. Adapter launches the worker.
-7. Worker reports progress over the optional event channel.
-8. Relay persists terminal task state/result back into the task comment.
-9. Relay reconciles dependents and/or resumes the parent continuation.
-10. Periodic watchdog reconciliation only repairs missed wake-ups and expired leases; webhook mode uses targeted reconciliation for the normal path and cached dashboard reads do not trigger broad discovery.
-
-## Continuations
-
-Continuations are adapters, separate from worker adapters. v1 supports Codex-thread continuation plus a generic command/webhook contract. Hosted web chat continuations may rely on their host integration; their durable state remains recoverable from the PR.
-
-## v1 acceptance criteria
-
-1. A reusable TypeScript package/CLI named `agents-relay`.
-2. GitHub PR/comment durable store with job/task marker parsing and updates.
-3. CLI to initialize a PR job, submit child tasks, inspect status, reconcile, retry/cancel tasks, and run the daemon.
-4. Dependency scheduling and nested parent/child lineage.
-5. Worker lease, expiry detection, recovery, retry, timeout, and cancellation semantics.
-6. At least Codex and shell worker adapters behind one adapter interface.
-7. Routing metadata is mandatory before a model-backed worker can launch.
-8. Optional event integration for wake-ups/progress with durable-state reconciliation.
-9. Parent continuation interface with Codex-thread continuation implemented.
-10. Dashboard web page showing jobs, task tree/state, worker/model, dependencies, results, leases, and live events/status.
-11. SSE or equivalent local live dashboard updates.
-12. Tests for marker parsing, state transitions, scheduling, reconciliation/recovery, and API/dashboard data.
-13. `skills/agents-relay/SKILL.md` plus supporting agent files describing how an agent submits async work, propagates lineage, consumes results, and treats events vs durable state.
-14. Documentation and a runnable local dogfood example.
-15. Browser-level verification of the dashboard before merge.
-
-## Non-goals for v1
-
-- Reimplement GitHub as a database.
-- Build a general workflow-language/DAG editor.
-- Require Redis, Postgres, Temporal, or Kubernetes.
-- Make NATS mandatory.
-- Implement a hosted multi-tenant control plane.
-- Encode domain-specific agent roles in the core runtime.
-- Build a broad public agent marketplace or unauthenticated remote HTTP API.
-
-## Dogfood
-
-This PR is the first top-level Agents Relay job. Development, review, fixes, and verification remain on this PR until the v1 acceptance criteria are met.

package/docs/autonomous-objective-jobs.md

@@ -1,121 +0,0 @@
-# Autonomous Objective-Driven Jobs
-
-This document records the design, implementation flow, recovery semantics, and validation of autonomous objective-driven jobs in Agents Relay.
-
-## Objective
-
-Existing jobs remain `fixed` by default. An `autonomous` job may grow its own durable task tree until the objective is satisfied. Planning is represented by real tasks rather than hidden generations or a second state store. GitHub-backed durable state remains authoritative.
-
-## Design principles
-
-- `executionMode` is explicitly `fixed` or `autonomous`; legacy jobs deserialize as `fixed`.
-- A planner is a real durable task (`kind: planner`) in the same parent/subtask hierarchy as execution work.
-- Reconciliation owns liveness: it decides when another planner is required, including after daemon restart or a missed wake-up.
-- The planner owns reasoning: it returns `objective_status`, an assessment, and typed `next_tasks`.
-- The default planner is the installable `skills/agents-relay/agents/planner.agent.md` agent contract shipped with the npm package; runtime command configuration is only an override.
-- `in_progress` creates durable child work; `satisfied` stops growth but does not bypass normal completion gates.
-- Failed or blocked work prevents autonomous completion and prevents blindly creating another planning round.
-- Planner and generated task creation are idempotent so repeated reconciliation does not duplicate work.
-
-## Autonomous lifecycle
-
-```mermaid
-flowchart TD
-    A[Job created] --> B{executionMode}
-    B -->|fixed| C[Existing fixed-job scheduler]
-    B -->|autonomous| D[Reconciliation]
-    D --> E{Runnable execution work?}
-    E -->|yes| F[Run durable tasks]
-    F --> D
-    E -->|no| G{Failed or blocked work?}
-    G -->|yes| H[Remain open for recovery]
-    G -->|no| I{Active planner?}
-    I -->|yes| J[Wait for planner outcome]
-    I -->|no| K[Create durable planner task]
-    K --> L[Run planner]
-    L --> M{objective_status}
-    M -->|in_progress| N[Create typed child tasks]
-    N --> D
-    M -->|satisfied| O[Existing completion gates]
-    O -->|pass| P[Eligible for normal completion]
-    O -->|fail| H
-```
-
-## Durable hierarchy
-
-Planning causality is visible directly in the existing task tree. No wave/generation abstraction is introduced.
-
-```mermaid
-graph TD
-    J[Autonomous Job] --> P1[planner-1]
-    P1 --> T1[implementation task]
-    P1 --> T2[test task]
-    P1 --> P2[planner-2]
-    P2 --> T3[remediation task]
-    P2 --> P3[planner-3: satisfied]
-```
-
-Each planner result is persisted with its assessment and generated work. Stable generated task IDs plus durable append semantics make replay safe.
-
-## Reconciliation and restart recovery
-
-The daemon does not depend on a planner remembering to schedule its successor. Reconciliation reconstructs the next action from durable state.
-
-```mermaid
-sequenceDiagram
-    participant W as Webhook/Startup/Watchdog
-    participant R as Reconciler
-    participant S as Durable Store
-    participant P as Planner
-    participant X as Worker
-    W->>R: wake/reconcile
-    R->>S: load job + task tree
-    alt lost or expired execution lease
-        R->>S: reclaim to READY or terminal failure
-    end
-    alt autonomous subtree settled
-        R->>S: append planner task idempotently
-        R->>P: execute planner
-        P-->>R: in_progress + next_tasks
-        R->>S: persist planner result + child tasks
-        R->>X: launch READY child work
-    else objective satisfied
-        R->>S: persist satisfied planner result
-        R->>R: apply normal completion gates
-    end
-```
-
-A restarted daemon can reclaim a durable planner lease owned by the previous runtime. Repeated reconciliation observes existing planner/task markers instead of creating duplicate work.
-
-## Completion semantics
-
-Planner satisfaction is evidence about the objective, not authority to close the job. The existing job lifecycle remains authoritative. An autonomous job can stop growing only after a planner reports `satisfied`; it can complete only when the normal completion conditions also allow it. Failed or blocked tasks remain visible and prevent accidental success.
-
-## Compatibility and surfaces
-
-Fixed jobs retain their previous scheduling behavior. Execution mode and planner state are serialized in durable markers, exposed through CLI/status data, and surfaced in the dashboard. Legacy markers without an execution mode are interpreted as `fixed`.
-
-## Implementation sequence
-
-```mermaid
-flowchart LR
-    A[Add durable execution mode] --> B[Add planner result/task model]
-    B --> C[Integrate planner with reconciler]
-    C --> D[Add idempotent child creation]
-    D --> E[Add restart recovery]
-    E --> F[Expose CLI/status/dashboard]
-    F --> G[Update documentation]
-    G --> H[Build + full test suite]
-```
-
-## Validation
-
-The completed branch was validated with `npm test`, which runs the TypeScript build before the Node test suite. Final result on 2026-09-19:
-
-- TypeScript build: passed.
-- Tests: **108 passed, 0 failed, 0 skipped/cancelled**.
-- Focused coverage includes marker round-trip and legacy defaults, fixed-job compatibility, autonomous task-tree growth, stable/idempotent generated task IDs, restart planner-lease recovery, objective satisfaction, and failed/blocked completion gates.
-
-## Follow-up
-
-GitHub API quota exhaustion prevented managed PR bootstrap during this implementation. The feature was therefore completed and validated on `feat/autonomous-objective-jobs`; managed PR/job bootstrap can be retried after quota recovery. The next P0 work is intentionally separate: GitHub App authentication and reducing residual GitHub API consumption while retaining webhook-driven targeted reconciliation.

package/docs/example.md

@@ -1,30 +0,0 @@
-# Local dogfood
-
-```sh
-npx agents-relay init --file /tmp/agents-relay.json --id dogfood --title "Local dogfood"
-npx agents-relay submit --file /tmp/agents-relay.json --task-id build --input "echo build" --adapter shell
-npx agents-relay reconcile --file /tmp/agents-relay.json
-npx agents-relay status --file /tmp/agents-relay.json
-```
-
-Autonomous local jobs use the same file and task tree. The mode is durable and
-defaults to fixed:
-
-```sh
-npx agents-relay init --file /tmp/agents-relay-auto.json --id auto --title "Objective" --mode autonomous
-npx agents-relay reconcile --file /tmp/agents-relay-auto.json --planner-command ./planner.sh
-npx agents-relay status --file /tmp/agents-relay-auto.json
-```
-
-`planner.sh` reads the current objective/task snapshot from stdin and prints a
-typed planner result. Its `next_tasks` IDs must remain stable across retries.
-
-For a nested task, submit `--parent build --deps build`; reconciliation releases it only after `build` succeeds.
-
-The same flow against the dogfood PR is:
-
-```sh
-npx agents-relay init --repo lalalic/agents-relay --pr 1 --id agents-relay-dev-20260918-1302 --title "Dogfood"
-npx agents-relay submit --repo lalalic/agents-relay --pr 1 --id agents-relay-dev-20260918-1302 --task-id safe-shell --input "printf dogfood" --adapter shell --capabilities shell
-npx agents-relay reconcile --repo lalalic/agents-relay --pr 1 --id agents-relay-dev-20260918-1302
-```