@hasna/loops 0.4.27 → 0.4.29

package/docs/USAGE.md

@@ -1,6 +1,6 @@
-# OpenLoops
+# Loops
 
-OpenLoops is a local CLI and daemon for persistent loops and workflows: scheduled or recurring work that survives process restarts and records every run.
+Loops is a local CLI and daemon for persistent loops and workflows: scheduled or recurring work that survives process restarts and records every run.
 
 It supports deterministic command loops, JSON-defined workflows, and guarded CLI adapters for headless coding agents:
 
@@ -13,18 +13,19 @@ It supports deterministic command loops, JSON-defined workflows, and guarded CLI
 
 ## Deployment Modes
 
-OpenLoops defaults to `local`, where SQLite in `LOOPS_DATA_DIR` is
+Loops defaults to `local`, where SQLite in `LOOPS_DATA_DIR` is
 authoritative and `loops-daemon` executes scheduled work. The package also
 defines `self_hosted` and `cloud` contracts for non-local control planes:
 
 - `self_hosted`: the Hasna-owned AWS/RDS control-plane deployment, served by
   `loops-serve` and backed by Postgres, with the embeddable `loops-api` contract
   shared by serve, SDK, and tests. This release exposes storage-backed `/v1`
-  loop CRUD and run listing, runner registration/claim/heartbeat/finalize
-  foundations, and local migration previews.
+  loop CRUD and run listing, runner claim/lease heartbeat/finalize foundations,
+  and local migration previews. Durable runner registration is not exposed
+  until the machine-record lifecycle is implemented.
 - `cloud`: hosted control-plane contract; this release exposes client/runner
-  status only, and requires `LOOPS_CLOUD_API_URL` plus `LOOPS_CLOUD_TOKEN` or
-  `HASNA_LOOPS_CLOUD_TOKEN` before status can report ready.
+  status only, and requires `HASNA_LOOPS_API_URL` plus
+  `HASNA_LOOPS_API_KEY` before status can report ready.
 
 Scheduler state is explicit in status JSON. `schedulerState.localStore` is
 SQLite plus local run artifact files: authoritative in `local`, cache/spool in
@@ -48,12 +49,11 @@ loops self-hosted status
 loops self-hosted migrate --dry-run
 loops self-hosted push --dry-run
 loops self-hosted pull --dry-run
-loops self-hosted runner-register --runner-id <id> --machine-id <machine>
-loops self-hosted runner-register --runner-id <id> --machine-id <machine> --apply
 loops cloud status
 loops-api status
 loops-serve version
-HASNA_LOOPS_DATABASE_URL=... loops-serve migrate --dry-run
+HASNA_LOOPS_MIGRATOR_DATABASE_URL=... loops-serve migrate --dry-run
+HASNA_LOOPS_DATABASE_URL=... HASNA_LOOPS_AUTH_DATABASE_URL=... loops-serve serve
 loops-runner status
 ```
 
@@ -86,27 +86,30 @@ leases, running runs, leased work items). Inline command env values are not
 exported as secrets; bundles with redacted env values require
 `--allow-redacted` and are marked non-importable.
 
-Self-hosted sync commands are preview-only until the control-plane API exposes
-id-preserving import endpoints:
+Self-hosted sync commands compare local definitions with the control-plane API.
+`push` can apply through the id-preserving `/v1/import` endpoint; `migrate` and
+`pull` remain preview/blocked for remote state that lacks a full export surface:
 
 ```bash
 loops self-hosted migrate --dry-run
 loops self-hosted push --dry-run
+loops self-hosted push --apply --manifest-file ./self-hosted-push.json
 loops self-hosted pull --dry-run
 ```
 
-The preview may inspect `LOOPS_API_URL`/`HASNA_LOOPS_API_URL`, but it refuses
-remote apply because normal loop CRUD would generate new ids. Use
-`loops self-hosted runner-register` to verify runner registration against an
-API, then use `loops-runner run-once` for the current bounded non-workflow
-claim/execute/finalize protocol. `loops-serve migrate` applies the Postgres
-schema and `api_keys` table for a self-hosted control-plane host; the standalone
-CLI migration previews still do not perform id-preserving remote apply.
-Runner registration is preview-only unless `--apply` is present.
+Self-hosted push is safe by default: workflows are archived and loops are
+paused with scheduling pointers cleared, including existing same-id rows that
+need re-neutralizing. `--replace` permits broader same-id data updates, but is
+not required for that safety normalization. `loops-runner run-once` uses the
+current bounded non-workflow
+claim/execute/finalize protocol. Durable runner registration is intentionally
+absent until the control plane persists and verifies machine records.
+`loops-serve migrate` applies the Postgres schema and `api_keys` table for a
+self-hosted control-plane host.
 
 ## Install
 
-**OpenLoops requires the [Bun](https://bun.sh) runtime (`bun >= 1.0`).** The
+**Loops requires the [Bun](https://bun.sh) runtime (`bun >= 1.0`).** The
 installed binaries are `loops`, `loops-daemon`, `loops-api`, `loops-serve`,
 `loops-runner`, and `loops-mcp`; each uses a `#!/usr/bin/env bun` shebang.
 
@@ -140,7 +143,7 @@ The CLI stores state in `~/.hasna/loops` by default. Set `LOOPS_DATA_DIR` to iso
 
 ## MCP Server
 
-OpenLoops ships a stdio MCP server for safe loop and workflow inspection from
+Loops ships a stdio MCP server for safe loop and workflow inspection from
 MCP-capable agents:
 
 ```bash
@@ -157,6 +160,7 @@ import { createLoopsMcpServer } from "@hasna/loops/mcp";
 Available read tools include `loops_list`, `loops_show`, `loops_runs`,
 `loops_doctor`, `loops_workflows_list`, `loops_workflow_read`, and
 `loops_workflow_validate`.
+`loops_list` and `loops_runs` accept label arrays with AND semantics.
 Resources are available at `loops://runtime` and `loops://tools`.
 Those tools use the same `Store`, public redaction helpers, and workflow parser
 as the CLI and SDK, so read output and validation behavior stay aligned across
@@ -166,12 +170,16 @@ Mutation tools are disabled by default. Start the server with
 `LOOPS_MCP_ALLOW_MUTATIONS=true` only for a trusted local MCP host that should be
 allowed to change loop state. The guarded mutation tools use canonical names:
 `loops_pause`, `loops_resume`, `loops_stop`, `loops_run_now`, `loops_archive`,
-`loops_unarchive`, `loops_create_command`, and `loops_create_workflow`.
+`loops_unarchive`, `loops_labels_update`, `loops_create_command`, and
+`loops_create_workflow`.
 Deprecated `loop_*` aliases are still registered where compatibility needs them,
 but callers should use the `loops_*` names. Mutation tools do not require or
 accept confirmation-string parameters; the server-side environment opt-in is the
 gate. MCP `loops_run_now` schedules the loop for immediate daemon pickup; inline
 execution remains CLI-only.
+When `showOutput` is enabled, `loops_runs` caps each stdout/stderr field at
+32,000 characters, caps output-bearing pages at 25 runs, and caps the aggregate
+MCP JSON response at 128,000 characters.
 
 Keep host-affecting or long-running operations on the CLI: daemon
 start/stop/install/logs, inline `run-now`, `tick`, loop deletion, workflow
@@ -205,6 +213,16 @@ Codewith auth profile, or workflow step dependency fails without creating a
 scheduled loop. Use `--json` with `--preflight` to capture stable machine-readable
 preflight evidence.
 
+For Codewith `--auth-profile` and workflow `authProfile`, local and remote
+preflight first request `codewith profile list --json` and match the requested
+name exactly against the root `data` or `profiles` inventory. That inventory is
+authoritative: `usable: false` rejects a profile, legacy entries without
+`usable` remain usable, and `currentProfile` does not add inventory membership.
+Loops falls back to the human-readable table, including active `*` rows,
+only when JSON mode is unsupported or its inventory is structurally
+unavailable. Embedded NUL bytes, missing profiles, and non-fallback
+profile-list failures fail closed.
+
 For shell command loops, preflight can only verify the shell plus configured
 accounts because the command string is interpreted later by the shell. Use
 `--no-shell` or workflow command `args` when you need executable-level
@@ -278,8 +296,34 @@ loops create agent supply-chain-watch \
   --prompt "Check for suspicious dependency or supply-chain changes. Report only concrete findings."
 ```
 
+Codewith `--auth-profile` is provider-native, not an OpenAccounts selector.
+Use `--account` only when you want OpenAccounts environment isolation.
+
+## Labels
+
+Command, agent, and workflow loops accept repeatable labels:
+
+```bash
+loops create command repo-status --every 1m --cmd "git status --short" \
+  --label BrowserPlan --label maintenance
+loops list --label browserplan --label maintenance
+loops runs --label browserplan
+```
+
+Labels are normalized to lowercase, deduplicated, limited to 32 per loop, and
+must match `[a-z0-9][a-z0-9._-]{0,63}` after normalization. Repeated filters use
+AND semantics. Run filtering uses the loop's current labels rather than a
+historical snapshot on each run.
+
+```bash
+loops labels add repo-status urgent
+loops labels remove repo-status maintenance
+loops labels set repo-status browserplan nightly
+loops labels clear repo-status
+```
+
 Run an OpenCode loop with an explicit provider/model. OpenCode reads
-`~/.config/opencode/config.json` when no model is supplied, so OpenLoops rejects
+`~/.config/opencode/config.json` when no model is supplied, so Loops rejects
 OpenCode agent targets without `--model` instead of inheriting a stale or
 machine-specific default.
 
@@ -292,7 +336,7 @@ loops create agent opencode-smoke \
   --prompt "Reply with exactly OK."
 ```
 
-Agent loops can also carry advisory per-session allowlist metadata:
+Agent loops can also carry an auditable advisory session contract:
 
 ```bash
 loops create agent repo-check \
@@ -301,13 +345,25 @@ loops create agent repo-check \
   --cwd /path/to/repo \
   --prompt "Check the repo and report concrete failures." \
   --allow-tool functions.exec_command \
-  --allow-command git,bun
+  --allow-command git,bun \
+  --safety-reason "isolated repository status inspection"
 ```
 
-These fields are stored on the loop target and exposed to the run environment
-as `LOOPS_AGENT_ALLOWED_TOOLS`, `LOOPS_AGENT_ALLOWED_COMMANDS`, and
-`LOOPS_AGENT_ALLOWLIST_ENFORCEMENT=metadata_only`. They are not enforced by
-OpenLoops yet; provider-native enforcement will be added separately.
+These fields are stored on the loop target, appended to provider stdin, and
+exposed as `LOOPS_AGENT_ALLOWED_TOOLS`, `LOOPS_AGENT_ALLOWED_COMMANDS`,
+`LOOPS_AGENT_ALLOWLIST_SAFETY_REASON`,
+`LOOPS_AGENT_ALLOWLIST_ENFORCEMENT=metadata_only`, and
+`LOOPS_AGENT_SESSION_CONTRACT`. A direct agent loop has no workflow run and
+does not create a workflow event. Agent steps inside workflow runs that carry
+an audit contract additionally persist one server-derived
+`agent_session_contract` event per step and run.
+Tool/command restrictions remain advisory metadata: current provider adapters
+do not claim native enforcement.
+
+Codewith/Codex `danger-full-access`, Cursor `sandbox=disabled`, and provider
+bypass modes (Claude, Cursor, AI Copilot, and OpenCode) require both a non-empty
+`--safety-reason` and explicit `--manual-break-glass`. A reason alone never
+substitutes for operator break-glass approval.
 
 For `codewith` and `aicopilot` account isolation, register matching OpenAccounts tools first if they are not built in on the machine:
 
@@ -354,7 +410,7 @@ from the workflow JSON file's directory:
 }
 ```
 
-OpenLoops stores the resolved prompt text for execution and records
+Loops stores the resolved prompt text for execution and records
 `promptSource` metadata with the absolute file path. Public CLI output from
 `show`, `list`, `workflows list`, `workflows show`, `workflows validate`,
 `workflows create`, and `templates render` redacts prompt bodies by default
@@ -443,8 +499,8 @@ for those. Set `"blockedExitCodes": []` on a gate-named step to opt out.
 
 ## Templates And Task Events
 
-OpenLoops is the runtime/scheduler/workflow engine for these flows — not the
-automation domain model. Todos-task routes are OpenLoops-native admission; they
+Loops is the runtime/scheduler/workflow engine for these flows — not the
+automation domain model. Todos-task routes are Loops-native admission; they
 do not replace the OpenAutomations product queue. See
 [Runtime Boundary](./RUNTIME_BOUNDARY.md) for ownership split and external
 compiler handoff paths (`@hasna/automations` claim-queue,
@@ -503,7 +559,7 @@ loops templates render routing-remediation \
   --var idempotencyKey=routing-health:repo:shard0
 ```
 
-Custom reusable workflow templates live under the OpenLoops app data directory:
+Custom reusable workflow templates live under the Loops app data directory:
 `~/.hasna/loops/templates` by default, or `$LOOPS_DATA_DIR/templates` when
 `LOOPS_DATA_DIR` is set. Store templates as declarative JSON files; listing,
 showing, and rendering templates never executes workflow steps or mutates the
@@ -609,6 +665,8 @@ arguments, and implicit Codewith/Codex full-access defaults. If a custom
 Codewith/Codex template uses `permissionMode: "bypass"`, it must also set
 `sandbox` to `workspace-write` or `read-only`. Use built-in templates with
 explicit break-glass handling for emergency workflows that need full access.
+Claude, Cursor, AI Copilot, and OpenCode bypass modes always require explicit
+break-glass plus a non-empty safety reason.
 
 Repo-mutating task/event routes should set `worktreeMode=required` so the
 workflow fails fast instead of falling back to the main checkout. When
@@ -623,7 +681,7 @@ inspection expose the exact checkout.
 Before a worker starts, worktree preparation verifies that any existing
 managed path is a real git worktree with the same top-level checkout and the
 same git common directory as the source repo. If the checkout is on a detached
-HEAD or unexpected branch, OpenLoops only reattaches it to the expected
+HEAD or unexpected branch, Loops only reattaches it to the expected
 generated branch when the worktree is clean. Dirty worktrees, symlinked paths,
 non-worktree paths, different common dirs, and unrecoverable branch switches
 fail closed with cleanup evidence (`worktreeMode=required`) instead of
@@ -744,13 +802,26 @@ cat task-created-event.json | loops routes create todos-task \
   --max-active 12
 ```
 
-The limits count active admitted/running OpenLoops work items once per workflow.
+The limits count active admitted/running Loops work items once per workflow.
 `--max-active-per-project` gates new work for the same project path,
 `--max-active-per-project-group` shares a pool across related projects such as
 `oss`, and `--max-active` is the global routed-workflow cap. Project matching
 uses the canonical git top-level path when available, so repo subdirectories
-share the same project cap. A throttled event records a deferred OpenLoops
+share the same project cap. A throttled event records a deferred Loops
 admission work item with JSON evidence instead of creating another worker loop.
+Route flags or an expanded named policy are authoritative ceilings. Positive
+integer task/event fields (`max_active`, `max_active_per_project`, and
+`max_active_per_project_group`, including camel-case aliases) may only lower an
+already configured ceiling for that admission attempt; metadata cannot create a
+cap, raise it, or override an explicit `--project-group`. The resolved route
+scope, project group, and limits are copied into workflow prompts and invocation
+evidence.
+
+Admission caps coordinate only through the active local SQLite store. The count
+and admission write are one transaction, so concurrent routers sharing the same
+`loops.db` serialize correctly. Separate `LOOPS_DATA_DIR` databases or machines
+do not share counts; these flags do not provide distributed coordination.
+
 Re-delivering the event later is safe because handlers dedupe by the work-item
 idempotency key before rendering worktree plans or checking route limits. In
 dry-run mode, throttle counts are not evaluated because opening the live loop
@@ -812,7 +883,7 @@ The `pilot` policy uses `sandbox=danger-full-access` and is treated as a paused
 manual break-glass lane; applying it requires the operator to pass
 `--manual-break-glass` explicitly.
 
-When a workflow run starts from an admitted work item, OpenLoops writes a
+When a workflow run starts from an admitted work item, Loops writes a
 manifest under:
 
 ```text
@@ -860,9 +931,9 @@ every candidate, so a drain can safely run every few minutes as a deterministic
 command loop: it fills only available capacity, writes compact JSON evidence
 when requested, and leaves excess ready tasks in todos for a later drain pass.
 Use `--dry-run` to preview candidates and rendered workflows without mutating
-OpenLoops state.
+Loops state.
 
-The route throttle flags count OpenLoops routed workflow work items, not the
+The route throttle flags count Loops routed workflow work items, not the
 live background-agent slots inside a provider. For Codewith drains, add
 `--provider-active-cap <n>` (or `--codewith-active-cap <n>`) so each candidate
 checks `codewith agent diagnostics --json` before workflow-loop creation and
@@ -902,7 +973,7 @@ in with the `auto:route` tag, `route_enabled=true`, or
 `automation.allowed=true` should be routed. Keep repo-mutating worker/verifier
 runs on a Codewith account pool with `--worktree-mode required`. Do not dispatch
 or paste task prompts into tmux panes. Use max-active throttles and
-`--max-dispatch` to bound OpenLoops agent fan-out, and use
+`--max-dispatch` to bound Loops agent fan-out, and use
 `--provider-active-cap` plus `--provider-admission-check` to bound live Codewith
 background-agent admission. Write compact evidence into a bounded reports
 directory so operators can audit each drain without unbounded stdout or loop
@@ -912,7 +983,7 @@ correctly do no work.
 
 Generated task/event route workflow specs are lifecycle-managed. After a
 generated one-shot route workflow run reaches `succeeded`, `failed`,
-`timed_out`, or `cancelled`, OpenLoops archives the generated workflow spec while
+`timed_out`, or `cancelled`, Loops archives the generated workflow spec while
 preserving workflow run, step, event, manifest, loop, invocation, and work-item
 history.
 
@@ -930,19 +1001,19 @@ cat event.json | loops routes create generic \
 ```
 
 This is the intended deterministic-to-agentic path: a producer creates a todos
-task, `@hasna/events` delivers `task.created`, OpenLoops records the invocation
-and admission item, OpenLoops creates a worker/verifier workflow when admitted,
+task, `@hasna/events` delivers `task.created`, Loops records the invocation
+and admission item, Loops creates a worker/verifier workflow when admitted,
 and the workflow updates todos with evidence. Use account pools so worker and
-verifier steps do not burn the same profile; OpenLoops picks deterministically
+verifier steps do not burn the same profile; Loops picks deterministically
 and uses a different verifier profile when the pool has at least two entries.
 Use `--dry-run` to inspect the rendered invocation, work item, workflow, and
 loop input without storing anything, including the worktree path and branch for
 git-backed tasks.
 
 Generated worker/verifier workflows fail closed when `sandbox=danger-full-access`
-is requested without `manualBreakGlass=true`. Use `workspace-write` for
-unattended task/event routes. Full access is an explicit manual emergency path,
-not a default automation mode.
+is requested without both `manualBreakGlass=true` and a non-empty
+`safetyReason`. Use `workspace-write` for unattended task/event routes. Full
+access is an explicit manual emergency path, not a default automation mode.
 
 ## Run Receipts
 
@@ -967,7 +1038,7 @@ mutation-gated `loops_receipt_write`. The SDK exposes `writeReceipt`,
 
 ## Transcript-Driven Loops
 
-OpenLoops can turn long-form media or meeting transcripts into recurring workflow work when paired with `iapp-transcriber`. The template at `docs/workflows/transcript-feedback-to-loops.json` transcribes an authorized media URL, asks an agent to extract recurring loop candidates, authors workflow specs, and validates generated workflows before scheduling. Copy it into the target repo, replace `/path/to/repo` with that repo's absolute path, and provide `TRANSCRIBER_SOURCE_URL` through the runner environment or a private, uncommitted workflow copy before storing or scheduling it. Do not commit private or signed media URLs.
+Loops can turn long-form media or meeting transcripts into recurring workflow work when paired with `iapp-transcriber`. The template at `docs/workflows/transcript-feedback-to-loops.json` transcribes an authorized media URL, asks an agent to extract recurring loop candidates, authors workflow specs, and validates generated workflows before scheduling. Copy it into the target repo, replace `/path/to/repo` with that repo's absolute path, and provide `TRANSCRIBER_SOURCE_URL` through the runner environment or a private, uncommitted workflow copy before storing or scheduling it. Do not commit private or signed media URLs.
 
 ```bash
 loops workflows validate /path/to/repo/.openloops/transcript-feedback-to-loops.json --preflight
@@ -1007,7 +1078,7 @@ loops expectations <loop-id-or-name> --json
 
 The JSON contains the expectation result, bounded error/stdout/stderr evidence,
 a stable failure fingerprint, route metadata, and recommended task fields.
-OpenLoops does not mutate Todos from `health`, `expectations`, or read-only
+Loops does not mutate Todos from `health`, `expectations`, or read-only
 `health scan`. To turn failed expectations or scan findings into deduped tasks,
 use an explicit mutating command:
 
@@ -1056,7 +1127,7 @@ Failure classifications are: `rate_limit`, `auth`, `model_not_found`,
 
 ## Hygiene
 
-OpenLoops includes deterministic hygiene checks for replacing local maintenance
+Loops includes deterministic hygiene checks for replacing local maintenance
 scripts with package commands:
 
 ```bash
@@ -1110,7 +1181,7 @@ Archived loops are hidden from the default `loops list`, excluded from daemon sc
 
 `loops run-now` reports the manual run source:
 
-- `source=ad_hoc`: the loop was not due yet, so OpenLoops created a one-off manual slot. This is a single immediate attempt and does not schedule retries or consume the future scheduled slot.
+- `source=ad_hoc`: the loop was not due yet, so Loops created a one-off manual slot. This is a single immediate attempt and does not schedule retries or consume the future scheduled slot.
 - `source=due_slot`: the persisted scheduled slot was already due, so the manual run claims that slot and advances or retries the loop using normal scheduler rules.
 - `source=retry_slot`: the loop was waiting on a failed slot retry, so the manual run claims that retry slot and advances the loop using normal retry rules.
 
@@ -1159,15 +1230,30 @@ On Linux this writes a user systemd service. On macOS it writes a LaunchAgent pl
 The adapters intentionally use provider command surfaces instead of pretending every agent has one SDK:
 
 - Claude uses `claude -p --output-format json` and safe-mode/local setting sources by default.
-- Codewith runs non-interactive `codewith --ask-for-approval never exec --json` sessions by default. exec starts a fresh session per invocation, avoiding the multi-megabyte rollout history that `codewith agent start` reloaded every turn (which drove `context_length_exceeded` silent no-ops), and it keeps network egress for gh/git — the `workspace-write` sandbox opts back into `sandbox_workspace_write.network_access`. Codewith exec is remote-capable like codex. OpenLoops rejects Codewith `extraArgs` that try to force `exec`, `--ephemeral`, `--json`, or other exec launch flags that the adapter already manages.
+- Codewith runs non-interactive `codewith --ask-for-approval never exec --json` sessions by default. exec starts a fresh session per invocation, avoiding the multi-megabyte rollout history that `codewith agent start` reloaded every turn (which drove `context_length_exceeded` silent no-ops), and it keeps network egress for gh/git — the `workspace-write` sandbox opts back into `sandbox_workspace_write.network_access`. Codewith exec is remote-capable like codex.
 - AI Copilot and OpenCode use `run --format json --pure`. OpenCode requires an explicit provider/model id because ambient OpenCode config is machine-specific.
-- Cursor is CLI-first for now via the standalone `agent -p` binary. OpenLoops no longer falls back to `cursor agent`; install the standalone Cursor Agent CLI so preflight and scheduled runs use the same executable.
+- Cursor is CLI-first for now via the standalone `agent -p` binary. Loops no longer falls back to `cursor agent`; install the standalone Cursor Agent CLI so preflight and scheduled runs use the same executable.
 - Codex uses `codex --ask-for-approval never exec --json --ephemeral --skip-git-repo-check`, with `--add-dir` for explicit extra writable directories where supported.
 - Agent prompts are sent through child stdin instead of argv where the provider supports stdin, including Codewith `exec` (which reads instructions from stdin when no positional prompt is given), so the prompt never lands on argv.
-- When `--account` or a step `account` is set, OpenLoops resolves `accounts env <profile> --tool <tool>` before spawning the target, strips inherited tool home/API-key variables, and applies the selected profile only to that process. Missing account profiles fail before the provider binary receives the prompt.
-- `--auth-profile` and step `authProfile` are provider-native auth selectors. They currently apply to Codewith and are passed to Codewith as `--auth-profile <name>` on the `exec` invocation; they do not call OpenAccounts.
+- When `--account` or a step `account` is set, Loops resolves `accounts env <profile> --tool <tool>` before spawning the target, strips inherited tool home/API-key variables, and applies the selected profile only to that process. Missing account profiles fail before the provider binary receives the prompt.
+- `--auth-profile` and step `authProfile` are provider-native Codewith selectors passed as `--auth-profile <name>` on the `exec` invocation; they do not call OpenAccounts. Local and remote preflight share the JSON-first, exact-name contract described above, use human-table parsing only as a compatibility fallback, and fail closed for unusable or missing profiles, NUL-containing names, and non-fallback list failures.
 - `--sandbox` maps to provider-native sandbox flags. Codewith/Codex accept `read-only`, `workspace-write`, or `danger-full-access`; Cursor accepts `enabled` or `disabled`.
+- `--allow-tool` and `--allow-command` declare advisory, metadata-only
+  restrictions and require `--safety-reason`. The exact contract is persisted
+  and emitted for audit, but Loops does not claim provider-side enforcement.
+  Relaxed sandboxes and native provider bypass modes also require explicit
+  `--manual-break-glass`.
 - `--permission-mode` maps `plan`, `auto`, and `bypass` where the provider supports it. Claude uses native permission modes, Cursor maps bypass to `--force`, and OpenCode/AICopilot map bypass to `--dangerously-skip-permissions`.
+- `extraArgs` is fail-closed: every provider currently rejects non-empty
+  passthrough arguments, including unknown options, positional subcommands,
+  split values, `--option=value`, and attached short-option forms. Configure
+  execution, output, permissions, sandboxing, model, cwd, and other supported
+  behavior through the modeled agent-target fields. A passthrough option must
+  be explicitly reviewed and added to the provider allowlist before use.
+  Legacy persisted targets are not silently accepted or rewritten: execution
+  fails validation until `extraArgs` is removed and replaced with modeled
+  fields. API and migration imports reject those targets instead of stripping
+  the arguments; update the source record and retry the import.
 - `--variant` is provider-specific reasoning/model effort. Claude maps it to `--effort`, Codewith/Codex map it to `model_reasoning_effort`, and OpenCode/AICopilot pass `--variant`.
 - Daemon and scheduled runs prepend common user executable directories such as `~/.local/bin` and `~/.bun/bin` before resolving provider CLIs.
 - Agent targets that set neither `timeoutMs` nor `idleTimeoutMs` get a default
@@ -1180,6 +1266,14 @@ The adapters intentionally use provider command surfaces instead of pretending e
   `timeoutMs`/`idleTimeoutMs` per target — `"timeoutMs": null` opts a target
   out of both the wall-clock default and the idle watchdog.
 
+For hosted workflow runs, the control plane derives any required agent session
+contract from the stored workflow step and persists it before execution. Reusing an
+older workflow run backfills a missing valid contract idempotently. Stored
+pre-contract workflows with unsafe/invalid agent options, mismatched stored
+contracts, duplicate contracts, command-step contracts, and client-fabricated
+contracts fail closed. Direct agent loops continue to expose their contract
+through prompt/environment metadata only.
+
 For production loops that can mutate repos, prefer the built-in
 `worktreeMode=auto`/`required` path and explicit prompts that name allowed write
 scope. Use `main` or `off` only for operations that intentionally need the

package/docs/workflows/transcript-feedback-to-loops.json

@@ -1,6 +1,6 @@
 {
   "name": "transcript-feedback-to-loops",
-  "description": "Turn an authorized media transcript into a reviewable backlog of recurring OpenLoops workflows.",
+  "description": "Turn an authorized media transcript into a reviewable backlog of recurring Loops workflows.",
   "version": 1,
   "steps": [
     {
@@ -49,7 +49,7 @@
         "provider": "codewith",
         "cwd": "/path/to/repo",
         "timeoutMs": null,
-        "prompt": "Read .openloops/transcripts/latest-transcript.json and create or update docs/loop-backlog.md. Extract only recurring work that is useful enough to schedule through OpenLoops. For each candidate include cadence, target provider, allowed write scope, expected artifacts, verification command, stop condition, and the specific transcript insight that justifies it. Prefer loops for code review/security, customer feedback triage, maintenance PRs, CI optimization, knowledge capture, and workflow hygiene."
+        "prompt": "Read .openloops/transcripts/latest-transcript.json and create or update docs/loop-backlog.md. Extract only recurring work that is useful enough to schedule through Loops. For each candidate include cadence, target provider, allowed write scope, expected artifacts, verification command, stop condition, and the specific transcript insight that justifies it. Prefer loops for code review/security, customer feedback triage, maintenance PRs, CI optimization, knowledge capture, and workflow hygiene."
       }
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/loops",
-  "version": "0.4.27",
+  "version": "0.4.29",
   "description": "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   "type": "module",
   "main": "dist/index.js",
@@ -79,11 +79,14 @@
     "build:bin": "bun build src/cli/index.ts --compile --outfile dist/loops",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
+    "check:branding": "bun test scripts/check-branding.test.mjs && bun run scripts/check-branding.mjs",
     "test:boundary": "bun run scripts/no-private-cloud-boundary.mjs",
+    "check:contracts": "bun run scripts/check-storage-kit.mjs && bun run scripts/check-contract-conformance.mjs",
+    "check:supply-chain": "bun audit && bun audit --production && bun run check:contracts && bun run check:branding && bun pm pack --dry-run --ignore-scripts && bun run test:boundary && bun run scripts/check-packed-boundary.mjs",
     "prepare": "test -d dist || bun run build",
     "dev:cli": "bun run src/cli/index.ts",
     "dev:daemon": "bun run src/daemon/index.ts",
-    "prepublishOnly": "bun run build && bun run typecheck && bun test && bun run test:boundary"
+    "prepublishOnly": "bun run build && bun run typecheck && bun test && bun run test:boundary && bun run check:supply-chain"
   },
   "keywords": [
     "loops",
@@ -110,6 +113,8 @@
     "bun": ">=1.0.0"
   },
   "dependencies": {
+    "@aws-sdk/client-secrets-manager": "^3.1083.0",
+    "@hasna/contracts": "0.5.2",
     "@hasna/events": "^0.1.9",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openrouter/ai-sdk-provider": "2.9.1",
@@ -119,8 +124,7 @@
     "zod": "4.4.3"
   },
   "optionalDependencies": {
-    "@hasna/machines": "0.0.49",
-    "@hasna/contracts": "^0.4.2"
+    "@hasna/machines": "0.0.49"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/dist/lib/storage/pg-runner-claim.d.ts

@@ -1,40 +0,0 @@
-import type { PoolQueryClient } from "../../generated/storage-kit/query.js";
-export interface ClaimedRunRow extends Record<string, unknown> {
-    id: string;
-    loop_id: string;
-    loop_name: string;
-    scheduled_for: string | Date;
-    attempt: number;
-    status: string;
-    claimed_by: string | null;
-    claim_token: string | null;
-    lease_expires_at: string | Date | null;
-}
-export interface ClaimNextRunOptions {
-    runnerId: string;
-    leaseMs: number;
-    claimToken: string;
-    /** Statuses a run may be in to be claimable. Defaults to queued + lease-expired running. */
-    now?: Date;
-}
-/**
- * Atomically claim the next claimable run for `runnerId`.
- *
- * A run is claimable when it is `queued`, or `running` with an expired lease
- * (crash recovery). Returns the claimed row, or `null` when nothing was
- * available. Two concurrent callers are guaranteed to receive distinct rows
- * (or one receives `null`) thanks to `FOR UPDATE SKIP LOCKED`.
- */
-export declare function claimNextRun(client: PoolQueryClient, options: ClaimNextRunOptions): Promise<ClaimedRunRow | null>;
-/**
- * Heartbeat a claimed run's lease. Returns true when the lease was extended
- * (the caller still owns the run), false when ownership was lost (claim token
- * mismatch, run finalized, or lease already stolen).
- */
-export declare function heartbeatRunLease(client: PoolQueryClient, input: {
-    runId: string;
-    runnerId: string;
-    claimToken: string;
-    leaseMs: number;
-    now?: Date;
-}): Promise<boolean>;