@intentius/chant-lexicon-fountain 0.89.0 → 0.90.0

package/dist/composites/box.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Box — a persistent machine that serves an app repo and its tools (#2705).
+ *
+ * A box is an `Environment` whose repositories hold the app repo and whose
+ * `setup_script` provisions the machine (for an arugula studio box, the
+ * studio's `box/provision-template.sh`), an `Agent` on a persistent sandbox
+ * provisioned from it, and optionally a `Vault` for the secrets every box of
+ * this kind shares.
+ *
+ * ```ts
+ * export const { environment, agent, vault } = Box({
+ *   name: "studio-box",
+ *   repo: { url: "https://github.com/arugula-salad/studio", ref: "main" },
+ *   setupScript: readFileSync("box/provision-template.sh", "utf8"),
+ *   permissionPolicy: { default: "auto_allow" },
+ *   allowedHosts: ["registry.npmjs.org", "github.com"],
+ *   vault: { secrets: [{ key: "STUDIO_SECRET", value: process.env.STUDIO_SECRET! }] },
+ * });
+ * ```
+ *
+ * Beside `Steward`: a steward is an environment's one writer, an `acp` agent
+ * whose every turn is a chant command line, bound to a teammate with a
+ * standing thread and schedules. A box is where people and their agents work
+ * on an app: a conversational runtime (`claude` by default), the app repo
+ * cloned in, the provisioning script run as setup, and one served port. It
+ * declares no teammate and no schedule, and nothing here starts a
+ * conversation. Starting and reaping a box stays a runtime act, as it is in
+ * hud's box runtime.
+ *
+ * The defaults are the closed ones, as `ConciergeStack`'s are, and loosening
+ * one is a visible parameter: networking is `limited` with an empty allowlist
+ * until `allowedHosts` names hosts or `unrestrictedNetworking: true` opens it
+ * (which FTN011 then warns about); `allowed_vault_ids` holds the box's own
+ * vault, or nothing, until `allowedVaults` widens it. `permission_policy` has
+ * no default at all, because fountain's unset policy is `auto_allow` and that
+ * should be a choice someone wrote down.
+ *
+ * ## The port
+ *
+ * fountain's `Environment` and `Agent` have no field for a served port (the
+ * pinned spec, v0.21.0). The port is recorded in the metadata of both, under
+ * `box-port`, and returned as `port`, so whatever builds the box's URL reads
+ * it from the declaration or from fountain's own record without a guess.
+ */
+import { Agent, Environment, Vault } from "../generated/index.js";
+/** The metadata key a box's served port is recorded under, on its Environment and Agent. */
+export declare const BOX_PORT_METADATA_KEY = "box-port";
+/** The port a box serves when none is given: the door's. */
+export declare const BOX_DEFAULT_PORT = 8080;
+/** Where the app repo is cloned when no `mountPath` is given. */
+export declare const BOX_DEFAULT_MOUNT_PATH = "/workspace/app";
+/** A permission verdict, or a number of seconds under the `ask_timeout` key. */
+export type BoxPermissionPolicy = Record<string, "ask" | "auto_allow" | "auto_deny" | number>;
+/** The app repo the box serves. Shape of fountain's `Repository`. */
+export interface BoxRepositoryOpts {
+    /** https clone url. */
+    url: string;
+    /** Absolute path the repo is cloned to. Default `/workspace/app`. */
+    mountPath?: string;
+    /** Branch or tag. The default branch when omitted. */
+    ref?: string;
+    /** Name of the secret holding a clone token. Required for a private repo. */
+    secretKey?: string;
+}
+/** The secrets every box of this kind shares, held in a Vault of the box's own. */
+export interface BoxVaultOpts {
+    /** Vault name. Default `<name>-secrets`. */
+    name?: string;
+    description?: string;
+    /** Written at apply. A reference that resolves at build, never a literal (FTN001). */
+    secrets?: {
+        key: string;
+        value: string;
+    }[];
+}
+export interface BoxOpts {
+    /** The Agent's name. The Environment is `<name>-env`. */
+    name: string;
+    /** The app repo the box serves, cloned into the sandbox before setup runs. */
+    repo: BoxRepositoryOpts;
+    /** The provisioning script's text, run as the Environment's `setup_script`. */
+    setupScript: string;
+    /** Setup exec timeout, 1 to 900 seconds (FTN024). fountain's default is 120. */
+    setupTimeoutSeconds?: number;
+    /** Agent runtime. Default `claude`. */
+    runtime?: "claude" | "codex" | "gemini" | "opencode";
+    /** Canonical provider/model_id. Omitted, fountain's default for the runtime. */
+    model?: string;
+    /** Per-tool permission policy. Required: fountain's unset policy is `auto_allow`. */
+    permissionPolicy: BoxPermissionPolicy;
+    /** Environment packages, passed through. */
+    packages?: Record<string, unknown>;
+    /** Environment variables, passed through. Not for secrets: use `vault`. */
+    envVars?: Record<string, string>;
+    /** Egress allowlist under `limited` networking. Default [], deny-all. */
+    allowedHosts?: string[];
+    /** Open the sandbox's network. FTN011 warns on it. Refused with `allowedHosts`. */
+    unrestrictedNetworking?: boolean;
+    /** Declare a Vault for the box's shared secrets. */
+    vault?: BoxVaultOpts;
+    /**
+     * Vaults a conversation may attach. Default: the box's own vault, or none.
+     * `"any"` leaves the list unset, which fountain reads as any vault the
+     * tenant owns: what a runtime that makes a vault per box (hud's) needs.
+     */
+    allowedVaults?: "any" | Array<InstanceType<typeof Vault> | string>;
+    /** The port the box serves. Default 8080, the door's. Recorded as `box-port` metadata. */
+    port?: number;
+    system?: string;
+    skills?: Array<Record<string, unknown>>;
+    mcpServers?: Record<string, unknown>;
+    /** Extra metadata, merged over the ownership marker on every resource the box declares. */
+    metadata?: Record<string, unknown>;
+}
+export interface BoxResources {
+    environment: InstanceType<typeof Environment>;
+    agent: InstanceType<typeof Agent>;
+    vault?: InstanceType<typeof Vault>;
+    /** The served port, as recorded under `box-port`. */
+    port: number;
+}
+export declare function Box(opts: BoxOpts): BoxResources;
+//# sourceMappingURL=box.d.ts.map

package/dist/composites/box.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"box.d.ts","sourceRoot":"","sources":["../../src/composites/box.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE/D,4FAA4F;AAC5F,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAEhD,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AAEvD,gFAAgF;AAChF,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,GAAG,YAAY,GAAG,WAAW,GAAG,MAAM,CAAC,CAAC;AAE9F,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sFAAsF;IACtF,OAAO,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,OAAO;IACtB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,IAAI,EAAE,iBAAiB,CAAC;IACxB,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,uCAAuC;IACvC,OAAO,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC;IACrD,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,gBAAgB,EAAE,mBAAmB,CAAC;IACtC,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,mFAAmF;IACnF,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,oDAAoD;IACpD,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,aAAa,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,YAAY,CAAC,OAAO,KAAK,CAAC,GAAG,MAAM,CAAC,CAAC;IACnE,0FAA0F;IAC1F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,YAAY,CAAC,OAAO,WAAW,CAAC,CAAC;IAC9C,KAAK,EAAE,YAAY,CAAC,OAAO,KAAK,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,YAAY,CAAC,OAAO,KAAK,CAAC,CAAC;IACnC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,GAAG,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,CAoE/C"}

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export { ConciergeStack } from "./composites/concierge-stack.js";
 export type { ConciergeStackOpts, ConciergeStackResources } from "./composites/concierge-stack.js";
 export { Steward, stewardForOp, STEWARD_RUNTIME_COMMAND } from "./composites/steward.js";
 export type { StewardOp, StewardOpts, StewardResources, StewardWebhookOpts } from "./composites/steward.js";
+export { Box, BOX_PORT_METADATA_KEY, BOX_DEFAULT_PORT, BOX_DEFAULT_MOUNT_PATH } from "./composites/box.js";
+export type { BoxOpts, BoxResources, BoxRepositoryOpts, BoxVaultOpts, BoxPermissionPolicy } from "./composites/box.js";
 export { acpCommandGroup } from "./acp/index.js";
 export { AcpServer } from "./acp/server.js";
 export type { AcpServerOptions } from "./acp/server.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAIlD,OAAO,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAC9D,YAAY,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EACL,8BAA8B,EAC9B,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAG9B,cAAc,mBAAmB,CAAC;AAIlC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACxF,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAInH,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAIhE,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,8BAA8B,GAC/B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,wBAAwB,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG5F,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAChG,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACtF,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAIzG,OAAO,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAIlD,OAAO,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAC9D,YAAY,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EACL,8BAA8B,EAC9B,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAG9B,cAAc,mBAAmB,CAAC;AAIlC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACxF,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAInH,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAIhE,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,8BAA8B,GAC/B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,wBAAwB,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG5F,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAChG,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACtF,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACzG,OAAO,EAAE,GAAG,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AACxG,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAIpH,OAAO,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "33090e28ff6ca41325918fd9fc2c7ceb354679308b1634834a6098b0fc03e364",
+    "manifest.json": "574b2bc5f0f9b2c0125e34c21d47fbdc1f154e558f9ff61e585a41b0c2c913da",
     "meta.json": "3301437a2a56eaf1a5cc8f6eabb18a40767f916e09701b2d9bf20aba4066738c",
     "types/index.d.ts": "cf6b634fe0a8e9e96f1d9d07e3df53838def2683dc93dbe3c7fd971c6d3908ae",
     "rules/ftn001-no-secret-literals.ts": "a417b194cd7039911cca9a0f14c49b042dfa6b1ee48517f7c2e22b16590a8599",
@@ -21,7 +21,7 @@
     "skills/chant-fountain.md": "906a312756a02c88de634915f63ab4dfe1b1078ff4d8cfb4b6dc97eec14bc237",
     "skills/chant-fountain-secrets.md": "40aa847d62547581bebdde630b54796c4e1cbf498869392e0d396d96a75c0ab6",
     "skills/chant-fountain-ops.md": "4e72f0a0c7477a9e98f85ea45e49ba69e8a699f9c13ba0f0cf1cb20a88151373",
-    "skills/chant-fountain-locked-sandboxes.md": "de82f06cb3a08ba6bf3ae45fb9869e21d6da18b9ebe0fc769da8aebaceea7dd1"
+    "skills/chant-fountain-locked-sandboxes.md": "14def4c68b13c2bd561f75819b188968cec85073a5dd8b59e91708e1af26daae"
   },
-  "composite": "916a499797c8130a9fdcba5f55f63449f67fee870a5b93466b7b00f7515fb5a9"
+  "composite": "21bc34705dabf0dfe5a50d7bb81bf76d54cf4647b5f5790cd66e54de1d4f9a5f"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "fountain",
-  "version": "0.89.0",
+  "version": "0.90.0",
   "chantVersion": ">=0.1.0",
   "namespace": "Fountain",
   "specVersion": "v0.21.0"

package/dist/op/activities/fountain-run.d.ts

@@ -1,15 +1,62 @@
 /**
  * fountainRun — start a conversation from a declared Agent and follow it
- * to a terminal status.
+ * to the end of its turn.
  *
  * Conversations are runs, not declarables (the one fountain kind the
  * lexicon deliberately does not model as a resource). This op is the
- * imperative half: resolve the agent by name, POST the conversation,
- * poll until `completed | failed | timed_out | terminated`, and terminate
- * on deadline so a hung run never outlives the op that started it.
+ * imperative half: resolve the agent by name, POST the conversation, and
+ * poll until the turn is done.
+ *
+ * What "done" means depends on the agent's `sandbox_mode` (#2718). An
+ * `ephemeral` conversation's machine is its own and this polls the
+ * conversation's own status to `completed | failed | timed_out |
+ * terminated` — none of which a running server's conversation status
+ * actually reaches on its own, so in practice this waits out `timeoutMs`
+ * and terminates, as it always has. A `persistent` agent's conversation
+ * (`Steward`, and `Box` from #2705) shares one machine across every
+ * conversation on it, and a turn ending there does not tear the sandbox
+ * down: the conversation settles on `idle`, not on any of the four
+ * statuses above. Waiting for one of those on a persistent agent is the
+ * bug this op used to have — it waited out the whole deadline after the
+ * turn had already finished, then terminated a machine that was meant to
+ * persist. For `idle`, this instead reads the finished turn back
+ * (`GET .../turns`) and returns its own outcome (`completed | failed |
+ * interrupted` — fountain's `end_turn` block, or an error) without
+ * terminating anything.
+ *
+ * Terminating the conversation's machine on deadline (a hung run should
+ * not outlive the op that started it) still happens whenever the turn has
+ * not ended — for either sandbox mode. `terminate` makes the choice
+ * explicit rather than leaving it implicit in `sandbox_mode`.
  */
 import { type FountainHttp, type FountainConnectionDeps } from "./fountain-apply.js";
+/**
+ * Conversation statuses that end an *ephemeral* agent's run. `completed`
+ * and `timed_out` are not values fountain's `Conversation.status` takes
+ * today (its enum is `pending | running | idle | failed | terminated`) —
+ * they are kept so a server that starts reporting them is handled without
+ * a further change here.
+ */
 export declare const TERMINAL_STATUSES: Set<string>;
+/**
+ * Conversation statuses that end a *persistent* agent's run: everything
+ * {@link TERMINAL_STATUSES} does, plus `idle` — the status a persistent
+ * conversation settles on once its turn ends, machine still up (#2718).
+ */
+export declare const PERSISTENT_DONE_STATUSES: Set<string>;
+/**
+ * How `fountainRun` treats the conversation's machine once its wait ends
+ * (#2718).
+ *
+ * - `on-deadline` — terminate only when `timeoutMs` is hit with the turn
+ *   still unfinished, never on a turn that ended cleanly. This was
+ *   `fountainRun`'s only behavior before this option existed.
+ * - `never` — never terminate, even past the deadline; the caller, or
+ *   fountain's own idle/max-lifetime bounds, is responsible for the machine.
+ * - `always` — terminate whenever the wait ends, whether the turn ended
+ *   cleanly or the deadline fired.
+ */
+export type TerminatePolicy = "never" | "on-deadline" | "always";
 export interface FountainRunArgs {
     /** Agent name (resolved against /api/agents) or a raw agent id. */
     agent: string;
@@ -26,19 +73,43 @@ export interface FountainRunArgs {
     profile?: string;
     /** Project root `chant.config.ts` is read from. Default: process.cwd(). */
     cwd?: string;
-    /** Give up (and terminate the conversation) after this long. Default 10 min. */
+    /** Give up after this long. Default 10 min. */
     timeoutMs?: number;
     /** Poll interval. Default 5s. */
     pollMs?: number;
+    /**
+     * When to terminate the conversation's machine (#2718). Default follows
+     * the agent's `sandbox_mode`: `on-deadline` for `ephemeral` (unchanged),
+     * `never` for `persistent` — its machine is a home meant to outlive the
+     * conversation, so a run that hits its deadline leaves it be unless this
+     * says otherwise.
+     */
+    terminate?: TerminatePolicy;
     /** Injectable clock/sleep for tests. */
     sleep?: (ms: number) => Promise<void>;
 }
 export interface FountainRunResult {
     conversationId: string;
+    /**
+     * The run's outcome. For a persistent agent whose turn ended, this is the
+     * turn's own status (`completed | failed | interrupted`); otherwise it is
+     * the conversation's status when the wait ended (`terminated` on a
+     * deadline).
+     */
     status: string;
-    /** True when the op hit its deadline and terminated the conversation. */
+    /** True when the agent's `sandbox_mode` resolved to `persistent`. */
+    persistent: boolean;
+    /** True when the op hit its deadline with the turn still unfinished. */
     terminatedByDeadline: boolean;
 }
+export interface ResolvedAgent {
+    id: string;
+    /** `ephemeral` or `persistent`; fountain's own default is `ephemeral`. */
+    sandboxMode: string;
+}
+/** Resolve an agent by name or id, along with its `sandbox_mode`. */
+export declare function resolveAgent(http: FountainHttp, agent: string): Promise<ResolvedAgent>;
+/** Agent id only — the common case, and the one call sites outside this file use. */
 export declare function resolveAgentId(http: FountainHttp, agent: string): Promise<string>;
 export declare function fountainRun(args: FountainRunArgs, http?: FountainHttp, deps?: FountainConnectionDeps): Promise<FountainRunResult>;
 //# sourceMappingURL=fountain-run.d.ts.map

package/dist/op/activities/fountain-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fountain-run.d.ts","sourceRoot":"","sources":["../../../src/op/activities/fountain-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAE1B,eAAO,MAAM,iBAAiB,aAA8D,CAAC;AAE7F,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQvF;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,eAAe,EACrB,IAAI,CAAC,EAAE,YAAY,EACnB,IAAI,CAAC,EAAE,sBAAsB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAuC5B"}
+{"version":3,"file":"fountain-run.d.ts","sourceRoot":"","sources":["../../../src/op/activities/fountain-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAE1B;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,aAA8D,CAAC;AAE7F;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,aAA0C,CAAC;AAKhF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,aAAa,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,wCAAwC;IACxC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,UAAU,EAAE,OAAO,CAAC;IACpB,wEAAwE;IACxE,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAID,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qEAAqE;AACrE,wBAAsB,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAe5F;AAED,qFAAqF;AACrF,wBAAsB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGvF;AAeD,wBAAsB,WAAW,CAC/B,IAAI,EAAE,eAAe,EACrB,IAAI,CAAC,EAAE,YAAY,EACnB,IAAI,CAAC,EAAE,sBAAsB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAwD5B"}

package/dist/op/activities/index.d.ts

@@ -6,6 +6,6 @@
  */
 export { fountainApply, resolveEndpoint, resolveToken, resolveConnection, parseManifest, toApplyPayload, isChantOwned, defaultFountainHttp, DEFAULT_FOUNTAIN_BASE_URL, OWNERSHIP_KEY, OWNERSHIP_VALUE, } from "./fountain-apply.js";
 export type { FountainApplyArgs, FountainApplySummary, ManifestResource, FountainHttp, FountainConnectionDeps, } from "./fountain-apply.js";
-export { fountainRun, resolveAgentId, TERMINAL_STATUSES } from "./fountain-run.js";
-export type { FountainRunArgs, FountainRunResult } from "./fountain-run.js";
+export { fountainRun, resolveAgent, resolveAgentId, TERMINAL_STATUSES, PERSISTENT_DONE_STATUSES, } from "./fountain-run.js";
+export type { FountainRunArgs, FountainRunResult, ResolvedAgent, TerminatePolicy } from "./fountain-run.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/op/activities/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,aAAa,EACb,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,EACzB,aAAa,EACb,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAChF,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,aAAa,EACb,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,EACzB,aAAa,EACb,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,WAAW,EACX,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/skills/chant-fountain-locked-sandboxes.md

@@ -31,4 +31,4 @@ The environment's config is the enforcement boundary, so watch it: `chant lifecy
 
 ## Running conversations
 
-Conversations are runs, not resources. Use the `fountainRun` activity: resolves the agent by name, starts (optionally with a prompt and an allowlisted vault), polls to `completed | failed | timed_out`, and terminates at its deadline so a hung sandbox never outlives the op. Multi-turn interaction (follow-up prompts, interrupt) is fountain's own conversations API — keep chant to the lifecycle edges.
+Conversations are runs, not resources. Use the `fountainRun` activity: resolves the agent by name, starts (optionally with a prompt and an allowlisted vault), and waits for the turn to end. What "end" means, and what happens to the machine, follows the agent's `sandbox_mode`: an `ephemeral` agent's conversation is polled for a terminal status and terminated on deadline, same as before; a `persistent` agent's (a `Steward` or `Box`) conversation settles on `idle` once its turn ends — machine still up for the next turn — so `fountainRun` reads the turn back and returns its outcome (`completed | failed | interrupted`) without terminating anything, by default. Pass `terminate: "on-deadline" | "always"` to opt a persistent agent's run back into ending the machine. Multi-turn interaction (follow-up prompts, interrupt) is fountain's own conversations API — keep chant to the lifecycle edges.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-fountain",
-  "version": "0.89.0",
+  "version": "0.90.0",
   "type": "module",
   "description": "Fountain lexicon for chant — sandboxed agent environments, vaults, and agents as typed estate",
   "license": "Apache-2.0",
@@ -50,7 +50,7 @@
     "bundle": "tsx src/package-cli.ts"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.89.0",
+    "@intentius/chant": "^0.90.0",
     "typescript": "^5.9.3",
     "zod": "^4.3.6"
   },

package/src/composites/box.ts

@@ -0,0 +1,197 @@
+/**
+ * Box — a persistent machine that serves an app repo and its tools (#2705).
+ *
+ * A box is an `Environment` whose repositories hold the app repo and whose
+ * `setup_script` provisions the machine (for an arugula studio box, the
+ * studio's `box/provision-template.sh`), an `Agent` on a persistent sandbox
+ * provisioned from it, and optionally a `Vault` for the secrets every box of
+ * this kind shares.
+ *
+ * ```ts
+ * export const { environment, agent, vault } = Box({
+ *   name: "studio-box",
+ *   repo: { url: "https://github.com/arugula-salad/studio", ref: "main" },
+ *   setupScript: readFileSync("box/provision-template.sh", "utf8"),
+ *   permissionPolicy: { default: "auto_allow" },
+ *   allowedHosts: ["registry.npmjs.org", "github.com"],
+ *   vault: { secrets: [{ key: "STUDIO_SECRET", value: process.env.STUDIO_SECRET! }] },
+ * });
+ * ```
+ *
+ * Beside `Steward`: a steward is an environment's one writer, an `acp` agent
+ * whose every turn is a chant command line, bound to a teammate with a
+ * standing thread and schedules. A box is where people and their agents work
+ * on an app: a conversational runtime (`claude` by default), the app repo
+ * cloned in, the provisioning script run as setup, and one served port. It
+ * declares no teammate and no schedule, and nothing here starts a
+ * conversation. Starting and reaping a box stays a runtime act, as it is in
+ * hud's box runtime.
+ *
+ * The defaults are the closed ones, as `ConciergeStack`'s are, and loosening
+ * one is a visible parameter: networking is `limited` with an empty allowlist
+ * until `allowedHosts` names hosts or `unrestrictedNetworking: true` opens it
+ * (which FTN011 then warns about); `allowed_vault_ids` holds the box's own
+ * vault, or nothing, until `allowedVaults` widens it. `permission_policy` has
+ * no default at all, because fountain's unset policy is `auto_allow` and that
+ * should be a choice someone wrote down.
+ *
+ * ## The port
+ *
+ * fountain's `Environment` and `Agent` have no field for a served port (the
+ * pinned spec, v0.21.0). The port is recorded in the metadata of both, under
+ * `box-port`, and returned as `port`, so whatever builds the box's URL reads
+ * it from the declaration or from fountain's own record without a guess.
+ */
+
+import { Agent, Environment, Vault } from "../generated/index";
+
+/** The metadata key a box's served port is recorded under, on its Environment and Agent. */
+export const BOX_PORT_METADATA_KEY = "box-port";
+
+/** The port a box serves when none is given: the door's. */
+export const BOX_DEFAULT_PORT = 8080;
+
+/** Where the app repo is cloned when no `mountPath` is given. */
+export const BOX_DEFAULT_MOUNT_PATH = "/workspace/app";
+
+/** A permission verdict, or a number of seconds under the `ask_timeout` key. */
+export type BoxPermissionPolicy = Record<string, "ask" | "auto_allow" | "auto_deny" | number>;
+
+/** The app repo the box serves. Shape of fountain's `Repository`. */
+export interface BoxRepositoryOpts {
+  /** https clone url. */
+  url: string;
+  /** Absolute path the repo is cloned to. Default `/workspace/app`. */
+  mountPath?: string;
+  /** Branch or tag. The default branch when omitted. */
+  ref?: string;
+  /** Name of the secret holding a clone token. Required for a private repo. */
+  secretKey?: string;
+}
+
+/** The secrets every box of this kind shares, held in a Vault of the box's own. */
+export interface BoxVaultOpts {
+  /** Vault name. Default `<name>-secrets`. */
+  name?: string;
+  description?: string;
+  /** Written at apply. A reference that resolves at build, never a literal (FTN001). */
+  secrets?: { key: string; value: string }[];
+}
+
+export interface BoxOpts {
+  /** The Agent's name. The Environment is `<name>-env`. */
+  name: string;
+  /** The app repo the box serves, cloned into the sandbox before setup runs. */
+  repo: BoxRepositoryOpts;
+  /** The provisioning script's text, run as the Environment's `setup_script`. */
+  setupScript: string;
+  /** Setup exec timeout, 1 to 900 seconds (FTN024). fountain's default is 120. */
+  setupTimeoutSeconds?: number;
+  /** Agent runtime. Default `claude`. */
+  runtime?: "claude" | "codex" | "gemini" | "opencode";
+  /** Canonical provider/model_id. Omitted, fountain's default for the runtime. */
+  model?: string;
+  /** Per-tool permission policy. Required: fountain's unset policy is `auto_allow`. */
+  permissionPolicy: BoxPermissionPolicy;
+  /** Environment packages, passed through. */
+  packages?: Record<string, unknown>;
+  /** Environment variables, passed through. Not for secrets: use `vault`. */
+  envVars?: Record<string, string>;
+  /** Egress allowlist under `limited` networking. Default [], deny-all. */
+  allowedHosts?: string[];
+  /** Open the sandbox's network. FTN011 warns on it. Refused with `allowedHosts`. */
+  unrestrictedNetworking?: boolean;
+  /** Declare a Vault for the box's shared secrets. */
+  vault?: BoxVaultOpts;
+  /**
+   * Vaults a conversation may attach. Default: the box's own vault, or none.
+   * `"any"` leaves the list unset, which fountain reads as any vault the
+   * tenant owns: what a runtime that makes a vault per box (hud's) needs.
+   */
+  allowedVaults?: "any" | Array<InstanceType<typeof Vault> | string>;
+  /** The port the box serves. Default 8080, the door's. Recorded as `box-port` metadata. */
+  port?: number;
+  system?: string;
+  skills?: Array<Record<string, unknown>>;
+  mcpServers?: Record<string, unknown>;
+  /** Extra metadata, merged over the ownership marker on every resource the box declares. */
+  metadata?: Record<string, unknown>;
+}
+
+export interface BoxResources {
+  environment: InstanceType<typeof Environment>;
+  agent: InstanceType<typeof Agent>;
+  vault?: InstanceType<typeof Vault>;
+  /** The served port, as recorded under `box-port`. */
+  port: number;
+}
+
+export function Box(opts: BoxOpts): BoxResources {
+  const port = opts.port ?? BOX_DEFAULT_PORT;
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Box "${opts.name}": port ${port} is not a TCP port (1 to 65535)`);
+  }
+  if (opts.unrestrictedNetworking && opts.allowedHosts !== undefined) {
+    throw new Error(
+      `Box "${opts.name}": allowedHosts and unrestrictedNetworking together — ` +
+        `an allowlist means nothing on an open network. Pass one.`,
+    );
+  }
+  if (!opts.setupScript.trim()) {
+    throw new Error(`Box "${opts.name}": setupScript is empty — a box is provisioned by its setup script`);
+  }
+
+  const owned = { "managed-by": "chant", ...(opts.metadata ?? {}) };
+  const metadata = { ...owned, [BOX_PORT_METADATA_KEY]: port };
+
+  const repository = {
+    url: opts.repo.url,
+    mount_path: opts.repo.mountPath ?? BOX_DEFAULT_MOUNT_PATH,
+    ...(opts.repo.ref !== undefined ? { ref: opts.repo.ref } : {}),
+    ...(opts.repo.secretKey !== undefined ? { secret_key: opts.repo.secretKey } : {}),
+  };
+
+  const environment = new Environment({
+    name: `${opts.name}-env`,
+    repositories: [repository],
+    setup_script: opts.setupScript,
+    ...(opts.setupTimeoutSeconds !== undefined ? { setup_timeout_seconds: opts.setupTimeoutSeconds } : {}),
+    ...(opts.packages ? { packages: opts.packages } : {}),
+    ...(opts.envVars ? { env_vars: opts.envVars } : {}),
+    ...(opts.unrestrictedNetworking
+      ? { networking_type: "unrestricted" as const }
+      : { networking_type: "limited" as const, networking_config: { allowed_hosts: opts.allowedHosts ?? [] } }),
+    metadata,
+  });
+
+  const vault = opts.vault
+    ? new Vault({
+        name: opts.vault.name ?? `${opts.name}-secrets`,
+        ...(opts.vault.description !== undefined ? { description: opts.vault.description } : {}),
+        ...(opts.vault.secrets ? { secrets: opts.vault.secrets } : {}),
+        metadata: owned,
+      })
+    : undefined;
+
+  // A Vault declaration rather than its `.id`, as in Steward: the manifest's
+  // reference form is the resource's name (FTN021), and an AttrRef would
+  // serialize to the chant export name instead.
+  const allowedVaults =
+    opts.allowedVaults === "any" ? undefined : (opts.allowedVaults ?? (vault ? [vault] : []));
+
+  const agent = new Agent({
+    name: opts.name,
+    runtime: opts.runtime ?? "claude",
+    ...(opts.model !== undefined ? { model: opts.model } : {}),
+    sandbox_mode: "persistent",
+    environment,
+    permission_policy: opts.permissionPolicy,
+    ...(allowedVaults !== undefined ? { allowed_vault_ids: allowedVaults } : {}),
+    ...(opts.skills ? { skills: opts.skills } : {}),
+    ...(opts.mcpServers ? { mcp_servers: opts.mcpServers } : {}),
+    ...(opts.system !== undefined ? { system: opts.system } : {}),
+    metadata,
+  });
+
+  return { environment, agent, ...(vault ? { vault } : {}), port };
+}

package/src/composites/composites.test.ts

@@ -2,6 +2,9 @@ import { beforeEach, describe, expect, it } from "vitest";
 import { WatchOp, type OpConfig } from "@intentius/chant/op";
 import { ConciergeStack } from "./concierge-stack";
 import { Steward, stewardForOp, __resetStewardsForTests } from "./steward";
+import { Box, BOX_PORT_METADATA_KEY } from "./box";
+import { postSynthChecks } from "../lint/post-synth/index";
+import spec from "../spec/fountain-openapi.snapshot.json";
 import { Environment, Vault } from "../generated/index";
 import { fountainSerializer } from "../serializer";
 import type { Declarable } from "@intentius/chant";
@@ -234,3 +237,133 @@ describe("Steward", () => {
     expect(yaml).toMatch(/allowed_vault_ids:\n\s+- prod-creds/);
   });
 });
+
+// ── Box ───────────────────────────────────────────────────────────────────
+
+describe("Box", () => {
+  const base = {
+    name: "studio-box",
+    repo: { url: "https://github.com/arugula-salad/studio" },
+    setupScript: "#!/bin/bash\nexec ~/box/provision-template.sh\n",
+    permissionPolicy: { default: "auto_allow" as const },
+  };
+
+  it("declares a closed Environment and a persistent claude Agent, with the port in metadata", () => {
+    const { environment, agent, vault, port } = Box(base);
+
+    const env = props(environment);
+    expect(env.name).toBe("studio-box-env");
+    expect(env.repositories).toEqual([{ url: "https://github.com/arugula-salad/studio", mount_path: "/workspace/app" }]);
+    expect(env.setup_script).toBe(base.setupScript);
+    expect(env.networking_type).toBe("limited");
+    expect(env.networking_config).toEqual({ allowed_hosts: [] });
+    expect(env.metadata).toEqual({ "managed-by": "chant", [BOX_PORT_METADATA_KEY]: 8080 });
+
+    const a = props(agent);
+    expect(a.name).toBe("studio-box");
+    expect(a.runtime).toBe("claude");
+    expect(a.model).toBeUndefined();
+    expect(a.sandbox_mode).toBe("persistent");
+    expect(a.environment).toBe(environment);
+    expect(a.permission_policy).toEqual({ default: "auto_allow" });
+    expect(a.allowed_vault_ids).toEqual([]);
+    expect(a.metadata).toEqual({ "managed-by": "chant", "box-port": 8080 });
+
+    expect(vault).toBeUndefined();
+    expect(port).toBe(8080);
+  });
+
+  it("declares the shared vault and scopes the agent to it", () => {
+    const { agent, vault } = Box({
+      ...base,
+      vault: { secrets: [{ key: "STUDIO_SECRET", value: "${STUDIO_SECRET}" }] },
+    });
+    expect(props(vault).name).toBe("studio-box-secrets");
+    expect(props(vault).secrets).toEqual([{ key: "STUDIO_SECRET", value: "${STUDIO_SECRET}" }]);
+    expect(props(vault).metadata).toEqual({ "managed-by": "chant" });
+    expect(props(agent).allowed_vault_ids).toEqual([vault]);
+  });
+
+  it("loosening is a visible parameter", () => {
+    const open = Box({
+      ...base,
+      runtime: "codex",
+      model: "openai/gpt-5",
+      port: 3000,
+      unrestrictedNetworking: true,
+      allowedVaults: "any",
+      repo: { url: "https://github.com/o/app", mountPath: "/srv/app", ref: "v1", secretKey: "GH_TOKEN" },
+      envVars: { NODE_ENV: "production" },
+      packages: { apt: ["podman"] },
+      setupTimeoutSeconds: 900,
+      metadata: { team: "studio" },
+    });
+    const env = props(open.environment);
+    expect(env.networking_type).toBe("unrestricted");
+    expect(env.networking_config).toBeUndefined();
+    expect(env.repositories).toEqual([{ url: "https://github.com/o/app", mount_path: "/srv/app", ref: "v1", secret_key: "GH_TOKEN" }]);
+    expect(env.env_vars).toEqual({ NODE_ENV: "production" });
+    expect(env.packages).toEqual({ apt: ["podman"] });
+    expect(env.setup_timeout_seconds).toBe(900);
+    expect(env.metadata).toEqual({ "managed-by": "chant", team: "studio", "box-port": 3000 });
+    const a = props(open.agent);
+    expect(a.runtime).toBe("codex");
+    expect(a.model).toBe("openai/gpt-5");
+    // "any" leaves the list unset: fountain reads null as any vault the tenant owns.
+    expect("allowed_vault_ids" in a).toBe(false);
+    expect(open.port).toBe(3000);
+
+    const listed = Box({ ...base, allowedHosts: ["registry.npmjs.org"] });
+    expect(props(listed.environment).networking_config).toEqual({ allowed_hosts: ["registry.npmjs.org"] });
+  });
+
+  it("refuses what it cannot mean", () => {
+    expect(() => Box({ ...base, port: 0 })).toThrow(/not a TCP port/);
+    expect(() => Box({ ...base, port: 8080.5 })).toThrow(/not a TCP port/);
+    expect(() => Box({ ...base, unrestrictedNetworking: true, allowedHosts: ["github.com"] })).toThrow(
+      /allowedHosts and unrestrictedNetworking/,
+    );
+    expect(() => Box({ ...base, setupScript: "  " })).toThrow(/setupScript is empty/);
+  });
+
+  it("serializes to a manifest whose specs the pinned API accepts, clean under every post-synth check", () => {
+    const { environment, agent, vault } = Box({
+      ...base,
+      allowedHosts: ["registry.npmjs.org", "github.com"],
+      vault: { secrets: [{ key: "STUDIO_SECRET", value: "${STUDIO_SECRET}" }] },
+    });
+    const entities = new Map<string, Declarable>([
+      ["boxAgent", agent as unknown as Declarable],
+      ["boxVault", vault as unknown as Declarable],
+      ["boxEnv", environment as unknown as Declarable],
+    ]);
+
+    const yaml = fountainSerializer.serialize(entities) as string;
+    expect([...yaml.matchAll(/^kind: (\w+)$/gm)].map((m) => m[1])).toEqual(["Environment", "Vault", "Agent"]);
+    expect(yaml).toContain("environment: studio-box-env");
+    expect(yaml).toMatch(/allowed_vault_ids:\n\s+- studio-box-secrets/);
+    expect(yaml).toContain("box-port: 8080");
+
+    // Every spec key is a field of the pinned create request, or one of the
+    // two manifest-level forms fountainApply and `fountain apply -f` resolve:
+    // a name reference to the agent's environment, and inline secrets.
+    const schemas = (spec as unknown as { components: { schemas: Record<string, { properties: Record<string, unknown> }> } })
+      .components.schemas;
+    const manifestOnly = new Set(["environment", "secrets"]);
+    for (const [kind, entity] of [
+      ["EnvironmentRequest", environment],
+      ["VaultRequest", vault],
+      ["AgentRequest", agent],
+    ] as const) {
+      const fields = Object.keys(schemas[kind].properties);
+      for (const key of Object.keys(props(entity))) {
+        if (key === "name" || manifestOnly.has(key)) continue;
+        expect(fields, `${kind} has no field ${key}`).toContain(key);
+      }
+    }
+
+    const ctx = { outputs: new Map(), entities, buildResult: { warnings: [], errors: [] } } as unknown as PostSynthContext;
+    const diagnostics = postSynthChecks.flatMap((c) => c.check(ctx));
+    expect(diagnostics).toEqual([]);
+  });
+});

package/src/index.ts

@@ -41,6 +41,8 @@ export { ConciergeStack } from "./composites/concierge-stack";
 export type { ConciergeStackOpts, ConciergeStackResources } from "./composites/concierge-stack";
 export { Steward, stewardForOp, STEWARD_RUNTIME_COMMAND } from "./composites/steward";
 export type { StewardOp, StewardOpts, StewardResources, StewardWebhookOpts } from "./composites/steward";
+export { Box, BOX_PORT_METADATA_KEY, BOX_DEFAULT_PORT, BOX_DEFAULT_MOUNT_PATH } from "./composites/box";
+export type { BoxOpts, BoxResources, BoxRepositoryOpts, BoxVaultOpts, BoxPermissionPolicy } from "./composites/box";
 
 // `chant acp` (#2125) — the ACP server, mounted through the plugin's command
 // group. Exported so an embedder can serve it over its own transport.

package/src/op/activities/fountain-apply.test.ts

@@ -9,7 +9,6 @@ import {
   vaultNameRefs,
   type FountainHttp,
 } from "./fountain-apply";
-import { fountainRun } from "./fountain-run";
 import type { ChantConfig } from "@intentius/chant/config";
 
 interface Call {
@@ -904,56 +903,3 @@ describe("fountainApply — Teammate, Schedule and Webhook", () => {
     ]);
   });
 });
-
-describe("fountainRun", () => {
-  it("resolves the agent by name, starts, and polls to a terminal status", async () => {
-    let polls = 0;
-    const http: FountainHttp = async (method, path, body) => {
-      if (path.startsWith("/api/agents?search=")) {
-        return { status: 200, json: { data: [{ id: "agent-1", name: "researcher" }] } };
-      }
-      if (method === "POST" && path === "/api/conversations") {
-        expect((body as Record<string, unknown>).agent_id).toBe("agent-1");
-        return { status: 201, json: { data: { id: "conv-1" } } };
-      }
-      if (method === "GET" && path === "/api/conversations/conv-1") {
-        polls += 1;
-        return {
-          status: 200,
-          json: { data: { status: polls < 3 ? "running" : "completed" } },
-        };
-      }
-      throw new Error(`unrouted: ${method} ${path}`);
-    };
-
-    const result = await fountainRun(
-      { agent: "researcher", prompt: "hi", pollMs: 1, sleep: async () => {} },
-      http,
-    );
-    expect(result).toEqual({ conversationId: "conv-1", status: "completed", terminatedByDeadline: false });
-  });
-
-  it("terminates the conversation when the deadline passes", async () => {
-    const calls: string[] = [];
-    const http: FountainHttp = async (method, path) => {
-      calls.push(`${method} ${path}`);
-      if (path === "/api/conversations" && method === "POST") {
-        return { status: 201, json: { data: { id: "conv-2" } } };
-      }
-      if (method === "GET") return { status: 200, json: { data: { status: "running" } } };
-      return { status: 200, json: null };
-    };
-
-    const result = await fountainRun(
-      {
-        agent: "123e4567-e89b-42d3-a456-426614174000",
-        timeoutMs: 1,
-        pollMs: 1,
-        sleep: async () => {},
-      },
-      http,
-    );
-    expect(result.terminatedByDeadline).toBe(true);
-    expect(calls).toContain("POST /api/conversations/conv-2/terminate");
-  });
-});

package/src/op/activities/fountain-run.test.ts

@@ -0,0 +1,219 @@
+import { describe, expect, it } from "vitest";
+import { fountainRun, resolveAgent, resolveAgentId } from "./fountain-run";
+import type { FountainHttp } from "./fountain-apply";
+
+describe("resolveAgent", () => {
+  it("resolves by name and reports sandbox_mode from the search result", async () => {
+    const http: FountainHttp = async (method, path) => {
+      if (method === "GET" && path.startsWith("/api/agents?search=")) {
+        return {
+          status: 200,
+          json: { data: [{ id: "agent-1", name: "researcher", sandbox_mode: "persistent" }] },
+        };
+      }
+      throw new Error(`unrouted: ${method} ${path}`);
+    };
+    expect(await resolveAgent(http, "researcher")).toEqual({
+      id: "agent-1",
+      sandboxMode: "persistent",
+    });
+  });
+
+  it("defaults sandbox_mode to ephemeral when the agent omits it", async () => {
+    const http: FountainHttp = async () => ({
+      status: 200,
+      json: { data: [{ id: "agent-1", name: "researcher" }] },
+    });
+    expect(await resolveAgent(http, "researcher")).toEqual({
+      id: "agent-1",
+      sandboxMode: "ephemeral",
+    });
+  });
+
+  it("looks a raw agent id up by GET /api/agents/{id} for its sandbox_mode", async () => {
+    const calls: string[] = [];
+    const http: FountainHttp = async (method, path) => {
+      calls.push(`${method} ${path}`);
+      return { status: 200, json: { data: { id: "123e4567-e89b-42d3-a456-426614174000", sandbox_mode: "persistent" } } };
+    };
+    const resolved = await resolveAgent(http, "123e4567-e89b-42d3-a456-426614174000");
+    expect(resolved).toEqual({ id: "123e4567-e89b-42d3-a456-426614174000", sandboxMode: "persistent" });
+    expect(calls).toEqual(["GET /api/agents/123e4567-e89b-42d3-a456-426614174000"]);
+  });
+});
+
+describe("resolveAgentId", () => {
+  it("returns a raw agent id with no HTTP call", async () => {
+    const http: FountainHttp = async () => {
+      throw new Error("should not be called");
+    };
+    expect(await resolveAgentId(http, "123e4567-e89b-42d3-a456-426614174000")).toBe(
+      "123e4567-e89b-42d3-a456-426614174000",
+    );
+  });
+});
+
+/** A scripted conversation: agent lookup, create, then a fixed sequence of GET replies. */
+function scriptedConversation(opts: {
+  sandboxMode?: string;
+  conversationId: string;
+  statuses: string[];
+  turns?: Array<{ turn_number: number; status: string }>;
+}) {
+  const calls: string[] = [];
+  let statusIndex = 0;
+  const http: FountainHttp = async (method, path, body) => {
+    calls.push(`${method} ${path}`);
+    if (method === "GET" && path.startsWith("/api/agents?search=")) {
+      return {
+        status: 200,
+        json: {
+          data: [{ id: "agent-1", name: "researcher", sandbox_mode: opts.sandboxMode }],
+        },
+      };
+    }
+    if (method === "POST" && path === "/api/conversations") {
+      expect((body as Record<string, unknown>).agent_id).toBe("agent-1");
+      return { status: 201, json: { data: { id: opts.conversationId } } };
+    }
+    if (method === "GET" && path === `/api/conversations/${opts.conversationId}`) {
+      const status = opts.statuses[Math.min(statusIndex, opts.statuses.length - 1)];
+      statusIndex += 1;
+      return { status: 200, json: { data: { status } } };
+    }
+    if (method === "GET" && path === `/api/conversations/${opts.conversationId}/turns`) {
+      return { status: 200, json: { data: opts.turns ?? [] } };
+    }
+    if (method === "POST" && path === `/api/conversations/${opts.conversationId}/terminate`) {
+      return { status: 200, json: null };
+    }
+    throw new Error(`unrouted: ${method} ${path}`);
+  };
+  return { http, calls };
+}
+
+describe("fountainRun — ephemeral (behaves as today, #2718)", () => {
+  it("resolves the agent by name, starts, and polls to a terminal status", async () => {
+    const { http } = scriptedConversation({
+      sandboxMode: "ephemeral",
+      conversationId: "conv-1",
+      statuses: ["running", "running", "completed"],
+    });
+
+    const result = await fountainRun(
+      { agent: "researcher", prompt: "hi", pollMs: 1, sleep: async () => {} },
+      http,
+    );
+    expect(result).toEqual({
+      conversationId: "conv-1",
+      status: "completed",
+      persistent: false,
+      terminatedByDeadline: false,
+    });
+  });
+
+  it("terminates the conversation when the deadline passes", async () => {
+    const { http, calls } = scriptedConversation({
+      sandboxMode: "ephemeral",
+      conversationId: "conv-2",
+      statuses: ["running"],
+    });
+
+    const result = await fountainRun(
+      { agent: "researcher", timeoutMs: 1, pollMs: 1, sleep: async () => {} },
+      http,
+    );
+    expect(result).toEqual({
+      conversationId: "conv-2",
+      status: "terminated",
+      persistent: false,
+      terminatedByDeadline: true,
+    });
+    expect(calls).toContain("POST /api/conversations/conv-2/terminate");
+  });
+});
+
+describe("fountainRun — persistent (#2718)", () => {
+  it("returns the finished turn's outcome once the conversation goes idle, without terminating", async () => {
+    const { http, calls } = scriptedConversation({
+      sandboxMode: "persistent",
+      conversationId: "conv-3",
+      statuses: ["pending", "running", "idle"],
+      turns: [{ turn_number: 1, status: "completed" }],
+    });
+
+    const result = await fountainRun(
+      { agent: "researcher", prompt: "hi", pollMs: 1, sleep: async () => {} },
+      http,
+    );
+    expect(result).toEqual({
+      conversationId: "conv-3",
+      status: "completed",
+      persistent: true,
+      terminatedByDeadline: false,
+    });
+    expect(calls).not.toContain("POST /api/conversations/conv-3/terminate");
+  });
+
+  it("reports a failed turn's outcome", async () => {
+    const { http } = scriptedConversation({
+      sandboxMode: "persistent",
+      conversationId: "conv-4",
+      statuses: ["running", "idle"],
+      turns: [
+        { turn_number: 1, status: "completed" },
+        { turn_number: 2, status: "failed" },
+      ],
+    });
+
+    const result = await fountainRun({ agent: "researcher", pollMs: 1, sleep: async () => {} }, http);
+    expect(result.status).toBe("failed");
+    expect(result.persistent).toBe(true);
+  });
+
+  it("does not terminate a hung run by default — the machine is a home (terminate: never)", async () => {
+    const { http, calls } = scriptedConversation({
+      sandboxMode: "persistent",
+      conversationId: "conv-5",
+      statuses: ["running"],
+    });
+
+    const result = await fountainRun(
+      { agent: "researcher", timeoutMs: 1, pollMs: 1, sleep: async () => {} },
+      http,
+    );
+    expect(result.terminatedByDeadline).toBe(true);
+    expect(result.persistent).toBe(true);
+    expect(calls).not.toContain("POST /api/conversations/conv-5/terminate");
+  });
+
+  it("terminate: on-deadline still ends a persistent agent's hung run", async () => {
+    const { http, calls } = scriptedConversation({
+      sandboxMode: "persistent",
+      conversationId: "conv-6",
+      statuses: ["running"],
+    });
+
+    await fountainRun(
+      { agent: "researcher", terminate: "on-deadline", timeoutMs: 1, pollMs: 1, sleep: async () => {} },
+      http,
+    );
+    expect(calls).toContain("POST /api/conversations/conv-6/terminate");
+  });
+
+  it("terminate: always ends the machine even after a clean turn", async () => {
+    const { http, calls } = scriptedConversation({
+      sandboxMode: "persistent",
+      conversationId: "conv-7",
+      statuses: ["running", "idle"],
+      turns: [{ turn_number: 1, status: "completed" }],
+    });
+
+    const result = await fountainRun(
+      { agent: "researcher", terminate: "always", pollMs: 1, sleep: async () => {} },
+      http,
+    );
+    expect(result.terminatedByDeadline).toBe(false);
+    expect(calls).toContain("POST /api/conversations/conv-7/terminate");
+  });
+});

package/src/op/activities/fountain-run.ts

@@ -1,12 +1,33 @@
 /**
  * fountainRun — start a conversation from a declared Agent and follow it
- * to a terminal status.
+ * to the end of its turn.
  *
  * Conversations are runs, not declarables (the one fountain kind the
  * lexicon deliberately does not model as a resource). This op is the
- * imperative half: resolve the agent by name, POST the conversation,
- * poll until `completed | failed | timed_out | terminated`, and terminate
- * on deadline so a hung run never outlives the op that started it.
+ * imperative half: resolve the agent by name, POST the conversation, and
+ * poll until the turn is done.
+ *
+ * What "done" means depends on the agent's `sandbox_mode` (#2718). An
+ * `ephemeral` conversation's machine is its own and this polls the
+ * conversation's own status to `completed | failed | timed_out |
+ * terminated` — none of which a running server's conversation status
+ * actually reaches on its own, so in practice this waits out `timeoutMs`
+ * and terminates, as it always has. A `persistent` agent's conversation
+ * (`Steward`, and `Box` from #2705) shares one machine across every
+ * conversation on it, and a turn ending there does not tear the sandbox
+ * down: the conversation settles on `idle`, not on any of the four
+ * statuses above. Waiting for one of those on a persistent agent is the
+ * bug this op used to have — it waited out the whole deadline after the
+ * turn had already finished, then terminated a machine that was meant to
+ * persist. For `idle`, this instead reads the finished turn back
+ * (`GET .../turns`) and returns its own outcome (`completed | failed |
+ * interrupted` — fountain's `end_turn` block, or an error) without
+ * terminating anything.
+ *
+ * Terminating the conversation's machine on deadline (a hung run should
+ * not outlive the op that started it) still happens whenever the turn has
+ * not ended — for either sandbox mode. `terminate` makes the choice
+ * explicit rather than leaving it implicit in `sandbox_mode`.
  */
 
 import {
@@ -16,8 +37,39 @@ import {
   type FountainConnectionDeps,
 } from "./fountain-apply";
 
+/**
+ * Conversation statuses that end an *ephemeral* agent's run. `completed`
+ * and `timed_out` are not values fountain's `Conversation.status` takes
+ * today (its enum is `pending | running | idle | failed | terminated`) —
+ * they are kept so a server that starts reporting them is handled without
+ * a further change here.
+ */
 export const TERMINAL_STATUSES = new Set(["completed", "failed", "timed_out", "terminated"]);
 
+/**
+ * Conversation statuses that end a *persistent* agent's run: everything
+ * {@link TERMINAL_STATUSES} does, plus `idle` — the status a persistent
+ * conversation settles on once its turn ends, machine still up (#2718).
+ */
+export const PERSISTENT_DONE_STATUSES = new Set([...TERMINAL_STATUSES, "idle"]);
+
+/** Turn statuses that mean the turn has ended — fountain's `end_turn` block, or an error. */
+const TERMINAL_TURN_STATUSES = new Set(["completed", "failed", "interrupted"]);
+
+/**
+ * How `fountainRun` treats the conversation's machine once its wait ends
+ * (#2718).
+ *
+ * - `on-deadline` — terminate only when `timeoutMs` is hit with the turn
+ *   still unfinished, never on a turn that ended cleanly. This was
+ *   `fountainRun`'s only behavior before this option existed.
+ * - `never` — never terminate, even past the deadline; the caller, or
+ *   fountain's own idle/max-lifetime bounds, is responsible for the machine.
+ * - `always` — terminate whenever the wait ends, whether the turn ended
+ *   cleanly or the deadline fired.
+ */
+export type TerminatePolicy = "never" | "on-deadline" | "always";
+
 export interface FountainRunArgs {
   /** Agent name (resolved against /api/agents) or a raw agent id. */
   agent: string;
@@ -34,31 +86,80 @@ export interface FountainRunArgs {
   profile?: string;
   /** Project root `chant.config.ts` is read from. Default: process.cwd(). */
   cwd?: string;
-  /** Give up (and terminate the conversation) after this long. Default 10 min. */
+  /** Give up after this long. Default 10 min. */
   timeoutMs?: number;
   /** Poll interval. Default 5s. */
   pollMs?: number;
+  /**
+   * When to terminate the conversation's machine (#2718). Default follows
+   * the agent's `sandbox_mode`: `on-deadline` for `ephemeral` (unchanged),
+   * `never` for `persistent` — its machine is a home meant to outlive the
+   * conversation, so a run that hits its deadline leaves it be unless this
+   * says otherwise.
+   */
+  terminate?: TerminatePolicy;
   /** Injectable clock/sleep for tests. */
   sleep?: (ms: number) => Promise<void>;
 }
 
 export interface FountainRunResult {
   conversationId: string;
+  /**
+   * The run's outcome. For a persistent agent whose turn ended, this is the
+   * turn's own status (`completed | failed | interrupted`); otherwise it is
+   * the conversation's status when the wait ended (`terminated` on a
+   * deadline).
+   */
   status: string;
-  /** True when the op hit its deadline and terminated the conversation. */
+  /** True when the agent's `sandbox_mode` resolved to `persistent`. */
+  persistent: boolean;
+  /** True when the op hit its deadline with the turn still unfinished. */
   terminatedByDeadline: boolean;
 }
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-export async function resolveAgentId(http: FountainHttp, agent: string): Promise<string> {
-  if (UUID_RE.test(agent)) return agent;
+export interface ResolvedAgent {
+  id: string;
+  /** `ephemeral` or `persistent`; fountain's own default is `ephemeral`. */
+  sandboxMode: string;
+}
+
+/** Resolve an agent by name or id, along with its `sandbox_mode`. */
+export async function resolveAgent(http: FountainHttp, agent: string): Promise<ResolvedAgent> {
+  if (UUID_RE.test(agent)) {
+    const { status, json } = await http("GET", `/api/agents/${agent}`);
+    if (status !== 200) throw new Error(`fountainRun: agent lookup failed (${status})`);
+    const data = (json as { data?: { id?: string; sandbox_mode?: string } })?.data;
+    if (!data?.id) throw new Error(`fountainRun: no agent "${agent}"`);
+    return { id: data.id, sandboxMode: data.sandbox_mode ?? "ephemeral" };
+  }
   const { status, json } = await http("GET", `/api/agents?search=${encodeURIComponent(agent)}`);
   if (status !== 200) throw new Error(`fountainRun: agent lookup failed (${status})`);
-  const data = (json as { data?: Array<{ id: string; name: string }> })?.data ?? [];
+  const data =
+    (json as { data?: Array<{ id: string; name: string; sandbox_mode?: string }> })?.data ?? [];
   const exact = data.find((a) => a.name === agent);
   if (!exact) throw new Error(`fountainRun: no agent named "${agent}"`);
-  return exact.id;
+  return { id: exact.id, sandboxMode: exact.sandbox_mode ?? "ephemeral" };
+}
+
+/** Agent id only — the common case, and the one call sites outside this file use. */
+export async function resolveAgentId(http: FountainHttp, agent: string): Promise<string> {
+  if (UUID_RE.test(agent)) return agent;
+  return (await resolveAgent(http, agent)).id;
+}
+
+/** The latest turn's status, or undefined if it can't be read or none exists. */
+async function latestTurnStatus(
+  http: FountainHttp,
+  conversationId: string,
+): Promise<string | undefined> {
+  const { status, json } = await http("GET", `/api/conversations/${conversationId}/turns`);
+  if (status !== 200) return undefined;
+  const turns = (json as { data?: Array<{ turn_number?: number; status?: string }> })?.data ?? [];
+  if (turns.length === 0) return undefined;
+  const latest = turns.reduce((a, b) => ((b.turn_number ?? 0) > (a.turn_number ?? 0) ? b : a));
+  return latest.status;
 }
 
 export async function fountainRun(
@@ -75,7 +176,10 @@ export async function fountainRun(
   const timeoutMs = args.timeoutMs ?? 600_000;
   const pollMs = args.pollMs ?? 5_000;
 
-  const agentId = await resolveAgentId(client, args.agent);
+  const { id: agentId, sandboxMode } = await resolveAgent(client, args.agent);
+  const persistent = sandboxMode === "persistent";
+  const terminatePolicy: TerminatePolicy = args.terminate ?? (persistent ? "never" : "on-deadline");
+  const doneStatuses = persistent ? PERSISTENT_DONE_STATUSES : TERMINAL_STATUSES;
 
   const createBody: Record<string, unknown> = { agent_id: agentId };
   if (args.prompt !== undefined) createBody.prompt = args.prompt;
@@ -89,19 +193,33 @@ export async function fountainRun(
   if (!conversationId) throw new Error("fountainRun: conversation create returned no id");
 
   const deadline = Date.now() + timeoutMs;
-  let status = "pending";
+  let conversationStatus = "pending";
   while (Date.now() < deadline) {
     const res = await client("GET", `/api/conversations/${conversationId}`);
     if (res.status === 200) {
-      status = (res.json as { data?: { status?: string } })?.data?.status ?? status;
-      if (TERMINAL_STATUSES.has(status)) {
-        return { conversationId, status, terminatedByDeadline: false };
+      conversationStatus =
+        (res.json as { data?: { status?: string } })?.data?.status ?? conversationStatus;
+      if (doneStatuses.has(conversationStatus)) {
+        let status = conversationStatus;
+        if (persistent && conversationStatus === "idle") {
+          const turnStatus = await latestTurnStatus(client, conversationId);
+          if (turnStatus && TERMINAL_TURN_STATUSES.has(turnStatus)) status = turnStatus;
+        }
+        if (terminatePolicy === "always") {
+          await client("POST", `/api/conversations/${conversationId}/terminate`);
+        }
+        return { conversationId, status, persistent, terminatedByDeadline: false };
       }
     }
     await sleep(pollMs);
   }
 
-  // Deadline: end the conversation so the sandbox does not outlive the op.
-  await client("POST", `/api/conversations/${conversationId}/terminate`);
-  return { conversationId, status: "terminated", terminatedByDeadline: true };
+  // Deadline: the turn never ended (or, for an ephemeral conversation, its
+  // done-status is never observed on the wire — see TERMINAL_STATUSES).
+  // `never` leaves a hung run's machine alone; every other policy ends the
+  // conversation so it does not outlive the op.
+  if (terminatePolicy !== "never") {
+    await client("POST", `/api/conversations/${conversationId}/terminate`);
+  }
+  return { conversationId, status: "terminated", persistent, terminatedByDeadline: true };
 }

package/src/op/activities/index.ts

@@ -25,5 +25,11 @@ export type {
   FountainConnectionDeps,
 } from "./fountain-apply";
 
-export { fountainRun, resolveAgentId, TERMINAL_STATUSES } from "./fountain-run";
-export type { FountainRunArgs, FountainRunResult } from "./fountain-run";
+export {
+  fountainRun,
+  resolveAgent,
+  resolveAgentId,
+  TERMINAL_STATUSES,
+  PERSISTENT_DONE_STATUSES,
+} from "./fountain-run";
+export type { FountainRunArgs, FountainRunResult, ResolvedAgent, TerminatePolicy } from "./fountain-run";

package/src/skills/chant-fountain-locked-sandboxes.md

@@ -31,4 +31,4 @@ The environment's config is the enforcement boundary, so watch it: `chant lifecy
 
 ## Running conversations
 
-Conversations are runs, not resources. Use the `fountainRun` activity: resolves the agent by name, starts (optionally with a prompt and an allowlisted vault), polls to `completed | failed | timed_out`, and terminates at its deadline so a hung sandbox never outlives the op. Multi-turn interaction (follow-up prompts, interrupt) is fountain's own conversations API — keep chant to the lifecycle edges.
+Conversations are runs, not resources. Use the `fountainRun` activity: resolves the agent by name, starts (optionally with a prompt and an allowlisted vault), and waits for the turn to end. What "end" means, and what happens to the machine, follows the agent's `sandbox_mode`: an `ephemeral` agent's conversation is polled for a terminal status and terminated on deadline, same as before; a `persistent` agent's (a `Steward` or `Box`) conversation settles on `idle` once its turn ends — machine still up for the next turn — so `fountainRun` reads the turn back and returns its outcome (`completed | failed | interrupted`) without terminating anything, by default. Pass `terminate: "on-deadline" | "always"` to opt a persistent agent's run back into ending the machine. Multi-turn interaction (follow-up prompts, interrupt) is fountain's own conversations API — keep chant to the lifecycle edges.