@groeponline/pi-wishcraft 1.4.11 → 1.4.12

package/AGENTS.md

@@ -1,102 +1,314 @@
-# AGENTS.md
-
-Guidance for AI agents (and humans) working on this repository.
-
-## What this project is
-
-pi-wishcraft is a powerline-style status bar and wishcraft interaction layer for the `pi`
-coding agent: status segments, welcome overlay/header, working "vibes" loading
-messages, a queue + idea inbox, bash mode, prompt/stash history, and full
-user customization.
-
-## Repository layout
-
-- `index.ts` — package entry: the public barrel. It re-exports the default
-  activation function and the documented public API (`resolveShortcutConfig`,
-  `parseBashModeSettings`, `PowerlineShortcuts`). Keep it a barrel; no
-  implementation lives here.
-- `src/` — the proxy-free extension runtime, organized by domain:
-  - `src/extension/` — the extension runtime, organized into domain subfolders:
-    `core/` (constants, types, `state.ts` hub, segment-context), `commands/`
-    (slash commands, queue commands, bash-mode actions, vibe command),
-    `session/` (activation, session lifecycle, git invalidation, stale-context),
-    `ui/` (custom editor, layout, menu views, powerline widgets, status-line
-    renderers), `history/` (prompt + stash history), `queue/` (queue context +
-    integration), `settings/` (settings IO), `shortcuts/` (shortcut config +
-    router), `welcome/` (welcome control + integration), `skills/` (inline
-    invocation). Leaf modules keep the dependency graph acyclic: shared types
-    and constants live in `core/`, queue/welcome callbacks are wired through
-    leaves or `RuntimeState`, and `core/state.ts` is the hub that only has
-    inbound edges. Verify with `npx madge --circular src index.ts bash-mode
-    queue`.
-  - `src/config/` — powerline config parsing, presets, types, segment ids/options.
-  - `src/segments/` — segment registry and the segment renderers.
-  - `src/theme/` — colors, icons, separators, theme loading.
-  - `src/usage/` — token stats, context usage, currency rates.
-  - `src/welcome/` — welcome header/overlay rendering and discovery.
-  - `src/working-vibes/` — vibe theme storage, generation, manager.
-  - `src/git/`, `src/shell/`, `src/editor/`, `src/render/`, `src/paths/`,
-    `src/shortcuts/`, `src/lifecycle/` — small single-purpose domains.
-- `bash-mode/` — managed shell session, transcript store, completion engine.
-- `queue/` — file-backed queue/inbox store and types.
-- `tests/` — flat `node:test` suite (`tests/*.test.ts`); structural tests read
-  the module under test from `src/`, never from `index.ts` source text.
-- `scripts/release.mjs` — zero-dep release helper (bump, CHANGELOG, tag).
-
-## Rules
-
-- **No root-level monofiles.** Implementation lives under `src/` organized by
-  domain; `index.ts` is only a barrel. Import implementation via
-  `src/**` paths (or `bash-mode/`, `queue/`).
-- **Module size:** when a file exceeds ~450 lines, split it along domain
-  boundaries (e.g. command handlers out of `commands.ts`, git invalidation
-  out of `session-lifecycle.ts`). Prefer many cohesive small modules.
-- **No circular imports.** Domain modules must not import back into
-  `src/extension/core/state.ts` for callbacks; move the callback into a leaf module
-  (e.g. `welcome-control.ts`) or wire it through `RuntimeState`.
-- **Bun/Node-native TS:** `import` paths carry `.ts` extensions
-  (`allowImportingTsExtensions`), `node:`-prefixed builtins, `node --test`
-  with type stripping. No build step.
-- **English UI:** operator overlays, notify strings, and `/wishcraft` copy are
-  English. Do not add Dutch UI strings.
-- **Tests:** behavior changes in `src/` need a focused regression test near
-  the existing tests for that subsystem; structural tests assert on module
-  files in `src/` (never `index.ts`).
-
-## Commands
+# Repository Guidelines
+
+## Project Overview
+
+`pi-wishcraft` is an operator cockpit extension for the **Pi** coding agent (`@earendil-works/pi-coding-agent`). It provides a powerline-style status bar, welcome overlay/header, working "vibes" loading messages, a file-backed idea queue, sticky Bash mode with PTY sessions, inline skill invocation, command-level hooks/policy controls, and a fullscreen Skill Studio. The package ships as a Pi extension rooted at `./index.ts` and is published to npm as `@groeponline/pi-wishcraft`.
+
+## Architecture & Data Flow
+
+### Bootstrap & Runtime Hub
+
+The extension bootstraps from `index.ts`, which re-exports `powerlineFooter` from `src/extension/session/activate.ts`. Activation reads Pi settings, parses powerline config, creates a mutable `RuntimeState` (via `createRuntimeState` in `src/extension/core/state.ts`), and registers Pi lifecycle hooks, commands, segments, presets, shortcuts, skills, and bash-mode sessions.
+
+`src/extension/core/state.ts` is the **central mutable hub** — it holds `config`, schedulers, and derived caches. All runtime mutations flow through `RuntimeState` and callback hooks (`requestStatusRender`, `requestImmediateStatusRender`, `resetLayoutCache`, `dispatchSignalEvent`). Leaf modules consume and extend this hub but never import sibling leaves directly.
+
+### Rendering Pipeline
+
+The render pipeline is a pure, acyclic chain:
+
+1. **SegmentContext** is built read-only by `src/extension/core/segment-context.ts` from `RuntimeState`, config, theme, git state, and usage data.
+2. **Segment renderers** are dispatched through `src/segments/registry.ts` — a fault-isolated `renderSegment` that maps segment IDs to pure render functions.
+3. **Status line composition** happens in `src/render/v2-entry.ts`, which orders segments, inserts the motion rail from `src/render/motion-rail.ts`, then delegates painting to `src/render/paint.ts` and `src/render/v2-adapter.ts`.
+
+### Motion & Signal
+
+The motion engine (`src/motion/*`) defines a catalog of animations (`src/motion/catalog.ts`), a centralized scheduler (`src/motion/scheduler.ts`), and an accessibility policy (`src/motion/policy.ts`). The Signal controller (`src/signal/controller.ts`) leases one motion consumer per runtime event and manages the lifecycle of rendered signals on the status-line rail.
+
+### Leaf Domains
+
+Each domain operates through `RuntimeState` callbacks:
+
+- **bash-mode/** — PTY-managed shell sessions, transcripts, ghost suggestions, completion engine
+- **queue/** — file-backed JSONL queue/inbox store with aliases and retention
+- **working-vibes/** — themed loading message generation and persistence
+- **welcome/** — fullscreen TUI overlay with branded layout and countdown
+- **usage/** — token/cost/context ledger, TPS ring, daily budget
+- **theme/** — color resolution, icons, separators, token mapping
+- **studio/** — Skill Studio UI component, Deck renderer, advice engine
+- **skills/** — skill registry, manager, inline invocation, doctor, status
+- **hooks/** — session/context/tool hooks, policy engine, repairs
+- **settings/** — settings IO, config commands, appearance write-back
+
+### Acyclic Dependency Rule
+
+Domain modules must not import back into the hub for callbacks. Shared types and constants live in `src/extension/core/`. Verify no circular imports:
+
+```bash
+npm run circular
+# → madge --circular src index.ts bash-mode queue
+```
+
+## Key Directories
+
+| Directory | Purpose |
+|---|---|
+| `src/` | Extension runtime, organized by domain (core, config, segments, render, signal, motion, theme, welcome, working-vibes, usage, studio, skills, hooks, settings, shortcuts, history, queue, contrib) |
+| `src/extension/` | Pi extension runtime: `core/` (hub, types, constants), `session/` (activation, lifecycle), `ui/` (deck, layout), `commands/`, `shortcuts/`, `queue/`, `welcome/`, `skills/`, `hooks/`, `settings/`, `history/`, `contrib/` |
+| `src/config/` | Powerline config parsing, presets, settings registry, tokens |
+| `src/segments/` | Segment registry and builtin renderers (core, system, usage, custom) |
+| `src/theme/` | Colors, icons, separators, token mapping |
+| `src/render/` | Paint primitives, v2 adapter, layout, motion-rail |
+| `src/motion/` | Motion catalog, scheduler, policy, types, gallery, composer |
+| `src/signal/` | Signal controller and event dispatching |
+| `src/welcome/` | Welcome overlay, renderer, art, layout |
+| `src/studio/` | Studio UI component, deck, advice engine |
+| `bash-mode/` | Standalone PTY shell session management (editor, transcript, completion, forward mode) |
+| `queue/` | Standalone file-backed queue store and types |
+| `tests/` | Flat `node:test` suite (`tests/*.test.ts`), helpers in `tests/helpers/`, fixtures in `tests/fixtures/` |
+| `docs/` | Operator guides (configuration, commands, bash-mode, segments, skills, etc.) |
+| `docs/design/` | vNext design specs (not operator how-to docs) |
+| `.compound-engineering/` | CE overlay: tracked `config.yaml`, artifacts, plans |
+
+## Development Commands
 
 ```bash
+# Install dependencies
 npm ci
-npm run typecheck      # tsc --noEmit (strict)
-npm test               # node --experimental-strip-types --test tests/**/*.test.ts
+
+# Type check (strict, no emit)
+npm run typecheck
+
+# Run all tests
+npm test
+
+# Check for circular imports
+npm run circular
+
+# Full package contract verification (for publish preparation)
+npm run verify:package
+
+# Local preview server (Deck/Signal/motion surfaces)
+npm run preview
+
+# Dockerized parallel testing (typecheck + test + circular)
+scripts/docker-test.sh [-n N]
+
+# Cloud agent bootstrap (Node 24, pi CLI install)
+scripts/cloud-agent-install.sh
+scripts/cloud-agent-start.sh
+```
+
+### Release Flow
+
+Releases are CI-driven via GitHub Actions:
+
+```bash
+# Locally: bump version, rewrite CHANGELOG, tag, optional push
+node scripts/release.mjs          # or: npm run release
+
+# Publish to npm (CI handles auth)
+scripts/npm-publish.sh
+
+# Create GitHub Release
+scripts/github-release.sh
+```
+
+CI workflows (`.github/workflows/`):
+- `test.yml` — Node 24, typecheck, test, circular, verify:package, npm audit
+- `release.yml` — reuses test.yml, prepares release-candidate branch
+- `promote-release-candidate.yml` — promotes verified SHA to main, tags, dispatches publish
+
+## Code Conventions & Common Patterns
+
+### Module Structure
+
+- **No root-level monofiles**: implementation lives under `src/` by domain; `index.ts` is a barrel only
+- **Module size**: split files exceeding ~450 lines along domain boundaries
+- **TypeScript**: `.ts` extensions on all imports (`allowImportingTsExtensions`), `node:`-prefixed builtins, strict mode, no build step
+- **Entry point**: `index.ts` re-exports `powerlineFooter` and shortcut helpers — keep it a barrel, no implementation
+
+### Import Paths & Dependency Direction
+
+```typescript
+// Correct: import via domain paths
+import { SEGMENTS } from "src/segments/registry.ts";
+import { createRuntimeState } from "src/extension/core/state.ts";
+
+// Incorrect: avoid importing implementation from index.ts barrel
+import { powerlineFooter } from "./index.ts"; // tests must not do this
+```
+
+- Tests import from `src/<domain>/*` module files directly, **never** from `index.ts`
+- Domain modules must not import back into the hub for callbacks — use `RuntimeState` + callback hooks
+
+### State Management
+
+`RuntimeState` (from `src/extension/core/state.ts`) is the singleton mutable hub. It owns:
+- `config` — parsed powerline configuration
+- Motion/signal/render schedulers
+- Derived caches (segment context, layout)
+
+Leaf consumers receive `RuntimeState` plus callback hooks rather than importing sibling leaves directly.
+
+### Callback Wiring Pattern
+
+```typescript
+// Leaf modules receive hooks, do not import siblings
+function createRuntimeState(hooks: {
+  requestStatusRender: () => void;
+  requestImmediateStatusRender: () => void;
+  resetLayoutCache: () => void;
+}): RuntimeState
+```
+
+### Error Handling
+
+- Segment rendering is fault-isolated — a failing segment does not crash the status line
+- Policy engine evaluates pre/post tool hooks with deny/inject results
+- Hooks runner uses stdin JSON + timeout + process-group kill
+
+### Naming Conventions
+
+- Domain barrels: `src/<domain>/index.ts`
+- Segment files: `src/segments/{core,system,usage,custom}.ts`
+- Motion modules: `src/motion/{catalog,scheduler,policy,types}.ts`
+- Test files: `tests/<subsystem>.test.ts` (flat suite, descriptive names)
+
+## Important Files
+
+### Entry Points
+- `index.ts` — package barrel (re-exports `powerlineFooter`, `resolveShortcutConfig`, `parseBashModeSettings`, `PowerlineShortcuts`)
+- `src/extension/session/activate.ts` — activation bootstrap
+- `src/extension/core/state.ts` — `RuntimeState` hub, `createRuntimeState`
+- `src/extension/core/types.ts` — `RuntimeState` type definitions
+
+### Configuration
+- `src/config/parse.ts` — `parsePowerlineConfig`, `PowerlineConfig` interface
+- `src/config/settings-registry.ts` — operator settings definitions, defaults, validation
+- `src/config/structural-presets.ts` — structural preset definitions
+- `src/config/tokens.ts` — semantic token mapping
+
+### Rendering
+- `src/render/v2-entry.ts` — `renderStatusLineV2` (composed render entry)
+- `src/render/v2-adapter.ts` — layout adaptation for painting
+- `src/render/paint.ts` — painting primitives
+- `src/render/motion-rail.ts` — motion rail surface rendering
+
+### Segments
+- `src/segments/registry.ts` — `SEGMENTS` registry, `renderSegment` dispatcher
+- `src/segments/core.ts` — model, shell_mode, path, git, time, session, hostname
+- `src/segments/system.ts` — thinking, subagents, queue, extension_statuses, open ports/TPS
+- `src/segments/usage.ts` — token_in/out/total, cost, context_pct, cache_read/write
+- `src/segments/custom.ts` — custom registered/static segments
+
+### Signal & Motion
+- `src/signal/controller.ts` — `SignalRuntime` lifecycle
+- `src/signal/integration.ts` — event dispatcher
+- `src/motion/catalog.ts` — motion definitions, channel matrix
+- `src/motion/scheduler.ts` — shared `MotionScheduler`
+- `src/motion/policy.ts` — accessibility/policy filter
+
+### Bash Mode
+- `bash-mode/pty-session.ts` — PTY session abstraction
+- `bash-mode/session-factory.ts` — shell session creation
+- `bash-mode/transcript.ts` — `BashTranscriptStore`
+- `bash-mode/completion.ts` — completion engine
+
+### Queue
+- `queue/store.ts` — `PowerlineQueueStore` (filesystem-backed JSONL)
+- `queue/types.ts` — queue item/target/status types
+
+### Studio & Skills
+- `src/studio/component.ts` — fullscreen Skill Studio component
+- `src/studio/deck/render.ts` — Deck renderer
+- `src/studio/advise/engine.ts` — advice pane engine
+- `src/extension/skills/skill-registry.ts` — skill catalog
+- `src/extension/skills/skill-manager.ts` — skill management commands
+
+### Release & Verification
+- `scripts/release.mjs` — version bump, CHANGELOG rewrite, tag
+- `scripts/verify-package.mjs` — package contract checks (name, description, keywords, pi manifest, resources, peers)
+- `scripts/verify-pi-package-contract.mjs` — Pi package contract validation
+- `scripts/npm-publish.sh` — idempotent npm publish with marker-tag promotion
+- `scripts/github-release.sh` — GitHub Release creation
+- `scripts/gen-lantern.mjs` — generates lantern art pixel-grid module
+
+## Runtime/Tooling Preferences
+
+| Requirement | Detail |
+|---|---|
+| **Node** | v22.14 system default; Node 24 via nvm for CI and pi CLI (pi requires ≥22.19) |
+| **Package manager** | npm (lockfile v3) |
+| **TypeScript** | 5.9.3, strict mode, `NodeNext` module/resolution, `allowImportingTsExtensions`, no build step |
+| **Test runner** | Node built-in `node:test` with `--experimental-strip-types` type stripping |
+| **Circular import check** | `madge --circular src index.ts bash-mode queue` (via `npm run circular`) |
+| **Import style** | `.ts` extensions on all imports, `node:`-prefixed builtins |
+| **Pi CLI** | Installed at `^0.84.0`; wrapped to run under Node 24 via nvm |
+| **Docker** | `fuse-overlayfs` storage driver for nested VM testing |
+| **Compound Engineering** | `.compound-engineering/` overlay; portable skills via `~/.agents/skills/ce-*`; native Cursor plugin disabled |
+
+## Testing & QA
+
+### Test Framework
+
+- **Runner**: Node's built-in `node:test` (flat per-file suites)
+- **Assertions**: `node:assert/strict`
+- **Type stripping**: `--experimental-strip-types` (no `tsc` compilation in tests)
+- **Invocation**: `npm test` runs `node --experimental-strip-types --test tests/**/*.test.ts`
+
+### Test Organization
+
+Tests are flat in `tests/` with supporting helpers and fixtures:
+
+- `tests/helpers/strip-ansi.ts` — shared ANSI stripping utility
+- `tests/fixtures/skill-template-golden.ts` — golden fixture for skill templates
+
+### Test Types
+
+| Type | Convention | Examples |
+|---|---|---|
+| **Structural tests** | Assert on module contracts: layout rules, config precedence, catalog/scheduler invariants, registry behavior | `effective-config.test.ts`, `render-v2.test.ts`, `tokens.test.ts`, `hooks.test.ts` |
+| **Behavior tests** | Assert runtime output: rendered strings, command execution, state changes, temp FS flows | `signal.test.ts`, `system-segments.test.ts`, `queue-store.test.ts`, `deck.test.ts` |
+| **Golden tests** | Pin exact rendered output or template text | `signal-golden.test.ts`, `skill-templates.test.ts` |
+
+### Import Conventions
+
+Tests import from `src/<domain>/*` module files directly — **never** from `index.ts`. For example:
+
+```typescript
+// Correct
+import { SEGMENTS } from "src/segments/registry.ts";
+
+// Incorrect — do not import from index.ts
+import { powerlineFooter } from "./index.ts";
+```
+
+### CI Verification Gates
+
+The `.github/workflows/test.yml` workflow enforces the full verification chain:
+
+```bash
+npm run typecheck     # tsc --noEmit
+npm test              # node --test
+npm run circular      # madge --circular
+npm run verify:package # verify-package.mjs + verify-pi-package-contract.mjs
+npm audit             # security audit
+```
+
+### Release Verification
+
+Before any publish, `prepublishOnly` runs the full chain:
+
+```bash
+tsc --noEmit && verify-package.mjs && verify-pi-package-contract.mjs
+```
+
+### Dockerized Parallel Testing
+
+For isolated, parallel CI runs:
+
+```bash
+scripts/docker-test.sh -n 4   # 4 parallel containers
 ```
 
-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`.
+Each container runs `typecheck + test + circular` with a shared read-only `node_modules` bind mount.

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [1.4.12] - 2026-09-05
+
 ## [1.4.11] - 2026-08-30
 
 ## [1.4.10] - 2026-08-30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groeponline/pi-wishcraft",
-  "version": "1.4.11",
+  "version": "1.4.12",
   "description": "Operator cockpit for Pi: live powerline status, searchable skills, idea queue, sticky Bash, hooks, policy controls, and session UX.",
   "type": "module",
   "files": [
@@ -63,7 +63,7 @@
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "^0.84.0",
-    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@earendil-works/pi-coding-agent": "^0.84.3",
     "@earendil-works/pi-tui": "^0.84.0",
     "@types/node": "24.13.3",
     "madge": "^8.0.0",

package/src/extension/skills/global-registry.ts

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface GlobalRegistrySkill {
+  name: string;
+  description: string;
+  category: string;
+  family: string;
+  metaSkill: string | null;
+  role: string | null;
+  routerParent: string | null;
+  mounts: string[];
+  drift: boolean;
+  filePath: string;
+}
+
+interface RegistryPayload {
+  schema?: string;
+  skills?: unknown[];
+}
+
+export function globalRegistryPath(): string {
+  return process.env.CHEFGROEP_SKILL_REGISTRY?.trim() || join(homedir(), ".config", "chefgroep", "skill-registry", "skills.json");
+}
+
+function expandHome(path: string): string {
+  if (path === "~") return homedir();
+  if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+  return path;
+}
+
+export function loadGlobalSkillRegistry(path = globalRegistryPath()): GlobalRegistrySkill[] {
+  if (!existsSync(path)) return [];
+  let payload: RegistryPayload;
+  try {
+    payload = JSON.parse(readFileSync(path, "utf8")) as RegistryPayload;
+  } catch {
+    return [];
+  }
+  if (payload.schema !== "chefgroep-global-skill-registry/v1" || !Array.isArray(payload.skills)) return [];
+  const out: GlobalRegistrySkill[] = [];
+  for (const raw of payload.skills) {
+    if (!raw || typeof raw !== "object") continue;
+    const skill = raw as Record<string, any>;
+    if (typeof skill.name !== "string" || typeof skill.description !== "string") continue;
+    const canonical = skill.canonical && typeof skill.canonical === "object" ? skill.canonical : {};
+    const canonicalPath = typeof canonical.path === "string" ? canonical.path : "";
+    out.push({
+      name: skill.name,
+      description: skill.description,
+      category: typeof skill.category === "string" ? skill.category : "general",
+      family: typeof skill.family === "string" ? skill.family : "general",
+      metaSkill: typeof skill.meta_skill === "string" ? skill.meta_skill : null,
+      role: typeof skill.role === "string" ? skill.role : null,
+      routerParent: typeof skill.router_parent === "string" ? skill.router_parent : null,
+      mounts: Array.isArray(skill.mounts) ? skill.mounts.filter((x: unknown): x is string => typeof x === "string") : [],
+      drift: skill.drift === true,
+      filePath: expandHome(canonicalPath),
+    });
+  }
+  return out;
+}

package/src/extension/skills/skill-registry.ts

@@ -14,6 +14,7 @@ import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, mkdirSy
 import { basename, dirname, join, relative } from "node:path";
 import { getAgentDir, getAgentPath } from "../../paths/agent-dirs.ts";
 import { parseSkillFrontmatter, stripFrontmatter } from "../../core/frontmatter.ts";
+import { loadGlobalSkillRegistry } from "./global-registry.ts";
 
 /** Category: where the skill came from. */
 export type SkillCategory = "global" | "project" | "prompts" | "extra";
@@ -39,6 +40,14 @@ export interface SkillEntry {
   frontmatterKeys: string[];
   /** Frontmatter trigger value (e.g. /test, /showcase). */
   trigger: string | null;
+  /** Machine-side ChefGroep routing metadata when the global registry is installed. */
+  routingCategory?: string;
+  routingFamily?: string;
+  metaSkill?: string | null;
+  role?: string | null;
+  routerParent?: string | null;
+  mounts?: string[];
+  registryDrift?: boolean;
   /** Diagnostic message (core diagnostics, or empty description). */
   warning?: string;
 }
@@ -108,6 +117,7 @@ export function setSkillCacheInvalidationHandler(handler: (() => void) | null):
 
 const usageCache = new Map<string, SkillUsage>();
 let usageLoaded = false;
+let usageLoadedFrom: string | null = null;
 
 /** Drop the discovery cache (the next read scans again). */
 export function invalidateSkillCache(): void {
@@ -340,11 +350,24 @@ export function loadSkillCatalog(cwd: string = process.cwd()): SkillEntry[] {
   );
   cachedAt = now;
   cachedCwd = cwd;
-  cachedEntries = [
+  const localEntries = [
     ...deduped.filter((e) => !looseNames.has(e.name)),
     ...loose,
     ...rejected,
-  ].sort((a, b) => a.name.localeCompare(b.name));
+  ];
+
+  // Enrich local Pi entries with routing metadata, but do not append
+  // registry-only skills here: generic Pi catalog/count semantics stay local.
+  const registry = loadGlobalSkillRegistry();
+  const registryByName = new Map(registry.map((r) => [r.name, r] as const));
+  for (const entry of localEntries) {
+    const r = registryByName.get(entry.name);
+    if (!r) continue;
+    entry.routingCategory = r.category; entry.routingFamily = r.family;
+    entry.metaSkill = r.metaSkill; entry.role = r.role; entry.routerParent = r.routerParent;
+    entry.mounts = r.mounts; entry.registryDrift = r.drift;
+  }
+  cachedEntries = localEntries.sort((a, b) => a.name.localeCompare(b.name));
   cachedPathMap = new Map(cachedEntries.map((e) => [e.name, e.filePath] as const));
   cachedTriggerMap = new Map(
     cachedEntries
@@ -354,6 +377,32 @@ export function loadSkillCatalog(cwd: string = process.cwd()): SkillEntry[] {
   return cachedEntries;
 }
 
+/** Full machine-side catalog for Skill Studio only. */
+export function loadSkillStudioCatalog(cwd: string = process.cwd()): SkillEntry[] {
+  const local = loadSkillCatalog(cwd).map((e) => ({ ...e }));
+  const localNames = new Set(local.map((e) => e.name));
+  const registryOnly: SkillEntry[] = loadGlobalSkillRegistry()
+    .filter((r) => !localNames.has(r.name))
+    .map((r) => {
+      let sizeBytes = 0, lineCount = 0, mtimeMs = 0;
+      let warning: string | undefined;
+      try {
+        const content = readFileSync(r.filePath, "utf8");
+        sizeBytes = Buffer.byteLength(content, "utf8");
+        lineCount = content.split("\n").length;
+        mtimeMs = statSync(r.filePath).mtimeMs;
+      } catch { warning = "registry source not readable on this host"; }
+      return {
+        name: r.name, description: r.description, filePath: r.filePath, baseDir: dirname(r.filePath),
+        isDirectorySkill: basename(r.filePath) === "SKILL.md", category: "extra" as SkillCategory,
+        disableModelInvocation: false, sizeBytes, lineCount, mtimeMs, frontmatterKeys: [], trigger: null, warning,
+        routingCategory: r.category, routingFamily: r.family, metaSkill: r.metaSkill, role: r.role,
+        routerParent: r.routerParent, mounts: r.mounts, registryDrift: r.drift,
+      };
+    });
+  return [...local, ...registryOnly].sort((a, b) => a.name.localeCompare(b.name));
+}
+
 /** Compat: name → file path (for inline-invocation $skill). */
 export function getAvailableSkills(): Map<string, string> {
   loadSkillCatalog();
@@ -376,10 +425,13 @@ function usageFile(): string {
 }
 
 function loadUsage(): void {
-  if (usageLoaded) return;
+  const file = usageFile();
+  if (usageLoaded && usageLoadedFrom === file) return;
   usageLoaded = true;
+  usageLoadedFrom = file;
+  usageCache.clear();
   try {
-    const raw = readFileSync(usageFile(), "utf8");
+    const raw = readFileSync(file, "utf8");
     const parsed = JSON.parse(raw) as Record<string, SkillUsage>;
     for (const [name, u] of Object.entries(parsed)) {
       usageCache.set(name, { count: u.count ?? 0, lastUsed: u.lastUsed ?? 0 });

package/src/motion/index.ts

@@ -36,6 +36,7 @@ export {
   allowedChannels,
   allowsColorTransition,
   cadenceFor,
+  channelsForMotion,
   describeMotionEvent,
   effectiveLevel,
   prefersAsciiGlyphs,

package/src/motion/policy.ts

@@ -8,7 +8,7 @@
  */
 
 import { CADENCE_MS, CHANNEL_MATRIX, PREVIEW_INTERVAL_MS } from "./catalog.ts";
-import type { MotionChannel, MotionEvent, MotionLevel, MotionPolicy, MotionToggles } from "./types.ts";
+import type { MotionChannel, MotionDef, MotionEvent, MotionLevel, MotionPolicy, MotionToggles } from "./types.ts";
 
 const CHANNEL_TOGGLE: Record<MotionChannel, keyof MotionToggles> = {
   workingGlyph: "state",
@@ -53,6 +53,33 @@ export function effectiveLevel(policy: MotionPolicy): MotionLevel {
   return policy.level;
 }
 
+/**
+ * Channels a motion is allowed to drive under the current policy.
+ *
+ * Same a11y filter as `allowedChannels`, but the source is the **motion's own
+ * declared channels** instead of the event table. This is what makes an
+ * explicit motion choice (preset signature or `appearance.motion` override)
+ * actually runnable: the event no longer vetoes a motion it wasn't paired
+ * with by the default matrix — the motion decides, the policy still filters.
+ */
+export function channelsForMotion(
+  motion: MotionDef,
+  policy: MotionPolicy,
+): MotionChannel[] {
+  if (policy.screenReader || policy.level === "off") return [];
+
+  const effective = effectiveLevel(policy);
+  return motion.channels.filter((channel) => {
+    if (effective === "functional") {
+      return channel === "workingGlyph" || channel === "panelIndicator";
+    }
+    if (effective === "reduced") {
+      if (channel === "ambient" || channel === "signal") return false;
+    }
+    return policy.toggles[CHANNEL_TOGGLE[channel]];
+  });
+}
+
 export function cadenceFor(
   channel: MotionChannel,
   policy: MotionPolicy,

package/src/render/motion-rail.ts

@@ -6,7 +6,8 @@
  * rail, streaming = travelling head + trail, compacting = inward heads.
  */
 
-import { sweepPosition, trailGlyph } from "../motion/index.ts";
+import { defaultMotionFor, getMotion } from "../motion/catalog.ts";
+import { frameAt, framesOf, sweepPosition, trailGlyph } from "../motion/frames.ts";
 import type { SignalRuntime } from "../signal/controller.ts";
 import type { SignalSpec } from "../config/types.ts";
 import { ansi, colorEnabled, getFgAnsiCode } from "../theme/colors.ts";
@@ -16,6 +17,7 @@ export function renderActivity(
   runtime: SignalRuntime,
   spec: SignalSpec,
   ascii = false,
+  width = 80,
 ): string {
   const label = runtime.activity || "ready";
   const open = spec.caps.leftOpen ?? "";
@@ -23,28 +25,70 @@ export function renderActivity(
   const dim = getFgAnsiCode("sep");
   const hot = getFgAnsiCode("accent");
   const reset = colorEnabled() ? ansi.reset : "";
-  // One glyph family, directional comet: light `─` track, fixed solid
-  // head, and a short box-drawing trail ONLY behind the head. Idle is a
-  // calm flat rail (no cycling glyphs — the old shade-block cloud read
-  // muddy across three unrelated glyph families).
-  const RAIL_WIDTH = 12;
+  // Adaptive rail width: ~20% of terminal, clamped [16, 40]. Wider
+  // terminals get a longer sweep so the motion reads at a glance.
+  const RAIL_WIDTH = Math.max(16, Math.min(40, Math.round(width * 0.2)));
   const track = ascii ? "-" : "─";
   const head = ascii ? "o" : "●";
   const railColor = runtime.active ? hot : dim;
+  const def = getMotion(runtime.motionId);
+  // The head glyph is the chosen motion's own frame — so ember-relay
+  // sweeps a ◇→◈→◆ sequence and hex-relay carries #-density, instead of
+  // every motion wearing the same generic comet. The trail reuses the
+  // motion's own past frames too, so each motion leaves its own wake.
+  // ASCII terminals fall back to the clean box-drawing comet — motion
+  // frames are a color-font feature.
+  const headGlyph = (tick: number, distance: number) => {
+    if (def && !ascii) return frameAt(def, Math.max(0, tick - distance), false);
+    return distance === 0 ? head : trailGlyph(distance, ascii);
+  };
+  const trailDepth = def?.generator?.trail ?? 4;
+  // Per-cell color gradient: hot head fading to dim through the palette.
+  // Distance 0 = accent, then model → path → sep so the wake cools off.
+  const cellColor = (distance: number): string => {
+    if (!colorEnabled()) return "";
+    if (distance <= 0) return hot;
+    if (distance <= 1) return getFgAnsiCode("model");
+    if (distance <= 2) return getFgAnsiCode("path");
+    return dim;
+  };
   let railBlock: string;
   if (!runtime.active) {
-    railBlock = track.repeat(RAIL_WIDTH);
+    // Idle: a frozen breathing wave of the ambient motion (wisp) frames.
+    // No animation consumer at idle, but a sine-sampled wave reads as
+    // "resting, not dead" — calmer than a full sweep, warmer than a flat track.
+    const ambient = getMotion(defaultMotionFor("idle"));
+    const ambientFrames = ambient ? framesOf(ambient) : null;
+    if (ambientFrames && colorEnabled()) {
+      const phase = Date.now() % 4000 / 4000;
+      const built: string[] = [];
+      for (let i = 0; i < RAIL_WIDTH; i++) {
+        const wave = Math.sin((i / RAIL_WIDTH) * Math.PI * 2 + phase * Math.PI * 2);
+        const frameIdx = Math.floor(((wave + 1) / 2) * ambientFrames.length) % ambientFrames.length;
+        const color = wave > 0.3 ? hot : dim;
+        built.push(`${color}${ambientFrames[frameIdx]}${reset}`);
+      }
+      railBlock = built.join("");
+    } else {
+      railBlock = track.repeat(RAIL_WIDTH);
+    }
   } else if (runtime.activity === "compacting") {
-    // Compact state: two heads travel inward and compress a heavy core —
-    // visually distinct from the sweep so compaction reads at a glance.
-    railBlock = renderCompactRail(runtime.tick, RAIL_WIDTH, ascii);
+    railBlock = renderCompactRail(runtime.tick, RAIL_WIDTH, ascii, headGlyph, cellColor);
   } else {
     const pos = sweepPosition(runtime.tick, RAIL_WIDTH, true);
     const built: string[] = [];
     for (let i = 0; i < RAIL_WIDTH; i++) {
-      if (i === pos) built.push(head);
-      else if (i < pos) built.push(trailGlyph(Math.min(pos - i, 4), ascii));
-      else built.push(track);
+      if (i === pos) built.push(`${cellColor(0)}${headGlyph(runtime.tick, 0)}${reset}`);
+      else if (i < pos) {
+        const distance = pos - i;
+        if (distance <= trailDepth) {
+          built.push(`${cellColor(distance)}${headGlyph(runtime.tick, distance)}${reset}`);
+        } else {
+          built.push(track);
+        }
+      } else {
+        built.push(track);
+      }
     }
     railBlock = built.join("");
   }
@@ -79,6 +123,8 @@ function renderCompactRail(
   tick: number,
   width: number,
   ascii: boolean,
+  headGlyph: (tick: number, i: number) => string,
+  cellColor: (distance: number) => string,
 ): string {
   const half = Math.floor(width / 2);
   // Heads oscillate from the edges toward center and back.
@@ -87,13 +133,21 @@ function renderCompactRail(
   const inward = phase < span ? phase : span * 2 - phase;
   const leftPos = inward;
   const rightPos = width - 1 - inward;
-  const head = ascii ? "*" : "●";
   const core = ascii ? "=" : "━";
   const track = ascii ? "-" : "─";
+  const reset = colorEnabled() ? ansi.reset : "";
+  // Color the core by distance from the nearest head — hottest at the
+  // heads, cooling toward center, so the compression reads thermally.
   let built = "";
   for (let i = 0; i < width; i++) {
-    if (i === leftPos || i === rightPos) built += head;
-    else built += i > leftPos && i < rightPos ? core : track;
+    if (i === leftPos || i === rightPos) {
+      built += `${cellColor(0)}${headGlyph(tick, 0)}${reset}`;
+    } else if (i > leftPos && i < rightPos) {
+      const nearestHead = Math.min(Math.abs(i - leftPos), Math.abs(i - rightPos));
+      built += `${cellColor(nearestHead)}${core}${reset}`;
+    } else {
+      built += track;
+    }
   }
   return built;
 }

package/src/render/v2-entry.ts

@@ -97,7 +97,7 @@ export function renderStatusLineV2(
 
   merged.leftSegments.forEach((id, i) => pushSegment(id, 10_000 - i));
 
-  const rail = renderActivity(runtime, options.signal, options.ascii);
+  const rail = renderActivity(runtime, options.signal, options.ascii, width);
   segments.push({ id: "signal", text: rail, priority: 5_000 });
   primary.push("signal");
 

package/src/signal/controller.ts

@@ -6,7 +6,7 @@
  */
 
 import {
-  allowedChannels,
+  channelsForMotion,
   defaultMotionFor,
   getMotion,
   type MotionEvent,
@@ -61,17 +61,17 @@ export function setSignalEvent(
   runtime.tick = 0;
   runtime.startedAt = Date.now();
   runtime.activity = options.activity ?? activityForEvent(event);
-  runtime.active = event !== "idle";
-
-  if (
-    event === "idle" ||
-    !allowedChannels(event, policy).includes("signal")
-  ) {
-    runtime.active = false;
-    return;
-  }
 
   const def = getMotion(runtime.motionId);
+  // The chosen motion's own channel declaration decides whether the rail
+  // runs — not the event table. `CHANNEL_MATRIX` still picks the default
+  // motion per event, but an explicit choice (preset signature or an
+  // `appearance.motion` override) is never vetoed by the matrix afterwards.
+  // The a11y policy (screen-reader, full→reduced, functional, toggles)
+  // filters both paths identically via `channelsForMotion`.
+  runtime.active =
+    def !== undefined && channelsForMotion(def, policy).includes("signal");
+  if (!runtime.active) return;
   // Wrap subscribe so a throw doesn't leave runtime.active=true with
   // release=null (a leaked state that would survive stopSignal).
   let release: (() => void) | null = null;

package/src/studio/component.ts

@@ -12,6 +12,8 @@ import {
   STUDIO_PANES,
 } from "./state.ts";
 import type { StudioKeyEvent, StudioState } from "./types.ts";
+import type { SkillEntry } from "../extension/skills/skill-registry.ts";
+import { buildListRows, filterListRows } from "./list.ts";
 
 const PANE_LABELS: Record<string, string> = {
   list: "Skills",
@@ -45,36 +47,55 @@ export function mapRawInput(data: string): StudioKeyEvent {
   return { key: "other" };
 }
 
-export function renderStudioFrame(theme: Theme, width: number, state: StudioState): string[] {
+export function renderStudioFrame(
+  theme: Theme,
+  width: number,
+  state: StudioState,
+  entries: readonly SkillEntry[] = [],
+): string[] {
   if (state.mode === "help") {
     const lines = [theme.fg("accent", HELP_LINES[0] ?? ""), ""];
-    for (const line of HELP_LINES.slice(2)) {
-      lines.push(theme.fg("muted", line));
-    }
+    for (const line of HELP_LINES.slice(2)) lines.push(theme.fg("muted", line));
     lines.push("", theme.fg("dim", "Press q, Esc, or Enter to close help"));
     return lines;
   }
 
   const focusMark = (pane: string): string =>
     state.focus === pane ? theme.fg("accent", `[${PANE_LABELS[pane] ?? pane}]`) : theme.fg("dim", ` ${PANE_LABELS[pane] ?? pane} `);
-
   const header = STUDIO_PANES.map((pane) => focusMark(pane)).join(" ");
   const filterLine = state.mode === "filter"
     ? theme.fg("accent", `filter: ${state.filterQuery}_`)
-    : state.filterQuery
-      ? theme.fg("muted", `filter: ${state.filterQuery}`)
-      : theme.fg("dim", "press / to filter, ? for help");
+    : state.filterQuery ? theme.fg("muted", `filter: ${state.filterQuery}`) : theme.fg("dim", "press / to filter, ? for help");
 
-  const lines: string[] = [
-    theme.fg("accent", "Skill Studio"),
-    header,
-    filterLine,
-    theme.fg("dim", "─".repeat(Math.max(1, Math.min(width - 1, 60)))),
-    theme.fg("muted", `selected: ${state.selectedIndex}`),
-    theme.fg("dim", "panes populate in upcoming units (browse, actions, advice)"),
-    theme.fg("dim", "─".repeat(Math.max(1, Math.min(width - 1, 60)))),
-    theme.fg("dim", "q/Esc exit · / filter · Tab focus · ? help"),
-  ];
+  const rows = filterListRows(buildListRows(entries), state.filterQuery);
+  const selectedIndex = rows.length ? Math.min(state.selectedIndex, rows.length - 1) : 0;
+  const selected = rows[selectedIndex];
+  const radius = 4;
+  const from = Math.max(0, selectedIndex - radius);
+  const visible = rows.slice(from, from + 9);
+  const lines: string[] = [theme.fg("accent", `Skill Studio · ${rows.length} skills`), header, filterLine, theme.fg("dim", "─".repeat(Math.max(1, Math.min(width - 1, 78))))];
+
+  if (!selected) {
+    lines.push(theme.fg("muted", "No skills match the current filter."));
+  } else {
+    for (let i = 0; i < visible.length; i += 1) {
+      const row = visible[i]!;
+      const absolute = from + i;
+      const mark = absolute === selectedIndex ? ">" : " ";
+      const route = row.routingCategory ? ` · ${row.routingCategory}/${row.routingFamily ?? "general"}` : "";
+      const drift = row.registryDrift ? " · drift" : "";
+      const text = `${mark} [${row.badge}] ${row.name}${route}${drift}`;
+      lines.push(absolute === selectedIndex ? theme.fg("accent", text) : theme.fg("muted", text));
+    }
+    lines.push(theme.fg("dim", "─".repeat(Math.max(1, Math.min(width - 1, 78)))));
+    lines.push(theme.fg("accent", selected.name));
+    lines.push(theme.fg("muted", selected.description || "No description"));
+    const ownership = [selected.role && `role=${selected.role}`, selected.routerParent && `parent=${selected.routerParent}`].filter(Boolean).join(" · ");
+    if (ownership) lines.push(theme.fg("dim", ownership));
+    lines.push(theme.fg("dim", selected.filePath));
+    if (selected.warning) lines.push(theme.fg("warning", `warning: ${selected.warning}`));
+  }
+  lines.push(theme.fg("dim", "q/Esc exit · / filter · j/k navigate · Tab focus · ? help"));
   return lines;
 }
 
@@ -82,6 +103,7 @@ export function createStudioComponent(
   theme: Theme,
   done: (value: string | null) => void,
   onStateChange?: (state: StudioState) => void,
+  entries: readonly SkillEntry[] = [],
 ) {
   let state = createStudioState();
 
@@ -89,7 +111,7 @@ export function createStudioComponent(
     focused: true,
     invalidate() {},
     render(width: number) {
-      return renderStudioFrame(theme, width, state);
+      return renderStudioFrame(theme, width, state, entries);
     },
     handleInput(data: string) {
       const next = handleStudioKey(state, mapRawInput(data));

package/src/studio/list.ts

@@ -13,6 +13,11 @@ export interface ListRow {
   category: SkillCategory;
   filePath: string;
   warning?: string;
+  routingCategory?: string;
+  routingFamily?: string;
+  role?: string | null;
+  routerParent?: string | null;
+  registryDrift?: boolean;
 }
 
 export function badgeForCategory(category: SkillCategory): string {
@@ -36,6 +41,11 @@ export function buildListRows(entries: readonly SkillEntry[]): ListRow[] {
     category: entry.category,
     filePath: entry.filePath,
     warning: entry.warning,
+    routingCategory: entry.routingCategory,
+    routingFamily: entry.routingFamily,
+    role: entry.role,
+    routerParent: entry.routerParent,
+    registryDrift: entry.registryDrift,
   }));
 }
 
@@ -43,6 +53,6 @@ export function filterListRows(rows: readonly ListRow[], query: string): ListRow
   const q = query.trim().toLowerCase();
   if (q.length === 0) return [...rows];
   return rows.filter(
-    (row) => row.name.toLowerCase().includes(q) || row.description.toLowerCase().includes(q),
+    (row) => row.name.toLowerCase().includes(q) || row.description.toLowerCase().includes(q) || row.routingCategory?.toLowerCase().includes(q) || row.routingFamily?.toLowerCase().includes(q),
   );
 }

package/src/studio/open.ts

@@ -6,13 +6,14 @@
 
 import type { RuntimeState } from "../extension/core/types.ts";
 import { createStudioComponent } from "./component.ts";
+import { loadSkillStudioCatalog, invalidateSkillCache } from "../extension/skills/skill-registry.ts";
 
 /**
  * Keep the operator command fail-closed until list/detail/actions/advice are
  * actually wired into the fullscreen component. The scaffold stays available
  * to tests and follow-up implementation without exposing a misleading command.
  */
-export const SKILL_STUDIO_PANES_READY = false;
+export const SKILL_STUDIO_PANES_READY = true;
 
 export async function openSkillStudio(
   rt: RuntimeState,
@@ -30,15 +31,12 @@ export async function openSkillStudio(
     ctx.ui.notify("Skill Studio is not available in RPC mode", "warning");
     return;
   }
-  if (!SKILL_STUDIO_PANES_READY) {
-    ctx.ui.notify("Skill Studio is not available until its panes are connected", "warning");
-    return;
-  }
-
   rt.currentCtx = ctx;
+  invalidateSkillCache();
+  const entries = loadSkillStudioCatalog(process.cwd());
 
   await ctx.ui.custom(
     (_tui: any, theme: any, _keybindings: any, done: (value: string | null) => void) =>
-      createStudioComponent(theme, done),
+      createStudioComponent(theme, done, undefined, entries),
   );
 }

package/src/theme/colors.ts

@@ -15,13 +15,9 @@ export const ansi: AnsiColors = {
 // ponytail: NO_COLOR (de-facto standard — present and non-empty) disables all
 // wishcraft color so the status bar stays plain text in no-color terminals
 // and color-blind pipelines. Computed lazily so test env changes take effect.
-let _colorEnabled: boolean | undefined;
 export function colorEnabled(): boolean {
-  if (_colorEnabled === undefined) {
-    const v = process.env.NO_COLOR;
-    _colorEnabled = !(v != null && v !== "");
-  }
-  return _colorEnabled;
+  const v = process.env.NO_COLOR;
+  return !(v != null && v !== "");
 }
 
 function hexToRgb(hex: string): [number, number, number] {

package/src/tools/patch.ts

@@ -1,179 +0,0 @@
-import { readFileSync, writeFileSync, copyFileSync, unlinkSync, existsSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { getAgentPath } from "../paths/agent-dirs.ts";
-
-export interface PatchHunk {
-  oldStart: number;
-  oldLines: number;
-  newStart: number;
-  newLines: number;
-  lines: string[];
-}
-
-export interface FilePatch {
-  targetFile: string;
-  hunks: PatchHunk[];
-}
-
-export interface PatchResult {
-  success: boolean;
-  targetFile: string;
-  appliedHunks: number;
-  totalHunks: number;
-  backupPath?: string;
-  error?: string;
-}
-
-const undoStack: { targetFile: string; backupPath: string; timestamp: number }[] = [];
-const MAX_UNDO_STACK = 10;
-
-/**
- * Parse a unified diff string into structured FilePatch objects.
- */
-export function parseUnifiedDiff(diffText: string): FilePatch[] {
-  const patches: FilePatch[] = [];
-  const lines = diffText.split(/\r?\n/);
-  let currentPatch: FilePatch | null = null;
-  let currentHunk: PatchHunk | null = null;
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-
-    if (line.startsWith("--- ")) {
-      continue;
-    }
-
-    if (line.startsWith("+++ ")) {
-      const rawPath = line.slice(4).trim();
-      const targetFile = rawPath.replace(/^[ab]\//, "");
-      currentPatch = { targetFile, hunks: [] };
-      patches.push(currentPatch);
-      continue;
-    }
-
-    const hunkHeaderMatch = line.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
-    if (hunkHeaderMatch && currentPatch) {
-      currentHunk = {
-        oldStart: parseInt(hunkHeaderMatch[1], 10),
-        oldLines: parseInt(hunkHeaderMatch[2] ?? "1", 10),
-        newStart: parseInt(hunkHeaderMatch[3], 10),
-        newLines: parseInt(hunkHeaderMatch[4] ?? "1", 10),
-        lines: [],
-      };
-      currentPatch.hunks.push(currentHunk);
-      continue;
-    }
-
-    if (currentHunk && (line.startsWith("+") || line.startsWith("-") || line.startsWith(" ") || line === "")) {
-      currentHunk.lines.push(line);
-    }
-  }
-
-  return patches;
-}
-
-/**
- * Apply a FilePatch to a file safely with an atomic backup.
- */
-export function applyFilePatch(patch: FilePatch, baseDir: string = process.cwd()): PatchResult {
-  const fullPath = join(baseDir, patch.targetFile);
-  
-  if (!existsSync(fullPath)) {
-    return {
-      success: false,
-      targetFile: patch.targetFile,
-      appliedHunks: 0,
-      totalHunks: patch.hunks.length,
-      error: `Target file not found: ${fullPath}`,
-    };
-  }
-
-  // 1. Create backup
-  const backupDir = getAgentPath("patch-backups");
-  if (!existsSync(backupDir)) {
-    mkdirSync(backupDir, { recursive: true });
-  }
-  const backupPath = join(backupDir, `${Date.now()}-${patch.targetFile.replace(/\//g, "_")}.bak`);
-  copyFileSync(fullPath, backupPath);
-
-  try {
-    const originalContent = readFileSync(fullPath, "utf-8");
-    let fileLines = originalContent.split(/\r?\n/);
-    let appliedHunks = 0;
-
-    for (const hunk of patch.hunks) {
-      const targetLineIdx = hunk.oldStart - 1;
-      const expectedOldLines = hunk.lines.filter((l) => !l.startsWith("+"));
-      
-      // Match context check
-      let matches = true;
-      for (let j = 0; j < expectedOldLines.length; j++) {
-        const expected = expectedOldLines[j].slice(1);
-        const actual = fileLines[targetLineIdx + j];
-        if (actual !== undefined && actual !== expected) {
-          matches = false;
-          break;
-        }
-      }
-
-      if (matches) {
-        const newHunkLines: string[] = [];
-        for (const line of hunk.lines) {
-          if (!line.startsWith("-")) {
-            newHunkLines.push(line.startsWith("+") ? line.slice(1) : line.slice(1));
-          }
-        }
-        
-        fileLines.splice(targetLineIdx, hunk.oldLines, ...newHunkLines);
-        appliedHunks++;
-      }
-    }
-
-    writeFileSync(fullPath, fileLines.join("\n"), "utf-8");
-
-    // Track undo stack
-    undoStack.push({ targetFile: fullPath, backupPath, timestamp: Date.now() });
-    if (undoStack.length > MAX_UNDO_STACK) {
-      const oldest = undoStack.shift();
-      if (oldest && existsSync(oldest.backupPath)) {
-        try { unlinkSync(oldest.backupPath); } catch {}
-      }
-    }
-
-    return {
-      success: appliedHunks > 0,
-      targetFile: patch.targetFile,
-      appliedHunks,
-      totalHunks: patch.hunks.length,
-      backupPath,
-    };
-  } catch (err) {
-    // Revert from backup
-    copyFileSync(backupPath, fullPath);
-    return {
-      success: false,
-      targetFile: patch.targetFile,
-      appliedHunks: 0,
-      totalHunks: patch.hunks.length,
-      error: err instanceof Error ? err.message : String(err),
-    };
-  }
-}
-
-/**
- * Revert the last applied patch.
- */
-export function undoLastPatch(): { success: boolean; targetFile?: string; error?: string } {
-  const last = undoStack.pop();
-  if (!last || !existsSync(last.backupPath)) {
-    return { success: false, error: "No undo backup available" };
-  }
-
-  try {
-    copyFileSync(last.backupPath, last.targetFile);
-    unlinkSync(last.backupPath);
-    return { success: true, targetFile: last.targetFile };
-  } catch (err) {
-    return { success: false, error: err instanceof Error ? err.message : String(err) };
-  }
-}

package/src/tools/ripgrep.ts

@@ -1,104 +0,0 @@
-import { spawnSync } from "node:child_process";
-
-export interface RipgrepMatch {
-  file: string;
-  lineNumber: number;
-  content: string;
-}
-
-export interface RipgrepOptions {
-  cwd?: string;
-  typeFilter?: string;
-  maxResults?: number;
-}
-
-export interface RipgrepResult {
-  matches: RipgrepMatch[];
-  totalCount: number;
-  engine: "ripgrep" | "grep-fallback";
-  error?: string;
-}
-
-/**
- * Execute a ripgrep (or fallback grep) search programmatically for subagent use.
- */
-export function searchRipgrep(pattern: string, options: RipgrepOptions = {}): RipgrepResult {
-  const cwd = options.cwd ?? process.cwd();
-  const maxResults = options.maxResults ?? 50;
-
-  // Try rg first
-  try {
-    const rgArgs = ["--json", "-m", String(maxResults), "-i"];
-    if (options.typeFilter) {
-      rgArgs.push("-t", options.typeFilter);
-    }
-    rgArgs.push(pattern, ".");
-
-    const proc = spawnSync("rg", rgArgs, { cwd, encoding: "utf-8", maxBuffer: 5 * 1024 * 1024 });
-
-    if (proc.status === 0 || proc.status === 1) {
-      const matches: RipgrepMatch[] = [];
-      const lines = (proc.stdout ?? "").split("\n");
-
-      for (const line of lines) {
-        if (!line.trim()) continue;
-        try {
-          const parsed = JSON.parse(line);
-          if (parsed.type === "match") {
-            const data = parsed.data;
-            matches.push({
-              file: data.path.text,
-              lineNumber: data.line_number,
-              content: data.lines.text.trimEnd(),
-            });
-          }
-        } catch {
-          // ignore non-json lines
-        }
-      }
-
-      return {
-        matches: matches.slice(0, maxResults),
-        totalCount: matches.length,
-        engine: "ripgrep",
-      };
-    }
-  } catch {
-    // Fallback to standard grep
-  }
-
-  // Fallback: standard grep
-  try {
-    const grepArgs = ["-rn", "-m", String(maxResults), "--exclude-dir=node_modules", "--exclude-dir=.git", pattern, "."];
-    const proc = spawnSync("grep", grepArgs, { cwd, encoding: "utf-8", maxBuffer: 5 * 1024 * 1024 });
-
-    const matches: RipgrepMatch[] = [];
-    const lines = (proc.stdout ?? "").split("\n");
-
-    for (const line of lines) {
-      if (!line.trim()) continue;
-      const parts = line.split(":");
-      if (parts.length >= 3) {
-        const file = parts[0];
-        const lineNumber = parseInt(parts[1], 10);
-        const content = parts.slice(2).join(":").trimEnd();
-        if (!isNaN(lineNumber)) {
-          matches.push({ file, lineNumber, content });
-        }
-      }
-    }
-
-    return {
-      matches: matches.slice(0, maxResults),
-      totalCount: matches.length,
-      engine: "grep-fallback",
-    };
-  } catch (err) {
-    return {
-      matches: [],
-      totalCount: 0,
-      engine: "grep-fallback",
-      error: err instanceof Error ? err.message : String(err),
-    };
-  }
-}