@archmax-ai/harness 0.4.2 → 0.6.0

package/dist/authoring-skill/archmax-harness/references/backend-integration.md

@@ -96,7 +96,7 @@ All optional (`CreateAgentParams`, `src/assembly/index.ts`):
 | `model` | `BaseChatModel` | Defaults to the env-configured OpenAI-compatible model. Inject your own to bypass env. |
 | `backend` | `BackendProtocolV2` | Serves the authored workspace. Defaults to a `FilesystemBackend` over `rootDir`. |
 | `authoring` | `BackendProtocolV2` | Serves the **authoring plane** — `workflows/**` (machine specs including the rubrics their states declare, `WORKFLOW.md`, `hooks/`, `tests/`) — to the runtime only. Never a route in the agent's workspace, so no tool call or PTC call can reach it. Defaults to `backend` when you supply one, else a `FilesystemBackend` over the resolved root. Handing it to a **writable** mount throws `AuthoringBackendExposedError`; a read-only mount may share it. |
-| `mounts` | `Record<string, MountSpec>` | Authored mounts as a `CompositeBackend` route table: key → backend, or `{ backend, readOnly, governed, searchable }`. Trailing slash = directory mount; no slash = exact-path file mount (`"/AGENTS.md"`). Read-only unless declared otherwise. `governed: true` hands the spec's `mounts` block the decision of **which states** may reach it (closed by default, like a skill bundle) and whether each may write there; a mount not so declared is visible in every state exactly as today, so a table that marks nothing behaves unchanged. `readOnly` is a **ceiling** the spec cannot lift: a grant may narrow a writable mount to reads in a state, never open a read-only one. A key may be several segments deep (`"/catalogs/eu/"`); its **first** segment is what is reserved, so `/workflows/x/` fails as `/workflows/` does. Omitted on the default backend: `defaultMounts(rootDir)` (the conventional table — `/skills/`, `/.platform/`, `/AGENTS.md`, none governed — extend with `{ ...defaultMounts(root), "/templates/": … }`). Omitted with a custom `backend`: nothing authored is served; expose subtrees with `mountSubtree(backend, "skills")`. A key colliding with a run area — or naming the authoring-plane prefix (`/workflows/`) — throws `MountCollisionError`. `searchable: false` declares a mount the runtime never searches on its own initiative: a root-wide `grep`/`glob` fans out over the other mounts only, while a search the agent addresses at the mount (or a path inside it) still reaches its backend and returns the backend's own answer — matches or `{ error }` — verbatim. Use it for a backend that must refuse searches (a remote folder served live). Listing and reading are unchanged, the prompt marks it "browse only", names arrive as `MountPrefixes.unsearchable`, and it is ignored on a file mount. |
+| `mounts` | `Record<string, MountSpec>` | Authored mounts as a `CompositeBackend` route table: key → backend, or `{ backend, readOnly, governed, searchable }`. Trailing slash = directory mount; no slash = exact-path file mount (`"/AGENTS.md"`). Read-only unless declared otherwise. `governed: true` hands the spec's `mounts` block the decision of **which states** may reach it (closed by default, like a skill bundle) and whether each may write there; a mount not so declared is visible in every state exactly as today, so a table that marks nothing behaves unchanged. `readOnly` is a **ceiling** the spec cannot lift: a governed writable mount is written only by a workflow whose own grants ask `access: read_write` (a bare grant reads it, so serving one route writable for one workflow in a delegation tree opens it to no other), and a grant may narrow a writable mount to reads in a state, never open a read-only one. A key may be several segments deep (`"/catalogs/eu/"`); its **first** segment is what is reserved, so `/workflows/x/` fails as `/workflows/` does. Omitted on the default backend: `defaultMounts(rootDir)` (the conventional table — `/skills/`, `/.platform/`, `/AGENTS.md`, none governed — extend with `{ ...defaultMounts(root), "/templates/": … }`). Omitted with a custom `backend`: nothing authored is served; expose subtrees with `mountSubtree(backend, "skills")`. A key colliding with a run area — or naming the authoring-plane prefix (`/workflows/`) — throws `MountCollisionError`. `searchable: false` declares a mount the runtime never searches on its own initiative: a root-wide `grep`/`glob` fans out over the other mounts only, while a search the agent addresses at the mount (or a path inside it) still reaches its backend and returns the backend's own answer — matches or `{ error }` — verbatim. Use it for a backend that must refuse searches (a remote folder served live). Listing and reading are unchanged, the prompt marks it "browse only", names arrive as `MountPrefixes.unsearchable`, and it is ignored on a file mount. |
 | `sessionStore` | `SessionStore` | Physical storage for run state (checkpoints, artifacts, the per-session `scratchpad/`). Zero-config default: `createFilesystemSessionStore({ dir: "<rootDir>/sessions" })`. Required with a custom `backend` (else `SessionStoreRequiredError`). Build with `createBackendSessionStore({ backend, prefix? })` for S3-style storage or `createMemorySessionStore()` for ephemeral runs. |
 | `systemPrompt` | `string` | Appended after workspace `AGENTS.md`. |
 | `tools` | `StructuredTool[]` | Host tools, granted per state by `tools.allow`. Build them with `toolsFromMap` — see [host tools](#host-tools). A name starting `archmax_`, or naming a runtime file operation (`copy_file`, `move_file`, `remove_file`), throws `ReservedToolNameError`. |
@@ -333,9 +333,11 @@ turn ended in — the position, variables, transcript and files are already ther
 message.
 
 The runtime does not reposition a later turn, so nothing is injected into the
-transcript to explain a jump. When a turn needs a path the current state cannot
-reach, the agent calls `archmax_reset` to return to the state the conversation began
-in (available in every state). To continue *mid-state* instead — inside the state
+transcript to explain a jump. When the current state can serve the new message, the
+agent answers there without a reset. That includes a terminal state that is also the
+state the conversation began in, such as a one-state chat workflow. When a turn needs
+a path the current state cannot reach, the agent calls `archmax_reset` to return to
+the state the conversation began in (available in every state). To continue *mid-state* instead — inside the state
 that stopped, with the arrival in its transcript — the turn must park rather than
 finish.
 
@@ -378,7 +380,7 @@ const outcome = await agent.workflow!.send(sessionId, { message: "Refund the ord
 
 - `signatureJsonSchema(entries)` → `{ type: "object", properties, required }`:
   one property per entry in declaration order, every name required,
-  `date`/`date-time` as `{ type: "string", format }`, an untyped entry as `{}`,
+  `date`/`date-time`/`file` as `{ type: "string", format }`, an untyped entry as `{}`,
   an entry's `description` carried over. It adds no `additionalProperties`; set
   it for your own ingress.
 - `signatureValueIssues(entries, values)` → one issue per missing name and per
@@ -387,6 +389,19 @@ const outcome = await agent.workflow!.send(sessionId, { message: "Refund the ord
   `"4"` to `4` before it validates or seeds.
 - A trigger's `description` is written for the caller. Use it as the MCP tool
   or operation description. The session's own model never sees it.
+- **A `file` entry** (`format: "file"` in the schema) takes a workspace path. To
+  hand a session an uploaded file, pass it on the turn rather than writing into
+  the store yourself:
+  `send(sessionId, { message, files: { invoice: { name: "invoice.pdf", content: bytes } } })`.
+  The runtime places the bytes in the session's `scratchpad/attachments/` (a taken
+  name gets `-1`, `-2`, …), seeds `invoice`, locked, with the placed path, and the
+  turn boundary then checks that the file is there and readable. `send` throws
+  `InvalidTurnFileError`, before anything is written, for a bad variable or file
+  name, a variable also given in `variables`, a session parked at a human state, or
+  bytes the store cannot hold exactly (a non-text file needs a store with
+  `uploadFiles`). `signatureValueIssues` checks only a `file` value's shape, so a
+  start form validates the path the upload will produce, or skips the entry and
+  lets `files` supply it.
 - A host that reads specs itself must read `requires`/`returns` through
   `normalizeSignature` (both spellings → `{ name, type?, description? }[]`),
   never as `string[]`: an entry may be an object. Hosts must be on the release
@@ -601,6 +616,15 @@ A custom `backend` **requires** an explicit `sessionStore` — assembly throws
 Persisting the session zone off-box (an S3-backed session store) is how you share run
 state across a worker fleet and an API.
 
+A session's files are stored under `<sessionId>/` in the store (beneath its
+`prefix`): the agent's `scratchpad/x.txt` in session `s1` is `s1/scratchpad/x.txt`.
+That address is a contract, so a host may read or write a session's files through
+its own handle on the store (ranged reads, recursive listings, presigned URLs). A
+host tool keys them by `ToolContext.sessionId`, which inside a sub-workflow is the
+child's id, never the session the turn was sent to. `sessionIdRejection` refuses an
+id holding `~` in any shape but a child's (`<parent>~<n>`): mint top-level ids
+without it.
+
 `downloadFiles`, `uploadFiles` and `delete` are optional in the protocol and stay
 optional in the workspace: a store with only the required methods serves skills,
 reads and text copies. `downloadFiles` is always present and reads a store without
@@ -645,7 +669,8 @@ const agent = await createAgent({ tools, essentialTools: ["get_markdown"] });
 - `paths` declares the arguments that name workspace paths and how the call
   uses each. Every path rule binds them: the read-only zone, the runtime's own
   areas, the skills and mounts the state was given (`mount.not-allowed`,
-  `skill.not-allowed`), a mount's `access: read` (`mount.read-only` for a
+  `skill.not-allowed`), a mount's `access: read` or a governed mount no grant
+  of the workflow asks `read_write` for (`mount.read-only` for a
   `write` or `remove`), inherited denials and `paths:` guards. A refused call
   never runs the handler. No declaration, no path rules. An argument may hold a
   list of paths (`files: string[]`), each governed; any other shape is refused.
@@ -654,8 +679,13 @@ const agent = await createAgent({ tools, essentialTools: ["get_markdown"] });
 - `context.workspace` is the turn's workspace, bound to the session — the
   instance `read_file` uses — with `downloadFiles`, `uploadFiles` (when the
   session store has it) and `delete` besides the text methods. The plain agent
-  hands the same context. Outside a turn, reading it throws; the property is
-  non-enumerable there, so comparing or logging the context does not.
+  hands the same context.
+- `context.sessionId` is the session the call is made in: inside a sub-workflow,
+  the child's own id (`<parent>~<n>`), for the model's call and a script's alike.
+  Key any session file your host stores itself by it (`<sessionId>/<path>` in the
+  session store), never by the session you sent the turn to.
+- Outside a turn, reading either throws; both are non-enumerable there, so
+  comparing or logging the context does not.
 
 ## Cases against your agent
 
@@ -708,7 +738,7 @@ real). A bespoke target that intercepts by other means sets
 `capabilities.toolMocks` itself. Mockless cases run against any
 workflow-governed target.
 
-**Sub-workflows inherit the assembly.** When a workflow delegates (by advancing
+**Sub-workflows inherit the assembly.** When a workflow delegates (by calling
 an `archmax_workflow_<slug>` tool), the child runtime is
 composed from the *same* resolved inputs as the parent — model and
 `modelFactory`, `backend` and `mounts`, `sessionStore` and `checkpointer`, host
@@ -721,11 +751,19 @@ never delegated to is never loaded, and one delegated from many places is
 composed once. A child whose spec is broken surfaces as a *dispatch* failure, not
 an assembly failure — a parent still assembles.
 
-The child runs on the parent's **session id** (which is what gives it the same
-run zone) under a nested checkpoint namespace, so `sessions.list()` reports one
-session and the parent session's metrics include the child's tokens.
-`capabilities.subWorkflows` is stamped `true` for a governed assembly and `false`
-for the plain one.
+The child runs as a **separate session**, `<parent>~<n>`, in the same session
+store, with its own checkpoints, its own token accounting and its own file space:
+its `scratchpad/` is not its caller's, so it can neither read nor overwrite a file
+of its caller's. `n` is the dispatch's number in the calling session, counted from 1
+across all its turns in its checkpointed state, so an agent built per turn never
+reuses one; a grandchild is `<parent>~<n>~<m>`. The `sub-workflow-*` events and a
+pending delegation name it by its `dispatchId`, the id below the root session (`1`,
+`1~1`). A host tool called in the child gets the child's id as
+`ToolContext.sessionId`, and its file work belongs to the child. `sessions.list()` reports it beside its caller
+with `parentSessionId` naming the caller, and `sessions.delete` removes it by its
+own id. The only files that cross are the runtime's copies of declared `file` arguments and
+`file` returns. `capabilities.subWorkflows` is stamped `true` for a governed
+assembly and `false` for the plain one.
 
 Omit both options and behavior is identical to `archmax test`. Cases run
 sequentially (`tests.maxConcurrency` above 1 is rejected, not silently

package/dist/authoring-skill/archmax-harness/references/hook-and-test-scripts.md

@@ -236,7 +236,9 @@ A **binary file** is not a refusal and does not throw: reads are text only, so
 file whose content holds a NUL byte (an archive, an Office document), resolves to
 the notice `Error: '<path>' is a binary file (<type>, <size>) and was not read;
 read_file returns text files only.` instead of content — an image too, even when
-the host turned on `images`, which shows images to the model only. A missing file reads as
+the host turned on `images`, which shows images to the model only. XML and JSON
+are text even when the store labels them `application/xml` or a `+xml`/`+json`
+type, so an Office document's unpacked `word/document.xml` reads as text. A missing file reads as
 an `Error: …` string the same way. A script that parses what it read checks
 first:
 
@@ -322,7 +324,8 @@ state fails that call closed with `parked`.
 Scripts still may not call `archmax_advance` (moving the state machine is the model's governed
 decision) or `archmax_set_variables`. Concurrent calls succeed or fail **independently**, so a script
 can act on what worked — `Promise.allSettled` is the honest shape when partial success is
-meaningful. Give each sub-run its own output path: they share one run zone.
+meaningful. Each sub-run is its own session with its own `scratchpad/`, so concurrent sub-runs
+never collide on a path; a `file` return comes back as a copy under a name no other file holds.
 
 ### Worked example: a `before` gate
 

package/dist/authoring-skill/archmax-harness/references/workflow-schema.md

@@ -196,7 +196,10 @@ mounts?:
                               # workflow reaches no governed mount; validate says so
                               # ONCE, naming them — write `allow_always: []` to mean it.
                               # An entry is a NAME, or `{ mount: <name>, access: read |
-                              # read_write }` to say what this level gives. The host's
+                              # read_write }` to say what this level gives. A bare NAME
+                              # asks for NO write: a governed mount is written only
+                              # where some grant of THIS workflow says `read_write`
+                              # (a child's or caller's grant never counts). The host's
                               # readOnly is a CEILING: `read_write` on a read-only mount
                               # opens nothing (validate warns); `read` NARROWS a
                               # writable one, and no narrower level widens it back.
@@ -368,7 +371,9 @@ states:
                                # warns about one that reads like it) — `forbid` is.
                                # An entry may name its access:
                                #   allow: [{ mount: shared, access: read }]
-                               # reads a writable mount without writing it here. The
+                               # reads a writable mount without writing it here, and
+                               #   allow: [{ mount: shared, access: read_write }]
+                               # asks to write it — which a bare name never does. The
                                # host's posture is the ceiling — `read_write` cannot
                                # open a read-only mount — and a `read` at either level
                                # holds, so a state never widens what the workflow
@@ -557,7 +562,9 @@ states:
 - **`type`** is one of `string`, `integer` (no fractional part), `number`
   (finite), `boolean`, `date` (RFC 3339 `YYYY-MM-DD`, a real calendar day),
   `date-time` (RFC 3339 with a mandatory `Z`/`±hh:mm` offset), `object` (not an
-  array) or `array`. Nothing is coerced (`"4"` is not an `integer`) and a typed
+  array), `array` or `file` (a path from the workspace root, such as
+  `scratchpad/attachments/invoice.pdf` or `skills/billing/assets/template.pdf`; see
+  [Passing files](#passing-files)). Nothing is coerced (`"4"` is not an `integer`) and a typed
   entry never takes `null`. It is held **at the start** (a mistyped seed is
   refused before any model call), **at the write** (`archmax_set_variables` of a
   mistyped typed return of the current trigger is a correctable refusal,
@@ -565,6 +572,17 @@ states:
   run — in practice a script or hook write). There are no enums, item or
   property schemas, ranges or optional inputs. An unknown `type`, an unknown
   entry key (`default:`) or an empty `description` fails load.
+- **A `file` value must name a readable file.** The pure rule checks only the
+  path's shape (a host runs it in a browser). At the start, at the write, at
+  completion and at a delegation call the runtime also requires a **file** (not a
+  folder) at the path that the session may read **on runtime authority** — the
+  rules a hook is bound by: zone rules (`checkpoints/`, `artifacts/`, `_specs/`
+  never) and every workflow-wide `forbid_always`, inherited ones included; the
+  state's allow list and mount/skill grants do not narrow it. So tell the agent to
+  write the file *before* it sets a `file` return: `archmax_set_variables` refuses
+  a path with nothing there. A host hands a file in with `TurnInput.files` (CLI:
+  `archmax run … --file invoice=./invoice.pdf`), which places it under
+  `scratchpad/attachments/` and seeds the path.
 - **When to type.** Type an entry when something outside the session reads the
   contract: a delegating model that must build the argument, a host publishing an
   MCP tool or a start form. Leave it bare when any value will do. Typing a
@@ -908,13 +926,13 @@ error.
 
 ### Read or read/write
 
-A grant entry is either a bare mount name — taking the posture the host wired — or
-a mapping naming the access this level gives:
+A grant entry is either a bare mount name, which asks for no write, or a mapping
+naming the access this level gives:
 
 ```yaml
 mounts:
   allow_always:
-    - reference                                  # the host's posture
+    - reference                                  # read; written only if a grant below asks
     - { mount: shared, access: read_write }      # writable where the host allows it
 
 states:
@@ -923,6 +941,17 @@ states:
       allow: [{ mount: shared, access: read }]   # reads it, cannot write it here
 ```
 
+**A workflow writes a governed mount only where its own grants ask to.** It is
+writable in a state when the host serves it writable, some grant of *this*
+workflow says `access: read_write` (in `allow_always` or any state's `allow`), and
+no grant applicable in the state says `access: read`. So a bare grant in one state
+and a `read_write` grant in another both write. One mount table serves a session
+and every child it dispatches, and the host serves a route writable when any
+workflow in that tree asks; a mount still belongs to the workflow that grants it,
+so a caller's `read_write` never lets its child write through a bare grant, nor the
+other way round. An ungoverned mount takes the host's posture: it has no grant to
+ask with.
+
 The host's `readOnly` is a **ceiling**, not a default to argue with:
 
 - `access: read_write` on a mount the workspace serves read-only opens nothing,
@@ -936,7 +965,8 @@ The host's `readOnly` is a **ceiling**, not a default to argue with:
 
 Two refusals, because they are two different edits: a write into a mount the
 **host** serves read-only is `zone.read-only` (fix the wiring), and a write into
-one a **grant** narrowed is `mount.read-only` (fix the spec).
+one a **grant** narrowed, or one no grant of the workflow asks to write, is
+`mount.read-only` (fix the spec; the refusal says which).
 
 ### What the agent sees
 
@@ -972,7 +1002,8 @@ so `AGENTS.md.bak` is not captured.
   everywhere already — use `forbid` to take one away);
 - an `access: read_write` on a mount the host serves **read-only**;
 - a name in both `allow_always` and a state's `allow` (unless the state entry
-  narrows the access, which does real work);
+  narrows the access to `read`, or asks `read_write` of a mount the root grants
+  bare: both do real work);
 - a state's `allow: []` beside a non-empty `allow_always`;
 - a `forbid` naming a governed mount nothing would have enabled there;
 - a `forbid_always` name some `allow` list also grants;
@@ -1015,7 +1046,8 @@ the host at assembly (`variables`, every seed locked), the agent mid-run
 
 `trigger` holds the current turn's trigger id. `title` holds a short one-line label
 naming the task the run is doing; the platform system prompt asks the agent to set
-one as its first activity and update it when the task changes significantly, so a
+one as its first activity, and to rename it only when the whole conversation has
+moved to a different subject (a follow-up on the same subject keeps it), so a
 host can name a run instead of showing a session id. A sub-workflow's child is not
 asked — its title names a session nothing lists and is never returned — so its
 prompt leaves the step out; do not write "set the title" into a child's state
@@ -1340,7 +1372,7 @@ enrich:
   delegation may happen is decided by the caller's `tools.allow` entry. A target
   with no `manual` entry has no state to start in and fails closed. `session:` and
   `message:` on that trigger are host-facing keys a delegation ignores: a sub-run
-  shares its parent's session, and carries no message. `sub-workflow` is no longer
+  is its own session, derived from its caller's, and carries no message. `sub-workflow` is no longer
   a trigger id — load and `validate` report it with the rename.
 - **Declare the child's signature** on that trigger — the contract, enforced both
   ways and at both ingresses:
@@ -1400,14 +1432,17 @@ enrich:
   state's work. A workspace overriding the platform prompt
   (`.platform/system/GRAPH_STATE.md`) keeps that by wrapping what children skip
   in `<!-- top-level-only -->` … `<!-- /top-level-only -->` lines.
-- **Same agent, isolated context, shared session.** Same model, backend, host
+- **Same agent, isolated context, own session.** Same model, backend, host
   tools; its **own** grading rubrics, from its own spec; a fresh transcript; the child's *own* per-state
-  `tools.allow`. It shares the run's session, so it writes `scratchpad/…` and
-  `scratchpad/…` exactly as the parent does and the parent reads them afterwards.
+  `tools.allow`. It is a separate session (`<parent>~<n>`, `n` the dispatch's
+  number in the caller, counted across its turns) with its own checkpoints and its own `scratchpad/`: a path it reads or writes
+  resolves inside its own session, so it can neither see nor overwrite a file of
+  its caller's, and concurrent sub-runs cannot collide on a path.
 - **Nothing crosses implicitly.** Down: only the arguments the call passed —
   the calling run's own variables are not copied. Up: only the result message
-  and the files. Everything the child sets is discarded when it finishes.
-- **Give each concurrent sub-run its own output path** — they share one run zone.
+  and the declared returns. Everything else the child sets or writes stays in its
+  session. The only files that cross are runtime-made copies of `file` arguments
+  and `file` returns (see "Passing files" below).
 - **Bounds** — the dispatcher's `bounds: { maxDepth: 3, maxConcurrent: 4 }`. No longer a spec key: the strict schema rejects `settings.sub_workflows` by name.
   Excess concurrency queues; depth and cycles are refused.
 - **Params are the sub-run's initial variables** — same construction, same name
@@ -1435,6 +1470,46 @@ parent reading a field the child does not return is an **error**; a state whose
 still carry it), and a fan-out is exempt from that warning because its
 entries' keys are not knowable statically.
 
+### Passing files
+
+A sub-run's `scratchpad/` is not its caller's, so a bare path string returned by a
+child (`returns: [result_file]`, untyped) names a file the caller **cannot
+read**. Type the entry `file` instead, and the runtime copies the file across:
+
+```yaml
+# the child
+triggers:
+  manual:
+    requires: [{ name: invoice, type: file }]
+    returns: [{ name: report, type: file }]
+```
+
+- **Down.** The caller passes any path in its workspace (`scratchpad/inbox/a.pdf`,
+  `skills/billing/assets/template.pdf`). Before the child starts, the runtime
+  copies the exact bytes into the **child's** `scratchpad/attachments/` (same name;
+  two arguments with one name take `-1`, `-2`) and seeds the child with that path,
+  so its opening message shows it. The child edits its own copy and never the
+  caller's file. The argument is a `read` path argument of the delegation tool, so
+  a `paths:` guard on the allow entry and the zone and mount rules bind it. An
+  argument naming nothing is refused `invalid-param` before the child runs. A
+  failed call's record names the caller's path.
+- **Up.** On completion, each `file` return the child set is copied into the
+  **caller's** `scratchpad/attachments/` and the result names that path. A taken
+  name gets the lowest free `-1`, `-2`, … before the extension (`report-1.pdf`), so
+  repeated or parallel calls never overwrite each other or the caller's files. A
+  return whose file is gone at completion fails the call `invalid-return`.
+- **No laundering.** A `file` value must name a file the session may read on
+  runtime authority, and a child inherits every ancestor's `forbid_always`. So a
+  child cannot hand back a file its caller's workflow denies: its agent's write
+  is refused, and a script's write is rejected at completion.
+- **Instructions to write.** Tell the child to write the file *first* and then set
+  the return to its path. Tell the caller the returned path is under
+  `scratchpad/attachments/`. Name files for what they hold (`<order_id>.json`):
+  the name survives the copy.
+- **Mocks and cases.** A mocked `file` return names a file in the case's own
+  session (seed it with `workspace:`), and it arrives copied into
+  `scratchpad/attachments/` like a real one. Assert the copy's path.
+
 ### A parked run may speak, never act
 
 A park does not end the conversation. Two moments get a **reply-only turn** — one
@@ -1696,9 +1771,11 @@ single-segment one is, and a sibling under the same first segment (`catalogs/uk`
 is not.
 
 A mount the host mounted **writable** is not a read-only zone — its paths are
-governed like ordinary run paths — but a state may still be given it read-only,
-with `mounts: { allow: [{ mount: <name>, access: read }] }`. A write refused by
-that grant is `mount.read-only`; one refused by the wiring is `zone.read-only`.
+governed like ordinary run paths — but a governed one is written only where a grant
+of the workflow says `access: read_write`, and a state may still be given it
+read-only, with `mounts: { allow: [{ mount: <name>, access: read }] }`. A write
+refused by a grant is `mount.read-only`; one refused by the wiring is
+`zone.read-only`.
 See [Mount governance](#mount-governance).
 
 The run root is writable, and it has exactly one named working area:

package/dist/authoring-skill/archmax-harness/references/workflow-yaml.md

@@ -50,7 +50,7 @@ states:
           - { name: due, type: date, description: The day it is due. }  # typed: held at the boundary
         returns: [result_file]   #   variables the run guarantees on completion (a caller's result);
                                  #   short of them: a child returns what it set + a `note`; a top-level run is rejected
-                                 #   entry types: string integer number boolean date date-time object array
+                                 #   entry types: string integer number boolean date date-time object array file
     instructions: >-
       Record the decision in scratchpad/refund.json, then archmax_advance to
       review; never close the case yourself.

package/dist/cli/bootstrap.d.ts

@@ -1,4 +1,4 @@
-import type { Agent, WorkflowSurface } from "../agent.js";
+import type { Agent, TurnFile, WorkflowSurface } from "../agent.js";
 import { type TriggerInput } from "../machine/triggers.js";
 import { type UsageTracker } from "../core/usage.js";
 import { type Style } from "./style.js";
@@ -10,6 +10,13 @@ import { type Invocation } from "./command.js";
 export declare function resolveWorkflow(given: string | undefined, rootDir: string | undefined): string;
 /** `--variables` must be a JSON object; anything else is an argument error before any assembly. */
 export declare function parseVariablesJson(raw: string | undefined): Record<string, unknown> | undefined;
+/**
+ * `--file <variable>=<path>` occurrences as a turn's files: each local file read
+ * (relative to the working directory) under its base name. The CLI is a host, so
+ * it reads the local filesystem; the runtime places the bytes in the session.
+ * Every problem is a usage error, found before anything is assembled.
+ */
+export declare function parseFileFlags(raw: string[] | undefined, variables: Record<string, unknown> | undefined): Record<string, TurnFile> | undefined;
 /** The one session header every command prints to stderr. Loads `.env` first so the model line is the effective one. */
 export declare function printSessionHeader(style: Style, workflow: string, rootDir: string | undefined, showModel?: boolean): void;
 /** Wire the state flow (and `--verbose` raw lines) behind a usage tracker whose handler the agent receives. */

package/dist/cli/bootstrap.js

@@ -4,12 +4,13 @@
  * event sink behind the state flow and the usage tracker, and the one
  * `withSession` wrapper every session command runs its body inside.
  */
-import { existsSync, readdirSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, resolve } from "node:path";
 import { createAgent } from "../assembly/index.js";
+import { VARIABLE_NAME_PATTERN } from "../machine/variables.js";
 import { UnknownTriggerError } from "../machine/triggers.js";
 import { WorkflowDisabledError, WorkflowLoadError } from "../machine/load-spec.js";
-import { EmptyMessageError, InvalidDecisionTargetError, MissingDeliveryTriggerError, SessionNotAwaitingInputError, SessionNotParkedError, } from "../sessions/resume.js";
+import { EmptyMessageError, InvalidTurnFileError, InvalidDecisionTargetError, MissingDeliveryTriggerError, SessionNotAwaitingInputError, SessionNotParkedError, } from "../sessions/resume.js";
 import { SessionNotResumableError, UnknownSessionTriggerError } from "../sessions/resolve.js";
 import { sessionIdRejection } from "../core/session-store.js";
 import { UnsupportedRuntimeContractError } from "../runtime/contract.js";
@@ -54,6 +55,44 @@ export function parseVariablesJson(raw) {
     }
     return value;
 }
+/**
+ * `--file <variable>=<path>` occurrences as a turn's files: each local file read
+ * (relative to the working directory) under its base name. The CLI is a host, so
+ * it reads the local filesystem; the runtime places the bytes in the session.
+ * Every problem is a usage error, found before anything is assembled.
+ */
+export function parseFileFlags(raw, variables) {
+    if (!raw || raw.length === 0)
+        return undefined;
+    const files = {};
+    for (const flag of raw) {
+        const at = flag.indexOf("=");
+        if (at <= 0 || at === flag.length - 1) {
+            throw new UsageError(`--file '${flag}' must be <variable>=<path> (e.g. --file invoice=./invoice.pdf)`);
+        }
+        const variable = flag.slice(0, at);
+        const path = flag.slice(at + 1);
+        if (!VARIABLE_NAME_PATTERN.test(variable)) {
+            throw new UsageError(`--file '${flag}': '${variable}' is not a valid variable name (lowercase letters, digits and underscores, starting with a letter)`);
+        }
+        if (Object.hasOwn(files, variable))
+            throw new UsageError(`--file names '${variable}' more than once`);
+        if (variables && Object.hasOwn(variables, variable)) {
+            throw new UsageError(`--file '${flag}': '${variable}' is also given in --variables; give it once`);
+        }
+        let content;
+        try {
+            if (!statSync(path).isFile())
+                throw new Error("not a file");
+            content = new Uint8Array(readFileSync(path));
+        }
+        catch {
+            throw new UsageError(`--file '${flag}': cannot read the file '${path}'`);
+        }
+        files[variable] = { name: basename(path), content };
+    }
+    return files;
+}
 /** The raw event line for `--verbose`, including the two events the default console output skips. */
 function rawEventLine(event) {
     switch (event.type) {
@@ -96,6 +135,7 @@ const KNOWN_ERRORS = [
     SessionNotParkedError,
     InvalidDecisionTargetError,
     EmptyMessageError,
+    InvalidTurnFileError,
     SessionNotAwaitingInputError,
     MissingDeliveryTriggerError,
     SessionNotResumableError,

package/dist/cli/bootstrap.js.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/cli/bootstrap.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/cli/bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/cli/command.d.ts

@@ -10,8 +10,10 @@ export interface OptionSpec {
     description: string;
     placeholder?: string;
     short?: string;
+    /** The flag may be given more than once; its value is then the list of every occurrence. */
+    multiple?: boolean;
 }
-export type Values = Record<string, string | boolean | undefined>;
+export type Values = Record<string, string | boolean | string[] | undefined>;
 export interface Invocation {
     positionals: string[];
     values: Values;

package/dist/cli/command.js

@@ -25,7 +25,7 @@ export const err = (line) => console.error(line);
 export function parseInvocation(cmd, args) {
     const options = Object.fromEntries(Object.entries({ ...GLOBAL_OPTIONS, ...cmd.options }).map(([name, spec]) => [
         name,
-        { type: spec.type, ...(spec.short ? { short: spec.short } : {}) },
+        { type: spec.type, ...(spec.short ? { short: spec.short } : {}), ...(spec.multiple ? { multiple: true } : {}) },
     ]));
     let parsed;
     try {

package/dist/cli/command.js.map

@@ -1 +1 @@
-{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/cli/command.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/cli/command.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,WAAW,CAAC;AAgCvD,kGAAkG;AAClG,MAAM,OAAO,UAAW,SAAQ,KAAK;CAAG;AACxC,yEAAyE;AACzE,MAAM,OAAO,QAAS,SAAQ,KAAK;CAAG;AAEtC,MAAM,CAAC,MAAM,cAAc,GAA+B;IACxD,IAAI,EAAE;QACJ,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,OAAO;QACpB,WAAW,EAAE,qEAAqE;KACnF;IACD,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,4BAA4B,EAAE;CACjF,CAAC;AACF,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACvD,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAEzD,MAAM,UAAU,eAAe,CAAC,GAAY,EAAE,IAAc;IAC1D,MAAM,OAAO,GAAG,MAAM,CAAC,WAAW,CAChC,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,cAAc,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;QAC1E,IAAI;QACJ,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;KAChH,CAAC,CACH,CAAC;IACF,IAAI,MAAwC,CAAC;IAC7C,IAAI,CAAC;QACH,MAAM,GAAG,aAAa,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC,CAAC;IAClF,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,UAAU,CAAC,MAAM,CAAE,CAAW,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,mBAAmB,CAAC,CAAC;IAC3F,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAgB,CAAC;IACvC,MAAM,IAAI,GAAG,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACvE,IAAI,MAAM,CAAC,IAAI;QAAE,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAE1E,0EAA0E;IAC1E,yEAAyE;IACzE,MAAM,WAAW,GAAG,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACxD,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAChB,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACzD,IAAI,IAAI;YAAE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;SAAM,IAAI,WAAW,CAAC,MAAM,GAAG,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;QACvD,MAAM,IAAI,UAAU,CAAC,wBAAwB,WAAW,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACvC,CAAC;AAED,SAAS,SAAS,CAAC,GAAY;IAC7B,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW;SACzB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACT,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,CACvF;SACA,IAAI,CAAC,GAAG,CAAC,CAAC;IACb,OAAO,WAAW,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC;AAClE,CAAC;AAED,SAAS,OAAO,CAAC,IAA6B;IAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrF,CAAC;AAED,SAAS,UAAU,CAAC,OAAmC;IACrD,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;QACnD,KAAK,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE;QACnG,IAAI,CAAC,WAAW;KACjB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,MAAM,QAAQ,GAAG,CAAC,UAAU,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAClF,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;QAC3B,QAAQ,CAAC,IAAI,CACX,EAAE,EACF,YAAY,EACZ,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CACpE,CAAC;IACJ,CAAC;IACD,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,cAAc,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1F,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,QAAmB;IAC9C,OAAO;QACL,gDAAgD;QAChD,EAAE;QACF,WAAW;QACX,OAAO,CACL,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC;YACpB,SAAS,CAAC,GAAG,CAAC;iBACX,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;iBACxB,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC;YAC/B,GAAG,CAAC,OAAO;SACZ,CAAC,CACH;QACD,EAAE;QACF,iBAAiB;QACjB,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;QACnC,EAAE;QACF,qEAAqE;KACtE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/cli/turn.d.ts

@@ -4,7 +4,7 @@
  * turn through `agent.workflow.send`; `decide` / `reply` / `deliver` each
  * resume one, and every outcome is described the same way.
  */
-import type { Agent } from "../agent.js";
+import type { Agent, TurnFile } from "../agent.js";
 import type { TriggerInput } from "../machine/triggers.js";
 import type { DecideOutcome, Outcome, ReplyOutcome } from "../sessions/resume.js";
 import type { WorkflowMachine } from "../machine/machine.js";
@@ -27,6 +27,8 @@ export interface RunTurnInput {
     prompt: string;
     trigger?: TriggerInput;
     variables?: Record<string, unknown>;
+    /** Local files handed to the turn (`--file`), each seeding its variable with the placed path. */
+    files?: Record<string, TurnFile>;
     sessionId?: string;
     sessionPath?: string;
 }

package/dist/cli/turn.js

@@ -192,6 +192,7 @@ export async function driveTurn(agent, style, usage, input) {
             message: input.prompt,
             trigger,
             ...(input.variables ? { variables: input.variables } : {}),
+            ...(input.files ? { files: input.files } : {}),
             ...(input.sessionPath ? { sessionPath: input.sessionPath } : {}),
         });
         const code = printOutcome(style, workflow.machine, sessionId, outcome);