@elie-laloum/outpost 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 1.1.0
+
+- Add typed issue campaigns with dynamic planning, bounded concurrency, per-issue branches, warm review, verified integration and tracker closure.
+- Add complete GitHub and Beads backlog connectors and executable campaign starters.
+- Isolate cold passes, validate cancellation and structured responses before allocation, and preserve raw/final agent output.
+- Expose per-turn transcripts, custom conversation stores, selective path rewriting and separate Claude cache counters.
+- Align environment allowlists, caller-relative prompts, interactive variable collection and lifecycle hook ordering.
+- Recover managed workspaces, refresh reusable branches and preserve host edits during committed-only remote synchronization.
+- Complete Podman namespace options, macOS preflight, file-mount preparation and bounded transfers.
+- Add human progress reporting, appendable journals, recovery metadata and terminal cleanup.
+- Expand functional, provider and package tests; document migration in English and French.
+
+## 1.0.0
+
+Initial Outpost release.
+
+- Separate workspace and sandbox ownership, reusable environments and asynchronous disposal.
+- Codex and Claude Code adapters with native conversations, resume and fork.
+- Docker, Podman, host, Vercel and Daytona providers; extensible provider contracts.
+- Managed Git worktrees, named branches, automatic integration and recovery files.
+- Remote synchronization retaining commit identity and protecting concurrent host changes.
+- Prompt files, typed variables, command expansion, completion loops and inactivity deadlines.
+- Tagged text/JSON responses, Standard Schema validation and resumable repair attempts.
+- Typed workflow graphs with conditions, retries, cancellation, concurrency and diagrams.
+- Interactive/headless initialization, five starter templates and issue-tracker connectors.
+- English/French documentation, cross-platform tests, coverage gates and package release automation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elie Laloum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.fr.md

@@ -0,0 +1,251 @@
+# Outpost
+
+[English](README.md) · [API](docs/api.md) · [Fournisseurs](docs/providers.md) · [Workflows](docs/workflows.md) · [Exploitation](docs/operations.md) · [Roadmap](ROADMAP.md)
+
+Outpost est une bibliothèque TypeScript pour exécuter des agents de développement dans des sandbox réutilisables, gérer leurs espaces de travail Git et composer des workflows typés. La v1 fournit les adaptateurs **Codex** et **Claude Code**, ainsi que les environnements Docker, Podman, Vercel, Daytona et une exécution locale explicite. Les adaptateurs d’agents et les fournisseurs de sandbox sont deux points d’extension distincts.
+
+[GitLab](https://gitlab.elielaloum.com/elielaloum/outpost) est le dépôt principal. [GitHub](https://github.com/elie-laloum/outpost) reçoit le miroir et exécute la CI ainsi que les publications de packages.
+
+## Prérequis
+
+- Node.js **24 ou supérieur**, Git et un dépôt possédant au moins un commit.
+- Docker ou Podman pour l’isolation locale ; un compte et le SDK optionnel correspondant pour une sandbox cloud.
+- Une authentification native de l’agent ou sa clé API. Un jeton GitHub/GitLab ne remplace pas une clé de modèle.
+- Des imports ESM. Les déclarations TypeScript sont livrées ; Node exécute directement les scripts générés en `.ts`/`.mts`.
+
+## Installation et premier lancement
+
+Depuis les sources :
+
+```sh
+npm ci
+npm run build
+npm pack
+```
+
+Installez l’archive obtenue dans votre dépôt cible, ou utilisez [GitHub Packages](https://github.com/elie-laloum/outpost/packages). La configuration du registre figure dans le [guide d’exploitation](docs/operations.md).
+
+```sh
+npm install --save-dev /chemin/elie-laloum-outpost-1.1.0.tgz
+npx outpost init --yes --agent codex --provider docker --template blank --build
+```
+
+Copiez `.outpost/.env.example` vers `.outpost/.env`. Renseignez `OPENAI_API_KEY`, ou laissez cette déclaration vide pour reprendre sa valeur dans le processus. Pour Claude, choisissez `--agent claude` et déclarez `ANTHROPIC_API_KEY` ou `CLAUDE_CODE_OAUTH_TOKEN`. Seules les clés déclarées sont importées dans les sandbox isolés.
+
+```sh
+node .outpost/run.mts "Ajouter la validation de configuration et ses tests"
+```
+
+Le script s’appelle `run.ts` si le projet déclare `"type": "module"`, sinon `run.mts`. L’initialisation refuse d’écraser des fichiers existants. `--install` installe la bibliothèque et le SDK optionnel avec le gestionnaire détecté : npm, pnpm, yarn ou bun. Sans `--build`, construisez ensuite l’image avec `npx outpost image build`.
+
+## Exécution ponctuelle
+
+```ts
+import { dispatch, codex } from "@elie-laloum/outpost";
+import { docker } from "@elie-laloum/outpost/providers/docker";
+
+const result = await dispatch({
+  agent: codex(),
+  provider: docker(),
+  branch: { mode: "integrate" },
+  brief: { text: "Corriger les tests en échec, vérifier et créer un commit." },
+});
+
+console.log(result.branch, result.commits, result.conversation);
+```
+
+`dispatch` crée l’environnement, lance l’agent, récupère les modifications et la conversation native, intègre les commits si demandé, puis ferme les ressources dont il est propriétaire. Le travail non commité est conservé. En cas d’échec, les worktrees séparés restent disponibles pour inspection.
+
+| Politique Git                                                 | Comportement                                                                          |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `{ mode: "current" }`                                         | Utilise le checkout actuel ; défaut des fournisseurs montés et locaux.                |
+| `{ mode: "named", name: "feature/validation", from: "main" }` | Crée ou réutilise un worktree géré pour cette branche.                                |
+| `{ mode: "integrate", from: "main" }`                         | Crée une branche temporaire puis fusionne ses commits dans la branche hôte d’origine. |
+
+Les fournisseurs distants exigent `named` ou `integrate`. `from` est optionnel. Une branche déjà utilisée ailleurs produit une erreur explicite. L’intégration refuse un changement de branche hôte et conserve le worktree en cas de conflit.
+
+## Sandbox réutilisable
+
+```ts
+import { createSandbox, claude } from "@elie-laloum/outpost";
+
+await using sandbox = await createSandbox({
+  agent: claude({ model: "sonnet", reasoning: "high" }),
+  branch: { mode: "named", name: "feature/settings" },
+});
+
+const first = await sandbox.dispatch({
+  brief: { text: "Implémenter la validation." },
+});
+const tests = await sandbox.command({ executable: "npm", arguments: ["test"] });
+if (tests.status !== 0)
+  await first.resume({ brief: { text: "Corriger les tests." } });
+await sandbox.attach();
+```
+
+Une commande retourne son statut, même non nul. Une exécution d’agent en échec lève une erreur. L’annulation par `AbortSignal`, le délai maximal et la surveillance d’inactivité arrêtent l’opération courante sans détruire la sandbox réutilisable. Une sandbox accepte une opération active à la fois. Le parallélisme utilise plusieurs sandbox.
+
+L’agent par défaut est optionnel pour une sandbox chaude. Fournissez `agent` à chaque appel de `sandbox.dispatch` ou `sandbox.attach` pour changer d’agent ou de modèle sans recréer l’environnement. Chaque exécution reçoit uniquement les variables de l’adaptateur choisi.
+
+`await using` ferme automatiquement le handle. `close()` est également disponible et idempotent. `attach()` ouvre le terminal natif avec Docker, Podman ou le fournisseur local. Les fournisseurs cloud rejettent explicitement cette opération.
+
+## Espace de travail indépendant
+
+```ts
+import { openWorkspace, codex, claude } from "@elie-laloum/outpost";
+
+await using workspace = await openWorkspace({
+  branch: { mode: "named", name: "feature/shared-work" },
+  copies: [".env.test"],
+});
+
+await workspace.dispatch({
+  agent: codex(),
+  brief: { text: "Implémenter et commiter." },
+});
+await workspace.dispatch({
+  agent: claude(),
+  brief: { text: "Relire, tester et commiter les corrections." },
+});
+```
+
+L’espace de travail fourni survit aux sandbox successives. Son propriétaire doit le fermer après elles. Un worktree contenant des modifications reste sur disque ; `close()` retourne alors `retainedDirectory`. Un worktree propre est supprimé, mais une branche nommée reste disponible. `close({ preserve: true })` conserve aussi un worktree propre.
+
+`workspace.sandbox()` et `workspace.attach()` donnent accès aux autres cycles de vie. Avec une sandbox chaude en mode `integrate`, utilisez explicitement `sandbox.workspace.integrate()` au moment voulu. Les exécutions ponctuelles intègrent avant de retourner leur résultat.
+
+## Prompts et boucles
+
+Un `brief` contient exactement une source : `text` littéral, ou `file` avec des `values` primitives optionnelles. Les fichiers sont relus à chaque passage ; le texte littéral n’est jamais interprété.
+
+```ts
+const result = await dispatch({
+  agent: codex(),
+  brief: {
+    file: ".outpost/brief.md",
+    values: { OBJECTIVE: "Corriger la validation" },
+  },
+  passes: 5,
+  until: ["<outpost>done</outpost>"],
+  idleMs: 600_000,
+  settleMs: 60_000,
+});
+```
+
+Les fichiers acceptent `{{OBJECTIVE}}`, les variables réservées `{{WORK_BRANCH}}` et `{{BASE_BRANCH}}`, ainsi que des commandes comme `` !`git status --short` ``. Les commandes présentes dans le fichier d’origine s’exécutent en parallèle dans la sandbox après les hooks. Une valeur substituée ne peut pas introduire une nouvelle commande d’expansion. Une valeur insérée dans une commande existante conserve toutefois sa sémantique shell : utilisez des valeurs fiables ou correctement échappées.
+
+Les variables absentes déclenchent une erreur ; les variables inutilisées passent par `warn`. Un marqueur de fin interrompt la boucle. Si l’agent reste actif après ce marqueur, le délai de grâce se renouvelle à chaque sortie, puis arrête sa commande. Un budget épuisé sans marqueur retourne `completed: false`.
+
+Chaque tour fournit sa durée, son statut, son texte, sa conversation éventuelle et les tokens bruts. Chaque tour expose aussi son chemin `transcript` lorsqu’il est capturé. Le résultat regroupe `input`, `cached` (lecture du cache), `cacheCreated` (création du cache), `output`, les commits et le marqueur observé. Aucun coût monétaire n’est extrapolé.
+
+## Réponses structurées
+
+```ts
+import { response } from "@elie-laloum/outpost";
+
+const result = await dispatch({
+  agent: codex(),
+  brief: {
+    text: "Analyser le dépôt et répondre avec <report>un JSON contenant ok</report>.",
+  },
+  response: response.json({
+    tag: "report",
+    repairs: 2,
+    schema(input) {
+      if (
+        !input ||
+        typeof input !== "object" ||
+        !("ok" in input) ||
+        typeof input.ok !== "boolean"
+      ) {
+        throw new Error("Un booléen ok est requis");
+      }
+      return { ok: input.ok };
+    },
+  }),
+});
+
+console.log(result.value.ok);
+```
+
+`response.text` extrait du texte balisé. `response.json` accepte une fonction ou un validateur Standard Schema, y compris asynchrone. La balise d’ouverture doit être demandée dans le prompt. Les réponses structurées exigent un seul passage ; les tentatives de correction reprennent la même conversation. En cas d’échec, `ResponseError.recovery` contient les informations de reprise disponibles.
+
+## Conversations natives
+
+```ts
+await result.resume({ brief: { text: "Expliquer le résultat." } });
+await result.fork({ brief: { text: "Explorer une autre solution." } });
+```
+
+La capture est active par défaut. Outpost enregistre les transcriptions dans le stockage natif de l’agent sur l’hôte et réécrit les champs de répertoire de travail. Le contenu des messages n’est pas remplacé globalement. Les transcriptions des sous-agents Claude sont récupérées au mieux, avec avertissement en cas d’échec. Un échec de capture de la transcription principale fait échouer l’exécution.
+
+`saveConversations: false` désactive la capture sur l’adaptateur. Une reprise ponctuelle vérifie d’abord l’existence de la transcription hôte. `fork` crée une nouvelle conversation ; il faut aussi choisir un autre workspace pour isoler les fichiers. `conversationHome` permet de choisir un autre répertoire de stockage hôte.
+
+## Workflows typés
+
+```ts
+import { task, workflow } from "@elie-laloum/outpost";
+
+const inspect = task({
+  key: "inspect",
+  perform: async () => ({ ready: true }),
+});
+const implement = task({
+  key: "implement",
+  after: [inspect],
+  retry: { attempts: 2, delayMs: 500 },
+  perform: async (context) => context.value(inspect).ready,
+});
+
+const result = await workflow("delivery", [inspect, implement]).start({
+  concurrency: 2,
+});
+result.unwrap();
+console.log(result.value(implement));
+```
+
+Les dépendances absentes, doublons et cycles sont rejetés avant exécution. Les valeurs sont typées et propres à chaque lancement. Conditions, tentatives supplémentaires, limites de concurrence, événements d’observation et diagrammes Mermaid sont disponibles. `agentTask`, `commandTask` et `isolatedTask` relient le graphe aux opérations de sandbox.
+
+L’annulation et le délai maximal des tâches sont coopératifs : le code d’une tâche doit respecter `context.signal`. Le planificateur attend le nettoyage des tâches actives avant de retourner. Les opérations Outpost respectent ce signal. Une fonction JavaScript arbitraire qui l’ignore ne peut pas être arrêtée de force.
+
+Les cinq modèles CLI sont `blank`, `iterate`, `review`, `plan` et `plan-review`. Les deux derniers font travailler plusieurs analyses indépendantes avant l’implémentation. Les connecteurs GitHub Issues, Beads et personnalisés sont générés avec `--tracker`. Consultez le [guide des workflows](docs/workflows.md).
+
+Un `dispatch({ passes })` ponctuel acquiert une nouvelle sandbox à chaque passe ; `sandbox.dispatch({ passes })` conserve son environnement. Les fichiers de prompt relatifs sont résolus depuis le répertoire de l’appelant. Les méthodes `resume`/`fork` d’un résultat ponctuel acceptent une nouvelle branche, un autre fournisseur et des hooks ; celles d’un résultat chaud restent liées à leur sandbox.
+
+## Campagnes par issue
+
+`campaign` relit le backlog à chaque cycle, valide un plan typé et attribue une branche par issue. Le parallélisme est borné ; la revue partage la sandbox d’implémentation. Une phase de fusion et de vérification intervient même pour une seule branche. La fermeture d’une issue a lieu uniquement après intégration des commits dans la branche hôte. GitHub et Beads fournissent les opérations de liste, détail et fermeture. Un connecteur personnalisé implémente `Backlog`.
+
+Les starters exposent `cycles`, `concurrency`, `implementationPasses`, `reviewPasses`, les agents de chaque rôle et les règles de `.outpost/STANDARDS.md`. Une issue sans commit n’est ni revue ni fermée. Un cycle sans progression s’arrête. `recoveryDetails(error)` fournit les chemins disponibles en cas d’erreur, sans remplacer la raison d’annulation. [Guide de migration 1.1 en français](docs/migration-1.1.fr.md).
+
+## Configuration et fournisseurs
+
+Les fournisseurs prennent en charge les variables d’environnement, montages de fichiers/répertoires, réseaux, ressources, groupes supplémentaires, périphériques et labels SELinux selon le backend. Les SDK cloud sont des dépendances optionnelles, chargées uniquement à l’utilisation du fournisseur concerné. [Référence des fournisseurs](docs/providers.md).
+
+Les hooks s’exécutent après la copie des entrées puis après la création de la sandbox. Les groupes `hostReady` et `sandboxReady` tournent en parallèle ; les commandes hôte restent séquentielles, tandis que les commandes du groupe sandbox démarrent ensemble et annulent leurs voisines en cas d’échec.
+
+Seul `.outpost/.env` est lu. Une valeur non vide du fichier est prioritaire ; une déclaration vide reprend la valeur du processus. Le `.env` à la racine du dépôt n’est pas importé. Les variables explicites du fournisseur et de l’adaptateur restent prioritaires. Une clé déclarée simultanément par le fournisseur et l’adaptateur provoque une erreur. Les journaux sont écrits dans `.outpost/logs` par défaut ; `false`, `"stdout"`, un chemin personnalisé et le mode verbeux sont disponibles.
+
+`AgentAdapter` permet d’ajouter un agent. `SandboxProvider`, `mountedProvider` et `remoteProvider` permettent d’ajouter un backend. Le domaine ne dépend pas d’un SDK cloud. [Architecture](docs/architecture.md) et [API complète](docs/api.md).
+
+## Vérification et publication
+
+```sh
+npm ci
+npm run check
+npm run coverage
+npm run test:package
+```
+
+La CI GitHub exécute les tests unitaires et fonctionnels sous Linux, Windows et macOS, impose 80 % de couverture des lignes, fonctions et branches, installe le package réellement produit et teste Docker/Podman. Les tests de contrats cloud utilisent des doubles contrôlés ; les essais avec de vrais modèles et comptes cloud nécessitent leurs identifiants.
+
+Les tags de version sont créés dans GitLab puis répliqués. Le workflow de release valide le tag et la CI, publie GitHub Packages et joint l’archive installable à une release GitHub. La publication npm est optionnelle, via trusted publishing une fois configuré. [Procédure d’exploitation](docs/operations.md).
+
+## Limites d’isolation et récupération
+
+Docker et Podman montent le worktree sélectionné et les métadonnées Git. L’agent peut modifier ce dépôt et son état Git. Les autres chemins hôte ne sont pas exposés par défaut, mais ce montage ne constitue pas une protection contre un agent hostile visant le dépôt partagé. `local()` s’exécute directement sur votre machine, sans isolation.
+
+Les fournisseurs cloud synchronisent l’historique, les changements suivis et les fichiers nouveaux. Les identifiants et auteurs des commits sont conservés. Une modification hôte concurrente déclenche une erreur de récupération plutôt qu’un écrasement. Les bundles, patches et fichiers de secours sont conservés sous `.outpost/recovery`.
+
+Les logs, transcriptions et fichiers de récupération peuvent contenir des données privées. Les dossiers d’exécution et `.env` sont exclus du versionnement. [Détails de sécurité](SECURITY.md).
+
+Licence MIT : [LICENSE](LICENSE).

package/README.md

@@ -0,0 +1,226 @@
+# Outpost
+
+[Français](README.fr.md) · [API](docs/api.md) · [Providers](docs/providers.md) · [Workflows](docs/workflows.md) · [Operations](docs/operations.md) · [Roadmap](ROADMAP.md)
+
+Outpost is a TypeScript library for running coding agents in reusable sandboxes, managing their Git workspaces and composing typed workflows. V1 supports **Codex** and **Claude Code**, with Docker, Podman, Vercel, Daytona and explicit host execution. Agent adapters and sandbox providers are separate extension points.
+
+The source repository is [GitLab](https://gitlab.elielaloum.com/elielaloum/outpost). [GitHub](https://github.com/elie-laloum/outpost) is its push mirror and runs all CI and package releases.
+
+## Requirements
+
+- Node.js **24 or later**, Git, and an existing repository with at least one commit.
+- Docker or Podman for local isolation; the appropriate account and optional SDK for a cloud sandbox.
+- An authenticated coding agent or its API key. Git hosting credentials are not model credentials.
+- ESM imports. TypeScript declarations ship with the package; Node can execute the generated `.ts`/`.mts` scripts directly.
+
+## Install and run
+
+Build from the source checkout:
+
+```sh
+npm ci
+npm run build
+npm pack
+```
+
+Install the resulting tarball in your target repository, or use the package from [GitHub Packages](https://github.com/elie-laloum/outpost/packages). Registry configuration is documented in [Operations](docs/operations.md).
+
+```sh
+npm install --save-dev /path/to/elie-laloum-outpost-1.1.0.tgz
+npx outpost init --yes --agent codex --provider docker --template blank --build
+```
+
+Copy `.outpost/.env.example` to `.outpost/.env`. Set `OPENAI_API_KEY` there, or leave its declaration empty to inherit the process value. For Claude, select `--agent claude` and declare `ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN`. Only declared process variables are imported into isolated sandboxes. Run the generated script:
+
+```sh
+node .outpost/run.mts "Add validation and tests for the configuration loader"
+```
+
+Initialization uses `run.ts` when the host package declares `"type": "module"`, and `run.mts` otherwise. It never overwrites an existing scaffold. `--install` installs the library and optional provider SDK with the detected package manager. Omit `--build` to build the image later with `npx outpost image build`.
+
+## One dispatch
+
+```ts
+import { dispatch, codex } from "@elie-laloum/outpost";
+import { docker } from "@elie-laloum/outpost/providers/docker";
+
+const result = await dispatch({
+  agent: codex(),
+  provider: docker(),
+  branch: { mode: "integrate" },
+  brief: { text: "Fix the failing tests, verify the result and commit it." },
+});
+
+console.log(result.branch, result.commits, result.conversation);
+```
+
+`dispatch` provisions a sandbox, executes the agent, collects changes and native conversation files, integrates commits when requested, and closes owned resources. Uncommitted work is retained. Failure paths preserve separate workspaces for inspection.
+
+| Branch policy                                                 | Behavior                                                                         |
+| ------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `{ mode: "current" }`                                         | Uses the current checkout. This is the mounted/host default.                     |
+| `{ mode: "named", name: "feature/validation", from: "main" }` | Creates or reuses a managed worktree for that branch.                            |
+| `{ mode: "integrate", from: "main" }`                         | Creates a temporary branch and merges its commits into the original host branch. |
+
+Remote providers require `named` or `integrate`. `from` is optional. Integration refuses a changed host branch and retains the workspace on conflict. A branch checked out elsewhere produces an actionable error.
+
+## Keep a sandbox warm
+
+```ts
+import { createSandbox, claude } from "@elie-laloum/outpost";
+
+await using sandbox = await createSandbox({
+  agent: claude({ model: "sonnet", reasoning: "high" }),
+  branch: { mode: "named", name: "feature/settings" },
+});
+
+const first = await sandbox.dispatch({
+  brief: { text: "Implement settings validation." },
+});
+const tests = await sandbox.command({ executable: "npm", arguments: ["test"] });
+if (tests.status !== 0)
+  await first.resume({ brief: { text: "Fix the failing tests." } });
+await sandbox.attach();
+```
+
+Commands return nonzero statuses; agent dispatches throw on agent failure. `AbortSignal`, command deadlines and idle watchdogs stop the current operation while leaving a warm sandbox usable. A sandbox accepts one active operation at a time. Use separate sandboxes for parallel work.
+
+The default agent is optional for a warm sandbox. Pass `agent` to individual `sandbox.dispatch` or `sandbox.attach` calls to switch between Codex and Claude, or change models, without recreating the environment. Each job receives only its selected adapter's variables.
+
+## Own the workspace separately
+
+```ts
+import { openWorkspace, codex, claude } from "@elie-laloum/outpost";
+
+await using workspace = await openWorkspace({
+  branch: { mode: "named", name: "feature/shared-work" },
+  copies: [".env.test"],
+});
+
+await workspace.dispatch({
+  agent: codex(),
+  brief: { text: "Implement the feature and commit." },
+});
+await workspace.dispatch({
+  agent: claude(),
+  brief: { text: "Review the implementation, test and commit fixes." },
+});
+```
+
+A supplied workspace outlives each sandbox. Its owner closes it. Closing a dirty workspace returns `retainedDirectory`; closing a clean managed workspace removes the worktree. Named branches remain. `workspace.sandbox()` and `workspace.attach()` provide the other lifecycles. Warm integration workspaces can call `sandbox.workspace.integrate()` explicitly.
+
+## Prompts and iteration
+
+Provide exactly one `brief`: literal `text`, or a `file` with optional primitive `values`. Files are reread each pass; inline text is never expanded.
+
+```ts
+const result = await dispatch({
+  agent: codex(),
+  brief: { file: ".outpost/brief.md", values: { OBJECTIVE: "Fix validation" } },
+  passes: 5,
+  until: ["<outpost>done</outpost>"],
+  idleMs: 600_000,
+  settleMs: 60_000,
+});
+```
+
+Files support `{{OBJECTIVE}}`, reserved `{{WORK_BRANCH}}` and `{{BASE_BRANCH}}`, and shell expansion such as `` !`git status --short` ``. Original file commands run concurrently inside the sandbox after setup hooks. Substituted text cannot introduce additional commands. Values inserted into an existing command are shell input: only interpolate trusted values there. Missing variables fail; unused variables warn through `warn`.
+
+Completion markers stop the loop. If the process hangs after a marker, the completion grace period resets on subsequent output and then stops that command. Every turn includes its duration, native transcript path when available and raw token counts (input, cache read, cache creation, output); the result includes aggregate usage and the matched completion marker.
+
+## Structured responses and conversations
+
+```ts
+import { response } from "@elie-laloum/outpost";
+
+const result = await dispatch({
+  agent: codex(),
+  brief: {
+    text: "Analyze the repository. Return <report>JSON with an ok boolean</report>.",
+  },
+  response: response.json({
+    tag: "report",
+    repairs: 2,
+    schema(input) {
+      if (
+        !input ||
+        typeof input !== "object" ||
+        !("ok" in input) ||
+        typeof input.ok !== "boolean"
+      ) {
+        throw new Error("Expected an ok boolean");
+      }
+      return { ok: input.ok };
+    },
+  }),
+});
+
+console.log(result.value.ok);
+await result.resume({ brief: { text: "Explain the result." } });
+await result.fork({ brief: { text: "Explore a different solution." } });
+```
+
+`response.text` extracts tagged text. `response.json` accepts a function or a Standard Schema validator, including asynchronous validation. Structured responses and conversation continuations require one pass. Repairs resume the same conversation. `ResponseError.recovery` exposes the conversation, commits and recovery paths. `recoveryDetails(error)` also retrieves recovery metadata for other failures without replacing cancellation reasons.
+
+Native conversation capture is enabled by default. Transcripts are saved to the host agent's own storage and working-directory fields are rewritten for host resumption. Claude child transcripts are copied on a best-effort basis. Set `saveConversations: false` on an adapter to opt out. Forks create a new conversation; use a separate workspace when filesystem isolation is also required.
+
+Each cold `dispatch({ passes })` provisions a fresh sandbox per pass. `sandbox.dispatch({ passes })` deliberately reuses its environment. Relative brief filenames resolve from the caller’s working directory. Cold result `resume`/`fork` accepts new branch/provider/hook settings; warm result methods retain the sandbox’s settings. See [1.1 migration notes](docs/migration-1.1.md).
+
+## Typed workflows
+
+```ts
+import { task, workflow } from "@elie-laloum/outpost";
+
+const inspect = task({
+  key: "inspect",
+  perform: async () => ({ ready: true }),
+});
+const implement = task({
+  key: "implement",
+  after: [inspect],
+  retry: { attempts: 2, delayMs: 500 },
+  perform: async (context) => context.value(inspect).ready,
+});
+const result = await workflow("delivery", [inspect, implement]).start({
+  concurrency: 2,
+});
+result.unwrap();
+console.log(result.value(implement));
+```
+
+The graph validates dependencies and cycles before running. Results are typed and scoped to one execution. Conditions, cooperative cancellation, retries, concurrency limits, observer events and Mermaid diagrams are built in. `agentTask`, `commandTask` and `isolatedTask` connect workflows to sandbox operations. [Workflow guide](docs/workflows.md).
+
+## Issue campaigns
+
+`campaign({ agent, provider, backlog })` loads a backlog, validates a typed plan, allocates a branch per issue and bounds parallel implementation. Review shares each issue sandbox. A merge phase validates the combined work; issue closure occurs only after integration into the host branch. The backlog is refreshed for the next cycle. GitHub and Beads connectors expose list, detail and close operations; custom trackers implement `Backlog`.
+
+[Campaign configuration and starter examples](docs/workflows.md#issue-campaigns).
+
+## Configuration and extension
+
+Provider settings cover environment variables, file/directory mounts, networks, resource limits, devices, extra groups and SELinux labels. Hooks run at workspace readiness and after sandbox creation. The two post-creation hook groups run concurrently. Host commands run in order; sandbox commands run concurrently and cancel their siblings on failure. [Complete API](docs/api.md) and [provider reference](docs/providers.md).
+
+Outpost reads only `.outpost/.env`. Nonempty file values win; empty declarations inherit matching process values. The repository-root `.env` is not imported. Explicit provider and adapter variables override those values. The same variable cannot be declared by both provider and adapter. Logs default to `.outpost/logs`, with `false`, `"stdout"`, custom files and verbose modes available.
+
+Implement `AgentAdapter` to add an agent. Implement `SandboxProvider` directly or use `mountedProvider`/`remoteProvider` to add an execution backend. Domain contracts do not depend on a specific cloud SDK. [Architecture](docs/architecture.md).
+
+## Verification and releases
+
+```sh
+npm ci
+npm run check
+npm run coverage
+npm run test:package
+```
+
+GitHub Actions runs unit and functional tests on Linux, Windows and macOS, enforces 80% line/function/branch coverage, installs the packed package, and runs real Docker and Podman tests. Cloud contract tests use controlled SDK doubles; live cloud/model checks require the corresponding credentials. No GitLab CI pipeline is required.
+
+Version tags are created on GitLab and mirrored. The release workflow validates the tag, runs CI, publishes GitHub Packages and attaches the installable tarball to a GitHub release. Optional npm publication uses trusted publishing when enabled. [Release procedure and registry setup](docs/operations.md).
+
+## Execution boundary
+
+Docker and Podman mount the selected worktree and Git metadata. Agents can edit that repository and its Git state. This protects unrelated host paths but is not a boundary against a hostile agent attacking the shared repository. Mount only what the task needs. `local()` runs directly on your machine without isolation. Cloud providers synchronize via Git bundles and file transfers; concurrent host changes cause a recovery error instead of being overwritten.
+
+Logs, conversation files and recovery files can contain private prompts or source. Runtime folders and `.env` are excluded from version control. See [Security](SECURITY.md) for the precise boundaries.
+
+MIT licensed. See [LICENSE](LICENSE).

package/ROADMAP.md

@@ -0,0 +1,34 @@
+# Roadmap
+
+## V1 contract
+
+Reusable sandboxes; independent workspaces; current/named/integration branch policies; Claude Code and Codex adapters; native session capture, resume and fork; Docker, Podman, host, Vercel and Daytona providers; command streaming and cancellation; file prompts, expansion, loops and structured responses; setup hooks; typed workflows; CLI initialization; EN/FR documentation; cross-platform tests and package release automation.
+
+## V1.x: efficiency and diagnostics
+
+- Durable campaign closure receipts to reconcile tracker outages without reimplementing merged issues.
+- Configurable planner policies, merge validation commands and per-role token budgets.
+
+- Incremental remote file manifests and compressed transfer batches while preserving recovery guarantees.
+- Content-addressed dependency caches and prebuilt agent images with signed provenance.
+- Configurable recovery retention with an inspect/prune CLI and storage quotas.
+- Structured metrics, OpenTelemetry integration and per-workflow usage budgets.
+- Richer diagnostic reports for provider capabilities and agent CLI compatibility.
+- More hosted-provider contract fixtures and scheduled live compatibility checks.
+
+## V2: durable orchestration
+
+- Persisted workflow checkpoints and recovery after host restarts.
+- Distributed task queues and worker leases with fencing tokens.
+- Explicit approvals and pause/resume nodes in workflows.
+- Artifact contracts between isolated tasks, with typed validation and lineage.
+- Native terminal transport for cloud backends where reliable PTY APIs are available.
+- Additional agent adapters through the existing domain ports.
+
+## Research
+
+- Stronger Git metadata isolation for adversarial agents.
+- MicroVM backends and fine-grained outbound network policies.
+- Speculative execution with conflict-aware integration and cost limits.
+
+Roadmap items are additions to the v1 contract. They are not prerequisites for running the current library.

package/SECURITY.md

@@ -0,0 +1,15 @@
+# Security boundaries
+
+Outpost runs coding agents that execute arbitrary project commands. Use it with repositories and credentials appropriate for that task.
+
+Docker/Podman expose only the selected checkout, Git metadata and explicit volumes. The Docker socket is not mounted by default. Containers use a chosen UID/GID, dropped capabilities, no-new-privileges and a private home. Extra devices, writable mounts and elevated hooks expand the boundary deliberately.
+
+Shared Git metadata is writable by the agent. A mounted sandbox is not an adversarial boundary protecting the host repository or its configuration. Outpost disables host Git hooks for its own Git commands, but a malicious repository can contain other executable configuration or project tooling. Do not run untrusted repositories with valuable host credentials. Host `local()` provides no isolation.
+
+Remote providers upload repository history and inputs to the selected cloud account. Explicit credentials and environment files are sent to that environment. Review the cloud provider's own storage/network policy. Concurrent host changes stop synchronization; recovery files preserve prior and incoming state when available.
+
+Prompt command expansion only recognizes commands present in the original prompt file. Substitution cannot introduce new expansion fragments. Values substituted inside an original shell command still have shell semantics and must be trusted or quoted by the prompt author.
+
+Conversation transcripts, logs, bundles and patches may contain secrets. Runtime files are ignored by Git and sensitive files are created with restrictive permissions where supported. Keep API keys in environment variables or ignored `.env` files. Never embed tokens in tracked configuration, remote URLs or examples.
+
+Report vulnerabilities privately using the repository's security reporting channel when enabled, or contact the maintainer through the hosting profile. Do not include live credentials in reports. V1 receives fixes for reproducible security defects.

package/dist/application/campaign.d.ts

@@ -0,0 +1,33 @@
+import type { AgentAdapter } from "../domain/ports.ts";
+import type { Backlog } from "../domain/backlog.ts";
+import { type SandboxOptions } from "./outpost.ts";
+export interface CampaignEvent {
+    readonly phase: "backlog" | "plan" | "implement" | "review" | "merge" | "close";
+    readonly cycle: number;
+    readonly issue?: string;
+}
+export interface CampaignOptions extends Omit<SandboxOptions, "workspace" | "branch" | "agent"> {
+    readonly agent: AgentAdapter;
+    readonly backlog: Backlog;
+    readonly planner?: AgentAdapter | false;
+    readonly reviewer?: AgentAdapter | false;
+    readonly merger?: AgentAdapter;
+    readonly cycles?: number;
+    readonly concurrency?: number;
+    readonly implementationPasses?: number;
+    readonly reviewPasses?: number;
+    readonly standards?: string;
+    readonly observe?: (event: CampaignEvent) => void;
+}
+export interface IssueOutcome {
+    readonly id: string;
+    readonly branch: string;
+    readonly state: "empty" | "failed" | "merged";
+    readonly error?: unknown;
+}
+export interface CampaignResult {
+    readonly cycles: number;
+    readonly reason: "empty" | "blocked" | "no-progress" | "limit";
+    readonly issues: readonly IssueOutcome[];
+}
+export declare function campaign(options: CampaignOptions): Promise<CampaignResult>;