@elie-laloum/outpost 1.1.0

package/docs/api.md

@@ -0,0 +1,147 @@
+# API reference
+
+## Domain and ownership
+
+`Workspace` owns a Git checkout and its lock. `Sandbox` owns a running environment attached to exactly one workspace. `dispatch` is one agent job, potentially containing several turns. `Task<T>` is one typed workflow node. A native conversation belongs to an agent and can outlive both workspace and sandbox.
+
+| Entry point              | Lifetime                                                                               |
+| ------------------------ | -------------------------------------------------------------------------------------- |
+| `dispatch(options)`      | Creates and closes its own sandbox; closes its workspace unless supplied.              |
+| `attach(options)`        | Opens a terminal session, synchronizes changes and closes owned resources.             |
+| `createSandbox(options)` | Returns a warm handle with `dispatch`, `resume`, `fork`, `attach`, `command`, `close`. |
+| `openWorkspace(options)` | Returns a workspace with `dispatch`, `sandbox`, `attach`, `integrate`, `close`.        |
+
+Sandbox and workspace handles implement `Symbol.asyncDispose` for `await using`. Explicit `close()` is supported and idempotent. Close the sandbox before closing a separately owned workspace. A warm sandbox rejects overlapping operations. Separate workspaces hold separate locks; automatic merges hold a host-branch merge lock.
+
+## WorkspaceOptions
+
+| Field              | Type / default                        | Meaning                                                    |
+| ------------------ | ------------------------------------- | ---------------------------------------------------------- |
+| `repository`       | `string`, current directory           | Repository root or a directory inside it.                  |
+| `branch`           | `BranchPolicy`, `{ mode: "current" }` | Checkout, named worktree, or temporary integration branch. |
+| `copies`           | `readonly string[]`                   | Repository-relative inputs copied before workspace hooks.  |
+| `limits.copyMs`    | `number`, 60000                       | Copy deadline.                                             |
+| `limits.gitMs`     | `number`, 30000                       | Git setup operation deadline.                              |
+| `limits.collectMs` | `number`, 30000                       | Commit collection deadline.                                |
+| `limits.mergeMs`   | `number`, 30000                       | Host merge deadline.                                       |
+
+Branch variants:
+
+```ts
+type BranchPolicy =
+  | { mode: "current" }
+  | { mode: "named"; name: string; from?: string }
+  | { mode: "integrate"; from?: string };
+```
+
+`from` accepts a Git commit-ish and is resolved before branch creation. An existing named branch is reused. Managed worktrees live under `.outpost/workspaces`. A branch checked out outside its managed location is not moved. Integration requires an attached host branch and never switches the host checkout. Dirty worktrees survive close; `close({ preserve: true })` also retains clean ones. Inspect the returned `retainedDirectory`.
+
+## SandboxOptions
+
+Includes `WorkspaceOptions`, plus:
+
+| Field              | Meaning                                                                                                                                         |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent`            | Default `AgentAdapter` for warm operations; optional on `createSandbox`, required on one-shot `dispatch`/`attach`. Use `codex()` or `claude()`. |
+| `provider`         | `SandboxProvider`; defaults to `docker()`.                                                                                                      |
+| `workspace`        | Existing workspace. Cannot be combined with `repository`, `branch` or `copies`.                                                                 |
+| `hooks`            | `workspaceReady`, `hostReady`, `sandboxReady` command arrays.                                                                                   |
+| `signal`           | Cancels provisioning. In one-shot calls, also cancels execution.                                                                                |
+| `logging`          | `false`, `"stdout"`, or `{ file?, verbose? }`; default generated JSONL file.                                                                    |
+| `bootstrap`        | Remote agent installation when absent; defaults to `true`.                                                                                      |
+| `conversationHome` | Host directory containing `.claude`/`.codex`; defaults to OS home.                                                                              |
+
+Hook order is copies → `workspaceReady` on host → provider acquisition/synchronization → concurrent `hostReady` and `sandboxReady`. Host commands run sequentially. Sandbox commands run concurrently. Failure aborts sibling hooks and waits for their cleanup. `openWorkspace({ hooks })` runs `workspaceReady` immediately and passes the remaining hooks to later sandboxes without repeating it. Commands may choose a directory, environment and timeout. Sandbox commands can request `elevated: true` on providers supporting elevation. Host execution does not elevate privileges.
+
+## DispatchOptions
+
+| Field          | Default / meaning                                                                             |
+| -------------- | --------------------------------------------------------------------------------------------- |
+| `brief`        | Required `{ text }` or `{ file, values? }`.                                                   |
+| `agent`        | Overrides the warm sandbox's default adapter for this job, including its model and variables. |
+| `logging`      | Overrides the sandbox's logging policy for this job.                                          |
+| `label`        | Optional label included in journal records and generated log filenames.                       |
+| `passes`       | Positive integer, default 1. Maximum agent turns when no response validator is supplied.      |
+| `until`        | String or strings; default `<outpost>done</outpost>`. Empty array disables markers.           |
+| `idleMs`       | 600000; maximum silence before completion. Any output refreshes it.                           |
+| `settleMs`     | 60000; grace period after completion, refreshed by output.                                    |
+| `deadlineMs`   | 3600000; hard deadline for each agent command.                                                |
+| `expansionMs`  | 30000; deadline for each embedded prompt command.                                             |
+| `signal`       | Cancels this operation, preserving a warm sandbox.                                            |
+| `continuation` | `{ id, fork? }`; native resume or conversation fork.                                          |
+| `response`     | A `ResponseSpec<T>` produced by `response.text/json`.                                         |
+| `observe`      | Receives normalized events; exceptions cannot fail the job.                                   |
+| `warn`         | Receives nonfatal warnings; exceptions cannot fail the job.                                   |
+
+Resume and structured output require `passes: 1`. A one-shot continuation validates the host transcript before allocating an environment. Warm continuations reuse sessions already present, otherwise importing the host transcript.
+
+`DispatchResult<T>` contains `text`, `value`, `turns`, `usage`, `completed`, optional `completion`, `conversation`, `transcript`, `log`, `branch`, `directory`, `commits`, optional `retainedDirectory`, and `resume`/`fork` methods. `value` is inferred from the response validator. Without a validator it is `undefined`. Usage contains raw `input`, `cached` (cache read), optional `cacheCreated` (cache creation) and `output` token counts. Claude transcript usage takes the final assistant message, independently from streamed totals. Costs are not estimated.
+
+Each turn contains `text`, `status`, `durationMs`, `usage`, and optional `conversation` and `transcript`. Commits contain their original `oid` and `subject`. A budget exhausted without a completion marker returns `completed: false`; process failures throw.
+
+## Agent settings
+
+```ts
+codex({
+  model: "your-model",
+  reasoning: "high",
+  approvalReviewer: "auto_review",
+  saveConversations: true,
+  variables: {},
+});
+
+claude({
+  model: "sonnet",
+  reasoning: "high",
+  permissions: "acceptEdits",
+  saveConversations: true,
+  variables: {},
+});
+```
+
+Model is optional; the installed CLI chooses its default. Codex reasoning accepts `low`, `medium`, `high`, `xhigh`. Claude also accepts `max`. Actual model support is determined by the CLI/provider. Claude permission modes are `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`.
+
+Noninteractive defaults avoid permission prompts because the outer sandbox is responsible for isolation. Codex can instead use the auto-review approval reviewer. Interactive commands use native terminal behavior and native session resume/fork commands.
+
+Events are a discriminated union with `kind`: `phase`, `prompt`, `text`, `result`, `tool`, `conversation`, `usage`, `summary`, `warning`, `failure`, `finished`, `raw`. Every public observation adds a one-based `pass` and ISO timestamp `at`. Protocol noise is retained as `raw`. Adapters implement `request(input): Command` and `events(line): AgentEvent[]`; a custom adapter can omit native conversation support.
+
+## Command and attachment
+
+```ts
+const result = await sandbox.command({
+  executable: "npm",
+  arguments: ["test"],
+  directory: "/workspace",
+  variables: { CI: "true" },
+  deadlineMs: 120_000,
+  retain: 65_536,
+  observe(channel, text) {
+    process.stdout.write(text);
+  },
+});
+```
+
+Arguments are passed directly, without implicit shell expansion. For shell syntax, explicitly invoke `sh -c` (inside Linux sandboxes) or the host shell. Default directory is the sandbox workspace. `stdin` supplies a string. `interactive` inherits terminal input/output by default; `terminal: { input?, output?, error? }` supplies caller-owned streams. Raw mode and cursor visibility are restored after attachment. `retain` bounds the captured tail of each stream; observers receive all output. `CommandResult` contains `status`, `stdout`, `stderr`.
+
+`attach({ agent?, brief?, continuation?, signal?, ask?, terminal? })` uses the adapter's terminal mode. Missing file-prompt variables are requested once per variable through the TTY or the optional async `ask(name)` callback. Existing values are preserved. Docker, Podman and host support attachment. Remote cloud adapters reject it explicitly. Both warm and one-shot results include commits, branch and workspace directory. The top-level result additionally returns disposal information.
+
+## Errors and recovery
+
+`OutpostError` has a machine-readable `code`, frozen `details`, `recovery`, and optional `cause`. `recoveryDetails(error)` retrieves recovery metadata for native errors and cancellation reasons as well, preserving their original identity. Codes: `configuration`, `process`, `timeout`, `aborted`, `workspace`, `conflict`, `prompt`, `response`, `session`, `provider`. Multiple failures can surface as `AggregateError` without losing the original causes.
+
+`ResponseError` adds `tag`, optional `raw` and `recovery`. Recovery records include the conversation and workspace; after collection they also include commits, transcript and log. Native main-transcript capture failure fails the dispatch. Child transcript capture errors only warn.
+
+Remote recovery directories contain Git bundles, binary patches and copied untracked files. A failed synchronization reports its recovery path. Do not delete it before inspecting the failure. See [Operations](operations.md).
+
+## Additional 1.1 contracts
+
+- `WorkspaceOptions.label` names generated branches and workspace directories; `hooks` and `signal` are available on standalone workspaces.
+- `SandboxOptions.includeUncommitted` explicitly seeds remote patches and untracked files; the default is committed history only.
+- `DispatchOptions.idleWarningMs` defaults to 60000; `diagnostic(message)` receives expansion-size estimates. Relative file briefs use the caller's cwd.
+- `AgentAdapter.resumable` declares repair capability. `storage?: ConversationStore` supplies locate/capture/restore; `transcriptUsage?(text)` extracts authoritative usage.
+- `conversations.native(format)` returns a store. Helpers include `locate`, `capture`, `restore`, `rewrite`, `projectKey`, `claudePath`, `directory` and `destination`.
+- Cold `DispatchResult.resume/fork` accepts `ContinuationOptions`, including a new branch, provider and lifecycle hooks. `WarmDispatchResult` accepts dispatch settings only.
+- `TransferOptions` contains optional `signal` and `deadlineMs`. `SandboxLease.upload/download` accept it as a third argument. Orchestration uses `limits.copyMs`, with a 120000 ms transfer default.
+- `reporter` renders observations with label, verbose, quiet and custom writer settings.
+- `campaign`, `CampaignOptions`, `CampaignResult`, `CampaignEvent`, `IssueOutcome`, `Issue`, `Assignment` and `Backlog` define issue delivery. See the [workflow guide](workflows.md#issue-campaigns).
+- `githubBacklog` and `beadsBacklog` accept `directory`, `label` and `deadlineMs`. Their commands receive declared project environment values.

package/docs/architecture.md

@@ -0,0 +1,21 @@
+# Architecture
+
+Outpost separates domain contracts from orchestration and infrastructure.
+
+| Layer                | Responsibility                                                                                                          |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `src/domain`         | Workspace policy, command/agent/provider ports, prompts, responses, workflow graph, issue/backlog contracts and errors. |
+| `src/application`    | Resource ownership, dispatch coordination, workflow task helpers, issue campaigns and remote synchronization.           |
+| `src/infrastructure` | Git, filesystem, native transcripts, process supervision, journals and shutdown cleanup.                                |
+| `src/providers`      | Claude/Codex protocols and Docker/Podman/host/Vercel/Daytona backends.                                                  |
+| `src/cli`            | Onboarding, starter templates and image lifecycle.                                                                      |
+
+The main boundaries are `AgentAdapter`, `ConversationStore`, `SandboxProvider`, `SandboxLease` and `Backlog`. An agent converts typed input into a command and normalizes protocol events. A provider owns allocation and release. The application owns synchronization and recovery. Cloud SDKs are optional imports isolated in their provider modules.
+
+Workspaces and sandboxes have distinct ownership. A separately acquired workspace can be passed through several agent environments. Promise-based exclusive operations avoid hidden queues or accidental overlap in one sandbox. Git lock files extend that protection across processes; stale process locks can be recovered.
+
+Workflows operate on typed task results rather than a global mutable context. Task identity determines value access. Results belong to one execution and cannot leak into a later run. Observer failures are separated from business outcomes.
+
+Prompt parsing records command fragments before substituting variables. This preserves command provenance. Native transcripts rewrite only structural `cwd` fields matching the source workspace without performing global string replacement on user messages. Remote transport preserves Git history instead of manufacturing new commits from a patch.
+
+Tests combine domain unit tests, deterministic provider contracts, real subprocess/Git functional tests and real container tests in CI. Tests requiring paid remote infrastructure are opt-in. Package smoke tests exercise the actual tarball outside the source checkout.

package/docs/migration-1.1.fr.md

@@ -0,0 +1,44 @@
+# Migrer vers la version 1.1
+
+La version 1.1 complète les campagnes par issue et corrige plusieurs contrats d’exécution. Voici les changements visibles depuis la version 1.0.
+
+| Domaine            | Comportement en 1.1                                                                                                                                                   |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Boucle ponctuelle  | Chaque passe de `dispatch` acquiert une nouvelle sandbox. Utilisez `createSandbox()` pour conserver un environnement entre les passes.                                |
+| Variables          | Seul `.outpost/.env` est lu. Une valeur non vide du fichier est prioritaire ; une déclaration vide reprend la valeur du processus.                                    |
+| Prompts            | Les chemins relatifs partent du répertoire de l’appelant, même lorsque `repository` désigne un autre dossier.                                                         |
+| Hooks              | `workspaceReady` intervient dès l’ouverture du workspace. Les hooks hôte sont séquentiels ; ceux de la sandbox sont concurrents.                                      |
+| Copies             | Une entrée absente est ignorée. Les autres erreurs de copie restent bloquantes.                                                                                       |
+| Cloud              | Les commits sont envoyés par défaut. `includeUncommitted: true` ajoute les modifications et fichiers non suivis. Les copies demandées explicitement sont transférées. |
+| Branche distante   | Sans politique explicite, un workspace d’intégration est créé.                                                                                                        |
+| Tokens Claude      | `input`, `cached` et `cacheCreated` distinguent entrée non cachée, lecture et création du cache.                                                                      |
+| Événements         | `pass` et `at` identifient chaque observation. Les lignes brutes accompagnent les événements normalisés.                                                              |
+| Journaux           | Un fichier explicite est complété sans écrasement. `logging: "stdout"` affiche une progression lisible.                                                               |
+| Reprise            | Un résultat ponctuel accepte une nouvelle branche, un fournisseur et des hooks. Un résultat chaud conserve sa sandbox.                                                |
+| Réponse structurée | La balise et la capacité de réparation sont validées avant allocation. Un bloc Markdown JSON peut apparaître dans la balise.                                          |
+
+Le marqueur par défaut reste `<outpost>done</outpost>`. Les adaptateurs natifs restent Codex et Claude Code.
+
+## Campagnes et starters
+
+`campaign` utilise `Backlog.list/get/close`, recharge les issues à chaque cycle et ne les ferme qu’après intégration des commits dans la branche hôte. Le connecteur GitHub pagine les résultats et applique son label. Beads doit être installé sur l’hôte ; sa recette de conteneur générée inclut aussi `bd`.
+
+Les paramètres du starter sont `cycles`, `concurrency`, `implementationPasses` et `reviewPasses`. `planner: false` traite les issues disponibles dans l’ordre ; `reviewer: false` désactive la revue. Les rôles `planner`, `reviewer` et `merger` acceptent des adaptateurs distincts pour choisir les modèles. Les règles de développement se trouvent dans `.outpost/STANDARDS.md`.
+
+Un échec d’implémentation est enregistré sans interrompre les issues indépendantes. Un cycle sans commit s’arrête. Un échec de fusion conserve le travail et ne ferme aucune issue concernée. Si la fermeture chez le tracker échoue après une fusion réussie, vérifiez son état avant de relancer la campagne.
+
+`init` ne remplace jamais les fichiers existants : adoptez le nouveau starter manuellement ou générez-le dans un autre dossier.
+
+## Diagnostic et récupération
+
+`recoveryDetails(error)` fournit les chemins, commits et journaux disponibles sans remplacer la raison d’annulation. Un échec de préparation nettoie le workspace s’il est propre ; le travail modifié et les artefacts d’une synchronisation échouée sont conservés. Les transferts réussis sont nettoyés à la fermeture.
+
+`reporter({ label, verbose, quiet, write })` produit un observateur lisible. `idleWarningMs` règle les avertissements d’inactivité ; `diagnostic` reçoit l’estimation de taille des expansions de prompt. Cette estimation n’est pas un compteur de facturation.
+
+## Extensions
+
+Un adaptateur peut fournir `storage: ConversationStore`, `resumable` et `transcriptUsage`. Le service `conversations` expose chemins, recherche, capture, restauration et réécriture sélective. Chaque tour expose son propre chemin `transcript`.
+
+Les transferts acceptent `{ signal, deadlineMs }` ; `limits.copyMs` borne leur attente. Un fournisseur personnalisé doit réellement respecter l’annulation pour empêcher des écritures tardives. `Command.terminal` accepte les flux de l’appelant et `attach.ask` complète les variables de prompt manquantes sans terminal interactif.
+
+La CI vérifie Linux, Windows, macOS, Docker et Podman. Les contrats Vercel/Daytona sont testés avec des doubles SDK. Une authentification modèle et des comptes cloud distincts restent nécessaires pour les essais réels correspondants.

package/docs/migration-1.1.md

@@ -0,0 +1,38 @@
+# Migrating to 1.1
+
+Version 1.1 completes the issue campaign layer and corrects execution contracts. Review these observable changes when upgrading from 1.0.
+
+| Area              | 1.1 behavior                                                                                                                                     |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Cold loops        | Each pass acquires a fresh sandbox. Use an explicit `createSandbox()` for warm multi-pass execution.                                             |
+| Environment       | Only `.outpost/.env` is loaded. Nonempty file values win; empty declarations inherit the process. Declare every key needed inside a sandbox.     |
+| Prompt files      | Relative paths resolve from the caller's working directory, even if `repository` points elsewhere.                                               |
+| Hooks             | `workspaceReady` runs at workspace creation. Host hooks are sequential; sandbox hooks run concurrently.                                          |
+| Optional inputs   | Missing `copies` entries are skipped. Other copy errors still fail.                                                                              |
+| Remote input      | Only commits are seeded by default. `includeUncommitted: true` opts into patch/untracked transfer. Selected `copies` are always explicit inputs. |
+| Remote default    | An omitted branch policy creates an integration workspace.                                                                                       |
+| Claude usage      | `input` contains uncached input; `cached` and `cacheCreated` remain separate counters.                                                           |
+| Observations      | Every public event has `pass` and `at`. Raw lines accompany normalized events. New phase, summary, result and warning events are available.      |
+| Journals          | Explicit files append across runs. `logging: "stdout"` renders human-readable progress.                                                          |
+| Continuations     | Cold result methods accept branch/provider/hook overrides. Warm result methods retain their existing sandbox and reject sandbox reconfiguration. |
+| Structured output | Opening tags and repair capability are checked before provisioning. JSON can use a Markdown code fence inside its tag.                           |
+
+The default completion marker remains `<outpost>done</outpost>`. Native adapters remain Codex and Claude Code.
+
+## Campaigns
+
+Regenerate starters in a new directory or manually adopt `campaign`; `init` never overwrites existing files. Campaigns use `Backlog.list/get/close`, refresh the backlog every cycle and close issues only after their commits reach the host branch. The GitHub connector paginates and applies its configured label. Beads runs on the host and must be installed there; its generated container recipe also includes `bd`.
+
+Set `cycles`, `concurrency`, `implementationPasses` and `reviewPasses` in the starter. `planner: false` takes ready issues in order. `reviewer: false` skips review. Set separate adapters for `planner`, `reviewer` and `merger` to choose different models.
+
+## Recovery and observability
+
+`recoveryDetails(error)` returns available branch, directory, commits, transcript and log information. It preserves cancellation reason identity. A preparation failure removes a clean owned workspace; changed workspaces and failed remote recovery files survive. Successful remote transfer staging is cleaned at close.
+
+`reporter({ label, verbose, quiet, write })` creates a public observation callback. `idleWarningMs` controls periodic inactivity messages; `diagnostic` receives estimated token sizes of prompt command expansions. Estimates are not billing counts.
+
+## Extension ports
+
+Custom agents can provide `storage: ConversationStore`, `resumable`, and `transcriptUsage`. `conversations` exposes native path, search, capture, restore and selective rewrite helpers. Per-turn results expose their own `transcript` path.
+
+Transfers accept optional `{ signal, deadlineMs }`. `limits.copyMs` bounds orchestration transfers. A custom provider must honor cancellation itself to prevent background side effects. `Command.terminal` accepts caller-owned input/output/error streams; `attach.ask` supplies missing file-prompt variables without a TTY.

package/docs/operations.md

@@ -0,0 +1,101 @@
+# Operations and releases
+
+## Repository topology
+
+GitLab is the writable source of truth:
+
+```text
+https://gitlab.elielaloum.com/elielaloum/outpost.git
+    push mirror → https://github.com/elie-laloum/outpost.git
+                       GitHub Actions → packages and releases
+```
+
+Create commits and tags on GitLab. The push mirror includes branches and tags and preserves divergent refs rather than silently overwriting them. Do not merge changes directly on GitHub; bring contributions back to GitLab. Mirror credentials belong in GitLab's protected mirror configuration, never in tracked files or local remote URLs.
+
+## Install a released archive
+
+Download the `.tgz` from [GitHub Releases](https://github.com/elie-laloum/outpost/releases), then:
+
+```sh
+npm install --save-dev ./elie-laloum-outpost-1.1.0.tgz
+npx outpost --help
+```
+
+The archive includes JavaScript, declarations, source maps, EN/FR READMEs and the license. Main imports and local/container providers have no mandatory runtime npm dependencies. Cloud SDK peers are optional and installed only when needed.
+
+For GitHub Packages, configure the scope in your project's `.npmrc`:
+
+```ini
+@elie-laloum:registry=https://npm.pkg.github.com
+```
+
+Authenticate to that registry using an appropriate package-read token or your organization's supported authentication flow, then install `@elie-laloum/outpost`. GitHub Packages can require authentication even for public packages. Do not commit authentication tokens. The public release archive avoids registry authentication.
+
+## Local development
+
+```sh
+npm ci
+npm run typecheck
+npm test
+npm run coverage
+npm run build
+npm run test:package
+npm run format:check
+```
+
+Tests use temporary Git repositories and fixture agents, so unit/functional tests require no paid model access. `test:package` installs the actual archive in a separate temporary project and checks imports and initialization. `test:container` requires `OUTPOST_CONTAINER_ENGINE=docker` or `podman` and an `outpost-ci:latest` image generated by the CLI.
+
+The CI matrix covers Linux, Windows and macOS. Docker and Podman jobs build the generated image, verify both native CLIs, edit/commit through mounted Git, round-trip binary files and nested directories, verify file-mount parent permissions, test output/environment handling and verify cancellation does not destroy the warm sandbox or leave a delayed writer alive. SDK contract tests cover Vercel and Daytona without provisioning cloud resources.
+
+Live model/cloud tests require separate provider credentials. Contract tests and CLI compatibility checks do not prove availability or model behavior in a specific paid account. Pin custom images and use account-specific smoke tests before broad deployment.
+
+## Release procedure
+
+1. Change `package.json` and `package-lock.json` to the intended stable version and update `CHANGELOG.md` on GitLab.
+2. Wait for GitHub CI on that mirrored commit to pass.
+3. Create `v<version>` on GitLab at that exact commit.
+4. The mirrored tag starts `Release`. It verifies the version, runs the complete reusable CI workflow, builds the package and publishes to GitHub Packages using its short-lived `GITHUB_TOKEN`.
+5. The workflow creates a GitHub release with the installable tarball. Confirm the package and release point to the expected version.
+
+The publishing job has `packages: write` and `contents: write`; ordinary CI only has `contents: read`. Checkout does not persist credentials. No long-lived package-publishing token is needed for GitHub Packages.
+
+For GitHub Packages, the release job sets the archive's repository metadata to the GitHub mirror so package permissions attach to that workflow repository. The tracked source manifest, writable repository and tag creation remain on GitLab.
+
+Optional npm publication is disabled until repository variable `NPM_PUBLISH` is `true`. Before enabling it, configure the npm package's trusted publisher for GitHub owner `elie-laloum`, repository `outpost`, workflow `release.yml`. The job uses OIDC and provenance. Account/namespace ownership and the registry's initial package setup must be completed by an authorized npm account. Enabling a variable alone does not establish that trust.
+
+Published package versions are immutable. If a release fails after publication, inspect the registry before rerunning to avoid duplicate publication errors; use a new patch version for changed content. Never move a released tag.
+
+## Recovery
+
+Every failure should retain enough context to inspect the workspace. `OutpostError.details` includes available paths; `recoveryDetails(error)` includes collected conversation, commit, log and workspace information without changing the error identity. Clean workspaces are removed after startup failure; dirty ones are retained. Dirty managed worktrees remain under `.outpost/workspaces`, and named branches remain after clean worktree removal.
+
+Remote transfer folders under `.outpost/recovery` may contain:
+
+- `initial.bundle` / `commits.bundle`: Git objects with original history.
+- `initial.patch` / `remote.patch` / `previous.patch`: binary-capable worktree changes.
+- `previous-index.patch`: the prior staged changes.
+- `incoming/` / `previous-files/`: untracked file copies.
+- `state.json`: synchronization endpoints and file lists.
+
+Inspect these before attempting recovery. Fetch a bundle into a separate recovery clone and review the patch there before applying it to valuable work. An incomplete network transfer is not guaranteed to contain every remote file; the original error identifies the failed stage. Keep the cloud sandbox accessible when performing custom manual recovery.
+
+Lock files record their owner PID. Active locks reject conflicting workspace use; dead owners can be recovered automatically. If a PID has been reused, verify ownership before manually deleting a lock. Avoid editing a local workspace while its remote sandbox is active.
+
+## Logs and credentials
+
+Logs are JSONL under `.outpost/logs`; prompts, text, tool events, conversation IDs and usage are recorded. Verbose mode additionally retains raw protocol events. Native transcripts use the agent's own host storage. Files can contain private data; choose retention and backup policies accordingly. Runtime folders are ignored by Git. Successful remote transfer staging is removed at closure; failed recovery artifacts and native transcripts are retained. Explicit `await sandbox.close()` is the reliable shutdown path. SIGINT/SIGTERM await registered cleanup; `process.exit()` can only perform synchronous cleanup, including container removal. Asynchronous cloud cleanup cannot be guaranteed during a forced process exit.
+
+Use `.outpost/.env` for task-specific secrets and `.env.example` for names only. Explicitly mount authentication files only when needed, preferably read-only. Container environment values are transported through per-command aliases, preserving the engine's own host environment and keeping values out of command arguments.
+
+## Troubleshooting
+
+| Symptom                                    | Check                                                                                      |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| Image not found or UID mismatch            | Build with the same engine, image name and UID/GID used by the provider.                   |
+| Podman cannot write the worktree           | Verify rootless user namespaces, host permissions and SELinux labels.                      |
+| Agent not authenticated                    | Check the agent API key/OAuth variable or its explicitly mounted native auth file.         |
+| Cold resume cannot find a transcript       | Confirm agent, conversation ID and `conversationHome`; capture must have succeeded.        |
+| Host changed during remote execution       | Preserve the recovery folder, resolve local edits and inspect incoming history separately. |
+| Workflow never finishes after cancellation | Ensure custom task callbacks and custom providers honor their `AbortSignal`.               |
+| Native CLI rejects a flag                  | Compare installed versions with exported `agentVersions`; rebuild a stale image.           |
+| No GitHub CI after a GitLab push           | Inspect the GitLab push mirror status and its token permissions.                           |

package/docs/providers.md

@@ -0,0 +1,119 @@
+# Sandbox providers
+
+| Provider       | Placement     | Terminal | File transfer     | Requirement                           |
+| -------------- | ------------- | -------- | ----------------- | ------------------------------------- |
+| Docker         | Mounted       | Yes      | Files/directories | Running Docker daemon                 |
+| Podman         | Mounted       | Yes      | Files/directories | Running Podman engine                 |
+| Host `local()` | Host checkout | Yes      | Files/directories | Native agent installed                |
+| Vercel         | Remote        | No       | Files/directories | `@vercel/sandbox`, Vercel credentials |
+| Daytona        | Remote        | No       | Files/directories | `@daytona/sdk`, Daytona credentials   |
+
+## Docker and Podman
+
+```ts
+import { docker } from "@elie-laloum/outpost/providers/docker";
+
+const provider = docker({
+  image: "outpost:my-repository",
+  user: { uid: 1000, gid: 1000 },
+  volumes: [
+    {
+      source: "~/.config/example",
+      target: "/home/agent/.config/example",
+      readOnly: true,
+    },
+  ],
+  networks: ["development"],
+  groups: [1000],
+  devices: [],
+  cpus: 2,
+  memoryMb: 4096,
+  label: "z",
+  retain: 65_536,
+  variables: {},
+});
+```
+
+`podman()` accepts the same options. Default image is `outpost:<normalized-repository-directory>`. Build it with the CLI. Default UID/GID match the host on POSIX and use 1000 on Windows. The image preflight reports numeric UID mismatches when the user was not explicitly overridden. Podman supports `userns: "keep-id" | false` and maps explicit UIDs/GIDs. macOS checks that Podman Machine is running. Mount sources support `~`, relative and absolute paths, and files. Relative targets resolve under `/workspace`; `~` and `~/...` resolve under the agent home. Individual file mounts must target the home: mount a directory for other destinations. Their parents are prepared for the agent UID/GID. Linux mounts use SELinux `z` by default; choose `Z` for a private label or `false` to omit labels. Windows/macOS use bind-mount syntax.
+
+Containers have a private ephemeral home, dropped capabilities, no-new-privileges and an init process. Only selected mounts and Git metadata are exposed. Git paths are remapped so Windows worktree pointers remain usable inside Linux. Credentials are passed through environment names rather than command-line values. A command-specific process group allows cancellation without destroying the warm environment.
+
+The generated image contains Git, Node.js, Python, shell utilities and both agent CLIs. Modify the Dockerfile/Containerfile to install project tools. `outpost image build --file custom.Dockerfile --image custom:tag --uid 1000 --gid 1000` selects an alternative recipe. `outpost image remove` removes only the selected image.
+
+## Explicit host execution
+
+```ts
+import { local } from "@elie-laloum/outpost/providers/local";
+const result = await dispatch({
+  agent: codex(),
+  provider: local(),
+  brief: { text: "Inspect the project." },
+});
+```
+
+This is unisolated execution using your OS account and environment. Install/authenticate the CLI on the host. Outpost never silently falls back to host execution if a container fails. The host adapter does not elevate privileges.
+
+## Vercel
+
+```sh
+npm install @vercel/sandbox
+```
+
+```ts
+import { vercel } from "@elie-laloum/outpost/providers/vercel";
+
+const provider = vercel({
+  create: { timeout: 30 * 60 * 1000 },
+  variables: { OPENAI_API_KEY: process.env.OPENAI_API_KEY! },
+});
+```
+
+`create` accepts the installed SDK's sandbox-creation options, including credentials, runtime/image, networking and resources. Credential discovery follows the SDK. `root` can override the remote workspace directory; `retain` controls captured output tails. The provider discovers the actual remote home. Outpost installs the chosen agent in a user-writable prefix if it is missing; set `bootstrap: false` on `createSandbox`/`dispatch` when managing tools yourself.
+
+## Daytona
+
+```sh
+npm install @daytona/sdk
+```
+
+```ts
+import { daytona } from "@elie-laloum/outpost/providers/daytona";
+
+const provider = daytona({
+  connection: { apiKey: process.env.DAYTONA_API_KEY },
+  create: { language: "typescript" },
+});
+```
+
+`connection` is the SDK client configuration. `create` accepts an image/snapshot sandbox configuration. The remote environment must provide Node.js, npm, Git, `sh` and `setsid`. `root`, `variables`, and `retain` are available. Native process sessions stream both output channels and are cleaned up after each invocation. Cancellation terminates only the command process group.
+
+## Remote Git transport
+
+Remote workspaces default to temporary integration branches and start from committed Git history. `includeUncommitted: true` explicitly sends the host patch and untracked files. Otherwise pre-existing host edits are preserved and overlapping remote edits are rejected before local mutation. Selected copied inputs are uploaded too. Each dispatch, command or terminal completion synchronizes back. New commits retain their object IDs, authors, timestamps and parent relationships. Repeated synchronization handles uncommitted work later becoming committed without duplicating commits.
+
+Outpost compares host state with its last synchronized state. Concurrent local edits cause a recovery error. Before applying remote changes it saves patches, untracked files and incoming commits in `.outpost/recovery`. Rewritten/non-fast-forward remote history is rejected. Relative transfer paths are validated, and local symlink-parent traversal is rejected.
+
+## Custom providers
+
+`mountedProvider({ name, variables?, acquire })` and `remoteProvider({ name, variables?, acquire })` wrap your own backend. `acquire(context)` receives repository/workspace paths, Git metadata directories, resolved variables and a signal. Return a `SandboxLease`:
+
+```ts
+interface SandboxLease {
+  root: string;
+  home: string;
+  invoke(command: Command): Promise<CommandResult>;
+  upload(
+    source: string,
+    destination: string,
+    options?: TransferOptions,
+  ): Promise<void>;
+  download(
+    source: string,
+    destination: string,
+    options?: TransferOptions,
+  ): Promise<void>;
+  release(): Promise<void>;
+}
+```
+
+`invoke` must stream output to `observe`, respect abort/deadline, and leave the lease reusable after cancellation. `release` must be idempotent. Transfer options contain `signal` and `deadlineMs`; custom transfers must stop writing after cancellation. Outpost bounds the wait, but cannot forcibly cancel arbitrary user callbacks. Cloud SDK requests already sent may finish remotely; built-in downloads check cancellation before writing returned bytes. Remote providers must support Git and file transfer; Outpost performs synchronization through those capabilities. Interactive support is optional but unsupported calls must fail clearly. Cloud factories also accept an optional connection factory for contract tests or custom SDK wiring.

package/docs/workflows.md

@@ -0,0 +1,101 @@
+# Workflows
+
+Tasks form a directed acyclic graph. Each task declares its dependencies with `after`, and can only read successful values from those dependencies. Declaration order does not affect scheduling. A workflow validates duplicate keys, missing dependencies and cycles before any task runs.
+
+```ts
+import { task, workflow } from "@elie-laloum/outpost";
+
+const analyze = task({
+  key: "analyze",
+  perform: async () => ({ needed: true }),
+});
+const change = task({
+  key: "change",
+  after: [analyze],
+  condition: (context) => context.value(analyze).needed,
+  timeoutMs: 300_000,
+  retry: {
+    attempts: 3,
+    delayMs: 500,
+    accepts: (error) => error instanceof Error,
+  },
+  perform: async (context) => {
+    context.signal.throwIfAborted();
+    return "changed";
+  },
+});
+
+const delivery = workflow("delivery", [analyze, change]);
+console.log(delivery.diagram());
+const result = await delivery.start({ concurrency: 2, stopOnError: true });
+result.unwrap();
+console.log(result.value(change));
+```
+
+`TaskContext` includes `signal`, one-based `attempt`, `executionId`, and typed `value(task)`. A condition runs before the first attempt. False conditions skip the task and its descendants. Retries occur only on failure, within the declared attempt budget, and can be filtered with `accepts`. Delays respect cancellation.
+
+Task deadlines are **cooperative**: task code must honor `context.signal`. The scheduler waits for active work to clean up, preventing abandoned work from mutating resources after a workflow returns. Sandbox operations honor the signal. Arbitrary callbacks that ignore it cannot be forcibly stopped by JavaScript.
+
+`stopOnError` defaults to true and aborts active siblings after the first failure. Set false to let independent branches finish. Failed/skipped dependencies skip descendants. External cancellation returns a cancelled workflow. Observers receive start/task/retry/finish events and cannot change outcomes; their exceptions are collected in `observerErrors`.
+
+`WorkflowResult` contains immutable task records, errors, observer errors, status, execution ID, typed value access and `unwrap()`. `unwrap` throws `WorkflowFailure` for failed/cancelled results. The error retains the full result.
+
+## Sandbox tasks
+
+- `agentTask({ key, sandbox, request })` dispatches through an existing sandbox. `request(context)` produces the prompt/options.
+- `commandTask({ key, sandbox, command })` executes a command and fails the task on nonzero status. The command may be a function of context.
+- `isolatedTask({ key, request })` owns a one-shot sandbox/workspace for that task. `request(context)` supplies the complete dispatch configuration.
+
+Use dependencies to serialize tasks sharing a sandbox. Use `isolatedTask` with distinct named workspaces for fanout. Parallel temporary integration branches serialize their host merge stage, but semantically conflicting changes still require human resolution.
+
+## Issue campaigns
+
+`campaign` is the application-level orchestration service for issue delivery. A `Backlog` supplies `list(signal)`, `get(id, signal)` and `close(id, signal)`. Each issue has an id, title, optional body and optional `blockedBy` ids. Blocked issues are excluded while their dependencies remain open.
+
+```ts
+import { campaign, codex, claude, githubBacklog } from "@elie-laloum/outpost";
+import { docker } from "@elie-laloum/outpost/providers/docker";
+
+const result = await campaign({
+  agent: codex(),
+  planner: claude(),
+  reviewer: codex(),
+  merger: codex(),
+  provider: docker(),
+  backlog: githubBacklog({ label: "outpost-ready" }),
+  cycles: 10,
+  concurrency: 3,
+  implementationPasses: 100,
+  reviewPasses: 1,
+  standards:
+    "Follow repository conventions, test behavior and keep comments brief.",
+  observe: (event) => console.log(event.phase, event.cycle, event.issue),
+});
+console.log(result.reason, result.issues);
+```
+
+Each cycle refreshes the backlog. The planner returns validated assignments with unique issue ids and new branch names. Unknown issues, invalid branches and duplicate assignments fail before implementation. `planner: false` takes ready issues in order, up to the concurrency limit.
+
+Each issue owns a named workspace and one sandbox. Implementation and optional review share that sandbox; review inspects the full diff against the cycle's base commit. An implementation without commits skips review and closure. A failed issue is recorded while independent issues finish. `reviewer: false` disables review.
+
+Completed branches enter a separate integration sandbox, even when only one branch completed. The merger resolves conflicts, validates the result and commits corrections. Outpost verifies that the original issue commits are ancestors of the integrated result and rejects uncommitted leftovers. Only after integration into the host branch does it close the issues. Merge failure retains the workspace; tracker closure failure is reported after integration and requires reconciliation before rerunning.
+
+The campaign stops on an empty or blocked backlog, no progress, cancellation, or the cycle limit. The result distinguishes `empty`, `blocked`, `no-progress` and `limit`, and records each issue as `empty`, `failed` or `merged`. Positive integer limits are validated before work starts.
+
+## Starter templates
+
+| Template      | Structure                                                                          |
+| ------------- | ---------------------------------------------------------------------------------- |
+| `blank`       | One dispatch with a configurable objective.                                        |
+| `iterate`     | Sequential campaign; reloads the tracker each cycle.                               |
+| `review`      | Sequential implementation and conditional warm review per issue.                   |
+| `plan`        | Typed plan, separate issue branches, bounded concurrent execution and integration. |
+| `plan-review` | Planned parallel execution with a warm review for each changed issue.              |
+
+Without a tracker, a campaign starter wraps the command-line objective as one in-memory issue. With `--tracker github`, `beads` or `custom`, the tracker supplies the workload. Limits and role adapters are editable at the top level of the generated call; standards live in `.outpost/STANDARDS.md`.
+
+GitHub uses authenticated host `gh`, paginates all issue pages, excludes pull requests and applies the configured label. `--label NAME` creates/updates the label and configures filtering. Declare `GH_TOKEN` in `.outpost/.env` or authenticate `gh` directly. The connector follows the official [GitHub CLI pagination contract](https://cli.github.com/manual/gh_api).
+
+Beads uses host `bd ready --json --limit 0`, `bd show` and `bd close`. Install and initialize [Beads](https://github.com/gastownhall/beads) on the host before running. Selecting Beads also installs its pinned CLI in the generated container image.
+
+The custom starter implements three HTTP operations: GET `issues?state=open`, GET `issues/:id`, POST `issues/:id/close`. Set `OUTPOST_TRACKER_URL` on the host and adapt authentication/pagination in `tickets.ts` or `tickets.mts`. `.outpost/TRACKER.md` documents the contract. Keep tracker mutation in the host connector so agents do not close issues before integration.