@akagilnc/pi-workflow-roles 0.1.3525 → 0.1.3529

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.3525",
+  "version": "0.1.3529",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/resources/engine-dispatch.md

@@ -25,6 +25,12 @@ themselves. Stuffing large bodies into argv/prompt is the verified cause of
 
 ## Process shape
 
+- The returned labor body is the final answer text only. Never return an
+  event stream, verbose log, or NDJSON deltas: the body is fed back into the
+  seat's context, and one 12-minute Opus labor returned as `stream-json` was
+  957k chars and killed the seat (712k-token request, #675, 2026-09-06).
+  Progress observability is the runner's job (process watch), not the body's.
+
 - Once an engine is selected, start exactly one subprocess per labor
   invocation by calling that engine's local CLI, with argv assembled from the
   engine note plus these dispatch rules; return the stdout labor content to

package/resources/engines/codex.md

@@ -32,14 +32,9 @@ codex exec --skip-git-repo-check --ephemeral -C "$PROJECT_ROOT" "YOUR_LABOR_PROM
 
 Default (non-`--json`) mode prints the session banner and progress on stderr
 (measured on this host). Collect the labor body from stdout so that stderr log
-noise is not mixed into the returned body. Use `--json` only when the seat itself
-needs machine-readable event rows (those rows land on stdout as JSONL; measured
-event types include `thread.started`, `turn.started`, `item.completed`, `error`,
-`turn.failed`):
-
-```bash
-codex exec --skip-git-repo-check --ephemeral --json "YOUR_LABOR_PROMPT"
-```
+noise is not mixed into the returned body. Never use `--json` for labor: its
+JSONL event rows go back into the seat's context as noise (see `opus.md` for the
+measured ratio).
 
 Prefer `codex exec --help` on the host over any remembered flag set. Do not wrap
 this engine behind `ak-role` flags.

package/resources/engines/cursor.md

@@ -30,7 +30,8 @@ cursor-agent -p -f --output-format text --model <MODEL_ID> "YOUR_LABOR_PROMPT"
   bracket override form (`'claude-opus-4-8[context=1m,effort=high]'` — see
   `cursor-agent --help`).
 - Owner pool directive 2026-08-28: default labor model = `cursor-grok-4.6-low`.
-- Stream JSON events for long labor: `--output-format stream-json`.
+- Always `--output-format text`; never `stream-json` (the event stream goes back
+  into the seat's context as noise — see `opus.md`).
 
 Prefer `cursor-agent --help` on the host over any remembered flag set. Do not
 wrap this engine behind `ak-role` flags.

package/resources/engines/grok-4.6.md

@@ -27,14 +27,11 @@ grok --prompt-file /path/to/labor-prompt.md -m grok-4.6 --always-approve --outpu
 - Official docs list `-p/--single` as the canonical headless prompt input;
   `--prompt-file` exists in the installed CLI (`--help`) and is smoke-verified
   on this host — prefer it for long prompts, fall back to `-p` if absent.
-- `--output-format plain` keeps stdout clean for capture — but it stays
-  silent until the run finishes. **For labor longer than ~2 minutes use
-  `--output-format streaming-json` instead**: it emits NDJSON events
-  (thought/text deltas) continuously from the first second, so long runs stay
-  observable instead of appearing hung. Reconstruct the final answer by
-  concatenating each NDJSON object's `data` where `type == "text"`, in stream
-  order; `type == "end"` (stopReason end_turn) marks completion. Do not treat
-  `thought` events as the answer (live-verified stream shape 2026-08-21).
+- `--output-format plain` keeps stdout clean for capture and is the only
+  format to use for labor. Do not use `streaming-json`: its NDJSON deltas go
+  back into the seat's context as noise (see `opus.md` for the measured ratio);
+  progress observability belongs to the runner's process watch, not to the
+  returned body.
 - **Always pass `--reasoning-effort <low|medium|high>`** matching the effort
   tier ordered in the labor mandate (verified live 2026-08-21: flag exists,
   alias `--effort`; a low-tier run completed correctly). If the mandate names

package/resources/engines/kimi.md

@@ -29,16 +29,10 @@ known Kimi model id (example alias shape measured: `kimi-code/k3-256k`):
 kimi -m <model-alias> -p "YOUR_LABOR_PROMPT"
 ```
 
-Use `--output-format stream-json` (choices measured on this host: `text`,
-`stream-json`; default is `text`) when long labor needs progressive observability
-while the engine works. Take the labor body from
-`{"role":"assistant","content":...}` rows, not from `role:meta` rows:
-
-```bash
-kimi -p "YOUR_LABOR_PROMPT" --output-format stream-json
-```
-
-Text / default mode when stream events are not needed. Measured on this host
+Use `--output-format text` (the default). Do not use `stream-json` for labor:
+the returned body goes back into the seat's context and the event stream is
+noise (see `opus.md` for the measured ratio). Progress observability belongs to
+the runner's process watch, not to the returned body. Measured on this host
 with separate fd redirects (`1>` / `2>`): stdout is the labor answer body;
 stderr carries the version line, thinking bullets, and the trailing
 `To resume this session:` hint. Collect the labor body from stdout only — do

package/resources/engines/opencode.md

@@ -20,7 +20,8 @@ opencode run -m opencode-go/glm-5.2 "YOUR_LABOR_PROMPT"
   `opencode models` first** — provider prefixes migrate (verified 2026-08-21:
   GLM lives under `opencode-go/`, e.g. `opencode-go/glm-5.2`; the older
   `zai/glm-5.2` id errors with "Unexpected server error").
-- `--format json` gives structured output; `--auto` auto-approves non-denied
-  permissions for unattended runs (both per official docs).
+- Plain text output only (never `--format json` for labor — the returned body
+  goes back into the seat's context); `--auto` auto-approves non-denied
+  permissions for unattended runs (per official docs).
 - Output goes to stdout; long prompts may be passed via shell heredoc or a
   file read into the argument — follow the installed CLI's actual interface.

package/resources/engines/opus.md

@@ -12,34 +12,27 @@ parameters.
 The machine entrypoint is `claude`. Run from the role project root. Non-interactive
 print mode (`-p` / `--print`) is verified available on this host.
 
-On this host (Claude Code 2.1.233), `--print` with `--output-format=stream-json`
-requires `--verbose` — without it the CLI exits immediately with
-`Error: When using --print, --output-format=stream-json requires --verbose`.
-Include `--verbose` in stream-json argv. Measured with separate fd redirects
-(`1>` / `2>`): NDJSON event rows land on stdout (including intermediate
-`system` / `assistant` activity and a final `type:"result"` row); stderr is
-empty on the success path — except when stdin is an open stream supplying no
-data (e.g. a shell test without redirection): then a benign
-`Warning: no stdin data received in 3s, proceeding without it` lands on stderr
-after a 3-second wait (host-verified 2026-08-28); redirect `< /dev/null` in
-shell tests. The packaged detour tool spawns engines with stdin ignored
-(`/dev/null`), which avoids this path:
+Print mode (`-p`) with `--output-format text` returns the labor body on stdout;
+stderr carries banners only. Measured with separate fd redirects (`1>` / `2>`).
 
 ```bash
-claude -p --verbose --output-format=stream-json "YOUR_LABOR_PROMPT"
+claude -p --output-format text "YOUR_LABOR_PROMPT"
 ```
 
 Pin the Opus model explicitly (`--model opus` verified accepted on this host;
 init event reports `claude-opus-5`):
 
 ```bash
-claude -p --model opus --verbose --output-format=stream-json "YOUR_LABOR_PROMPT"
+claude -p --model opus --output-format text "YOUR_LABOR_PROMPT"
 ```
 
-Use `--output-format=stream-json` (choices measured on this host: `text`, `json`,
-`stream-json`) when long labor needs progressive observability while the engine
-works; take the labor body from the final `result` event's `result` field,
-not from intermediate stream rows.
+Use `--output-format text` (the default): stdout is the labor body and nothing
+else. Never use `--output-format=stream-json` / `--verbose` for labor — the
+returned body goes back into the seat's context, and the event stream is noise:
+measured 2026-09-06 on this host, the same one-sentence task returned 382 bytes
+as `text` and 45,028 bytes as `stream-json --verbose` (118×); a 12-minute labor
+returned 957k chars and killed the seat with a 712k-token request (#675). Progress observability belongs to the runner's
+process watch, not to the returned body.
 
 ## Headless permissions
 

package/resources/engines/sonnet.md

@@ -10,18 +10,17 @@ parameters.
 ## Invocation
 
 Same host CLI as the `opus` engine: the machine entrypoint is `claude`, and all
-CLI mechanics (print mode, `--output-format=stream-json` requiring `--verbose`,
-fd layout, result-row extraction) are documented in `../opus.md` — read that
+CLI mechanics (print mode, `--output-format text`, fd layout) are documented in `../opus.md` — read that
 note for them; they are not duplicated here.
 
 The only difference is the model pin:
 
 ```bash
-claude -p --model sonnet --verbose --output-format=stream-json "YOUR_LABOR_PROMPT"
+claude -p --model sonnet --output-format text "YOUR_LABOR_PROMPT"
 ```
 
 `--model sonnet` is verified accepted on this host (Claude Code 2.1.233); the
-stream-json init event reports `claude-sonnet-5` (host-verified 2026-08-28).
+`json` init metadata reports `claude-sonnet-5` (host-verified 2026-08-28).
 
 Prefer `claude --help` on the host over any remembered flag set. Do not wrap
 this engine behind `ak-role` flags.

package/resources/engines/zcode.md

@@ -18,8 +18,8 @@ zcode --prompt 'YOUR_LABOR_PROMPT' --cwd /path/to/worktree
 
 `--prompt` defaults to permission mode `yolo` (no TTY permission stalls).
 Useful extras measured from `zcode --help`: `--attach <path>` (repeatable),
-`--mode build|edit|plan|yolo`, `--resume <sess_...>`, `--json` where
-supported. Prefer `zcode --help` on the host over any remembered flag set.
+`--mode build|edit|plan|yolo`, `--resume <sess_...>`. Never `--json` for
+labor (the returned body goes back into the seat's context as plain text). Prefer `zcode --help` on the host over any remembered flag set.
 
 ## Realm and model traps (host-verified 2026-08-29, all three hit in sequence)