@op1/threads 0.1.7 → 0.2.0

package/README.md

@@ -1,20 +1,32 @@
 # @op1/threads
 
-Managed top-level worker sessions for OpenCode 2.0.7. The server entrypoint is `index.ts`; the terminal entrypoint is `tui.ts`.
+Managed top-level worker sessions and dynamic workflows for OpenCode V2. Dynamic workflows target OpenCode 2.0.12. The server entrypoint is `index.ts`; the terminal entrypoint is `tui.ts`.
 
-## Install
+## Dynamic workflows
 
-Install the plugin globally:
+Use `/workflow-run <task>` to have OpenCode author a JavaScript workflow with parallel agents, structured handoffs, and a durable run journal. `/workflows` opens the run navigator. Workers use native OpenCode conversations and configured agent profiles, including VERA roles.
+
+Dynamic workflows are included in `@op1/threads` 0.2.0. The `v0.1.8` tag preserves the pre-workflow release.
+
+Read [Run a dynamic workflow](docs/workflows.md) for progress, pause, stop, resume, worktree, and saved-script usage. The [runtime contract](skills/workflow-authoring/references/runtime.md) documents the authoring API and execution limits.
+
+See [verification evidence](docs/workflows-verification.md) for the native checks and recovery guarantees.
+
+See [capacity and limits](docs/workflow-capacity-findings.md) for total agent steps, concurrent workers, and measured load.
+
+## Install dynamic workflows
+
+Install the versioned plugin globally:
 
 ```sh
-opencode plugin add @op1/threads
+opencode plugin add @op1/threads@0.2.0
 ```
 
 Or add it to `plugins` in `~/.config/opencode/opencode.jsonc`:
 
 ```jsonc
 {
-  "plugins": ["@op1/threads"]
+  "plugins": ["@op1/threads@0.2.0"]
 }
 ```
 
@@ -22,7 +34,7 @@ Keep the other entries in your plugin list. Open a fresh TUI to load the termina
 
 The `skills/managed-sessions` directory contains the VERA delegation guide. Copy or link it into `~/.config/opencode/skills/managed-sessions` to make it available to agents.
 
-For local development, clone [opzero1/threads](https://github.com/opzero1/threads), run `bun install`, and use the clone's absolute path as the plugin entry instead. The internal plugin ID remains `op-threads`, so switching between local and published installs preserves worker records.
+The internal plugin ID remains `op-threads`, so switching between local and published installs preserves worker records. For local development, clone the `dynamic-workflows` branch, run `bun install`, and use the checkout's absolute path as the plugin entry.
 
 ## Delegate work
 
@@ -88,11 +100,17 @@ Send keys are scoped to the worker and determine a stable message ID. A retry wi
 
 Plugin option `maxWorkers` defaults to 4 and accepts integers from 1 through 32. Admission is serialized by coordinator within the loaded server process. A worker without a report continues to occupy a slot unless its native outcome is `failed` or `interrupted`. A successful run without a report does not silently free its slot.
 
+Plugin option `workflowConcurrency` sets the default concurrency for new workflows. It accepts integers from 1 through 8 and defaults to 3. Plugin option `workflowMaxAgents` sets their total agent-step limit, accepts integers from 1 through 1,000, and defaults to 4. Explicit `workflows_start` values override these defaults. Existing runs retain their recorded limits. For eight concurrent agents with eight total steps, configure `"options": { "maxWorkers": 32, "workflowConcurrency": 8, "workflowMaxAgents": 8 }` on the plugin entry.
+
 ## Terminal and RPC
 
-The terminal synchronizes workers before opening native tabs without changing focus. A TUI memory index survives plugin reloads and respects manually closed tabs. `/threads` explicitly reopens workers for open coordinator tabs. A new TUI recovers workers from durable storage. Closing the TUI does not interrupt workers.
+The terminal synchronizes workers before opening native tabs without changing focus. A TUI memory index survives plugin reloads and respects manually closed native tabs. Conversations closed through Activity stay dismissed across restarts. `/threads` explicitly reopens workers for open coordinator tabs, including workers dismissed through Activity. A new TUI recovers the other workers from durable storage. Closing the TUI does not interrupt workers.
+
+Activity shows Main and Worker roles as row subtitles. It omits a leading `[Main] ` or `[Worker] ` from known managed titles, including closed history rows and prefixes reapplied by older clients. Managed identity comes from the worker RPC, including lookups for loaded history conversations whose workers are on older pages. Unrelated prefixed titles remain unchanged.
+
+For open managed tabs, the TUI also removes one legacy prefix from the fresh saved title. The remainder stays unchanged, and empty remainders are not saved. A durable client-storage marker makes this saved-title cleanup one-shot per session. Later intentional prefixed renames remain in saved history, while Activity omits the redundant role label from its display.
 
-Managed tabs use saved title prefixes: `[Main]` for the coordinator and `[Worker]` for each managed worker. Labels appear when the TUI discovers the relationship, including existing threads. The rest of the title stays editable; renaming a managed conversation reapplies its role prefix. Unrelated sessions keep their titles. OpenCode's native tab API has no separate badge field, so the prefixes also appear in session history.
+When upgrading, restart all existing TUIs. Older 0.1.7 clients still write role prefixes and can reapply them after cleanup.
 
 Workers with `PASS` or `PASS WITH NOTES` reports hide automatically once idle. This also applies to reports saved before upgrading. Unreported workers and `FAIL` or `INCONCLUSIVE` reports stay visible. The selected tab, running workers, and tabs needing input stay open until they are inactive.
 
@@ -100,7 +118,7 @@ The coordinator can call `threads_hide` when a worker is no longer needed. Hidin
 
 Reports reach the coordinator through silent synthetic messages. They remain available through `threads_list` and the session history without adding a notification row to the conversation. Older report notification rows remain in native history.
 
-All open native root-session tabs are automatically grouped by OpenCode project ID, including sessions not managed by this plugin. Projects follow their first appearance in the current tab order. Worktrees with the same project ID stay together.
+With Activity disabled or unable to mount, open native root-session tabs are grouped by OpenCode project ID, including sessions not managed by this plugin. This includes horizontal, narrow, and unsupported-version fallback. Projects follow their first appearance in the current tab order. Worktrees with the same project ID stay together.
 
 Within each project, running sessions and sessions waiting for input come before idle sessions. Tabs with the same priority keep their relative order. Selecting an idle tab does not reorder it. Native tab order is shared between terminals in the same directory, so sorting by each terminal's selection would make them repeatedly undo each other's moves. Idle is a display priority, not a completion verdict. Each tab with unloaded project metadata stays in its own group until that metadata becomes available. Reconciliation moves only out-of-order tabs, without changing focus or closing and reopening them to reorder. Native tabs do not support divider rows.
 
@@ -113,14 +131,74 @@ result: { workers: WorkerView[] }
 
 The input accepts at most 100 coordinator IDs. Raw HTTP RPC requests wrap the input as `{ "input": { "coordinatorIDs": ["ses_..."] } }`. Each method declares `errors: {}` and the RPC declares `events: {}`. The TUI subscribes to native session events and reconciles at most one snapshot at a time, with a three-second missed-event refresh.
 
+## Activity sidebar
+
+Activity replaces the contents of the native left vertical tab rail on compatible OpenCode V2 layouts. Native tabs remain enabled and retain their layout reservation, resize handle, activity state, and session navigation. The prompt and transcript remain native OpenCode UI.
+
+Subtitles start with the project name or folder basename, followed by a distinct location or worktree basename when needed. Main and Worker labels appear only for known managed relationships; ordinary history rows show project and location without a role label.
+
+Rows are grouped in this order:
+
+- **Priority**: permission or form attention, then running work, then unread results or errors.
+- **Pinned**: pinned conversations without priority activity.
+- **Today**, **Yesterday**, recent weekdays, and older calendar dates, using the local timezone.
+
+Divider lines separate sections. Click a heading to collapse or expand its conversations; the arrow and count show its current state. Collapsed sections stay collapsed across reloads and restarts. This changes sidebar visibility without closing tabs, and `/activities` can still find conversations in collapsed sections.
+
+A session appears once. Priority takes precedence over pinning. Idle does not mean that a task passed. Open-tab status comes from the native tab API; closed history uses available native running and input-request state, without inventing a success status. Date groups use the last native execution's `time.idle`, falling back to `time.updated` for conversations without an execution. Title cleanup therefore does not move an older executed conversation into Today.
+
+Running rows use OpenCode's registered animated dot spinner. Input requests take precedence over the spinner, and it is removed when the session becomes idle.
+
+Colors follow the active theme: selected conversations and date headings use its accent, running indicators use its information color, and input requests use its warning color. Unread errors use the error color. Worker headings and pinned controls use purple, while project subtitles and inactive controls use subdued text. Blank lines separate section headings from conversations and give worker groups space above and below their heading. Long titles are truncated to keep the action buttons separate.
+
+Managed workers appear indented under their main conversation. The stack appears in **Priority** when any member is running, needs input, or has an unread result. Otherwise, a pin on any visible member places the stack in **Pinned**; date sections use the most recent member activity. Workers with an unavailable main conversation remain standalone rows.
+
+Each main conversation with workers has a **▾ Workers (N)** heading below its subtitle. Click the heading to collapse the worker list, or **▸ Workers (N)** to expand it. When the list is collapsed, the main row summarizes worker activity, with input requests taking precedence over running spinners. Collapsing keeps the workers running and their tabs open. Stack preferences survive reloads and restarts, and `/activities` still lists collapsed workers.
+
+Activity fetches the 100 most recent root sessions across projects and refreshes them in the background. Open and pinned sessions are merged into the list; older pins and known main conversations are resolved individually. Archived, deleted, and native child sessions are excluded. Closed managed workers are not reintroduced by fetched history. `/threads` restores their native tabs using the existing worker visibility rules.
+
+Left-click a row to open or focus its real session. Each row has one-click **[◇]** (pin), **[◆]** (unpin), and **[×]** (close from Activity) buttons beside its title. These controls work on both main and worker rows without selecting a background conversation. Closing removes the row and closes its native tab when open. Saved history and the pin preference remain intact. Dismissed rows stay hidden through refreshes, reloads, and restarts. Selecting a closed conversation in `/activities` restores it; `/threads` also restores dismissed managed workers. Reopening a conversation through native session navigation restores its Activity row. Right-click also opens the action menu. The mouse wheel scrolls the list, and the native rail edge remains draggable.
+
+| Command | Action |
+| --- | --- |
+| `/activity` | Toggle Activity and the native rail |
+| `/pin` | Pin or unpin the current conversation |
+| `/activities` | Choose a loaded conversation, including closed Activity rows, and restore it if needed |
+| `/activity-sections` | Choose a section to collapse or expand |
+| `/activity-threads` | Choose a managed worker stack to collapse or expand |
+| `/threads` | Restore managed worker tabs |
+
+The same actions are available in the command palette. **+ New session** dispatches OpenCode's registered `session.new` command. Pins use plugin client storage and survive TUI reloads and restarts.
+
+In `/activities`, **Ctrl+F** pins or unpins the highlighted conversation. The picker stays open and preserves your search and selection. This also works for conversations in **Priority**. **Enter** opens the highlighted conversation, and **Esc** closes the picker. The footer shows the current pin action. Configure `threads.activity.choose.pin` in `cli.json` to change the shortcut.
+
+Activity requires vertical tabs. To select the layout and disable Activity by default, configure the terminal plugin in `~/.config/opencode/cli.json`:
+
+```json
+{
+  "tabs": { "layout": "vertical" },
+  "plugins": [{ "package": "@op1/threads", "options": { "activity": false } }]
+}
+```
+
+Omit `activity` or set it to `true` to enable the sidebar. Keep the server plugin in `opencode.json`; server plugin options are not forwarded to the terminal entrypoint. For local development, replace the package name in both files with the clone's absolute path.
+
+The left rail has no public plugin slot in 2.0.7. `src/activity-rail.ts` is an internal compatibility adapter: it checks a bounded render-tree structure and unambiguous geometry, hides native children while remembering their visibility, and mounts only plugin-owned content. OpenTUI constructors are imported at the terminal entrypoint to preserve host identity. The adapter uses renderer pre-paint callbacks and resize events, not continuous tree polling or root monkeypatches. It restores native children on detach, toggle, and disposal. Compatibility depends on the detected rail structure and geometry, regardless of the OpenCode version string. Unrecognized rail structures, horizontal layouts, and narrow layouts fall back to native tabs. Activity never moves shared native tabs while mounted; native project and activity grouping resumes during fallback.
+
+`src/activity-theme.ts` accepts both `base`/`muted` and legacy `default`/`subdued` theme tokens. Missing colors use a valid fallback before reaching the renderer: assigning an undefined spinner color aborts the entire frame. Accent and worker colors follow the theme's foreground brightness rather than fixed light/dark shade numbers. If a hue lacks sufficient text contrast, Activity uses the theme's normal foreground. The `@opencode/theme` development dependency keeps the host theme types available to TypeScript. Renderer regression tests cover both token shapes and missing colors, including spinner construction and subsequent color updates.
+
 ## Verification and limits
 
-Run `bun run typecheck`, `bun test`, and `bun run verify:live`. The live check requires OpenCode 2.0.7, Python, and `uv`. It starts a separate local server, a deterministic model endpoint, and a terminal process with isolated configuration and data. It verifies actual tool calls, durable messages, permission restrictions, worker limits, deleted-worker cleanup, restart behavior, and native tab visibility, busy state, and focus.
+Run `bun run typecheck`, `bun test`, and `bun run verify:live`. The live check requires OpenCode V2, Python, and `uv`. It starts a separate local server, a deterministic model endpoint, and a terminal process with isolated configuration and data. It verifies actual tool calls, durable messages, permission restrictions, worker limits, deleted-worker cleanup, restart behavior, and native tab visibility, busy state, and focus.
 
 Run `bun run verify:tabs` to verify project grouping across real git worktrees, activity-based ordering, permission prompts, completed and resumed workers, focus preservation, and TUI reopening.
 
+Run `bun run verify:activity` to exercise Activity enabled against an isolated instance of the installed OpenCode version. The suite clears its own `.audit/activity` artifacts, uses the deterministic model fixture, and reads actual renderer bounds through the test-only TUI probe. It checks layout, click and keyboard navigation, one-click pin and close controls, and native prompt responses. It also covers section and worker-stack collapse, aggregated worker status, title cleanup, worker restoration, fallback layouts, reloads, and restart persistence. `verify:tabs` and `verify:idle-tabs` explicitly disable Activity to inspect native ordering.
+
 Run `bun run verify:roles` to verify named profiles against the native server and deterministic model endpoint. It checks actual system prompts, model variants, native delegation, read-only execution, reporting, and role-aware retries.
 
+Run `bun run verify:workflows` to exercise dynamic scripts through real OpenCode tools and sessions. The isolated fixture checks structured pipelines, exact retries, role restrictions, ownership, checkpoints, saved scripts, retained worktrees, service restart, and the terminal navigator.
+
 Run `bun run verify:idle-tabs` to open two native terminals on different idle sessions in the same directory and verify that their shared tab order stays stable.
 
 Pass an extracted package directory to test the release artifact: `bun run verify:live /absolute/path/to/package`.

package/docs/dynamic-workflows-plan.md

@@ -0,0 +1,46 @@
+# Dynamic workflows implementation
+
+## Completion criteria
+
+An OpenCode V2 session can submit a JavaScript workflow, continue its conversation while agents run, inspect phases and worker sessions, receive validated results, pause or stop, and resume recorded work after a service restart. Writing steps can use retained worktrees. Saved workflows can run again with different arguments. VERA profiles retain their configured models and permissions. A failed or inconclusive task cannot silently become a passing workflow.
+
+Verification covers the confined interpreter, the durable runner, actual OpenCode session and tool calls, restart recovery, and the terminal controls. A final real-model run exercises workflow authoring and structured handoffs. An independent reviewer inspects the implementation and evidence before completion.
+
+## Baseline
+
+- Threads: `df7686af1c6601ae7d05ae607bc584f185109231`, annotated tag `v0.1.8`, already present at `opzero1/threads`.
+- Dotfiles: snapshot the current tracked setup and intended additions in `afif-reap/dotfiles` before changing VERA guidance.
+- Installed OpenCode: `2.0.12`.
+
+## Ownership
+
+Implement workflow modules in the existing Threads package. This shares the worker service and its ownership checks without requiring an unauthenticated cross-plugin dispatch API. The `workflows` tool namespace and RPC remain distinct from the existing `threads` interface.
+
+VERA selects the process and owns the final engineering verdict. The workflow runner schedules steps, validates handoffs, journals progress, and reconciles interrupted work. OpenCode owns model execution, permissions, tools, and worktrees. The TUI renders server state and links to native sessions.
+
+Use the published `@opencode/codemode` package pinned to `2.0.12` for confined execution. The initial reference checkout marked its older package private; the published V2 package has a supported export. Generated scripts never run through host `eval`, `Function`, or Node `vm`.
+
+## Protocol
+
+1. Checkpoint the repositories and capture the existing test baseline.
+2. Prove the confined script adapter with real interpreter tests: structured fan-out, per-item pipelines, deterministic inputs, cancellation, invalid scripts, and failures.
+3. Implement the durable runner and worker adapter. Persist dispatch identities before starting work. Record validated results before returning them to scripts. Reconcile existing worker sessions on resume. Reject concurrent execution of the same run.
+4. Integrate role authorization, structured result reporting, retained worktrees, concurrency and call limits, measured usage, saved workflows, and bounded retry helpers.
+5. Add workflow tools, server commands, RPC, terminal navigation, phase and step progress, and pause, stop, resume, and checkpoint controls.
+6. Add the workflow-authoring and VERA recipes. Verify actual OpenCode sessions and terminal interactions in isolated fixtures, then a scoped real-model run.
+7. Inspect the complete diff, independently audit behavior and the decision trail, and resolve accepted findings.
+
+## Recovery contract
+
+The journal records a run, its script and arguments, each named step's request fingerprint, worker identity, execution outcome, validated result, and evidence. A restart does not blindly replay user-visible effects. Resume first reconciles an existing worker and any recorded result. An interrupted write with uncertain state requires inspection rather than an automatic fresh worker.
+
+Script control flow uses only arguments and recorded step results. Reject clock and randomness access. A run's script and arguments are immutable. Resume reuses matching named steps; a changed request under the same key fails closed. An edited saved script starts a new run. This avoids reusing results whose dependencies changed through untracked script control flow. Worktree paths and results survive completion. Integration is a distinct verified action.
+
+## Reference guidance
+
+- [Pi Dynamic Workflows](https://github.com/QuintinShaw/pi-dynamic-workflows): code orchestration, role routing, journaling, worktrees, and interactive progress.
+- [Devin Dynamic Workflows](https://docs.devin.ai/work-with-devin/dynamic-workflows): structured per-item pipelines and when workflows are useful.
+- [Claude Code workflows](https://code.claude.com/docs/en/workflows): deterministic scripts, replay semantics, saved commands, background controls, and validation before spawning.
+- [OpenCode V2 plugins](https://opencode.ai/v2/docs/build/plugins): supported host integration.
+
+The references inform the behavior. Existing OpenCode and VERA ownership, permissions, and evidence requirements determine the implementation.

package/docs/workflow-capacity-findings.md

@@ -0,0 +1,47 @@
+# Workflow capacity findings
+
+The native load harness uses an isolated OpenCode service and a deterministic local provider. It makes no paid model calls. The package uses `@opencode/plugin` and `@opencode/schema` 2.0.7, with `@opencode/codemode` 2.0.12.
+
+## Exact bounds
+
+- Workflow concurrency defaults to 3 and accepts 1–8. The plugin option `workflowConcurrency` overrides the default for new runs; explicit run values take precedence.
+- A workflow defaults to 4 agents and accepts 1–1,000 total agent steps. The plugin option `workflowMaxAgents` overrides the default for new runs; explicit run values take precedence.
+- Worker and run timeouts accept 1 second through 7 days. Defaults are 30 minutes per worker and 24 hours per run.
+- Threads `maxWorkers` defaults to 4 and accepts 1–32. It is both the unfinished managed-worker admission limit and the owner-wide workflow execution limit. A run's effective concurrency is therefore `min(concurrency, maxWorkers)`, with `maxWorkers` shared by simultaneous workflows owned by one session.
+- Workflow workers are top-level native OpenCode sessions. Workflow workers cannot delegate, start workflows, or spawn managed workers. Managed Threads workers may use native subagents if their permissions allow it, but cannot spawn another managed worker.
+- Saved workflow nesting permits four `workflow()` boundaries; the fifth fails. Cumulative host calls are bounded at `maxAgents * 8 + 100`, shared with nested calls. Arguments, host-call payloads, results, checkpoint responses, and each durable worker report are limited to 1 MiB.
+- The runtime module admits 64 simultaneous interpreter calls, including nested calls. These Bun workers execute scripts; they are separate from native agent sessions. Excess calls fail immediately rather than waiting for nested work to free a slot.
+- The durable run record is limited to 16 MiB, including embedded settlement order. Payload admission reserves at least 64 KiB for control metadata, with additional space for outstanding step and settlement diagnostics. The reservation reduces usable payload capacity.
+- Progress logs retain the newest 200 entries, each truncated to 2,000 characters. Checkpoint prompts are truncated to 10,000 characters. Reports allow at most 100 evidence strings; summary and evidence strings are each limited to 20,000 characters.
+
+## Measured capacity
+
+`bun run verify:workflow-capacity --steps 1000 --timeout 900` passes all eight scenarios on OpenCode 2.0.14 and Bun 1.4.0:
+
+| Measurement | Result |
+| --- | --- |
+| Sustained run | 1,000 steps, 1,000 unique native worker sessions, ordered results |
+| Sustained elapsed time | 229.823 seconds |
+| Owner pool | Two runs share eight concurrent workers; 16 unique sessions across both runs |
+| Service RSS at eight blocked workers | 565,493,760 bytes, about 539 MiB |
+| Pause | 0.242 seconds; eight active workers drain, eight queued workers do not start |
+| Stop | 0.120 seconds; eight active native requests interrupted |
+| One-second worker deadline | Failure observed after 1.321 seconds, including dispatch and teardown |
+| One-second run deadline | Failure observed after 1.149 seconds |
+| Host-call boundary | 108 accepted; 109 rejected when `maxAgents` is 1 |
+| Log retention | Newest 200 of 205 entries retained |
+| Cleanup | Zero active sessions; all 1,016 worker identities from the sustained and shared-pool scenarios retained |
+
+The measured source hash is `1414fd9d27ead4a1f955f11168917842aaef043a8eec172b7bd73699aaf3e414`. These timings describe a deterministic provider on one machine, not real-model throughput. RSS is one service sample, not peak memory. The result does not establish capacity at 32 workers, across multiple owners, or over a seven-day run.
+
+Separate native regressions exercise the nesting boundary. Focused tests exercise byte-size limits and simultaneous failure diagnostics. The 35-cycle runtime soak checks CPU termination and native thread cleanup; it does not load-test 64 simultaneous interpreters.
+
+## Native OpenCode limits
+
+The inspected V2 schema defines agent `steps` as a positive integer and exposes no global native-session concurrency ceiling. This is not proof of unlimited capacity. `experimental.subagent_depth` defaults to 1. These native-generation controls are separate from workflow concurrency and total steps. The user's current configuration sets depth to 2 and the `general` agent to 20 steps.
+
+## Practical recommendation
+
+Use at most eight workflow workers per owner, keep the default four for ordinary interactive use, and increase to eight only for an isolated load or known I/O-bound work. Prefer batches of 100–250 concise steps even though 1,000 are admitted. Store large evidence in artifact files and return paths. Keep reports far below 1 MiB so the 16 MiB aggregate journal retains headroom. Do not treat the configured maximum of 32 managed workers as a verified operating target.
+
+The harness writes measured evidence to `.audit/workflow-capacity/evidence.json`. The capacity fixture explicitly configures eight workers. The plugin's four-worker default can be overridden with `maxWorkers`.

package/docs/workflows-verification.md

@@ -0,0 +1,105 @@
+# Dynamic workflow verification
+
+The hardening pass targets the seven defects reproduced against `5858de1`, plus storage and timeout races found during integration. The original blanket readiness claim is superseded by these checks and the limits below.
+
+Current verification uses OpenCode `2.0.14`, Bun `1.4.0`, and published `@opencode/codemode` `2.0.12`. Earlier baseline and failing-before evidence used OpenCode `2.0.12`.
+
+## Version 0.2.0 release verification
+
+The release adds configurable `workflowConcurrency` and `workflowMaxAgents` defaults for new runs. Explicit run values take precedence, and resumed records retain their original limits. The persisted schema defaults remain 3 concurrent agents and 4 total steps.
+
+Release verification passed on OpenCode 2.0.14:
+
+- `bun run typecheck` and all 109 unit tests / 407 assertions.
+- 13 native regression cases against the extracted npm package, including configured 8/8 defaults, explicit 2/2 overrides, eight completed steps, and resumed 3/4 limits.
+- 27 native workflow/TUI checks and 27 managed-session checks against the extracted package with fresh production dependencies.
+- Independent source review: **PASS WITH NOTES**, with no release-blocking findings.
+
+The packed source hash is `3b5b77f200d79164227c3caeb86eeab95f4c1188b8f7d5c1f689296e1022df72`. The package includes both entrypoints, all runtime worker modules, and the authoring skill with its runtime reference. Local release artifacts are in `.audit/release-0.2.0/`.
+
+## Hardening checkpoint checks
+
+| Command | Result | Coverage |
+| --- | --- | --- |
+| `bun run typecheck` | Pass | Server, runtime, and terminal types |
+| `bun test` | 109 tests, 407 assertions pass | Confinement, replay, checkpoint atomicity, journal limits, deadline races, failed-attempt accounting, and existing Threads behavior |
+| `bun run verify:workflow-regressions` | 12 cases pass | Original engine defects, CPU-bound deadline, saved and nested execution, composition helpers, and retained-worktree handoff |
+| `bun run verify:roles` | 17 checks pass | Configured profiles, inherited restrictions, role admission, and native delegation |
+| `bun run verify:live` | 27 checks pass | Managed-worker lifecycle, reports, limits, native tabs, and restart recovery |
+| `bun run verify:workflow-runtime` | Pass | 35 CPU-bound interpreter cancellations, stable native thread count, and idle CPU |
+| `python3 scripts/verify-workflows-model.py` | Pass | Model-authored workflow, real VERA readers, validated handoffs, and automatic coordinator notification |
+| `bun run verify:workflows` | 27 checks pass | Native workflow lifecycle, permissions, hard restart, uncertain writes, fresh navigator snapshots, keyboard step navigation, and terminal controls |
+| `bun run verify:workflow-capacity --steps 1000 --timeout 900` | 8 scenarios pass | Eight concurrent workers, 1,000 unique native sessions, owner pool sharing, controls, deadlines, and cleanup |
+
+Native harnesses use real isolated OpenCode services with deterministic local providers. These fixtures prove execution behavior rather than model quality. The separate real-model check uses the installed plugin and configured VERA profiles.
+
+Each workflow, regression, and capacity harness records a hash of `index.ts`, `tui.ts`, `package.json`, and direct TypeScript sources in `src/`. It rejects source changes during its run. Local artifacts are retained under `.audit/` and are gitignored:
+
+- `workflows/evidence.json` and `workflows/tui.screen.txt`
+- `workflow-regressions/evidence.json` and `workflow-regressions/evidence.baseline.json`
+- `workflow-capacity/evidence.json`
+- `runtime-soak/evidence.json`
+- `workflow-model/evidence.json`
+
+The commands regenerate the evidence. Raw transcripts and temporary session directories are not published.
+
+The final workflow, regression, and 1,000-step capacity runs all verified source hash `1414fd9d27ead4a1f955f11168917842aaef043a8eec172b7bd73699aaf3e414`.
+
+## Regression and recovery proof
+
+The native regression harness first reproduced six engine failures on the old source. The runtime tests separately reproduced the synchronous deadline failure. All twelve native cases now pass:
+
+1. Queued agents cannot dispatch after the measured token budget is exhausted.
+2. Failed attempts count toward that budget.
+3. Answering one checkpoint preserves `waiting` when another remains unanswered.
+4. Concurrent checkpoint responses replay in their recorded order after restart.
+5. An exposed failure remains a failure on replay, preserving the script's fallback branch.
+6. A crash after an accepted report requires explicit same-worker resolution.
+7. Saved scripts accept new arguments and retain pinned nested source after restart.
+8. Composition helpers execute through the native service.
+9. Saved commands register and refresh.
+10. A fifth nested workflow boundary fails.
+11. A writer and verifier use the same retained worktree.
+12. A CPU-bound script reaches its deadline while service RPC remains responsive.
+
+The hard-crash fixture appends one line, blocks before its report, and kills the service. After restart, no provider request is allowed until explicit recovery. Resume preserves the uncertain write. A follow-up asks the same worker to inspect and report its existing effect; the final file still has exactly one line.
+
+Checkpoint responses and settlement order are committed atomically. Focused tests reject oversized responses before persistence, allow a smaller retry, and retain a concurrently committed agent settlement. Legacy external journals remain preserved during migration. Payload admission reserves diagnostic space while retaining the 16 MiB hard limit.
+
+The macOS runtime soak starts and cancels 35 CPU-bound interpreters. Native thread count returns from 25 to 25, and the following idle second consumes 2.157 ms of process CPU. The check uses the real CodeMode interpreter inside terminable Bun workers.
+
+## Independent review
+
+Independent review is a release gate. The initial audit rejected unqualified readiness and supplied executable counterexamples. Later review found a constructor-failure capacity leak, checkpoint journal poisoning, insufficient control headroom, and recovery failures that affected healthy sibling runs. Those findings received focused regression tests and fixes.
+
+The final integrated engine/store review returned **PASS WITH NOTES**, with no blocking findings. Its remaining timer-cleanup finding was reproduced and fixed: a full legacy journal now clears the deadline and notifies the owner even when failure persistence also fails. The focused test preserves both original records.
+
+A separate UI reviewer identified the stale navigator snapshot, then returned **PASS WITH NOTES** after the fix. Explicit refreshes are serialized, background requests coalesce, and responses are guarded across owner navigation. The native terminal suite passes all 27 checks. The A→B→A generation guard has source review but no dedicated navigation regression.
+
+Accepted review limits include unsupported selective deletion of journal records, replay-order mismatches waiting until the run deadline, and reliance on a single loaded scheduler implementation. Checkpoint responses appear both in the checkpoint and its settlement entry, so they count twice toward the journal limit. A nearly full run can reject even a small response while preserving the unanswered checkpoint. Passing implementation-worker reports alone are not treated as independent approval.
+
+## Real-model verification
+
+Run `wfr_8eafe136e930d91c0127b44532be49a4` completed through coordinator `ses_f35910071ffe0I7E0NR3Bzfvfk`, using `vera-core`:
+
+- `vera-operator-readonly`, `openai/gpt-5.6-sol#low`, read `src/workflow-types.ts`.
+- `vera-engineer-readonly`, `openai/gpt-5.6-sol#medium`, read `src/workflow-rpc.ts`.
+- Validated result: `{"limits":{"concurrency":3,"maxAgents":4},"controls":["pause","resume","stop"]}`.
+
+Both worker models matched their profiles and journal records. Their transcripts contain successful reads and accepted results. After the automatic notification, the coordinator inspected the run and delivered a PASS receipt.
+
+## Execution boundaries
+
+- One OpenCode service with one loaded scheduler implementation owns scheduling. Multiple services or duplicate module instances sharing storage are unsupported.
+- Interrupted writes require inspection and same-worker resolution. A missing worker does not authorize repeating its effects.
+- Scripts, arguments, and nested scripts are immutable within a run. Changes require a new run key.
+- Native failures and explicit `FAIL` or `INCONCLUSIVE` reports prevent completion, even when the script catches them.
+- Token budgets govern dispatch using reported usage. In-flight work can exceed the threshold; unmeasured usage blocks further budgeted dispatch.
+- Old journals without checkpoint settlement order cannot replay answered checkpoints deterministically. They fail with a diagnostic rather than inventing an order.
+- Corrupt and exact-limit legacy records retain their evidence and produce owner-visible diagnostics. A full legacy record may require explicit repair or a new run key.
+- Selectively deleting a run record while retaining its legacy completion journal is unsupported. Both records belong to the same run identity.
+- An inconsistent settlement order can wait until the run deadline. Recovery does not invent missing completions to make the script advance.
+- Interpreter termination stops script CPU work. Parent-side host effects remain subject to native interruption and uncertain-write recovery.
+- Worktrees remain available for inspection and integration. The coordinator owns the final engineering verdict.
+
+The [capacity findings](workflow-capacity-findings.md) distinguish cumulative sessions, concurrent agents, interpreter calls, and measured operating limits.

package/docs/workflows.md

@@ -0,0 +1,60 @@
+# Run a dynamic workflow
+
+Describe the work with `/workflow-run`. OpenCode loads the authoring contract, writes a JavaScript script, and starts the run in the background.
+
+```text
+/workflow-run Audit src/auth and src/billing for missing authorization checks. Use VERA reviewers, confirm each finding independently, and return source references.
+```
+
+The run has a stable ID. Your conversation stays available while its agents work. Each worker uses a native OpenCode session with its selected profile, model, and permissions.
+
+## Inspect progress
+
+1. Run `/workflows`.
+2. Select a run to open its panel.
+3. Select a step with the arrow keys and press **Enter**, or click it, to open its native worker conversation.
+
+The panel shows phases, step outcomes, verdicts, evidence, retained directories, recorded usage, and the final result. Step counts include work recorded so far; a dynamic script can add more steps. Press `f` for the full-screen view or `Esc` to close the panel.
+
+The navigator lists every run owned by the current coordinator session, including completed and failed runs. The detail panel shows one selected run. Other coordinator sessions have their own run lists.
+
+Ask the agent to inspect the run when you need its complete saved script or structured handoffs:
+
+```text
+Inspect that workflow and summarize the confirmed findings and missing evidence.
+```
+
+## Pause, stop, and resume
+
+Press `p` in the run panel to pause new scheduling. Active steps finish before the run becomes paused.
+
+Press `x` to stop the run and interrupt its active workers. Completed results and worktree directories remain available.
+
+Press `r` to resume. For a waiting checkpoint, enter a JSON response. For example, enter `true`, `42`, or a quoted string.
+
+After a service restart, reopen the original conversation and select the run with `/workflows`. Resume reconciles its existing sessions before scheduling more work. It does not assume that an interrupted write left the directory unchanged.
+
+For an uncertain write, ask the agent to inspect the retained worker and directory. Send the resolution request to that same worker. After the worker reports and finishes, resume the run. Use the [recovery contract](../skills/workflow-authoring/references/runtime.md#start-and-control) for crash and legacy-journal limits.
+
+## Save a useful workflow
+
+1. Select its run in `/workflows`.
+2. Press `s`.
+3. Enter a new name.
+4. Select **Project** or **User**.
+
+The saved file contains the script. Run arguments and worker conversations stay in the original run. Existing files are not overwritten.
+
+Invoke `/workflow-<name>` to reuse the script with new input. Project scripts live in `.opencode/workflows/`. Personal scripts live in the `workflows/` directory under your OpenCode configuration.
+
+An edited script starts a new run. A run's script and arguments remain fixed so resuming it cannot silently reuse results from different instructions.
+
+After editing a saved file directly, run `/workflow-refresh` to reload its command. The names `run` and `refresh` are reserved.
+
+## Use VERA roles
+
+Ask for VERA when the task needs its engineering and evidence rules. The workflow chooses configured role IDs such as `vera-engineer` and `vera-auditor-readonly`; `/setup-vera` remains the place to change their models.
+
+Keep an implementation and its runtime verification on the same retained worktree. Give the auditor the changed paths and verification evidence. The root conversation inspects the artifacts and owns integration and the final verdict.
+
+For script syntax, limits, tools, and recovery semantics, read the [runtime contract](../skills/workflow-authoring/references/runtime.md). The [implementation plan](dynamic-workflows-plan.md) describes module ownership and verification requirements.

package/index.ts

@@ -3,6 +3,7 @@ import type { SessionContext } from "@opencode/plugin/promise/session";
 import { z } from "zod";
 import { Report, ThreadsRpc, WorkerView } from "./src/rpc";
 import { Send, Spawn, WorkerTarget, threads } from "./src/threads";
+import { workflows } from "./src/workflows";
 
 export default Plugin.define({
   id: "op-threads",
@@ -121,5 +122,6 @@ export default Plugin.define({
         },
       });
     });
+    return workflows(ctx, workers, models, limit);
   },
 });

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@op1/threads",
-  "version": "0.1.7",
-  "description": "Visible top-level worker sessions for OpenCode V2, with native tabs and durable reports.",
+  "version": "0.2.0",
+  "description": "Visible worker sessions and durable dynamic workflows for OpenCode V2.",
   "type": "module",
   "main": "./index.ts",
   "exports": {
     ".": "./index.ts",
     "./tui": "./tui.ts"
   },
-  "files": ["index.ts", "tui.ts", "src/", "skills/"],
+  "files": ["index.ts", "tui.ts", "src/", "skills/", "docs/workflows.md", "docs/workflows-verification.md", "docs/workflow-capacity-findings.md", "docs/dynamic-workflows-plan.md"],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/opzero1/threads.git"
@@ -27,19 +27,35 @@
     "verify:live": "uv run --with pyte python scripts/verify-live.py",
     "verify:roles": "python3 scripts/verify-roles.py",
     "verify:idle-tabs": "uv run --with pyte python scripts/verify-idle-tabs.py",
-    "verify:tabs": "uv run --with pyte python scripts/verify-tab-groups.py"
+    "verify:tabs": "uv run --with pyte python scripts/verify-tab-groups.py",
+    "verify:activity": "uv run --with pyte python scripts/verify-activity.py",
+    "verify:workflows": "uv run --with pyte python scripts/verify-workflows.py",
+    "verify:workflow-regressions": "python3 scripts/verify-workflow-regressions.py",
+    "verify:workflow-capacity": "python3 scripts/verify-workflow-capacity.py",
+    "verify:workflow-runtime": "bun scripts/verify-workflow-runtime.ts"
   },
   "dependencies": {
+    "@opencode/codemode": "2.0.12",
     "@opencode/plugin": "2.0.7",
     "@opencode/schema": "2.0.7",
+    "acorn": "8.15.0",
+    "ajv": "8.17.1",
+    "effect": "4.0.0-rc.112",
+    "fuzzysort": "3.1.0",
     "zod": "4.1.8"
   },
   "peerDependencies": {
+    "@opentui/core": "0.5.10",
+    "@opentui/solid": "0.5.10",
     "solid-js": ">=1.9.0"
   },
   "devDependencies": {
+    "@opencode/theme": "2.0.12",
+    "@opentui/core": "0.5.10",
+    "@opentui/solid": "0.5.10",
     "@types/bun": "1.4.0",
-    "solid-js": "1.9.9",
+    "opentui-spinner": "0.0.7",
+    "solid-js": "1.9.12",
     "typescript": "5.9.3"
   }
 }

package/skills/workflow-authoring/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: Workflow authoring
+description: Author and run durable dynamic JavaScript workflows in OpenCode with parallel agents, structured handoffs, and resumable progress.
+---
+
+# Workflow authoring
+
+Use a workflow for broad independent work or a pipeline whose later steps consume earlier results. Keep small, tightly coupled tasks with one owner.
+
+1. Define the result, named slices, and verification predicate. For VERA tasks, retain the selected protocol and role profiles.
+2. Read [the runtime contract](references/runtime.md). Write a script with a literal `export const meta` first, named agent steps, and a final JSON result.
+3. Call `workflows_start` with a unique task key, `script` or saved `name`, JSON `args`, and the smallest useful concurrency and agent limit. It returns immediately.
+4. Continue independent work. The runner delivers a final notification. Use `workflows_inspect` for evidence and `workflows_control` for pause, stop, resume, and checkpoint responses. Never infer success from an idle worker.
+5. Inspect the result and the affected artifacts before giving the final verdict. Save a useful script with `workflows_save`; its arguments and transcripts are not saved with it.
+
+Every step selects an actual configured `agent`. Use `vera-operator-readonly` for discovery, `vera-engineer` for implementation, and `vera-auditor-readonly` for independent review. Model choices remain in the profiles. Workflow workers are leaves. The runner bounds the complete run, including nested workflows.
+
+Use `access: "read"` for investigations. It denies edits and shell commands. Real command-based verification needs a suitably permitted worker with `access: "write"`, even when its intended task is only running tests. Use `isolation: "worktree"` for independent implementations and return the retained directory and changed paths. Give subsequent verification the same directory. The root owns integration.
+
+Verification evidence is part of the handoff. `FAIL` and `INCONCLUSIVE` cannot establish a passing step. Do not replace execution evidence with reviewer votes. A workflow does not expand the user's authorization for external actions.
+
+## Example
+
+```javascript
+export const meta = {
+  name: "module-audit",
+  description: "Audit named modules and return source-backed findings",
+};
+
+await phase("Audit");
+const findings = await pipeline(args.modules, module => agent(
+  `Audit ${module} for ${args.check}. Read the actual source. Return concrete findings with paths and line numbers.`,
+  {
+    key: `audit:${module}`,
+    agent: "vera-engineer-readonly",
+    access: "read",
+    schema: {
+      type: "object",
+      properties: { findings: { type: "array", items: { type: "string" } } },
+      required: ["findings"],
+      additionalProperties: false,
+    },
+  },
+));
+return findings;
+```
+
+Invoke with structured arguments, for example `args: { modules: ["src/auth", "src/billing"], check: "missing authorization checks" }`. Set `maxAgents` to cover the named slices and any verification steps. Built-in defaults are four total agents and three concurrent agents; plugin options can override them. The `workflows_start` schema shows the configured defaults.
+
+The example returns candidate findings. Add an independent confirmation stage when the task requires a verified report.