@codions/portta 0.1.0 → 0.2.0

package/dist/runtime/.env.example

@@ -234,12 +234,6 @@ PORTTA_RUNTIME_DOCS=true
 # always available.
 PORTTA_RUNTIME_API_DOCS=
 
-# The MCP tools over HTTP, at POST /api/mcp, for an agent that has no CLI where
-# it runs (a Dev Container, a remote worktree, a cloud runner). The same tools
-# `portta mcp` serves, behind the same credential and the same agent ceiling.
-# Off by default: it is reachable from wherever the panel is.
-PORTTA_MCP_HTTP=false
-
 # Panel persistence: one SQLite file under this installation, at
 # `state/panel/portta.db`. There is nothing to configure, no password to
 # generate and no service to start — the file is created on first open
@@ -313,25 +307,12 @@ PORTTA_APPLY=true
 # See docs/development/adr/0030-the-panel-and-a-project-lifecycle.md.
 PORTTA_RUNNER=true
 
-# ----------------------------------------------------------------------------
-# The host daemon
-# ----------------------------------------------------------------------------
-# Work that needs the host -- issues through `gh` and Linear, and Taskflow's
-# git worktrees, tmux and agent CLIs -- runs in `portta host serve`, a daemon on
-# the host. Whenever the panel is on, it gets a name for the host and the
-# daemon's token (state/host/token), read-only, and reaches the daemon through
-# an authorised proxy.
-#
-# The daemon binds loopback by default, which a panel container reaches on
-# Docker Desktop. On Linux, bind it to the Docker bridge gateway instead, for
-# example PORTTA_HOST_BIND=172.17.0.1, and never to 0.0.0.0.
-# See docs/product/guides/host-daemon.md.
-PORTTA_HOST_BIND=127.0.0.1
-PORTTA_HOST_PORT=5111
-
-# Where the panel reaches the daemon. Empty means http://host.docker.internal on
-# PORTTA_HOST_PORT.
-PORTTA_HOST_URL=
+# On a public host (PORTTA_PROFILE=remote-public) the runner stays off the panel
+# unless this is true AND the panel is on its own domain (PORTTA_WEB_EXPOSE=domain),
+# sign-in is required (PORTTA_AUTH_MODE=required) and TLS is on (TLS_ENABLED=true).
+# Like PORTTA_RUNNER it is absent from the Settings catalogue: only an edit on the
+# host can change it, so a panel cannot release itself.
+# PORTTA_RUNNER_PUBLIC=true
 
 # ----------------------------------------------------------------------------
 # TLS
@@ -422,23 +403,6 @@ CLOUDFLARE_ENABLED=false
 CF_DNS_API_TOKEN=
 CLOUDFLARE_ZONE=
 
-# ----------------------------------------------------------------------------
-# Issues: GitHub through `gh`, and Linear
-# ----------------------------------------------------------------------------
-# Nothing is configured here, and that is the point.
-#
-# The panel reads and writes issues through the host daemon, which runs the
-# GitHub CLI as whoever is signed in on the host — so the credential is `gh
-# auth`'s, kept where `gh` keeps it, and never in this file or in the panel's
-# container (docs/development/adr/0018-github-issues-through-the-gh-cli.md).
-#
-#   gh auth login            once, on the host
-#   portta host serve        the daemon the panel reaches it through
-#
-# Linear is optional and works the same way: export LINEAR_API_KEY in the
-# environment that runs `portta host serve`. It is deliberately not a variable
-# here, because this file is one the panel itself can write.
-
 # ----------------------------------------------------------------------------
 # Cloudflare Tunnel: optional connector (credential stays in state/cloudflared)
 # ----------------------------------------------------------------------------

package/dist/runtime/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

package/dist/runtime/docker/compose/features/web-dev.yaml

@@ -30,7 +30,6 @@ services:
       - ./apps/web/app:/app/apps/web/app
       - ./apps/web/components:/app/apps/web/components
       - ./apps/web/lib:/app/apps/web/lib
-      - ./apps/web/modules:/app/apps/web/modules
       - ./apps/web/messages:/app/apps/web/messages
       - ./apps/web/server:/app/apps/web/server
       - ./apps/web/public:/app/apps/web/public
@@ -39,7 +38,6 @@ services:
       # services and API.
       - ./packages/core/src:/app/packages/core/src
       - ./packages/contracts/src:/app/packages/contracts/src
-      - ./packages/mcp/src:/app/packages/mcp/src
       - ./packages/auth/src:/app/packages/auth/src
       - ./packages/db/src:/app/packages/db/src
       # The generated migrations the process applies on the next migrate.

package/dist/runtime/docker/compose/features/web.yaml

@@ -136,9 +136,6 @@ services:
       # while the panel stays on loopback.
       PORTTA_RUNTIME_DOCS: ${PORTTA_RUNTIME_DOCS:-true}
       PORTTA_RUNTIME_API_DOCS: ${PORTTA_RUNTIME_API_DOCS:-}
-      # The MCP tools over HTTP at /api/mcp, off unless the operator turned
-      # them on: the endpoint follows the panel's own exposure.
-      PORTTA_MCP_HTTP: ${PORTTA_MCP_HTTP:-false}
       # The resolved gateway configuration, so the panel and the CLI always
       # describe the same gateway.
       PORTTA_PROFILE: ${PORTTA_PROFILE:-local}
@@ -201,7 +198,6 @@ services:
       PORTTA_RUNTIME_AUTH_STORE: /app/state/auth/protections.json
       PORTTA_RUNTIME_RUNNER_DIR: /app/state/runner
       PORTTA_RUNTIME_ACCESS_DIR: /app/state/access
-      PORTTA_RUNTIME_SSH_DIR: /app/state/ssh
       PORTTA_PANEL_ADVERTISED_HOST: ${PORTTA_PANEL_ADVERTISED_HOST:-}
       TLS_ENABLED: ${TLS_ENABLED:-false}
       TLS_MODE: ${TLS_MODE:-local}
@@ -220,14 +216,12 @@ services:
       # mounted here: see docs/development/adr/0001-decoupled-infrastructure.md.
       #
       #   .env             the configuration the Settings page edits
-      #   state/git        metadata `portta repos scan` collected, read-only
       #   state/metrics    current.json + history from `portta host watch`
       #   state/environment host readiness report from the same collector
       #   state/runner     the `{ verb, project }` request the runner reads
       #   state/access     tunnel records cleaned when a project is removed
       #   state/panel      the panel's SQLite database, read-write and its own
       #   state/auth       credentials the panel manages, never served directly
-      #   state/ssh        SSH credentials the panel manages, never served directly
       #   traefik/dynamic  read-write, and the ONE place the panel configures
       #                    Traefik. It may write three generated filenames there
       #                    and refuses every other path in its own process.
@@ -235,7 +229,6 @@ services:
       - ./.env:/app/state/.env
       - ./.env.example:/app/state/.env.example:ro
       - ./.env-lock:/app/state/.env-lock
-      - ./state/git:/app/state/git:ro
       - ./state/metrics:/app/state/metrics:ro
       - ./state/environment:/app/state/environment:ro
       - ./state/runner:/app/state/runner
@@ -246,7 +239,6 @@ services:
       # container, which is how a restart loses the most recent writes.
       - ./state/panel:/app/state/panel
       - ./state/auth:/app/state/auth
-      - ./state/ssh:/app/state/ssh
       - ./config/traefik/dynamic:/app/state/traefik-dynamic
       # The Cloudflare Tunnel connector's generated config and its credential.
       # Read-write because setting the tunnel up is something the panel is asked

package/dist/runtime/templates/README.md

@@ -1,15 +1,15 @@
 # Templates
 
 Reference overlays for the shapes a project usually has, for **manual mode**:
-a project that owns its own `compose.portta.yaml` instead of the overlay
+a project that writes its own overlay instead of the one
 `portta adopt` generates (see
 [Add an existing project](../docs/product/guides/adopting-projects.md#manual-mode)).
 They are **references to copy from**, not runtime that projects depend on:
 nothing here is included, mounted or extended by a consumer project. Copy the
 closest one, adjust the service names and ports, and it is yours.
 
-`portta envs init <path>` generates the same thing from a project's actual
-Compose file, which is usually faster.
+`portta adopt <path> --dry-run` prints the plan Portta would generate from a
+project's actual Compose file, which is usually faster.
 
 | Template | Shape |
 |---|---|

package/dist/runtime/templates/overlays/06-monorepo.yaml

@@ -29,13 +29,6 @@ services:
   web:
     networks: [default, portta]
     labels:
-      # Optional, and only useful because inference cannot get them right here:
-      # `portta.git.root` says where the repository actually starts when
-      # the Compose file is not at its root, and `portta.repo` gives the
-      # panel a repository link with no host-side Git at all. Delete both and
-      # everything behaves exactly as it does now.
-      # - "portta.repo=owner/monorepo"
-      # - "portta.git.root=/srv/dev/monorepo"
       - "traefik.enable=true"
       - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
       - "traefik.http.services.${COMPOSE_PROJECT_NAME}-web.loadbalancer.server.port=3000"

package/dist/runtime/templates/overlays/07-worktree.env

@@ -36,7 +36,6 @@ PORTTA_NETWORK=portta
 #
 #   labels:
 #     - "portta.project=base-empresarial"
-#     - "portta.repo=owner/base-empresarial"
 
 # ---------------------------------------------------------------------------
 # What must NOT be shared with the other worktree

package/dist/runtime/templates/project/PORTTA.md

@@ -2,24 +2,25 @@
 
 > Copy this file into the project and adjust the names. It covers only what
 > someone working on *this* project needs. The rules themselves live in the
-> Portta repository, which stays the single source of truth.
+> source repository of Portta, which stays the single source of truth.
 
 ## Prerequisites
 
 Portta must be running on this machine:
 
 ```bash
-portta status      # if this fails: portta bootstrap && portta up local
+portta status      # if this fails: portta setup
 ```
 
 ## Starting
 
 ```bash
-docker compose -f compose.yaml -f compose.portta.yaml up -d
+portta adopt .            # once: records the plan outside this repository
+portta runtime up .
 ```
 
-Set `COMPOSE_FILE=compose.yaml:compose.portta.yaml` in `.env` to drop the
-`-f` flags.
+Portta keeps the generated overlay with its own state, so this repository has
+no `compose.portta.yaml` and its Compose file is never edited.
 
 ## Namespace
 
@@ -73,8 +74,8 @@ Credentials are this project's, from its own `.env`.
 ```bash
 git worktree add --relative-paths ../<project>-issue59 issue59
 cd ../<project>-issue59
-echo "COMPOSE_PROJECT_NAME=<project>-issue59" >> .env
-docker compose -f compose.yaml -f compose.portta.yaml up -d
+portta adopt .            # the branch gives it its own namespace and URL
+portta runtime up .
 # -> http://<project>-issue59-web.localhost
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codions/portta",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Machine-first CLI for a shared Docker development gateway",
   "keywords": [
     "docker",
@@ -9,8 +9,7 @@
     "development",
     "gateway",
     "devcontainer",
-    "reverse-proxy",
-    "mcp"
+    "reverse-proxy"
   ],
   "license": "MIT",
   "type": "module",
@@ -42,30 +41,20 @@
   "homepage": "https://github.com/codions-labs/portta#readme",
   "bugs": "https://github.com/codions-labs/portta/issues",
   "dependencies": {
-    "@agentclientprotocol/claude-agent-acp": "^0.76.0",
-    "@agentclientprotocol/codex-acp": "^1.11.0",
-    "@anthropic-ai/claude-agent-sdk": "^0.3.163",
     "@clack/prompts": "^1.1.0",
-    "@devcontainers/cli": "0.89.0",
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "better-sqlite3": "^12.11.1",
     "commander": "14.0.2",
     "execa": "9.6.1",
-    "pi-acp": "^0.0.33",
     "systeminformation": "^5.33.8",
-    "ws": "8.19.0",
     "yaml": "^2.8.2",
-    "zod": "4.5.4"
+    "zod": "4.6.7"
   },
   "devDependencies": {
     "@types/node": "24.13.3",
     "esbuild": "0.28.2",
     "portta-contracts": "0.1.0",
     "portta-core": "0.1.0",
-    "portta-host": "0.1.0",
-    "portta-mcp": "0.1.0",
     "typescript": "7.0.2",
-    "vitest": "4.1.11",
+    "vitest": "4.1.12",
     "tsx": "4.23.13"
   }
 }

package/dist/acp-providers-M3DUUBYJ.js

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-import { createRequire as __createRequire } from "node:module"; const require = __createRequire(import.meta.url);
-import{a,b,c}from"./chunk-QBKADN76.js";import"./chunk-EFZZFIRZ.js";import"./chunk-6J5HN4ZN.js";export{a as BUILTIN_ACP_PROVIDERS,c as availableProviders,b as resolveAcpProviders};

package/dist/arktype-aI7TBD0R-SOJGD3SZ.js

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-import { createRequire as __createRequire } from "node:module"; const require = __createRequire(import.meta.url);
-import{a as e}from"./chunk-6J5HN4ZN.js";function t(){return(n,o)=>n.toJsonSchema(o)}e(t,"getToJsonSchemaFn");export{t as default};

package/dist/assets/skills/portta-workflows/SKILL.md

@@ -1,285 +0,0 @@
----
-name: portta-workflows
-description: Author and run custom multi-agent workflows with Taskflow — JavaScript files that orchestrate Codex, Claude Code, OpenCode, and Pi agents deterministically via agent()/parallel()/pipeline()/phase(). Use when a task should be decomposed across agents, independently verified, resumed durably, or managed as a reusable project workflow.
-license: MIT
-compatibility: Requires the portta CLI and at least one agent CLI (Codex, Claude Code, OpenCode or Pi).
-metadata:
-  author: codions-labs
-  version: "1"
----
-
-# Taskflow workflows
-
-Create custom workflows in `<project>/.portta/workflows/`. `portta flow workflows list` shows the project catalog; `portta flow run workflow <workflow-id>` starts a durable Taskflow Run that can be observed in the dashboard and resumed with `portta flow runs resume <run-id>`. Each `agent()` call spawns a real **Codex**, **Claude Code**, **OpenCode**, or **Pi** agent — you pick the provider per call.
-
-A workflow structures work across many agents — to be comprehensive (decompose and cover in parallel), to be confident (independent perspectives and adversarial checks before committing), or to take on scale one context can't hold (migrations, audits, broad sweeps). The file is where you encode that structure: what fans out, what verifies, what synthesizes.
-
-When you write one, the right move is often **hybrid**: scout first (list the files, find the channels, scope the diff) to discover the work-list, then write a workflow to pipeline over it. You don't need to know the shape before the *task* — only before the *orchestration step*.
-
-Common single-phase workflows you can chain across runs:
-- **Understand** — parallel readers over relevant subsystems → structured map
-- **Design** — judge panel of N independent approaches → scored synthesis
-- **Review** — dimensions → find → adversarially verify (example below)
-- **Research** — multi-modal sweep → deep-read → synthesize
-- **Migrate** — discover sites → transform each (workspace isolation) → verify
-
-For larger work, run several in sequence — read each result before deciding the next phase. You stay in the loop; each workflow is one well-scoped fan-out.
-
-Every script must begin with `export const meta = {...}`:
-```js
-export const meta = {
-  name: 'find-flaky-tests',
-  description: 'Find flaky tests and propose fixes',   // one-line summary
-  phases: [                                            // one entry per phase() call
-    { title: 'Scan', detail: 'grep test logs for retries' },
-    { title: 'Fix', detail: 'one agent per flaky test' },
-  ],
-}
-// script body starts here — use agent()/parallel()/pipeline()/phase()/log()
-phase('Scan')
-const flaky = await agent('grep CI logs for retry markers', { schema: FLAKY_SCHEMA })
-// ...
-```
-
-The `meta` object must be a PURE LITERAL — no variables, function calls, spreads, or template interpolation. Required fields: `name`, `description`. Optional fields: `phases`, `defaultProvider` with `defaultModel`, `defaultSandbox`, `whenToUse`, and `workspace`. Use the SAME phase titles in `meta.phases` as in `phase()` calls — titles are matched exactly; a `phase()` call with no matching meta entry just gets its own progress group.
-
-Script body hooks:
-- agent(prompt: string, opts?: {provider?: 'codex' | 'claude-code' | 'opencode' | 'pi', model?: string, effort?: string, schema?: object, label?: string, phase?: string, sandbox?: 'read-only' | 'workspace-write' | 'danger-full-access', approval?: 'never' | 'on-request', cwd?: string, instructions?: string, maxTurns?: number, worktree?: boolean | string, key?: string}): Promise<any> — spawn an agent. Without schema, returns its final text as a string. With schema (a JSON Schema), the agent is forced to return JSON matching it and `agent()` returns the validated object — no parsing needed. Returns null if the user skips the agent mid-run (filter with `.filter(Boolean)`). `opts.provider` / `opts.model`: **default to omitting both** — the agent inherits the provider and model the workflow is being run with, which is almost always correct. Only set them when the user explicitly asks for a specific provider/model, or you're highly confident a particular step needs a different one — and then set them **together**: provider and model are both-or-neither. `opts.label` overrides the display label. `opts.phase` assigns one call to a named phase without changing the ambient phase. `opts.sandbox` defaults to `read-only`; use `workspace-write` only when the agent must write. `opts.worktree` requests an isolated child workspace: in a durable Taskflow Run this is a Taskflow-managed fork lease; in a standalone workflow run it is an engine-managed git worktree. Use it only when parallel agents mutate files and would otherwise conflict. `opts.key` is a stable resume pin that survives prompt-wording/reordering edits.
-- pipeline(items, stage1, stage2, ...): Promise<any[]> — run each item through all stages independently, NO barrier between stages. Item A can be in stage 3 while item B is still in stage 1. This is the DEFAULT for multi-stage work. Wall-clock = slowest single-item chain, not sum-of-slowest-per-stage. Every stage callback receives `(prevResult, originalItem, index)` — use originalItem/index in later stages to label work without threading context through stage 1's return value. A stage that throws drops that item to `null` and skips its remaining stages.
-- parallel(thunks: Array<() => Promise<any>>): Promise<any[]> — run tasks concurrently. This is a BARRIER: awaits all thunks before returning. A thunk that throws (or whose agent errors) resolves to `null` in the result array — the call itself never rejects, so `.filter(Boolean)` before using the results. Use ONLY when you genuinely need all results together.
-- log(message: string): void — emit a progress message to the user (shown as a narrator line above the progress tree)
-- phase(title: string): void — start a new phase; subsequent `agent()` calls are grouped under this title in the progress display
-- args: any — the workflow input. Durable Taskflow Runs receive it from `--input` / `--input-json`; standalone runs receive it from `--args` / `--args-file`. Use this to parameterize a workflow — e.g. pass a research question, target path, or config object.
-- budget: {total: number|null, spent(): number, remaining(): number} — the run's output-token target, set with `--budget N` for standalone runs. `budget.total` is null if no target was set. `budget.spent()` returns output tokens spent this run. `budget.remaining()` returns `max(0, total - spent())`, or `Infinity` if no target. The target is a HARD ceiling, not advisory: once `spent()` reaches `total`, further `agent()` calls throw. Use for dynamic loops: `while (budget.total && budget.remaining() > 50_000) { ... }`, or static scaling: `const FLEET = budget.total ? Math.floor(budget.total / 100_000) : 5`.
-- now(): number / random(): number — journal-seeded deterministic time/RNG. Use these instead of `Date.now()`/`Math.random()` (which throw — see below).
-
-Agents are told their final text IS the return value (not a human-facing message), so they return raw data. For structured output, use the schema option — validation happens at the worker layer and the agent retries once on a mismatch.
-
-## Providers
-
-Every `agent()` runs under a provider/model. **By default, do NOT set `provider` or `model` per agent** — each agent inherits the provider/model the workflow is being run with, which is almost always what you want. Most workflows (including the canonical example and the patterns above) omit them entirely. Pin them only when the user explicitly asks for a specific provider/model, or you're confident a particular step needs a different one.
-
-**Provider and model are both-or-neither** — at every site (per-call opts, `meta.defaultProvider`/`defaultModel`, standalone `--provider`/`--model`): set both, or omit both to inherit the run defaults. A lone `provider:` (or lone `model:`) is rejected before the agent spawns. This exists because a lone provider override could inherit a model belonging to a *different* provider. When you pin a provider, name the model explicitly. `portta flow workflows doctor` shows which providers are installed/authenticated.
-
-The four providers:
-- **codex** (OpenAI) — the default. `opts.effort` tunes reasoning depth: `"none" | "minimal" | "low" | "medium" | "high" | "xhigh"`. Requires the `codex` CLI authenticated (ChatGPT login); its built-in tools come from that auth, and it ignores `OPENAI_API_KEY`. Native structured output uses a free-form working turn followed by a schema-constrained extraction turn.
-- **claude-code** (Anthropic) — via the Claude Agent SDK; requires the `claude` CLI / SDK available. `opts.effort` accepts `"low" | "medium" | "high" | "xhigh" | "max"` (`max` is Opus-tier; the model silently downgrades unsupported levels). Structured output is delivered on the final result only (intermediate messages stay free-form).
-- **opencode** (OpenCode CLI ≥ 1.16.2) — spawn-per-call subprocess backend. `model` is an open `provider/model` string routed by OpenCode, required whenever `provider: "opencode"` is set. **Requires `sandbox: "danger-full-access"`** — OpenCode has no enforceable confinement, so the default `read-only` sandbox is rejected. `effort` maps directly to OpenCode's provider-specific `--variant` flag. `maxTurns` is rejected. Structured output uses a silent extraction turn that reuses the working session.
-- **pi** (`@earendil-works/pi-coding-agent` ≥ 0.79.1) — spawn-per-call subprocess backend. `model` is an open Pi model reference. **Requires `sandbox: "danger-full-access"`** — Pi's tool allowlists are not OS confinement, so `read-only`/`workspace-write` are rejected. `effort` maps onto Pi's full thinking range (`none`→off … `max`→xhigh); `maxTurns` is rejected. Structured output uses a silent tool-less extraction turn.
-
-(`opts.effort` is a single union — `"none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"` — and each worker maps to its nearest supported level: `minimal`→`low` on Claude, `max`→`xhigh` on Codex/Pi. OpenCode passes the value through as `--variant`.)
-
-Codex and Claude Code honor every `sandbox` mode (read-only by default); **OpenCode and Pi are full-access-only** — every call on them needs an explicit `sandbox: "danger-full-access"` (per call or via the standalone `--sandbox`), a deliberate fail-closed choice because neither CLI can honestly enforce confinement. All providers honor `cwd`; `worktree` isolates parallel file edits regardless of provider. Outdated OpenCode/Pi binaries are refused at runtime (`provider_outdated`); `portta flow workflows doctor` flags them up front.
-
-The default case — omit provider, so fan-out and synthesis run on the workflow's selected provider:
-```js
-const findings = await parallel(AREAS.map(area => () =>
-  agent(`Inspect ${area} and list concrete issues.`, { schema: FINDINGS_SCHEMA })))
-const report = await agent(`Synthesize into a prioritized report:\n${JSON.stringify(findings.filter(Boolean), null, 2)}`)
-return report
-```
-Pin a provider only when you mean to — e.g. a deliberate cross-provider verify pass when the user has asked for that diversity:
-```js
-const verified = await pipeline(
-  suspects,
-  s => agent(`Is this a real bug? ${s.desc}`, { schema: VERDICT }),
-  (v, s) => agent(`Try to REFUTE that ${s.desc} is a bug; default to refuted if unsure.`,
-    { provider: "claude-code", model: "<claude-model>", schema: VERDICT }).then(r => ({ ...s, real: v.real && !r.refuted })))
-```
-
-Scripts are plain JavaScript, NOT TypeScript — type annotations (`: string[]`), interfaces, and generics fail to parse. The script body runs in an async context — use await directly. Standard JS built-ins (JSON, Math, Array, etc.) are available — EXCEPT `Date.now()`/`Math.random()`/argless `new Date()`, which throw (they would break resume) and are rejected by a submit-time lint; use the injected `now()`/`random()` instead, or pass timestamps in via `args`. No filesystem, network, or relative import/require in the workflow body (the agents do the I/O).
-
-DEFAULT TO `pipeline()`. Only reach for a barrier (`parallel()` between stages) when you genuinely need ALL prior-stage results together.
-
-A barrier is correct ONLY when stage N needs cross-item context from all of stage N-1:
-- Dedup/merge across the full result set before expensive downstream work
-- Early-exit if the total count is zero ("0 bugs found → skip verification entirely")
-- Stage N's prompt references "the other findings" for comparison
-
-A barrier is NOT justified by:
-- "I need to flatten/map/filter first" — do it inside a pipeline stage: `pipeline(items, stageA, r => transform([r]).flat(), stageB)`
-- "The stages are conceptually separate" — that's what `pipeline()` models. Separate stages ≠ synchronized stages.
-- "It's cleaner code" — barrier latency is real. If 5 finders run and the slowest takes 3× the fastest, a barrier wastes 2/3 of the fast finders' idle time.
-
-Smell test: if you wrote
-```js
-const a = await parallel(...)
-const b = transform(a)        // flatten, map, filter — no cross-item dependency
-const c = await parallel(b.map(...))
-```
-that middle transform doesn't need the barrier. Rewrite as a pipeline with the transform inside a stage. When in doubt: pipeline.
-
-Concurrent `agent()` calls are capped at 100 per standalone workflow by default (override with `--concurrency N`) — excess calls queue and run as slots free up. You can pass more items than the cap to `parallel()`/`pipeline()` and they all complete; only up to the cap run at any moment. Total agent count across a workflow's lifetime is capped at 1000. A single `parallel()`/`pipeline()` call accepts at most 4096 items; passing more is an explicit error, not a silent truncation.
-
-The canonical multi-stage pattern — pipeline by default, each dimension verifies as soon as its review completes:
-```js
-export const meta = {
-  name: 'review-changes',
-  description: 'Review changed files across dimensions, verify each finding',
-  phases: [{ title: 'Review' }, { title: 'Verify' }],
-}
-const DIMENSIONS = [{ key: 'bugs', prompt: '...' }, { key: 'perf', prompt: '...' }]
-const results = await pipeline(
-  DIMENSIONS,
-  d => agent(d.prompt, { label: `review:${d.key}`, phase: 'Review', schema: FINDINGS_SCHEMA }),
-  review => parallel(review.findings.map(f => () =>
-    agent(`Adversarially verify: ${f.title}`, { label: `verify:${f.file}`, phase: 'Verify', schema: VERDICT_SCHEMA })
-      .then(v => ({ ...f, verdict: v }))
-  ))
-)
-const confirmed = results.flat().filter(Boolean).filter(f => f.verdict?.isReal)
-return { confirmed }
-// Dimension 'bugs' findings verify while dimension 'perf' is still reviewing. No wasted wall-clock.
-```
-
-When a barrier IS correct — dedup across all findings before expensive verification:
-```js
-const all = await parallel(DIMENSIONS.map(d => () => agent(d.prompt, { schema: FINDINGS_SCHEMA })))
-const deduped = dedupeByFileAndLine(all.filter(Boolean).flatMap(r => r.findings))
-const verified = await parallel(deduped.map(f => () => agent(verifyPrompt(f), { schema: VERDICT_SCHEMA })))
-```
-
-Loop-until-count pattern — accumulate to a target:
-```js
-const bugs = []
-while (bugs.length < 10) {
-  const result = await agent("Find bugs in this codebase.", { schema: BUGS_SCHEMA })
-  bugs.push(...result.bugs)
-  log(`${bugs.length}/10 found`)
-}
-```
-
-Loop-until-budget pattern — scale depth to `--budget`. Guard on `budget.total`: with no target set, `remaining()` is Infinity and the loop would run straight to the 1000-agent cap.
-```js
-const bugs = []
-while (budget.total && budget.remaining() > 50_000) {
-  const result = await agent("Find bugs in this codebase.", { schema: BUGS_SCHEMA })
-  bugs.push(...result.bugs)
-  log(`${bugs.length} found, ${Math.round(budget.remaining() / 1000)}k remaining`)
-}
-```
-
-Composing patterns — exhaustive review (find → dedup vs seen → diverse-lens panel → loop-until-dry):
-```js
-const seen = new Set(), confirmed = []
-let dry = 0
-while (dry < 2) {
-  const found = (await parallel(FINDERS.map(f => () =>
-    agent(f.prompt, { phase: 'Find', schema: BUGS })))).filter(Boolean).flatMap(r => r.bugs)
-  const fresh = found.filter(b => !seen.has(key(b)))
-  if (!fresh.length) { dry++; continue }
-  dry = 0; fresh.forEach(b => seen.add(key(b)))
-  const judged = await parallel(fresh.map(b => () =>
-    parallel(['correctness', 'security', 'repro'].map(lens => () =>
-      agent(`Judge "${b.desc}" via the ${lens} lens — real?`, { phase: 'Verify', schema: VERDICT })))
-      .then(vs => ({ b, real: vs.filter(Boolean).filter(v => v.real).length >= 2 }))))
-  confirmed.push(...judged.filter(v => v.real).map(v => v.b))
-}
-return confirmed
-// dedup vs `seen`, NOT `confirmed` — else judge-rejected findings reappear every round and it never converges.
-```
-
-Quality patterns — common shapes; pick by task and compose freely:
-- Adversarial verify: spawn N independent skeptics per finding, each prompted to REFUTE. Kill if ≥majority refute. Prevents plausible-but-wrong findings from surviving.
-  ```js
-  const votes = await parallel(Array.from({ length: 3 }, () => () =>
-    agent(`Try to refute: ${claim}. Default to refuted=true if uncertain.`, { schema: VERDICT })))
-  const survives = votes.filter(Boolean).filter(v => !v.refuted).length >= 2
-  ```
-- Perspective-diverse verify: when a finding can fail in more than one way, give each verifier a distinct lens (correctness, security, perf, does-it-reproduce) instead of N identical refuters — diversity catches failure modes redundancy can't.
-- Judge panel: generate N independent attempts from different angles (e.g. MVP-first, risk-first, user-first), score with parallel judges, synthesize from the winner while grafting the best ideas from runners-up. Beats one-attempt-iterated when the solution space is wide.
-- Loop-until-dry: for unknown-size discovery (bugs, issues, edge cases), keep spawning finders until K consecutive rounds return nothing new. Simple counters (`while count < N`) miss the tail.
-- Multi-modal sweep: parallel agents each searching a different way (by-container, by-content, by-entity, by-time). Each is blind to what the others surface; useful when one search angle won't find everything.
-- Completeness critic: a final agent that asks "what's missing — modality not run, claim unverified, source unread?" What it finds becomes the next round of work.
-- No silent caps: if a workflow bounds coverage (top-N, no-retry, sampling), `log()` what was dropped — silent truncation reads as "covered everything" when it didn't.
-
-Scale to what the user asked for. "find any bugs" → a few finders, single-vote verify. "thoroughly audit this" or "be comprehensive" → larger finder pool, 3–5 vote adversarial pass, synthesis stage. When unsure, lean toward thoroughness for research/review/audit requests and toward brevity for quick checks.
-
-These patterns aren't exhaustive — compose novel harnesses when the task calls for it (tournament brackets, self-repair loops, staged escalation, whatever fits).
-
-Use a workflow for multi-step orchestration where control flow should be deterministic (loops, conditionals, fan-out) rather than model-driven.
-
-## Workspaces
-
-`meta.workspace` declares the Run-level workspace policy:
-```js
-workspace: {
-  default: 'isolated_worktree',
-  allowed: ['isolated_worktree', 'new_branch', 'current_branch'],
-  mutatesRepository: true,
-  reason: 'Review agents may prepare fixes',
-}
-```
-
-Taskflow owns the lifecycle of Run workspaces. Select one at launch with `--workspace worktree|branch|current`; do not create or remove those worktrees manually. Use `agent(..., { worktree: true })` only for child agents that need isolated parallel writes. Taskflow grants each such execution a fork lease and releases the lease after the agent finishes, preserving changed branches for inspection.
-
-## Resume
-
-Every durable Taskflow Run has a run ID. `portta flow runs resume <run-id>` resumes an interrupted Run from its frozen workflow snapshot and original input. Completed agent calls replay from the durable journal while incomplete or failed calls run again. Stable `opts.key` values keep independently meaningful calls associated with their cached results across safe edits and reorderings.
-
-For a standalone workflow run, re-run the same file with `portta flow workflows run <file> --resume <run-id>` — the longest unchanged prefix of agent calls returns cached results instantly; the first edited/new call and everything after it runs live. Same file + same args gives a full cache hit. `Date.now()`/`Math.random()`/`new Date()` are unavailable in scripts because they would break this — use `now()`/`random()`, or pass timestamps via `args`.
-
-## CLI commands
-
-Durable Taskflow Runs:
-```
-portta flow workflows list
-portta flow run workflow <workflow-id> [--input <text> | --input-json <json>]
-                                           [--profile <name>]
-                                           [--workspace worktree|branch|current]
-                                           [--branch <name>] [--base <branch>]
-portta flow runs list
-portta flow runs show <run-id>
-portta flow runs cancel <run-id>
-portta flow runs resume <run-id>
-portta flow runs transcript <execution-id>
-```
-
-Authoring and standalone validation/execution:
-```
-portta flow workflows run <file.workflow.js | name> [--args '<json>' | --args-file <f>]
-                                       [--provider codex|claude-code|opencode|pi --model m] [--effort e]
-                                       [--sandbox read-only|workspace-write|danger-full-access] [--cwd dir]
-                                       [--concurrency N] [--budget N] [--resume <runId>] [--fake] [--json] [--open]
-portta flow workflows save <file.workflow.js> [--project] [--force]
-portta flow workflows validate <file.workflow.js | name>
-portta flow workflows doctor
-portta flow workflows guide
-```
-
-Use `portta flow workflows validate <file>` before adding or changing a catalog workflow. `--fake` runs with a fake worker for a fast smoke test; `--json` prints `{runId, status, url, result, error}`. A standalone `run` auto-starts its live viewer and prints the URL; `--open` also opens it in a browser.
-
-## Saved / named workflows
-
-Workflow IDs come from **`meta.name`**, not the filename. The durable Taskflow catalog resolves across three tiers, highest precedence first: **project** (`<project>/.portta/workflows/`), **global** (`~/portta/state/host/workflows/`), and package **built-ins**. Place new workflows in Taskflow directories.
-
-Six built-ins ship with Taskflow. Two are ports of Claude Code's bundled workflows:
-- **`deep-research`** — scope → 5 parallel web searches → fetch/dedup top sources → 3-vote adversarial verification per claim → cited report.
-- **`code-review`** — one finder per review angle, an independent verifier per finding, a gap-sweep at high levels, ranked report.
-
-The other four are multi-provider workflows — designs where two models' decorrelated errors are the point:
-- **`multi-provider-review`** — Codex and Claude independently review the same target, then a synthesis agent merges consensus, unique catches, and disagreements.
-- **`bake-off`** — both providers implement the same task in isolated workspaces, blind judges score the diffs, and a tie-break settles splits.
-- **`provider-debate`** — one provider proposes, the other attacks, N rounds of rebuttal, then a judge rules.
-- **`second-opinion`** — both providers answer cheaply; disagreement triggers deeper passes and adjudication.
-
-## Running a workflow for a user (from an agent)
-
-When you (an agent such as Claude Code or Codex) create or run a workflow on a user's behalf:
-
-- Put reusable project workflows in `.portta/workflows/`, validate them, and confirm they appear in `portta flow workflows list` before starting a durable Run.
-- Prefer `portta flow run workflow <workflow-id>` for work the user should observe, cancel, inspect, or resume in Taskflow. Return the Run ID immediately and tell the user it is visible in the Taskflow dashboard; then inspect the final Run/result when it completes.
-- Use `portta flow workflows run <file> --fake --no-serve` for a cheap authoring smoke test. Use a real standalone run only when the user explicitly wants the standalone viewer or CLI-only execution.
-- For a real standalone run, background it in Claude Code or block on it in Codex unless the user specifies otherwise. Surface the printed viewer URL immediately so the user can watch live progress, then report the result when the workflow completes.
-
-## Installation
-
-Install with the [Skills CLI](https://www.skills.sh):
-
-```
-npx skills add codions-labs/portta --skill portta-workflows -g
-```
-
-It installs into Claude Code, Codex, OpenCode, Cursor, Zed and the other agents it supports, symlinking by default so an update reaches every agent at once. `npx skills update` refreshes it; `npx skills remove` takes it out.
-
-Pair it with `portta-method`, which carries the branching, worktree, commit and pull request rules this project follows.