pi-goal-expander

Grok-style goal harness for Pi: expand a rough objective into a frozen plan, drive multi-turn pursuit, and harness-own verification so the model cannot self-certify.

Optional soft integration with @clanker-code/pi-subagents / upstream for planner/skeptic roles (degrades without it).

Install

pi install npm:pi-goal-expander
# local:
# pi install /path/to/pi-goal-expander
# pi install git:github.com/clankercode/pi-goal-expander

Smoke:

pi -ne -e ./src/index.ts

Surfaces

| Surface | Purpose | |---------|---------| | /goal <objective> | Start harness (research → expand plan → execute) | | /goal-expand <text> / /goal expand <text> | Same as /goal (starts harness) | | /goal status \| pause \| resume [--takeover] \| clear \| help | Lifecycle + help | | update_goal tool | message / completed / blocked_reason | | goal_expand tool | Same as /goal for the model |

Session ownership

Each active goal is owned by the Pi session that created it, scoped to that repository's .pi/goal/ state. Other top-level sessions in the same repository are read-only and do not restore the goal or receive goal injections. Plain /goal resume never takes another session's goal; use /goal resume --takeover only for a deliberate handoff. Ownership includes a 15-minute diagnostic lease, but lease expiry never transfers a goal automatically.

How it works

1. Start — create goal state under .pi/goal/<id>/, inject a slim goal_set notice while the planner runs, then write plan.md (planner subagent if available, else structural draft on disk only). When pi-subagents is available, the planner spawn sets inheritContext: true (session fork / parent conversation inheritance) and also hands off a compact parent-branch transcript into the planner prompt when sessionManager.getBranch() is available — so the planner sees prior chat/research, not only the objective string.
2. Execute kickoff — short message with objective + plan/evidence paths + steps (triggerTurn: true). The full plan body stays on disk; kickoff does not paste the draft skeleton into the transcript
3. Execute — agent reads/rewrites plan.md as needed, works the checklist, keeps evidence/index.md filled
4. Verify — update_goal({ completed: true }) runs pre-verify + evidence-index gate (bias: not achieved without proof), then a blocking skeptic panel when pi-subagents is available (spawn → wait → aggregate before Achieved)
5. Continue / stall / complete — gaps replayed; same gap fingerprint twice → pause; verify cap → pause; success → receipt + user-visible completion summary (reload hint)

Statusline: ◎ plan · ◎ plan <agentId> (while planning) · ● active · 🔬 verify · ⏸ pause · ✓ done

Progress milestones

While executing, call update_goal({ message }) at least for:

• researched — codebase/context research done
• implementing — implementation underway
• pre-complete — work done, about to request verify

Optional mid-checklist notes are fine. History stores these as typed progress events.

Lifecycle events

The harness emits custom session messages (customType: pi-goal-expander:event, usually display: false) with a details.kind field. Useful for dogfood logs and dashboards.

| kind | When | |--------|------| | session_restore | Active goal reloaded on session_start when the current Pi session owns it | | goal_set | Goal created; planner may still be running (display message) | | planning_started | Phase → planning | | planning_completed | Plan written; phase → executing | | planning_failed | Planner hard-failed | | goal_start | Execute kickoff injected | | progress | update_goal({ message }) logged | | verify_started | Verify round begins (may re-emit with panel agentIds) | | verify_not_achieved | Verify failed; gaps recorded | | verify_achieved | Verify passed | | goal_completed | Goal status complete (after verify_achieved) | | verify_paused | Verify cap hit → pause | | paused / resumed / cleared | /goal pause\|resume\|clear | | blocked_attempt | update_goal({ blocked_reason }) | | goal_complete_summary | User-facing completion blurb (pi-goal-expander:complete, display true) |

Verify policy (goal kind → skeptic N)

Panel size is derived from plan.md Goal kind (see src/loop/verify-policy.ts):

| Goal kind | Default skeptic N | |-----------|-------------------| | analysis / research | 1 | | code-change | 3 | | missing / unknown | config skepticN (default 3, clamp 1–5) |

Config skepticN is the fallback when kind is absent, not a hard override of kind defaults. Kind is read from the ## Goal kind section of the active plan at completed:true time.

Panel timeout / infra policy

| Condition | Outcome | |-----------|---------| | No event bus / pi-subagents ping fails | Degraded path — Achieved only if preverify + evidence gates pass (no false “panel passed”) | | Bus alive but all spawns fail, all waits timeout, or no usable verdict text | Fail-closed — NotAchieved with gap verifier panel unavailable | | Partial verdicts | Aggregate what arrived (parseVerifierVerdict + aggregateVerdicts, bias-to-refute; malformed/empty = refute) |

Per-skeptic wait uses config subagentsTimeoutMs (default 600s). The panel is on the critical path: verify_achieved is not emitted until wait+aggregate finish or the fail-closed policy applies.

Planner timeout / degrade policy

| Condition | Outcome | |-----------|---------| | No bus / pi-subagents ping fails | Degraded structural draft (when soft mode); kickoff notes the real reason (ping_failed / unavailable) | | Planner spawned but wait times out | Fail-closed — planning_failed, goal user_paused; planner agent stopped; no execute kickoff; no draft baseline as “success” | | Structural draft write | Never overwrites a non-draft plan.md already on disk |

Planner wait uses config plannerTimeoutMs (default 30m), separate from panel subagentsTimeoutMs (default 10m). Lifecycle events planning_completed / planning_failed include plannerReason (ok | no_bus | ping_failed | wait_timeout | spawn_error | agent_failed | structural_fallback).

Completion UX

On Achieved the harness emits a user-visible notify + display summary (pi-goal-expander:complete) with objective, receipt path (when receipts enabled), and a generic reload hint (/reload if UI settings look stale). That is the last goal-owned UI action for the goal; further continuation / next-step injects for that goalId are suppressed. Other extensions may still emit after; the goal harness itself stays quiet.

Goal state location vs edit scope

| What | Where | |------|--------| | Goal store (plan.md, state.json, evidence/, receipts) | <cwd>/.pi/goal/<id>/ by default | | Override store root | PI_GOAL_ROOT (absolute path used as the goal root) | | Override cwd used for store resolution | PI_GOAL_CWD (falls back to extension ctx.cwd, then process.cwd()) |

Edit scope is not limited to the goal store. Objectives often name files outside the session cwd (e.g. ~/.pi/agent/settings.json). Agents should treat .pi/goal/ as harness bookkeeping only; allowed write targets follow the objective.

Evidence

Before completion succeeds, write:

.pi/goal/<id>/evidence/index.md

| Criterion | Artifact | Notes |
|-----------|----------|-------|
| 1 | tests/foo.test.ts | … |
| 2 | json:path/to/settings.json#powerline.cost.subscriptionDisplay=reported-cost | config assert |

Artifact forms

• Path — any path-like string is checked for existence (tests/…, src/…, absolute paths).
• JSON assert — json:<filePath>#<dotted.path>=<expected> reads the file, walks the dotted path, and requires an exact value match. Completion fails if the assertion fails even when the file exists (useful for config/settings goals).

Draft plan gate: update_goal(completed:true) returns NotAchieved with plan not expanded beyond draft if plan.md still matches the structural expand skeleton. Rewrite the plan with real criteria before completing.

Development

npm install
just check

Harness contract test (tests/harness-contract.test.ts): memory bus + installMockSubagentsRpc asserts the dogfood event order goal_set → planning events → goal_start → verify_started → complete (no live LLM).

Release

See RELEASE.md:

just release patch   # or minor | major | 0.2.0

Design

docs/superpowers/specs/2026-07-20-goal-harness-design.md

License

Unlicense (public domain).