@hank-warren/pi-loop 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @hank-warren/pi-loop
 
+## 0.9.0
+
+### Minor Changes
+
+- 897739d: Framed approval card, fresh-session launch, and a loop-safe permission posture.
+
+  **pi-loop**
+
+  - The approval card is now a framed `customType` transcript block, emitted once per draft, with its choices in an action menu. It used to go out twice and neither copy was a card: `loop_propose` returned it as tool-result markdown (re-spending the objective's tokens in the model's own context) and `/loop` re-printed it as a toast.
+  - `startLoop` is split into `buildLoop` and `installLoop`, and the menu gains **Start loop in a fresh session** — the loop is built in the planning session and installed in a new one, so only the objective crosses and the drafting conversation does not.
+  - A loop publishes `PI_LOOP_ACTIVE=1` and `PI_LOOP_ID` on the process while active. This is a contract for other extensions, mirroring `PI_SUBAGENT_CHILD`: no import, no dependency, no RPC.
+  - The autonomy posture is reconciled with it. Reshaping a command to get _around_ a permission gate stays forbidden; revising it to satisfy a concern a guardian actually stated is legitimate and bounded. The `⚠ loop blocked` detector is unchanged.
+
+  **pi-auto-permissions**
+
+  - While `PI_LOOP_ACTIVE=1`, an `ask_user` verdict returns the guardian's concern to the agent as a non-blocking block instead of opening a modal. A session waiting on a modal is busy, and a busy session starves a loop's continuation path — the prompt would not be answered, it would deadlock the loop until it expired. **The verdict is unchanged; only its delivery is.** The absence of a user is never authorization.
+  - Revision is bounded — per concern, per gate, and by consecutive blocked attempts — after which the block names `loop_wait` instead of inviting another try. The bounds survive a compaction and a session restore.
+
+  Detection is fail-open in both directions: with the environment variables absent, behaviour is exactly as before, and neither package requires the other.
+
+## 0.8.0
+
+### Minor Changes
+
+- 2a04a46: Plan mode, a ledger write tool, and a widget that shows progress.
+
+  **Breaking: `/schedule` is removed.** It lived here because the machinery was the same
+  machinery — an idle-gated delivery path, coalescing, caps, an expiry. True, and still the
+  wrong home: a loop pursues one objective until it is done and then stops, while a schedule
+  fires forever on a clock. Persisted tasks in `~/.pi/agent/loop/schedules.json` are no longer
+  read and the `schedules.lease` lockfile is no longer taken.
+
+  **`/loop` now opens planning.** With nothing running it starts a drafting conversation
+  instead of printing "No loop in this session". The model drafts the objective as an
+  acceptance test, then calls the new `loop_propose` tool, which renders an approval card
+  showing the exact criteria the split will produce, the cadence and the caps — and starts
+  nothing. You start it, change the cadence, keep editing, or cancel. The criteria used to be
+  frozen before anyone had ever seen them; the card is the moment they can still be fixed.
+  `/loop 30m <objective>` and inline `loop:` are unchanged.
+
+  **Fixed: a wrapped bullet silently truncated its criterion.** `deriveCriteria` kept lines
+  carrying a bullet marker and discarded the rest, so a bullet longer than a terminal width
+  lost everything after its first line — while the criterion still looked well-formed. The
+  acceptance gate was quietly weakened to whatever survived, with no signal.
+
+  **New `loop_progress` tool, the only supported ledger write path.** The ledger is the one
+  thing that survives compaction, and the model was told to maintain it with no tool to do so,
+  so it reached for a shell heredoc — and one `cat > PROGRESS.md` replaced the objective line,
+  the other sections and every failed-approach note. `loop_progress` edits one section and
+  leaves every other byte alone, and marks a criterion met with the citation that justified
+  it, stored alongside it. Only `passes` ever changes, now by construction rather than by
+  prose in a skill file.
+
+  **A blocking prompt no longer deadlocks the loop invisibly.** A session waiting on a modal
+  is `busy`, which makes every continuation and every fallback tick skip; no turn completes,
+  so the cap never trips and the no-progress breaker never fires. Expiry was the only thing
+  left — up to seven days — while the widget showed a next-wake time throughout. Loops now
+  carry an autonomy posture (decide and record rather than ask, `loop_wait` as the only
+  non-deadlocking way to ask, never reshape a command to get past a permission prompt, prefer
+  the undoable), and a run left open past fifteen minutes flips the widget to an attention
+  state. The loop never answers the prompt.
+
+  **The widget was redesigned around progress.** It led with the interval — a fallback
+  heartbeat a settle-paced loop may never deliver — and reported turns against the cap, which
+  is budget burn. Criteria met over total now leads, with the turn budget, the loop's age and
+  the next wake after it. The widget and the footer render the same function: they had drifted,
+  so a loop waiting on CI showed an ordinary next-wake time above the editor while the footer
+  said it was waiting, and a paused loop dropped the cause that `/loop status` printed.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -128,6 +128,23 @@ The turn a wake delivers for an elapsed wait **counts against `maxTurns`** like
 
 There is deliberately **no cancel tool**. The events that legitimately cancel a wait (you typing, an earlier wake arriving) are not the model's to report — so when one of them ends a wait, its reason rides along once on the next loop message as `Previous wait (cancelled): …` and is then dropped.
 
+## Working unattended, and the `PI_LOOP_ACTIVE` contract
+
+The posture in the system append is stated as mechanics rather than as rules to obey, because the mechanics are the reason: a session waiting on a modal is *busy*, and busy makes every continuation and every fallback tick skip. Nothing ends the loop until it expires. So: decide rather than ask, take the reversible path, record the decision in the ledger, and use `loop_wait` — the one way to ask that does not deadlock the session.
+
+The subtle half is what to do with a *blocked* command. Reshaping one to get **around** a permission gate — splitting it up, obfuscating it, routing it through another tool, retrying variations until one is allowed — is forbidden outright, and it is the dangerous failure precisely because it *looks like progress*. But a guardian that blocks with a specific objection is naming something to fix, and fixing exactly that is the response it asked for. Treating every block as terminal would have made the loop stop at objections that named a one-word remedy.
+
+What separates the two is a bound, which is why pi-loop publishes its state to the process while a loop is active:
+
+| Variable | Meaning |
+| --- | --- |
+| `PI_LOOP_ACTIVE` | `1` while a loop is active; absent otherwise (a paused or stopped loop withdraws it) |
+| `PI_LOOP_ID` | the loop's id, so a reader can tell one loop from the next |
+
+This is a contract for other extensions, deliberately the same mechanism `pi-subagents` established with `PI_SUBAGENT_CHILD=1` — an environment variable, not an import, not a dependency, not an RPC. [pi-auto-permissions](https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-auto-permissions) is the first consumer: while it is set, a guardian verdict that would have opened a modal instead returns the concern to the agent as a block, carrying a bounded number of revision rounds and then naming `loop_wait`. Nothing is approved that would not have been approved with a user present; only the delivery changes. Neither package needs the other installed, in either direction.
+
+The `⚠ loop blocked` widget state remains, unchanged, as the backstop: it catches prompts from extensions pi-loop cannot influence, where there is no contract to read.
+
 ## Breakers
 
 - **No progress.** The characteristic failure of an autonomous loop is not crashing, it is *restating*: the same paragraph of "here is what I would do next", turn after turn, calling no tools. pi-loop fingerprints the visible assistant text (SHA-256 over NFKC-normalised, case- and whitespace-folded text) of every tool-free loop-caused turn; `noProgressTurns` consecutive repeats (default 3, settings-tunable, `null` disables) **pause** the loop rather than stopping it — it stays configured, the widget says why, and `/loop resume` or your next message continues it with a fresh safety epoch. A turn that called **any** tool, including `loop_wait`, is progress by definition and resets the counter; counting a declared wait is the false positive that made this class of breaker infamous.
@@ -156,42 +173,6 @@ Long loops die by context exhaustion, not by failing. pi-loop owns the compactio
 - **Loop-owned re-anchor**: when a compaction completes mid-loop, pi-loop dispatches one pointer-sized continuation at the next settle — re-read `PROGRESS.md` and `criteria.json`, continue from authoritative state, plus the next 1-3 actions lifted out of the summary that just replaced the conversation. The loop no longer goes quiet until the next wake. A re-anchor supersedes an ordinary continuation already queued: after a compaction, "re-read the ledger" is strictly the better instruction.
 - Loop state itself lives in custom session entries, which compaction never touches, and survives session restarts (the timer re-arms on resume; expired loops are dropped with a notice).
 
-## `/schedule`: recurring prompts and headless runs
-
-The same extension also schedules work, because the machinery is the same machinery: an idle-gated delivery path, coalescing, caps, and an expiry.
-
-```
-/schedule                                        manager TUI
-/schedule list
-/schedule every 30m check the release queue      in-session prompt, every 30 minutes
-/schedule at +2h remind me to cut the RC         once, two hours from now
-/schedule at 2026-01-31T09:00 monthly report     once, at an ISO timestamp
-/schedule cron "0 9 * * 1" weekly triage         Monday mornings
-/schedule every 6h --run --cwd /srv/app sync     headless `pi -p` run
-/schedule pause|resume|run|status|delete <id>
-```
-
-Flags: `--run` (headless instead of in-session), `--cwd <path>`, `--max <n|unlimited>`, `--wake always|failure|success|never`, `--name <text>`.
-
-**Two task kinds, deliberately different lifetimes:**
-
-- **`prompt`** injects a prompt into the owning session, delivered exactly like a loop wake — only at a settled idle boundary, queued while the agent is busy. It is **session-scoped**: it lives in memory and dies with the session, because a prompt with no session to arrive in is not a task, it is a leak.
-- **`run`** spawns a headless `pi -p "<prompt>"` in a working directory, tees stdout and stderr to `~/.pi/agent/loop/runs/<task-id>/<timestamp>.log`, and records the exit code. It never touches the conversation unless `wakeOn` says to report back (default: only failures). These are the only tasks persisted, in `~/.pi/agent/loop/schedules.json`.
-
-  A headless run is a **fresh `pi` invocation**, so it uses your *default* model and settings, not the model the scheduling session happens to be using. If a run needs a specific model, say so in the prompt's environment — or check the run log, which records the command, cwd, prompt, and exit code precisely so a surprise like this is one `cat` away.
-
-**One fire per occurrence, not one per open session.** Headless firing is arbitrated by a lockfile lease (`schedules.lease`) holding a pid and a heartbeat: without it, a task scheduled for 09:00 fires once in every Pi session that happens to be open. A holder that dies stops renewing and the next session takes over after 90 seconds. It is not a distributed lock — the failure it must prevent is duplicate work, and the worst it can produce is one skipped tick.
-
-**Missed occurrences coalesce into a single fire.** A laptop asleep for a weekend wakes to one catch-up, never one turn per missed interval.
-
-**Every task is bounded twice**: `maxRuns` (default 25, `--max unlimited` is an explicit opt-in) and a hard 90-day expiry.
-
-**Cron** is five numeric fields at minute granularity (`minute hour day-of-month month day-of-week`), supporting `*`, `n`, `a-b`, `a,b`, and `/step`. No names, no `@daily`, no seconds, no timezones beyond the host's local clock — each of those is a place where two implementations disagree, and a scheduler with debatable semantics is worse than one that refuses the expression. When both day fields are restricted, a day matching *either* fires, as in every crontab in the world.
-
-`/schedule` is **user-typed only**, exactly like `/loop`: the model gets no scheduling tools. A model that can schedule its own future turns can schedule its way around every limit the loop imposes.
-
-> **Never co-install [`@jl1990/pi-scheduler`](https://www.npmjs.com/package/@jl1990/pi-scheduler).** Both register `/schedule`; the commands and the concepts collide.
-
 ## Settings
 
 `~/.pi/agent/pi-loop.json` (absent file = defaults, never created implicitly; saves are atomic and preserve unknown fields), or `/loop settings`:
@@ -223,7 +204,7 @@ These were considered and cut, and the reasoning is recorded so they are not sil
 
 ## The companion skill
 
-The package is a hybrid: it ships the extension **and** a `pi-loop` skill (`skills/pi-loop/SKILL.md`), which carries the judgment the engine cannot encode — how an objective becomes falsifiable criteria, what the evidence gate accepts as a citation, when to declare a `loop_wait` instead of polling, what `PROGRESS.md` is worth, and when the work belongs in `/schedule` or in no loop at all.
+The package is a hybrid: it ships the extension **and** a `pi-loop` skill (`skills/pi-loop/SKILL.md`), which carries the judgment the engine cannot encode — how an objective becomes falsifiable criteria, what the evidence gate accepts as a citation, when to declare a `loop_wait` instead of polling, what `PROGRESS.md` is worth, and when the work belongs in no loop at all.
 
 It is **loaded on demand**: one line in each of `loop_start` and `loop_complete`'s prompt guidelines points at it by name, exactly as `pi-processes` does, and the model reads the body when it judges it needs it. Nothing about the guidance enters a stored loop message or the system append — those bytes are the cache prefix, and `test/bytes.test.ts` fails if any of them so much as mentions a skill.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-loop",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Long-running work for Pi: settle-paced loops with a durable ledger, adaptive waits, no-progress breakers, evidence-gated completion, and a task scheduler.",
   "type": "module",
   "keywords": [
@@ -47,5 +47,8 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
+  },
+  "dependencies": {
+    "@narumitw/pi-tui-kit": "^0.49.3"
   }
 }

package/skills/pi-loop/SKILL.md

@@ -70,6 +70,56 @@ c2: "gh pr checks 171 → all 3 checks passed (ci/gate, ci/typecheck, ci/scan-se
 
 Audit requirement by requirement before calling it, and match the verification scope to the requirement scope: a criterion about the whole suite is not proven by one test file. **Effort exhaustion is not completion** — running long, running out of ideas, or nearing a cap is never a reason to call the tool. If the criteria are not met, keep working; another continuation is coming.
 
+## A loop runs unattended, so a question is a deadlock
+
+Outside a loop, asking the user costs a few seconds of their attention. Inside one they are not
+there by construction, and the cost is not a slow answer — it is the loop's death.
+
+A session blocked on a modal prompt is **busy**, and `busy` is the third test in the decision
+prefix both drivers share:
+
+```
+loop liveness -> expiry -> plan mode -> compaction -> busy -> wait -> the turn cap -> act
+```
+
+So `agent_settled` never fires and no continuation is queued; every fallback tick returns
+`skip: agent-busy`; `automaticTurns` never increments, so the turn cap never trips; and the
+no-progress breaker needs tool-free *turns*, of which there are none. **Expiry is the only thing
+left, up to seven days later** — and the widget shows the next wake time the whole time.
+
+This is why the guidance is a posture rather than a list of forbidden tools. Your other
+extensions are unknowable and a blacklist goes stale the moment one of them ships a new prompt.
+The rule follows from the mechanics instead:
+
+1. **Decide, do not ask.** Take the reversible option, write the decision *and the reasoning*
+   into `PROGRESS.md`, and keep going. The user reads it when they return and the loop never
+   stopped. A decision recorded beats a question unanswered.
+2. **`loop_wait` is the loop-safe form of asking.** It is the one way to say "I need a human"
+   that does not deadlock: continuations stop, the reason shows in the widget and `/loop status`,
+   and any wake resumes it. Use it exactly where you would otherwise open a modal, and put the
+   options in the ledger first so the answer can be one word.
+3. **Never reshape a command to get *around* a permission gate.** This is the dangerous one. An
+   agent under a turn cap has real incentive to rewrite a blocked command into something the
+   guardian waves through, and that failure *looks like progress*. Splitting the command up,
+   obfuscating it, routing it through a different tool, or simply retrying variations until one
+   is allowed are all the same move, whatever the loop's state.
+
+   Addressing a stated concern is not that move. A guardian that blocks with a specific
+   objection — pi-auto-permissions does exactly this while `PI_LOOP_ACTIVE=1`, because a modal
+   would deadlock the loop — is naming something to fix, and fixing precisely that is the
+   response it asked for. The bound is what keeps the two apart: the block tells you how many
+   revision rounds remain against that concern, and when they run out it stops offering the
+   option and names `loop_wait` instead. A block that states no concern you can address is
+   already final; do not spend the rounds on it.
+4. **Prefer the undoable.** Nobody is watching to catch a bad call, so when two paths are close,
+   take the one that is cheap to reverse: a worktree over the clone, additive over destructive, a
+   draft pull request over a merge.
+5. **Ask only when proceeding is irreversible *and* the choice is load-bearing.** Then use
+   `loop_wait`, not a prompt.
+
+Autonomy is not permission to be reckless. It is the opposite: the absence of a human in the loop
+is exactly why the reversible path is the right default.
+
 ## Waiting on the world
 
 When progress depends on something outside the session — a CI run, a deploy, a human reply — call `loop_wait` with a one-sentence reason. Do not spend continuations re-checking, and never sleep in a shell to pass time.
@@ -87,7 +137,9 @@ The ledger lives at `~/.pi/agent/loop/<loop-id>/`, and `PROGRESS.md` has four fi
 
 The failed-approaches section carries the most value, because it is the only thing that survives compaction and the only thing that stops the next continuation — or the next engineer — from re-running an experiment that already failed. "Tried X, it failed because Y" is the whole point; "tried several things" is worth nothing.
 
-`criteria.json` sits next to it. You may flip an entry's `passes` field when authoritative evidence proves it, citing that evidence in `PROGRESS.md`. You may **never** add, remove, reword, or re-id an entry: a model that can rewrite its acceptance criteria eventually rewrites them into something it has already achieved.
+Write both files with the **`loop_progress`** tool, never with the file or shell tools. `loop_progress` edits one section and leaves every other byte alone; a whole-file write takes out the objective line, the other three sections, and however many days of failed-approach notes were in them. That is not a hypothetical — it is what a `cat > PROGRESS.md <<EOF` does on the first ledger update, and `createLedger` opens the file with `flag: "wx"` precisely so the engine can never do it.
+
+`criteria.json` sits next to it. Mark an entry met with `loop_progress`, which flips `passes` and stores the citation that justified it alongside the criterion, where `loop_complete` can be held to it later. Only `passes` ever changes: you may **never** add, remove, reword, or re-id an entry, and never hand-edit the file. A model that can rewrite its acceptance criteria eventually rewrites them into something it has already achieved.
 
 Both files are best-effort. If the ledger could not be created the loop still runs; it just has no memory outside the conversation.
 
@@ -103,7 +155,7 @@ The interval is a fallback heartbeat, not the pacemaker — the loop advances wh
 
 An inline invocation *permits* a loop; it does not oblige you to start one. When the work is a bad fit, say so in one line and offer the alternative instead:
 
-- **Recurring cadence** ("check the release queue every morning") → `/schedule`, which owns cron, one-shots, and headless runs. A loop pursues one objective until it is done; it is not a timer.
+- **Recurring cadence** ("check the release queue every morning") → not a loop. A loop pursues one objective until it is done and then stops; it is not a timer, and an objective that is never "done" only produces turns until a cap. Use whatever scheduling your setup provides.
 - **Genuine open exploration** ("figure out why memory grows") → do the investigation in the conversation. A loop's value is the gate at the end; an investigation has no end state to gate on, so the loop only supplies unwanted turns. Once the investigation names a fix, *that* is a loop objective.
 - **Work that finishes this turn** → just do it, and say why no loop was needed.
 

package/src/fresh-launch.ts

@@ -0,0 +1,128 @@
+/**
+ * Starting an approved loop in a fresh session.
+ *
+ * A loop started interactively owns the session it was planned in, and the
+ * planning conversation is the worst possible context for it: every turn of
+ * drafting is carried, re-read and re-billed for the whole run, and none of it
+ * is the objective. The card is where that gets fixed, because the card is
+ * where the user is already deciding how the loop should run.
+ *
+ * Modelled on `packages/pi-plan-mode/src/fresh-implementation.ts`, which
+ * solves the same problem for a plan. The difference is what crosses: a plan
+ * hands over a file path, while a loop hands over its state, appended to the
+ * new session in `setup` exactly as `persist` would have appended it here.
+ * Only the objective and the caps cross; the drafting conversation does not.
+ *
+ * The ledger is written before the handoff, from this session. It is a
+ * filesystem artifact keyed by loop id, not session state, and writing it here
+ * is what makes the approved criteria authoritative: the restoring session
+ * treats whatever is already on disk as the truth, so criteria written after
+ * it restores would arrive too late to be the ones it is held to.
+ */
+
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { BuiltLoop } from "./loop.js";
+import { LOOP_STATE_ENTRY_TYPE } from "./state.js";
+
+type NewSessionOptions = Exclude<Parameters<ExtensionCommandContext["newSession"]>[0], undefined>;
+type SessionManagerLike = Parameters<NonNullable<NewSessionOptions["setup"]>>[0];
+
+export type FreshLoopResult =
+	| { kind: "started" }
+	| { kind: "cancelled" }
+	/** The session exists and holds the loop, but it could not be kicked off. */
+	| { kind: "partial"; detail: string }
+	| { kind: "rejected"; detail: string };
+
+export interface FreshLoopRequest {
+	built: BuiltLoop;
+	/** Write the ledger for `built` before the handoff; returns a failure detail. */
+	prepareLedger(): string | undefined;
+}
+
+export async function startLoopInFreshSession(
+	ctx: ExtensionContext,
+	request: FreshLoopRequest,
+): Promise<FreshLoopResult> {
+	if (!isCommandContext(ctx)) {
+		return {
+			kind: "rejected",
+			detail:
+				"Starting a loop in a fresh session needs the interactive /loop command. Run /loop again and choose it from the menu.",
+		};
+	}
+	if (ctx.mode === "print" || ctx.mode === "json") {
+		return {
+			kind: "rejected",
+			detail: "A fresh session is unavailable in print/JSON mode. Start the loop in this session.",
+		};
+	}
+
+	const ledgerFailure = request.prepareLedger();
+	if (ledgerFailure) {
+		// Not fatal to the loop — a loop runs without a ledger — but it is fatal
+		// to *this* path: the new session would derive its own criteria from the
+		// objective and could be held to a different gate than the one approved.
+		return {
+			kind: "rejected",
+			detail: `The loop's ledger could not be written (${ledgerFailure}), so the approved criteria could not be handed to a new session. Start the loop in this session instead.`,
+		};
+	}
+
+	await ctx.waitForIdle();
+
+	const parentSession = ctx.sessionManager.getSessionFile();
+	let setupError: string | undefined;
+
+	let result: Awaited<ReturnType<ExtensionCommandContext["newSession"]>>;
+	try {
+		result = await ctx.newSession({
+			...(parentSession ? { parentSession } : {}),
+			setup: async (sessionManager: SessionManagerLike) => {
+				try {
+					// The same entry `persist` writes, so the new session's ordinary
+					// restore path picks it up with no special case — plus the handoff
+					// flag, which is what tells that session it owns the first turn.
+					// The kickoff cannot be driven from here: Pi builds a new extension
+					// instance for the new session, so this session's controller is not
+					// the one that ends up holding the loop.
+					sessionManager.appendCustomEntry(LOOP_STATE_ENTRY_TYPE, {
+						loop: { ...request.built.loop, handoff: true },
+					});
+				} catch (error: unknown) {
+					setupError = errorDetail(error);
+				}
+			},
+			withSession: async (replacementCtx: ExtensionContext) => {
+				if (setupError) {
+					replacementCtx.ui.notify(
+						`Fresh session created, but the loop could not be handed to it: ${setupError}. Nothing is running; start the loop from /loop in either session.`,
+						"error",
+					);
+				}
+			},
+		});
+	} catch (error: unknown) {
+		return {
+			kind: "rejected",
+			detail: `Unable to start a fresh session: ${errorDetail(error)}. The draft is unchanged; start the loop in this session instead.`,
+		};
+	}
+
+	if (result.cancelled) return { kind: "cancelled" };
+	return setupError ? { kind: "partial", detail: setupError } : { kind: "started" };
+}
+
+function isCommandContext(ctx: ExtensionContext): ctx is ExtensionCommandContext {
+	return typeof (ctx as Partial<ExtensionCommandContext>).newSession === "function";
+}
+
+function errorDetail(error: unknown) {
+	const detail = error instanceof Error ? error.message : String(error);
+	const normalized =
+		detail
+			.replace(/[\u0000-\u001f\u007f-\u009f]/gu, " ")
+			.replace(/\s+/gu, " ")
+			.trim() || "unknown error";
+	return normalized.length > 500 ? `${normalized.slice(0, 499)}…` : normalized;
+}

package/src/index.ts

@@ -11,23 +11,18 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
 import { completeLoopArguments, parseLoopCommand } from "./command.js";
 import { registerLoopCompleteTool } from "./complete-tool.js";
 import { InlineInvocationState, registerInlineInvocation } from "./inline-invocation.js";
+import { registerLoopProgressTool } from "./progress-tool.js";
+import { registerLoopProposeTool } from "./propose-tool.js";
+import { LOOP_PLANNING_HINT } from "./planning.js";
 import { registerLoopStartTool } from "./start-tool.js";
 import { registerLoopWaitTool } from "./wait-tool.js";
 import { LoopController, type LoopControllerOptions } from "./loop.js";
-import { showLoopManager, showLoopSettings } from "./manager.js";
+import { showLoopApproval, showLoopManager, showLoopSettings } from "./manager.js";
 import { buildLoopObjectivePrompt } from "./objective.js";
 import { registerLoopMessageRendering } from "./render.js";
-import { completeScheduleArguments, parseScheduleCommand } from "./schedule/command.js";
-import { describeTask, listTasks, showScheduleManager } from "./schedule/manager.js";
-import { describeSchedule } from "./schedule/model.js";
-import { Scheduler } from "./schedule/runner.js";
 
 export default function loop(pi: ExtensionAPI, options: LoopControllerOptions = {}) {
 	const controller = new LoopController(pi, options);
-	const scheduler = new Scheduler(pi, {
-		...(options.agentDir === undefined ? {} : { agentDir: options.agentDir }),
-		...(options.now === undefined ? {} : { now: options.now }),
-	});
 	// Registered unconditionally and never toggled with loop state: tools are
 	// part of the cached request prefix, so mutating the tool set mid-session
 	// would invalidate the whole conversation cache. It refuses when no loop is
@@ -36,6 +31,8 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 	// Registered on the same terms and for the same reason: the tool set is
 	// part of the cached prefix, so it never changes with loop state.
 	registerLoopWaitTool(pi, controller);
+	registerLoopProgressTool(pi, controller);
+	registerLoopProposeTool(pi, controller);
 	// Inline invocation: an `input` handler arms a one-turn system-prompt hint
 	// for a mid-prompt `/loop` token, `before_agent_start` appends it, and
 	// loop_start is the model-invoked start it points at — refused on any turn
@@ -54,9 +51,34 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const command = parseLoopCommand(args);
 			switch (command.kind) {
-				case "show":
-					await showLoopManager(controller, ctx);
+				case "show": {
+					// Bare /loop is the front door. With a loop running it is the
+					// manager, as before. With a draft awaiting approval it is the
+					// card. With neither it opens planning, which is what used to be
+					// a one-line "no loop in this session" dead end.
+					const running = controller.state && controller.state.status !== "stopped";
+					if (running) {
+						await showLoopManager(controller, ctx);
+						return;
+					}
+					if (controller.planning.proposal) {
+						await showLoopApproval(controller, ctx);
+						return;
+					}
+					if (controller.planning.active) {
+						ctx.ui.notify(
+							"Still planning: describe the objective, and the agent will put a loop up for approval.",
+							"info",
+						);
+						return;
+					}
+					controller.beginPlanning();
+					ctx.ui.notify(
+						"Loop planning. Describe what you want the loop to achieve and how you will know it is done; the agent drafts it and puts it up for approval. Nothing starts until you approve it.",
+						"info",
+					);
 					return;
+				}
 				case "status":
 					ctx.ui.notify(controller.statusLines(ctx).join("\n"), "info");
 					return;
@@ -101,83 +123,11 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 		},
 	});
 
-	// The scheduler is user-typed only, exactly like /loop: the model gets no
-	// scheduling tools, because a model that can schedule its own future turns
-	// can schedule its way around every limit the loop imposes.
-	pi.registerCommand("schedule", {
-		description:
-			'Schedule prompts and headless runs: /schedule [every <dur>|at <time>|cron "<expr>"] [--run] <prompt>, or list/pause/resume/run/status/delete',
-		getArgumentCompletions: (prefix: string) => completeScheduleArguments(prefix),
-		handler: async (args: string, ctx: ExtensionCommandContext) => {
-			const command = parseScheduleCommand(args, { cwd: ctx.cwd });
-			switch (command.kind) {
-				case "show":
-					await showScheduleManager(scheduler, ctx);
-					return;
-				case "list":
-					ctx.ui.notify(listTasks(scheduler).join("\n"), "info");
-					return;
-				case "error":
-					ctx.ui.notify(command.message, "error");
-					return;
-				case "create": {
-					const { task, warning } = scheduler.create(command);
-					if (warning) {
-						ctx.ui.notify(`Scheduled task not persisted: ${warning}`, "warning");
-					}
-					if (command.clampedFrom !== undefined) {
-						ctx.ui.notify("Intervals below 1 minute are raised to the minimum.", "warning");
-					}
-					ctx.ui.notify(
-						[
-							`Scheduled "${task.name}" (${task.id}): ${describeSchedule(task.schedule)}.`,
-							task.task.kind === "run"
-								? `Runs headlessly in ${task.task.cwd}; wakes this session on ${task.task.wakeOn}.`
-								: "Injects a prompt into this session at an idle boundary; it dies with the session.",
-							`Runs: ${task.maxRuns === null ? "unlimited" : `at most ${task.maxRuns}`}; expires ${new Date(task.expiresAt).toLocaleDateString()}.`,
-						].join("\n"),
-						"info",
-					);
-					return;
-				}
-				default: {
-					const task = scheduler.find(command.id);
-					if (!task) {
-						ctx.ui.notify(
-							`No scheduled task matches ${command.id}. Run /schedule list to see them.`,
-							"error",
-						);
-						return;
-					}
-					if (command.kind === "status") {
-						ctx.ui.notify(describeTask(task).join("\n"), "info");
-						return;
-					}
-					if (command.kind === "pause" || command.kind === "resume") {
-						const status = command.kind === "pause" ? "paused" : "active";
-						scheduler.update({ ...task, status });
-						ctx.ui.notify(`Task "${task.name}" is now ${status}.`, "info");
-						return;
-					}
-					if (command.kind === "run") {
-						scheduler.fireNow(task);
-						ctx.ui.notify(`Running "${task.name}" now.`, "info");
-						return;
-					}
-					scheduler.remove(task.id);
-					ctx.ui.notify(`Deleted "${task.name}".`, "info");
-				}
-			}
-		},
-	});
-
 	pi.on("session_start", async (_event, ctx) => {
 		controller.onSessionStart(ctx);
-		scheduler.onSessionStart(ctx);
 	});
 	pi.on("session_shutdown", async () => {
 		controller.onSessionShutdown();
-		scheduler.onSessionShutdown();
 	});
 	// The pacemaker: agent_end records the intent to continue, agent_settled
 	// delivers it once Pi will accept a message.
@@ -189,12 +139,16 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 	});
 	pi.on("agent_settled", async (_event, ctx) => {
 		controller.onAgentSettled(ctx);
-		scheduler.onAgentSettled(ctx);
 	});
 	// A loop carries its own objective and injects it as a byte-stable system
 	// append, which is what lets the poke and continuation messages stay
 	// pointer-sized.
 	pi.on("before_agent_start", (event) => {
+		// Planning precedes any loop, so its guidance is injected on the same hook
+		// and is mutually exclusive with the objective append below.
+		if (controller.planning.active) {
+			return { systemPrompt: `${event.systemPrompt}\n\n${LOOP_PLANNING_HINT}` };
+		}
 		const loop = controller.state;
 		if (!loop || loop.status !== "active") return;
 		const objectivePrompt = buildLoopObjectivePrompt(loop, controller.ledger);

package/src/interval.ts

@@ -54,6 +54,31 @@ export function formatDuration(ms: number): string {
 	return `${Math.round(ms / 1_000)}s`;
 }
 
+/**
+ * Render an elapsed span approximately, for display only.
+ *
+ * `formatDuration` renders the *canonical token* for a configured interval and
+ * only ever emits one unit on an exact multiple, so an arbitrary elapsed span
+ * falls through it to seconds — 2h12m comes back as "7920s". An age needs the
+ * opposite trade: two units at most, truncated, never exact.
+ */
+export function formatElapsed(ms: number): string {
+	const clamped = Math.max(0, ms);
+	if (clamped < UNIT_MS.m) return `${Math.floor(clamped / 1_000)}s`;
+	for (const [big, small] of [
+		["d", "h"],
+		["h", "m"],
+	] as const) {
+		const bigMs = UNIT_MS[big];
+		const smallMs = UNIT_MS[small];
+		if (bigMs === undefined || smallMs === undefined || clamped < bigMs) continue;
+		const whole = Math.floor(clamped / bigMs);
+		const rest = Math.floor((clamped % bigMs) / smallMs);
+		return rest > 0 ? `${whole}${big}${rest}${small}` : `${whole}${big}`;
+	}
+	return `${Math.floor(clamped / UNIT_MS.m)}m`;
+}
+
 /** Render a wall-clock time as HH:MM for the status widget. */
 export function formatClock(timestamp: number): string {
 	const date = new Date(timestamp);