@hank-warren/pi-loop 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @hank-warren/pi-loop
 
+## 0.6.0
+
+### Minor Changes
+
+- b642391: Removing goal-bound loops is breaking for anyone holding one; it lands as a 0.x minor per this repo's convention.
+
+  **Start a loop from an inline `/loop` invocation.** Pi dispatches `/loop` only when it is the first thing in the message, so `quick check /loop 10m get CI green` used to arrive as prose and vanish. A new `loop_start` tool, pointed at by a one-turn `<system-reminder>`, now starts the loop and begins working in the same turn. `loop: <objective>` at line start works the same way. The message itself is never rewritten, split, re-sent, or annotated: an `input` handler only records it, and `before_agent_start` appends the hint when the starting prompt is that same message.
+
+  `loop_start` **refuses unless the inline hint armed for that turn.** A loop is self-continuing, so a spurious start does not produce one unwanted answer, it produces turns until a cap — that gate is enforcement rather than prompt guidance. It also refuses when a loop is already active, when `loop_complete` is missing from the active tool set, and on an unparsable objective, interval, or expiry.
+
+  New settings: `inlineInvocation` (default `true`) and `defaultInterval` (default `"10m"`, used when an invocation names no interval).
+
+  **Goal-bound loops are gone,** along with every `goal-state` reader, the completion-race clear-scan, and the goal outcomes in the tick and continuation decisions. A loop owns its objective, ledger, post-compaction re-anchor, and evidence-gated completion, so delegating completion to a second extension bought nothing and cost a coupling. `plan-mode-state` is now the only sibling entry pi-loop reads.
+
+  A loop persisted before this release with no objective of its own adopts its focus text as one on restore, and pauses with an explanation when there is nothing to adopt.
+
+  `@hank-warren/pi-goal` is deprecated in favour of this package. Its published versions stay installable.
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -2,30 +2,16 @@
 
 Inspired by Claude Code's `/loop`, adapted to Pi: keep work moving across many turns, and keep long loops coherent across context compaction.
 
-A loop is a **pacemaker**: it owns *when* the session works. What it works *on* comes in two modes, chosen automatically when the loop starts:
+A loop is a **pacemaker** that owns its own work: it carries an objective and completion criteria, and ends when the model calls `loop_complete` with cited evidence, a cap is reached, its expiry arrives, or you stop it. **No other extension is required.**
 
-- **Standalone** — the loop carries its own objective and completion criteria. It ends when the model calls `loop_complete`, a cap is reached, or you stop it. **No other extension required**, and this is the mode to use.
-- **Goal-bound** (**deprecated**) — an active [pi-goal](../pi-goal) goal is present, so the loop binds to it and pi-goal owns *whether the work is done*. Coupling stays read-only: fail-open reads of pi-goal's `goal-state` entries.
+Earlier versions could instead bind a loop to a [pi-goal](https://www.npmjs.com/package/@hank-warren/pi-goal) goal and let that extension own *whether the work is done*. That mode is gone as of 0.6.0, along with every `goal-state` reader: a loop now does everything the pairing did — objective, durable ledger, post-compaction re-anchor, evidence-gated completion — so the coupling bought nothing. A loop persisted before 0.6.0 that carries no objective adopts its focus text as one on restore, and pauses with an explanation when there is nothing to adopt.
 
-**An active goal still wins**, for now: start a loop while a goal is running and it binds to that goal, with any trailing text kept as a per-wake focus — with a deprecation warning. With no active goal, the trailing text becomes the loop's own objective.
-
-### Goal-bound loops are going away
-
-A standalone loop now does everything the pairing did — it owns its objective, keeps a durable ledger, re-anchors itself after compaction, and gates completion on cited evidence — so delegating "is the work done" to a second extension buys nothing and costs a coupling. [pi-goal](../pi-goal) carries the matching deprecation banner.
-
-This release keeps the goal-bound path working, warns when you start one, and **migrates a restored goal-bound loop to standalone** by adopting the goal's objective text (falling back to the loop's own focus text). The one case it deliberately does not migrate is a **still-active** goal: pi-goal is driving that session's continuations, and a standalone loop driving them too would send two messages at every settle — that loop keeps its old behaviour and gets the warning instead. If there is nothing to adopt at all, the loop pauses and says so rather than pretending.
-
-The following release removes the goal-bound branch, the `goal-state` readers, and their fixtures.
-
-pi-plan-mode's `plan-mode-state` is read the same fail-open way in both modes, so a loop never injects into a planning conversation.
+pi-plan-mode's `plan-mode-state` is read fail-open — the only sibling state left — so a loop never injects into a planning conversation.
 
 ## Usage
 
 ```
-/loop 30m until all tests pass and CI is green   # standalone: the loop owns the objective
-/goal get CI green                               # ...or bind to a goal
-/loop 30m                                        #    poke that goal every 30m if the session stalls
-/loop 10m recheck the pipeline                   #    trailing text is a per-wake focus when goal-bound
+/loop 30m until all tests pass and CI is green   # the trailing text is the objective
 /loop                                            # manager TUI (status, pause/resume, edit, settings, stop)
 /loop status | pause | resume | stop | settings
 /loop --max 20 --compact-at 60% --expires 3d 10m # per-loop overrides
@@ -33,7 +19,26 @@ pi-plan-mode's `plan-mode-state` is read the same fail-open way in both modes, s
 ```
 
 - **Intervals** are `<number><unit>` with unit `s`/`m`/`h`/`d`, parsed by the extension (never the model), minimum 1 minute (smaller values clamp, and the effective value is echoed).
-- `/loop` is deliberately **user-typed only** — the model never starts or stops loops. (Inline `/goal` invocation is the [pi-goal fork](https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-goal)'s `goal_start` tool.)
+- Loops are **user-driven only**: the model may start one *you* invoked inline (below), and never on its own initiative.
+
+### Inline invocation
+
+Pi dispatches `/loop` only when it is the first thing in the message, so `quick check /loop 10m get CI green` arrives as ordinary prose and nothing happens. That is the common way to lose an invocation, so pi-loop detects it:
+
+```
+quick check /loop 10m get CI green on main, verified by a passing run
+loop: get CI green on main, verified by a passing run
+```
+
+Both make the model call the `loop_start` tool with the objective and then begin working, in the same turn.
+
+**Your message is never touched** — not cut, split, re-sent, or annotated. An `input` handler only *records* the text; `before_agent_start` appends a one-turn `<system-reminder>` when the starting prompt is that same message. The hint is a per-turn system-prompt append, never a stored message, so "call loop_start now" cannot linger and fire on a later turn.
+
+Detection is deliberately narrow. A token at position 0 is ignored (that is Pi's own dispatch), as is one inside backticks or a quoted span — `` `/loop` `` and `"/loop 5m ship it"` are how people *discuss* the command — and a bare trailing `/loop` with no remainder. The `loop:` form needs to start a line, so "my loop: is unclear" is prose. Extension-sent prompts never arm, and neither does steered or queued input, whose delivery order would leave a stale arm behind.
+
+**`loop_start` refuses unless the turn was armed.** This is enforcement, not guidance. A loop is *self-continuing*: a spurious start does not produce one unwanted answer, it produces turns until a cap. So the tool checks a flag the inline hooks set for exactly one turn, and refuses outright otherwise, along with a loop already being active, a missing `loop_complete`, or an unparsable interval or expiry.
+
+An invocation that names no interval uses the `defaultInterval` setting (`10m`). In a settle-paced loop the interval is only a fallback heartbeat, so the value matters far less than it looks. Turn the whole feature off with `"inlineInvocation": false`.
 
 ## What paces a loop
 
@@ -55,8 +60,6 @@ A reply that starts or ends with `LOOP_OK` and carries at most **300 characters*
 
 The chip is **display-only**. The stored message keeps its exact bytes, because rewriting them would break the prompt cache this whole design is built around.
 
-A **goal-bound** loop is unchanged: pi-goal drives its own settle continuations, so pi-loop would only double every turn, and the interval stays that loop's only driver.
-
 ### Two counters
 
 One wake now yields many turns, so a single counter cannot bound a loop:
@@ -70,28 +73,25 @@ Either cap trips independently and stops the loop; `null` on either means unlimi
 
 Each tick — fallback heartbeat or settled boundary — evaluates, in order:
 
-1. **Expired?** Loops hard-expire after `maxLoopDuration` (default 7 days, or per loop with `--expires 3d`, echoed at start) — a forgotten loop is bounded. A standalone loop gets **one final turn** first: "write the current state into the ledger, start no new work, claim no completion", and the settle after it stops the loop. A loop that simply vanished at its deadline would leave its most recent state only in a conversation about to be closed. If that final wake cannot be delivered, the loop stops immediately rather than living past its deadline.
+1. **Expired?** Loops hard-expire after `maxLoopDuration` (default 7 days, or per loop with `--expires 3d`, echoed at start) — a forgotten loop is bounded. The loop gets **one final turn** first: "write the current state into the ledger, start no new work, claim no completion", and the settle after it stops the loop. A loop that simply vanished at its deadline would leave its most recent state only in a conversation about to be closed. If that final wake cannot be delivered, the loop stops immediately rather than living past its deadline.
 2. **Plan mode active?** Skip quietly; never inject prompts into a planning conversation.
 3. **Agent busy?** Never interrupt: coalesce into a single pending wake delivered at the next fully-settled idle boundary. N missed ticks collapse into one poke.
-4. **Mode-specific stop criteria.** *Standalone*: none — the loop reads no goal state at all, so pi-goal being absent, complete, or paused is irrelevant to it; it ends only via `loop_complete`, a cap, or you. *Goal-bound*: a missing goal (cleared mid-loop) **pauses** the loop; completion **stops** it — including through the clear that follows it, since pi-goal persists the finished goal and *then* clears the entry, so the newest entry at completion is a clear and the loop reads back past it; a safety pause (`paused`/`blocked`/`usage_limited`/`budget_limited`, or any unknown status) **pauses** it — pi-loop never pokes past pi-goal's circuit breakers. An `active` or `goal_wait`-waiting goal in an idle session is exactly the stall this extension exists for, so it pokes toward the goal (a tick is the external wake `goal_wait` arranges).
+4. **A declared wait?** A `loop_wait` whose deadline has not passed holds both drivers: the loop is not stalled, it is waiting on the world.
 5. **Caps** (see [Two counters](#two-counters)): stop.
-6. **Settled boundary, standalone loop:** dispatch the recorded continuation — a pointer-sized message (`⟳ loop continue #6`) that points at the system prompt for the objective, exactly as the pokes do.
-
-6. **Poke**: a goal wake message — the wake header, why it fired (stalled or the external wake for a waiting goal), and the loop focus when set. Every poke carries a marker (`<!-- pi-loop-poke:<id>:<n> -->`) so a wakeup is identifiable as loop-injected rather than user-typed. The marker is **provenance only** — pi-loop coalesces wakes in its own state and never reads the marker back to drop a delivery.
-
-**A poke never restates the objective**, in either mode — the objective always reaches the model through a byte-stable system append on the same turn, and duplicating it in the message would store another copy on every wake. The two modes differ only in who provides that append: pi-goal's, on every active goal turn, for a goal-bound loop; this extension's own, for a standalone one. Both work because pokes are delivered as ordinary user messages that pass through `before_agent_start`.
+6. **Settled boundary:** dispatch the recorded continuation — a pointer-sized message (`⟳ loop continue #6`) that points at the system prompt for the objective, exactly as the pokes do.
+7. **Fallback heartbeat: poke.** The wake header, why it fired (stalled, or a wait that has elapsed), and the loop focus when set. Every poke carries a marker (`<!-- pi-loop-poke:<id>:<n> -->`) so a wakeup is identifiable as loop-injected rather than user-typed. The marker is **provenance only** — pi-loop coalesces wakes in its own state and never reads the marker back to drop a delivery.
 
-That makes the goal-bound case a genuine **cross-extension assumption**, and the last one left: if pokes were ever delivered by a path that bypasses `before_agent_start` (for example `pi.sendMessage({triggerTurn})`, which calls the agent directly), a goal-bound poke would arrive with no objective anywhere and would have to carry it again. It disappears with the goal-bound path. The token-lean contract is pinned in `test/messages.test.ts`; the matching cache-stability contract lives in [pi-goal](https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-goal#fork-feature-cache-safe-token-lean-injections), whose README records the same assumption from the other side.
+**A poke never restates the objective.** The objective reaches the model through a byte-stable system append on the same turn, and duplicating it in the message would store another copy on every wake. That works because pokes are delivered as ordinary user messages, which pass through `before_agent_start`; a delivery path that bypassed it (for example `pi.sendMessage({triggerTurn})`, which calls the agent directly) would arrive with no append and would have to carry the objective again. The token-lean contract is pinned in `test/messages.test.ts`.
 
 In the transcript, a poke renders as a one-line chip (`⏰ loop wake 4/25 · stalled`) via a markdown transformer. That hook is display-only by Pi's contract — the stored message and the model's context are untouched.
 
-Expiry, completion, and pi-goal's safety states are evaluated whenever the session settles, so a loop stops as soon as its goal does rather than at the next scheduled tick. Only the fallback heartbeat pokes; a settle continues.
+Expiry and the caps are evaluated whenever the session settles, so a loop ends as soon as the work does rather than at the next scheduled tick. Only the fallback heartbeat pokes; a settle continues.
 
 The footer status shows `loop 5m · 3/25 · next 14:32`, and a widget above the editor shows the same state with the loop focus beneath it; `/loop status` shows the full card including the last tick's decision and reason.
 
-## Standalone loops: objective, injection, and `loop_complete`
+## Objective, injection, and `loop_complete`
 
-A standalone loop has to put its objective in front of the model itself, since no pi-goal append is doing it. It uses the same cache-safe split pi-goal uses:
+A loop puts its own objective in front of the model, under a cache-safe split:
 
 - **Static per loop — the system prompt.** The objective, `loop_id`, ledger contract, and loop-mode rules are appended to the system prompt, **byte-identically on every turn of that loop**. Anthropic caches `tools → system → messages` as one prefix, so a moving value there (iteration, next wake) would invalidate the cache for the whole conversation every wake. It changes only when the loop does.
 
@@ -151,7 +151,7 @@ The system append carries the objective only while the loop is *active*, and con
 Long loops die by context exhaustion, not by failing. pi-loop owns the compaction path:
 
 - **Proactive compact at a threshold** (default 70% of the context window, `--compact-at` / settings): at an idle boundary, pi-loop triggers `/compact` itself with loop-specific instructions — preserve the objective and acceptance criteria verbatim, **every failed approach and the reason it failed**, decisions and rationale, files modified, commands and unresolved errors, and the next 1-3 actions. The instructions explicitly **stop carrying prior summaries forward wholesale** and tell the next turn to re-derive status from the ledger and authoritative state instead: cumulative carry-forward grows the text while the information in it decays. Pending pokes are held until the compaction completes. Pi's reserve-token auto-compaction remains as the fault handler.
-- **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. A standalone loop no longer goes quiet until the next wake, and nothing is delegated to pi-goal. A re-anchor supersedes an ordinary continuation already queued: after a compaction, "re-read the ledger" is strictly the better instruction. (A goal-bound loop still leaves that message to pi-goal, which owns its continuations.)
+- **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
@@ -200,6 +200,8 @@ Flags: `--run` (headless instead of in-session), `--cwd <path>`, `--max <n|unlim
   "automaticTurns": 25,
   "noProgressTurns": 3,
   "maxLoopDuration": "7d",
+  "inlineInvocation": true,
+  "defaultInterval": "10m",
   "compaction": {
     "enabled": true,
     "threshold": 0.7,
@@ -208,7 +210,7 @@ Flags: `--run` (headless instead of in-session), `--cwd <path>`, `--max <n|unlim
 }
 ```
 
-`maxIterations: null` and `automaticTurns: null` mean unlimited; `noProgressTurns: null` disables the breaker.
+`maxIterations: null` and `automaticTurns: null` mean unlimited; `noProgressTurns: null` disables the breaker. `inlineInvocation: false` turns off mid-prompt `/loop` detection; `defaultInterval` is the fallback heartbeat an inline invocation gets when it names none.
 
 ## Deliberate omissions
 
@@ -224,7 +226,7 @@ These were considered and cut, and the reasoning is recorded so they are not sil
 pi install npm:@hank-warren/pi-loop
 ```
 
-**No other extension is required.** A standalone loop stands alone; a goal extension (`npm:@hank-warren/pi-goal` or upstream `@narumitw/pi-goal`) is only needed for the deprecated goal-bound mode, and that mode is being removed.
+**No other extension is required.** The only sibling state pi-loop reads is [pi-plan-mode](https://www.npmjs.com/package/@hank-warren/pi-plan-mode)'s, fail-open, so a loop never injects into a planning conversation — and it works fine without it.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-loop",
-  "version": "0.5.0",
+  "version": "0.6.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": [

package/src/complete-tool.ts

@@ -1,5 +1,5 @@
 /**
- * `loop_complete`: the standalone loop's terminal tool.
+ * `loop_complete`: the loop's terminal tool.
  *
  * It used to be deliberately thin, on the argument that stopping a pacemaker
  * has a small blast radius: the user just restarts it. That argument does not
@@ -94,7 +94,7 @@ export function registerLoopCompleteTool(pi: ExtensionAPI, controller: LoopContr
 				if (!loop || loop.objective === undefined) {
 					return {
 						content: toolContent(
-							"No standalone /loop is active. loop_complete only applies to a loop started with its own objective; a goal-bound loop is ended through pi-goal.",
+							"No /loop with an objective is active, so there is nothing to complete. Start one with /loop <interval> <objective>.",
 						),
 						details: { loopId: params.loop_id },
 						isError: true,

package/src/decide.ts

@@ -9,17 +9,13 @@
  *   handler for a lost continuation or an external wait, not the pacemaker.
  *
  * Both share one precedence prefix: loop liveness → expiry → plan mode →
- * compaction → busy → mode-specific stop criteria → caps → act.
+ * compaction → busy → wait → caps → act.
  *
- * The mode-specific step is the whole difference between the two kinds of
- * loop. A goal-bound loop delegates "is the work done" to pi-goal and reads
- * its `goal-state`, so a missing goal pauses it and a safety state holds it;
- * pi-goal also owns its settle continuations, so `decideContinuation` never
- * acts for one. A standalone loop owns its own objective, reads no goal state
- * at all, and ends only through `loop_complete`, a cap, or the user.
+ * A loop owns its own objective and reads no other extension's state: it ends
+ * only through `loop_complete`, a cap, an expiry, or the user.
  */
 
-import { GOAL_SAFETY_STATUSES, type GoalSnapshot, isStandaloneLoop, type LoopState } from "./state.js";
+import type { LoopState } from "./state.js";
 
 export interface TickEnvironment {
 	now: number;
@@ -28,7 +24,6 @@ export interface TickEnvironment {
 	/** A loop-owned proactive compaction is in flight; hold pokes. */
 	compacting: boolean;
 	planModeEnabled: boolean;
-	goal: GoalSnapshot | undefined;
 }
 
 /** A `loop_wait` whose deadline has passed is due, not waiting. */
@@ -39,8 +34,8 @@ function isWaiting(loop: LoopState, now: number): boolean {
 }
 
 /**
- * An expiring standalone loop gets one last turn to write its state into the
- * ledger before it stops; every other expiry stops immediately.
+ * An expiring loop gets one last turn to write its state into the ledger
+ * before it stops; a loop already spending that turn stops immediately.
  */
 export type ExpiryReason = "loop-expired" | "expiry-final-wake";
 
@@ -54,36 +49,26 @@ export type TickDecision =
 	| { action: "none"; reason: "loop-not-active" }
 	| { action: "expire"; reason: ExpiryReason }
 	| { action: "skip"; reason: SkipReason }
-	| { action: "stop"; reason: "goal-complete" | "max-iterations" | "max-automatic-turns" }
-	| { action: "pause"; reason: "goal-safety"; cause: string }
-	| { action: "pause"; reason: "goal-missing" }
-	| {
-			action: "poke";
-			reason: "goal-stalled" | "goal-waiting" | "objective-stalled" | "wait-elapsed";
-	  };
+	| { action: "stop"; reason: "max-iterations" | "max-automatic-turns" }
+	| { action: "poke"; reason: "objective-stalled" | "wait-elapsed" };
 
 export type ContinuationDecision =
-	| { action: "none"; reason: "loop-not-active" | "goal-bound" }
+	| { action: "none"; reason: "loop-not-active" }
 	| { action: "expire"; reason: ExpiryReason }
 	| { action: "skip"; reason: SkipReason }
 	| { action: "stop"; reason: "max-iterations" | "max-automatic-turns" }
 	| { action: "continue"; reason: "settled-idle" };
 
-/** Shared prefix: everything that holds or ends a loop before mode matters. */
+/** Shared prefix: everything that holds or ends a loop before caps matter. */
 function decideCommonPrefix(
 	loop: LoopState,
 	env: TickEnvironment,
 ): Extract<TickDecision, { action: "none" | "expire" | "skip" }> | undefined {
 	if (loop.status !== "active") return { action: "none", reason: "loop-not-active" };
 	if (env.now >= loop.expiresAt) {
-		// The final wake is a standalone loop's own summarise-and-stop turn; a
-		// goal-bound loop has no ledger of its own to write, and pi-goal owns
-		// that conversation.
-		return {
-			action: "expire",
-			reason:
-				isStandaloneLoop(loop) && !loop.expiring ? "expiry-final-wake" : "loop-expired",
-		};
+		// The final wake is the loop's own summarise-and-stop turn; a loop already
+		// spending it has nothing left to buy.
+		return { action: "expire", reason: loop.expiring ? "loop-expired" : "expiry-final-wake" };
 	}
 	if (env.planModeEnabled) return { action: "skip", reason: "plan-mode-active" };
 	if (env.compacting) return { action: "skip", reason: "compaction-in-flight" };
@@ -111,16 +96,13 @@ function decideCaps(
 }
 
 /**
- * The settled-idle boundary of a standalone loop: the session finished a turn
- * with the objective unfinished, so the loop continues immediately instead of
- * waiting out an interval of idle wall time.
+ * The settled-idle boundary: the session finished a turn with the objective
+ * unfinished, so the loop continues immediately instead of waiting out an
+ * interval of idle wall time.
  */
 export function decideContinuation(loop: LoopState, env: TickEnvironment): ContinuationDecision {
 	const prefix = decideCommonPrefix(loop, env);
 	if (prefix) return prefix;
-	// pi-goal drives its own settle continuations for a goal-bound loop; two
-	// extensions continuing the same session would double every turn.
-	if (!isStandaloneLoop(loop)) return { action: "none", reason: "goal-bound" };
 	const capped = decideCaps(loop);
 	if (capped) return capped;
 	return { action: "continue", reason: "settled-idle" };
@@ -129,40 +111,10 @@ export function decideContinuation(loop: LoopState, env: TickEnvironment): Conti
 export function decideTick(loop: LoopState, env: TickEnvironment): TickDecision {
 	const prefix = decideCommonPrefix(loop, env);
 	if (prefix) return prefix;
-
-	// A standalone loop carries its own objective, so it never consults
-	// pi-goal: it runs until loop_complete stops it, a cap is reached, or the
-	// user intervenes.
-	if (isStandaloneLoop(loop)) {
-		const capped = decideCaps(loop);
-		if (capped) return capped;
-		// The prefix already let a still-waiting loop skip, so a wait surviving
-		// to here is one whose deadline has come due: this wake is the wake it
-		// asked for, and it counts against the wake cap like any other.
-		return { action: "poke", reason: loop.waiting ? "wait-elapsed" : "objective-stalled" };
-	}
-
-	const goal = env.goal;
-	// Goal-bound loops require a goal to operate: the goal evaluator owns the
-	// stop criterion, so such a loop with no goal has nothing to decide when it
-	// is done.
-	if (!goal) return { action: "pause", reason: "goal-missing" };
-	if (goal.status === "complete") return { action: "stop", reason: "goal-complete" };
-	if ((GOAL_SAFETY_STATUSES as readonly string[]).includes(goal.status)) {
-		return { action: "pause", reason: "goal-safety", cause: goal.status };
-	}
-	if (goal.status !== "active") {
-		// Unknown status from a newer pi-goal: treat like a safety state
-		// rather than poking past a guard we do not understand.
-		return { action: "pause", reason: "goal-safety", cause: goal.status };
-	}
-
 	const capped = decideCaps(loop);
 	if (capped) return capped;
-
-	// An idle session with an active goal is exactly the stall/wait case:
-	// pi-goal continues on its own at every idle boundary, so idleness at
-	// tick time means its continuation was lost, or the goal is waiting on
-	// an external event — which this wakeup is.
-	return { action: "poke", reason: goal.waiting ? "goal-waiting" : "goal-stalled" };
+	// The prefix already let a still-waiting loop skip, so a wait surviving to
+	// here is one whose deadline has come due: this wake is the wake it asked
+	// for, and it counts against the wake cap like any other.
+	return { action: "poke", reason: loop.waiting ? "wait-elapsed" : "objective-stalled" };
 }

package/src/index.ts

@@ -1,15 +1,17 @@
 /**
- * pi-loop: Claude-Code-/loop-inspired pacemaker for Pi. A loop wakes the
- * session on an interval to keep an active pi-goal goal moving (stall rescue
- * and goal_wait wakes) with loop-aware compaction. Loops require an active
- * goal: the loop owns *when* the session wakes; @narumitw/pi-goal (or the
- * @hank-warren/pi-goal fork) owns *whether the work is done*, read through
- * its `goal-state` session entries only.
+ * pi-loop: Claude-Code-/loop-inspired long-running work for Pi. A loop
+ * carries its own objective and completion criteria, is paced by the session
+ * settling, keeps a durable ledger, compacts itself, and ends through
+ * `loop_complete`, a cap, its expiry, or the user. It depends on no other
+ * extension; the only sibling state it reads is pi-plan-mode's, fail-open, so
+ * a loop never injects into a planning conversation.
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { completeLoopArguments, parseLoopCommand } from "./command.js";
 import { registerLoopCompleteTool } from "./complete-tool.js";
+import { InlineInvocationState, registerInlineInvocation } from "./inline-invocation.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";
@@ -28,12 +30,19 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 	});
 	// 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
-	// standalone loop is active.
+	// would invalidate the whole conversation cache. It refuses when no loop is
+	// active.
 	registerLoopCompleteTool(pi, controller);
 	// 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);
+	// 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
+	// the hint did not arm. The user's message is never transformed.
+	const invocation = new InlineInvocationState();
+	registerInlineInvocation(pi, controller, invocation);
+	registerLoopStartTool(pi, controller, invocation);
 	// Collapse loop pokes into one-line transcript chips (display-only; the
 	// stored message and model context are untouched).
 	registerLoopMessageRendering(pi);
@@ -84,7 +93,8 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 							return;
 						}
 					}
-					controller.startLoop(ctx, command);
+					const result = controller.startLoop(ctx, command);
+					if (!result.ok) ctx.ui.notify(result.message, "error");
 					return;
 				}
 			}
@@ -169,8 +179,8 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 		controller.onSessionShutdown();
 		scheduler.onSessionShutdown();
 	});
-	// The pacemaker of a standalone loop: agent_end records the intent to
-	// continue, agent_settled delivers it once Pi will accept a message.
+	// The pacemaker: agent_end records the intent to continue, agent_settled
+	// delivers it once Pi will accept a message.
 	pi.on("agent_start", async (_event, ctx) => {
 		controller.onAgentStart(ctx);
 	});
@@ -181,10 +191,9 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 		controller.onAgentSettled(ctx);
 		scheduler.onAgentSettled(ctx);
 	});
-	// A standalone loop carries its own objective, so it injects it the way
-	// pi-goal does for a goal-bound one: a byte-stable system append, which is
-	// what lets the poke messages stay pointer-sized. A goal-bound loop adds
-	// nothing here — pi-goal already owns that turn's append.
+	// 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) => {
 		const loop = controller.state;
 		if (!loop || loop.status !== "active") return;

package/src/inline-command.ts

@@ -0,0 +1,159 @@
+/**
+ * Inline slash-command detection.
+ *
+ * Pi dispatches extension commands only when a message *starts* with the
+ * command token; a command mentioned mid-prompt arrives as plain text. This
+ * helper finds inline occurrences of a `/cmd` token (and `cmd:` prefix lines)
+ * so the caller can react — here, by appending a reminder that tells the model
+ * to invoke the corresponding tool. It never rewrites or re-sends the user's
+ * message.
+ *
+ * Ported from @hank-warren/pi-goal, which proved the mechanism before pi-loop
+ * absorbed it; the helper was always generic over the command name.
+ */
+
+export interface InlineCommandSplit {
+	/** Text before the command token, trailing whitespace removed. */
+	prose: string;
+	/** Everything after the command token to end of message, trimmed. */
+	commandArgs: string;
+}
+
+/**
+ * Find the first inline `/<commandName>` occurrence in `text`.
+ *
+ * Detection rules:
+ * - The token must be preceded by start-of-line or whitespace and followed by
+ *   whitespace plus a non-empty remainder. A bare trailing `/cmd` mention or a
+ *   path-like `foo/cmd` never matches.
+ * - A token at position 0 is ignored: that is Pi's native dispatch position.
+ * - Occurrences inside backtick code (inline spans and fenced blocks) or
+ *   inside a single/double-quoted span are ignored. Code regions are
+ *   approximated by the CommonMark backtick-run rule: a run of N backticks
+ *   opens a region closed by the next run of exactly N backticks.
+ *
+ * Returns undefined when no qualifying occurrence exists.
+ */
+export function extractInlineCommand(
+	text: string,
+	commandName: string,
+): InlineCommandSplit | undefined {
+	const token = `/${commandName}`;
+	const ignored = ignoredRegions(text);
+	let searchFrom = 0;
+	while (searchFrom < text.length) {
+		const index = text.indexOf(token, searchFrom);
+		if (index === -1) return undefined;
+		searchFrom = index + 1;
+		if (index === 0) continue;
+		const before = text[index - 1];
+		if (before !== undefined && !/\s/.test(before)) continue;
+		const afterToken = text[index + token.length];
+		if (afterToken === undefined || !/\s/.test(afterToken)) continue;
+		if (insideRegion(ignored, index)) continue;
+		const commandArgs = text.slice(index + token.length).trim();
+		if (!commandArgs) continue;
+		return {
+			prose: text.slice(0, index).trimEnd(),
+			commandArgs,
+		};
+	}
+	return undefined;
+}
+
+/**
+ * True when the message inline-invokes the command: a mid-message `/cmd`
+ * token with a remainder, or a `cmd:` prefix at the start of any line — both
+ * outside backtick code and quoted spans.
+ */
+export function detectsInlineInvocation(text: string, commandName: string): boolean {
+	if (extractInlineCommand(text, commandName) !== undefined) return true;
+	const ignored = ignoredRegions(text);
+	const prefixPattern = new RegExp(`^[ \\t]*${escapeRegExpText(commandName)}:[ \\t]+\\S`, "gim");
+	for (
+		let match = prefixPattern.exec(text);
+		match;
+		match = prefixPattern.exec(text)
+	) {
+		if (!insideRegion(ignored, match.index)) return true;
+	}
+	return false;
+}
+
+type Region = readonly [start: number, end: number];
+
+/**
+ * Backtick code regions plus single/double-quoted spans. Quoting a command is
+ * how people discuss one (`use "/loop 10m ship it" to start`), so a quoted
+ * token is a mention, not an invocation.
+ */
+function ignoredRegions(text: string): Region[] {
+	return [...codeRegions(text), ...quoteRegions(text)];
+}
+
+function codeRegions(text: string): Region[] {
+	const regions: Region[] = [];
+	const runs: Array<{ index: number; length: number }> = [];
+	const runPattern = /`+/g;
+	for (let match = runPattern.exec(text); match; match = runPattern.exec(text)) {
+		runs.push({ index: match.index, length: match[0].length });
+	}
+	for (let open = 0; open < runs.length; open += 1) {
+		const opener = runs[open];
+		if (opener === undefined) continue;
+		for (let close = open + 1; close < runs.length; close += 1) {
+			const closer = runs[close];
+			if (closer === undefined || closer.length !== opener.length) continue;
+			regions.push([opener.index, closer.index + closer.length]);
+			open = close;
+			break;
+		}
+	}
+	return regions;
+}
+
+/**
+ * Single- and double-quoted spans, matched conservatively so an apostrophe
+ * inside a word (`don't`) never opens one: an opening quote follows nothing,
+ * whitespace, or an opening bracket and precedes a non-space; its closing
+ * quote is on the same line, follows a non-space, and precedes end-of-line,
+ * whitespace, or closing punctuation.
+ */
+function quoteRegions(text: string): Region[] {
+	const regions: Region[] = [];
+	for (let index = 0; index < text.length; index += 1) {
+		const quote = text[index];
+		if (quote !== '"' && quote !== "'") continue;
+		const before = text[index - 1];
+		const after = text[index + 1];
+		if (before !== undefined && !/[\s([{<]/.test(before)) continue;
+		if (after === undefined || /\s/.test(after)) continue;
+		const close = closingQuoteIndex(text, index, quote);
+		if (close === undefined) continue;
+		regions.push([index, close + 1]);
+		index = close;
+	}
+	return regions;
+}
+
+function closingQuoteIndex(text: string, openIndex: number, quote: string): number | undefined {
+	for (let index = openIndex + 1; index < text.length; index += 1) {
+		const char = text[index];
+		if (char === "\n") return undefined;
+		if (char !== quote) continue;
+		const before = text[index - 1];
+		const after = text[index + 1];
+		if (before === undefined || /\s/.test(before)) continue;
+		if (after !== undefined && !/[\s.,;:!?)\]}>]/.test(after)) continue;
+		return index;
+	}
+	return undefined;
+}
+
+function insideRegion(regions: readonly Region[], index: number): boolean {
+	return regions.some(([start, end]) => index >= start && index < end);
+}
+
+function escapeRegExpText(value: string) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}