@awebai/oats 0.29.3 → 0.29.4

package/docs/design/2026-09-27-team-model-v2.md

@@ -0,0 +1,136 @@
+# Team model v2: the workspace defines teams and the default; souls declare which they may join
+
+Status: **PROPOSED 2026-09-27** (the lead drafts; the messaging co-lead shapes it; the human confirms the open questions). It supersedes teams-contract §3 amendment K's default-team rule and the "primary" label. The rest of `2026-09-25-teams-contract.md` stands: explicit join, only eligible labels, live reconciliation, and the provider's join/leave verbs.
+
+## The human's direction (2026-09-27, verbatim)
+
+> "El workspace define los equipos que hay, y a que equipo se instancian los souls por default. Y luego en el soul.yaml defines a que equipos se puede unir ese soul, y un default si quieres override el default de el workspace."
+>
+> "we do not need aweb primitives for this, we already have teams. we need to be able to add and remove souls to teams."
+>
+> "only pepe and i are using this for now, just clean up and do the right thing. no backwards comp required. setup may require creating accounts and teams, we need to support onboarding."
+
+## Why: today's model has four overlapping ideas
+
+1. The workspace's `teams:` labels + `messaging.byTeam.<label>` map labels to provider teams. This part is right.
+2. **The default team is not the workspace's.** After amendment K it's the provider setting `team`, else the provider's own default. For oats.aweb that's the messaging root's active team: host state, invisible in config.
+3. **"Primary"** (the first of a soul's `team:` labels) sets `OATS_TEAM_LABEL` and ordering but isn't the default team.
+4. **`oats-membership.yaml` `team`** is a repository-level default label layered under the soul's.
+
+On top of that, a soul can override the default only by writing a provider team *id* in its messaging slot, not a workspace label. And adding or removing a soul's teams means hand-editing YAML.
+
+## The model
+
+### The workspace (`oats-workspace.yaml`)
+```yaml
+teams:
+  dev:      { description: … }
+  platform: { description: … }
+defaultTeam: dev                 # NEW: required when `teams` is non-empty; a declared label
+messaging:
+  oats.aweb: { from: package }
+  byTeam:
+    dev:      { team: <provider team id> }
+    platform: { team: <provider team id> }
+```
+- **`teams:`** declares the teams that exist (labels), as today.
+- **`defaultTeam:`** is the team a soul's instances go to by default. It's a label, never a provider id.
+- **`messaging.byTeam.<label>`** maps each label to its provider team, as today. It's the ONLY place a provider team id is written.
+- **Validation:** `defaultTeam` must be a declared label (`E_TEAM_UNKNOWN`). Once messaging is active, the default team's label must be mapped (`E_TEAM_UNMAPPED`, a refusal, not a warning: an instance must have somewhere to live).
+
+### The soul (`soul.yaml`)
+```yaml
+teams: [dev, platform]           # RENAMED from `team`: the teams this soul MAY join
+defaultTeam: platform            # NEW, optional: overrides the workspace's; must be in `teams`
+```
+- **`teams:`** is the eligible labels. Each must be declared by the workspace (`E_TEAM_UNKNOWN`), as today. The list is unordered: **"primary" goes away.**
+- **`defaultTeam:`** is optional. It must be one of the soul's `teams`, else `E_TEAM_NOT_ELIGIBLE`. When omitted, the workspace's `defaultTeam` applies, and the soul is eligible for it implicitly.
+- **Removed:**
+  - a soul's messaging-slot provider team id override;
+  - `oats-membership.yaml` `team` (two layers only: the workspace, then the soul);
+  - the old `team:` key.
+
+  No aliases (the human: no backwards compatibility).
+
+### Resolution (the kernel)
+- `effectiveDefault = soul.defaultTeam ?? workspace.defaultTeam`.
+- The provider receives the default team's mapped payload as its default. It gets **no root-active-team fallback.**
+- Plus the eligible set, `{label → payload}` for every label in `soul.teams ∪ {effectiveDefault}` that the workspace maps.
+- **The env names** (renamed, no aliases):
+  - `OATS_DEFAULT_TEAM` (the label) and `OATS_DEFAULT_TEAM_ID` (its mapped provider id);
+  - `OATS_TEAMS` (the JSON of the eligible set).
+  - `OATS_TEAM_LABEL`, `OATS_TEAM_LABELS` and `OATS_TEAM_ID` go.
+- **A standalone deployment** (no workspace) sets `teams` / `defaultTeam` / `messaging.byTeam` in its local config, with the same rules.
+
+### At spawn, and live
+- An instance is **always in its effective default team** (it can't leave it: `E_TEAM_DEFAULT`).
+- It joins other eligible teams explicitly: the spawn choice `join=…`, or the provider's join/leave on a live instance. This is unchanged from the teams contract.
+- **When a soul loses a label**, or the workspace unmaps it, a joined instance leaves it on the next live read. This is unchanged: teams contract §7 decision 6.
+- **When the effective default changes** (the workspace or soul `defaultTeam` edited), running instances keep their team until respawn. Readiness warns (`default-team-changed`) and names the new default.
+
+### Verbs: add and remove a soul's teams, set its default
+The CLI edits `soul.yaml` for a soul the deployment can edit (a member soul in a clone on this computer, or a local soul):
+```
+oats soul teams <soul>                                  # eligible, default (and where it comes from)
+oats soul teams <soul> --add <label>[,<label>] | --remove <label>[,<label>]
+oats soul teams <soul> --default <label> | --clear-default
+```
+- Each edit validates against the workspace (known label; the default ∈ teams) and writes the file.
+- **For a member soul it edits the clone's working tree and says so:** the change travels by commit/PR, as every config change does (oats.setup). It never pushes.
+- **Package souls are read-only:** their teams are the package's. A workspace adds a package soul to a team through the workspace instead, `teams.<label>.souls: [<pkg>/<soul>]`, which extends that soul's eligible set. Proposed; see Open question 3.
+- The Desktop gets the same controls on a soul's page (add/remove/default), and the spawn dialog shows the default + eligible teams.
+
+### Onboarding (setup creates accounts and teams)
+- **`oats aweb setup`** (the provider's setup verb, a setup-time human act):
+  - creates the account (`aw init --new-account --username …`) when none exists;
+  - creates every declared team that the workspace doesn't map yet;
+  - writes the resulting ids into `messaging.byTeam` **as a proposed diff** for the human to commit (oats.setup: config changes by PR).
+  - It never runs at spawn, mint, retire or wake.
+- **What aweb allows today** (the messaging lane, from aweb's lead, 2026-09-27):
+  - **The first account and its default team:** fully automatable (`aw init --new-account --username …`).
+  - **An additional team on a BYOD domain:** automatable headlessly with the namespace controller key:
+    1. `aw id team create --name <t> --namespace <domain>`;
+    2. the team key signs `aw id team invite`;
+    3. the root runs `accept-invite --local`.
+
+    `aw id team register` hosts it on aweb.ai. No human login is needed.
+  - **An additional team on a hosted account (`<u>.aweb.ai`):** NO CLI path. Only a logged-in human creates it, in the dashboard. aweb's lead proposes a generic `aw team create <name>` under the logged-in account.
+- **Update (2026-09-27, the human's decision via aweb's lead): the hosted gap closes headlessly** (aweb `aweb-abkh`, pending a Cloud + CLI release).
+  - A member of an org-owned hosted team creates a sibling team in the same account with `aw id team create --name <t>`, which returns the new `team_id` + a **single-use invite token**. The caller doesn't auto-join.
+  - The home that should hold the new team's member runs `aw --identity-home <root> id team accept-invite <token> --name <alias> --local`.
+  - No TTY, no `aw auth`; bounded by the account plan's team limit.
+- **So setup is designed FULLY HEADLESS:**
+  1. The account + the workspace's default team: `aw init --new-account --username …`.
+  2. Every further declared team (hosted or BYOD): `aw id team create --name <label>` + `accept-invite --local` into the deployment's root.
+  3. Setup writes each new id into `messaging.byTeam` as a proposed diff for the human to commit.
+- **The only gate is the aw/Cloud version floor** that ships `aweb-abkh`. Below it, a hosted extra team is refused with the remedy "upgrade aw" (the provider's readiness names the floor), not a guided dashboard step. The model doesn't change.
+- Setup needs no human login at all on this path.
+- Setup never runs at spawn/mint/retire/wake, and OATS holds no human login (the provider consumes the resulting root).
+- The oats.setup skills (`oats-teams`, `oats-onboarding`, `oats-workspace-config`) teach the model and the verbs.
+
+## Open questions (for the human)
+1. **At spawn:** is an instance in ONLY its default team (others joined explicitly), as proposed? Or does it join every team its soul lists?
+2. **When a soul's team is removed:** do running instances leave on the next live read (proposed, as today), or only when told to?
+3. **Package souls:** is a workspace-side `teams.<label>.souls: [...]` the right way to add a package soul to a team? The alternative is that package souls have only their package's teams.
+
+## Sequencing (proposed)
+1. **Now, small (the messaging lane):** an oats.aweb release with the setup `--new-account` fix + the dead `helperInjection` key.
+2. **This design:** the co-lead shapes it → the human answers 1–3 → **Decided**.
+3. **Kernel 0.30.0 (breaking):**
+   - the schemas;
+   - resolution + env;
+   - the `oats soul teams` verb;
+   - readiness;
+   - the oats.setup skills;
+   - docs.
+4. **oats.aweb 1.17:** the default from the kernel (no root-active fallback); `oats aweb setup` onboarding.
+5. **Desktop:**
+   - the server passes the new fields (the engineer);
+   - the soul-page team controls + the spawn dialog (the ux-designer).
+6. **The KB + migration** of the two existing deployments (one-shot, by the humans with the setup-admin soul).
+
+**Owners (proposed):**
+- the kernel: a cli-dev;
+- oats.aweb + onboarding: the messaging co-lead's developer;
+- the Desktop: the engineer + the ux-designer;
+- this doc, the review and the release: the lead.

package/docs/official-catalog.md

@@ -68,8 +68,8 @@ this policy does not invent new catalog or manifest fields.
 - Listed capabilities: `oats.okf`, `oats.okf-harvest`, `oats.okf-maintenance`,
   `oats.aweb`, `oats.authoring`, `oats.jira`, `oats.linear`, `oats.dev`,
   `oats.knowledge-theory`, `oats.core` and `oats.setup`. `oats.okf-harvest` and
-  `oats.okf-maintenance` select the `oats.okf` package (4.0.0).
-- **`oats.framework` 1.3.1** is listed at tag `oats-framework/v1.3.1` in
+  `oats.okf-maintenance` select the `oats.okf` package (4.0.1).
+- **`oats.framework` 1.3.2** is listed at tag `oats-framework/v1.3.2` in
   `awebai/oats`, payload root `oats-package`. The `oats.core`, `oats.setup` and
   `oats.knowledge-theory` aliases select that distribution; package identity is
   distinct from capability identity. Core supplies operation/soul guidance;

package/docs/packages.md

@@ -74,8 +74,8 @@ members:
   - git:github.com/acme/agents
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.3.1
-  oats.okf: v4.0.0
+  oats.framework: v1.3.2
+  oats.okf: v4.0.1
   oats.aweb: v1.16.0
 teams:
   global: { description: Org-wide }
@@ -344,8 +344,8 @@ A soul that names one of the package's capabilities with
 }
 ```
 
-`ref` carries the tag convention: a workspace's `oats.framework: v1.3.1`
-resolves to tag `oats-framework/v1.3.1`. Resolving through the catalog never
+`ref` carries the tag convention: a workspace's `oats.framework: v1.3.2`
+resolves to tag `oats-framework/v1.3.2`. Resolving through the catalog never
 advances a lock by itself — `oats sync` does, and
 says so.
 

package/docs/release-notes/v0.29.4.md

@@ -0,0 +1,90 @@
+# OATS 0.29.4
+
+## Security
+
+- **An automation's `model` could inject spawn options** (#255). A trigger's
+  `spawn.model` or a schedule's `model` such as `--task-file=<path>` was passed
+  to the child `oats spawn` as a flag of its own. It could make any readable
+  file the instance's `TASK.md`, or add `--work` or `--allow-child-spawns`,
+  past the automation schema. Three changes close it:
+  - `model` must be a model id; a schedule's `agent` and `repo` may not start
+    with `-`;
+  - every value reaches the child as one `--flag=value` token;
+  - the CLI refuses an inline value that is itself an option (`--model=--yolo`
+    is `E_BAD_ARGS`).
+- **oats.okf 4.0.1: a crafted Git base could write files anywhere the user
+  can write** (okf 3.0.0 and 4.0.0). Every tree entry of a base's accepted
+  commit is now contained, and a bad entry refuses the whole base with
+  `E_PATH`. Upgrade the pin; details under oats.okf 4.0.1 below.
+
+## Fixed
+
+- **A member repository named `local`** collided with this host's own
+  triggers and schedules (`local/<id>`): their state, live counts and CLI
+  edits. Such a member is now `E_AUTOMATION_DUPLICATE`, and its automations
+  are not listed (#256).
+- **A workspace command's `cwd` may no longer leave the deployment**, through
+  `..` or a symlink (#256).
+- **A newer push supersedes a pending `synchronize`** for an older head of the
+  same pull request (#256).
+- **A workspace trigger's `owner` and `on.repo` must be on the same GitHub
+  host** (#256).
+- **Upgrading from 0.28 re-fired every open pull request.** Trigger state kept
+  under a local trigger's bare id (0.28) is now carried to `local/<id>`, so
+  nothing re-fires. Homes that 0.28 spawned still count toward the trigger's
+  concurrency (#256).
+- **A package soul's command could get another soul's `OATS_SOUL`.** A command
+  run from the deployment with `--soul <package>/<soul>` read the soul's copy
+  under the bare name's agent directory. It ran without `OATS_SOUL`, or with a
+  same-named member soul's copy. It now reads `agents/<package>--<soul>/`
+  (#256).
+
+## Changed
+
+- **`helperInjection` is marked deprecated in the capability manifest
+  schema** (#257). It has been ignored since 0.26 and is still accepted, so
+  old manifests validate. oats.core 2.1.2 and oats.setup 2.1.3 no longer
+  declare it; the catalog and this repo's workspace pin `oats.framework` to
+  `oats-framework/v1.3.2`, which ships them.
+- **`triggersMaxConcurrent`** in the host registry
+  (`~/.oats/schedules/registry.json`) caps trigger-spawned live instances
+  across the host's scopes (#256). It is absent by default, which means no
+  host cap: each trigger's own `concurrency.max` applies. It is separate from
+  the schedules' `maxConcurrent`: neither counts the other's instances.
+
+## oats.okf 4.0.1 (catalog pin and bundled mirror)
+
+The catalog and this repo's workspace pin `oats.okf` to `v4.0.1`. The three
+bundled capabilities (`oats.okf`, `oats.okf-harvest`, `oats.okf-maintenance`)
+are the tag's trees. The kernel floor stays `>=0.29.0`.
+
+- **Security: a crafted Git base could write files anywhere the user can
+  write.** This affects okf 3.0.0 and 4.0.0: upgrade.
+  - Validating a Git base's accepted commit copied every tree entry into a
+    scratch directory with no containment check. Git accepts literal `..`
+    entries.
+  - The first `oats okf bases`, or a spawn against a crafted accepted commit,
+    could create any file that did not yet exist, with attacker content.
+  - Every entry is now checked against the canonical path rules, and its
+    target must stay inside the scratch. All entries are checked before
+    anything is written, and the first bad entry refuses the whole base with
+    `E_PATH`. The staging materializer asserts the same.
+  - GitHub probably blocks such a push; local and self-hosted bases do not.
+- **Credentials are never shown to agents.** A repository URL with a user or
+  token in it is refused at binding: use a Git credential helper or an SSH
+  key. Every repository in `bases` output and in errors is redacted,
+  including Git's own failure text.
+- **Knowledge review trusts only the accepted base.**
+  `review-context --checkout` takes node ownership from the base's accepted
+  `okf-base.json`, never from the PR. It lists the nodes a PR claims but the
+  source does not own, and flags any change to `okf-base.json`.
+- **A merge is tied to the reviewed head**
+  (`gh pr merge --match-head-commit`). **`okf-needs-human` is a hard stop**
+  for every PR event, until a human removes the label.
+- **Turning harvest off takes effect at once.** `run-source` and `retire`
+  re-read the harvest switch, including the soul's. A soul or deployment that
+  turns harvest off after spawn stops capture at the next run. Retire then
+  takes no final capture; inputs already in custody stay.
+- **`OATS_SETTINGS_ORIGINS` is an extra signal:** a harvest value that comes
+  from the soul never switches harvest on. `soul.yaml` stays the authority for
+  the absolute opt-out.

package/docs/schedules.md

@@ -27,7 +27,11 @@ and no queue.
 - `<workspace>/.agents/schedules/state.json` — last attempted minute and
   last run per job (gitignored), plus one lock directory per running job.
 - `~/.oats/schedules/registry.json` — the host registry: which scopes the
-  host ticks, `maxConcurrent` (default 1) and the tick interval. One host
+  host ticks, `maxConcurrent` (default 1: running scheduled jobs), the tick
+  interval, and `triggersMaxConcurrent` (absent by default: no host cap; a
+  positive integer caps trigger-spawned live instances across the host's
+  scopes). The two caps are separate: a running scheduled job never holds a
+  trigger, and a trigger's instances never hold a schedule. One host
   lock serializes ticks, run-now, reconcile and remove; it is never reclaimed
   by another process: a lock whose owner is unreadable or gone is reported
   with the directory to remove, and the holder removes its own lock on exit
@@ -41,7 +45,11 @@ see [Captured definitions](#captured-definitions-removed-in-026).
 - **spawn** `{id, enabled, cron, tz, kind: "spawn", agent, agentsRoot?,
   repo?, backend?, purpose?, task, launchConfig?, harness?, model?, yolo?, wake?}` — every
   due minute launches one disposable instance of `agent` with the same
-  options `oats spawn` takes. `agentsRoot` names the exact agents root that
+  options `oats spawn` takes. `model` is a model id (a letter or digit, then
+  letters, digits and `. _ : / @ + - [ ]`, at most 128 characters, or
+  `@native-default`), and `agent` and `repo` never start with `-`: an
+  automation's values reach the child `oats spawn` as single `--flag=value`
+  tokens and can never be read as options of their own. `agentsRoot` names the exact agents root that
   holds the soul (it must lie inside the workspace and defaults to the
   workspace's own root); it is what tells same-named souls in different
   member repositories apart. `repo` is the work repository, as `--repo`.
@@ -144,8 +152,14 @@ logged in with the keyring or its config file under your HOME works there. A
   finds its own earlier review, for example).
 - **Concurrency.** `max` (default 1) bounds the live instances of the trigger,
   `perKey` (default 1) those of one PR; both are counted from the homes'
-  `instance.json.trigger` records, so a retired instance frees its slot. An
-  event over the bound stays pending (`held`).
+  `instance.json.trigger` records, so a retired instance frees its slot. The
+  host registry's `triggersMaxConcurrent`, when set, bounds every trigger's
+  live instances together. An event over a bound stays pending (`held`). A
+  newer push supersedes a pending `synchronize` for an older head of the same
+  PR, so only the newest head is reviewed.
+- **The owner acts on the repository's host.** A workspace trigger's `owner`
+  and `on.repo` must be on the same GitHub host (`E_TRIGGER_INVALID`, field
+  `owner`): the owner check and the poll ask gh on that one host.
 - **The spawn** is `oats spawn` (the same path as a scheduled spawn). `soul` is
   bare or qualified (`<package>/<soul>`). `purpose` (default
   `{trigger}-{number}`, must render to a slug) and `task` are templated from

package/docs/workspaces.md

@@ -59,8 +59,8 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
   - git:github.com/acme/tools              # a member that ALSO publishes a package (see below)
 
 packages:                                  # the ONLY versioned things
-  oats.framework: v1.3.1                   # bare version → resolves through the official catalog
-  oats.okf: v4.0.0
+  oats.framework: v1.3.2                   # bare version → resolves through the official catalog
+  oats.okf: v4.0.1
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 
 teams:                                     # labels, declared once so they cannot drift

package/lib/automations.mjs

@@ -43,6 +43,10 @@ export const PLACEMENT_REASONS = Object.freeze(["host-unnamed", "assigned-elsewh
 export const KIND_NAMES = Object.freeze(["trigger", "schedule"]);
 const NEVER_SCANNED = new Set(["oats-package", ".git", "node_modules"]);
 export const AUTOMATION_ID_RE = /^[a-z0-9-]{1,40}$/;
+/** A model id an automation may pass to `oats spawn --model`: a provider/model id, never an option.
+ *  The first character is alphanumeric (or the spawn CLI's own `@native-default`), so no value can
+ *  be read as a flag (re-review B #1). `[` `]` admit a harness's context-size alias (`opus[1m]`). */
+export const MODEL_RE = /^(?:@native-default|[A-Za-z0-9][A-Za-z0-9._:/@+\[\]-]{0,127})$/;
 export const HOST_NAME_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const OWNER_RE = /^([a-z0-9-]+(?:\.[a-z0-9-]+)+)\/([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))$/;
 const HEADER_KEYS = ["kind", "schemaVersion", "id", "description", "runsOn", "owner", "enabled"];
@@ -123,6 +127,9 @@ export async function discoverAutomations(discovery, { remote, memberName, kinds
   const names = new Map();
   for (const m of (discovery?.members || []).filter((x) => x.confirmed && x.commit)) {
     const name = memberName(m.key);
+    // `local/<id>` names this host's own automations (and their state, live counts and CLI edits):
+    // a member labelled `local` would collide with them (re-review B #3).
+    if (name === LOCAL) { problems.push({ code: "E_AUTOMATION_DUPLICATE", repoKey: m.key, path: "", message: `member name ${JSON.stringify(name)} is reserved for this host's own triggers and schedules (local/<id>), so ${m.key}'s are not listed — rename the repository to list them` }); continue; }
     if (names.has(name)) { problems.push({ code: "E_AUTOMATION_DUPLICATE", repoKey: m.key, path: "", message: `member name ${JSON.stringify(name)} is also ${names.get(name)}'s: triggers and schedules are named <member>/<id>, so ${m.key}'s are not listed` }); continue; }
     names.set(name, m.key);
     let candidates;

package/lib/packages.mjs

@@ -372,11 +372,8 @@ export async function packageSoulDigests(remote, remoteRef, commit, souls, detai
         if (e?.code === "E_REMOTE_PATH_MISSING") throw oatsError("E_PACKAGE_MANIFEST", `package soul ${soul.path} is missing at ${String(commit).slice(0, 12)}`, { ...details, soul: soul.name, path: soul.dir });
         throw e;
       }
-      // A fake remote reports a digest without copying: only a real copy can be checked for its files.
-      if (existsSync(dest)) {
-        for (const file of ["soul.yaml", "AGENTS.md"]) {
-          if (!existsSync(join(dest, file))) throw oatsError("E_PACKAGE_MANIFEST", `package soul ${soul.path} lacks ${file} at ${String(commit).slice(0, 12)} — a soul directory carries soul.yaml and AGENTS.md`, { ...details, soul: soul.name, path: soul.dir, missing: file });
-        }
+      for (const file of ["soul.yaml", "AGENTS.md"]) {
+        if (!existsSync(join(dest, file))) throw oatsError("E_PACKAGE_MANIFEST", `package soul ${soul.path} lacks ${file} at ${String(commit).slice(0, 12)} — a soul directory carries soul.yaml and AGENTS.md`, { ...details, soul: soul.name, path: soul.dir, missing: file });
       }
       out.push({ name: soul.name, path: soul.path, digest: assertDigest(`package soul ${soul.path} digest`, digest, details) });
     }

package/lib/schedule.mjs

@@ -21,7 +21,7 @@
  *  succeeded. A launch whose side effects cannot be confirmed stays
  *  `unknown` with its slot held until `reconcile` proves what happened. */
 import { spawnSync } from "node:child_process";
-import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
@@ -31,7 +31,7 @@ import { loadLocal } from "./workspace.mjs";
 import { noteRuntimeName } from "./deprecation.mjs";
 import { tickTriggers } from "./triggers.mjs";
 import { resolveMemberClone } from "./instance-resolution.mjs";
-import { AUTOMATION_ID_RE, automationContext, automationError, baseRow, localEntry, localId, soulOriginOf, splitId } from "./automations.mjs";
+import { AUTOMATION_ID_RE, MODEL_RE, automationContext, automationError, baseRow, localEntry, localId, soulOriginOf, splitId } from "./automations.mjs";
 import { RESERVED_LAUNCH_ENV, MAX_INSTANCE_NAME, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
 
 export const SCHEDULE_FILE = "oats-schedules.json";
@@ -208,6 +208,12 @@ export function readRegistry() {
   if (!Array.isArray(reg.workspaces)) reg.workspaces = [];
   if (!Number.isInteger(reg.maxConcurrent) || reg.maxConcurrent < 1) reg.maxConcurrent = 1;
   if (!Number.isInteger(reg.tickIntervalSec) || reg.tickIntervalSec < 60) reg.tickIntervalSec = 60;
+  // The host cap on trigger-spawned live instances (re-review B #5): absent = unbounded (each
+  // trigger's own concurrency.max still applies). Separate from maxConcurrent: a running scheduled
+  // job never holds a trigger, and trigger homes never hold a schedule. Hand-edited, so refused loudly.
+  if (reg.triggersMaxConcurrent !== undefined && !(Number.isSafeInteger(reg.triggersMaxConcurrent) && reg.triggersMaxConcurrent >= 1)) {
+    throw scheduleError("E_SCHEDULE_INVALID", `${join(hostScheduleDir(), "registry.json")}: triggersMaxConcurrent must be a positive integer, or absent for no host cap (got ${JSON.stringify(reg.triggersMaxConcurrent)})`, { field: "triggersMaxConcurrent" });
+  }
   return reg;
 }
 export function writeRegistry(reg) { writeJson(join(hostScheduleDir(), "registry.json"), reg); }
@@ -300,14 +306,14 @@ export function validateDefinition(ws, def, { checkAgent = true } = {}) {
   validateCron(def.cron, def.tz);
   const out = { id, enabled, cron: def.cron.trim(), tz: def.tz.trim(), kind: def.kind };
   if (def.kind === "spawn") {
-    if (typeof def.agent !== "string" || !def.agent.trim()) throw scheduleError("E_SCHEDULE_INVALID", "agent: soul name required", { field: "agent" });
+    if (typeof def.agent !== "string" || !def.agent.trim() || def.agent.trim().startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", "agent: soul name required (not an option)", { field: "agent" });
     out.agent = def.agent.trim();
     if (def.agentsRoot !== undefined) {
       const known = scopeRoots(ws);
       if (typeof def.agentsRoot !== "string" || !isAbsolute(def.agentsRoot) || !inside(ws, def.agentsRoot) || !known.includes(resolve(def.agentsRoot))) throw scheduleError("E_SCHEDULE_INVALID", `agentsRoot: must be one of this scope's agents roots (${known.join(", ") || "none"})`, { field: "agentsRoot" });
       out.agentsRoot = resolve(def.agentsRoot);
     }
-    if (def.repo !== undefined) { if (typeof def.repo !== "string" || !def.repo.trim()) throw scheduleError("E_SCHEDULE_INVALID", "repo: the work repository path, as oats spawn --repo", { field: "repo" }); out.repo = def.repo; }
+    if (def.repo !== undefined) { if (typeof def.repo !== "string" || !def.repo.trim() || def.repo.startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", "repo: the work repository path, as oats spawn --repo", { field: "repo" }); out.repo = def.repo; }
     if (def.backend !== undefined) { if (!BACKENDS.has(def.backend)) throw scheduleError("E_SCHEDULE_INVALID", "backend: tmux or herdr", { field: "backend" }); out.backend = def.backend; }
     if (def.purpose !== undefined) { if (typeof def.purpose !== "string" || !/^[a-z0-9-]{1,40}$/.test(def.purpose)) throw scheduleError("E_SCHEDULE_INVALID", "purpose: lowercase letters, digits and dashes", { field: "purpose" }); out.purpose = def.purpose; }
     // A run spawns <agent>-<purpose|id>-<YYYYMMDDHHMM>; instance names are at most
@@ -323,7 +329,7 @@ export function validateDefinition(ws, def, { checkAgent = true } = {}) {
     }
     if (def.launchConfig !== undefined) { if (typeof def.launchConfig !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(def.launchConfig)) throw scheduleError("E_SCHEDULE_INVALID", "launchConfig: the name of a launch configuration on the running host (oats-local.yaml launch-configs)", { field: "launchConfig" }); out.launchConfig = def.launchConfig; }
     if (def.harness !== undefined) { if (!HARNESSES.has(def.harness)) throw scheduleError("E_SCHEDULE_INVALID", "harness: pi, claude or codex", { field: "harness" }); out.harness = def.harness; }
-    if (def.model !== undefined) { if (typeof def.model !== "string") throw scheduleError("E_SCHEDULE_INVALID", "model: string", { field: "model" }); out.model = def.model; }
+    if (def.model !== undefined) { if (typeof def.model !== "string" || !MODEL_RE.test(def.model)) throw scheduleError("E_SCHEDULE_INVALID", "model: a model id: a letter or digit, then letters, digits and . _ : / @ + - [ ] (at most 128 characters)", { field: "model" }); out.model = def.model; }
     if (def.yolo !== undefined) { if (typeof def.yolo !== "boolean") throw scheduleError("E_SCHEDULE_INVALID", "yolo: boolean", { field: "yolo" }); out.yolo = def.yolo; }
     if (def.wake !== undefined) {
       const w = def.wake;
@@ -402,6 +408,10 @@ export function validateWorkspaceSchedule(dep, a) {
   if (spec.kind === "command") {
     if (d.cwd !== undefined && (typeof d.cwd !== "string" || isAbsolute(d.cwd))) throw scheduleError("E_SCHEDULE_INVALID", "cwd: a directory relative to the deployment (a workspace schedule never names a machine path)", { field: "cwd" });
     spec.cwd = resolve(dep, d.cwd ?? ".");
+    // Inside the deployment, `..` and symlinks included (re-review B #4): Git content never picks a
+    // directory elsewhere on the host.
+    const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+    if (!inside(real(dep), real(spec.cwd))) throw scheduleError("E_SCHEDULE_INVALID", `cwd: ${JSON.stringify(d.cwd)} leaves the deployment; a workspace command's cwd is a directory inside it`, { field: "cwd" });
   }
   const out = validateDefinition(dep, spec, { checkAgent: false });
   delete out.enabled;
@@ -521,19 +531,22 @@ export function workspaceSpawnContext(ws) {
  *  `io.oatsBin`, `io.commandTimeoutMs` and `io.noLaunch` are the test seams. */
 function spawnViaCli(ws, root, agent, opts, context, io) {
   if (context.error) throw scheduleError(context.error.code, `this deployment realizes a workspace (${context.dir}) but its oats-local.yaml cannot be read: ${context.error.message}`);
-  const argv = ["spawn", agent.name, "--dir", context.dir, ...(opts.discover ? [] : ["--agents-root", root]), "--purpose", opts.purpose, "--json"];
-  if (opts.launchConfig) argv.push("--launch-config", opts.launchConfig);
-  if (opts.harness) argv.push("--harness", opts.harness);
-  if (opts.model) argv.push("--model", opts.model);
-  if (opts.backend) argv.push("--backend", opts.backend);
-  if (opts.repo) argv.push("--repo", opts.repo);
+  // Every value travels as ONE `--flag=value` token, so no value can be read as a flag of its own;
+  // the soul is the one positional, and an option-shaped one is refused.
+  if (String(agent.name).startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", `agent: ${JSON.stringify(agent.name)} is not a soul name`, { field: "agent" });
+  const argv = ["spawn", agent.name, `--dir=${context.dir}`, ...(opts.discover ? [] : [`--agents-root=${root}`]), `--purpose=${opts.purpose}`, "--json"];
+  if (opts.launchConfig) argv.push(`--launch-config=${opts.launchConfig}`);
+  if (opts.harness) argv.push(`--harness=${opts.harness}`);
+  if (opts.model) argv.push(`--model=${opts.model}`);
+  if (opts.backend) argv.push(`--backend=${opts.backend}`);
+  if (opts.repo) argv.push(`--repo=${opts.repo}`);
   if (opts.yolo === true) argv.push("--yolo"); else if (opts.yolo === false) argv.push("--no-yolo");
   if (opts.launch === false) argv.push("--no-launch");
   // The task is multi-line text of arbitrary size: it travels as a private file, never in argv.
   mkdirSync(join(stateDir(ws), "tasks"), { recursive: true });
   const taskFile = join(stateDir(ws), "tasks", `${opts.purpose}-${process.pid}.md`);
   writeFileSync(taskFile, opts.task, { mode: 0o600 });
-  argv.push("--task-file", taskFile);
+  argv.push(`--task-file=${taskFile}`);
   let r;
   try { r = spawnSync(process.execPath, [io?.oatsBin || OATS_BIN, ...argv], { cwd: context.dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: io?.commandTimeoutMs || COMMAND_TIMEOUT_MS, killSignal: "SIGTERM", maxBuffer: 16 * 1024 * 1024, env: childEnv() }); }
   finally { try { rmSync(taskFile, { force: true }); } catch { /* best effort */ } }
@@ -866,7 +879,7 @@ export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
     }
     // Triggers: each scope's event-driven spawns, polled at their own interval (lib/triggers.mjs).
     for (const ws of wsList) {
-      try { considered.push(...tickTriggers(ws, { now, io, dryRun, ctx: contexts.get(ws) })); }
+      try { considered.push(...tickTriggers(ws, { now, io, dryRun, ctx: contexts.get(ws), reg, wsList })); }
       catch (e) { considered.push({ workspace: ws, action: "error", error: `triggers: ${e.message}` }); }
     }
     if (!dryRun) writeHostState({ ...readHostState(), lastTick: now.toISOString(), minute: minuteKey(minuteStart(now)) });
@@ -978,10 +991,11 @@ export function testSchedule(ws, qid, io, { now = new Date(), ctx = null } = {})
       const { root, discover } = resolveScheduledAgent(ws, def);
       const context = workspaceSpawnContext(ws);
       if (context.error) throw scheduleError(context.error.code, context.error.message);
-      const argv = ["spawn", def.agent, "--dir", context.dir, ...(discover ? [] : ["--agents-root", root]), "--preview", "--json"];
-      if (def.launchConfig) argv.push("--launch-config", def.launchConfig);
-      if (def.harness) argv.push("--harness", def.harness);
-      if (def.model) argv.push("--model", def.model);
+      if (String(def.agent).startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", `agent: ${JSON.stringify(def.agent)} is not a soul name`, { field: "agent" });
+      const argv = ["spawn", def.agent, `--dir=${context.dir}`, ...(discover ? [] : [`--agents-root=${root}`]), "--preview", "--json"];
+      if (def.launchConfig) argv.push(`--launch-config=${def.launchConfig}`);
+      if (def.harness) argv.push(`--harness=${def.harness}`);
+      if (def.model) argv.push(`--model=${def.model}`);
       const r = spawnSync(process.execPath, [io?.oatsBin || OATS_BIN, ...argv], { cwd: context.dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: io?.commandTimeoutMs || COMMAND_TIMEOUT_MS, killSignal: "SIGTERM", maxBuffer: 16 * 1024 * 1024, env: childEnv() });
       const envelope = parseEnvelopeText(r.stdout);
       if (!envelope || typeof envelope.ok !== "boolean") throw scheduleError("E_SPAWN_FAILED", `the spawn preview answered no valid envelope (exit ${r.status ?? r.signal})`);