@groeponline/pi-wishcraft 1.4.1 → 1.4.6

package/AGENTS.md

@@ -72,3 +72,31 @@ npm test               # node --experimental-strip-types --test tests/**/*.test.
 ```
 
 Run both before proposing any non-trivial change.
+
+Compound Engineering overlay: `.compound-engineering/` (tracked `config.yaml`, gitignored `config.local.yaml`). Artifact root `.compound-engineering/artifacts/`. Portable skills `~/.agents/skills/ce-*`; native Cursor plugin is fallback only when this overlay is absent.
+
+## Cursor Cloud specific instructions
+
+The Cloud Agent environment is provisioned so the extension can be tested both as
+a library and inside real `pi`, with Docker for containerized/parallel runs.
+
+- **Node:** the platform `node` on `PATH` is v22.14 (fine for `npm ci`,
+  `typecheck`, and the test suite, which use `--experimental-strip-types`).
+  Node 24 is available via `nvm` and is what CI uses.
+- **pi CLI:** installed and pinned to the wishcraft peer range
+  (`@earendil-works/pi-coding-agent` `>=0.81.0 <0.85.0`). pi requires Node
+  `>=22.19`, so the `pi` launcher is wrapped to run under the `nvm` Node 24.
+  `~/.pi/agent/settings.json` loads this checkout (`packages: ["/workspace"]`,
+  `preset: chef`) so `pi` renders the wishcraft welcome/powerline on startup.
+  Running a model needs a provider key (`/login`); the extension loads without
+  one.
+- **Docker:** `dockerd` runs with the `fuse-overlayfs` storage driver (required
+  in the nested VM). `scripts/cloud-agent-start.sh` starts it per boot;
+  `scripts/cloud-agent-install.sh` is the idempotent bootstrap (`npm ci` plus
+  self-healing pi setup).
+- **Containerized / parallel testing:** `scripts/docker-test.sh [-n N]` runs the
+  full check suite (`typecheck` + `test` + `circular`) in `node:24` containers,
+  each with an isolated copy of the tree, so `N` runs are safe in parallel.
+- **Publishing / pi.dev:** merges to `main` auto-publish to npm via the org
+  `NPM_TOKEN` (`.github/workflows/release.yml`), and pi.dev mirrors npm. Gate
+  the catalog contract with `npm run verify:package`.

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 ## [Unreleased]
 
+## [1.4.6] - 2026-08-28
+
+## [1.4.5] - 2026-08-28
+
+## [1.4.4] - 2026-08-28
+
+## [1.4.3] - 2026-08-28
+
+### Added (v2 Platform — wishcraft-v2-platform plan)
+- Powerline v2: the status line now renders through a single path (`renderStatusLineV2` -> `computeLaneLayout` -> `paintLayout`) with the motion rail as a first-class layout segment (reading order left -> rail -> right preserved; under width pressure the right lane yields first, the rail later). The legacy v1 three-lane renderer (`src/signal/render.ts`) is deleted; rail semantics live in `src/render/motion-rail.ts`. Deliberate visible delta: the configured separator now joins every primary segment. Golden pinned post-cutover in `tests/signal-golden.test.ts` (pre-cutover baseline preserved in git history at 84b2e2a).
+- Multi-row layout: segments declare a visual row count (`LayoutSegment.height?` + auto-derive from embedded `\n`); `computeLaneLayout` returns `primaryRowCount`/`secondaryRowCount`; `paintLayout`/`paintSecondary` render one string per row with the separator on row 0 only.
+- Motion rail: lantern sigil as 3-row active rail for the streaming state — a portable `#`-block lantern (sway + breath) that replaces the braille version that rendered as shade-block blobs on terminals without braille fonts. ASCII fallback stays a directional comet; `ready` = calm flat `─` track; `compacting` = inward heads.
+- Bash v2: PTY session core (`bash-mode/pty-session.ts`, SGR-safe ANSI filter, sentinel-based command boundary) plus the long-lived `PtyManagedShellSession` cutover: `session-factory.ts` routes `auto`/`v2` through the PTY-backed session and the editor forwards printable input to the running command's stdin while it runs (interactive programs work; Ctrl-C stays an interrupt). When `script(1)` is missing, commands degrade per-run to plain pipes with a one-time warning. The legacy pipe-based `ManagedShellSession` is deleted.
+- Skill Studio modules: shell + state machine + `/studio` command, list/inspect/actions (create from template, overwrite confirm, doctor), DeepWiki client with 7-day disk cache (`src/studio/deepwiki/`), AI advice engine with pi-ai streaming and char-capped context (`src/studio/advise/`), and an advice pane that streams + inserts into the session. Operator exposure remains deferred and fail-closed until the Studio panes are connected.
+- Versioned autoresearch harness (`.auto/measure.sh`, `checks.sh`, `config.json`, `prompt.md`): one-run `METRIC` output for test/typecheck/circular plus signal-render and registry micro-benchmarks.
+- Tests: 706 passing across new and existing suites; full `typecheck`, `madge --circular`, and `npm test` green.
+
+### Fixed
+- `segmentHeight` counted trailing empty lines as extra rows, forcing an empty full-width row below a segment — the "big block under every line" render bug.
+- `paintLayout` row-1+ separator padding used `separator.length` (ANSI bytes) instead of `visibleWidth(separator)` — a dead column between lanes on multi-row content.
+- Multi-row rail color: `renderActivity` now wraps each sigil row with its own ANSI color+reset, so rows 1+ render in the lane accent instead of falling back to the terminal default.
+- `activityForEvent` and `defaultMotionFor` had no `default` case — unknown events leaked the literal text `undefined` into the powerline.
+- `MotionScheduler.subscribe` now calls `onDone` on an existing consumer with the same id before replacing it (a silent leak on re-subscribe).
+- `setSignalEvent` wraps `scheduler.subscribe` in try/catch so a throw leaves the runtime in a clean idle state instead of `active=true` with `release=null`.
+
+### Changed
+- Version numbering: the ladder had raced up to 1.7.x while the shipped feature depth was a handful of patches. This release restores the honest number (1.4.3) and `chooseBump` now defaults to `patch` for normal `feat:` commits — only an explicit breaking marker (`feat!:`, `BREAKING CHANGE`) auto-promotes (to `major`); `minor` is an explicit manual choice.
+
+### Deferred
+- Editor live-tail and v1 session cleanup.
+- PTY echo/privacy.
+- Paste while running.
+- Managed-suite pipe-mode safeguards.
+- Studio operator exposure until its panes are connected.
+- Deck left-rail navigation bug (arrow-down skipping straight to the skills list).
+
 ## [1.4.1] - 2026-08-27
 
 ## [1.4.0] - 2026-08-27

package/README.md

@@ -12,12 +12,17 @@
 # pi-wishcraft
 
 Cockpit and harness for the [pi](https://github.com/badlogic/pi-mono) coding agent: a live status bar, overlay menus, skills, an idea inbox, sticky bash, hooks, and tool-input repairs. Stock pi stays the engine. This package is the operator layer.
-
 Kongming lanterns started as battlefield signals and later carried wishes. Wishcraft is that split in a coding session: telemetry on the bar, thoughts you can park without interrupting the run.
 
 Install `@groeponline/pi-wishcraft`. It is listed on the [Pi package catalog](https://pi.dev/packages/@groeponline/pi-wishcraft). Grew out of [`nicobailon/pi-powerline-footer`](https://github.com/nicobailon/pi-powerline-footer). Maintained by [GroepOnline](https://github.com/GroepOnline).
 
-Guides live in [`docs/`](docs/index.md). This page is the contract: what ships, how to install it, and what can fail.
+Guides live in [`docs/`](docs/index.md). This is the Pi extension contract: what ships, how to install it, and what can fail.
+
+## Quick start tutorial
+
+Install, restart Pi (or run `/reload`), then press `alt+p` for the Deck. Try `/signal menu`, `/skills`, `/ideas`, and `ctrl+shift+b`. Full setup: [docs/configuration.md](docs/configuration.md).
+
+## v2 Platform (in this release)
 
 ## Install
 
@@ -27,13 +32,13 @@ Pi package manager (usual path):
 pi install npm:@groeponline/pi-wishcraft
 ```
 
-Ephemeral VMs / CI:
+For a local checkout or CI environment, run the repository bootstrap script with Bash:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/GroepOnline/pi-wishcraft/main/scripts/install.sh | bash
+bash ./scripts/install.sh
 ```
 
-Then restart pi or `/reload`. Pi host packages are declared as `peerDependencies: "*"`, matching the Pi package contract.
+Then restart Pi or `/reload`. Pi host packages are declared as `peerDependencies: "*"`, matching the Pi package contract.
 
 ## What you get
 
@@ -48,6 +53,8 @@ Then restart pi or `/reload`. Pi host packages are declared as `peerDependencies
 | Hooks + repairs | Command hooks on pi events. Custom-tool input repairs before execution. Kill-switch: `wishcraft.hooksEnabled`. |
 | Read hints | Appends a one-line continuation hint after a partial `read`, so the model knows the next offset. Opt-out: `wishcraft.readHints: false`. |
 | Policy | In-process deny/inject rules in global settings. No spawn. Kill-switch: `wishcraft.policyEnabled`. |
+| Working indicator | Four deterministic styles (`dots`, `pulse`, `bar`, `ascii`) with accessibility-aware static fallbacks. |
+| Welcome art | `lantern`, `balloon`, and `normal` opening artwork, each with a different silhouette and narrow-terminal fallback. |
 
 Pi owns the footer chrome, feed scrolling, and input. Wishcraft supplies widgets, overlays, and the bash/stash/editor integrations. The bar is not clickable; actions are commands and overlays.
 
@@ -126,7 +133,9 @@ At 80% the cost segment warns; at 100% it goes red and welcome notifies. `/usage
 
 ## Hooks
 
-Hooks are commands that read JSON on stdin. Definitions come from the **global** agent settings file only. Project `.pi/settings.json` cannot install new hook commands. `wishcraft.hooksEnabled: false` disables every hook without deleting the config.
+Hooks are commands that read JSON on stdin. See [docs/configuration.md](docs/configuration.md) for examples.
+
+Definitions come from the **global** agent settings file only. Project `.pi/settings.json` cannot install new hook commands. `wishcraft.hooksEnabled: false` disables every hook without deleting the config.
 
 ```json
 {
@@ -147,7 +156,7 @@ Hooks are commands that read JSON on stdin. Definitions come from the **global**
 }
 ```
 
-**bash-guard** (exit 2 = deny):
+**Example hook** (exit 2 = deny):
 
 ```bash
 #!/usr/bin/env bash
@@ -161,7 +170,7 @@ fi
 exit 0
 ```
 
-**write-audit** (append-only, never blocks):
+**Another example** (append-only, never blocks):
 
 ```bash
 #!/usr/bin/env bash
@@ -169,7 +178,7 @@ mkdir -p "$HOME/.pi/agent/logs"
 cat >> "$HOME/.pi/agent/logs/write-audit.jsonl"
 ```
 
-**SessionStart git-status** (extra context, never blocks):
+**SessionStart example** (extra context, never blocks):
 
 ```bash
 #!/usr/bin/env bash
@@ -188,7 +197,8 @@ Repairs run on custom/extension tools only, before hooks: drop null optionals, p
 
 ## Policy
 
-Declarative deny/inject rules in the **global** agent settings file. No shell commands — pure in-process regex. Evaluated before command hooks. `wishcraft.policyEnabled: false` disables policy without deleting rules.
+Declarative deny/inject rules live in the global settings file; see [docs/configuration.md](docs/configuration.md).
+No shell commands — pure in-process regex. Evaluated before command hooks. `wishcraft.policyEnabled: false` disables policy without deleting rules.
 
 ```json
 {
@@ -211,24 +221,18 @@ Declarative deny/inject rules in the **global** agent settings file. No shell co
 }
 ```
 
-**deny** — regex on tool input (`bash` uses `command`; other tools use JSON-serialized input). First match wins; the tool call is blocked with `reason`.
-
-**inject** — regex on file path after a matching tool completes; context is appended to the tool result (same shape as postToolUse hook `additionalContext`).
 
 ## Limits
 
 - No mouse on the live footer. Pi core owns that surface.
 - No second `alt+i` product. Ports stay on `alt+i`; other detail is `→` in the navigator.
 - ChefGroep status keys (`powerline.preset`, `powerline.tps`, `powerline.ports`) exist for other extensions. They are not the public pitch.
-- The legacy `@groeponline/pi-powerline-footer` package is deprecated on npm in favor of `@groeponline/pi-wishcraft`; the GitHub fork relationship is retained for upstream history and attribution.
+- The legacy `@groeponline/pi-powerline-footer` package is deprecated in favor of `@groeponline/pi-wishcraft`.
 - Tags are not rewritten. 0.19.x through current stay on the timeline.
 
 ## vNext Direction
 
-Wishcraft is evolving into Pi's animated operator layer — intent, skills, ideas, guardrails, and session state made visible and controllable without turning Pi into an IDE.
-
-- **[vNext Stacked PR Release Plan](docs/design/vnext-release-plan.md)**: Specifications for PR0 through PR8.
-- **[Design Corpus](docs/index.md#design-system--vnext-specifications)**: Deck, Signal, Motion Gallery, tokens, and the 10 structural presets. `npm run preview` renders the Deck frames.
+Wishcraft is Pi's animated operator layer. See the [release plan](docs/design/vnext-release-plan.md) and [design corpus](docs/index.md#design-system--vnext-specifications).
 
 ## Docs
 

package/ROADMAP.md

@@ -14,11 +14,11 @@ Baseline: **v1.3.1** (`e79737f`, tag `v1.3.1` 2026-08-25, npm `1.3.1`) — `orig
 
 ## 1.4 — Extension Contract (current, split)
 
-**1.4a — Settings registry** — *shipped* `0bfa5a2` `feat(config): typed settings registry` on `origin/main`. `src/config/settings-registry.ts` (28 defs, `SETTING_DEFAULTS`, `get/validate` O(1) maps, `SETTING_GROUPS`). `src/extension/settings/wishcraft-config-items.ts` now renders from registry (124 lines removed). Tests `tests/settings-registry.test.ts` + `wishcraft-config.test.ts` green (557). Still TODO: `contributeSettings()` Pi-contribution + `defaults/migrations` + docgen from registry.
+**1.4a — Settings registry** — *partly shipped* `0bfa5a2` `feat(config): typed settings registry` on `origin/main`. `src/config/settings-registry.ts` (28 defs, `SETTING_DEFAULTS`, `get/validate` O(1) maps, `SETTING_GROUPS`). `src/extension/settings/wishcraft-config-items.ts` now renders from registry (124 lines removed). Tests `tests/settings-registry.test.ts` + `wishcraft-config.test.ts` green. Still TODO: `contributeSettings()` Pi-contribution + `defaults/migrations` + docgen from registry.
 
-**1.4b — Contribution API** — *pending* `62d6156` `feat(contract): typed contribution API` on `origin/feat/contribution-api` (not yet on `origin/main`). `src/extension/contrib/{types,registry}.ts` ships `registerDeckRoute`/`registerSignalSource` (validate `id /^[a-z0-9][a-z0-9-_]*$/`, dedup, `false` never throw). Deck wired via `src/extension/ui/deck/routes.ts` `getAllDeckRouteDefs()`/`isDeckRoute()`. Still TODO: `registerMotion()`, `registerAppearanceContribution()`, `registerRecipeOrAction()` as separate slices (one PR per contract).
+**1.4b — Contribution API** — *shipped on main* (1.4 line; `src/extension/contrib/{types,registry,appearance}.ts`, tests `contrib-registry.test.ts` + `appearance-contrib.test.ts`). `registerDeckRoute`/`registerSignalSource`/`registerAppearanceContribution` (validate `id /^[a-z0-9][a-z0-9-_]*$/`, dedup, `false` never throw). Deck wired via `getAllDeckRouteDefs()`/`isDeckRoute()` (calls `getContributedDeckRoutes()`); Signal render calls `getContributedSignalSources()` fault-isolated (render.ts:196-203; a throwing/empty source never takes down Signal). Still TODO: `registerMotion()`, `registerRecipeOrAction()` as separate slices (one PR per contract).
 
-**1.4c — Signal wiring** — *next* after 1.4b merge. `src/signal/render.ts` must call `getContributedSignalSources()` with per-source fault isolation (`try/catch` → `null`), versioned capability scope. Done when both Deck and Signal contributions render without taking down the bar (`tests/contrib-registry.test.ts` + `signal.test.ts` + fault test).
+**1.4c — Signal wiring** — *shipped* (with 1.4b): both Deck and Signal contributions render fault-isolated; covered by `contrib-registry.test.ts` + `appearance-contrib.test.ts`.
 
 **1.4d — Preset composer** — Decouple `PresetDef` `tokens/chrome/signal/motion/deck/welcome/glyphs` from `src/config/structural-presets.ts` to allow `contributedAppearance` overrides per preset with validation. Done when `tests/structural-presets.test.ts` + `tokens.test.ts` cover contributed palette/motion.
 

package/STRATEGY.md

@@ -0,0 +1,54 @@
+---
+name: pi-wishcraft
+last_updated: 2026-08-28
+---
+
+# pi-wishcraft Strategy
+
+## Target problem
+
+pi-wishcraft today is a bundle of loosely-coupled segments (motion, ports, bash, vibes, skills) — each works on its own, none hangs together. There is no "this is how pi should feel" layer. The crux: wishcraft is not yet a default skin, it is a grab-bag of features.
+
+## Our approach
+
+pi-wishcraft is a customizable, feel-good default skin for pi — vibrant, warm, and tunable down to the last spinner. Where a tool must be finished to ship, a skin evolves, so we ship fast and iterate; perfection is the wrong goal. The bet: **vibe + customization depth** — the difference between wishcraft and any other pi extension is not feature count, it is that the skin lives.
+
+## Who it's for
+
+**Primary:** someone installing pi on day 1, typing `/wishcraft`, and choosing their first preset within five minutes — without reading the manual. They are hiring pi-wishcraft to make pi feel like their terminal, with essentials (bash, /cd, skills, health) already working on day one.
+
+## Key metrics
+
+- **Essentials-reliability** — bash-mode session breaks + ports/health crashes per release, measured via GitHub issues and npm feedback. Regresses the moment the foundation rots.
+- **First-touch customization** — % of fresh installs where a settings-file write happens within 7 days (opt-in local usage file). Stand-in for "felt at home" until real telemetry is in place.
+- **Customization depth** — average number of active theme / segment / preset tweaks per user after 30 days (settings file). Indicates "made it theirs."
+
+## Tracks
+
+### How we work
+
+Every track runs the same loop: **observe → root-cause → simplify → ship**. Half-finished work is removed, not shipped. Presets are data, not code, so the community can contribute via PR.
+
+### Skin & feel
+
+The v2 cutover landing this week: powerline, welcome, bash, ports, skills, motion as one coherent skin — not a pile of segments. The first preset must work out of the box.
+
+_Loop in this track:_ segment crashes and motion stalls are bugs, not features; we trace and remove them before adding more.
+
+### Customization depth
+
+Every detail tunable — colour, font, animation, spinner, preset. Deck and (soon) Studio are the two entry points. Presets and segments live as data so users and the community can extend without forking.
+
+_Loop in this track:_ presets that no one uses get simplified or removed; a knob nobody touches is dead weight.
+
+### Skill Studio & modes
+
+Studio (in progress, U5+) as the in-process workshop for skills, plus extension modes like creator, PTC, minimal, code, verbose. Joins up with deepseek, codex, claude, and oh-my-pi conventions — wishcraft does not ship its own harness.
+
+_Loop in this track:_ advice that users ignore is a signal; modes that feel "cool" but unused get cut.
+
+## Not working on
+
+- A standalone agents / harness runtime — wishcraft plugs into existing harnesses, never replaces one.
+- Tool-product features that don't make the skin more beautiful or more tunable (analytics dashboards, productivity trackers).
+- Mobile / web / cloud variants — pi is terminal-native; that stays the case.

package/bash-mode/editor-input.ts

@@ -11,7 +11,9 @@ export const DEFAULT_EDITOR_BOUNDARY_SHORTCUTS: EditorBoundaryShortcuts = {
 };
 
 export function isPrintableInput(data: string): boolean {
-  return data.length === 1 && data.charCodeAt(0) >= 32;
+  const points = [...data];
+  if (points.length !== 1) return false;
+  return (points[0]?.codePointAt(0) ?? 0) >= 32;
 }
 
 export function isCommandUndoShortcut(data: string): boolean {

package/bash-mode/editor.ts

@@ -42,6 +42,7 @@ export class BashModeEditor extends CustomEditor {
   private ghost: GhostSuggestion | null = null;
   private ghostAbort: AbortController | null = null;
   private ghostToken = 0;
+  private ghostSchedule: ReturnType<typeof setTimeout> | null = null;
 
   constructor(
     tui: any,
@@ -76,9 +77,26 @@ export class BashModeEditor extends CustomEditor {
     this.scheduleGhostUpdate();
   }
 
+  /** Resolve a ghost immediately for callers that need a settled refresh. */
+  async refreshGhostSuggestionNow(): Promise<void> {
+    const text = this.getExpandedText();
+    const currentToken = ++this.ghostToken;
+    this.ghostAbort?.abort();
+    this.ghostSchedule = null;
+
+    const controller = new AbortController();
+    this.ghostAbort = controller;
+    const ghost = await this.optionsRef.resolveGhostSuggestion(text, controller.signal);
+    if (controller.signal.aborted || currentToken !== this.ghostToken) return;
+    this.ghost = ghost;
+    this.tui.requestRender();
+  }
+
   clearGhostSuggestion(): void {
     this.ghostAbort?.abort();
     this.ghostAbort = null;
+    if (this.ghostSchedule) clearTimeout(this.ghostSchedule);
+    this.ghostSchedule = null;
     this.ghost = null;
   }
 
@@ -145,6 +163,24 @@ export class BashModeEditor extends CustomEditor {
         return;
       }
 
+      // v2 forward-mode: while a command runs, printable input goes to the
+      // PTY stdin (AE1). Interrupt stays a keybinding above; key-releases
+      // and multi-key sequences stay in the editor. Enter (\r) and EOF
+      // (\x04) must also forward — line-oriented stdin programs (read,
+      // sudo, git rebase -i) cannot proceed without a line terminator.
+      // Opt-in via forwardWhileRunning so v1 run-blocked behavior unchanged.
+      if (
+        bashMode &&
+        this.optionsRef.isShellRunning() &&
+        (this.optionsRef.forwardWhileRunning?.() ?? false) &&
+        this.optionsRef.onForwardInput != null &&
+        !isKeyRelease(data) &&
+        (isPrintableInput(data) || data === "\r" || data === "\n" || data === "\x04")
+      ) {
+        this.optionsRef.onForwardInput(data);
+        return;
+      }
+
       if (
         bashMode &&
         this.keybindingsRef.matches(data, "tui.editor.cursorUp")
@@ -338,23 +374,24 @@ export class BashModeEditor extends CustomEditor {
     const text = this.getExpandedText();
     const currentToken = ++this.ghostToken;
     this.ghostAbort?.abort();
+    if (this.ghostSchedule) clearTimeout(this.ghostSchedule);
+    this.ghostSchedule = null;
 
     const controller = new AbortController();
     this.ghostAbort = controller;
+    // Start immediately so editor actions have deterministic refresh semantics.
+    // The abort signal and token still discard stale results when typing races
+    // with an in-flight history/filesystem lookup.
     this.optionsRef
       .resolveGhostSuggestion(text, controller.signal)
       .then((ghost) => {
-        if (controller.signal.aborted || currentToken !== this.ghostToken)
-          return;
+        if (controller.signal.aborted || currentToken !== this.ghostToken) return;
         this.ghost = ghost;
         this.tui.requestRender();
       })
       .catch((error) => {
-        if (error instanceof Error && error.message === "aborted") return;
-        console.debug(
-          "[wishcraft] Failed to resolve bash ghost suggestion:",
-          error,
-        );
+        if (controller.signal.aborted || (error instanceof Error && error.message === "aborted")) return;
+        console.debug("[wishcraft] Failed to resolve bash ghost suggestion:", error);
       });
   }
 }

package/bash-mode/forward.ts

@@ -0,0 +1,64 @@
+/**
+ * Forward state for bash v2 (U4). Pure reducer: given a ForwardState and
+ * raw input data, decide what the PTY session should do (stdin, interrupt,
+ * nothing) and what the new state should be. The BashForwardEditor drives
+ * this; it has no TUI imports so the unit is fully testable.
+ */
+
+import { matchesKey } from "@earendil-works/pi-tui";
+
+export interface ForwardState {
+  running: boolean;
+  lastExitCode: number | null;
+  cwd: string;
+}
+
+export type PtyAction = "stdin" | "interrupt";
+
+export interface ForwardDecision {
+  state: ForwardState;
+  ptyAction?: PtyAction;
+}
+
+const DONE_SENTINEL = "__PI_DONE__";
+
+export function createForwardState(): ForwardState {
+  return { running: false, lastExitCode: null, cwd: "" };
+}
+
+function parseSentinel(data: string): { exitCode: number; cwd: string } | null {
+  if (!data.startsWith(`${DONE_SENTINEL}:`)) return null;
+  const rest = data.slice(DONE_SENTINEL.length + 1);
+  const colon = rest.indexOf(":");
+  if (colon === -1) return null;
+  const exitCode = Number.parseInt(rest.slice(0, colon), 10);
+  const cwd = rest.slice(colon + 1);
+  if (!Number.isFinite(exitCode)) return null;
+  return { exitCode, cwd };
+}
+
+export function handleForwardInput(
+  state: ForwardState,
+  data: string,
+): ForwardDecision {
+  if (data.length === 0) return { state };
+
+  const sentinel = parseSentinel(data);
+  if (sentinel) {
+    return {
+      state: {
+        running: false,
+        lastExitCode: sentinel.exitCode,
+        cwd: sentinel.cwd,
+      },
+    };
+  }
+
+  if (!state.running) return { state };
+
+  if (matchesKey(data, "ctrl+c") || data === "\x03") {
+    return { state, ptyAction: "interrupt" };
+  }
+
+  return { state, ptyAction: "stdin" };
+}