@archmax-ai/harness 0.6.1 → 0.7.1

package/skills/archmax-harness/references/workflow-schema.md

@@ -206,7 +206,8 @@ mounts?:
                               # validate ERRORS on a name the table does not mount.
   forbid_always?: string[]    # MOUNT NAMES out of reach of EVERY state, governed or
                               # not, whatever any list grants. Deny beats allow.
-                              # Inherited by every sub-workflow, naming the workflow
+                              # Binds this workflow's own HOOKS too, and is
+                              # inherited by every sub-workflow, naming the workflow
                               # that declared it. A NAME only — a denial is total, so
                               # there is no `access` to qualify. (A root `mounts.allow`
                               # is a load error: one mounts model.)
@@ -391,7 +392,11 @@ states:
                                # volatile prompt block, and filtered out of every
                                # ls/glob/grep result, the WORKSPACE ROOT LISTING
                                # included. Lifecycle HOOKS are exempt from this key
-                               # (runtime authority), but not from `forbid_always`.
+                               # (runtime authority), but not from `forbid_always`
+                               # nor from the WORKFLOW's grants: a hook reaches a
+                               # governed mount only if allow_always or SOME state's
+                               # allow names it, in any state, and writes it only
+                               # where a grant of the workflow asks `read_write`.
 
     model?: string             # MODEL ID ONLY — this state's turns run on it (and the
                                # handoff message of a park it holds). Most specific of
@@ -542,12 +547,18 @@ states:
 - `requires:` / `returns:` are the run's **signature**, and both are enforced. A
   firing that does not supply every `requires` name does not start. `returns`
   is checked once as the run finishes, and **nothing is handed back**: a
-  sub-workflow child with a name unset **completes**, and its caller gets the
-  returns it set plus `note: "Not all return variables were set by the
-  sub-workflow: '<name>' was not set."`; a top-level run with a name unset is
-  **rejected**; a typed one mistyped rejects either way. A run that *parks* is
-  not checked — it has not finished. `note` is reserved: a `returns` list may
-  not declare it. Want the model to try again? Check the returns in a terminal
+  sub-workflow child with a name unset **completes**, and its caller gets
+  every declared return, the unset ones `null`, plus `note: "Not all return
+  variables were set by the sub-workflow: '<name>' was not set."`; a top-level
+  run with a name unset is **rejected**; a typed one mistyped rejects either
+  way. A run that *parks* is not checked — it has not finished. A return is
+  owed **only at the finish**: `archmax_advance` checks a state's own
+  `requires:`, never the returns, a later write replaces an unlocked earlier
+  one, and a seed of one (a name in both lists) lands **unlocked** and does not
+  overwrite a value the session already holds. So do not list a return in a
+  state's `requires:` unless that state must settle it, and do not tell the
+  agent to lock one before its value is final. `note` is reserved: a `returns`
+  list may not declare it. Want the model to try again? Check the returns in a terminal
   `after` hook, which can `correct`. Each entry is a bare
   run-variable name (**untyped**: any value, `null` included) or a strict object
   `{ name, type?, description? }` naming one; the spellings mix in one list and
@@ -577,8 +588,10 @@ states:
   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
+  never), the workflow's mount grants taken across all its states (a governed
+  mount no state is granted is out of reach), and every workflow-wide
+  `forbid_always`, inherited ones included; the state's allow list and its own
+  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
@@ -774,7 +787,8 @@ workflow's grant, the state's own `allow` and the always-on surface alike.
 **Deny beats allow, and no narrower level widens a denial.** A forbid entry may
 name the tool `*` (every tool); `*` in an allow list is a load error. A lifecycle
 hook is exempt from the state's `allow` **and** its `forbid` — runtime authority,
-outside that surface both ways — but never from `forbid_always`.
+outside that surface both ways — but never from `forbid_always` (the workflow's
+own `tools.`, `skills.` and `mounts.forbid_always`, and every ancestor's).
 
 Precedence (highest first):
 
@@ -873,7 +887,8 @@ capability workflow-wide.
 Hooks are **exempt**: a `before`/`after` script reads authored data on runtime
 authority, so a state may enable nothing and still be gated by a hook that reads
 the very bundle the model cannot. That is the shape to reach for when a capability
-should *enforce* something without being *usable*.
+should *enforce* something without being *usable*. A bundle the workflow's
+`skills.forbid_always` denies is refused to its hooks too.
 
 **`tools.forbid` on a state denies there**, and `tools.forbid_always` at the
 root denies everywhere. Both beat every grant. Migrating a workflow off the
@@ -1015,7 +1030,18 @@ so `AGENTS.md.bak` is not captured.
 
 Hooks and rubric graders are bound by `mounts.forbid_always` and **not** by a
 state's `forbid` or its enabled set: they run on runtime authority, exactly as for
-tools, so a `before` hook can read a mount the model in that state cannot.
+tools, so a `before` hook can read a mount the model in that state cannot. A hook
+is still held to its **workflow's** grants, taken across every state:
+
+- it reads a governed mount only if `allow_always` or some state's `allow` names
+  it, else `mount.not-allowed`. The table serves every child too, so it can hold a
+  mount only a child grants, and the caller's hooks cannot reach that;
+- it writes one only where a grant of the workflow asks `access: read_write`, and an
+  `access: read` in `allow_always` narrows any mount for it (`mount.read-only`).
+
+So when a hook needs a mount no state's model should see, grant it in a state the
+hook's workflow has anyway, or in `allow_always` with the model's states
+forbidding it.
 
 ## Session variables in guards
 
@@ -1083,7 +1109,8 @@ scalar.
 **Authoring rules that matter:**
 
 - **Lock anything a guard reads.** Host seeds are locked automatically (`title`
-  excepted, which is never locked); for an agent-established fact pass `lock: true`. An unlocked variable can be
+  and a seed of a trigger's `returns` excepted, which land unlocked); for an
+  agent-established fact pass `lock: true` — on a return, only once it is final. An unlocked variable can be
   overwritten by any later state — that rewrite is permitted, being one writer
   twice, and the later value simply wins — so a guard bound to an unlocked name is
   a weak guard. A lock is the only thing that makes a fact settled.
@@ -1358,7 +1385,7 @@ enrich:
   (`unresolved-param`) and **disabled-target** refusals are blocked calls —
   nothing ran, so correct the call and retry. A child whose returns are
   mistyped (`invalid-return`) is a failure: it ran. One that left returns unset
-  is not: the call answers with what it set and a `note`.
+  is not: the call answers with them `null` and a `note`.
 - **A whole-argument reference keeps its type.** `{ quantity: "${{count}}" }`
   seeds the child with the number `count` holds, so it satisfies an `integer`
   parameter; `{ note: "order ${{order_id}}" }` is substituted as text.
@@ -1396,16 +1423,18 @@ enrich:
 
   A dispatch missing a `requires` name is **refused before the child is
   composed**; a child that completes without every `returns` name set
-  **completes anyway**, and the call answers with the returns it set plus a
-  `note` naming the rest — no second attempt is spent, and the caller decides
+  **completes anyway**, and the call answers with every declared return, the
+  unset ones `null`, plus a `note` naming them — no second attempt is spent, and
+  the caller decides
   (a child that *parks* is not checked — it has not finished; a child that
   raises fails the call `raised`). A typed entry is held to its type at both
   ends: a mistyped argument is refused `invalid-param` before the child runs, and
   a mistyped return fails the call `invalid-return`. What the child must *do* to
   produce a variable belongs in the state `instructions` that set it. The names,
   with type and description where declared, are rendered into the child's prompt
-  under its entry state, so it is told what to produce before it can be failed
-  for omitting it.
+  in every state, so it is told what to produce before it can be failed for
+  omitting it — and to set each once its final value is known, locking one only
+  when it is final.
 - **The call answers with the returns, by name.** A signed target answers
   `{ message, returns: { enrichment_file, delayed } }`; one declaring no
   `returns:` answers with the closing message alone. The message keeps its own
@@ -1416,7 +1445,7 @@ enrich:
 - **Mocks are held to the same contract.** An `archmax_workflow_<slug>` mock for a
   signed target supplies `returns:`. One that supplies a mistyped typed one
   (`invalid-return`) fails the mocked dispatch, and one that omits a declared
-  name answers like a real child that left it unset: what it supplied, plus a
+  name answers like a real child that left it unset: that name `null`, plus a
   `note` — a mock stands in for the sub-run, never for its agreement.
 - **No prose crosses the boundary.** A sub-run gets no instruction from its
   caller — it works from its own state `instructions` (system prompt) plus the
@@ -1499,7 +1528,8 @@ triggers:
   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
+  runtime authority (its own workflow's mount grants and `forbid_always`), 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

package/skills/archmax-harness/references/workflow-yaml.md

@@ -170,9 +170,9 @@ states:
   the agent back with the reason, bounded per hook by `max_iterations`
   (default 0 → a correct is a hard veto). A list runs in order and stops at
   the first non-ok. Errors and missing files veto (fail-closed). Hooks run
-  on runtime authority: the state's `allow`/`forbid`/`skills` do not bind
-  them; `forbid_always` and safety rules do. Human states may not declare
-  hooks.
+  on runtime authority: the state's `allow`/`forbid`/`skills`/`mounts` do not
+  bind them; `forbid_always`, safety rules and the workflow's mount grants
+  (any state's) do. Human states may not declare hooks.
 - **Budgets and `on_error`.** `budget.maxTurns`/`timeoutMs`/`maxParks` bound
   a state's segment. A terminal failure (hook execution error, exhausted
   corrections, exhausted budget, exhausted parks) routes to `on_error`
@@ -188,8 +188,11 @@ states:
   mistyped argument is refused `invalid-param`, and `"${{count}}"` alone
   passes the value with its own type), its `returns` the result
   (`{ message, returns }`; a child finishing with some unset completes, and
-  `returns` holds what it set plus a `note` naming the rest; a mistyped typed
-  return fails `invalid-return`). Each failed call is the
+  `returns` holds every declared one, the unset ones `null`, plus a `note`
+  naming them; a mistyped typed return fails `invalid-return`). Returns are
+  owed only at the finish: no state needs them to be left, a later write
+  replaces an unlocked earlier one, and a seed of one lands unlocked; lock one
+  only once it is final. Each failed call is the
   calling state's failure, recorded with its arguments and routed through
   `on_error` when the agent finishes unless a later successful call of the
   same workflow from the same state recovers it first. One success recovers
@@ -276,5 +279,6 @@ Closed by default; **deny beats allow, and no narrower level widens a denial.**
   A state enabling no skill can run no script at all.
 - **Scripts' `tools.*` calls** are governed per call: an `archmax_run` script
   is bound like the model (grant every tool it calls); a hook is exempt from
-  the state's lists. Neither may read `workflows/**` or write a mount. A
-  refused call throws inside the script.
+  the state's lists but held to its workflow's mount grants. Neither may read
+  `workflows/**` or write a read-only mount. A refused call throws inside the
+  script.