@mindfoldhq/trellis 0.6.0-beta.3 → 0.6.0-beta.5

package/dist/templates/markdown/spec/guides/cross-platform-thinking-guide.md.txt

@@ -26,37 +26,68 @@
 | `python3` command | ✅ Always available | ⚠️ May need `python` |
 | `python` command | ⚠️ May be Python 2 | ✅ Usually Python 3 |
 
-**Rule 1**: Always use explicit `python3` in documentation, help text, and error messages.
+**Rule 1**: For user-facing docs, help text, and error messages, either:
+
+- state the platform rule explicitly (`python` on Windows, `python3` elsewhere), or
+- render the command through the same platform-aware helper / placeholder the code uses.
 
 ```python
 # BAD - Assumes shebang works
 print("Usage: ./script.py <args>")
 print("Run: script.py <args>")
 
-# GOOD - Explicit interpreter
-print("Usage: python3 script.py <args>")
-print("Run: python3 ./script.py <args>")
+# GOOD - Platform-aware wording
+print("Usage: python on Windows, python3 elsewhere")
+print("Run: {{PYTHON_CMD}} ./.trellis/scripts/task.py <args>")
 ```
 
-**Rule 2**: When calling Python from TypeScript/Node.js, detect the available command:
+**Rule 2**: When generating config files at init time, use placeholder + platform detection:
 
 ```typescript
+// In template file (settings.json):
+{ "command": "{{PYTHON_CMD}} .claude/hooks/script.py" }
+
+// In configurator:
 function getPythonCommand(): string {
+  return process.platform === "win32" ? "python" : "python3";
+}
+
+function replacePlaceholders(content: string): string {
+  return content.replace(/\{\{PYTHON_CMD\}\}/g, getPythonCommand());
+}
+```
+
+**Rule 3**: When calling Python at runtime from JavaScript, detect platform dynamically:
+
+```javascript
+import { platform } from "os"
+
+const PYTHON_CMD = platform() === "win32" ? "python" : "python3"
+execSync(`${PYTHON_CMD} "${scriptPath}"`, { ... })
+```
+
+**Rule 4**: If you need to verify Python is actually installed (not just choose
+the command), probe the same platform-selected alias you will later render or
+execute:
+
+```typescript
+function getPythonCommand(platform = process.platform): string {
+  return platform === "win32" ? "python" : "python3";
+}
+
+function warnIfPythonTooOld(): void {
+  const cmd = getPythonCommand();
   try {
-    execSync("python3 --version", { stdio: "pipe" });
-    return "python3";
+    execSync(`${cmd} --version`, { stdio: "pipe" });
   } catch {
-    try {
-      execSync("python --version", { stdio: "pipe" });
-      return "python";
-    } catch {
-      return "python3"; // Default, will fail with clear error
-    }
+    // Missing Python is a separate error path; don't silently swap aliases.
   }
 }
 ```
 
-**Rule 3**: When calling Python from Python, use `sys.executable`:
+**Rule 5**: Don't assume the Python version the AI CLI uses matches your shell's `python3`. The user's terminal may resolve `python3` → homebrew 3.11, but AI CLI hosts (including enterprise-forked Claude Code / Cursor distributions) spawn hook subprocesses with a minimal PATH that resolves `python3` → `/usr/bin/python3` → macOS system 3.9. Distributed templates must either target the lowest plausible version or use `from __future__ import annotations` for PEP 604 syntax. See `cli/backend/script-conventions.md` → **CRITICAL: PEP 604 Annotations Require `from __future__ import annotations`** for the hard rule and audit check.
+
+**Rule 6**: When calling Python from Python, use `sys.executable`:
 
 ```python
 import sys
@@ -69,30 +100,6 @@ subprocess.run(["python3", "other_script.py"])
 subprocess.run([sys.executable, "other_script.py"])
 ```
 
-**Rule 4**: Don't assume the Python version your AI CLI uses matches your shell's `python3`. Your terminal may resolve `python3` → 3.11 (via homebrew/pyenv), but AI CLI hosts often spawn hook subprocesses with a minimal PATH that resolves `python3` → the system Python (3.9 on macOS). Any `.py` file run as an AI-CLI hook must be written for the lowest plausible Python version.
-
-Concrete failure: PEP 604 union syntax (`str | None`) requires Python 3.10+. If your hook file uses it, start with `from __future__ import annotations` so annotations become lazy strings and work on Python 3.7+:
-
-```python
-#!/usr/bin/env python3
-"""My hook."""
-from __future__ import annotations     # REQUIRED for PEP 604 annotations
-
-def handler(x: str | None) -> dict | None:   # OK — lazy annotation
-    ...
-```
-
-```python
-# BAD — crashes on Python < 3.10:
-#   TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'
-def handler(x: str | None) -> dict | None:
-    ...
-```
-
-Note: `from __future__ import annotations` only covers **annotations**. Runtime expressions like `isinstance(x, int | str)` still require Python 3.10+. Avoid them in hook scripts.
-
-Applies to anything the AI CLI executes as a hook: `match/case` statements (3.10+), `tomllib` (3.11+), `ExceptionGroup` / `except*` (3.11+) — all crash on older Python regardless of `__future__`.
-
 ### 2. Path Handling
 
 | Assumption | macOS/Linux | Windows |
@@ -101,7 +108,7 @@ Applies to anything the AI CLI executes as a hook: `match/case` statements (3.10
 | `\` separator | ❌ Escape char | ✅ Native |
 | `pathlib.Path` | ✅ Works | ✅ Works |
 
-**Rule**: Use `pathlib.Path` for all path operations.
+**Rule (Python)**: Use `pathlib.Path` for all path operations.
 
 ```python
 # BAD - String concatenation
@@ -112,6 +119,51 @@ from pathlib import Path
 path = Path(base) / filename
 ```
 
+#### Logical key vs filesystem path (TypeScript)
+
+A path string has two distinct roles. **Treat them differently.**
+
+| Role | OS-native (`\` on Windows) | Always POSIX (`/`) |
+|------|---------------------------|--------------------|
+| `fs.readFileSync(p)` / `path.join(cwd, x)` for fs call | ✅ Required | ❌ May fail on Windows |
+| `Map<relPath, content>` key, JSON field, hash dictionary key, anything persisted across OS | ❌ Cross-OS mismatch | ✅ Required |
+
+**Rule**: Anywhere a path string crosses OS or persists (Map keys consumed by another OS, JSON fields, hash dictionary keys), normalize to POSIX. Anywhere it goes straight to `fs.*`, leave OS-native.
+
+**Single source of truth**: `packages/cli/src/utils/posix.ts` exports `toPosix(p)`. Don't sprinkle `replaceAll('\\', '/')` at every `path.join` site — apply `toPosix` **once at the boundary**: collector exit (Map key entering hash dictionary) or write-time (`saveHashes` before `JSON.stringify`).
+
+```typescript
+// BAD - logical key carries OS-native separator
+function collectTemplates(): Map<string, string> {
+  const files = new Map<string, string>();
+  for (const entry of walk(dir)) {
+    files.set(path.join(".opencode", entry), readFile(entry));  // \ on Windows
+  }
+  return files;
+}
+
+// GOOD - normalize at the boundary
+import { toPosix } from "../utils/posix.js";
+
+function collectTemplates(): Map<string, string> {
+  const files = new Map<string, string>();
+  for (const entry of walk(dir)) {
+    files.set(toPosix(path.join(".opencode", entry)), readFile(entry));
+  }
+  return files;
+}
+
+// ALSO ACCEPTABLE - write-side defense (for storage helpers like saveHashes)
+function saveHashes(cwd: string, hashes: Record<string, string>): void {
+  const normalized = Object.fromEntries(
+    Object.entries(hashes).map(([k, v]) => [toPosix(k), v])
+  );
+  fs.writeFileSync(getHashesPath(cwd), JSON.stringify(normalized, null, 2));
+}
+```
+
+**Common offender**: `path.relative(cwd, fullPath)` produces `\` on Windows. If you then use that string as a hash dictionary lookup key (`hashes[relPath]`), `toPosix` it first, or the lookup misses on Windows.
+
 ### 3. Line Endings
 
 | Format | macOS/Linux | Windows | Git |
@@ -119,7 +171,7 @@ path = Path(base) / filename
 | `\n` (LF) | ✅ Native | ⚠️ Some tools | ✅ Normalized |
 | `\r\n` (CRLF) | ⚠️ Extra char | ✅ Native | Converted |
 
-**Rule**: Use `.gitattributes` to enforce consistent line endings.
+**Rule 1**: Use `.gitattributes` to enforce consistent line endings.
 
 ```gitattributes
 * text=auto eol=lf
@@ -127,6 +179,23 @@ path = Path(base) / filename
 *.py text eol=lf
 ```
 
+**Rule 2**: When hashing or comparing **content** across platforms, normalize line endings before computing the hash. `.gitattributes` only governs git checkout — files written by users, scripts, or `core.autocrlf=true` may still arrive as CRLF, and `sha256(LF)` ≠ `sha256(CRLF)` for otherwise-identical content.
+
+```typescript
+// BAD - Windows users with autocrlf=true get a different hash
+export function computeHash(content: string): string {
+  return createHash("sha256").update(content, "utf-8").digest("hex");
+}
+
+// GOOD - normalize before hashing so logical content hashes identically
+export function computeHash(content: string): string {
+  const normalized = content.replace(/\r\n/g, "\n");
+  return createHash("sha256").update(normalized, "utf-8").digest("hex");
+}
+```
+
+Apply this rule wherever the hash crosses OS boundaries (template hash dictionary, content fingerprints stored in JSON, integrity checks against a remote registry).
+
 ### 4. Environment Variables
 
 | Variable | macOS/Linux | Windows |
@@ -135,7 +204,7 @@ path = Path(base) / filename
 | `PATH` separator | `:` | `;` |
 | Case sensitivity | ✅ Case-sensitive | ❌ Case-insensitive |
 
-**Rule**: Use `pathlib.Path.home()` instead of environment variables.
+**Rule 1**: Use `pathlib.Path.home()` instead of environment variables.
 
 ```python
 # BAD
@@ -145,6 +214,25 @@ home = os.environ.get("HOME")
 home = Path.home()
 ```
 
+**Rule 2**: When injecting environment variables into shell commands, generate
+the prefix for the actual host shell. Do not assume `export` works everywhere.
+AI tool "Bash" surfaces on Windows may execute through PowerShell.
+
+```javascript
+// BAD - breaks when the host shell is PowerShell
+command = `export TRELLIS_CONTEXT_ID=${shellQuote(contextKey)}; ${command}`;
+
+// GOOD - shell-aware command prefix
+const prefix = process.platform === "win32"
+  ? `$env:TRELLIS_CONTEXT_ID = ${powershellQuote(contextKey)}; `
+  : `export TRELLIS_CONTEXT_ID=${shellQuote(contextKey)}; `;
+command = `${prefix}${command}`;
+```
+
+Also make duplicate-injection detection shell-aware. A guard that only matches
+`export VAR=` will miss PowerShell's `$env:VAR = ...` form and can wrap an
+already-correct command a second time.
+
 ### 5. Command Availability
 
 | Command | macOS/Linux | Windows |
@@ -173,6 +261,25 @@ def tail_follow(file_path: Path) -> None:
                 time.sleep(0.1)
 ```
 
+### Optional Advisory Checks in Agent Sandboxes
+
+AI CLI subprocesses may run with outbound network disabled even when the user's
+normal terminal has network access. Prefer local CLI probes over optional
+network probes when the local CLI already exposes the needed information.
+
+**Rule 1**: Do not let a failed optional advisory check consume a once-per-session
+marker. Write the marker only after the script resolves a usable value and can
+make the intended decision. Otherwise a transient sandbox/network failure hides
+the hint for the rest of the session.
+
+**Rule 2**: If a local command can provide the needed value, try it with a short
+timeout and captured output. For example, `trellis --version` already runs the
+CLI's version comparison logic and can support an actionable update prompt
+without duplicating npm registry parsing.
+
+**Rule 3**: Keep advisory checks silent on failure. The user-facing context output
+must not fail or become noisy because an advisory check could not complete.
+
 ### 6. File Encoding
 
 | Default Encoding | macOS/Linux | Windows |
@@ -183,6 +290,9 @@ def tail_follow(file_path: Path) -> None:
 
 **Rule**: Always explicitly specify `encoding="utf-8"` and use `errors="replace"`.
 
+> **Checklist**: When writing scripts that print non-ASCII, did you configure stdout encoding?
+> See `backend/script-conventions.md` for the specific pattern.
+
 ```python
 # BAD - Relies on system default
 with open(file, "r") as f:
@@ -223,6 +333,12 @@ result = subprocess.run(
 
 When making platform-related changes, check **all these locations**:
 
+### Commands / Skills Sync
+- [ ] New command/skill added to ALL platforms (claude, cursor, iflow, codex, and any new platform)
+- [ ] Each platform's test file updated with new entry in `EXPECTED_COMMAND_NAMES` / `EXPECTED_SKILL_NAMES`
+- [ ] Platform-integration spec's required command table updated if adding a new required command
+- [ ] Command format matches platform convention (see `platform-integration.md` → Command Format by Platform)
+
 ### Documentation & Help Text
 - [ ] Docstrings at top of Python files
 - [ ] `--help` output / argparse descriptions
@@ -239,7 +355,7 @@ When making platform-related changes, check **all these locations**:
 ```bash
 # Find all places that might need updating
 grep -r "python [a-z]" --include="*.py" --include="*.md"
-grep -r "\./" --include="*.py" --include="*.md" | grep -v python3
+grep -r "{{PYTHON_CMD}}\\|python3\\|python " --include="*.py" --include="*.md"
 ```
 
 ---
@@ -248,10 +364,15 @@ grep -r "\./" --include="*.py" --include="*.md" | grep -v python3
 
 Before committing cross-platform code:
 
-- [ ] All Python invocations use `python3` explicitly (docs) or `sys.executable` (code)
+- [ ] User-facing Python invocations are platform-aware (`python` on Windows, `python3` elsewhere) or use `{{PYTHON_CMD}}`
+- [ ] Python subprocesses from Python use `sys.executable`
 - [ ] All paths use `pathlib.Path`
 - [ ] No hardcoded path separators (`/` or `\`)
+- [ ] Path strings used as logical/persisted keys (Map keys, JSON fields, hash dictionary keys) are normalized via `toPosix()`; `fs.*` calls keep OS-native paths
+- [ ] Content hashes computed across OSes normalize line endings (`\r\n` → `\n`) before hashing
+- [ ] Cross-OS JSON with potential legacy pollution carries a `__version` sentinel and the loader discards unknown/legacy versions
 - [ ] No platform-specific commands without fallbacks (e.g., `tail -f`)
+- [ ] Optional advisory checks do not burn once-per-session markers on failure
 - [ ] All file I/O specifies `encoding="utf-8"` and `errors="replace"`
 - [ ] All subprocess calls specify `encoding="utf-8"` and `errors="replace"`
 - [ ] Git commands use `-c i18n.logOutputEncoding=UTF-8`
@@ -283,6 +404,101 @@ output = {
 
 ---
 
+## Cross-Platform Persisted JSON: Schema Migration Sentinel
+
+When a JSON file may be read/written across OSes (committed to git, synced via cloud, copied between machines) **and an older format may already exist on user disks with cross-platform pollution** (Windows-style keys, CRLF-derived hashes, locale-encoded strings), add a `__version` sentinel and let the loader discard old formats so the writer regenerates clean data.
+
+**Why not migrate-in-place?** Path-key migration (`\\` → `/`) plus hash-input migration (CRLF → LF re-hash) plus encoding fixes are correlated — trying to translate the old payload risks producing wrong values. Discarding and regenerating is **safe**: the data is recomputable from disk, and `loadX` returning `{}` triggers the existing init/update path to rebuild canonical entries.
+
+```typescript
+const SCHEMA_VERSION = 2;
+type StoredV2 = { __version: number; hashes: Record<string, string> };
+
+export function loadHashes(cwd: string): Record<string, string> {
+  const file = getHashesPath(cwd);
+  if (!fs.existsSync(file)) return {};
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf-8")) as unknown;
+
+    // Reject legacy flat format (no __version) and unknown versions.
+    // The next saveHashes / initializeHashes will write a fresh v2 file.
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      (parsed as StoredV2).__version !== SCHEMA_VERSION ||
+      typeof (parsed as StoredV2).hashes !== "object"
+    ) {
+      return {};
+    }
+    return (parsed as StoredV2).hashes;
+  } catch {
+    return {};
+  }
+}
+
+export function saveHashes(cwd: string, hashes: Record<string, string>): void {
+  const payload: StoredV2 = { __version: SCHEMA_VERSION, hashes };
+  fs.writeFileSync(getHashesPath(cwd), JSON.stringify(payload, null, 2));
+}
+```
+
+**When to apply**:
+- Hash dictionaries / content fingerprints (e.g., `.template-hashes.json`)
+- Cache files where stale entries are recomputable from authoritative source
+- Any cross-OS persisted file where format change correlates with cross-platform fixes
+
+**When NOT to apply** — if losing the data hurts the user (task state, drafts, settings the user typed). Use real migration there. Sentinel + discard is only safe when data is recomputable.
+
+**Reference**: `packages/cli/src/utils/template-hash.ts` v2 envelope.
+
+---
+
+## JSON/External Data Defensive Checks
+
+When parsing JSON or external data, TypeScript types are **compile-time only**. Runtime data may not match.
+
+**Rule**: Always add defensive checks for required fields before using them.
+
+```typescript
+// BAD - Trusts TypeScript type definition
+interface MigrationItem {
+  from: string;  // TypeScript says required
+  to?: string;
+}
+
+function process(item: MigrationItem) {
+  const path = item.from;  // Runtime: could be undefined!
+}
+
+// GOOD - Defensive check before use
+function process(item: MigrationItem) {
+  if (!item.from) return;  // Skip invalid data
+  const path = item.from;  // Now guaranteed
+}
+```
+
+**When to apply**:
+- Parsing JSON files (manifests, configs)
+- API responses
+- User input
+- Any data from external sources
+
+**Pattern**: Check existence → then use
+
+```typescript
+// Filter pattern - skip invalid items
+const validItems = items.filter(item => item.from && item.to);
+
+// Early return pattern - bail on invalid
+if (!data.requiredField) {
+  console.warn("Missing required field");
+  return defaultValue;
+}
+```
+
+---
+
 ## Common Mistakes
 
 ### 1. "It works on my Mac"
@@ -318,6 +534,9 @@ python3 script.py  # Works!
 # User's Windows (Python from python.org)
 python3 script.py  # 'python3' is not recognized
 python script.py   # Works!
+
+# Trellis docs/config should say the rule, not guess one alias everywhere
+{{PYTHON_CMD}} script.py
 ```
 
 ### 5. "UTF-8 is the default everywhere"
@@ -328,6 +547,9 @@ subprocess.run(cmd, capture_output=True, text=True)  # Works!
 
 # User's Windows (GBK/CP1252 default)
 subprocess.run(cmd, capture_output=True, text=True)  # Garbled Chinese/Unicode
+```
+
+> **Note**: stdout encoding is also affected. See `backend/script-conventions.md` for the fix.
 
 ---
 
@@ -341,3 +563,27 @@ subprocess.run(cmd, capture_output=True, text=True)  # Garbled Chinese/Unicode
 ---
 
 **Core Principle**: If it's not explicit, it's an assumption. And assumptions break.
+
+---
+
+## Release Checklist: Versioned Files
+
+When releasing a new version, ensure **all versioned files** are created/updated:
+
+- [ ] `src/migrations/manifests/{version}.json` - Migration manifest exists
+- [ ] Manifest has correct version, description, changelog
+- [ ] `pnpm build` copies manifests to `dist/`
+- [ ] Test upgrade path from older versions (not just adjacent)
+
+**Why this matters**: Missing manifests cause "path undefined" errors when users upgrade from older versions.
+
+```bash
+# Verify all expected manifests exist
+ls src/migrations/manifests/
+
+# Test upgrade path
+node -e "
+const { getMigrationsForVersion } = require('./dist/migrations/index.js');
+console.log('From 0.2.12:', getMigrationsForVersion('0.2.12', 'CURRENT').length);
+"
+```

package/dist/templates/pi/extensions/trellis/index.ts.txt

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { createHash, randomBytes } from "node:crypto";
 import { delimiter, dirname, join, resolve } from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 
 type JsonObject = Record<string, unknown>;
 type TextContent = { type: "text"; text: string };
@@ -632,6 +632,166 @@ function buildTrellisContext(
   ].join("\n");
 }
 
+// ---------------------------------------------------------------------------
+// Workflow-state breadcrumb (TypeScript port of the shared workflow-state
+// hook used by class-1 platforms).
+//
+// Pi is extension-backed and MUST NOT receive Python hook scripts under .pi/.
+// We therefore parse `.trellis/workflow.md` `[workflow-state:STATUS]...
+// [/workflow-state:STATUS]` blocks directly in TypeScript and emit the
+// per-turn `<workflow-state>` breadcrumb in `before_agent_start` and `input`.
+// Tag regex mirrors the shared parser so the breadcrumb body stays
+// byte-identical with hook-driven platforms.
+// ---------------------------------------------------------------------------
+
+const WORKFLOW_STATE_TAG_RE =
+  /\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n([\s\S]*?)\n\s*\[\/workflow-state:\1\]/g;
+
+function loadWorkflowBreadcrumbs(projectRoot: string): Record<string, string> {
+  const workflow = readText(join(projectRoot, ".trellis", "workflow.md"));
+  if (!workflow) return {};
+  const result: Record<string, string> = {};
+  for (const match of workflow.matchAll(WORKFLOW_STATE_TAG_RE)) {
+    const status = match[1] ?? "";
+    const body = (match[2] ?? "").trim();
+    if (status && body) result[status] = body;
+  }
+  return result;
+}
+
+function readActiveTaskStatus(
+  projectRoot: string,
+  taskDir: string,
+): { taskId: string; status: string } | null {
+  try {
+    const data = JSON.parse(
+      readText(join(taskDir, "task.json")),
+    ) as JsonObject;
+    const status = stringValue(data.status);
+    if (!status) return null;
+    const id = stringValue(data.id) ?? taskDir.split(/[\\/]/).pop() ?? "";
+    return { taskId: id, status };
+  } catch {
+    return null;
+  }
+}
+
+function buildWorkflowStateBreadcrumb(
+  projectRoot: string,
+  contextKey: string | null,
+): string {
+  const templates = loadWorkflowBreadcrumbs(projectRoot);
+  const taskDir = readCurrentTask(
+    projectRoot,
+    undefined,
+    undefined,
+    contextKey,
+  );
+  let header: string;
+  let lookupKey: string;
+  if (!taskDir) {
+    header = "Status: no_task\nSource: session";
+    lookupKey = "no_task";
+  } else {
+    const info = readActiveTaskStatus(projectRoot, taskDir);
+    if (!info) {
+      header = "Status: no_task\nSource: session";
+      lookupKey = "no_task";
+    } else {
+      header = `Task: ${info.taskId} (${info.status})\nSource: session`;
+      lookupKey = info.status;
+    }
+  }
+  const body = templates[lookupKey] ?? "Refer to workflow.md for current step.";
+  return `<workflow-state>\n${header}\n${body}\n</workflow-state>`;
+}
+
+// ---------------------------------------------------------------------------
+// Session overview (developer / git branch / active tasks)
+//
+// Spawns `python3 .trellis/scripts/get_context.py` (the same script other
+// platform session-start hooks invoke) to keep developer/git/active-task
+// summary byte-identical with class-1 platforms. Failure is non-fatal — we
+// emit an empty overview rather than block the conversation.
+// ---------------------------------------------------------------------------
+
+const SESSION_OVERVIEW_TIMEOUT_MS = 5000;
+
+function pythonExecutable(): string {
+  const override = stringValue(process.env.TRELLIS_PYTHON);
+  if (override) return override;
+  return process.platform === "win32" ? "python" : "python3";
+}
+
+function buildSessionOverview(
+  projectRoot: string,
+  contextKey: string | null,
+): string {
+  const script = join(projectRoot, ".trellis", "scripts", "get_context.py");
+  if (!isExistingFile(script)) return "";
+  try {
+    const result = spawnSync(pythonExecutable(), [script], {
+      cwd: projectRoot,
+      env: contextKey
+        ? { ...process.env, TRELLIS_CONTEXT_ID: contextKey }
+        : process.env,
+      encoding: "utf-8",
+      timeout: SESSION_OVERVIEW_TIMEOUT_MS,
+      windowsHide: true,
+    });
+    if (result.status !== 0) return "";
+    const stdout = (result.stdout ?? "").trim();
+    if (!stdout) return "";
+    return `<session-overview>\n${stdout}\n</session-overview>`;
+  } catch {
+    return "";
+  }
+}
+
+// Per-turn cache so input + before_agent_start in the same turn don't double-spawn.
+class TurnContextCache {
+  private key: string | null = null;
+  private timestamp = 0;
+  private workflowState = "";
+  private sessionOverview = "";
+  // Refresh window: per-turn injections that fire close together share a
+  // single python3 spawn; anything older than this re-runs the resolver.
+  private static readonly TTL_MS = 1500;
+
+  get(
+    projectRoot: string,
+    contextKey: string | null,
+  ): { workflowState: string; sessionOverview: string } {
+    const now = Date.now();
+    if (this.key === contextKey && now - this.timestamp < TurnContextCache.TTL_MS) {
+      return {
+        workflowState: this.workflowState,
+        sessionOverview: this.sessionOverview,
+      };
+    }
+    this.workflowState = buildWorkflowStateBreadcrumb(projectRoot, contextKey);
+    this.sessionOverview = buildSessionOverview(projectRoot, contextKey);
+    this.key = contextKey;
+    this.timestamp = now;
+    return {
+      workflowState: this.workflowState,
+      sessionOverview: this.sessionOverview,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Sub-agent dispatch protocol snippet (registered with the `subagent` tool).
+// Mirrors the [workflow-state:in_progress] dispatch protocol text in
+// trellis/workflow.md so the AI sees the same `Active task: <path>` rule
+// whether it reads workflow.md, the per-turn breadcrumb, or the tool prompt.
+// ---------------------------------------------------------------------------
+
+const SUBAGENT_DISPATCH_PROTOCOL = `Sub-agent dispatch protocol (Trellis): your dispatch prompt MUST start with one line "Active task: <task path from \`task.py current\`>" before any other instructions. No exceptions. On class-2 platforms (codex / copilot / gemini / qoder) the sub-agent depends on this line because there is no hook to inject task context. On class-1 platforms (claude / cursor / opencode / kiro / codebuddy / droid) and on Pi, the line is the canonical fallback when hook/extension injection misses. trellis-research uses the line to know which {task_dir}/research/ to write into.
+
+Wrong: prompt: "implement the new feature"
+Correct: prompt: "Active task: .trellis/tasks/05-09-pi-workflow-state-injection\\n\\nImplement the new feature ..."`;
+
 function normalizeAgentName(agent: string): string {
   return agent.startsWith("trellis-") ? agent : `trellis-${agent}`;
 }
@@ -886,6 +1046,15 @@ export default function trellisExtension(pi: {
   const projectRoot = findProjectRoot(pi.cwd ?? process.cwd());
   const processContextKey = createProcessContextKey(projectRoot);
   let currentContextKey: string | null = null;
+  const turnContextCache = new TurnContextCache();
+
+  const buildPerTurnInjection = (contextKey: string | null): string => {
+    const { workflowState, sessionOverview } = turnContextCache.get(
+      projectRoot,
+      contextKey,
+    );
+    return [workflowState, sessionOverview].filter(Boolean).join("\n\n");
+  };
 
   const getContextKey = (input?: unknown, ctx?: PiExtensionContext): string => {
     const resolvedContextKey = resolveContextKey(
@@ -904,6 +1073,8 @@ export default function trellisExtension(pi: {
     name: "subagent",
     label: "Subagent",
     description: "Run a Trellis project sub-agent with active task context.",
+    promptSnippet: SUBAGENT_DISPATCH_PROTOCOL,
+    promptGuidelines: SUBAGENT_DISPATCH_PROTOCOL,
     parameters: {
       type: "object",
       properties: {
@@ -976,8 +1147,9 @@ export default function trellisExtension(pi: {
       ctx,
       contextKey,
     );
+    const perTurn = buildPerTurnInjection(contextKey);
     return {
-      systemPrompt: [current, context].filter(Boolean).join("\n\n"),
+      systemPrompt: [current, context, perTurn].filter(Boolean).join("\n\n"),
     };
   });
   pi.on?.("context", (event, ctx) => {
@@ -986,8 +1158,11 @@ export default function trellisExtension(pi: {
     return Array.isArray(messages) ? { messages } : undefined;
   });
   pi.on?.("input", (event, ctx) => {
-    getContextKey(event, ctx);
-    return { action: "continue" };
+    const contextKey = getContextKey(event, ctx);
+    const additionalContext = buildPerTurnInjection(contextKey);
+    return additionalContext
+      ? { action: "continue", additionalContext, systemPrompt: additionalContext }
+      : { action: "continue" };
   });
   pi.on?.("tool_call", (event, ctx) => {
     const contextKey = getContextKey(event, ctx);