Skip to content

Horae JSON Schemas

Machine-readable contracts for the documents Horae reads and writes (PLAN.md §3). All schemas use JSON Schema draft 2020-12. $id values below are relative to https://raw.githubusercontent.com/horae-dev/horae/main/schemas/.

Schema File $id (relative) Validates
Pipeline pipeline/v1.json pipeline/v1.json pipelines/*.yaml (§3.2)
Plugin manifest plugin-manifest/v1.json plugin-manifest/v1.json plugin.yaml (§3.3)
Intent (any) intent/v1.json intent/v1.json one intent, oneOf tagged by a type const
One intent intents/<type>/v1.json intents/<type>/v1.json note.create, note.append_section, note.replace_owned_block, task.create, task.update_status, notify.push, http.post
Lockfile lockfile/v1.json lockfile/v1.json horae.lock (§4)
Marketplace index marketplace/v1.json marketplace/v1.json marketplace.json of a marketplace repository (§4)
Run record run-record/v1.json run-record/v1.json one run (§3.1, §2.1.6)
Instance configuration instance/v1.json instance/v1.json horae.yaml (§3.1, §3.4, §7)
Skill skill/v1.json skill/v1.json skills/<namespace>/<skill>/skill.yaml of a plugin (§2.1, §3.4)
Eval case eval-case/v1.json eval-case/v1.json skills/<namespace>/<skill>/evals/<case>.yaml (§5)
Eval recorded response eval-recorded/v1.json eval-recorded/v1.json evals/recorded/<backend>/<case>.json (§5)

Source of truth

The pydantic models in src/horae/contracts/ are the source of truth (public types such as Hostname, NotePath or SecretName live in horae.contracts.types and are re-exported from horae.contracts). The files here are generated; do not edit them by hand:

uv run python -m horae.contracts.export          # regenerate schemas/ (from any directory)
uv run python -m horae.contracts.export --check  # exit 1 if schemas/ is stale

tests/test_contracts.py fails if the committed files differ from what the models generate (byte for byte, LF line endings: see .gitattributes), if a *.json file outside examples/ is not a generated schema, and checks that the schemas and the models agree on every example.

The output bytes depend on the pydantic version locked in uv.lock. A Renovate bump of pydantic may change them; the drift test then fails in CI and the fix is to regenerate.

Versioning

  • Each schema has a versioned $id, https://raw.githubusercontent.com/horae-dev/horae/main/schemas/<name>/v<N>.json, and lives at <name>/v<N>.json, so the $id resolves to the file once it is on main.
  • A breaking change adds v<N+1>.json next to the old file; compatible additions stay in v<N>. Most rules are deliberately tight: loosening one later is a compatible change.
  • Files that Horae writes itself carry schema_version (horae.lock, run records). Files that people write (pipelines, plugin.yaml) do not, so the PLAN.md examples validate unchanged. horae.yaml accepts an optional schema_version: 1 (the default), so that a future v2 file can be told apart (decision 26).

Rules worth knowing

  • Unknown keys are rejected everywhere (additionalProperties: false), except the free-form parameters of a plugin call and recorded data (source outputs, LLM requests and responses).
  • No type coercion. A string is never a number, a number never a string, and true is never an integer (not even schema_version: 1). Dates are ISO 8601 strings: YYYY-MM-DD, or RFC 3339 date-times with seconds and an explicit offset (2026-10-27T05:30:00Z, upper-case T/Z). Naive date-times are rejected. The models accept the same strings from JSON (validate_json) and from already-parsed data (validate_python, e.g. json.loads, MCP or SQLite rows), and also date / datetime objects from Python code. In YAML, quote dates: an unquoted 2026-10-27 is a YAML timestamp, not a string, and the JSON Schema rejects it.
  • A pipeline step is an object with exactly one key: collect, transform, llm, act or notify. Each lists plugin calls, either bare (tasks.normalize) or with parameters (calendar.events: { days: 2 }), or in the explicit form with a per-call timeout ({ tool: calendar.events, params: { days: 2 }, timeout_s: 90 }, decision 35). A pipeline has at most one llm step (contains + maxContains: 1).
  • The llm step has no tools key, and requires a budget with both usd and tokens_out.
  • Plugin permissions (network, secrets, paths, intents) default to empty: no access.
  • Sinks apply intents (PLAN.md §3.1, §3.3); permissions.intents lists the intents a plugin may propose or, for a sink, apply.
  • Sizes are bounded: lists and maps at most 256 entries; note content at most 1 MiB (1 048 576 characters, i.e. code points); titles 500, headings 200, notification bodies and messages 4096 characters; captured stderr 64 KiB; URLs 2048; paths 1024 (255 per segment).

Strings that reach the outside world

Type Rule
Host (permissions.network) lowercase DNS name; the last label starts with a letter, so no IP literal (dotted, decimal, hex or IPv6); localhost and *.localhost rejected; single-label names (coach, a Docker/Coolify service) allowed; no port, scheme or wildcard
http.post.url, runtime.url, homepage https:// only; host as above; optional port 1–65535; no user info, fragment, backslash, whitespace or control characters
notify.push.link https:// or obsidian://, then [^\x00-\x20\x7f]+
task.create.link https://, a non-empty authority without @ (no user info), then optionally /, ? or # and the rest; no whitespace, control character or backslash anywhere; at most 2048 characters (decision 52)
Lockfile repo https://<host>/<segments> with segments of A-Z a-z 0-9 . _ - (.git optional), no ./.. segment, no port, user info, query or fragment, at most 512 characters
Note path (intents) relative POSIX path: no leading /, no \, no control characters, no empty segment, no segment starting with . (so no ., .., .obsidian/ or hidden files)
permissions.paths normalised absolute POSIX path: no ./../empty segment, no trailing /, not /, no \ or control characters
Secret name ^[A-Z][A-Z0-9_]*$ (not starting with _); HORAE_* reserved; LD_*, DYLD_*, PYTHON*, PATH, HOME rejected
models.<alias>.base_url (horae.yaml) https:// to a host name (localhost included), an IPv4 literal or a bracketed IPv6 literal; http:// only to localhost, 127.0.0.0/8, 10/8, 172.16/12, 192.168/16, [::1], [fc00::/7] or a single-label name (ollama); optional port; no user info, fragment, backslash, whitespace or control characters (decision 24)
Task title, headings, descriptions one line: ^[^\x00-\x1f\x7f]+$
Block id ^[a-z0-9][a-z0-9-]{0,63}$
Fingerprint (task.create.fingerprint, task.update_status.task) ^[A-Za-z0-9._:-]{1,128}$
Run id ^[A-Za-z0-9._-]{1,128}$ (safe as a file name)

Contracts constrain shape, not meaning. The runtime still has to:

  • check http.post and mcp-http hosts against permissions.network using the same parsed host (horae.contracts.url_host), never a second URL parser (horae.intents does this for http.post, #20), and resolve names through the egress proxy so that a declared name cannot reach private or link-local addresses;
  • never follow redirects in a sink that makes a request (http.post, mcp-http), or re-check the host of every hop with url_host against the same permissions.network: a declared host must not be able to bounce a request to an undeclared one;
  • keep the run-wide number of proposed intents within RunRecord.intents's bound, horae.contracts.MAX_RUN_INTENTS (256): horae.intents.MAX_INTENTS bounds one step only;
  • escape text before it reaches a format that interprets it: sinks writing Obsidian Tasks must escape the emoji signifiers (📅, ⏰, ✅, 🔁…) in titles, not only Markdown;
  • install plugins with git clone -- <repo> and protocol.allow restricted to https, even though the lockfile already only accepts https:// URLs.

Rules only the pydantic models check

JSON Schema cannot express these; the models enforce them and the tests pin the difference:

  • run-record: changes[].intent is an index into intents; finished_at is not before started_at (run and step records); intents[].applied_by, applied_by_step and applied_by_call are all set or all absent (the JSON Schema's dependentRequired checks presence, the model also rejects an explicit null next to a value); pipeline_definition is a valid pipeline named pipeline, at most 64 KiB as compact JSON (decision 33).
  • skill: two input_view paths may not overlap (one a prefix of the other) or disagree on whether a value is an object or an array (decision 39). task_fingerprint.ids is an input_view path (or lies below one), and task_fingerprint needs task.create in intents (decision 67).
  • plugin-manifest: the host of an mcp-http runtime.url is listed in permissions.network; no tool in provides is a sink operation of the plugin's own sink or notifier namespaces (<ns>.read, <ns>.apply, <ns>.restore, <ns>.parent_exists, <ns>.identity, decision 36). Each key of provides.personal_fields is one of sources or transforms, and a tool's paths may not overlap or disagree on a value's shape, a scan-only free_text: path included (decision 68 K; the same rule for the lock's personal_fields).
  • Hosts (permissions.network, every https URL): a label starting with xn-- must be a valid IDNA A-label. It must round-trip through Python's idna codec (IDNA2003, so no runtime dependency) and decode to letters, marks, digits and - only. The second rule rejects what IDNA2003 allows but IDNA2008 does not, such as emoji (xn--ls8h) and symbols (xn--g6h); it approximates IDNA2008 rather than implementing RFC 5892 exactly.
  • instance (horae.yaml): a bracketed IPv6 literal in base_url must parse as an IPv6 address (the schema only checks its characters and, for http, the fc/fd prefix).
  • task.create link (decision 52 A): the host may not be an IP address (its last label is a number, as WHATWG reads it, after NFKC), and no character may be a supplementary-plane format character (tags U+E0001, U+E0020-U+E007F, ...) or a lone surrogate. The pattern already refuses the Basic Multilingual Plane controls, format characters and separators, bracketed IPv6 and % in the authority.

Known validator differences

  • Integral floats. JSON Schema integer (and const: 1) accepts 2000.0; the models reject it.
  • Trailing newline with Python's jsonschema. It evaluates pattern with re.search, where $ also matches before a final \n, so "Buy milk\n" passes ^[^\x00-\x1f\x7f]+$. ECMA-262 validators and the models reject it. The patterns use no look-around and no \s/\d/\w shorthands, so they mean the same in ECMA-262 and Rust regex (pydantic); the test suite validates with ECMA $ semantics.
  • Formats. format (date, date-time) is an annotation unless the validator asserts formats (FormatChecker in Python's jsonschema, with jsonschema[format-nongpl]). Every date and date-time also has a pattern, so a naive date-time fails either way; an impossible date such as 2026-02-30 fails only with format assertion (and always in the models).
  • Explicit null. Optional fields accept null as "absent", in both.
  • Non-finite numbers. The models reject NaN and Infinity; standard JSON cannot contain them.

Lockfile canonical form

Serializing a Lockfile sorts plugins by name and every permission list, so a diff of two lockfiles shows only real changes. Reading accepts any order. The file's text is block-style YAML with sorted keys and a trailing newline, after the file's own leading comment lines (horae.marketplace.lock, decision 70): the same lock is always the same bytes.

Examples

examples/<name>/valid/ and examples/<name>/invalid/ hold passing and failing examples for every schema. Each valid example passes the JSON Schema, validate_python and validate_json; each invalid one fails all three. examples/pipeline/valid/daily-brief.yaml and examples/plugin-manifest/valid/github.yaml are the PLAN.md §3.2 and §3.3 examples, verbatim (a test checks this). All other examples are synthetic.

Decisions

Confirmed by the maintainer on 2026-10-28. PLAN.md left these open; each takes the most conservative option, so loosening one later is a compatible change.

  1. Intent names. §2.1 says create_task, append_note, notify; §3.3 lists the closed set note.create, note.append_section, note.replace_owned_block, task.create, task.update_status, notify.push, http.post. v1 uses the §3.3 names.
  2. Intent fields are the minimum each sink needs: task.create has title, a required fingerprint, optional due and time (HH:MM, the ⏰ reminder; time requires due); task.update_status uses the fingerprint as task id and the statuses todo, done, cancelled, snoozed (until, a date or date-time, is required for snoozed and only allowed there); notify.push has body, optional title and link; http.post has url and a JSON body (no headers). The core (horae.intents) accepts only plain JSON data in body (string keys, finite numbers, nesting at most 64 deep) and caps its compact serialization (json.dumps(body, allow_nan=False, separators=(",", ":"))) at 1 MiB of UTF-8 (horae.contracts.types.MAX_BODY).
  3. Fingerprint alphabet A-Z a-z 0-9 . _ : -, 1–128 characters (fits source:id keys).
  4. Note paths reject every segment starting with ., not only .obsidian/: hidden files and folders are never written by intents.
  5. Text limits: title 500, heading 200, notification body 4096, note content 1 MiB.
  6. URLs are https only for http.post, mcp-http runtimes (even to internal Docker service names), homepage and lockfile repo. Host names must be lowercase and cannot be IP literals or localhost.
  7. Notification links are https:// or obsidian:// only.
  8. Secret names reject the listed loader variables and reserve HORAE_. Other variables that change process behaviour (NODE_OPTIONS, BASH_ENV, *_PROXY, SSL_CERT_FILE…) are left to the runtime's environment builder, which must own the full deny list.
  9. permissions.paths is { read: [...], write: [...] } of absolute paths. What they are relative to (the container's filesystem, the instance root, a vault mount) is open for #20/#51.
  10. permissions.network takes bare host names (single-label names allowed): no port, scheme or wildcard. Any port on a declared host is allowed: http.post to https://hooks.example.org:8443/ passes when hooks.example.org is declared. Ports are not part of the permission; restricting them would need a new, explicit host:port form.
  11. Namespace prefix. Tools are <namespace>.<tool> and skills <namespace>/<skill>. The namespace is not required to equal the plugin name, because PLAN.md uses prefixes that are not plugin names (coach.brief from plugin-mcp-brief). How a namespace resolves to a plugin is for the engine to define.
  12. "Implements" vs "proposes". permissions.intents covers both the intents a plugin may propose and those a sink may apply. Whether these should be two lists is open.
  13. Trigger. Optional: a pipeline without one runs only from an external scheduler (horae run). cron is five fields separated by single spaces, of 0-9 A-Z a-z * / , - (no @daily macros), with an optional IANA timezone (instance default otherwise).
  14. One LLM step per pipeline is enforced (PLAN.md says "by default"); a later opt-out would be an explicit key.
  15. on_unchanged_input accepts only skip: §2.2 forbids an LLM call on unchanged input.
  16. LLM timeout. timeout_s is optional; the core supplies a default.
  17. Transforms in provides. §3.1 lists sources, sinks, notifiers, skills and pipeline packs, but §3.2 uses plugin transforms (tasks.normalize), so provides.transforms was added.
  18. Remote runtime. protocol: mcp-http with an https url whose host is in permissions.network. runtime is optional so pipeline packs and skill-only plugins need none.
  19. Manifest metadata. Optional description (one line), license (SPDX expression, syntax only) and homepage (https). No author or keywords.
  20. horae.lock. §4 lists its content (name, version, SHA, approved permissions) but not its syntax; the schema validates the parsed document (the example is YAML) and adds the git repo (https only). Permission lists are written sorted.
  21. Run record. v1 requires pipeline_digest (SHA-256, hex, of the canonical pipeline definition; the canonical form is fixed by the engine, see horae.engine.canonical) and context (now, IANA timezone, rendered template vars). Optional: lock_digest, config_digest, input_hash, per-step error / timings / capped stderr, LLM attempt and schema_valid, and violations (egress_blocked, guard, undeclared_secret, undeclared_path; intent_skipped since decision 60). Statuses: run ok, noop, degraded, failed, undone; step ok, skipped, degraded, failed. A dry run has no changes. Untrusted-content tagging is not part of v1. intents[].proposed_by is the proposing tool (<namespace>.<tool>) or, for intents of the llm step, the skill (<namespace>/<skill>) (added with #17, a compatible loosening).
  22. $id host. raw.githubusercontent.com/horae-dev/horae/main/schemas/…, which this project controls and which serves the files once merged. A custom domain can come later as v<N+1>.

Provisional decisions (#16, pending maintainer review)

Taken in #16 so that the loader could be built; each is the conservative option and can be loosened later without breaking a valid file.

  1. horae.yaml (instance v1) is kept minimal; every key is optional. schema_version (1, decision 26), timezone (IANA, default UTC), state_dir (default state, relative to the instance directory), models (alias → backend from the run-record list, model, base_url (decision 24) and secret, the name of the secret holding the API key or token), plugin_defaults and plugins (decision 26), secrets (dir, default /run/secrets, and refs: secret name → {env: VAR} or {file: name}, a single file name inside dir; decision 25) and scheduler.mode (builtin, the default, or external). It never holds a secret value. Rules the loader (not the schema) checks: time zones exist (zoneinfo.available_timezones(), with the tzdata package as a runtime dependency so that the answer does not depend on the host), llm.model aliases are defined, configured plugins are in horae.lock (skipped when horae.lock itself is invalid), a pipeline's name equals its file name.
  2. Backends and endpoints (A). ollama and openai-compatible require base_url; anthropic requires secret; claude-cli needs neither. base_url is a BackendUrl: https is always allowed (any host name, localhost included, or an IP literal); plain http only to loopback (localhost, 127.0.0.0/8, [::1]), private addresses (RFC 1918 10/8, 172.16/12, 192.168/16; IPv6 ULA fc00::/7) and single-label names (a Compose or Coolify service such as http://ollama:11434), where TLS is usually not available and the traffic does not leave the host or the private network. No user info (credentials belong in a secret), no fragment. The JSON Schema expresses the same rule (one pattern and if/then for the required keys).
  3. Secrets come from files unless a reference says otherwise (B). A secret with no entry in secrets.refs is read from <secrets.dir>/<NAME> only. Environment variables are read only through an explicit {env: VAR} reference. This keeps a plugin that declares a secret name from pulling an arbitrary variable of the host environment, and steers deployments towards secret files, which a plugin cannot read through /proc/<horae-pid>/environ (see the #24 design note, "Not enforced until M5"). An explicit env reference to a variable that is unset or empty is an error. One trailing newline (\n or \r\n) is stripped from every value; a value that still contains \r, \n or NUL, or a file that is not a regular UTF-8 file of at most 64 KiB, is an error. Files are opened once, non-blocking (a FIFO cannot hang horae doctor), and checked with fstat on that descriptor.
  4. schema_version and plugin timeouts (C). horae.yaml takes an optional schema_version: 1 (true and 1.0 are rejected, as everywhere). plugin_defaults (startup_timeout_s, default 10, and call_timeout_s, default 30) applies to every plugin; plugins.<name> may override either. Every timeout is 1 to 600 seconds. Instance.plugin_timeouts(name) returns the effective pair for the #24 plugin host.
  5. horae doctor (D). Exit codes (kept by decision 37): 0 no problem, 1 problems found, 2 usage error, 70 internal error (EX_SOFTWARE; the doctor then prints only the exception type, never its message, traceback or locals, which may hold a resolved secret). --json prints {"schema_version": 1, "ok", "instance", "problems": [{file, line, column, severity, message}]}; severity is error or, since decision 38, warning (reported, not failing).
  6. The environment deny list is the #24 host's (E). SecretName rejects only the loader variables of decision 8. The full deny list of the #24 design note (NODE_OPTIONS, BASH_ENV, *_PROXY, SSL_CERT_*, GIT_*, …) is enforced by the plugin host when it builds a child environment, not by the schema: it is about what a variable does in a child process, not about whether a name is a valid secret name. The #24 SecretResolver protocol should return a Secret (not str), so values stay redacted until the host puts them in the child environment, and the host can redact every value from SecretResolver.resolved().
  7. Problem positions (F). A problem points at the value when the value is wrong (scheduler.mode: cron points at cron), and at the key when a key is unknown, invalid or missing (a missing key points at its parent's key). A mapping key that is not a valid name is shown as <key at line N>, never echoed, since it may be a secret pasted in the wrong place. Messages never show a regular expression, and a union (a pipeline step, a secret reference) gives a single problem, e.g. unknown step kind 'colect' (expected one of: collect, transform, llm, act, notify).
  8. Intent routing in the run record (#17, maintainer decision D1). Following ADR 0002, sources, transforms and the LLM step propose intents; act / notify entries are never called during a run, they name the sink or notifier that applies the intents later (#21/#22). Each recorded intent says which entry: intents[].applied_by (the entry's <namespace>.<tool>), applied_by_step (its step) and applied_by_call (its index in the step). The three are optional in v1 (a compatible addition) but go together, and the engine sets them on every intent it records; an applier must refuse an intent without them. llm[].intents records the raw intents returned with the response, before the core fills a target from the entry's parameters, for replays and for reuse on unchanged input (D2). input_hash is the LLM step's cache key (horae.engine), set only when the LLM output was accepted or reused. The routing and binding rules are the engine's, documented in horae.engine.executor; in short:

    • every act entry has a required mode (create, append-section, replace-owned, tasks, post); the note modes bind path and post binds url, compared as exact strings (no case, Unicode or URL normalisation);
    • a notify.push link is routed only to a notify entry whose trusted link_prefix it falls under; without link_prefix a proposed link is never routed. A prefix is an https:// or obsidian:// link with a host, no user info, query or fragment, and a clean path that ends with / (e.g. obsidian://vault/Main/), else params_invalid. Both are parsed (urlsplit), not compared as strings: same scheme, the same authority (since decision 52 B, an https host compares case-insensitively, without one trailing dot, with :443 equal to no port; an obsidian:// netloc exactly), and a link path under the prefix path (case-sensitive) whose rest has no empty, . or .. segment, backslash, or %2e / %2f / %5c / %25 (so no /notes/../admin, no host.evil or host@evil). The link may add its own query and fragment;
    • a task.update_status is routed only if its task fingerprint appears as a string value in the run's collected input; task.create binds no target but its optional link, which (decision 52) is routed only to a mode: tasks entry whose trusted link_prefix it falls under, by the notify.push rule above;
    • two entries that may apply the same type to the same target make every such intent intent_ambiguous, by design: untrusted data never chooses between trusted entries;
    • the proposer's permissions are checked before routing (intent_rejected wins);
    • the run record model checks that a route names a real, later entry of the right kind that lists the intent.

    Routing binds where an intent goes, not what it says: note content, task titles, notification titles and bodies, and http.post bodies stay untrusted text, which appliers must treat as data. Reusing an unchanged input re-proposes identical intents, notify.push included, so appliers (#21/#22) must deduplicate notifications (e.g. by input_hash and intent); reused intents that no longer route are a cache miss and the LLM is called.

Provisional decisions (#19, pending maintainer review)

  1. Run lifecycle (#19). horae.yaml takes an optional runs.timeout_s (default 900, 1 to 86400 seconds), the run timeout. Per-call limits stay where they are: plugin_defaults.call_timeout_s for tool calls (the #24 host) and the pipeline's llm.timeout_s for the LLM step (the engine). Other rules of the runner (horae.runner), which are not part of a schema (A to G are provisional maintainer decisions):
    • run ids are <UTC start, %Y%m%dT%H%M%S%fZ>-<pipeline>-<6 hex>, so they sort by start time and match RunId; a collision (RunExists) is retried once with a fresh id;
    • (B) liveness is an OS advisory lock. A run holds flock(LOCK_EX | LOCK_NB) on <state_dir>/locks/<pipeline>.lock (directory 0700, file 0600, opened O_CLOEXEC | O_NOFOLLOW) for its whole life; the kernel releases it however the process ends. A busy lock is retried for 0.2 s, then the run is refused with PipelineLocked, naming the running run read from the store (its start, pid and host) when there is one; nothing is written. With the lock held, any running row of that pipeline is dead by definition and is abandoned (failed, no record, journal kept) as a compare-and-set on its id and last heartbeat (Store.abandon_run(heartbeat_before=...)), then begin_run. The store's unique index on running runs stays as a second guard (PipelineBusy is reported as PipelineLocked). Heartbeats (every 10 s) stay for observability but no longer decide liveness: there is no stale delay and no pid or host check. Local filesystems only (no NFS or SMB, as ADR 0006 already requires for the database). POSIX only: Linux (the container target) and macOS (development); without fcntl (Windows) taking a lock raises LocksUnsupported (Windows is unsupported, no msvcrt fallback);
    • (G) recovery covers only the pipeline being started; other pipelines are recovered when they next start. horae runs shows a running row whose lock is free as running (stale?) ("stale": true in --json), checked without waiting and read-only (a missing lock file is a free lock; one that cannot be opened is not flagged);
    • (A) dry runs take the lock too;
    • (C) the heartbeat interval (10 s), the stop grace period (5 s) and the lock retry (0.2 s) are constants, not horae.yaml settings. A heartbeat waits at most 100 ms for the write lock (HEARTBEAT_BUSY_TIMEOUT_MS, on a second connection), then skips the beat; heartbeat failures of any kind are logged once per run (exception type only) and never stop the run;
    • (D) timeouts. Past runs.timeout_s the run is cancelled and given 5 s to stop. If it stops, its partial record is saved failed (the interrupted step failed with error kind timeout, later steps skipped) and RunTimedOut(record) is raised. If it finished anyway after the deadline (a step ignored the cancellation), it is saved failed with the error the run timed out after N s (it finished after the deadline), never ok. If it still has not stopped, the run is abandoned with the error timeout: the run timed out after N s and its step did not stop within 5 s and RunTimedOut is raised with record = None;
    • (F) cancellation. When the caller cancels Runner.run (Ctrl-C, or async with asyncio.timeout(...)), the partial record is saved (kind cancelled; a run cancelled before its first step gets a minimal record, every step skipped, error the run was cancelled before it started), passed to the on_record callback, and a plain asyncio.CancelledError is re-raised, so asyncio.timeout turns it into TimeoutError. RunTimedOut is a RunnerError, not a CancelledError. The same 5 s grace applies (then the run is abandoned with cancelled: ...). A cancellation that arrives while the heartbeat stops is not swallowed;
    • a crash (any other exception) abandons the run with run crashed (<ExceptionType>), never the exception's message; if that abandon fails, it is logged (types only) and the next run of the pipeline recovers the row. A row abandoned by someone else while the run runs is noticed by the heartbeat, the next step write or the final save: the run stops with RunLost;
    • clocks: timestamps and run ids use the wall clock, the run timeout the event loop's monotonic clock. A wall-clock step only shifts recorded times (and may reorder run ids started across it); since liveness is the lock's, it cannot make a live run look dead;
    • the template time zone is the pipeline trigger's timezone when set, else horae.yaml timezone;
    • (E) the store is <state_dir>/horae.db. horae runs lists runs (--pipeline, --status, --limit, --json) with the exit codes of decision 27. It opens the store with Store.open(path, read_only=True): it never creates the store or any file (no -wal / -shm when no writer is active), never switches the journal mode and never migrates; a schema older than this Horae exits 1 (SchemaTooOldError: "run horae run once to migrate it"), a newer one too (SchemaTooNewError), and so do permission and other OS errors. The table has an ERROR column: the run's error on one line, control and bidi characters collapsed, at most 60 characters. --json prints {"schema_version": 1, "instance", "runs": [{id, pipeline, status, stale, dry_run, abandoned, started_at, finished_at, duration_s, cost: {usd, tokens_in, tokens_out}, error}]}, where instance is the resolved absolute path and error is the run's full error, which carries step messages as capped by the engine (4096 characters).

Provisional decisions (#21, pending maintainer review)

  1. Dry-run diff (#21). horae.apply plans what applying a stored run would change and horae diff <run-id> shows it; nothing is applied (that is the journal's, #22). The rules (D1 to D8 are provisional maintainer decisions):
    • (D1) the core owns note conventions. The Sink port (horae.apply.sink) has two operations: read(call) -> bytes | None, a read-only fetch of a note.* intent's current target (None: no such note), and apply(call, *, expected_before_sha256) -> Applied, a compare-and-swap for #22 (the SHA-256 of the bytes the change was planned against, None meaning "must not exist"; a mismatch changes nothing and raises SinkError("target_changed")). There is no sink-side preview: the core computes each note change from read() and horae.apply.notes, and builds task, notification and HTTP previews from the intent alone, without calling the sink, so a plugin cannot show one change and make another. What a sink returns is type-checked at runtime (bytes or None, else preview_invalid). Over MCP note bytes travel base64-encoded, at most MAX_MCP_NOTE_BYTES (about 5.95 MiB, decision 36; note_too_large). The sink receives a deep copy of the intent and its entry's parameters;
    • (D2) Horae never creates content in a note it does not own. A note is owned when its file name ends in .assistant.md, decided on the path the sink resolved without following symlinks. note.create (note_exists if present) and note.append_section (note_missing if absent) need an owned note. note.replace_owned_block creates a missing note or block only in an owned note; on any other note it only replaces a block that already exists (not_owned otherwise);
    • markers and line breaks. A block is the lines from <!-- horae:begin <block> --> to <!-- horae:end <block> -->, both included; a marker may end the note without a final newline. One case-insensitive recogniser (horae:(begin|end), optionally with a block name) serves both directions: in a note, every line naming the block counts and must be exactly one canonical begin line followed by one canonical end line (surrounding spaces and a final \r aside), else block_ambiguous; in untrusted text (content, heading) it must not appear anywhere (content_has_marker). Untrusted text may break lines only with \n or \r\n: a lone \r, U+0085, U+2028 or U+2029 is refused (content_line_break). Inserted lines use the note's line ending (that of its first line, \n for a new or one-line note); the rest of the note is kept byte for byte;
    • targets (for #22 too). A sink resolves a note path without following symlinks on any component (symlink), refuses a file with more than one hard link (hard_link) and anything but a regular file (not_a_file), and decides ownership on that path. The built-in LocalSink walks the path with dir_fd and O_NOFOLLOW, opens the note O_RDONLY | O_NOFOLLOW | O_NONBLOCK | O_CLOEXEC, checks it with fstat and reads from the descriptor; a name that is too long or a parent that is not a directory is not_a_file, a permission or other OS error unreadable, a path holding : is refused (path_invalid). POSIX only: Windows is unsupported. apply (#22) must use the same resolution, on the descriptor it writes through;
    • chaining. Several intents on one note are planned in run order, each against the bytes the previous one leaves (follows names it; the note is read once), which is the order #22 applies them in, so before_sha256 is exactly the expected_before_sha256 of that apply. An intent that cannot be planned does not change what the next one sees;
    • (D3) which runs. ok, noop and degraded runs are planned. A failed (run_failed) or undone (run_undone) run is refused, and so is a run whose changes is not empty (already_applied: its journal, #22, says what changed);
    • (D4) horae diff exit codes: 0 planned without problems, 1 configuration or store problem, 2 usage error, 3 unknown, unfinished or refused run, 4 planned with problems (some intents cannot be applied), 70 internal error. A notification already sent (duplicate) is information, not a problem. With --json, an error is a JSON object on stdout, {"schema_version": 1, "error": {"kind", "message"}} (kinds config_invalid, store_error, unknown_run, internal), and a refused run is the change set with "refused": {"kind", "message"}; without it, errors go to stderr. Text output escapes every Unicode Cc, Cf, Zl and Zp character except tab; JSON output is ASCII and strict (a non-finite number becomes a string);
    • (D5) what a dry run may write. User data never: no vault change, no notification, no remote write. Horae's own state database (<state_dir>/horae.db) is not user data: horae run --dry-run (#26) records its run there, and the write guard of tests/test_dry_run.py allows only that path (and its -wal, -shm, -journal) besides the test's scratch directory. horae diff itself opens the store with Store.open(path, read_only=True): it creates, migrates and changes nothing (an OS error opening it exits 1). The guard covers Python-level writes, metadata changes, sockets, name resolution, SQLite connections and process creation; writes made below Python (ctypes, C extensions) and plugin subprocesses (#24's sandbox) are out of its scope;
    • (D6) the vault is given with --vault only (no environment variable, no horae.yaml key) until plugin sinks exist (#24); without it note intents are vault_unset problems;
    • (D7) notification deduplication. dedupe_key is the SHA-256 (canonical JSON) of the pipeline, the routing entry (applied_by and its recorded parameters), the run's input_hash (or, without one, its id), the intent, and its occurrence index (how many identical entry and intent pairs precede it in the run). A reused unchanged input re-proposes the same keys, while two identical notifications of one run are both sent. The applier (#22) records a key once sent (Store.record_notification) and skips it afterwards; the key reaches the notifier as SinkCall.dedupe_key;
    • (D8) horae diff ships in #21; horae run --dry-run prints the same change set (#26, decision 37).

Provisional decisions (#23, pending maintainer review)

  1. Replay (#23): run record extensions and horae replay. Compatible v1 additions, all optional, so records written before them stay valid (they are only not replayable). The engine (horae.engine.execute) writes them; D1 to D6 are provisional maintainer decisions:

    • (D1) pipeline_definition: the canonical pipeline definition that ran (horae.engine.canonical_pipeline, the input of pipeline_digest), at most 64 KiB as compact JSON (MAX_PIPELINE_BYTES; omitted when larger). It is named pipeline_definition because pipeline already holds the pipeline's name. The models check that it is a valid pipeline named pipeline; replay checks that its digest is pipeline_digest. Replay runs this definition, so a run replays as it ran after its file was edited (noted); without it, only a current definition with the same digest replays, else "pipeline changed" (unless --against-current);
    • per-call raw proposals (finding 1): inputs[].call (the source's index in its step) and inputs[].intents (the raw intents it returned, any JSON shape, absent when none); a collect source whose proposals failed the step is recorded too. A failed source's entry in the step output gains call. A transform step that ran has steps[].calls: [{call, ref, params, input_hash, intents?, error_kind?}]: each call made, input_hash the SHA-256 of the canonical JSON of the input it was given (intermediate outputs are not recorded). Replay answers each call by (step, call) and the engine re-validates and re-routes the raw proposals, so a target omitted by the proposer is filled again from the (possibly edited) entry, and a rejected or unroutable proposal fails the replayed step as it failed the run;
    • engine-owned LLM fields (finding 2): llm[].model_alias (the pipeline's alias), input_hash (SHA-256 of the attempt's input; not the cache key, which is input_hash of the run), repair (the errors sent with the attempt) and schema_errors (each capped at 4096 characters, at most 256; the repair retry is sent these capped errors). request stays whatever the backend reports, for information;
    • (D3) models (alias to concrete model, as given to the engine) and lock_digest / config_digest: the engine records what its caller passes; the runner (#19) passes Instance.lock_digest() (SHA-256 of the canonical JSON of the validated horae.lock) and Instance.config_digest() (SHA-256 of the canonical JSON of the validated models and plugins sections of horae.yaml, defaults filled in; the time zone, state directory and timeouts are not part of it). Replay uses the recorded models (the caller's only when the record has none, noted). A recorded digest that differs from the current instance's is an error, or a note with --against-current;
    • (D5) plugins[].provides: the tools and skills of the pipeline the run resolved to that plugin, sorted. horae.replay.LockRegistry resolves a ref to the plugin the run resolved it to when that plugin is still locked, else to the locked plugin named after its namespace, with the locked version, commit and permissions. So the PLAN.md §3.2 brief (coach.brief from mcp-brief, the skill from pack-daily-brief) replays from the CLI. Replay asks its registry once, up front, for every ref of the pipeline and runs the engine on that frozen snapshot; a PluginRegistry does no I/O beyond local files and starts no process; horae replay never uses a live plugin host;
    • comparison: canonical pretty JSON of the intents (routing fields included), plus a summary of the run status, input_hash, step kinds, statuses and error kinds, counts, violation kinds and plugin versions (with provides). An undone run's status is compared as it was before the undo, derived from its steps (noted). Messages, timings, stderr and cost are not compared;
    • (D4, refined by finding 7) horae replay exit codes: 0 identical, 1 configuration or store problem (an invalid instance, a store that cannot be opened, a schema older or newer than this Horae: like doctor and runs), 2 usage error (a bad option, an unknown run, no store at the path), 3 not comparable (the pipeline, horae.lock or horae.yaml changed without --against-current, an unresolved plugin, a call the record cannot answer, a record that is not a valid v1 record or predates these fields), 4 different, 70 internal error (its type only). --json prints {"schema_version": 1, "run_id", "pipeline", "outcome", "identical", "against_current", "definition", "pipeline_digest", "lock_digest", "config_digest", "error", "mismatches", "notes", "intents_diff", "summary"} with every key also on errors (null or empty), each digest as {recorded, current, changed};
    • (D6) horae replay opens the store with Store.open(path, read_only=True) and never creates it;
    • (D2) these extensions land with the replay itself (#23), not in a separate change.

    Remaining limits: per-call stderr and failure messages beyond their recorded excerpt are not reproduced (messages are not compared), and only the first call of a multi-call transform step has its input checked (later calls get the previous call's output, which is not recorded).

Provisional decisions (#22, pending maintainer review)

  1. Journal and undo (#22). No contract changes: the run record already has changes and the undone status. The rules (horae.apply.apply, horae.apply.undo, the runner):
    • apply in the runner. Ports.sinks (a SinkRegistry) is the runner's apply port. After the engine finishes ok, noop or degraded (not a dry run, not timed out or cancelled), the runner plans the run (plan_changes, with the notifications already sent) and applies it (apply_changes) while its row is still running and its heartbeat still beats, then saves the record with changes (indices into intents, with the core's target: note path, task fingerprint, http.post URL, or the notifier's tool). Without Ports.sinks nothing is applied. The apply is not under runs.timeout_s; each sink call (the plan's reads, the apply's read and apply, undo's read and restore) is bounded by plugin_defaults.call_timeout_s (kind timeout; the change stays "maybe applied"). A run whose caller cancels it after its steps finished but before the apply is saved failed ("cancelled before apply", nothing applied): never ok with intents that were not applied;
    • one apply at a time (D6). The runner's apply phase and horae undo hold the instance-wide apply lock <state_dir>/locks/_apply.lock (the same flock helper as the pipeline locks; a pipeline name never starts with _), in addition to the pipeline lock. The runner waits for it at most APPLY_LOCK_WAIT_S (30 s), then fails the run apply_locked with nothing applied; undo does not wait (apply_locked, exit 5 since decision 37);
    • journal first. For each planned change in intent order: journal_append (with the sink, applied_by, where it writes, sink_identity, and for a note its bytes before and after), then Sink.apply (a compare-and-swap on the planned before_sha256; the core re-reads the note and recomputes the bytes first), then journal_mark_applied. Notes are undoable; task changes, notifications and HTTP calls are journalled with undoable = 0. A notification whose dedupe_key was already sent (Store.get_notification) is skipped; once sent, record_notification and the mark share one transaction (a crash in between can send it twice, never lose it). An unchanged note is skipped;
    • failures (D1). A plan with problems or a refusal applies nothing (plan_invalid, plan_refused). Otherwise the first failing change stops the apply: earlier changes stay applied and recorded, later ones are not applied, and the run is saved failed with error = <kind>: intent <i> (<sink>) could not be applied: <message>; <n> change(s) applied before it, the rest not applied (kinds target_changed, the sink's SinkError.kind when it matches ^[a-z_]{1,32}$, timeout, host_error for any other exception or kind, whose message is dropped, apply_mismatch when the sink reports other bytes than planned, no_sink). There is no automatic rollback: a run that fails mid-apply stays failed, and horae undo is the remedy. A crash during the apply abandons the run (decision 31); its journal remains. On apply_mismatch the bytes the sink reports are journalled (actual_after_sha256, a blob), and undo accepts them as "as the run left it";
    • the store (migration 3, unreleased, so edited in place) adds journal.applied_by (undo finds the sink even for an abandoned run, which has no record), journal.sink_identity (where that sink writes), journal.actual_after_sha256 and journal.undo_overwrote_sha256 (both blobs; prune_runs keeps every referenced blob), and an index on (target, id) for the newer-run check. All are NULL for older rows;
    • sink identity. A sink may have an identity (at most 512 characters; horae.apply.sink_identity): LocalSink / LocalFileSink use local:<st_dev>:<st_ino>:<real path> of the vault, FixtureSink a fixed id. Undo refuses sink_mismatch (exit 1, also under --force, before reading anything) when the sink an entry's tool resolves to now has another identity than the one recorded (e.g. --vault names an empty or another vault). A note missing together with its directory is never "already restored" when a change of it was applied (parent_missing: RestorableSink.parent_exists). Over MCP the identity is the plugin's (decision 36);
    • undo restores bytes, not intents. RestorableSink adds read_target(target), parent_exists(target) and restore(target, content, *, expected_sha256) (content=None removes the note), a compare-and-swap. A synthetic apply was rejected: the closed intent set has no "write these bytes" or "delete" intent, and an abandoned run has no SinkCall to rebuild. Entries are grouped per (resolved sink identity, note) in sequence order, so two tools of one sink editing one note are one group: one write of the bytes the note had before the run's first change of it (a note the run created is removed), latest note first. Each note is read first: holding its original bytes it is already restored (resumability after a crash; also a change journalled but never applied); with the digest of the last applied entry's after (or actual_after), or of a later entry still applied = 0, it is restored; otherwise it changed since and the whole undo is refused before any write, unless --force, which keeps the overwritten bytes as a blob (undo_overwrote_sha256, reported). Once written, the note's entries are marked undone. When every undoable entry is undone, a run with a record is saved undone. Undoing an undone run is a no-op; a running run or a dry run is refused;
    • last in, first out per note (D8). If a later run (any pipeline) has an applied, not undone change of the same note through the same identity, undo refuses newer_run (exit 4) naming those runs, unless --force, which reports them (later_runs);
    • crashes (D3, D4). horae undo holds the pipeline lock, so the pipeline's running rows are dead: it abandons them first with the runner's helper (horae.runner.recover_pipeline, a compare-and-set on the last heartbeat), so a run killed mid-apply can be undone at once. An abandoned run stays failed (the store's constraint), its entries undone. A run with no undoable entry at all is refused nothing_to_undo (exit 3) and its status is left as it is. Directories created by apply are kept;
    • not undone (D2, D7). Task changes are not undone (no recorded before-state yet; left to the tasks story). Notifications stay sent and their dedupe keys are kept, so an undo never causes a surprise re-notification;
    • horae undo <run-id> (--vault, --force, --json) holds the pipeline's lock and the apply lock, opens the store read-write (migrating it) and writes with LocalFileSink (provisional until #24: LocalSink's resolution, every file-system call in a worker thread; nothing is created before the compare-and-swap passes, then missing directories are made relative to the parent descriptor and each new entry's directory is fsynced; the new bytes go to .horae-<12 hex>.tmp (O_CREAT | O_EXCL | O_NOFOLLOW, the note's mode, fsync), and just before os.replace the note's device, inode, size and mtime are checked against the compare-and-swap read; a removal renames the note to .horae-<12 hex>.old, hashes what it renamed, then unlinks it or puts it back with link + unlink, never over a new note; stale .horae-*.tmp files older than an hour are swept from touched directories; the remaining check-then-rename window is not closed against concurrent editors). LocalSink stays read-only for horae diff. Exit codes follow horae diff: 0 undone (or nothing left), 1 configuration, store, lock or sink problem, or sink_mismatch, 2 usage, 3 unknown, running or dry run, or nothing_to_undo, 4 refused because a note changed or a later run changed it (--force), 70 internal. horae replay used other codes (2 unknown run, 3 not comparable); #26 aligned them (D9, decision 37: an unknown run is 3 everywhere, and the pipeline and apply locks are 5). --json prints {"schema_version": 1, run: {id, pipeline, status, abandoned}, force, complete, marked_undone, refused, notes: [{target, applied_by, sink_identity, intents, action, status, forced, expected_sha256, found_sha256, later_runs, overwrote_sha256}], not_undoable: [{intent, intent_type, target, applied_by, applied}], problems}; errors are {"schema_version": 1, "error": {kind, message}}.

Provisional decisions (#24, pending maintainer review)

  1. Plugin host v1 (#24, design note and maintainer answers on #85). Contract changes, both compatible v1 additions:

    • per-call timeout (answer 8). A plugin call has a third, explicit form, {tool: <ref>, params: {...}, timeout_s: N} (ToolCall; params optional, timeout_s 1 to 600 like plugin_defaults.call_timeout_s). It cannot be confused with the mapping form, whose single key is a tool ref (always with a dot). The suggested {ref: {params: {...}, timeout_s: N}} was not used: it is ambiguous with a tool whose parameters are named params or timeout_s. Without timeout_s the explicit form is the same call as the mapping form and has the same pipeline digest; with one, the canonical form keeps {tool, params, timeout_s} (a timeout changes how the call runs). When omitted, plugins.<name>.call_timeout_s, then plugin_defaults.call_timeout_s apply. The engine passes it to ToolCaller.call(..., timeout_s=);
    • secret_in_output violation (answer 4). The maintainer's answer "add the secrets from the output" is read as: a secret value (or its base64, hex, percent or JSON encoding) found in a tool's output or intents is redacted ([REDACTED:<NAME>]) and recorded as a secret_in_output violation; the step does not fail. Redaction covers every secret the instance resolved (SecretResolver.resolved()), in stderr, error messages, outputs and intents. A replay leaves this kind out of the compared violations (it describes the live process).

    Rules of the host (horae.plugins.host), not part of a schema: - mcp>=2.3,<2.4 is a core dependency (answer 1). The host spawns the process itself (answer 2; stdio_client copies host variables) and keeps the SDK's ClientSession, which advertises no client capability and refuses sampling, roots and elicitation; - the child environment is exactly PATH (fixed), HOME and TMPDIR (empty per-run directories), LANG=C.UTF-8, TZ (the instance time zone) and the declared secrets (answer 3), with the deny list of decision 28 (env_unsafe); - one process per plugin per run, lazily started; one in flight per process; after a timeout, crash or protocol failure the process group is killed and the plugin may be started once more in the run, then plugin_unavailable (answer 6); - intents travel in the result's _meta["dev.horae/intents"] (answer 5); the untrusted input of a transform in the request's _meta["dev.horae/input"], so the arguments are the trusted parameters only. Data is structuredContent, else a single text block that parses as JSON (answer 9); - parallel collect (answer 7). The calls of a collect step run concurrently (at most 8 in flight, started in declaration order); results, snapshots, stderr, violations and intents are recorded in declaration order, so records and replays do not depend on timing. Every source of the step is called and recorded, even when an earlier one's proposals fail the step (sequentially, the later ones were not called). Transforms stay sequential (each feeds the next); act / notify entries are never called; - /proc/<pid>/environ (answer 10): Horae never adds a resolved secret to its own environment, and secret files (decision 25, the default) are recommended over {env: VAR} references, whose values a same-user plugin can read on Linux. The proper fix is the M5 container isolation (#50, #51).

    Security review of the implementation (provisional, pending maintainer review): - A. Sibling plugins. Plugins run as the same user, so while two run at once one can read the other's environment, hence its declared secrets (/proc/<pid>/environ on Linux, ps eww on some systems). Accepted as a pre-M5 risk, mitigated by the first-party-only rule of the "declared" tier, and narrowed: the engine releases each plugin right after the last step of the plan that calls it (or as soon as the run stops early), through an optional release(plugin) method of the ToolCaller (ReleasingToolCaller); PluginHost.release stops its process, so a plugin is not alive during later steps that do not use it. A released plugin called again starts afresh without using its one restart; a failing release is ignored; - B. Complete redaction from the first call. When the host opens it resolves every secret declared by every locked plugin and every secrets.refs entry (one that cannot be resolved is skipped; the plugin needing it fails with secret_missing later), so redaction does not depend on which plugin started first (SecretResolver.referenced() lists the refs); - C. More encodings. For secrets of at least 8 bytes the redactor also matches the lower- and upper-case hex, and misaligned base64 (both alphabets) of the value embedded in a longer stream at byte offsets 1 and 2 (an HTTP Basic user:<secret> header): only the characters that depend on the value alone, ceil(8k/6) to floor((8k + 8n)/6) for offset k and n bytes, so up to 4 bits of the value can stay visible on each side; - D. Short secrets and keys. Encoded and partial forms are used only for secrets of at least 8 bytes. A shorter secret is matched by its raw value only, in every channel (stderr, messages, string leaves), where it is bounded (not next to an ASCII letter or digit: token=abc123 and <ref>: abc123 match, xabc123y does not), and as a whole JSON string or number; an error message is redacted whole first (a secret may contain or straddle :), then the body of the redacted <ref>: <message> is also matched as a whole value. The host logs a warning (name only) for each secret under 8 bytes it redacts, since its encodings are not redacted. Superseded for short secrets by decision 43 H (#53): a secret under 8 bytes is now refused when it is resolved, so the bounded raw-value matching and this warning are gone; the rest of D (keys, messages, overlaps, numbers) stands. Object keys are never rewritten: a key holding a secret fails the call with output_invalid and nothing is stored. When the matches of two secrets overlap, only the leftmost one is replaced (documented limit). A JSON number whose json.dumps is a secret becomes the token string; the SDK's own log records (mcp.*, client, server) are scrubbed when created: message redacted, arguments, traceback and stack dropped (every logger since decision 43 E); - E. umask. Every plugin process starts with umask 0o077; - F. Stderr window. The per-call stderr window keeps its quiet-window heuristic (stderr and stdout are separate pipes, so nothing orders them); tests wait for a sentinel line instead of relying on timing. What a process wrote before it died between two calls goes with the next call; what it wrote after its last call is kept, redacted, in PluginHost.leftover_stderr; - G. runtime.command pinning. The lock pins version, commit and permissions, not the manifest's runtime.command or the plugin's files; pinning them is M4 (#44, #46). A relative command must resolve (symlinks included) inside the plugin's directory, and is passed as an absolute path; - the deny list (decision 28) also covers GLIBC_TUNABLES, JAVA_TOOL_OPTIONS, JDK_JAVA_OPTIONS, CLASSPATH, PERL5LIB, PERLLIB, RUBYLIB, SSLKEYLOGFILE, OPENSSL_*, NODE_EXTRA_CA_CERTS, NODE_TLS_REJECT_UNAUTHORIZED, LOCPATH, GCONV_PATH, TZDIR, LANGUAGE, SHELLOPTS, PS4, GODEBUG, MALLOC_*, UV_*, PIP_*, NPM_CONFIG_* and VIRTUAL_ENV; - calls to one plugin are serialised, so N calls to it in one step can take N times the call timeout; the run timeout (#19) bounds the whole. Group termination cannot reach a descendant that left the group (setsid/setpgid), and the final killpg after the leader is reaped has a (very unlikely) PID-reuse race; both are M5's (#50, #51).

Provisional decisions (#25, pending maintainer review)

  1. Plugin sinks, fixture plugins and the walking skeleton (#25). One contract rule (the manifest's reserved sink operation names, a pydantic-only rule: the generated schemas do not change). The rules (horae.plugins.host.sink, horae.plugins.builtin, horae.runner.open_ports):
    • sink operations by convention. An act / notify entry's tool (<ns>.<tool>, in provides.sinks or provides.notifiers) is never called. The core applies the intents routed to it through five tools of the same plugin, named <ns>.read, <ns>.apply, <ns>.restore, <ns>.parent_exists and <ns>.identity (horae.contracts.plugin.SINK_OPERATIONS), which the plugin lists in tools/list but not in provides, so no pipeline step can call them (the engine only calls provided tools); the core calls them with PluginHost.call_operation (same process, timeouts, restart and redaction as any call). McpSinks is the SinkRegistry (Ports.sinks): one McpSink per (plugin, namespace);
    • reserved names. The manifest contract refuses a plugin that provides <ns>.<op> for an operation op and one of its own sink or notifier namespaces ns; HostRegistry refuses any plugin providing a sink operation name of any installed plugin's namespaces (and a manifest built without validation). call_operation only calls tool == f"{ns}.{op}" with op in SINK_OPERATIONS, ns a sink or notifier namespace of that plugin and tool provided by no plugin (tool_missing otherwise): it is not a way to call arbitrary unprovided tools;
    • the core computes the bytes (D1 of decision 32). For a note.* intent McpSink.apply reads the note (<ns>.read), checks the planned SHA-256 (target_changed), computes the new bytes with horae.apply.notes.note_after and sends them to <ns>.apply with expected_before_sha256: the plugin only writes them, atomically, if the note still has that digest, and reports the digest of what it wrote. Other intents are passed through (content and expected_before_sha256 null). restore is the same compare-and-swap for undo (content: null removes the note);
    • apply_mismatch over MCP has no actual_after. A sink reporting another digest than the planned one fails the change with apply_mismatch; only the digest came back, not the bytes, so the journal entry keeps applied = 0 without actual_after, and horae undo takes the note for "changed since": restoring it needs --force (which keeps the overwritten bytes in the journal, decision 34);
    • double read (accepted). apply_changes reads a note to check it against the plan, and McpSink.apply reads it again to build the bytes it sends: two <ns>.read per note change. The adapter never sends bytes computed from a read it did not make itself, notes are small, and merging the reads would couple the adapter to the apply phase;
    • one note-size cap over MCP. Note bytes are standard base64, at most MAX_MCP_NOTE_BYTES = (MAX_MESSAGE_BYTES 8 MiB − a 64 KiB envelope margin) × 3/4 = 6,242,304 bytes (about 5.95 MiB) decoded, either way (note_too_large; the built-in LocalFileSink keeps 16 MiB). A sink sends each result once, as structuredContent with a short text block (no second copy of the payload). The cap is checked before encoding on both sides: McpSink.apply / restore refuse larger content before the call, and file-sink.read of a larger note returns note_too_large (never an oversized message, which would cost the plugin its process with output_too_large). Malformed results are output_invalid. A sink error is a result {"error": {"kind", "message"}}: the kind must match ^[a-z_]{1,32}$ (else host_error), the message (already redacted by the host) loses its control and format characters and is capped at 500 characters. A host failure becomes SinkError with the host's kind (timeout, plugin_crashed, tool_missing…);
    • secret_in_output from sink operations. It is logged by secret name only (the host redacted the value) and kept by McpSinks; apply_changes adds those collected during a run (the runner's diff and apply) to RunRecord.violations (McpSinks.take_violations, deduplicated, at most 256 in all). Outside a run (horae undo, a dry run's diff built outside the runner) there is no record: they are only logged;
    • trusted configuration. horae.yaml has no per-plugin configuration in v1, so every sink operation receives paths, the plugin's path permissions as approved in horae.lock, and every tool call carries them in _meta["dev.horae/paths"]. file-sink writes to its single paths.write entry (vault_unset without one, config_invalid otherwise); its manifest asks for no path, since where the vault is is the user's choice, granted in the lock. This channel stays for v1: M4's horae plugin add (#44) must carry the paths.write entry into the lock it writes (a per-plugin configuration in horae.yaml is a later decision);
    • identity (decision 34). mcp:<plugin>:<what <ns>.identity returns> (its SHA-256 when longer than 512 characters). sink_identity stays synchronous, with a mandatory asynchronous prepare done by the core: a registry may have prepare(tools), which horae.apply.prepare_sinks awaits before any identity is read, with only the tools about to be used (apply_changes: the run's applied_by tools, so a notify.push or task.* change, which reads nothing first, still journals its identity; undo_run: the journal's undoable entries). No caller prepares by hand. Until it is fetched the identity raises identity_unknown. Definitive failures (identity_invalid, vault_unset, config_invalid) are cached; any other kind (host kinds: a timeout, a crash) is retried once on the next prepare, then cached. file-sink returns local:<st_dev>:<st_ino>:<real path> of its vault, so undo refuses another vault (sink_mismatch). The prefix keeps a plugin from claiming the identity of the built-in LocalFileSink: horae undo --vault refuses a run applied through file-sink; without --vault, horae undo goes through the plugin host (#26, decision 37);
    • built-in fixture plugins. fixture-source (fixture-source.serve, data and intents from a JSON fixture file, default the packaged one; a file must be a regular file whose real path is inside a paths.read entry approved in the lock, opened with O_NONBLOCK and checked with fstat; its manifest asks for no path, and the walking skeleton's lock grants none, so only the packaged fixture is served there) and file-sink (file-sink.write_note, built on LocalFileSink, so the same path and write rules) are stdio MCP servers in horae.plugins.builtin, version 0.1.0. Their packaged manifests run python3 -m <module>; horae.plugins.builtin.install(directory) writes them to <directory>/<name>/plugin.yaml (mode 0644, a temporary file then os.replace, no symbolic link followed for the directories, InstallError when sys.executable is empty) with the command pinned to the running interpreter, until M4 installs plugins into their own environments (#44, #46);
    • placeholder commit for built-ins. The walking skeleton's lock pins both plugins at commit 0000000000000000000000000000000000000000 (a commit of the core cannot name the commit that contains it). It is not fetched: the plugins ship inside the core. M4's fetch and verify (#44, #46) must special-case built-in plugins rather than try to resolve that commit;
    • live ports. horae.runner.open_ports(instance, plugins_dir) builds the HostRegistry (HostRegistry.from_directory), opens a PluginHost (host_for_instance) and McpSinks for one run or one undo, and closes the host at the end of the block. Where plugins are installed is M4's; horae run, horae diff and horae undo open it on <instance>/plugins (#26, decision 37);
    • the walking skeleton (examples/walking-skeleton) pins both plugins with the placeholder commit and a vault path to replace (in a copy of the directory); tests/test_e2e.py builds its lock from it at test time. The end-to-end test runs dry run (under the write guard, which then allows the plugins' processes and Horae's own state: the store, <state_dir>/locks and <state_dir>/plugin-runs; the vault is also compared byte for byte), run, replay and undo with real subprocesses, and fails when the module takes 60 s or more;
    • store first open (a flake fix found here). Store.open (writable) initialises a database (create, WAL, migrate) under a POSIX advisory lock <db>.init.lock (0600, O_NOFOLLOW, flock retried with full-jitter backoff for at most the busy timeout, then StoreBusy); an open whose database header already says WAL and the current schema version skips it. Read-only opens never take it nor create the file. The lock file is left in place (removing it would race with the next opener).

Provisional decisions (#26, pending maintainer review)

  1. CLI commands: one exit-code table, --json everywhere, horae init and horae run (#26). No contract changes. The rules (horae.cli, horae.cli_output, horae.cli_init, horae.cli_run, horae.cli_host, horae.cli_undo):
    • exit codes, the same for every command (init, run, runs, diff, undo, replay, doctor; each command's --help lists the ones it uses, horae --help the table): 0 ok (no problem, listed, planned, identical, undone, created); 1 a configuration, store, plugin or runtime problem (doctor's problems, a run that failed or timed out or was lost, a sink failure, sink_mismatch); 2 usage error (a bad option, a missing argument, a malformed --var); 3 unknown or refused (an unknown run or pipeline, a refused run: failed, undone, already applied, a dry run, nothing to undo; a replay that cannot be compared; a non-empty horae init target); 4 different (a replay differs; a plan with problems, from horae diff or horae run --dry-run; an undo refused because a note changed); 5 locked (the pipeline is running, pipeline_locked; the apply lock is held, apply_locked: undo at once, a run after APPLY_LOCK_WAIT_S); 70 internal error (EX_SOFTWARE, only the exception's type is printed); 130 / 143 horae run interrupted by SIGINT / SIGTERM (128 + the signal; a KeyboardInterrupt reaching any other command is 130, kind interrupted). Changes from decisions 32 to 34: horae replay of an unknown run (or with no store) is 3, not 2; horae undo refused by a lock is 5, not 1. Decisions 27 and 31 (E) are unchanged;
    • --json on every command: exactly one JSON document on stdout, ASCII, strict (horae.apply.render.dumps), schema_version: 1. An error is {"schema_version": 1, "error": {"kind", "message"}}, usage errors included (kind usage; JsonUsageCommand recognises --json among a command's arguments, before any --; JsonUsageGroup does the same for the horae group's own errors, horae --json and horae nope --json); horae replay keeps its report with every key and outcome error, its error being the same {kind, message} object (null when there is none; kind not_comparable for a replay that cannot compare), and horae doctor its report (instance is the resolved absolute path). An OSError is store_error when it names the store's files, else io_error (the file it names and its strerror, never the exception's text). Without --json, results go to stdout and errors to stderr as one line, horae <command>: <message>, with untrusted text escaped (safe: Unicode Cc, Cf, Zl and Zp except tab). No colour unless asked (horae diff --color). Common error kinds: config_invalid, plugins_invalid, store_error, unknown_run, unknown_pipeline, pipeline_locked, apply_locked, internal;
    • horae init [DIR] (default: the current directory) writes a working example instance, the walking skeleton: horae.yaml and pipelines/daily-fixture.yaml (the packaged horae/init_template, kept identical to examples/walking-skeleton by a test), a generated horae.lock (both built-in plugins at their version, the placeholder commit of decision 36, the permissions their manifests ask for, and file-sink's paths.write set to the instance's own vault/, an absolute path), an empty vault/, state/ (0700), plugins/ (horae.plugins.builtin.install) and a .gitignore for those three. It refuses (exit 3, target_not_empty or target_invalid) a target that is not a new or empty directory (a file, a symbolic link, anything inside it): no --force, nothing is ever overwritten (files are opened x). It is atomic: the lock is validated first (a path it cannot hold, a backslash for instance, is target_invalid, exit 1, nothing written); the instance is built in a temporary directory, then a new target is one rename of a hidden sibling (.horae-init-*), and an existing empty target (opened O_NOFOLLOW) gets the entries of a hidden directory built inside it renamed up into it (the directory itself is kept, so a shell inside it stays there, and its parent need not be writable); on any failure the temporary directory, the entries moved and the parents init created are removed. --json prints {schema_version, instance, vault, pipelines, plugins, files}. Instances are not relocatable in v1 (provisional): horae.lock holds the vault's absolute path and the installed manifests the absolute path of the interpreter; init says so, and horae doctor reports a copied or moved instance (below); Afterwards horae doctor passes and horae run daily-fixture writes vault/Daily/<date>.assistant.md;
    • horae run <pipeline> [--dry-run] [--var KEY=VALUE]... [--json]: loads the instance (config_invalid), checks the pipeline (unknown_pipeline, 3) and the installed plugins (HostRegistry.from_directory on <instance>/plugins: plugins_invalid, 1, before any process starts or any file is written), then open_ports and Runner.run (lock, recovery, execute, apply through McpSinks, whose identities the core prepares, decision 36). --var names match VarName and may not be a built-in variable (now, timezone, date; usage, 2); at most MAX_ITEMS - 1 of them (the context holds date too; usage, 2), and a malformed one echoes only its name part (before =, truncated to 64 characters), never its value. A dry run records its run and prints the change set it would apply (plan_changes, rendered like horae diff, without a second header line; with problems, exit 4; when a sink plugin could not start, plugin_unavailable, spawn_failed, startup_timeout or handshake_failed, exit 1, kind plugin_unavailable: a problem, not a difference). The run's status gives the code: ok, noop, degraded 0; failed 1 (run_failed; apply_locked 5); RunTimedOut 1 (timeout), RunLost 1 (run_lost), PipelineLocked 5. --json prints {schema_version, run_id, run: {id, pipeline, status, dry_run, started_at, finished_at, intents, changes: [{intent, target}], cost, violations, error_kinds, error}, plan, error} (run_id as soon as the run's row exists, from Runner.run(on_begin=), also when no record was saved; run is null when none was, plan without --dry-run); error_kinds are the failed steps' kinds (also appended to the text error). No LLM backend in M1: a pipeline with an llm step fails with llm_unavailable (exit 1); M2 wires the backends into open_ports(llm=...). Signals (follow-up of decision 31 F): SIGINT and SIGTERM handlers (loop.add_signal_handler, removed afterwards) cancel the run's task and the command exits 130 / 143, naming the run. During the engine phase the runner saves the partial record (failed, kind cancelled), which is printed. The apply phase is shielded (provisional): once it has started planning, a cancellation is remembered, the apply finishes (each sink call bounded by call_timeout_s), the record is saved with its real status (its changes were applied: ok, say) and only then is the run reported interrupted; a cancellation while it waits for the apply lock stops the wait (failed, "cancelled before apply", nothing applied). If the run is nonetheless abandoned during the apply (a crash), its error says "run crashed during apply (); run horae undo <id> to revert what was written", the command prints "abandoned during apply; run horae undo <id>" and --json has the id; a cancellation that abandons a run says cancelled: ..., never run crashed (CancelledError). A second signal while the run stops is ignored: the runner's grace period (STOP_GRACE_S) still bounds the stop, after which the run is abandoned as before. Secrets: the run's error and messages come from the record and the host, which redact them; internal errors print the exception type only;
    • sinks for horae diff and horae undo: through the plugin host (open_ports, McpSinks) when the instance has a plugins/ directory, so a run applied by file-sink is planned and undone by file-sink (decision 36's identity). --vault stays as an explicit override: the built-in LocalSink (diff, read only) or LocalFileSink (undo) on that directory, for instances without plugins or runs applied by the built-in sink; undo through it refuses a run applied by a plugin (sink_mismatch). Without plugins and without --vault, the built-in sinks have no vault (vault_unset), as before. horae diff through the host starts the plugins, which only read (<ns>.read); the store is still opened read-only;
    • where plugins are installed: <instance>/plugins/<name>/plugin.yaml (horae.cli_host.PLUGINS_DIR), until M4's horae plugin add (#44) decides otherwise;
    • horae doctor checks, beyond the configuration (check_instance, horae.cli_host.instance_problems): every paths.read / paths.write entry of horae.lock exists; an instance with its own vault/ that the lock does not write to is a problem (a copied instance still writing to the original's vault); with a plugins/ directory, the plugins match the lock (check_plugins) and each stdio command (its pinned interpreter) exists and is executable (resolve_command). Each is a problem (exit 1) naming horae.lock or the plugin's manifest;
    • follow-ups (out of scope here): enforcing the manifests' horae version range against horae.__version__; whether a second identical run should be noop rather than ok.

Provisional decisions (#28, pending maintainer review)

  1. LLM backend interface, the anthropic backend, usage and cost (#28). Compatible v1 additions and the rules of horae.llm (interface) and horae.llm.backends.anthropic (SDK anthropic 1.17 over httpx2, Messages API, anthropic-version: 2023-06-01):
    • contract changes (all optional): models.<alias>.price in horae.yaml, {input_per_mtok, output_per_mtok, cache_read_per_mtok?, cache_write_per_mtok?}, US dollars per million tokens, each 0 to 10000; models.<alias>.max_output_tokens (1 to 1000000), a cap on every call's max_tokens; base_url of a backend: anthropic alias must be https:// (C). Usage (run records: llm[].usage, cost) gains cache_read_tokens, cache_write_tokens (when the provider reports them; tokens_in stays the input billed at the full price) and priced (false when the alias has no price: usd is then 0). Without a cache price, cache reads are priced as input tokens and cache writes at twice the input price (conservative). A price is part of the models section, so changing it changes config_digest (decision 33), not the LLM cache key. The horae doctor report's severity may now be warning (decision 27): a warning is printed and listed but does not fail the check (ok stays true, exit 0);
    • A. no shipped price list: prices change and differ per account, so the instance states the ones it pays. Without one, only tokens_out bounds the step, so horae doctor warns about each cloud (anthropic) alias used by an llm step that has no price;
    • B. pre-flight budget: ModelBackends.render refuses the attempt with budget_exceeded, before any request (and before the key is read), when the remaining tokens_out (capped by max_output_tokens) is below 1, or, with a price, when the input alone may cost more than the remaining usd or what is left buys no output token. The input is bounded without a count_tokens call: a token is at least one UTF-8 byte, so the canonical JSON size of the whole rendered payload (system, messages, schema) plus a margin of 512 tokens (INPUT_TOKEN_MARGIN, for the framing and structured-output instructions the provider adds) is the bound; max_tokens is then what the remaining usd buys after that bound. The engine still checks the reported spend after the call;
    • C. explicit network path: the core LLM client ignores the ambient environment: no HTTP(S)_PROXY / ALL_PROXY, no .netrc, no SSL_CERT_FILE / SSL_CERT_DIR (an explicit httpx2.AsyncHTTPTransport(trust_env=False, verify=True) and a client with trust_env=False; verify=True without trust_env is httpcore2's default context on the system trust store, which reads no SSL_CERT_*, whereas ssl.create_default_context() would, through OpenSSL's default verify paths). Redirects are not followed; OpenTelemetry spans are off. An explicit proxy or CA option (models.<alias>.proxy / ca_file) is a later decision;
    • D. intents: raw intents live in a reserved top-level intents property of the skill's output object. ModelBackends validates the whole output, then, only when intents is present, requires a list (else output_invalid, with the usage), moves it into LlmResponse.intents and removes it from output. #27 (skill format) reserves the name in skill output schemas; #31 validates against the schema including it; #35 routes the intents;
    • E. what is recorded: LlmCall.request is a summary, not the payload: backend, model, max_tokens, body_sha256 / body_bytes (the exact bytes sent), and the SHA-256 and size of the skill prompt (system_*), the canonical input (input_*) and the output schema (schema_*), with repair_errors (how many errors were sent). The input is already in the run's data and LlmCall.input_hash; the full body is never recorded, dry runs included (they make no LLM call);
    • G. the #31 validator is mandatory before production use: structured outputs drop the constraints they do not support (anthropic.transform_schema moves them into descriptions), so without ModelBackends(validate=...) an output may break maxLength, pattern, numeric bounds and the like;
    • two layers: ModelBackends is the engine's LlmBackend (alias → backend, model, base_url, secret, price; prompt from a PromptSource; max_tokens from the budget); a ProviderBackend per alias makes one request with no tools. Both split an attempt into render (pure: the exact provider payload, a RenderedRequest whose body() is canonical JSON bytes frozen at render time; no I/O, no secret) and send (one network call with a fresh copy of exactly those bytes; a payload changed after rendering is refused with invalid_request), so the core can inspect what leaves the host first (T10, #34/#53); complete is send(render(...));
    • the API key comes from the declared secret only (models.<alias>.secret, through the instance's SecretResolver, decision 25), resolved on the first call. The SDK reads ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, credential profiles and ANTHROPIC_BASE_URL only when it is not given a key and a URL, so it always gets a placeholder key and an explicit base_url (default https://api.anthropic.com). SDK retries are disabled (max_retries=0): the engine owns the single repair retry;
    • headers are rebuilt: the SDK merges ANTHROPIC_CUSTOM_HEADERS from the environment into every request, which can override any header. A request hook on its HTTP client refuses any request but POST <base_url>/v1/messages to the alias' origin and replaces every header with exactly host (from the request URL), accept and content-type (application/json), content-length (the body's length), anthropic-version (2023-06-01), user-agent (horae) and x-api-key (the declared secret, set at the last moment). No Authorization, anthropic-beta, x-stainless-* (platform, retry or timeout) or accept-encoding header is sent. A refusal carries its reason in its own exception (no shared state);
    • logging: at DEBUG (ANTHROPIC_LOG=debug or a logging configuration) the SDK logs request options, the prompt and the input included. Building a client pins the anthropic, httpx2 and httpcore2 loggers, and their children that set a lower level, to WARNING;
    • request shape: system is Horae's preamble (the user message is untrusted data, never instructions; answer with JSON matching the schema), then the skill's rendered prompt. One user message holds the input as JSON inside <input> tags, then, on the repair retry, the previous attempt's schema errors as a JSON array inside <schema_errors> tags (framed as data, not instructions). In both, every < is written as the JSON escape < (valid JSON, since < only occurs inside strings), so the data cannot close its tag. The output is constrained with structured outputs (output_config.format: {type: json_schema, schema}, the schema passed through anthropic.transform_schema); the text must parse as one JSON value: no NaN or infinite number (1e999), no duplicate key, no nesting beyond the parser's limit;
    • error kinds (messages are Horae's: the HTTP status and the API error type, never the API's text; raised outside the SDK's exception handler, so neither __cause__ nor __context__ reaches the SDK error and its request): timeout (SDK timeout, 408, 504), rate_limited (429), auth_failed (401, 403, an unresolvable secret), overloaded (529, 503), invalid_request (400, 404, 409, 413, 422, an unknown alias, a schema structured outputs cannot take, a payload changed after rendering), output_invalid (refusal, max_tokens or context-window truncation, tool or other non-text content, unacceptable JSON, intents not a list), host_error (connection failure, a refused request, another status); budget_exceeded (B), backend_unavailable (an alias whose backend has no implementation yet) and skill_unavailable (no prompt for the skill) come from ModelBackends. Every rejection after a successful HTTP response carries the usage the response reported; when it reported none usable, the call is charged conservatively (the input bound and the whole max_tokens);
    • wiring: open_ports gives the runner a ModelBackends over the instance's aliases when a pipeline has an llm step (sharing the host's SecretResolver; lazy; closed with the ports), so horae run no longer fails with llm_unavailable (decision 37) when an alias is configured. horae doctor reports a model alias used by an llm step whose backend is not available (models.<alias>.backend), besides its secret;
    • integration points (#27): the prompt, viewed input, output schema and skill version come from the LlmRequest (RequestPrompts reads the fields #27 added: prompt, output_schema, skill_version). A request without a prompt or schema (an engine given no SkillSource) stops with skill_unavailable before any request; skill_unavailable means "no usable prompt for this skill here", and #27's skill_invalid (a skill that is present but malformed) is reported while planning, before the LLM layer is reached. open_ports (horae.runner._ports) builds both the owned ModelBackends and the DirectorySkills source (Ports.skills, decision 39); the reserved intents property is the one #27's schema check requires of a skill that declares intents (horae.skills.INTENTS_PROPERTY is INTENTS_KEY).

Provisional decisions (#27, pending maintainer review)

  1. Skill format and loader (#27). A new contract, schemas/skill/v1.json (horae.contracts.skill.SkillManifest), the loader horae.skills, and one optional run-record field, llm[].skill_digest (a compatible addition). Numbered 39 because #28 (decision 38) merges first. Choices to verify:
    • (A) layout. A skill <namespace>/<skill> is the folder skills/<namespace>/<skill>/ of the plugin that lists it in provides.skills (HostRegistry.plugin_for_skill, then the plugin's installed directory). The namespace is a folder level so one plugin can ship skills of two namespaces without a clash. The folder holds skill.yaml, the prompt (prompt.md by default) and the output schema (output.schema.json by default); other files are ignored;
    • (B) skill.yaml and race-safe reads: name (must equal the skill ref), version (semver), description (one line), input_view (1 to 256 paths), optional prompt and output_schema file names, optional intents. File names are one path segment (^[A-Za-z0-9_][A-Za-z0-9_.-]*$), so ../, absolute paths and hidden files cannot be written. The loader opens the plugin root and walks skills, the namespace and the skill one component at a time relative to the previous descriptor (dir_fd), each O_DIRECTORY | O_NOFOLLOW, then opens each file relative to the skill folder with O_NOFOLLOW | O_NONBLOCK and checks it with fstat: a regular file with exactly one hard link. Every symbolic link inside the skill tree is refused (a symlinked skill folder, namespace or skills folder too, and a link between two files of the folder), and so is a hard link to a file elsewhere. Swapping a component for a link between a check and the read cannot redirect the read. Sizes: skill.yaml, prompt and schema at most 64 KiB each. Every problem, including a non-finite number, a lone surrogate, a $ref chain or a recursion too deep, is a SkillError (skill_invalid);
    • (C) input view: dotted paths with [], not JSON Pointer: tasks[].title, [].data (a collect output is an array at the root), matrix[][].v. JSON Pointer names one location (/tasks/0/title) and has no "every element", and its ~0/~1 escapes are hard to review in YAML. Names are [A-Za-z_][A-Za-z0-9_-]*: a key with another character cannot be selected in v1; the bracket-quoted form (["a.b"]) is reserved for it. A path selects the whole value it ends on; overlapping or shape-contradicting paths are refused. input_view is a list of paths or a mapping path: {options} (for #34's field classes, events[].attendees[]: {class: person}): options are free-form but bounded (at most 16 per path, names like the paths', values booleans, finite numbers, one-line strings or lists of at most 64 of them); class, when given, is one of person, email, phone, place, amount, free_text. v1 does not act on options; they join the skill's digest only when present, so a mapping without options has the list form's digest. Applying the view (InputView.apply) keeps exactly the declared keys that are present, maps [] over arrays (keeping order, dropping elements of the wrong shape) and re-encodes the result with sort_keys, so object keys are sorted at every depth (inside selected whole values too) and nothing is shared with the input; a value of the wrong shape selects nothing (the root: null, see G). Missing fields are not an error: the input is untrusted data;
    • (D) prompt: no template syntax in v1. The prompt is sent verbatim; {{ and }} are refused so a later syntax (e.g. {{date}} from the run context, never from the input) is a compatible addition. It must be non-empty UTF-8 without a character of the Unicode categories Cc, Cf, Co, Cs, Cn, Zl, Zp (but tab and newline: no CR, so the digest does not depend on line endings), which covers the bidirectional controls, zero-width characters, U+00AD, U+180E, the tag characters U+E0000 to U+E007F and U+2028 / U+2029, nor another invisible character (the variation selectors U+FE00 to U+FE0F and U+E0100 to U+E01EF, the combining grapheme joiner, the Hangul fillers). The input is never interpolated into the prompt: it travels separately, as data (tenet 5);
    • (E) output schema: draft 2020-12, self-contained, regex-free and bounded (horae.skills.check_output_schema): the metaschema, an optional $schema that must be 2020-12, a root "type": "object", only local $refs (at most 32 chained, no cycle, no %: the validator percent-decodes pointers; resolved with referencing, as the validator resolves them), every $defs / definitions entry bounded even when unreferenced, and no $id, $anchor, $dynamic*, $recursive* or $vocabulary; no pattern, patternProperties, propertyNames or "format": "regex" (a plugin author's regex is a ReDoS risk; #31 must still validate outputs in a worker it can kill on a timeout); every subschema a value meets has a type, enum, const, $ref or combinator; a string needs maxLength, an array maxItems (and items past its prefixItems), an object additionalProperties: false (as the backends' strict structured-output modes require), an integer or number a finite lower and upper bound. The size bound is in UTF-8 bytes of the compact JSON (separators=(",", ":"), ensure_ascii=False) and is a sound worst case: a string counts 6 * maxLength + 2 (every code point escaped as \uXXXX), a number the digits of its larger extreme (an integer two more, for 3.0; a number or an extreme of 10^15 or more at least 25, the longest float repr), enum / const their longest serialisation (1 may be 1.0); anyOf / oneOf take the largest branch, allOf the smallest bounded branch (unconstrained branches are skipped; refused only if none is bounded), and a keyword that does not bound is skipped when another one does. #31 re-serialises the validated output in that form, so the bound holds for what it stores. A property test (hypothesis, a new dev dependency) checks it on random bounded schemas. The bound must be at most MAX_OUTPUT_BYTES (256 KiB); the file nests at most 64 levels and is strict JSON (no duplicate keys, no NaN, no number overflowing to infinity). Amended by #31 (decision 44 G): the product of anyOf / oneOf branch counts along any path of the schema, $refs followed (memoised per $ref), is at most MAX_COMBINATOR_FANOUT = 1024 (a validator tries every branch, so nested alternatives, through a chain of $defs say, make one validation exponential); alternatives side by side (properties, allOf) do not multiply. This adds jsonschema as a runtime dependency (it was a dev dependency; #31 needs it to validate outputs). Amended by #36 (decision 48 D4): an enum or a const needs a type beside it (SchemaProblem naming the JSON pointer: Anthropic's structured output, transform_schema, refuses one without), and horae doctor reports a loaded skill's schema that a backend's structured output still refuses (schema_problems, with the pointer of the deepest refused subschema): an error when an alias of that backend runs the skill, else a warning;
    • (F) intents. intents is a list of types or a mapping type: max (1 to 256, #35): at most max intents of that type per llm step; more is a guard violation that degrades the step (decision 46; it was intent_rejected before #35); a reused output over the limit is a cache miss. Omitted or empty: the skill proposes none. They must be within the plugin's approved permissions.intents (load error otherwise). The engine checks the LLM's intents against the plugin's permissions narrowed to the skill's, on fresh and reused outputs alike, and a task.update_status fingerprint must appear in the viewed input (what the model was shown), not merely in the data collected. The reserved output property (#28): the LLM proposes intents in a top-level intents property of its output, which the backends extract; a skill that declares intents must declare properties.intents as a bounded "type": "array" in its output schema, and a skill that declares none may not;
    • (G) the engine (execute(..., skills=SkillSource), Ports.skills, built by open_ports as DirectorySkills over <instance>/plugins): the skill is loaded while planning, before the backend is checked, so an invalid skill fails the run before any plugin is called (skill_invalid on the llm step, even without a backend; a port bug is host_error), and horae doctor loads every skill an llm step uses (a SkillError is a problem). LoadedSkill exposes name, version, digest, prompt, output_schema (a fresh deep copy on each access: the skill keeps canonical bytes), intents, intent_limits, output_bound, view_paths and view(data). LlmRequest gains prompt, output_schema (a fresh copy per attempt), skill_version and skill_digest, and its input is the viewed input, so a backend (#28) only sends it. A viewed input of null (the input does not have the view's shape) degrades the step without calling the LLM (input_invalid). LlmCall.skill_version is the loaded skill's version (not the backend's), LlmCall.skill_digest its digest, and LlmCall.input_hash the hash of the viewed input. Without a skill source (fakes, older callers) nothing changes; whether a real backend must refuse a request without a prompt is a question for the maintainer;
    • (H) cache key. With a skill, the key (RunRecord.input_hash) is the SHA-256 of {skill, plugin: {name, version, commit}, model, input: <viewed input>, skill_version, skill_digest}, where skill_digest is the SHA-256 of the canonical JSON of {name, version, prompt, output_schema, input_view, intents} (plus view_options and intent_limits when the manifest has any; not description). A new version, an edited prompt, schema, view or intents is a cache miss; a change to an undeclared input field is not (the model would see the same thing). Skills are loaded once per run (DirectorySkills caches them), so a run sees one version of the files;
    • (I) replay. replay(..., skills=) passes the source to the engine; horae replay reads skills from <instance>/plugins when it exists (local files only, like LockRegistry). A skill edited since the run replays as different, by design; when both records carry llm[].skill_digest, the report adds the note "skill changed since the run" and an llm.<skill>.skill_digest summary field.

Provisional decisions (#30, pending maintainer review)

  1. The openai-compatible and ollama backends (#30). Two compatible v1 additions and the rules of horae.llm.backends.openai_compatible and horae.llm.backends.ollama, which keep every rule of decision 38 (render/send, the key only from the declared secret, rebuilt headers, the explicit network path, quiet loggers, strict JSON, the pre-flight budget, clean error chains, the summary recorded as LlmCall.request, reserved intents) and share its code (horae.llm.backends._shared):
    • contract change (optional): models.<alias>.structured_output, json_schema (the default when unset), json_object or none, accepted for backend: openai-compatible only (the model and the JSON Schema both refuse it on another backend). It is the fallback for a server that lacks JSON Schema structured output;
    • contract change (optional): models.<alias>.max_tokens_field, max_tokens (the default when unset) or max_completion_tokens, openai-compatible only (refused on another backend by the model and the JSON Schema), for OpenAI's reasoning models, which refuse max_tokens. There the limit also bounds the hidden reasoning tokens, so a low tokens_out can end in length with no visible output (an output_invalid truncation, charged); the payload keys follow the field, so a payload rendered for one field is refused by an alias set to the other;
    • A. no SDK: both talk to their API with a direct httpx2 client (one JSON POST). The openai SDK would add a dependency and what the anthropic backend has to neutralise (OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_ORG_ID / OPENAI_PROJECT_ID, its own retries, platform headers and debug logging); the ollama client reads OLLAMA_HOST. Nothing here reads the environment. The posted bytes are the canonical JSON of the rendered payload, so they equal RenderedRequest.body() byte for byte;
    • B. what base_url means: for openai-compatible it is the API root with its version prefix, as the OpenAI SDKs take it (https://openrouter.ai/api/v1, https://api.mistral.ai/v1, http://vllm:8000/v1), and the only request is POST <base_url>/chat/completions; for ollama it is the server root (http://ollama:11434) and the only request is POST <base_url>/api/chat. A request to any other origin, path or query is refused (host_error). http:// follows decision 24 (loopback, private and single-label hosts only);
    • C. the key is optional: secret is optional for both; when declared it is sent as Authorization: Bearer <key> (for ollama, to a proxy in front of it), else no Authorization header is sent. The headers are exactly host, accept, content-type, content-length, accept-encoding: identity, user-agent: horae and that one (anthropic sends accept-encoding: identity too);
    • D. openai-compatible request: model, max_tokens, stream: false and two messages (system: the preamble, then the skill's prompt; user: the tagged input and schema errors of decision 38). json_schema sends response_format: {type: json_schema, json_schema: {name: horae_output, schema, strict: false}}: strict: false because OpenAI's strict mode refuses schemas that do not mark every property required or that use keywords it lacks (maxLength, pattern), and the #31 validator checks the full schema anyway (decision 38 G). json_object sends {type: json_object} and none no response_format; both append the schema to the system prompt. With json_schema the schema is not also put in the prompt: it is in response_format, and repeating it would make the request larger and give the model two copies to reconcile; the trade-off is that a server which silently ignores response_format gets no schema text (the #31 validator still refuses its output; such a server should use json_object or none). strict: false is recorded here as the decision (see above). max_tokens by default (what the compatible servers take; max_tokens_field above for reasoning models). OpenRouter's provider routing fields (order, allow_fallbacks, data_collection...) are not sent and cannot be configured: a later per-alias option, since routing decides which company sees the data;
    • E. openai-compatible response: exactly one choice, finish_reason: stop, and message.content one JSON value. length / model_length (truncation), a non-empty message.refusal or content_filter (refusal), tool_calls / function_call and any other finish reason are output_invalid with the usage. Usage is prompt_tokens / completion_tokens; a reported prompt_tokens_details.cached_tokens (at most prompt_tokens) becomes cache_read_tokens and is taken out of tokens_in. An error status carries the API's error type when it is a short identifier;
    • F. ollama request and response: model, stream: false, format (the output schema: Ollama's structured outputs, Ollama 0.5 or later), options.num_predict (the max_tokens) and the same two messages. done must be true; done_reason: length is a truncation, tool calls and any reason but stop (or none, as older servers send) are output_invalid. Usage is prompt_eval_count / eval_count; Ollama may omit prompt_eval_count for a cached prompt, and a missing count is charged conservatively (decision 38). Ollama's error text is never shown: the message has the status only (a missing model is HTTP 404, invalid_request);
    • G. cost and horae doctor: without a price a call costs usd: 0 (priced: false), as for every backend. horae doctor treats ollama as local (no price warning) and openai-compatible as cloud (the warning of decision 38 A, which never fails the check), even when its base_url is a local vLLM: the backend name is the only signal kept simple here. The #34 design note proposes an explicit local: flag per alias; when it lands it replaces this rule;
    • H. shared conformance suite: tests/test_llm_backends_shared.py runs the same tests over anthropic, openai-compatible and ollama with recorded synthetic responses (tests/fixtures/llm/<backend>/: success, truncation, refusal where the API has one, tool call, 401, 429, 5xx, malformed JSON, missing usage); a new backend joins it by adding a Kind in tests/llm_backend_kinds.py;
    • I. the response is bounded (every backend, anthropic included, through _shared.BoundedTransport around the client's transport): accept-encoding: identity is sent; the cap of a call is response_cap(max_tokens) = min(8 MiB, max(1 MiB, 64 × max_tokens)) bytes of decoded body (64 bytes a token: a token is a few bytes of text, which JSON may escape up to 6 bytes a character, inside the provider's envelope). A success whose content-length exceeds it is refused before its body is read; one that grows past it while read (chunked) is refused at the cap. A server that compresses anyway is inflated by Horae (gzip, deflate), at most one byte past the cap per step, so a gzip bomb (305 KB inflating to 300 MiB) is refused with about one cap in memory; any other content-encoding (or a list of them) and corrupt compressed data are refused. All of these are output_invalid with the conservative usage (decision 38: the input bound and the whole max_tokens), since the provider may have billed the call. An error body is cut at 64 KiB (its status still maps the error);
    • J. the body is read strictly: decoded as UTF-8 only (bytes.decode("utf-8"), no charset sniffing: UTF-16, a stray 0xff or an encoded surrogate are refused), then parsed by the strict JSON parser of decision 38; it must be one JSON object. anthropic now reads the raw response itself the same way (the SDK posts the canonical bytes with cast_to=httpx2.Response and still maps HTTP and connection errors; no SDK model is built from the response). Any exception other than an LlmError while reading the result is output_invalid with the conservative usage, never a crash. An error body that is not UTF-8 gives the status only;
    • K. reported usage is untrusted: a token count must be an integer from 0 to 10**12 (10**400 or 10**308, which would overflow the cost to infinity, are unusable: the call is charged conservatively). A usable report is then floored: tokens_in (with the cache tokens) at least ceil(request bytes / 4) and tokens_out at least ceil(UTF-8 bytes of the output text / 4), the latter capped at max_tokens (what a provider honouring the request may bill). The larger value is the one recorded, priced and charged to the budget; the reported value is not kept separately (kept simple: one Usage). A server that reports 0 / 0 is still charged for what it plainly sent;
    • L. http:// is checked at connect time (decision 24 limits the host name; this limits where it resolves): for an http:// base_url the transport's network backend (_shared.LanOnlyNetwork) resolves the host when it opens a connection and refuses unless every address is loopback (127/8, ::1), RFC 1918 (10/8, 172.16/12, 192.168/16) or IPv6 ULA (fc00::/7), an IPv4-mapped address being checked as IPv4; link-local (169.254/16, fe80::/10, where cloud metadata services answer) and CGNAT (100.64/10) are refused. It then connects to the checked address itself, so a second lookup cannot rebind the name. A refusal is host_error ("request refused: an http endpoint that resolves to a public address"), like every other refused request, and nothing is sent; a failed lookup is a connection error (host_error, or timeout within the step's timeout). https:// endpoints are not restricted (TLS authenticates the host);
    • M. horae doctor warns about a key over http://: an alias used by a pipeline with a secret and an http:// base_url gets a warning (never a failure): the key crosses the local network in clear, readable by anyone on the path;
    • N. the base_url path cannot traverse: besides decision 24, a base_url whose path has a . or .. segment or an encoded /, . or \ (%2F, %2E, %5C, any case) is refused, since a server or proxy may decode it into a path the guard never compared (https://h/%2e%2e/v1, https://h/a%2Fb, https://h/v1/../x).

Provisional decisions (#33, pending maintainer review)

  1. Budgets per day and the usage ledger (#33). (39 and 40 are taken by #27 and #30.) A compatible v1 addition and the rules of horae.runner._budget, the store and horae usage:
    • contract change (optional): horae.yaml budgets: {daily?, pipelines?}, where daily is {usd?, tokens_out?} (at least one, and not null: each anyOf branch of the JSON Schema requires its property as a number; usd > 0, tokens_out >= 1) for every pipeline together, and pipelines.<name>.daily the same for one pipeline (a name that is not a pipeline of the instance is a loader problem). Both apply; the lower allowance wins. The day is the instance's timezone day (not a trigger's). usd bounds only priced aliases (an alias without price records usd: 0, decision 38 A); tokens_out bounds every call. The step's own budget is unchanged and still bounds both attempts together;
    • reservation: before every LLM attempt, the runner first prepares the request outside any lock (ModelBackends.prepare: the alias, the skill's prompt from the PromptSource, which may read files, the provider backend and the input bound); then, in one store transaction (BEGIN IMMEDIATE, so the processes of other runs wait for it), it reads the day's spend from the ledger (settled calls at their cost, unsettled ones at their reservation), caps the attempt's budget with what is left of each ceiling (see A for a refusal), renders the request with that budget (ModelBackends.render(capped, prepared): pure sizing and payload, no I/O; its pre-flight of decision 38 B may refuse it too) and reserves the most it can cost (ModelBackends.worst_case: the input bound at the input price, or at the cache write price for a provider backend that may_write_cache, plus max_tokens at the output price: the bound max_tokens already keeps within the budget). Amended by #113 (decision 42's amendment (#113, live run)): the output part is output_attempts × max_tokens at the output price (a backend that may bill several outputs for one call, claude-cli: 4; 1 for the others), and max_tokens divides the step's remaining tokens_out and usd by output_attempts so it still fits. Another LlmBackend (a test fake) reserves the capped budget itself. Two runs of different pipelines therefore never both spend the last of a ceiling (tests/test_budgets.py has a two-process test whose day_spend waits between the read and the reservation: it fails with a deferred transaction). Not the apply lock: an LLM call can take minutes and must not block other runs' applies;
    • settling, right after the call (not with the step record: failed attempts cost money too and have no LlmCall): the reported usage (also of a failed call, LlmError.usage; zero for a backend's cached response; a cost above the reservation is logged, amounts only, and the row marked over_reservation); a refusal that reports no usage and means the provider processed nothing (budget_exceeded, backend_unavailable, skill_unavailable, invalid_request, auth_failed, rate_limited, overloaded) releases the reservation; any other failure without usage (a timeout, a lost connection, a cancellation) keeps the reservation as an estimated cost. Crash consistency: a process that dies between reserving and settling leaves its reserved row, which keeps counting for its day: a crash can over-count, never under-count (until the run is abandoned or recovered, see D). A store failure while reserving refuses the call (host_error); while settling it is logged (type only) and the reservation stays;
    • the ledger is the llm_usage table (migration 4): per attempt run_id, pipeline, step, attempt, alias, backend, model, state (reserved or settled), tokens in and out, cache read and write tokens, usd, priced, estimated, over_reservation, at (UTC) and day (local). The ledger outlives its runs (C);
    • horae usage [--pipeline P] [--since DATE] [--until DATE] [--by day|pipeline|model] [--json] groups the ledger by day and pipeline (or by day, pipeline, or backend and model), oldest first, with a TOTAL row; dates are local days, inclusive. Cells of calls of an unpriced alias are flagged *, calls in flight +, calls settled at their reservation ~ and calls that cost more than reserved !, with a footnote each; a cost under a ten-thousandth of a dollar shows as <$0.0001. --by model groups by backend, model and alias: a call that reached no provider has a null backend and model (- in the table). The store is opened read-only (decision 31 E: a missing store lists nothing, an older schema exits 1). Exit codes as decision 37: 0 listed, 1 configuration or store problem, 2 usage error (a malformed date, --since after --until, an unknown --by), 70 internal. --json prints {schema_version: 1, instance, by, pipeline, since, until, rows: [{<by keys>, calls, tokens_in, tokens_out, cache_read_tokens, cache_write_tokens, usd, unpriced_calls, in_flight_calls, estimated_calls, over_reservation_calls}], total};
    • (A) a minimum useful output: a call is refused (budget_exceeded, no request, nothing reserved) when what a daily ceiling leaves cannot buy MIN_OUTPUT_TOKENS = 256 output tokens, or fewer when the step's own budget buys fewer (min(256, what the step alone allows)): an answer cut short is worse than none. The refusal names the daily ceiling (the instance daily budget leaves ...), also when the pre-flight of decision 38 B refuses only because of it; a step whose own budget is too small is refused in the step's own words, as before;
    • (B) horae doctor warns when a usd ceiling (budgets.daily or budgets.pipelines.<name>) covers a pipeline whose llm alias has no price: its dollars are then unbounded, only tokens_out bounds it;
    • (C) the ledger lives independently of runs: run_id is nullable, ON DELETE SET NULL, so prune_runs never changes a day's totals; the ledger's own retention is Store.prune_usage(older_than) (settled rows of earlier local days; reserved rows are kept);
    • (D) abandon and recovery: abandon_run (the stale-run recovery calls it too, a compare-and-set on the run's status) turns the run's reserved rows into settled ones at their reservation, estimated = 1; horae usage tells calls in flight (+, in_flight_calls) from settled estimates (~, estimated_calls);
    • (E) dry runs are charged: they call the model. PLAN.md's "a dry run writes nothing" is about user data (decision 32 D5): Horae's own state, the run record and the usage ledger, is written;
    • (F) the day is stored at reservation time: a later timezone change does not rewrite history (past rows keep their day); local midnight and DST transitions follow the instance's time zone (a 23- or 25-hour day is one day);
    • provider prompt caches: a ProviderBackend declares may_write_cache (default False; anthropic is False, since Horae sends no cache_control; claude-cli is True, decision 42). For such a backend the input bound is priced at the cache write price (cache_write_per_mtok, else twice the input price) in both max_tokens and worst_case, so a settled call never exceeds its reservation; a backend without it that reports cache writes beyond the bound is flagged over_reservation (and logged). Likewise a ProviderBackend declares output_attempts (default 1; claude-cli is 4, #113): worst_case reserves that many outputs of max_tokens and max_tokens divides the step's budget by it; an unusable declared value (not an int of at least 1, or a bool) is backend_unavailable, a larger one is clamped to MAX_OUTPUT_ATTEMPTS (16);
    • untrusted usage (decision 40 K): a backend's floored usage (input at least a quarter of the request bytes, output at least a quarter of the output bytes but at most max_tokens) and its conservative charge (input_bound of the payload sent plus the whole max_tokens) stay within the reservation: ModelBackends.prepare sizes the input bound on the payload at the largest max_tokens the request allows (its tokens_out, capped by the alias' max_output_tokens), so the payload actually sent, with a max_tokens no larger, is never bigger. A count a provider reports above the bound but under 10**12 is kept (decision 40) and flagged over_reservation;
    • follow-ups: a monthly ceiling; provider-side spend limits (#63); calling prune_usage from a retention setting.

Provisional decisions (#29, pending maintainer review)

  1. The claude-cli backend with isolation (#29, the design note on #97; every recommendation accepted). One compatible v1 addition and the rules of horae.llm.backends.claude_cli. Not a legal assessment: personal headless use of claude -p on your own plan is PLAN.md's ⚠️ unverified reading (risk #70); this backend is "personal use under your plan's terms", and anthropic with an API key stays the recommended backend for published setups (ADR 0005).
    • contract change (optional): models.<alias>.command, an absolute path (no control characters, at most 1024 characters), accepted for backend: claude-cli only (the model and the JSON Schema both refuse it on another backend). Unset, claude is looked up on the fixed child PATH (/usr/local/bin:/usr/bin:/bin), never Horae's own PATH (answer 6). The native installer puts claude in ~/.local/bin, which is not on it: such setups set command. command must name the native binary: the npm package's claude is a #!/usr/bin/env node script, and node is usually not on the fixed PATH, so its --version fails; the error then says so (finding 9). Symlinks are resolved when the backend first runs it, so one run uses one release;
    • token mode only (answer 1): the alias' secret (a CLAUDE_CODE_OAUTH_TOKEN made with claude setup-token) is passed as CLAUDE_CODE_OAUTH_TOKEN, revealed into the child's mapping only. The contract keeps secret optional (a login mode may come later), but an alias without it is refused at the first call (backend_unavailable, nothing runs) and by horae doctor (an error). A secret that cannot be resolved, or holds a NUL, is auth_failed. Checked locally on 2.1.284: with an empty HOME and no token the CLI answers "Not logged in" (no ambient login, keychain included, is used);
    • render, then send (decision 38): the payload is {argv, stdin, max_tokens}; argv is fixed but for the model and the system prompt, stdin holds the untrusted input and the repair errors (fenced and escaped as for every backend; never in argv, which ps shows), max_tokens the output budget (passed as CLAUDE_CODE_MAX_OUTPUT_TOKENS, F; it also sizes the stdout cap, the usage floor and the conservative charge). send refuses any other payload (invalid_request): argv must have exactly the template's length and equal it item for item (a shorter or longer list is refused before any item is read, finding 4). The system prompt (SYSTEM_PREAMBLE, then the skill's trusted prompt) goes in --system-prompt, at most 64 KiB (invalid_request);
    • the flags (answer 3): -p --output-format json --model <model> --tools "" --strict-mcp-config --mcp-config {"mcpServers":{}} --setting-sources "" --no-session-persistence --disable-slash-commands --permission-mode dontAsk --max-turns 1 --system-prompt <system>. On 2.1.284 every flag is listed by claude --help but --max-turns (hidden), and every one is accepted by the parser (checked locally with an empty HOME: an unknown option fails with unknown option, these do not). Their behaviour is verified by the live test (tests/test_llm_claude_cli_live.py, @pytest.mark.live, skipped unless HORAE_LIVE_CLAUDE=1 and a token are given, never in CI): no tool runs and none is reported, user settings and their hooks are not loaded, user and project MCP servers do not start, no CLAUDE.md reaches the model (in the working directory, in HOME or in an ancestor of the workspace), the system prompt replaces the default one, no transcript or memory is written, no ambient login is used, the output limit is honoured. Each negative assertion has a positive control (finding 2): the same source with the one flag or switch that removes it turned back on must fire its canary first, else the test fails as broken for that release. (E) merge gate, not yet run live: the maintainer runs the live test once and pastes its output into #105's body before the flag set is final and the PR merges. --bare, --restricted and --safe-mode are not in argv (B): --bare's help says OAuth and the keychain are never read under it, which seems to exclude token auth; the live test prints what each does with the token (evaluation only) and one is adopted only once a live run shows it keeps token auth;
    • the environment: exactly PATH (the fixed one), HOME and TMPDIR (fresh empty per-call directories, 0700), LANG=C.UTF-8, TZ=UTC, DISABLE_AUTOUPDATER=1, DISABLE_TELEMETRY=1, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1, CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 and CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 (B), GIT_CEILING_DIRECTORIES (the workspace root, C), CLAUDE_CODE_MAX_OUTPUT_TOKENS (the call's max_tokens, F; not for the version check) and the token; nothing is inherited (ANTHROPIC_*, *_PROXY, NODE_OPTIONS, CLAUDE_CONFIG_DIR never reach it), built on the plugin host's base_env. To verify live: that the switches stop auto-update, telemetry and non-essential traffic on the pinned release (not checkable from the test: no network capture), that CLAUDE_CODE_DISABLE_CLAUDE_MDS and CLAUDE_CODE_DISABLE_AUTO_MEMORY do what their names say (the CLAUDE.md and memory live tests), and that CLAUDE_CODE_MAX_OUTPUT_TOKENS bounds the output (its live test; a reported output_tokens above max_tokens is output_invalid anyway, see the result);
    • the process (the plugin host's posture, decision 35): an argument list (no shell), the working directory an empty per-call directory, umask 077, a new session (its own process group), the per-call directories removed afterwards, also when the caller cancels the call (the group is killed first; finding 10). The step's timeout, then SIGTERM to the group and SIGKILL 2 s later (timeout, no usage: the ledger keeps the reservation as an estimate); stdout at most response_cap(max_tokens) bytes (1 to 8 MiB, the HTTP backends' body cap, T33; output_invalid, charged conservatively, the group killed at once; finding 7); stderr captured head and tail (64 KiB), its tail drained for at most 1 s after the exit before the reader stops (finding 8), and redacted with every resolved secret before it reaches an LlmError;
    • (C) the workspace: each call's home, tmp and cwd are in a fresh directory under <state_dir>/llm-runs (Horae-owned, created 0700, refused when it is a symlink or not this user's, made 0700 when looser), not the system temporary directory, which other users share; GIT_CEILING_DIRECTORIES is that root, so git finds no repository above it (the instance is often one). The factory receives it through horae.llm.backends.model_backends(work_dir=...), which horae.runner.open_ports calls with <state_dir>/llm-runs; a backend built without one (a test, a library use, horae doctor's version check, which writes nothing in the state directory) falls back to a fresh 0700 directory in the system temporary directory. A CLAUDE.md in the state directory or the instance is an ancestor of the working directory: B's switch and --setting-sources "" keep it out (live-tested with a control);
    • (D) managed settings: administrator-managed settings (/etc/claude-code/ managed-settings.json and managed-mcp.json on Linux, the same names under /Library/Application Support/ClaudeCode/ on macOS) apply to every claude run and no flag turns them off: they can add hooks, an environment and MCP servers. horae doctor warns when one of them exists (by name; their contents are never read). They, and remote-managed settings (pushed by an organisation's admin console, not visible as a file), are an accepted residual of T11: they are set by the machine's administrator or the plan's organisation, both already trusted with the token;
    • the version pin (answers 2, 7): CLAUDE_CODE_VERSION_RANGE = ">=2.1.284,<2.2" (2.1.284 is the release checked). <command> --version runs once per backend (one per alias per run), in the same isolated environment without the token; its output must be X.Y.Z (Claude Code). Outside the range, or unreadable, the alias is backend_unavailable for the rest of the run and nothing is sent (when the command is a #! script whose interpreter is not on the fixed PATH, the message names the interpreter and says to point command at the native binary); horae doctor runs the same check (an error). Bumping the range needs the live test's output for the new release in the bump PR's body and the version in docs/security.md T11, and a re-verified retry count of a truncated output (OUTPUT_ATTEMPTS, the amendment below);
    • the result (answer 5): stdout must be UTF-8 and one JSON object (strict parsing) with type: "result". is_error (anything but false): api_error_status through the HTTP status table, error_max_turns → output_invalid, a result starting "Not logged in" → auth_failed, else host_error (no error_max_budget_usd mapping: Horae passes no --max-budget-usd, so it is dead code until it does; finding 11); the usage is attached only when the result reports spend (so a refusal releases its reservation, decision 41). A non-zero exit without a result is host_error. A success needs subtype: "success" (finding 5), num_turns: 1, no permission_denials, a stop reason other than tool_use or max_tokens, a reported output_tokens no larger than max_tokens (else the limit was not honoured: output_invalid with the usage as reported, the conservative choice, which the ledger flags over_reservation when it passes the reservation; finding 1), and a result that parses as one JSON value (no fence stripping; --json-schema is not used, schema validation is #31's); any other result is output_invalid with its usage. Messages are Horae's; the CLI's text never is;
    • usage and cost (answer 4): tokens from usage (input_tokens, output_tokens, cache reads and writes), floored as decision 40 K, charged conservatively when missing or unusable. total_cost_usd (a finite number from 0 to 10⁶, else ignored) is notional under a subscription but counts against the step and daily budgets: usd is the larger of it and the alias' price applied to the tokens, and priced is true when either is known. may_write_cache is true (decision 41: Claude Code caches by itself), so the input bound is priced at the cache write price. (A) price is required for a claude-cli alias an llm step uses: horae doctor reports its absence as an error (not a warning), and the backend refuses the first call without one (backend_unavailable, nothing runs), so every call has a dollar reservation before it is made (the notional total_cost_usd is known only after). A price under the plan's notional rates still bounds the call; the larger of the two settles it. Follow-up: pass the remaining step usd as --max-budget-usd (a second fence) once Completion carries it, with its error_max_budget_usd mapping;
    • conformance: claude-cli joins the backend-agnostic tests of tests/test_llm_backends_shared.py with a fake claude (tests/claude_cli_fake.py); the HTTP-only ones are skipped there with their reason;
    • the security review (on #105): eleven findings (numbered above where they changed a rule) and six provisional decisions, A (price required), B (the CLAUDE.md and auto-memory switches now; --bare / --restricted / --safe-mode only after a live run), C (the workspace under <state_dir>/llm-runs, GIT_CEILING_DIRECTORIES), D (doctor warns about managed settings; managed and remote-managed settings an accepted residual), E (the first live run with positive controls in the PR body is the merge gate) and F (CLAUDE_CODE_MAX_OUTPUT_TOKENS), pending the maintainer's review like the rest of this decision.
    • Amendment (#113, live run): the first live run against Claude Code 2.1.284 (the haiku alias) found three things the fake did not show; the rules above are amended as follows, and with them the whole live test passes (17 tests, every positive control fired). (1) Code fences. With Horae's system prompt the model answers ```json fenced JSON (also with thinking off), which the strict "one JSON value" rule refused. A result that is exactly one enclosing Markdown code fence (an optional json info string, any case, whitespace around it) around one JSON value is now accepted (claude_cli.unfenced): the opening line exactly three backticks and the info string (trailing spaces or tabs, LF or CRLF), the closing three backticks on a line of their own at the end; prose before or after it, two fences, a fence inside text, a one-line fence, ~~~ or four-backtick fences stay output_invalid. The parser is linear string operations, no regular expression (a backtracking pattern was quadratic on a whitespace-only result as large as the stdout cap, blocking the event loop; review of #113). SYSTEM_PREAMBLE is unchanged (it is shared by every backend and part of the LLM cache key). --json-schema (the CLI's structured output) was considered and rejected: it works through an internal StructuredOutput tool (num_turns: 2, stop_reason: "tool_use"), which breaks the one-turn, no-tool invariants. (2) Thinking. The model thinks by default: an {"ok": true} answer cost 126 output tokens (115 of them thinking) and, at a 64-token limit, took a hidden second turn. MAX_THINKING_TOKENS=0 joins the switches (B): 13 output tokens, thinking_tokens: 0, one turn, and max_tokens bounds the answer itself (live-tested with a control: without the switch, the same call thinks). (3) The output limit. An answer longer than max_tokens is not cut: Claude Code retries the truncated output on its own up to 3 times, then exits 1 with is_error, subtype: "success", no api_error_status, num_turns: 4 and output_tokens 4 × max_tokens (256 at 64). So one call can bill 4 outputs of max_tokens: a provider backend now declares output_attempts (1 when absent; an unusable declared value is backend_unavailable, one above MAX_OUTPUT_ATTEMPTS is clamped to it; claude-cli: OUTPUT_ATTEMPTS = 4), carried on PreparedRequest and RenderedRequest; worst_case (decision 41) reserves output_attempts × max_tokens output tokens, and max_tokens divides the step's remaining tokens_out and usd by it so that the reservation still fits the step's budget (a claude-cli step with tokens_out: 2000 gets max_tokens 500; the alias' max_output_tokens caps each output, not divided). So authors should size a step's tokens_out and usd for 4 outputs when its alias is claude-cli. The conservative charge and the stdout cap cover 4 outputs too. On a success the bound stays max_tokens (num_turns must be 1: one output). An is_error result with no HTTP status whose reported output_tokens is at least max_tokens, and that shows the CLI's own retry or limit handling (more than one turn or a success subtype; with neither it stays host_error), is now output_invalid ("the output was truncated at the limit", on the reported count, never the CLI's text); it was host_error. It is charged its reported usage, its output at least OUTPUT_ATTEMPTS × max_tokens when it took more than one turn (the CLI billed the retries even if a release reported only the last one). The live output-limit test also checks the reported output is at most 4 × max_tokens. The retry count is the CLI's behaviour, not a documented contract: bumping CLAUDE_CODE_VERSION_RANGE must re-verify it live (and change OUTPUT_ATTEMPTS if a release retries more or fewer times). The same run printed that --restricted and --safe-mode keep token auth (a success) and --bare does not ("Not logged in"); none is adopted (B: a separate decision).

Provisional decisions (#53, pending maintainer review)

  1. Secret redaction in logs and run records (#53, design note and maintainer answers on #100; security review findings and maintainer decisions on #106). (39 and 42 are taken by #27 and #29.) Contract change: none; a store migration (0005_secret_flags). The store's findings reuse the secret_in_output violation of decision 35 (so a replay leaves them out of the compared violations, as it does for the host's). Maintainer decisions (binding, on #106): the journalled after / actual_after bytes are exempt and flagged only for a secret new compared to before (C), and secrets under 8 bytes are refused (H). Provisional, pending maintainer review: B (identifiers exempt and flagged), E (every logger, warnings, exception hooks), F (secure_delete), G (key collisions). Rules of horae.secrets, the store, the engine, the LLM layer and the CLI:
    • A. one shared redactor and a process registry. Redactor, token, SecretInKey and the encodings of decision 35 C moved to horae.secrets.redact (re-exported by horae.plugins.host.redact); the log scrubber to horae.secrets.logs (re-exported by horae.plugins.host.logs). Every SecretResolver.resolve adds the secret to a process registry (remember; current() is a Redactor of every secret this process resolved, rebuilt when the set grows; it only grows, so a rotated value stays redacted). Instance.prime_redaction() resolves, for redaction only, every secret the instance names (secrets.refs, the secrets horae.lock grants, the model aliases' secret), skipping one that cannot be resolved; Runner.run and the CLI commands that read the instance call it first; those that read horae.yaml alone (runs, diff, usage, undo) prime the same names (horae.config.loader.redaction_names(config, lock), shared with the instance), reading horae.lock best effort (an absent or invalid lock adds nothing). A provider backend still resolves its own key lazily, through its own resolver. A JSON number whose json.dumps is a secret's value is a numeric match (pin: 12345678): the checks that refuse see it (Redactor.find), the host and the CLI redact it, the store flags it without changing its type;
    • B. what is redacted, and identifiers (provisional). Only free text is rewritten. Identifiers the system needs are exempt and flagged (kept as written, neither refused nor rewritten; a hit is a secret_in_output violation): run ids, pipeline names, timestamps, statuses, kinds, plugin names and refs, tokens, digests, the journal's target, applied_by and sink_identity, a task's fingerprint, source and target, notification keys, the usage ledger's alias, backend and model, a run's host, the pipeline definition. Rewriting them made the record invalid (a run refused for a secret that happened to equal a word of its own structure), broke undo (a redacted journal target no longer names the note) and replay. Only the LLM cache refuses. The free-text allowlist (horae.store._gate): step output, error.message, stderr, call params and intents; input params, data and intents; the intent payload fields content, heading, title, body; context.vars values; LLM request, response, intents, repair, schema_errors; violation details; the run's error; a task's title; an abandoned run's error. A pipeline definition holding a secret's value is not copied into the record (pipeline_definition is None; its parameters refuse the run at plan time);
    • C. the store's secret gate (answers 1–3), fail safe. Every table, just before writing, with the registry's redactor: free text redacted (JSON: string leaves and object keys), identifiers and numeric matches flagged (B). Refused (SecretRefused, an InvalidRow, nothing written, name only): an LLM cache entry holding a secret in any string, key or number (answer 3; callers treat it as "do not cache", Store.cache_put_safe, for #32), and, as a residual, a record or step that would no longer validate once its free text is redacted (a token longer than the room its field has left). The journalled after bytes and a sink's actual_after bytes: exempt, and flagged only when the secret is new (maintainer decision on #106): kept byte for byte (apply's mismatch check and undo depend on them); a hit is recorded only when the secret occurs more often than in the journalled before ("the store found secret X in the content Horae wrote to , not in the note before"), so a secret the user already had in their note is not flagged. Exempt (answer 2): the journalled before bytes and the bytes a forced undo overwrote, the user's own note, which undo restores byte for byte (docs/security.md T09). Every finding is logged (horae.store, names only) and kept in the secret_flags table, in the same transaction as the row that held it; save_run turns a run's findings (and those in the record itself) into secret_in_output violations, then deletes them, so a record saved by another Store or process still gets them; abandon_run deletes them (no record); when the violations would pass MAX_ITEMS, the rest is aggregated into one violation;
    • D. trusted inputs are refused (answer 4). The engine fails the run at plan time, before any call, params_invalid naming the secret only, when a template variable (horae run --var) or a rendered parameter holds the value (or a known encoding) of a resolved secret, in a string, an object key or as a number's whole value; the variable is redacted in the record's context. A skill's prompt or output schema holding one (in a string, an object key or as a number's whole value) is refused at plan time too: _plan loads the skill through the engine's SkillSource (#27, decision 39) and fails the run with params_invalid (<skill>: the prompt or output schema holds secret <NAME>) before any step runs. ModelBackends.prepare keeps the same check as a backstop (an engine given no SkillSource, a PromptSource that reads other files), before rendering, reserving or sending. params_invalid releases a ledger reservation;
    • E. logs, warnings, uncaught exceptions (provisional). horae.secrets.logs.install() (the CLI entry point, Runner.run, an opening PluginHost; idempotent) wraps the log record factory: every record of every logger (the root, asyncio, urllib3, py.warnings, uvicorn, openai, mcp... not a list of prefixes any more) is redacted when it is created (message formatted and redacted with the registry and every open host, args dropped, exc_info and stack_info replaced by the exception's type name), whatever handler sees it. It also calls logging.captureWarnings(True) and sets sys.excepthook and threading.excepthook to hooks that redact the report they print. The HTTP loggers are pinned to WARNING. The LLM layer: ModelBackends.send redacts what a provider backend returns (an LlmError's message and stderr, raised again as a new error with no __cause__ / __context__; the output, intents and schema errors; logged by name); the engine redacts an LlmError message from any LlmBackend before recording it. The pipeline digest and the cache key are computed on the real values (they are hashes);
    • F. deleted bytes (provisional). Every writable store connection (the main one and the heartbeat's) sets PRAGMA secure_delete = FAST, so a deleted or replaced row is zeroed where SQLite rewrites its page anyway. A database written before #53 can hold unredacted values in rows and free pages: docs/operations/retention-and-backups.md documents a one-off VACUUM;
    • G. key collisions (provisional). When redacting two keys of one JSON object gives the same text, the later one is renamed [REDACTED:NAME]#2 (#3...) and a violation says so: nothing is lost silently;
    • H. short secrets (maintainer decision on #106; supersedes decision 35 D). A declared secret shorter than 8 bytes of UTF-8 (MIN_SECRET_BYTES) is refused when it is resolved: SecretError "... is too short for reliable redaction (min 8 bytes)", never echoing the value. horae doctor reports it as an error; a plugin that declares it fails with secret_missing, a model alias with its backend's secret error (the run needing it is refused); priming skips it with a warning naming it (horae.secrets). The redactor has no short-secret case any more (Redactor raises ValueError if it is handed one), and the host no longer warns about one;
    • I. CLI output. Every command prints through horae.cli_output.echo, which redacts the text; to_json scrubs the document as data first (numbers too, so the JSON stays valid). horae.apply.render.safe redacts before it escapes control and invisible characters, and text is redacted before it is cut (an HTTP body at 200 characters, a run's error at 4096), so neither a secret holding such a character nor a secret cut in half slips through. An identifier holding a secret is printed redacted (B keeps it in the store, not on the terminal);
    • limits: unknown encodings are not recognised and only the leftmost match of two overlapping secrets is replaced (decision 35); the gate knows only the secrets this process resolved (primed from the instance); an 8-byte secret still matches inside unrelated text that contains it (the reason identifiers are flagged, not rewritten); a secret in an identifier is in the store (flagged), but not in the logs nor the CLI.

Provisional decisions (#31, pending maintainer review)

  1. Schema-validated output with one repair retry (#31). (42 is taken by #29.) Contract change: none (llm[].schema_valid, repair and schema_errors exist since decisions 21 and 33; validator_unavailable is a new step error kind, an ErrorKind string). Rules of horae.llm.validate, horae.llm._schema_errors and ModelBackends. A security review of the first implementation found 8 issues; review decisions A to F below are provisional, for the maintainer to confirm:

    • A. the validator is the default (review decision D): ModelBackends.validate defaults to horae.llm.validate.validate_output (imported lazily: horae.llm.validate imports horae.skills, which imports horae.llm.base), and so does horae.llm.backends.model_backends (what open_ports builds), so decision 38 G holds for every ModelBackends, not only the one the runner builds. The only opt-out is the explicit sentinel horae.llm.UNVALIDATED (test doubles of the backends). A Validator is called validate(output, schema, timeout_s=...) and may return an awaitable; a synchronous one (test doubles) runs inline;
    • B. what is validated: the provider's parsed output, before the reserved intents are split off, against the skill's full output schema (RenderedRequest.output_schema, the skill file; never the provider's transformed copy, which drops constraints: anthropic.transform_schema moves maxLength into a description, and the validator still reports /x: maxLength), with jsonschema's Draft202012Validator. Formats are annotations (draft 2020-12's default): asserting them would depend on optional packages (rfc3339-validator...), so the same output would be valid in one install and not in another. Then the reserved intents, when present, must be an array of objects. First, in the parent, the output re-serialised as decision 39 E bounds it (compact, ensure_ascii=False, UTF-8) must fit MAX_OUTPUT_BYTES; a larger one is the single repair error SIZE_ERROR (the model's fault) and never reaches the worker;
    • C. a killable, isolated worker: each validation runs in a fresh child process, awaited through asyncio pipes, so the event loop is never blocked:
    interpreter sys.executable -I -B horae/llm/_schema_errors.py (isolated: no PYTHON* variables, no user site, not the script's folder on sys.path; no bytecode written)
    environment empty (env={})
    descriptors stdin (the request) and stdout (the answer) pipes, stderr /dev/null, nothing else (close_fds)
    working directory /
    session its own (start_new_session): no signal of the terminal reaches it
    CPU RLIMIT_CPU of the timeout plus one second, set by the worker on itself
    memory RLIMIT_AS at MAX_WORKER_MEMORY (256 MiB; the worker is about 26 MiB once jsonschema is imported), RLIMIT_DATA where that cannot be set; macOS refuses both, so the ceiling is Linux only there (review decision A). An allocation past it is a MemoryError: exit status 3, WORKER_ERROR
    timeout min(VALIDATION_TIMEOUT_S, the attempt's remaining deadline - VALIDATION_MARGIN_S) (10 s and 0.5 s; the interpreter start included), then killed and reaped
    cancellation the awaiting task cancelled (the step's or the run's deadline): killed and reaped
    answer read with a bound: at most MAX_WORKER_OUTPUT + 1 bytes (64 KiB), a longer answer is not read and the worker is killed; it must be a JSON array of at most 16 strings of 1 to 200 characters

    Not a thread (it cannot be stopped) nor a process pool (one task cannot be killed without breaking the pool, and a forked pool inherits the parent's resolved secrets, descriptors and threads). The cost is one interpreter start, about 0.5 s with jsonschema, at most twice per llm step. The worker imports only the standard library and jsonschema (nothing of horae, no instance state). horae doctor checks, when a pipeline has an llm step, that sys.executable and the worker script exist and that a trivial validation, run exactly as above, gives the expected error (horae.llm.validate.worker_problem); - D. fail closed, and no repair for the validator's own failure (review decision C): a timeout (/: timeout: the output could not be validated in time), a worker that cannot start, exits non-zero or answers anything else (/: validator: the output could not be validated), an unusable schema (/: schema: ...) or an output that is not plain JSON (/: json: ...) is never a pass: validate_output raises, and ModelBackends raises LlmError("validator_unavailable", <that fixed message>, usage=<the attempt's usage>) (so does any exception of another validator: the validator failed (<type>)). It is not the model's fault, so no repair is made: the step degrades at once with kind validator_unavailable, its cost charged to the run and settled in the ledger (decision 41). No intent of the attempt is kept, as for any failed attempt; - E. repair errors carry no data: each error is <pointer>: <keyword>: <description>, where the pointer holds array indexes and property names the schema declares only (any other segment is *; at most 120 characters, cut on a segment), the keyword is the failing JSON Schema keyword (false for a false schema, invalid for an unlisted one) and the description is Horae's fixed wording, with at most a number or type names taken from the schema (trusted, the skill author's). Never an instance value, an excerpt of the output, an undeclared key, or jsonschema's own message (which quotes the value). The errors are de-duplicated, sorted in the natural order of their pointers (segment by segment, an index before a name, indexes by value: /b/2 before /b/10; then by keyword and description), at most MAX_ERRORS = 16 (the last one then says how many more there were) of at most 200 characters each; at most 1000 failures are examined. One output and one schema give one list, so a live run sends the same repair for the same output; a replay serves the recorded errors (horae.replay), so a later change of this order (or of the wording) changes no replay of a recorded run, but changes what a new run records. The provider backends still frame the errors as data inside <schema_errors> (decision 38). The repair attempt sends the same viewed input, prompt and schema plus these errors: nothing new; - F. an invalid output proposes nothing: when the validator reports errors, ModelBackends drops the output's intents whatever their shape (LlmResponse.intents is empty, so LlmCall.intents of an invalid attempt is []; a non-list intents is a schema error, no longer output_invalid). The engine (unchanged) routes and keeps nothing from an attempt with schema errors, makes exactly one repair attempt with the remaining step budget (and, through the ledger, the remaining daily allowance; decision 41), and after a second invalid output degrades the step (schema_invalid): no intent of the step enters the record, later steps are skipped, the run is degraded, which horae runs shows (and --status degraded lists); - G. a schema cannot make one validation exponential (review decision B): the loader caps the product of anyOf / oneOf branch counts along any path of the output schema, $refs followed (memoised per $ref), at MAX_COMBINATOR_FANOUT = 1024, else skill_invalid (decision 39 E, amended). An 18-level $defs chain that branches twice per level (2^18 paths) is refused; alternatives side by side (in properties, allOf) do not multiply. What the cap does not bound (an anyOf over a long array keeps every branch's errors for every item) the worker's memory ceiling does; - H. the deadline and the attempt's cost (review decision E): the validator is given what is left of the attempt's deadline less VALIDATION_MARGIN_S, so it times out (D: validator_unavailable, the usage charged) before the engine's own deadline cancels the step. Should the step or the run be cancelled during the validation all the same, the cancellation carries the attempt's usage (horae.engine.ports.attach_usage / attached_usage): the ledger settles with it (not with the reservation as an estimate) and the engine adds it to the run's cost; - I. jsonschema is pinned to one minor version (review decision F): `jsonschema

    =4.26,<4.27. Which outputs are valid, and which errors (keyword, path, order) a repair sends, depend on the validator's behaviour, so its version is part of the replay contract: the record holds the errors sent, and a new minor version is an explicit upgrade (with this decision's tests), not a silent change between installs; - **follow-ups**: a warm worker if the start-up cost matters (#29's CLI backend is slower anyway); a memory ceiling on macOS (none of itssetrlimit` limits applies); #51 (sandboxing plugins) may reuse the worker's isolation.

Provisional decisions (#32, pending maintainer review)

  1. The LLM cache and the $0 path (#32). Numbering: 44 is #31's (PR #108), opened in parallel. Neither is renumbered: whichever of the two merges second places the #31 section (44) before this one, so the list stays in order. A compatible v1 addition to horae.yaml and the rules of horae.runner._cache, the engine, horae undo and the new horae cache purge:

    • contract change (optional): horae.yaml cache: {ttl_s?, max_entries?}, integers; ttl_s 60 to 31622400 (366 days), default 604800 (7 days); max_entries 1 to 100000, default 1000. Not part of config_digest (decision 33 D3): it changes what is reused, never what a replay computes;
    • one source. The store's llm_cache table is the single source of reusable outputs for live runs; the runner no longer reads Store.last_accepted_llm (D2, decision 30), which stays for tools and tests. Migration 6 adds the index llm_cache_created (on created_at, which trimming orders by). A store upgraded from before #32 starts with an empty cache: its first run per input calls the model once;
    • two keys (G). The engine key (RunRecord.input_hash, unchanged: SHA-256 of the canonical JSON of the skill, the skill plugin's name, version and commit, the resolved model, the viewed input, and with a loaded skill its skill_version and skill_digest, decision 39) is what the run records and what replay and undo use. The stored key (StoreLlmCache.stored_key) is SHA-256 of {input_hash, alias, version}: alias is the step's model alias as horae.yaml declares it at the time, without secret and price and without unset fields (backend, model, base_url, structured_output, max_output_tokens, max_tokens_field, and a later field such as the claude-cli command), version is LLM_KEY_VERSION (horae.llm.backends._shared, bumped whenever SYSTEM_PREAMBLE or the request framing changes; a test pins the preamble's digest to it). So the same model name on another backend or endpoint, or with another output mode, is a miss; a new price is not. The entry's response is {output, intents, backend, model, skill_version, input_hash, run_id, created_at} (input_hash the engine key, run_id the producing run); its tokens_* and cost_usd are what producing it cost (both attempts), for information;
    engine key (input_hash) stored key (llm_cache.key)
    skill name, version, digest yes via input_hash
    skill plugin name, version, commit yes via input_hash
    resolved model name yes via input_hash, and in alias
    viewed input yes via input_hash
    alias backend, base_url, structured_output, max_output_tokens, max_tokens_field, command no yes
    alias secret, price no no
    LLM_KEY_VERSION (preamble, framing) no yes
    pipeline, act/notify bindings no no (re-checked on reuse, C)
    - the engine reads, the runner writes. execute(cache=LlmCache): the engine awaits
    cache.lookup(key, model_alias=..., output_schema=...) when previous does not match
    the key; a hit is reused exactly as D2 (no backend call, LlmCall with cached=True,
    zero usage and the request marker {skill, model, reused_input_hash, source_run},
    source_run the producing run; intents validated and routed again; a reuse whose
    intents no longer route is a miss; the same step and run statuses: noop when nothing
    is proposed). A hit names the alias' current backend and model (equal to the stored
    ones, since they are in the stored key, unless the alias is no longer declared). No
    backend call means no ledger row: a cached output is charged zero (decision 41). An
    exception from lookup, or an entry for another key, is a miss. A store error while
    reading, writing or purging is logged (type only) and never fails the run;
    rule when
    write (remember, after the record is saved) the run is ok or noop (H: not degraded, failed or undone), not a dry run (D); the llm step ok; its last call schema-valid with recorded intents; no call of the step a reuse (a hit never extends an entry); no resolved secret in the entry (cache_put_safe, decision 43); two processes writing one key: the last write wins
    read (lookup) not --no-cache; the entry exists, expires_at not passed and created_at within the current ttl_s (A); well-formed (else deleted); the full output (the output with its reserved intents put back) passes the skill's full output schema (F, else deleted); its intents still validate and route in this pipeline (C)
    delete expiry and max_entries at the start of each non-dry run (first in, first out); invalid on read (F); horae undo of a run (B); horae cache purge (E)
    - (A) bounded staleness. An entry is live for ttl_s from when it was produced (its
    expires_at, and also created_at against the current ttl_s at lookup: lowering
    ttl_s applies at once to every entry; raising it applies to entries written from then
    on). A hit does not extend it: an unchanged input asks the model again at most once per
    ttl_s (PLAN.md §2.2's "no LLM call when inputs unchanged" holds within that window).
    After expiry a non-deterministic model may answer differently, so an unchanged input may
    produce new intents and notifications once per ttl_s (appliers still deduplicate
    what is identical). At the start of every non-dry run, entries past ttl_s or their
    expires_at are deleted, then the oldest beyond max_entries (Store.cache_trim,
    first in, first out: a hit does not make an entry recent), best effort;
    - (B) undo invalidates. When horae undo marks a run undone, every entry for that
    run's engine key is deleted in the same store transaction (Store.cache_delete_input,
    which matches the input_hash the entries record, whatever alias they were stored
    under), also when the undone run was itself a cache hit: running the same input again
    asks the model instead of re-applying what was just undone. A partial undo (not every
    change undone) leaves the entry;
    - (C) cross-pipeline and cross-history reuse stays. Any earlier accepted output is
    reused, not only the last run's (input A, B, then A again makes two calls), across
    processes, and across pipelines that run the same skill, model alias and viewed input.
    This is safe because routing and bindings are re-checked on every reuse: an intent
    whose explicit target is bound differently in the other pipeline does not route, which
    is a miss (the model is called);
    - (D) dry runs read, never write. A dry run reuses a live entry (a preview costs
    nothing on unchanged input) but neither stores its output nor purges: a preview must
    not change what later real runs do;
    - (E) horae run --no-cache (debugging) skips the lookup: the model is called even on
    unchanged input, and its accepted output still replaces the entry (a fresh answer is a
    valid answer). Runner.run(cache=False) is the same. **`horae cache purge [--all
    --older-than DAYS] [--skill NAME] [--json]** deletes entries on demand (--skill`
    alone: all of that skill's): it opens the store writable but never creates it, takes no
    lock, prints how many entries were deleted and how many remain (`{schema_version,
    instance, all, older_than_days, skill, deleted, remaining}`); exit codes per decision
    37: 0 purged (possibly nothing), 1 configuration or store problem, 2 usage error
    (nothing selected, --all with --older-than), 70 internal;
    - (F) re-validated on read. A cached output is checked against the skill's full output
    schema at every lookup, by the validator of the backend path: #31's
    horae.llm.validate.validate_output (default_validator; the interim synchronous
    check_output is removed with #31, so no validation runs on the event loop), with its
    killable worker, CPU and memory ceilings, at most CACHE_VALIDATION_TIMEOUT_S (10 s),
    and the loader's fan-out cap on the schema (decision 44 C, G). An entry that fails, or
    that cannot be validated (fail closed; validator_unavailable on a cache read is a
    miss, never a degraded step: the model is then called), is a miss and is deleted.
    So an entry written before a validator existed, or tampered with in the store, is
    never reused unchecked;
    - replay stays exact. Replay never reads the store's cache: a run that reused an entry
    is replayed with that output as previous (recorded_previous, decision 33, which
    keeps source_run), so the replay takes the same path; a run that called the model is
    replayed from its tape;
    - follow-ups: a per-skill ttl_s; LRU instead of first in, first out if hit rates
    show it matters.

Decisions (#35, design note and maintainer answers on #99)

  1. The action guard on LLM proposals (#35). Numbering: 44 is #31's (PR #108), 45 #32's. No contract change: the run record's violations[].kind already has guard, and the step's error.kind is the free-form ErrorKind guard_violation. horae.engine.guard runs on every batch of intents the llm step proposes (fresh, previous or a cache hit), after schema validation and the permission check, before routing:
    • (1) per-type limits. A skill's intents: {type: max} (decision 39 F) caps the intents of each type per step; more is a guard violation (it was intent_rejected). A type the skill does not declare stays intent_rejected (a permission breach, the run fails);
    • (0) structurally conservative (security review): rather than chasing each obfuscation, the guard refuses whole classes of text the parsers it guards against could read differently: control and format characters, any non-trivial tag-like token, any link destination with whitespace or a backslash (rules 0a, 0b, 3, 5);
    • (0b) Markdown escapes. A renderer drops \ before ASCII punctuation, so the text it renders differs from the text as written ([x](java\script:…), <https\://…>). Every check also runs on a view with those escapes removed (after each entity-decoding pass), and the text is refused if any view fails. A backslash is refused outright inside a link destination, a reference definition and a tag-like token or autolink;
    • (0a) no control or format character. Any Cc character but \n (tab and carriage return included), any Cf character (zero-width, joiners, bidi controls, BOM, soft hyphen) and U+2028 / U+2029 refuse the text before any other scan, also when an entity decodes to one (h&#9;ttps:). Note text already refused lone CR and U+2028 / U+2029 (content_line_break); this extends it to all guarded text. A ZWJ emoji sequence is refused too (known cost);
    • (2) embeds are always refused, even when the URL is in the input (they fetch when the note renders, without a click): any ![ (Markdown and reference images, Obsidian ![[…]] embeds);
    • (3) tag-like tokens: an allowlist, exact form. Every < followed by a letter, /, ! or ? starts a tag-like token, up to its >. It is allowed only as exactly <name>, </name> or <name/> with a name of b i u s em strong code pre br hr p ul ol li blockquote h1–h6 kbd sup sub mark del (no attribute, no :, no space), or as an autolink: content up to > that urls reads as one URL with a scheme:// or a special scheme, and no whitespace, quote or = (the URL then goes through (4)). Everything else is refused: other tags (img, iframe, svg, a, div, span, custom elements…), any attribute (on*, style, background, poster, srcset, ping, href, so also url( and @import), <name:…> forms, comments, doctype, processing instructions and an unclosed <b. A denylist of embed tags, then an autolink exemption, were rejected in review;
    • (4) URLs. Backslashes are read as / first (https:/\host, \\host). A URL is a run (up to whitespace, <, > or a control character) starting at scheme: followed by / (any [a-z][a-z0-9+.-]*, whatever precedes it), at a scheme of http https ftp ws wss obsidian mailto javascript vbscript data file blob followed by any non-space character (ftp:host), at // at a token boundary (protocol-relative, not after a scheme character, : or /), or at www. at a word start. A URL with a refused scheme (javascript vbscript data file blob) is always refused. Every other URL (answer 3) must be an exact string extracted the same way from the viewed input (string values and object keys of what the model was shown), case-sensitive, after dropping at most 16 trailing punctuation characters (.,;:!?)]}'"*_~ and backtick) on either side. So a known URL may be copied, but never extended (…?q=<data>, …/<data>). A notify.push link must be exactly such a URL and fall under the entry's link_prefix (decision 30). A per-pipeline strict_links (only trusted parameters and link_prefix) is a follow-up;
    • (5) link destinations. After ]( (up to the next ), or the line end when there is none) and after a line's leading [label]: (not a [^footnote]:; up to the line end; container prefixes skipped, (H2)), leading spaces skipped: a destination holding any whitespace or backslash (so also a title, [x]( javascript :…) or a line break) or starting with a refused scheme (also inside <…>) is refused; its URLs go through (4). A refused scheme in prose (data: three items: colon then a space) is not a link in Markdown and passes;
    • fields scanned: note.* content and heading, task.create title and fingerprint, notify.push title, body and link, every string and object key of an http.post body. Targets bound by routing (path, http.post url) are not text;
    • robust parsing, bounded work. Every check runs on the text as written and on its HTML-entity-decoded forms (up to three passes: &#x3c;img, &amp;lt;img) and their Markdown-unescaped forms (0b), ASCII case-insensitively. Scans are linear (find loops that resume after each match, regular expressions without nested quantifiers, pointers to the next ), line end or whitespace reused while ahead); a test scans 1 MiB of hostile text per field, and a seeded fuzz (case flips, decimal and hex entities, Markdown escapes, controls and format characters inserted into embeds, script links and unknown URLs) never passes;
    • (answer 4) the whole step degrades. A violation records one Violation(kind="guard") and the step degraded with error.kind guard_violation: none of its intents is routed (also the valid ones), its output is not used, later steps are skipped, the run is degraded, and no input_hash is recorded (so the runner never caches it). The LLM call is recorded with its raw intents (replay and audit);
    • (answer 6) content-free detail. Violation.detail (= the step error's message, at most 512 characters) names only closed-set values: the proposer (skill:<name>), the intent type and position, the field and the kind of problem, e.g. skill:daily-brief/ rank proposed note.create #2 with an image or embed in `content`, never the URL, its host or the text. The same line is logged at warning (horae.engine);
    • reuse (decision 45). On a reuse, a guard violation is a cache miss: nothing of the entry is recorded (no violation) and the model is called. For a cache hit the engine awaits the cache's discard(key, model_alias=...) (a port member, (H4)); StoreLlmCache.discard deletes the entry (logged, store errors swallowed), so a poisoned entry is not looked up again. A refused previous (replay) is only a miss;
    • (answer 5) scope. LLM proposals only; collect and transform intents are not guarded in v1 (first-party plugins in the D tier, T04); hostile plugins are #52's;
    • fencing (design note C). The backends already fence the input: it is sent as JSON inside <input> tags with every < written < (horae.llm.backends._shared. escaped), and repair errors likewise inside <schema_errors>, so data can never close the fence (tests/test_llm_backends_shared.py). A per-call nonce adds nothing to that and would make requests non-deterministic, so none is added and LLM_KEY_VERSION is unchanged;
    • known limits: obfuscated URLs that are not links in Obsidian (hxxps://) pass; zero-width and other format characters are refused (0a); a URL the input brings may be copied (tenet 5 as written); a brief citing a new URL from the model's own knowledge is refused; being conservative, a Windows path (C:\x), a:/b, x<b and c (an unclosed tag-like token), a Markdown link title and a ZWJ emoji not in the input are refused too.
    • hardening round (provisional, pending maintainer review). Conservative: v1 protects the Obsidian rendering surface, not only CommonMark. In text bound for a note or a notification (every guarded field but http.post body), on every view:
    • (H1a) active code fences. A fence of three or more backticks or tildes, after any leading spaces (more than CommonMark's three too), blockquote > or list prefix, whose info string starts (case-insensitively, after spaces or {) with dataview, dataviewjs, templater, mermaid, js, javascript, html, button or query (ACTIVE_FENCES): Obsidian or a common plugin runs, queries or draws these instead of showing code. Other fences (python, none) pass;
    • (H1b) Templater and inline queries. <% and %> anywhere (Templater, inline script), `= and `$= (Dataview inline queries, their default prefixes);
    • (H1c) frontmatter. In a note intent's content (all three note.* types), a first non-blank line of three or more - (a frontmatter block can set cssclasses, aliases and plugin properties). This complements decision 32's note conventions (content_has_marker, content_line_break); a thematic break later in the text passes;
    • (H1d) Mermaid click. click <id> href, click <id> call or click <id> then a quote, at a line's content start or after a ;, anywhere (also outside a fence, although (H1a) already refuses a mermaid fence). A callback without a quote (click A cb) is not matched: it needs a Mermaid block, which (H1a) refuses;
    • (H1e) wikilinks. A [[…]] (up to ]] or the line end, alias included) holding :// or a refused scheme (javascript: …) is refused; plain internal wikilinks ([[Daily/2026-10-27|today]]) pass. Embeds ![[…]] stay refused by (2);
    • (H1f) obsidian: URIs must be in the input set like any URL (4); a miss is reported as its own kind (an obsidian URI not in the input), and the case-sensitive match means OBSIDIAN://… is refused unless written so in the input;
    • (H2) container prefixes before link definitions. Before a [label]:, any spaces and tabs, blockquote > and list markers (-, *, +, 1., 1), followed by a space, a tab or the line end) are skipped, repeatedly (> - [r]: javascript:x). A footnote definition [^x]: is not a link definition but gets no exemption: its text goes through the URL, embed and tag checks like any other text (an unknown URL in a footnote is refused);
    • (H3) entity decoding fails closed. When a fourth html.unescape would still change the text after the three allowed passes, the text is refused (too many levels of HTML entities): the guard never checks a text whose rendering it has not seen. Text with four or more nested &amp; levels is refused (known cost);
    • (H4) discard is part of the LlmCache port. LlmCache.discard(key, *, model_alias) is now a Protocol member, so mypy rejects a cache without it; horae.engine.NoDiscardCache is an abstract base whose discard is a documented no-op (a refused hit then stays a miss each lookup, never routed). The engine awaits it directly (exceptions still ignored). A refused previous (replay, decision 33; the D2 reuse of decision 30) is not a cache entry: it is only a miss and is left as is;
    • (H5) logging and source. Details and the warning line stay content-free. The guard's source must be skill: followed by the pipeline configuration's SkillRef (<namespace>/<skill>, pattern-checked, at most 128 characters); anything else is a ValueError (a programming error, never input or model text);
    • (H6) ADR 0002 keeps its accepted text; what #17 and #35 added after acceptance is a dated amendment at its end;
    • bounded work: the new scans are line loops and find loops that resume after each match (wikilinks reuse the next ]] and line end), plus one regular expression without nested quantifiers (click); a test scans 1 MiB per hostile shape.

Provisional decisions (#34, pending maintainer review)

  1. De-identification before a cloud model, and no secret in a request (#34, design note docs/design/0034-deidentification.md and the maintainer's answers on PR #98). Numbering: 46 is #35's (the action guard). Compatible v1 additions to horae.yaml and the run record, and the rules of horae.llm.deid, horae.llm.base, the engine and the cache:
    • (A) local or cloud, explicit. models.<alias>.local: true | false (optional, strict boolean). Unset: ollama is local, every other backend (anthropic, claude-cli, openai-compatible) is cloud (LOCAL_BACKENDS, ModelAlias.is_local); never inferred from base_url. horae doctor's price warning now applies to every cloud alias by this rule (replacing decision 40's CLOUD_BACKENDS): an openai-compatible alias with local: true is not warned, an ollama alias with local: false is. local joins the alias' part of the cache's stored key and config_digest only when set (an unset local is left out of both, so the digests of an instance that does not use it are unchanged and old runs replay without a "horae.yaml changed" error);
    • (B) what is declared. Field classes in the skill's input view (#27, decision 39: path: {class: person|email|phone|place|amount|free_text}, amount also buckets: [numbers]), plus an optional vocabulary: horae.yaml deidentification: {vocabulary: <file name>}, a file of secrets.dir (personal data: never in the instance repository) read like a secret file (SecretResolver.read_file: one path segment, a regular file of at most 64 KiB, opened once; not registered for redaction). Its format is one class: term per line (person, email, phone, place; # comments; 2 to 200 characters, no control character, at most 4096 terms); a plain format, not YAML, so no alias expansion and no parser echoing content. Errors name the line, never the term. horae doctor reports an unusable vocabulary as an error;
    • (C) the transforms (horae.llm.deid.pseudonymize, a pure function of the viewed input, the classes and the vocabulary): every scalar leaf and every object key under a person, email, phone or place field becomes [PERSON_1], [EMAIL_1], [PHONE_1], [PLACE_1] (a value over MAX_VALUE_CHARS, 1 KiB, is withheld as [PERSON], not reversible); an amount becomes a bucket label (<0, 50-200, >=1000; default bounds 0, 10, 100, 1000, 10000; [AMOUNT] for a value that is not a finite number), not reversible. Every other string of the viewed input and every object key (free_text fields and unclassed ones alike: provisional B below) is scanned for the known values: the vocabulary terms, the values of this input's token-class fields (so "Lunch with Bob" is covered when Bob is an attendee) and each name part of a person value or term (at least 3 letters, mapped to the whole name's pseudonym: provisional C), replaced by their pseudonym; a phone's last 9 digits with any [\s.\-()] separators and up to 4 digits of prefix; an amount's renderings (provisional D), replaced by its bucket label. Matching: the string is NFKC- normalized and stripped of format characters (zero-width, bidi controls, soft hyphen), cut into tokens (letter runs [^\W\d_]+, digit runs, white-space runs, other single characters), and compared token by token with the known values (letters case-folded on both sides, STRAUSS = Strauß; any white-space run, NBSP and ideographic space included, equals any other): a known value matches whole letter runs only (Alice in alice_smith, user_alice, alice123; not in Malice), leftmost then longest. A trie over the tokens, at most MAX_TERM_TOKENS (48) deep: linear in the text whatever the number of terms (600 KB and 4096 terms well under a second). A string in which nothing is found is sent byte-identical. Text of the input shaped like a pseudonym ([PERSON_1], any case, fullwidth brackets after NFKC) is first neutralized to (PERSON_1) (counted neutralized), so the model can never be handed a pseudonym that re-identification would turn into a real value. Two keys of one object that are the same once pseudonymized fail closed (deid_unavailable). A classed path under another classed path is refused (DeidError, a defence in depth: the skill contract already refuses overlapping view paths);
    • (D) stable per run, no key (maintainer answer 3). Pseudonyms are numbered per class in order of first occurrence: the classed leaves and keys in canonical order (sorted keys, array order), then the matches in scanned strings; the same value (the same tokens) keeps its pseudonym. The same input always gives byte-identical requests, so a replay or a cache hit recomputes the same mapping. Cross-run stability (keyed HMAC) is a later option. DEID_VERSION is 2 (the matching of the privacy review);
    • (E) where it runs and what is stored. The engine applies it (execute(deid=...), the horae.engine.ports.Deidentifier port, horae.llm.deid.Deidentifier built by the runner and by horae replay from horae.yaml), for a skill with classes and a cloud alias (on by default, no opt-out in v1: answer 7), because the engine is the one place that sees the three paths (a call, a cache hit, a replay). Order: input view → pseudonymize (in a worker thread, within the step's timeout_s) → LlmRequest (input pseudonymized, classified, deidentified = the summary) → ModelBackends renders (appends DEID_NOTE: copy placeholders verbatim) → T10 check → send → schema validation → the attempt is recorded in llm[] and its usage spent → re-identify the accepted output and raw intents (the growth is summed first, Pseudonyms.growth: past MAX_REIDENTIFIED_BYTES, 256 KiB, the step degrades with output_too_large and nothing is substituted; the call and its cost stay recorded) → the permission check, the action guard (decision 46) and routing, all on the re-identified intents and against the real viewed input (guard_for(viewed)): a URL or note link present in the real input matches, and no pseudonym reaches the guard's link and tag rules (they are put back first; an unresolved one is left as the model wrote it and judged as any other text). The mapping lives only in memory: llm[].response and llm[].intents are what the provider returned (pseudonymized), llm[].input_hash the hash of what was sent, llm[].request.deid {version, input_sha256, counts, unresolved} (a digest of what was sent, never one of the mapping or of a value, which could be guessed); the step output and the routed intents carry real values. The LLM cache stores the pseudonymized output (from llm[]) and the digest of what was sent (deid_input_sha256), re-identified on a hit; the usage ledger holds no data. A reused output (PreviousLlm: a cache hit, or a replay's recorded reuse, whose request.deid.input_sha256 is kept) is reused only when its deid_input_sha256 equals this run's de-identified digest (None on both sides without de-identification): otherwise a miss, and a replay reports a mismatch ("the de-identified input differs (vocabulary changed…)"). Both checks of ModelBackends (deid_required and T10) live in ModelBackends only: an engine given another LlmBackend (a test double, the replay tape) has neither, so the runner always wires ModelBackends. For #29 (claude-cli, PR #105): the subprocess' argv and stdin must be derived only from the decoded frozen body (RenderedRequest.body()), never from the Completion or the request, so the bytes checked are the bytes sent. As a backstop, ModelBackends.prepare refuses a classified request to a cloud alias that was not de-identified (deid_required, an engine given no policy); a policy that cannot de-identify (unreadable vocabulary) degrades the step (deid_unavailable) before anything is sent. Both are not billed;
    • (F) the cache key (decision 45 G). For a cloud alias, the stored key adds deid: {version, vocabulary} (DEID_VERSION, the vocabulary file's SHA-256, or "unavailable"), so another vocabulary or transform version is a miss and an entry is only re-identified with the mapping that made it; a local alias' key is unchanged. LLM_KEY_VERSION is not bumped (the preamble is unchanged; DEID_NOTE is part of a de-identified request only, and those keys changed anyway). Entries of cloud aliases written before #34 are therefore a miss once;
    • (G) unresolved pseudonyms are left and noted (answer 4): a pseudonym the input never issued, or a mangled one (Person 1, PERSON1, [person_1]), stays as the model wrote it and is listed in llm[].request.deid.unresolved (at most 16, 40 characters each); no repair retry. Re-identification puts back the original value's text (_text(value)): a string stays a string, also when it is exactly one pseudonym of a number (a phone given as a number comes back as "33612345678"), so the validated output keeps its types (finding 5);
    • (H) no secret in a request (T10, the #14 addition). ModelBackends.send scans the exact frozen body (RenderedRequest.body()) with the process registry (horae.secrets.redact.current()), primed once with every secret the instance declares (ModelBackends.redaction_names = Instance.redaction_names(), the #53 set: secrets.refs, the lockfile's plugin secrets, the aliases' secret), not only those this process resolved: the raw bytes and the decoded JSON (strings, object keys, whole numbers), every encoding of decision 43. For every backend, local ones too (a secret in a request is never legitimate, and a local endpoint may log it). A match raises secret_in_request naming the secrets (never a value; the log line gives only their count) before the provider backend is called: nothing is sent, the usage ledger releases the reservation (NOT_BILLED, decision 41), the step is degraded and the engine records a secret_in_request violation (run record v1, a compatible addition to violations[].kind: answer 6);
    • (I) after the privacy review (provisional, pending maintainer review). The maintainer's answers on PR #98 stand (1: explicit local:, never inferred from base_url; 2: classes in the input view plus a vocabulary in secrets.dir; 3: per run; 4: leave and note; 5: render then send; 6: a secret_in_request violation; 7: on by default). Provisional answers to the review's open questions:
    • A: local stays explicit and is never inferred; horae doctor warns when an ollama alias leaves local unset and its base_url host is neither loopback, private, single-label nor a local name (.localhost, .local, .lan, .internal, .home.arpa), or its model tag ends with -cloud;
    • B: once a skill declares any class, the known-value matcher runs over every string of the viewed input (not only free_text fields) and every object key;
    • C: each name part (at least 3 letters) of a person value or term is a term mapped to the same pseudonym as the whole name (privacy over meaning: [PERSON_1] for "Bob" is put back as "Bob Martin");
    • D: an amount's renderings (1234.56, 1234,56, 1,234.56, 1.234,56, 1 234,56, 1'234.56, the whole part 1234; at least 3 digits, not all zeros) in a string become its bucket label (not reversible, not a pseudonym; counted in amount); object keys under a token-class field become pseudonyms (and are put back by re-identification);
    • E: bucket bounds written by the skill are accepted as they are (skills are trusted code, reviewed with their plugin): a skill could choose narrow buckets that reveal an amount, as it could simply not classify the field;
    • F: the T10 check scans every secret the instance declares (the primed #53 registry), not only the ones this process resolved (see H);
    • G: input_hash (the engine's cache key, decision 47 E) stays an unsalted SHA-256 of the real viewed input: it is stored locally only (run record, cache), never sent, and a salt would break replay and the cache across processes; a dictionary attack on it needs the store, which holds the real outputs anyway;
    • (J) amendment: the secret check before de-identification (security review of PR #110). H scanned only the rendered request, after pseudonymization: a classed value or an amount rendering inside a secret (secret sk-live-alice-smith-1234567, classed person "Alice Smith") was rewritten, so the scan of the whole value no longer matched while the rest of the secret was sent (a parser differential). So:
    • the engine scans the real viewed input (its canonical JSON bytes, every encoding, and its strings, object keys and whole numbers: the same check as secrets_in) for every resolved or primed secret before it is pseudonymized, and before the LLM cache is consulted; a match degrades the step with secret_in_request and records the same violation (naming the secrets, never a value), nothing is sent and nothing is billed; horae eval (#36, decision 48) runs the same check (horae.engine.secrets_in_viewed) on each case's viewed input, offline and live, before de-identifying: the case is an error (secret_in_request) and nothing is rendered or sent;
    • ModelBackends.send keeps its check of the rendered bytes (defence in depth: the prompt, the schema and anything added when rendering);
    • belt and braces, the pseudonymizer replaces no known value, phone or amount rendering whose span in a scanned string overlaps a resolved secret, so a secret is never sent in part even if the engine's check were bypassed;
    • the engine's check sees the process registry, which the runner primes with every declared secret before a run (#53); a declared secret first resolved by ModelBackends (an engine used without the runner) is caught by the backend's check;
    • limits: matching misses nicknames, initials, typos and transliterations, and over-matches a known value that is also a common word; a value of more than 48 tokens is not looked for in text; values in unclassed fields that equal no known value are sent as they are (the input view stays the primary control);
    • follow-ups: per-instance pseudonyms by keyed HMAC; NER-assisted detection in free_text; de-identification of data sent to plugins.

Provisional decisions (#36, pending maintainer review)

  1. Skill evaluation harness: golden cases, recorded responses, horae eval (#36). Numbering: 46 is #35's, 47 is #34's (de-identification). Two new contracts, schemas/eval-case/v1.json (horae.contracts.evals.EvalCase) and schemas/eval-recorded/v1.json (RecordedResponse), and the rules of horae.evals and horae.cli_eval:
    • (A) where the cases live. Next to the skill, in its folder: skills/<namespace>/<skill>/evals/<case>.yaml (a case name is [a-z0-9][a-z0-9_-]{0,63}, at most 256 cases) and evals/recorded/<backend>/<case>.json (one recording per backend, <backend> one of the models.<alias>.backend names). The skill loader ignores evals/, so the cases do not change the skill's digest. Every eval file is opened O_NOFOLLOW (a link is refused), must be a regular file, and is size-bounded (256 KiB a case, 512 KiB a recording); the folders must be real directories;
    • (B) a case has schema_version: 1, the step input before the input view (plain JSON: a YAML date must be quoted), optional description, targets (the routed path or url of each target-bound intent type, which a pipeline's act entries bind in a run; a note type without one gets Evals/<case>.md), budget (a live call's; default {usd: 0.05, tokens_out: 1024}) and expect: schema_valid (default true), the exact output (without its reserved intents), assertions (each a JSON pointer, RFC 6901, into {"output": ..., "intents": [...]} with exactly one of equals, length, contains (a substring, or an array element), not_contains and matches (decision 64) and exists), the exact raw intents or intent_counts per type, and guard (pass, the default, or violation for a case that proves a hostile output is refused). Equality is canonical JSON equality;
    • (C) a recording is provider-agnostic (maintainer's preference): the parsed JSON output as the provider backend returned it (the reserved intents included), its usage and stop_reason, the concrete model, the skill's name, version and digest, and the SHA-256 of what was sent (request: the skill's prompt, the viewed input, the output schema: RenderedRequest.summary's digests). Never the provider's payload, headers or a secret. A recording whose skill digest or version, prompt, input or schema digest differs from the current one is stale: reported (stale: [skill, prompt, input, schema]), a warning, not a failure (the repository's own CI test refuses stale fixtures);
    • (D) offline is the run's path, minus routing. horae eval <skill>: the input view (Skill.view), the request rendered by the real provider backend of the alias (ModelBackends.render: prompt, viewed input, schema, max_tokens from the budget, its pre-flight), then the recorded result handed back by a provider backend whose render is the real one and whose send returns the recording, so ModelBackends.send's own path runs: the production validator (validate_output, the killable worker; a validator_unavailable is an error), the intents split off (an invalid output proposes nothing), the redaction. Then the intents' omitted targets are filled from targets, validate_intents checks them against the plugin's permissions.intents narrowed to the skill's, and the action guard (check_intents) runs with the viewed input as what the model was shown and the skill's per-type limits. Without --alias, each recorded backend is evaluated with a synthetic alias (the recorded model, a placeholder secret name and a .invalid endpoint, which render never uses; nothing is resolved or sent); --alias renders with that instance alias and only its backend's recordings. A backend without a factory (claude-cli today) is an error (backend_unavailable). No network, no secret, no cost: CI runs every skill's cases (tests/test_evals.py, over tests/fixtures/plugins and the built-in plugins);
    • (E) the skill comes from the instance's installed plugins (<instance>/plugins, checked against horae.lock, plugins_invalid 1) or, with --plugin-dir, a plugin folder or a folder of plugins (folders without plugin.yaml are skipped; see M); it is loaded as the engine loads it (load_skill with the plugin's permissions.intents, skill_invalid 1). An unknown skill is unknown_skill (3), a malformed name a usage error (2), an unknown --case unknown_case (3), an invalid case or recording eval_invalid (1), a skill without cases no_cases (1);
    • (F) --live spends money, explicitly, and records it (D1, review findings 1 to 4). It needs the instance (its alias and secret; --alias, required when the instance has more than one, unknown_alias 3). Every case is rendered first and the eval's worst case (the sum of ModelBackends.worst_case, what the usage ledger reserves) is shown on stderr. A cloud alias without a price (ModelAlias.is_local false, decision 47 A) is refused (unpriced_alias, 3) unless --allow-unpriced (D3); --max-usd must be a finite amount over 0 (usage, 2). The worst case must fit --max-usd and what the instance's budgets.daily has left today (Store.day_spend), else budget_exceeded (3), nothing sent. --max-usd is required unless a daily usd ceiling bounds the eval (a tokens_out-only ceiling does not bound the cost: usage, 2). Then --yes, or a confirmation on a terminal (refused: not_confirmed, 3; not a terminal without --yes: usage, 2), then the allowance is read again (it may have changed while the confirmation waited). Each case is sent once (no repair retry: the eval reports validity, it does not repair) with the alias' declared key, through a provider backend that keeps the raw result for --record. A report is written to <state_dir>/evals/<namespace>/<skill>/<UTC timestamp>.json (the --json document, with report set) and a .txt summary beside it;
    • (G) --record (D2, findings 6 and 12) needs --live and --plugin-dir (a plugin's own folder: never the instance's installed plugins, which horae.lock pins; usage, 2). It replaces the recording of each case whose live answer passes the case (so a case expecting schema_valid: false or guard: violation records the bad answer it proves is caught); any other answer is not written and the case says why (recorded_skipped). The output and stop reason are redacted with the process registry first (decision 43). A recording is written atomically and durably (finding 11): mkstemp in the backend folder (O_EXCL, random name, 0600), written, fsynced, chmod 0644, os.replaced, then the folder fsynced; a recording that cannot be written is reported on stderr and the eval goes on;
    • (H) results and exit codes (decision 37). Each case (per backend) is pass, fail (a check failed) or error (it could not be evaluated: no_recording, input_invalid, eval_invalid, deid_unavailable, case_failed, a backend or validator error). Exit 0 every case passed, 4 some failed, 1 some could not be evaluated, the report could not be written, or any problem above, 2 usage, 3 unknown or refused, 70 internal, 130 interrupted. --json: {schema_version, mode, skill, skill_version, skill_digest, plugin, alias, run, cases: [{case, backend, model, status, schema_valid, schema_errors, intents_error, guard (pass | violation | not_run), guard_detail, stale, checks: [{name, ok, message, diff}], usage, worst_case, recorded_diff, recorded_path, recorded_skipped, stop_reason, error}], summary: {cases, passed, failed, errors, stale, usage}, estimate, report, report_error, error} (error is eval_failed, eval_errors or interrupted, else null); a command error is {schema_version, error}. The report has its own version, EVAL_REPORT_SCHEMA_VERSION = 1 (finding 14), not the CLI error envelope's. Diffs are unified diffs of indented canonical JSON (sorted keys, ASCII), at most 400 lines; text output escapes untrusted characters (safe). Schema errors and guard details stay content-free (decisions 44 and 46);
    • (I) pack-daily-brief ships three cases for daily-brief/rank-and-word with anthropic recordings (synthetic): overdue-first (assertions, one note), tasks-only (exact output, no intent) and injected-embed (a recorded output that obeyed an injected image embed; the guard must refuse it). The fixture pack satisfies the issue's "used by pack-daily-brief" for now (D7): a real pack-daily-brief repository adopting the cases is future work. Rendering them for anthropic showed that the fixture's output schema could not be used for structured output (transform_schema needs a type beside enum and const): the fixture now declares "type": "string" there, and the loader requires it (D4);
    • (J) a live eval is a run of its own (D1). Under its own lock (<state_dir>/locks/_eval-<sha256 of the pipeline, 16 hex>.lock: another live eval of the skill is eval_busy, 3) the eval opens the store for writing (created when missing, as a run does), abandons a dead eval's running row (recover_pipeline), and, once the gate passed, begin_runs a row of pipeline eval:<skill> (a pipeline name never holds :; a skill name too long for the store's 64 characters keeps its start and ends with a digest). Each case is then sent through LedgerLlm.complete, like a run's llm step: prepared, reserved atomically against the daily ceilings inside BEGIN IMMEDIATE (MIN_OUTPUT_TOKENS floor; a ceiling another process spent since the pre-flight refuses the case, budget_exceeded, nothing sent), sent, then settled or released; each case is its own step of the row. Store.finish_bare_run then marks the row ok (every case sent) or failed (interrupted), with the cases' cost; the row never gets a run record. Migration 7 rebuilds the runs table so that a finished eval: row may have no record (its CHECK allows substr(pipeline, 1, 5) = 'eval:'). horae runs hides eval:* rows unless --all (or --pipeline eval:<skill>); horae usage and the daily ceilings count them like any other pipeline's;
    • (K) failures midway (finding 5). A case whose sending raises anything but a cancellation is an error result (case_failed, the exception's type only) and the next case is sent. Each result is kept as soon as it is known: an interruption (Ctrl-C) or a bug midway still finishes the run row (failed), settles what the ledger can (an interrupted call keeps its reservation, estimated), writes the report of the cases sent (error: interrupted), then exits 130 (or 70). A report that cannot be written is said on stderr and in report_error, the JSON document is still printed, and the exit code is at least 1;
    • (L) report files (finding 10). Each folder level under the state directory (evals/, the namespace, the skill) is created 0700 and must be a real directory (not a link); the .json and .txt are written 0600 to new temporary names (O_CREAT | O_EXCL | O_NOFOLLOW), fsynced, then renamed into place, the .txt first and the .json last; an existing report is never replaced;
    • (M) eval files (findings 7 and 13). Dotfiles (.DS_Store, editors' swap files, temporary recordings) in evals/, recorded/ and the backend folders are skipped. A case file whose name is not a case name, an invalid case and an invalid recording are error results of that case (eval_invalid, the file named), the other cases still run; --case must be a case name (usage, 2). With --plugin-dir, an invalid plugin.yaml of the folder itself is plugins_invalid (1); in a folder of plugins, a skill no valid manifest provides is plugins_invalid when some manifest is invalid (it may be that one's), else unknown_skill; two plugins providing the skill are refused (plugins_invalid);
    • (N) the judge shares the engine's rules (D5, findings 8 and 9). _Replay is kept (offline renders with the real backend and replays the recording), but a case fails (stop_reason check) when the recorded or live stop reason is a refusal or a truncation (horae.llm.backends.UNUSABLE_STOP_REASONS = REFUSAL_STOP_REASONS {refusal, content_filter} | TRUNCATION_STOP_REASONS {max_tokens, model_context_window_exceeded, length, model_length}, shared by the backends). The engine's fill_target(payload, binds) fills omitted targets (from the case's targets) and check_task_fingerprints(typed, shown) refuses a task.update_status of a task the model was not shown (intents_error), both used by _Run.propose and by the eval. A case also fails when its usage is over its budget (usage_within_budget). budget_from: <pipeline> (a case taking a pipeline's llm step budget) is not done: a follow-up;
    • (O) de-identification (decision 47). A classified skill's viewed input is pseudonymized for a cloud alias before it is rendered (offline and live, with the instance's policy when an instance is loaded, else the alias' own with no vocabulary), the request says so (classified, deidentified), and the output and intents are re-identified before they are judged, as a run does; a vocabulary that cannot be used is deid_unavailable and nothing is sent. A recording holds what the provider saw (the pseudonymized output), never the real values; offline, the same pseudonymization gives the same request digests (not stale);
    • D4 (amends decision 39 E): the skill loader requires a type beside enum / const; CI renders every fixture and built-in skill through every backend in FACTORIES (render only, never sent, tests/test_evals.py); horae doctor reports a schema a backend's structured output refuses, with the offending JSON pointer, and the Anthropic render's error now carries that pointer and its cause;
    • follow-ups: budget_from; a --repair live mode that exercises the repair retry; horae eval --all over every installed skill; a JSON Schema for the eval report (schemas/eval-report/v1.json); a real pack-daily-brief repository with its cases.

Provisional decisions (#39, pending maintainer review)

  1. The built-in scheduler, external triggers and push monitors (#39). Numbering: 48 is #36's; #38 and #42 may be adding decisions in parallel, so this number may move when they merge. Compatible v1 additions to the instance contract (scheduler.monitors, scheduler.max_concurrent, scheduler.misfire_grace_s), one new runtime dependency (cronsim) and one command (horae serve); no store migration.
    • A, cron library: cronsim (>=2.7,<3, pinned in uv.lock). Pure Python, no dependency, typed (py.typed), about 1,200 lines with its explain module, maintained by the author of Healthchecks.io, where it evaluates every check's schedule, so its daylight-saving behaviour is exercised in production. croniter was considered: larger, and it went through an end-of-life notice and a change of maintainers; APScheduler is a whole scheduler with its own job store and executors, more than needed (Horae has its run lock and store). cronsim also validates the fields (horae.config.cron.cron_problem): an expression the contract's shape accepts but that cannot fire (0 0 30 2 *, 61 * * * *) is a loader problem at trigger.cron (also in horae doctor).
    • B, time zone. A trigger is evaluated in its own timezone, else horae.yaml timezone (decision 13; UTC when neither is set); fire times are stored and reported in UTC. Daylight saving follows Debian cron, as cronsim implements it: a time in the skipped hour fires once at the first instant after the gap, a time in the repeated hour fires once (its first occurrence), and an expression whose hour field is * fires at every real occurrence (tests/test_scheduler.py, Europe/Paris in March and October).
    • C, mode. scheduler.mode (builtin by default) is overridden by the HORAE_SCHEDULER environment variable when it is set and not blank: builtin or external, matched without regard to case (External is external), anything else a configuration error (horae serve exits 1, horae doctor reports it). In external mode horae serve fires nothing (an external scheduler runs horae run <pipeline>, which is unaffected by the mode); the process still runs, for the HTTP API of #37.
    • D, missed runs and overlap. Missed fire times are skipped, never caught up: on start each pipeline waits for its first fire time after now, and a loop that wakes late (a suspended host) runs the fire time it waited for once, then the first one after now. The push monitor is what reports a missed run. A fire time while the pipeline's previous scheduled run is still running or waiting for a slot, or whose run finds the per-pipeline flock held (a manual horae run: PipelineLocked; a scheduled run takes the same lock as any run, decision 31), is skipped and recorded: a warning log line and the pipeline's skipped / last_skip / last_skip_reason (running, locked) in the scheduler state. A skipped fire time pings no monitor and writes no run row (the run in progress pings and records its own). A clock stepped back never fires the same fire time twice (the next one is after both the last one fired and now).
    • D2, misfire grace. A fire time that would start more than scheduler.misfire_grace_s late (default 3600, 1 s to 7 days), after a suspended host or while waiting for a slot (D3), is skipped and recorded (last_skip_reason: misfire), not run: a run long after its time is more surprising than a missed one, which the monitor reports.
    • D3, concurrency. Scheduled runs are serialised by default: scheduler.max_concurrent (1 to 16, default 1) runs at most at once. A fire time that finds no free slot waits, first in first out (state waiting), and starts when a run ends, unless it is then past its misfire grace (D2); a stop drops the waiting fire times. Interaction with the apply lock (decision 34): whatever max_concurrent is, two applies never overlap, since every run's apply holds the instance-wide apply lock and waits for it at most APPLY_LOCK_WAIT_S (30 s) before it fails apply_locked with nothing applied. With max_concurrent: 1 scheduled runs never wait on each other's applies (only on a manual horae run or horae undo); with more, runs proceed side by side and their applies queue on the lock, so a long apply can make another run fail apply_locked. Runs side by side share the store (SQLite in WAL mode, decision 36).
    • D4, isolation. A pipeline whose next fire time cannot be computed (an unknown time zone, a date out of range; the loader refuses what it can, but 0 0 29 2 * is valid and rare) logs an error naming the pipeline and the exception's type only, shows no next_fire, and retries after 1 min, doubling up to 1 h; the other pipelines and the runs in progress carry on.
    • E, the process: horae serve. The long-running entry point of a container (the name #37's HTTP API will share: one process). It runs horae.scheduler.Scheduler, whose state() (SchedulerState: mode, active, started_at, max_concurrent, and per pipeline cron, timezone, next_fire, last_fire, last_outcome, last_run_id, last_ping (ok, failed, skipped, none: no monitor), running, waiting, skipped, last_skip, last_skip_reason; to_dict() is JSON-ready, times as ...Z) is what /healthz will report. The state lives in memory: the skip counts and last_* fields start afresh on restart (persisting them is a follow-up). Scheduled runs run in the process, exactly as horae run runs them; a crashed run is logged with its run id and internal error (<type>), never the exception's message. The instance is loaded once: a change to horae.yaml, a pipeline or the lock needs a restart. horae serve has no --json (it is a process, not a report; horae cache purge has none either). The wall clock is re-read at least every 30 s while waiting, so a clock step or a suspend delays a fire time by at most that much.
    • E2, shutdown. The first SIGTERM or SIGINT stops every loop, drops the fire times waiting for a slot and cancels the runs in progress; a cancelled run stops as horae run does on SIGTERM (partial record saved failed; an apply in progress finished first and saved with its real status). The run is then reported with the status it was saved with (status and run id from the saved record, its monitor pinged accordingly: an apply that finished is ok and up); a run stopped before any record was saved is recorded cancelled (keeping its run id, if it began) and pings nothing: the monitor's own heartbeat window reports it. horae run follows the same rule for an interrupted run, and bounds that ping to 2 s. The command then exits 0 (a requested stop is the normal end of a server, unlike an interrupted horae run). A second signal stops waiting for the reports and pings (each up to 10 s): the runs are still awaited so that their records are saved (bounded by the runner's 5 s grace period, or for an apply by its sink calls' call_timeout_s), then the command exits 128 + that signal (130, 143), so a forced stop is visible. A container should be given at least 20 s to stop (compose stop_grace_period: 20s; Docker's default is 10 s), more when applies are long.
    • F, push monitors. scheduler.monitors.<pipeline>: {secret, kind}: the push URL is a secret (it carries the monitor's token), resolved like any other (decision 25) and added to the secrets the instance names, so it is primed for redaction (decision 43) and checked by horae doctor; a monitor for an unknown pipeline is a loader problem. kind: uptime-kuma (default) sets the status (up / down), msg (the outcome word) and ping (the run's duration in ms) query parameters; kind: healthchecks pings the URL for success and <url>/fail for a failure. up is a run ok, noop or degraded (a degraded run is up, as its exit code is 0); everything else is down (failed, timeout, lost, crashed, and a run that could not begin: plugins not matching the lock, a store, lock or I/O problem, the error kind as the message). Pinged after every run of the pipeline, scheduled or horae run, never for a dry run, a locked pipeline, or a run stopped before any record was saved (E2). horae doctor resolves the secret and checks it is a valid push URL with the ping's own validator, never echoing the value. The network rules are the LLM backends' (decisions 24, 40): the URL must be a BackendUrl (https:// anywhere, http:// only to loopback, private or single-label hosts, re-checked at connect time by LanOnlyNetwork), one GET, no retry, no redirect, trust_env=False, 10 s for the whole exchange, the body bounded at 64 KiB and unused. A failure (timeout, refused, non-2xx, unresolvable secret, invalid URL) is one warning in Horae's words, never the URL, response or exception message, and never changes the run's outcome or exit code; the --json document of horae run is unchanged.
    • Not done (follow-ups): skipped fire times and the last_* state are not persisted (lost on restart; a store table would need a migration); no reload of a changed instance without a restart; no catch-up option; no /start ping (Healthchecks) to measure durations on the monitor side; the push URL with Uptime Kuma's default query (?status=up&msg=OK&ping=) is redacted as a whole, so the rewritten URL is never logged by design rather than by redaction.

Provisional decisions (#42, pending maintainer review)

  1. The plugin SDK: Tasks-safe task titles and fingerprints (#42, review findings). Numbering: 49 is #39's, on its unmerged branch, so this takes 50. The SDK (sdk/, horae-sdk) is not a contract of the core, but its escaping is the T02 control (docs/security.md), so its rules are recorded here:
    • (A) the intent's title is the Tasks-safe form. horae_sdk.intents.task_create escapes the title (horae_sdk.tasks.escape_title), as the acceptance criterion of #42 asks ("intent builders escape"), and the 500-character cut of the Title contract happens after escaping. Sinks writing Tasks syntax still use tasks.task_line / task_line_for, which escape again (idempotent: unchanged). A sink for another target shows tasks.plain_text(title), for plain-text display only (renamed from unescape_title; never fed to a Markdown or Tasks target, and not an exact inverse). Follow-up: escape at the sink only and keep the plain title in the intent (the intent would then carry what the source said, and each sink would escape for its own syntax);
    • (B) builders are total on the title. A title with nothing printable left after escaping (only zero-width, bidi, controls or whitespace) becomes (untitled) (tasks.UNTITLED, escaped), so one hostile item never aborts a whole collect;
    • (C) escaping rules. Signifiers become uppercase-hex character references; Markdown and Obsidian punctuation gets a backslash; every rule that looks back looks at the last piece written, not the last character read (\:: gave a literal ::). :: keeps a backslash on its second colon. The second % of %% and = of == become &#x25; / &#x3D;: comments and highlights are Obsidian extensions, not CommonMark, nothing documents that a backslash neutralises them, and a reference leaves no %% / == in the line even for a parser that drops backslashes first (a reference is decoded only when rendering, after the syntax is parsed). Autolinks: the : of a URL scheme (a run of A-Z a-z 0-9 + . - holding a letter, followed by a non-space) and the . of a www. prefix get a backslash, so https://, obsidian://, javascript: and www. are not autolinked (10:30 and Re: x are left alone; a bare e-mail address is not changed). The cut never separates a combining mark, a variation selector or an emoji modifier from its character; it is not a full grapheme segmentation (no dependency for it): a regional-indicator flag may be split;
    • (D) idempotence trade-offs (no behaviour change): a backslash escape already in the title and a reference in the SDK's own form (uppercase hex, of a signifier, % or =) pass through and render as that character; any other reference (&amp;, lowercase hex) has its & escaped and renders literally;
    • (E) verification. sdk/tests/test_sdk_tasks.py ports the Tasks plugin's emoji and Dataview field regexes (with the optional U+FE0F), its tag regex and the Obsidian constructs, checks that they see every field of a hostile title and none of its escaped form, and a Hypothesis property over a hostile alphabet checks that no ::, %%, == or raw signifier survives. Obsidian itself is not run in CI: sdk/README.md ("Manual check in a real vault") is the checklist for a release that changes horae_sdk.tasks;
    • (F) fingerprints. intents.fingerprint(*parts) keeps the readable form (parts joined with :, other characters as -) when it is exact (every part non-empty and in A-Z a-z 0-9 . _ -, at most 128 characters), so clean fingerprints and the recordings using them are stable. Otherwise the readable form is lossy and attacker-collidable (a:b / a-b, Re: x! / Re: x?), so it is cut to 110 characters and followed by :: and 16 hex digits of the SHA-256 of the parts as a JSON array. An exact form never holds ::, so the two shapes cannot collide. task_create's fingerprint parameter is key (it shadowed the function);
    • (G) protocol limits in the SDK. A result with more than 256 intents (horae.intents.MAX_INTENTS) or a message over MAX_MESSAGE_BYTES minus MESSAGE_MARGIN is refused by the SDK before sending (a tool error, or a sink operation's output_too_large), with a plugin-side message; content from the core that is not base64 is output_invalid, the kind of the core's own sinks; an undeclared intent type is echoed cut to 40 characters;
    • (H) the test harness. Record mode (HORAE_SDK_RECORD=1, record=True) is refused when CI or GITHUB_ACTIONS is set, names each rewritten file on stderr, writes atomically and never through a symbolic link; replay works inside a running event loop (areplay, areplay_all); check refuses unknown expect keys;
    • (I) release. release-sdk.yml refuses a tag whose commit is not on main (git merge-base --is-ancestor), the pypi environment must be restricted to sdk-v* tags with required reviewers, and the build backend is pinned (hatchling==1.32.4, bumped by Renovate). PyPI attestations are not produced: uv publish 0.13.6 uploads existing .publish.attestation files but does not create them (follow-up: a Sigstore signing step). Coverage is gated at 85% for the core (src/horae) and the SDK separately, and the sdist no longer ships the tests (they need the core).

Provisional decisions (#37, pending maintainer review)

  1. The HTTP API: /healthz and the read-only /runs (#37). Three new runtime dependencies (fastapi, uvicorn and an explicit starlette>=1.9,<2, pinned in uv.lock, all older than the 7-day minimum release age), new options of horae serve (--host, --port, --allowed-host), one optional argument of Store.list_runs (before, a page cursor) and one of Store.open (immutable, E); no contract change, no store migration.
    • A, one process, one event loop. The API is a FastAPI application served by uvicorn's programmatic Server inside horae serve, in the scheduler's event loop (horae.api): /healthz reads the live Scheduler.state(), and there is one process to supervise. Horae binds the socket itself before anything starts (a port in use or a bad host is a configuration error, exit 1, bind_failed, Horae's message), and uvicorn's own signal handlers, log configuration, access log, Server header, proxy-header rewriting and lifespan are off: the redacting log record factory (decision 43) stays in place, and request logging is the proxy's job. FastAPI is imported by horae serve only. /runs and /runs/{id} are synchronous and run in the shared worker thread pool, so a store read never blocks the scheduler's loop. /healthz is asynchronous: its store check runs in a small executor of its own (two threads), so a pool busy with slow /runs requests never fails the health check and SQLite never runs on the loop; it reads Scheduler.state() on the event loop, the scheduler's own, so the snapshot never interleaves with the scheduler changing it (no worker thread reads the scheduler).
    • B, binding. --host (HORAE_HOST, default 127.0.0.1) and --port (HORAE_PORT, default 8080). The container image sets HORAE_HOST=0.0.0.0 so that the reverse proxy (Coolify's Traefik) can reach it on the container network; the port is EXPOSEd, never meant to be published. HORAE_HOST=:: listens on IPv6 only (IPV6_V6ONLY), so the image's IPv4 loopback HEALTHCHECK then fails: use 0.0.0.0 or override the check. The API has no authentication of its own: SSO is the proxy's middleware (PLAN §7, #41: only /act/ is exempt; /runs and /healthz require SSO). It must never be exposed without that proxy. The Docker network is trusted: a neighbour container on it can reach port 8080 directly and send any Host it likes (the Host check of G2 is a defence against browsers, not against neighbours), so #41's template must put Horae on a network shared only with the proxy.
    • C, /healthz. 200 when the store opens read-only at this Horae's schema version and the scheduler is active (SchedulerState.active) or its mode is external; 503 otherwise (also while horae serve stops). Body: schema_version (1), status (ok / unavailable), version, store (status ok / error, reason missing / schema_too_old / schema_too_new / unreadable or null, schema_version) and scheduler (SchedulerState.to_dict(), decision 49 E). No path, no configuration value beyond the scheduler state, no exception text. horae serve creates and migrates the store once at start, so a new instance is healthy before its first run (a failure there is a warning; /healthz then says error). The body stays this detailed (pipelines, cron expressions, fire times, outcomes): it is behind SSO (#41), and keeping neighbours off the network is #41's job (B), so a reduced unauthenticated body is not needed. Behind the SSO proxy an external monitor needs its own way in (a proxy rule for the monitor, or Uptime Kuma on the same network): an operator choice, not Horae's (#41).
    • D, /runs. GET /runs lists runs newest first (start time, then id) as horae runs --json shows them (horae.run_view.run_json, shared with the CLI: id, pipeline, status, stale, dry run, abandoned, times, duration, cost, error; never the run record, pid or host). Keyset pagination: limit (1 to 100, default 20) and an opaque cursor (next_cursor of the previous page, null on the last), stable while runs are added (a new run never shifts a page, unlike an offset); runs that share a start time stay in id order across pages, and a cursor is a position, so it still works when its run has been pruned. Only the exact cursor shape the API writes is accepted (canonical base64url of [<UTC isoformat time>, <run id>]); anything else, a time that would overflow included, is 400, never 500. Filters pipeline and status, which takes the same values as horae runs --status (run_view.RunStatusFilter: running, ok, noop, degraded, failed, undone; stale is a flag computed from the locks after the query, not a status, in either); live skill evals (eval:<skill>) only with all=true or their own pipeline, as in the CLI. GET /runs/{id} is one run, the same object (404 when unknown); it stays (a link to one run is what the dashboard and #38's messages need). Bad parameters are 400 invalid_request naming the parameter, never echoing its value. Only GET routes exist (405 otherwise); no slash redirect (/runs/ is 404).
    • E, read-only store access. Each request opens the store with Store.open(read_only=True, immutable=False) (decision 36): no migration, no WAL switch, query_only, and always plain mode=ro, a WAL reader with SQLite's locks and the shared -shm. The CLI's one-shot reads (horae runs) keep immutable=True, which opens the database immutable when there is no -wal file and so creates nothing. The API cannot: it reads in the scheduler's process, where a run's store writes and, on close, checkpoints into the main file at any moment, and an immutable connection takes no lock and trusts the file not to change, so such a read could be torn (the size of the WAL is no bound: a closing writer checkpoints whatever it holds). With plain mode=ro a reader never blocks the writes and sees only committed data, tested with a write transaction open and with a writer thread that checkpoints on every close while the API reads. The cost: a read with no writer active may leave an empty -wal and a 32 KiB -shm (the database file's permissions, no data); the next writer's close removes them (tested).
    • F, no secrets in responses. Every body, errors included, is redacted as data (scrub_data: strings, keys, numbers) and then as text with the process registry (decision 43), which horae serve primes with every secret the instance names; the store already redacts what it writes, so this is the second line. Error bodies are Horae's ({schema_version, error: {kind, message}}): an internal error shows its exception type only, a validation error the parameter's name only.
    • G, headers and surface. Every response from the app: Cache-Control: no-store, X-Content-Type-Options: nosniff, Content-Security-Policy: default-src 'none'; frame-ancestors 'none', Referrer-Policy: no-referrer, X-Frame-Options: DENY, Content-Type: application/json (uvicorn's own 400 for a request it cannot parse never reaches the app and has none). No CORS (no Access-Control-* header; a preflight is 405). The OpenAPI document and the docs pages are disabled, on every interface (not only off loopback): the API is three routes, documented here and in the README, and a schema endpoint would be one more thing to keep behind SSO.
    • G2, Host check (DNS rebinding; added after the security review of this branch). With the default loopback bind, a web page could point its own name at 127.0.0.1 and read /runs and /healthz from the user's browser (same origin for the page). So a request whose Host is not an allowed host is refused before any route runs: 400, {kind: invalid_host, message: "host not allowed (see HORAE_ALLOWED_HOSTS)"}, the host never echoed, with the security headers. Always allowed: localhost, 127.0.0.1, ::1 (any port; the container's HEALTHCHECK and a local client). Also allowed: each --allowed-host (HORAE_ALLOWED_HOSTS, space-separated): the proxy's public hostname, which Traefik forwards as Host; and the bind address itself when it is not a wildcard. An allowed host is a DNS name (_ allowed too: Docker service names) or an IP address, compared exactly after lower-casing and dropping a trailing dot: no wildcard, no port, no sub-domain matching (a bad value is a usage error, exit 2). A missing, malformed or repeated Host is refused. A wrong Host is visible, not refused at start: the loopback HEALTHCHECK stays green while every proxied request is refused, so horae serve logs a warning at start when it listens on a wildcard (0.0.0.0, ::) with no allowed host, naming HORAE_ALLOWED_HOSTS, and logs each refused Host value once (warning, horae.api; ascii()-escaped so no control or bidi character reaches the log, truncated to 64 characters, at most 32 distinct values then one line saying it stops, through the redacting record factory). It warns rather than refuses to start: a wildcard bind with loopback clients only is a valid setup. Allowed hosts are set on the command line (and the environment) only, not in horae.yaml: it is a property of the deployment, like --host, and needs no contract change; an api.allowed_hosts key is a follow-up if instance repos want it.
    • H, shutdown. The first SIGTERM / SIGINT stops the scheduler (decision 49 E2) and asks the server to stop: it closes its socket and waits up to 5 s for requests in progress. The command exits 0 once both have stopped; a second signal also forces the server. A server that ends on its own stops the scheduler and exits 70.
    • I, container. The image's default command is horae serve (it was --help; it stays serve), and its HEALTHCHECK asks /healthz over loopback with the standard library (python -c, urllib, no proxy): no curl or wget in the image. The check follows HORAE_PORT, not a --port flag: change the port with HORAE_PORT (a serve --port N command leaves the check asking 8080 and the container unhealthy). A container running another command (init, doctor, run) reports unhealthy, which is harmless for a one-off; one with HORAE_HOST set to :: or to a non-loopback address other than 0.0.0.0 must override the check. scripts/smoke-image.sh checks that horae serve becomes healthy with the image's own check, serves /runs, warns about HORAE_ALLOWED_HOSTS and exits 0 on docker stop; under emulation (QEMU) it waits longer (SMOKE_SERVE_WAIT_S, SMOKE_PROBE_TIMEOUT_S, SMOKE_STOP_S).
    • J, dependencies. starlette is a direct dependency with its own range (>=1.9,<2): the API relies on Starlette's handler behaviour (exception handlers, middleware order, redirect_slashes), so a change of major version must be a deliberate bump, not a side effect of a FastAPI update.
    • Not done (follow-ups): /act (#38), api.allowed_hosts in horae.yaml; no ETag or conditional requests; no metrics endpoint. Done in #41: the SSO-exemption test against the rendered templates (tests/test_deploy_templates.py, docs/security.md T15) and the network of B: plain compose, one shared only with Traefik; the Coolify template, the resource's own network, which Coolify connects the proxy to and no other app joins (never a shared traefik-network; docs/operations/coolify.md, "The network").

Provisional decisions (#122, pending maintainer review)

  1. task.create takes an optional link (#122). A compatible v1 addition: one optional field of task.create (TaskCreate.link, the TaskLink type), mirrored in intent/v1.json and run-record/v1.json, and an optional link_prefix parameter on a mode: tasks act entry; no store migration. It lets a task created from an external item (a pull request, a calendar event) carry a clickable link, which the escaped title never can (decision 50).
    • A, the shape: https:// only. ^https://[^F/?#@\\%\[\]]+([/?#][^F\\]*)?$, at most 2048 characters, where F (TASK_LINK_FORBIDDEN, written as \u escapes) is every Basic Multilingual Plane character of the Unicode categories Cc, Cf, Zs, Zl and Zp: the notify.push link (decision 7) restricted to https, with a non-empty authority that holds no @ (no user info, so no https://good@evil reading as good), % or brackets, and no backslash anywhere (browsers read \ as / in an https URL). No control, format (bidi, zero-width, soft hyphen), space or separator character may appear anywhere, nor a lone surrogate: the model (_check_task_link) and the SDK also check the categories with unicodedata, which covers the supplementary planes (tag characters) that one ECMA-262, Rust and Python pattern cannot. The host is a name, never an IP literal: bracketed IPv6 fails the pattern, and a host whose last label (one trailing dot dropped, after NFKC) is decimal digits or 0x hex is what a browser reads as IPv4 (127.0.0.1, 127.1, 0x7f.1, 2130706433, full-width digits), refused by the model and the SDK (the use case is a named web host; a link_prefix on an IP is refused the same way). The SDK keeps a copy of the pattern, and a shared test checks it equals the core's and that both refuse every code point of those categories. No obsidian://, unlike notify.push: a notification link opens the vault from a phone, while a task link is written into a note, where an obsidian:// URI is an action (new, open with a command plugin) one click away, and the use case (an external item) is a web page. http://, javascript:, data: and every other scheme are refused by the schema. Loosening it later (another scheme) is compatible.
    • B, routing binds it (decision 30). A task.create with a link is taken only by a mode: tasks entry with a trusted link_prefix the link falls under, by the same rule and the same code as notify.push (_check_link_prefix, _link_under: an https:// prefix with a host, no user info, query or fragment and a clean path ending in /; same scheme, the same authority, a clean rest of path, own query and fragment allowed). The authority of an https link and prefix is compared as a DNS origin: the host case-insensitively, one trailing dot ignored, an explicit :443 equal to no port, and no user info (GitHub.com, github.com:443 and github.com. fall under https://github.com/my-org/); the path stays case-sensitive (/My-Org/ is not under /my-org/), as do an obsidian:// netloc (compared exactly) and the rest of the rule. _link_under is shared, so this applies to notify.push https links too (decision 30 compared the netloc exactly; it only accepts more spellings of the same origin). When a tasks entry would take the task but for its link, the intent_unrouted message says task link not under a trusted link_prefix (a fixed text, no URL). Without link_prefix, a task with a link is never routed (intent_unrouted), as for notify.push: deny by default, so a pipeline names the hosts its tasks may point at (link_prefix: https://github.com/my-org/). A task without a link needs no prefix, so existing pipelines are unchanged. An obsidian:// or otherwise invalid link_prefix on a tasks entry, or a link_prefix on an act entry of any other mode, is params_invalid (it used to be inert metadata there; no pipeline used it). Upgrading a source: once a source (or skill) sends link, every mode: tasks entry that receives its tasks needs a link_prefix covering those links, or the step fails at run time with intent_unrouted (horae doctor does not inspect act entries, and cannot know what a source will send). The entry's parameters, link_prefix included, are recorded in the act step's output and passed to the sink plugin as the params of its apply call (SinkCall.params), as for every entry parameter: a Tasks sink must accept, and may ignore, link_prefix.
    • C, the action guard. A task.create link proposed by an LLM skill must be exactly a URL of the viewed input, like a notify.push link (decision 46), on top of the prefix; a refusal degrades the step. Source and transform proposals are not guarded (first-party plugins, #52), so the prefix is what binds them.
    • D, no v2. The field is optional and additionalProperties: false only ever refused it: every v1 intent, run record and pipeline stays valid, and a v1 consumer that does not know the field never receives it unless a pipeline opts in with link_prefix (an applier built before this change would ignore it). Per "Versioning", that is a compatible addition in v1.
    • E, the sink renders it inert. The intent keeps the link exactly as proposed (routing and the guard compare it as written). horae_sdk.tasks.task_line (and task_line_for) writes it right after the escaped title and before the date fields, as [link](<destination>): a fixed label, never text from the title or the URL; the title cannot open, close or fake a link (its brackets and parentheses are escaped, decision 50). link_destination percent-encodes (UTF-8) everything outside A-Z a-z 0-9 - . _ ~ : / ? # @ ! & ' * + , ; = %: so ( ) [ ] < >, backtick, $, ", { } | ^ and every non-ASCII character (no signifier, bidi or zero-width character reaches the line); a % that starts no escape becomes %25 (no %%); the & of an HTML entity becomes %26 (Markdown decodes entities in a destination, and &#x2E;&#x2E; would otherwise become .. after routing checked the path); the second : of :: and = of == become %3A / %3D (no Dataview field, no highlight). It is idempotent and percent-decodes to the same string as the link does. The ported Tasks and Dataview regexes see no field in the link and the escaped title (property tests over a hostile alphabet and arbitrary text). A destination longer than 4096 characters is left out (MAX_DESTINATION): a non-ASCII character takes up to 12 once encoded, so a 2048-character link could reach about 24 KiB, past plugin-obsidian's 16 KiB analysis cap for a line; the line is then written without the link, and nothing of it is returned or logged. The core's dry-run diff shows the link as plain text in angle brackets ((link <url>), terminal-escaped), so a ) in the URL cannot read as the end of the parenthesis.
    • F, the SDK. intents.task_create(..., link=None) checks the same shape (tasks.is_task_link); horae-sdk goes to 0.2.0 for the link, then 0.3.0 for the reminder order and the block id (decision 53; not yet published; there is no changelog file, the README's "Task links" section and these decisions are the notes).
    • Order and block id (#127, decision 53). The link comes first, then the ⏰ HH:MM reminder, then the Tasks date fields, so a trailing ⏰ cannot hide 📅 (a line written as 📅 d ⏰ t by SDK 0.2.0 is read but not rewritten); with a fingerprint the line ends with the ^h- block id, which a sink's index must treat as collidable (48 bits) and fail closed on.
    • Not done (follow-ups): the Obsidian plugin's own Tasks writer must render the link the same way (link_destination) before it may list task.create links as supported; task.update_status takes no link.

Provisional decisions (#127, pending maintainer review)

  1. The SDK writes the reminder before the Tasks fields, and a block id (#127). This number is provisional and may be renumbered against other open PRs.
    • A, the order. horae_sdk.tasks.task_line writes - [ ] <title> ⏰ HH:MM 📅 date (SDK 0.3.0), where 0.2.0 wrote 📅 date ⏰ HH:MM. Tasks reads fields from the end of the line and stops at a signifier it does not know; a trailing ⏰ hid the due date from it. Readers must accept both orders (plugin-obsidian's parser does).
    • B, old lines are not rewritten (decision). Lines written in the old order keep it; their due date stays invisible to Tasks until the line is edited.
    • C, the block id. With fingerprint (task_line_for(..., block_id=True)), the line ends with ^h- and 12 hex digits of the SHA-256 of the fingerprint. The prefix makes it unlikely to collide with a user's block ids. 48 bits can collide between two fingerprints (about 2e-5 at 100,000 tasks): a sink's block-id to fingerprint index must detect a second fingerprint mapping to the same id and fail closed (refuse) rather than overwrite. A non-string or invalid fingerprint is a ValueError.
    • D, the SDK version. horae-sdk is 0.3.0.

Decisions (#38, design note and maintainer answers on #115)

  1. Signed single-use action links, /act/<token> (#38, the design note docs/design/0038-act-links.md and the maintainer's answers on PR #115: all ten recommendations accepted). A compatible v1 addition to the intent contract (notify.push.actions) and to horae.yaml (http), store migration 8, one core secret (HORAE_ACT_KEY), two routes. A tap on a notification button changes one task in one predefined way, once, within 24 h, without SSO: the token is the only credential.
    • A, what a link can do. A closed set of kinds, never an intent document: task.done (task.update_status {status: done}) and task.snooze ({status: snoozed, until}, until computed by the core when the button is pressed: 1h, 3h, or tomorrow at 09:00 in the instance time zone). notify.push, http.post and note.* can never be reached. Adding a kind is a core change (ADR 0002).
    • B, the contract. notify.push gains an optional actions: 1 to 3 (ntfy's limit) {kind, task, duration?, label?}; task a fingerprint, duration required for task.snooze and only there. The proposer never writes a URL, nor the button's text: label is deprecated and ignored (still accepted, one line of at most 64 characters, so proposals written with it stay valid; review decision 2 on PR #115): the core labels each button from its kind and duration (horae.api.act.BUTTON_LABELS: Done, Snooze 1h, Snooze 3h, Tomorrow), so a button cannot say something other than what its link does. Like a task.update_status target, every button's task must appear in the data the run collected (rule 4 of horae.engine.executor, maintainer decision 2), and the action guard scans the labels of an LLM proposal. A notification without actions keeps the dedupe_key it had before the field existed (the field is left out of the key when absent), so an upgrade re-sends nothing.
    • C, minting. Only the core holds the key. When the apply phase sends a notify.push with actions, horae.api.act.LinkMinter mints one link per action whose task is in the store's task index and open (an unknown, done or cancelled task's button is left out; so is a task.done button for a recurring task, a snooze stays allowed, review decision 3: whether a task repeats comes from the index's recurring flag and from the run's collected data, any object with a boolean recurring naming the fingerprint in fingerprint, source_fingerprint, task or key, e.g. obsidian.open_tasks, which also updates the flag) and passes them to the notifier with the call: SinkCall.actions, sent to an MCP notifier's <ns>.apply as actions: [{"action": "http", "label", "url", "method": "POST"}] (ntfy http actions, so plugin-ntfy#4 can forward them as they are; horae_sdk.ApplyRequest.actions in the SDK), only when there are some. A notifier renders these, never the intent's own actions, and treats each URL as a credential (sent to the push service only, never logged). The URL is http.public_url + /act/ + the token: the base comes from horae.yaml only, never from a request's Host or X-Forwarded-Host (normalised: a :443 in http.public_url is dropped, as a browser's Origin drops it). Without the key, http.public_url or a route (F) whose plugin may apply task.update_status (the runner checks route_permitted as horae serve does), nothing is minted and the notification is sent without buttons (logged once per process). Daily-note links are a follow-up (maintainer decision 3).
    • D, the token (horae.api.act._token, maintainer decision 4: a signed payload, not a server-side row). One base64url segment without padding, payload || tag: ver(1) kid(4) kind(1) exp(8, Unix s, big-endian) nonce(16) state(8) dur(1) fp_len(1) fingerprint(1..128), tag = HMAC-SHA256(key, "horae-act/v1\0" || payload) (32 bytes, not truncated); 73 to 200 bytes, 98 to 267 characters (^[A-Za-z0-9_-]{98,267}$). state is the first 8 bytes of SHA-256 over the task's (status, due, snoozed_until) at mint time (maintainer decision 10). It carries no secret, URL or title; it is signed, not encrypted (whoever sees the link can read the fingerprint). Decoding is strict and total: one spelling per token (re-encoding must give the same string), the tag checked with hmac.compare_digest before any field, then the version, key id, a known kind, a duration that fits it, the fingerprint's length and alphabet; a string that is not even well-formed pays for one MAC over a buffer of the maximum payload size, so the work barely depends on which check failed (best effort: the store lookups after the MAC still differ).
    • E, the key (maintainer decision 8). A dedicated secret, HORAE_ACT_KEY, at least 32 bytes (openssl rand -base64 48), read by SecretResolver.resolve_core: the file <secrets.dir>/HORAE_ACT_KEY, else the environment variable of that name. HORAE_* is reserved for the core (SecretName), so no secrets.refs entry, plugin or child environment can name it; it is remembered for redaction like every secret and primed by Instance.prime_redaction. Key id HMAC-SHA256(key, "horae-act/kid")[:4]. One key at a time, no grace window: rotating it (new value, restart) refuses every outstanding token. Missing: /act answers 503 and notifications go out without buttons. Set but unusable (shorter than 32 bytes, unreadable): horae serve refuses to start (config_invalid) and horae doctor reports an error; set without http.public_url or a route, horae doctor warns; read from the environment rather than the file, horae doctor warns too (a same-uid plugin can read the core's environment through /proc: prefer the file). No secrets.refs env / file and no deidentification.vocabulary may name a core secret's variable or file (CORE_SECRETS, any case: the contract refuses it), so no reference can hand the key to a plugin.
    • F, the route. The change is applied by the instance's one mode: tasks act entry (its tool and parameters as written; one with a template is not used), as decision 30 routes a task.update_status; zero or several distinct entries, or a plugin that may not apply task.update_status (checked by horae serve with the plugin registry): no route, /act is 503. Each POST opens the instance's sinks (the plugin host) for that call.
    • G, single use (store migration 8, maintainer decision 7). Table act_consumed (nonce primary key, kid, expires_at, consumed_at, run_id, outcome: pending, applied, not_changed, stale, failed). POST: verify; take the apply lock (decision 34 D6, at most 3 s, else 503 and the token stays usable) and the _act pipeline lock, recovering an _act run a dead process left running; refuse a used token or an unknown task (404, nothing written); open the sinks (unreachable: 503, nothing written); begin a run of the reserved pipeline _act; if the task's state is not the token's, consume it stale (nothing applied, the run failed with target_changed); else, in one transaction, insert the nonce (pending; a primary-key conflict means used) and journal the task.update_status the core built (never from the request), commit, then Sink.apply (bounded by plugin_defaults.call_timeout_s), then mark the entry applied and the outcome applied, update the task index and end the run ok. A sink that answers it changed nothing (details.changed: false; plugin-obsidian answers so, with details.recurring, for a recurring task asked done): the entry is marked applied (the sink answered), the outcome is not_changed, the task index is not updated (a details.recurring flags the task recurring) and the run ends noop (review decision 3); the apply phase of a run leaves the index alone the same way. A sink failure or timeout uses the token up (failed, single attempt). A crash after the commit leaves the token used and the change journalled "maybe applied": at most once, never twice. _act runs are bare rows (no run record: PipelineName forbids _ and they have no definition or steps; the runs table's CHECK now allows them, like eval: rows), visible in horae runs; their journal entry names the task and the sink, their act_consumed row the outcome (the ref of the logs is SHA-256 of its nonce). Used-token rows are kept 24 h 05 min (MAX_AHEAD_S = ACT_RETENTION_S) after their token expired, so a clock stepped back by less than that cannot make a used token usable again; then they are deleted (one bounded DELETE per POST, and by prune_runs).
    • H, expiry and clocks. exp = mint + 24 h, refused when now >= exp, and refused when exp > now + 24 h 05 min (a clock that jumped forward at mint, or a bug). Minting and checking share a host and a clock: no skew leeway.
    • I, staleness. POST recomputes state from the task index; any change of status, due date or snooze (task done meanwhile, snoozed again, due date moved) makes the link stale (409, consumed). A re-collection that leaves the three fields unchanged (a new title) does not. The task index is now kept by the apply phase (horae.apply.index_task, needed for this decision: nothing wrote it before): an applied task.create inserts its task (todo), or updates the title, due date, time and source of a known one without reopening it; an applied task.update_status changes a known task (a date until in the instance time zone), unless the sink answered changed: false; a store failure there is logged and never fails the apply. Migration 8 adds tasks.recurring (0 or 1, default 0).
    • J, GET shows, POST applies (maintainer decisions 1 and 5). GET verifies and reads the store read-only: it writes nothing (no nonce, run, lock or log line with the token), so link previews, prefetchers and scanners leave the token usable; it shows the action and the task's title (escaped, at most 120 characters) and due date, nothing else (never the fingerprint, note or time), with one <form method="post"> button, or "task changed" (409, no button). HEAD is 405. A ntfy http button POSTs in one tap (the native client sends no Origin); a view link opens the page. Origin check on POST: an Origin header, when present, must be http.public_url's origin (one header only; null is refused), and Sec-Fetch-Site, when present, must be same-origin or none; otherwise the 404 page, nothing consumed. The confirmation page has Referrer-Policy: strict-origin (review finding 1): under no-referrer a browser sends Origin: null with the form's POST, so its button was refused; strict-origin sends only the origin, never the path, so the token does not leave in a Referer (tested by submitting the rendered form as a browser does). No cookie is set or read. Every /act response: Content-Security-Policy: default-src 'none'; style-src 'sha256-<inline style>'; form-action 'self'; frame-ancestors 'none'; base-uri 'none', Cache-Control: no-store, Referrer-Policy: no-referrer (the confirmation page: strict-origin), X-Content-Type-Options: nosniff, X-Robots-Tag: noindex, nofollow, X-Frame-Options: DENY; no script, external asset or Open Graph tag.
    • K, failures. Every refusal of a token (malformed, truncated, oversized, forged, another key, expired, too far ahead, used, unknown task, a cross-origin POST, and any other path under /act) is the same 404 page with the same headers. Distinct answers only where they say nothing about the token: 429 (rate limit), 503 (no key, no route, apply lock busy, sinks unreachable). After a consume the holder of a valid token gets the outcome: 200 applied, 200 "Not changed" (not_changed; "tick it in Obsidian" for a recurring task), 409 stale, 502 failed (after a timeout: the change "may not have been applied"), 500 when something failed after the consume (the page says the change may have been applied, never "not available").
    • L, rate limit (maintainer decision 9, review decision 4; constants). In process, for GET and POST: a token bucket per client (10 a minute, burst 5), taken before any decoding or store access, and a global one (60 a minute, burst 60), taken only for a token whose MAC verified (checked before any store access, a few microseconds), so invalid tokens never block valid ones; 429 with Retry-After. A request whose token is refused costs its client 3 in all (the client's bucket may go into debt down to minus its burst); the global bucket never goes into debt. A client is an IPv4 address or the /64 of an IPv6 address (rotating addresses inside a /64 gets no new bucket). At most 4096 client buckets (LRU). One process (horae serve); several workers would each have their own. The client address is the peer, unless the peer is in horae.yaml http.trusted_proxies: then the right-most X-Forwarded-For address that is not itself a trusted proxy (a generalisation of the note's "last hop", identical with one proxy; it serves the reference deployment, below). Without trusted proxies the header is ignored. A trusted_proxies entry is at least /8 (IPv4) or /32 (IPv6): a wider one (/0 above all) would trust any client's header. Reference deployment, Cloudflare tunnel then Traefik (#41): no entry point carrying Horae's routers may trust forwarded headers (forwardedHeaders.trustedIPs, insecure; docs/operations/coolify.md, forwarded headers), so Traefik replaces X-Forwarded-For with cloudflared's address and every request shares cloudflared's bucket (still limited, never unlimited). http.trusted_proxies is for a chain whose proxies may pass the client's address on.
    • M, routing and SSO (#41 tests the rendered Traefik template). Exactly /act/{token} (one path segment; no path converter, no mount or prefix router under /act), so %2F, .. or a trailing segment can never reach /runs or /healthz through the prefix the proxy exempts from SSO; every other 404 under /act is the same page. #41's exemption should match the token's exact shape, PathRegexp(^/act/[A-Za-z0-9_-]{98,267}$), rather than PathPrefix(/act). The routes read no SSO or forwarded-user header. The Host check of decision 51 G2 still applies: http.public_url's host must be an allowed host (horae serve warns otherwise).
    • N, logs. No access log (decision 51 A). One line per /act request (horae.api.act): act <method> <kind> <ref> <outcome>, ref the first 8 hex digits of SHA-256(nonce), for a token whose tag verified; an unverified string is act <method> invalid len=<n>. Never the token, the URL or the task. The operator guide (#41) must turn off Traefik's access log for the /act router or drop its path: Traefik logs paths before Horae sees them; the token also reaches cloudflared's logs (at debug) and Cloudflare's own request logs for the zone.
    • O, imports. horae.api loads its names lazily (PEP 562) so the runner can import horae.api.act (key, token, minting) without loading FastAPI; the routes are loaded by horae.api._app only.
    • P, the review of PR #115 (the maintainer: "go with what's good for the project"). 1, the confirmation page's Referrer-Policy: strict-origin (J); 2, the core labels the buttons (B); 3, recurring tasks and not_changed (C, G, I); 4, the rate limit's /64 clients and MAC-verified global bucket (L); 5, this decision renumbered from 53 (53 is #127's); 6, no reference to a core secret, and horae doctor's warning (E); 7, the narrowest trusted_proxies (L); 8, :443 dropped from http.public_url (C); 9, the runner checks the route's plugin (C); 10, the used-token retention (G); 11 and 12, the timeout and after-consume pages (K); 13, no button for a closed task (C).
    • Not done (follow-ups): rendering actions as ntfy buttons (plugin-ntfy#4) and their iOS behaviour (#72, #65); daily-note links (decision 3); the SSO-exemption test against the rendered template and the Traefik access-log setting (#41); an SDK intent builder for actions (the field is plain JSON meanwhile); showing the buttons in the dry-run diff.

Provisional decisions (#128, pending maintainer review)

  1. The action guard refuses note structure, and a skill may refuse every link (#128). Numbering: 52 is #122's, 53 #127's, 54 #38's (/act, PR #115). One compatible addition to skill/v1.json (an optional links); no other contract change. The pack-daily-brief review found an obeyed injection could still write live Obsidian constructs into LLM note content; decision 46 is extended:

    • A, note structure (rule 8 of horae.engine.guard). In every text field of a note.* intent (content, and note.append_section's heading) proposed by an LLM skill, refused:
    • a task checkbox: a line whose prefix (any whitespace, > at any depth, list markers -, *, + and ordered markers <digits>. / <digits>) with any number of digits, each followed by whitespace, repeatedly) holds at least one list marker and is followed by [, any one character, ] (- [ ], * [x], + [/], 1. [ ], - []], > > - [ ] in a callout, - - [ ], 1234567890. [ ]); a space after ] is not required (conservative). This walk is its own, wider than the Tasks plugin's ^[\s>]*([-*+]|[0-9]+[.)]) +\[.\]: the CommonMark walker of H2 stops ordered markers at nine digits, which Tasks does not (a security review finding). [x] without a list marker, -[ ] and - [ab] pass. The other rules below are substring searches anywhere in the text, so no prefix, indentation or nesting can hide them;
    • any Tasks signifier (SIGNIFIERS, with or without U+FE0F) anywhere, not only on a task line: a copy of the keys of horae_sdk.tasks.SIGNIFIERS (the core does not depend on the SDK at run time); sdk/tests/test_sdk_tasks.py checks they are equal. Known cost: a brief cannot use ✅ or ❌ as decoration;
    • any [[ (a wikilink, internal ones too: decision 46 H1e let them pass; a note link is a click away from any note of the vault, and embeds ![[ stay refused by rule 2);
    • any :: (a Dataview inline field: key:: v on a line, [key:: v], (key:: v)); known cost: std::vector, ::1;
    • any %% (an Obsidian comment, which hides text in reading view);
    • a horae block marker: MARKER, the very recogniser of horae.apply.notes (horae:(begin|end), any case, any spacing; a test checks the patterns are equal). Before, the guard passed horae:end daily-brief and apply then failed the whole run (content_has_marker) every day the input held it; now the llm step degrades (guard_violation) and apply never runs;
    • a tag (answer to "allow #tags?": refused). Tags execute nothing, but they put the note into the user's tag searches, Dataview FROM #tag queries and a Tasks global filter, so an injected #urgent or #todo reaches dashboards the pipeline does not own; a brief needs none. A tag is a # at the start or after a character that is not a letter, digit, _, & (a character reference &#x25;), \ (an escape) or / (a URL fragment), followed by a body (up to whitespace or one of !@#$%^&*(),.?":{}|<>, the Tasks tag pattern) that is not only ASCII digits: #128, (#42), C#, page#x and a heading # Title pass; #todo, #2026plan and ##x do not. Known cost: a # comment in a code block is refused.

    No code exemption (conservative): the rules apply inside inline code and fences too. Tasks reads its fields from the raw line by regex (a backtick does not hide a signifier from it), Dataview's inline-field parsing of code spans is not documented, and an exemption would need a CommonMark-exact code-span parser.

    On the source only. Obsidian's metadata cache, Tasks, Dataview and apply read the note as written; a backslash escape (\[\[, \#, :\:) or a character reference (&#x1F4C5;, %&#x25;) keeps them from matching (decision 50 relies on the same reading). So these rules run on the text as written, not on the entity-decoded and Markdown-unescaped views of decision 46 (which keep guarding links, embeds and HTML, what a renderer produces). Consequence: horae_sdk.tasks.escape_title output always passes them (a Hypothesis property in sdk/tests/test_sdk_tasks.py, also as - <title> and > - <title> lines), so a skill may list escaped titles. The link rules may still refuse an escaped URL not in the input (https\://… reads as a URL once unescaped, decision 46 0b). - B, links: none (a skill option, SkillManifest.links, input by default). The input allowance (decision 46, 4) lets a URL through when the viewed input holds it, and an attacker writes the input (a task title, a mail). A skill that writes no link says links: none: in its note.* text every link is refused, on every view, whatever the input holds: a URL (rule 6: scheme:/…, special schemes, //…, www., so bare URLs and autolinks), ]( (inline links, also to vault paths), ][ (reference links) and a line's leading [label]: definition (also behind a [^footnote]: prefix), and a bare email address. A shortcut reference [label] alone is not refused: it links only through a definition already in the note (the user's). notify.push and task.create link fields keep their own rules (exactly an input URL under a trusted link_prefix, decisions 30, 52). Detail: … with a link, and the skill allows none in `content`. The option does not join the skill digest (the cache key): the guard runs on every reuse, so a cached output is checked with the current option. The engine passes it from LoadedSkill.links (a new member of the port) and horae eval from the skill under evaluation. - C, not done (follow-up). A template render transform, so a skill returns structured lines that the core renders and escapes instead of free Markdown (the issue's third proposal), is left for a later issue: these refusals are the floor whatever renders the note. - D, compatibility. links is optional with a default, so every v1 skill stays valid and behaves as before for links. The note-structure rules are new refusals: a skill whose prompt asks for task checkboxes, tags or wikilinks in a note now degrades its step; tasks belong in task.create intents (escaped by the sink, decision 50). 56. Optional plugin secrets, permissions.optional_secrets (#136). Provisional. A declared secret had to resolve or the plugin did not start, so a plugin with several credentials of which a user needs one (plugin-calendar's CALENDAR_*, plugin-github's two tokens, a per-entry ntfy token) needed placeholder values. - A, the form. A parallel list, permissions.optional_secrets, beside secrets, same name rules (SecretName, at most 256, unique), default empty. Chosen over secrets: [NAME, {name: NAME2, optional: true}] because secrets stays a list of names, so every v1 manifest and horae.lock stays valid and every reader of secrets (the lock, the SDK, the redaction priming) keeps meaning "required". It applies to both plugin.yaml and horae.lock (one Permissions model). A name in both lists is refused (pydantic only: JSON Schema cannot say it). - B, permissions. An optional secret is a permission like any other: horae.lock must grant it in optional_secrets (_exceeds compares both lists; a grant as a required secret does not cover an optional request, and the locked list is the one in force). - C, the host. Required secrets resolve as before (missing: secret_missing, the plugin does not start). An optional secret is resolved at start; if it does not resolve (no file or variable, too short, unreadable: any SecretError) it is simply absent from the child environment, and the plugin reports secret_missing itself when a call needs it. Both lists are checked against the environment deny list. When the host opens, it resolves optional secrets with the others, so redaction covers those that resolve. - D, horae doctor. Each unresolved optional secret is an info problem (a new severity value, beside error and warning), at the lock's optional_secrets entry, never failing the check; ok is true and the exit code 0. A required one stays an error. A too-short optional secret is also only info (its message says why). - E, compatibility. Additive: an optional field with a default. Older cores reading a manifest with optional_secrets refuse it (additionalProperties: false), as for any new field.

Provisional decisions (#137, pending maintainer review)

  1. notify.push takes an optional stable key (#137). A compatible v1 addition. key is a Fingerprint (^[A-Za-z0-9._:-]{1,128}$).
    • A, key. Without key the dedupe_key is unchanged (decision 30): the SHA-256 of pipeline, routing entry, input_hash or run id, intent and occurrence. A pipeline without an LLM step has no input_hash, so a reminder re-proposed every 5 minutes got a new key each run. With key, the dedupe_key is the SHA-256 of (pipeline, routing entry, key, the local date of the run's started_at in the instance timezone): the text, the input, the run and the occurrence no longer count. The same keyed notification proposed by many runs on one local day is recorded once; the next local day (DST days are 23 or 25 h long, the date is the calendar date in the zone) it is sent again.
    • B, skipping. Unchanged mechanism: plan_changes(notified=) marks the key duplicate (information, not a problem) and apply_changes skips it, without a journal entry, listing it in ApplyResult.duplicates. Two keyed notifications with the same key and entry in one run are one send.
    • C, compatibility. key is absent from the identity of a notification without it, so upgrading re-sends nothing. horae_sdk.intents.notify_push(..., key=None) builds it.
    • Follow-up. plugin-ntfy keeps its own dedupe: daily derivation until its callers pass key; obsidian.reminders should set key to the reminder's stable id.
    • Amendment (follow-up to #137): the key is the identity. The date component in A is dropped. With key, the dedupe_key is the SHA-256 of (pipeline, routing entry, key) and nothing else, so a lookback that crosses midnight no longer sends a key twice (the run's local date was not the date the key carried). A proposer that wants "once a day" puts the day in the key (obsidian.reminders already does: rem:...:<date>T<time>, digest:<date>). The instance timezone no longer takes part in the key (it is no longer passed to plan_changes). Retention: notifications rows are never pruned (prune_runs keeps them, see docs/operations/retention-and-backups.md), so a repeat of an old key is never resent; a keyed notification re-sent after an upgrade is possible once, for keys recorded with the old day-scoped hash.

Provisional decisions (#138, pending maintainer review)

  1. A repeated task.create fingerprint is not re-created (#138). No schema change.
    • A, plan. plan_changes(known_task=) reads the task index (decision 54): a task.create whose fingerprint the index knows (or an earlier intent of the same run planned) is a TaskChange with action existing (title, due and time as indexed; shown as unchanged) or update (title, due or time differ; before is the indexed task). The planner never reopens anything. update is what the upstream intent says, not a promise: the diff reads "changed upstream; not applied unless the sink rewrites the task", because a sink may keep its line (plugin-obsidian does: changed: false).
    • B, apply. Unchanged path: the intent still goes to the sink, the authority on the vault (plugin-obsidian dedupes by ^h- block id and may adopt or dismiss it). The index is updated from its answer: an applied answer updates title, due and time and keeps the status (a ticked task stays ticked); changed: false leaves the index alone (so an update the sink declines is planned again next run), except adopted (and not dismissed), which indexes the task as todo if unknown.
    • C, compatibility. TaskChange.action gains existing and update; without known_task every task.create stays create.

Provisional decisions (#139, pending maintainer review)

  1. horae undo reverts task status changes; Sink.restore takes an optional force (#139). No schema change (the journal's before and after columns hold the two blobs); the sink operation list gains restore_status.
    • A, what is journalled. A task.update_status journal entry starts not undoable. Its before is the task index entry it replaces (TaskEntry as JSON; none for a task the index does not know), taken before the sink is called. When the sink's answer says details.changed: true (and the details are JSON of at most 64 KiB) the entry is marked applied with the details as its after and becomes undoable, in the same transaction. Any other answer (changed: false, no details, a recurring task) leaves it as before: not undoable, listed by horae undo. The /act buttons (decision 54) journal the same way, so a tick from a notification can be undone too. The details are the sink's own data (the secret gate flags a secret in them, like after) and go back only to the sink that produced them (its identity is checked, sink_mismatch).
    • B, the operation. <ns>.restore_status (details, optional force) returns {"restored": bool}; it joins SINK_OPERATIONS (a plugin may not provide a tool of that name, as for the others). In process, the optional TaskRestorableSink.restore_status. The sink alone knows how to put the task back; the core never reads the vault. A sink without it (tool_missing, or not_supported as the SDK default) leaves the change listed under "Not undoable", exactly as before, and a run with nothing else to undo is nothing_to_undo.
    • C, order, refusal, index. Status changes are undone first, latest first, then the notes. A task a later run changed too is newer_run (undo that run first, or --force). A task edited since the run is SinkError("target_changed") from the sink: the undo is refused (changed, exit 4) with "use --force"; the status changes restored before the refused one stay restored (undo is resumable) and no note was written. #149: this is deliberately not a transaction, and the report says so: a refusal names the tasks restored before it, the text report ends with "Partly undone" (what is restored, what is not, "run horae undo <run> again"), and --json gains partial (additive). Task restores run before note restores, and that stays. The core does not know which file a task line is in (the sink alone does), so it cannot order a task and a note of one file by journal id; a true interleave needs a dry-run restore_status, which is out of scope. A run that changed a note and a task line of the same file therefore either is refused up front (changed, the file no longer matches what the note change left) or, when the task restore rewrites the file after the note was read, fails the note's compare-and-swap (target_changed, with a hint that a restored task may have edited the note); horae undo --force restores the note in both cases and keeps the overwritten bytes in the journal. For each restored change the task index entry is put back in the transaction that marks the journal entry undone: status, snoozed_until, snooze_tz, wake time and the run that last wrote it, exactly as journalled (Store.restore_task_status). A task the index lost is restored in the sink only. horae undo --json gains a tasks list (additive; schema_version stays 1).
    • D, force. Sink.restore(target, content, *, expected_sha256, force=False) and restore_status(details, *, force=False) get force. It is true only when the user passed horae undo --force: it is a parameter of undo_run, set by the CLI flag, and nothing a plugin or a note returns (details, errors, note content) can set it. The core sends force only when true (<ns>.restore and <ns>.restore_status arguments), so a plugin built before it is called exactly as before; a forced restore to a plugin whose tool refuses the argument (tool_error) is asked again without it, and an in-process sink without the parameter is called without it (the core's own compare-and-swap on the bytes it read still holds, and --force still keeps the overwritten bytes in the journal). force never lifts the compare-and-swap, the path rules or the vault boundary (sink_mismatch).
    • E, compatibility. horae-sdk 0.4.0: Sink.restore(..., force=False) and Sink.restore_status(paths, details, force=False) (default not_supported); the SDK passes force only when true and the sink's method takes it. file-sink.restore accepts force and ignores it (no owned-block rule of its own; likewise the built-in LocalFileSink.restore). A sink that overrides restore with the old signature must add force to pass mypy, and <ns>.restore_status is a reserved operation name (a plugin that provides a tool of that name is rejected at load): both are in the SDK README's "Upgrading a sink to 0.4.0".
    • Follow-up (plugin-obsidian). Its task sink must put the replaced line in Applied.details (before_line; today only digests, and restore_status expects it from the core's journal, which the core cannot supply: it never sees the line), serve <ns>.restore_status (tasksink.restore_status with force), and honour force in restore for notes edited outside the owned block.

Provisional decisions (#135, pending maintainer review)

  1. A mode: tasks entry takes several link_prefix values; an unroutable task link is skipped, not fatal (#135). A compatible v1 addition: the link_prefix entry parameter is free-form pipeline data, so only run-record/v1.json changes (a new violations[].kind value, intent_skipped).
    • A, several prefixes. On a mode: tasks entry, link_prefix is either one string (unchanged) or a list of 1 to 32 strings. Each is checked exactly as before (_check_link_prefix: https://, a host, no user info, query or fragment, a clean path ending in /). An empty list, more than 32, or any invalid item is params_invalid naming link_prefix. A task.create link is taken by the entry if it falls under any of them. notify entries keep a single string (decision 30).
    • B, overlap: the longest prefix wins. When two entries take the same link (their prefixes overlap, https://github.com/org/ and https://github.com/org/app/), the entry whose matching prefix is longest takes it. Two entries that match with an identical prefix stay intent_ambiguous. Within one entry, overlap is moot.
    • C, degrade per item. A task.create that a tasks entry would take but for its link (no prefix matches, or the entry has none) no longer fails the step with intent_unrouted: that one intent is left out, the others are routed, and the step ends ok. The run record gets one intent_skipped violation per proposing call: the source, the positions and the fixed text task link not under a trusted link_prefix (never a link), and the core logs a warning. If every intent of a call is skipped the detail says skipped all. Every other routing failure (no entry binds the type, an unknown fingerprint, ambiguity) still fails the step. Extended by #149: a notify.push with a link that a notify entry would take but for that link (no link_prefix, or none that the link falls under) is skipped the same way, with the fixed text notification link not under a trusted link_prefix; a call that proposes both kinds lists both texts in its one violation. A notify.push without a link, or one that no notify entry binds at all, is unchanged. horae doctor reports, as a warning (never an error), each pipeline whose newest 20 runs hold intent_skipped violations, with the latest run and its detail, so a skipped link does not stay unseen.
    • D, compatibility. Pipelines that never had an off-prefix link are unchanged; ones that did now succeed with a violation instead of failing. A consumer must accept the new kind; per "Versioning" a new enum value is a compatible addition.

Provisional decisions (#43, pending maintainer review)

  1. Marketplace resolution (#43). New schema marketplace/v1.json (a marketplace's marketplace.json) and two optional horae.yaml keys, marketplaces and marketplace_pins. The number may be renumbered against other open PRs.
    • A, the index contract. MarketplaceIndex (horae.contracts.marketplace) mirrors schema/marketplace.schema.json of horae-dev/marketplace, strict and extra=forbid: {plugins: [{name, repo, versions: {<semver>: <40-hex sha>}, tier}]}, names unique. Name, semver and repo (GitRepoUrl: https only) are the lockfile's types. The index pins a 40-hex SHA-1 or a 64-hex SHA-256, the lockfile's CommitSha (#153: the schema first took 40-hex only; marketplace/v1.json is regenerated, no version bump, as it only accepts more). Unique names are checked by the model, not by JSON Schema (as in the marketplace verifier).
    • B, config. marketplaces: an ordered list of 1 to 16 https:// git URLs, highest priority first, default ["https://github.com/horae-dev/marketplace"]; no duplicate. marketplace_pins: plugin name -> one of the marketplaces.
    • C, fetch and cache. horae plugin search|resolve clone (shallow, --depth=1, not --filter) or update each index into <state_dir>/marketplaces/<hash of the URL>/repo.git, read marketplace.json from the fetched HEAD (at most 4 MiB), validate it, and store the validated copy and when it was fetched beside the clone. A copy that fails validation never replaces the cache. Git is hardened as the marketplace verifier's _git: protocol.allow=never and only https, GIT_CONFIG_GLOBAL/SYSTEM off, no prompt, an empty environment but PATH, HOME, LANG, TMPDIR, a 120 s timeout, -- before the URL. The transport is a constructor argument of MarketplaceClient, never a setting; only tests pass file, to clone local fixture repositories.
    • D, resolution. name[@version]. Indexes are searched in marketplaces order. Without a version, the highest semver by semver.org precedence; pre-releases are skipped unless --pre (a version named explicitly may be one; a plugin with only pre-releases is an error that says so). A name listed by several indexes under the same repository (a mirror) comes from the highest-priority one, entirely. Under different repositories it is a conflict: an error that names every index with its repository (priority order) and suggests marketplace_pins. Unknown name or version are errors that list where it looked or the available versions.
    • E, disambiguation: a pin in config. Chosen over an index-name/plugin syntax: an index is any git URL and has no short name that is unique (two marketplace repositories of different owners are likely), a pin is explicit, reviewable in horae.yaml, and keeps name@version the only reference grammar (also the lockfile's and #44's). A pin to an index that does not list the plugin is an unknown-plugin error.
    • F, offline. When a refresh fails, the cached copy of that index is used and a warning names the index, the reason and the copy's date. --offline skips the fetch. An index with no cache (fetch failed, or --offline) is an error, never skipped: skipping a higher-priority index could hide a conflict. The cache is validated again when read.
    • G, CLI. horae plugin search [QUERY] and horae plugin resolve NAME[@VERSION] (--offline, --pre, --json, -i). Exit 0 ok; 1 configuration problem or no cache; 2 malformed reference; 3 unknown plugin or version, or conflict. They install nothing (#44).
    • C2, fetch environment, cache and concurrency (#153). The git environment stays allow-listed; a call that reads a remote (index clone/fetch, plugin clone, fetch, ls-remote) also inherits exactly HTTPS_PROXY, HTTP_PROXY, NO_PROXY (and lowercase forms), SSL_CERT_FILE and SSL_CERT_DIR, so a server behind a proxy or with its own CA can fetch. A proxy must be an http, https, socks5 or socks5h URL with a host and no credentials; a CA path must be absolute and exist; otherwise the fetch fails with an error that names the variable and never its value (an index then falls back to the cache, as for any failed fetch). Protocol allow-list, no ext::, hooks off and the other variables are unchanged with a proxy set. Every directory the client creates under the cache (and uv-cache) is 0700, ancestors included; one that already existed is not changed. Each index clone is written under an exclusive flock on <cache_dir>/<hash>.lock (waiting up to 150 s); past that, LockBusy: exit 5, kind lock_busy, as the horae.lock guard.
    • H, trust. An index is untrusted data (security.md, B6): it can only point to a repository and a SHA. #44 re-verifies the tag and the SHA, #46 shows the permissions.

Provisional decisions (#44, pending maintainer review)

  1. Install from git with a pinned commit (#44). horae plugin add NAME[@VERSION] (--offline, --pre, --json, -i) resolves the name as decision 61 D, then horae.marketplace.install.PluginInstaller.install(name, version, repo, sha), which a direct install from a git URL (#48) calls the same way, without the marketplace. No schema change.
    • A, fetch. The marketplace's hardened git runner (decision 61 C), extended for every call with core.hooksPath=/dev/null and GIT_LFS_SKIP_SMUDGE=1. git clone --bare --depth=1 --no-tags --single-branch --no-recurse-submodules --branch v<version> -- <repo>, then one fetch -- <repo> <sha> +refs/tags/v<version>:refs/tags/v<version>, so the tag is the remote's (a branch named like the tag cannot stand in for it). Only https (GitRepoUrl) is accepted, checked before git runs; the transport is a constructor argument, never a setting (only tests pass file). The clone, fetch and ls-remote calls inherit the proxy and CA variables of decision 61 C2 and nothing else; an install works in its own scratch directory, so it shares no clone to lock.
    • B, verify. rev-parse <sha>^{commit} must be the pinned SHA and refs/tags/v<version>^{commit} (an annotated tag dereferenced) the same commit, else the install is refused: a moved tag, a tampered index, or a SHA the repository does not have. The tag name is v<version>, as the marketplace's verifier expects.
    • C, the tree. Before checkout, from ls-tree: at most 5000 entries and 100 MiB of file content (and at most 200 MiB fetched); no ., .., empty or .git segment (any case); no .horae-install.json at the root; no symlink whose target is absolute or climbs out of the tree. Checkout of the tree only (no .git is installed) with core.symlinks=false (a symlink inside the tree becomes a small file holding its target), core.protectHFS/protectNTFS, --no-recurse-submodules (a submodule stays an empty directory). No hook or filter runs: hooks are off, and a filter needs config, which is /dev/null (global, system) or written by our clone (the repository's is never cloned).
    • D, manifest. plugin.yaml at the commit must validate as PluginManifest and name the resolved plugin and version, else refused.
    • E, where, and atomicity. <instance>/plugins/<name>, the layout the plugin host already reads (HostRegistry.from_directory), derived from the validated name only. All the work happens in plugins/.install-<random>/, and the finished tree is renamed into place (same file system: atomic), so plugins/<name> is absent or complete, even if the process is killed. A scratch directory is never read by the host; one older than an hour is removed by the next install. A name already installed is refused (upgrade is #47).
    • F, what is recorded: a manifest in the install directory, not horae.lock. plugins/<name>/.horae-install.json = {schema_version: 1, name, version, repo, commit}, the fields of a LockedPlugin without permissions (Installed.lock_entry(permissions) builds the entry). horae.lock stays the list of approved plugins: writing it is #46, with the permissions the user approves. So an installed plugin is not enabled: the host loads only the plugins of horae.lock, and the CLI says so and what is left (approve its permissions, install its dependencies). The record is what #46 and #47 read to know what is on disk.
    • G, dependencies. install(..., prepare=...) runs on the verified tree before the rename: the hook for #45 (the plugin's venv); a failure aborts and leaves nothing.
    • H, CLI exits. 0 installed; 1 a repository that cannot be fetched (install_failed); 3 refused (install_refused) or already installed (already_installed); the others as decision 61 G.

Provisional decisions (#131, pending maintainer review)

  1. The locked network list travels in every plugin call's _meta (#131). No schema changes: it is a wire addition of the plugin host (horae.plugins.host.session) and the SDK (horae-sdk 0.5.0). Decision 62 is taken by open PR #155.
    • A, the key. Every request to a plugin (a source, a transform, a sink operation) carries _meta["horae/network"]: the plugin's permissions.network as approved in horae.lock (the host's effective manifest, never the manifest's declared list), a list of host names in the lock's order. A plugin the lock grants no host sends []: an empty list is never "everything allowed", and the key is always present from a core that has this decision. The key has no dev. prefix on purpose: it names a core capability a plain MCP server never sets, and horae/ is reserved for the core (the earlier keys, dev.horae/input, dev.horae/paths and dev.horae/intents, are unchanged).
    • B, trust. The core builds _meta itself; a transform's untrusted input travels under dev.horae/input and parameters are arguments, so neither can set or shadow the key. Before M5 it is advice the plugin enforces on itself, not isolation: a malicious plugin simply ignores it (T05 stays open until the egress proxy, #50). It protects against a configuration that points a good plugin at a host the user did not approve (a server or allowed_hosts from trusted pipeline config, a redirect, a hostile URL).
    • C, matching. horae_sdk.Network.allows(url) uses the lock's semantics and nothing looser. A host matches only if it is written exactly as listed: names are lowercase (Hostname) and compared without case folding, trailing dot, wildcard or implicit subdomain; an internationalised name is its xn-- A-label; any port is accepted on an approved host (decision 10). The URL must satisfy the shape of HttpsUrl: https only, no user info (https://allowed@evil/ and https://evil\@allowed/ never match), no backslash, whitespace, control character, fragment or IP literal. A list entry that is not a valid Hostname matches nothing. The core's helper horae.contracts.url_host stays the core's reading; the SDK has no dependency on the core, so it carries its own copy, and the SDK tests assert the two agree.
    • D, compatibility. A core older than this decision sends no key; the SDK then reports the list as unknown (allowed_hosts is None, host_allowed(url) is None), which is not "refused": the plugin decides, and falls back to its own configuration. A present but malformed value is read as an empty list (fail closed). An SDK older than 0.5 ignores the key. The list is repeated on every call (a few names), not sent once.
    • E, scope. Plugins are not changed here: plugin-ntfy (server) and plugin-calendar (allowed_hosts) are to call call.host_allowed(url) / request.host_allowed(url) in follow-ups, treating False as a refusal and None as "use my own config".

Provisional decisions (#134, pending maintainer review)

  1. A public replay backend, a request digest of a case, and the not_contains / matches assertions (#134). Provisional. Changes eval-case/v1.json (two optional checks; an older case file stays valid, and schema_version stays 1). Decision 62 is taken by open PR #155 and 63 is merged.
    • A, the replay backend is public. horae.llm.replay.ReplayBackend(inner, source) replaces the private horae.evals._harness._Replay: its render is the real backend's (same payload, same digests, same cost bound) and its send returns a recording, so nothing leaves the host and no secret is read. source is one CompletionResult (what the eval harness uses) or Recordings, a library looked up by request digest. replay_backends(models, source) builds the ModelBackends over it. _Replay stays as a subclass of ReplayBackend (same constructor), so the packs that import it keep working; it is deprecated and is removed once the packs have switched.
    • B, horae run --llm-replay <recordings>. <recordings> is a recording file, or a folder searched (at most 6 levels, 4096 files, dotfiles and symbolic links skipped) for *.json recordings in the format of decision 48 C, e.g. a skill's evals/recorded/. Every llm step renders its request with the real backend of its alias, and the recording whose request digest (prompt, viewed input, output schema) matches answers it, preferring one recorded for the alias' backend. The answer goes through the same validator, intent split, redaction, routing and guard as a live one. A request no recording answers fails the step with replay_miss (the run is degraded, the message names the digests and whether a recording shares the prompt or the schema): never a live call. Two recordings of one request and backend with different outputs are refused when loaded. A recordings path that cannot be read is exit 1, replay_unavailable. The cache lookup is skipped (as --no-cache); an accepted output is cached like any other, so a replay that must leave the cache alone is a --dry-run or a scratch instance. No new instance setting: the flag is the only switch, so a replay can never be configured by mistake into a production instance.
    • C, the request digest of a case. horae.evals.request_digest(sue, loaded) returns the RecordedRequest (SHA-256 of the prompt, of the canonical viewed input and of the canonical output schema) that horae eval --live --record would store and that --llm-replay looks up, rendered offline through the real backend (the digests do not depend on the backend or the model; the skill's input is de-identified as for a cloud alias unless a local backend is given). It raises EvalError for a case that cannot be rendered.
    • D, a stale recording fails horae eval. Offline, a recording whose request digest (or skill digest) no longer matches is the case error stale_recording (exit 1), with the message case <name>: the recording for backend <b> is stale (<prompt|input|schema| skill> changed since it was recorded); re-record it with horae eval --live --record. Before, it was a warning and the stale answer was still judged. Live, a stale recording stays a note (the new answer is what gets recorded). stale stays in the JSON report.
    • E, not_contains. The opposite of contains: a string holds no such substring, an array no such element. Something must be there: a missing value fails (nothing there; use exists: false to assert absence), so a mistyped pointer cannot make the check pass vacuously. A non-string needle on a string fails.
    • F, matches and ReDoS. A regular expression (Python re syntax, re.search, unanchored, flags inline such as (?i)) that must be found in the string at the pointer. The core has no user-supplied regex elsewhere; its pattern for untrusted work that can run long is the killable worker of the output validator (horae.llm.validate, decision 44), and matches uses it: the pattern is at most 256 characters and must compile (checked when the case loads); the searched string at most 65536 characters (a longer one fails the assertion); the search runs in a short-lived python -I -B child (empty environment, cwd /, new session, CPU and memory ceilings) that is killed after 2 seconds. A search that does not finish fails the assertion (the pattern could not be searched), never passes and never hangs the eval. A non-string value fails. Nothing else changes: the worker imports nothing of Horae.
    • G, what the packs switch to. pack-daily-brief's tests/test_pipeline_e2e.py (Recorded) to horae.llm.replay.ReplayBackend or replay_backends; scripts/sync_recordings.py (_offline_backends, deidentify, recorded_request, request_for, viewed_input) to horae.evals.request_digest; pack-reminders uses no private replay. Pipelines can be tested with horae run --llm-replay.

Provisional decisions (#54, pending maintainer review)

  1. The read-only MCP server (#54). New command horae mcp serve [-i <instance>] [--brief-pipeline NAME] (horae.cli_mcp, horae.mcp_server), over the mcp SDK already used by the plugin host (mcp>=2.3,<2.4, MCPServer), stdio only. Decision 64 is taken by #134.
    • A, tools. Exactly three, none with a side effect: tasks.today (open tasks, status todo, due today in the instance's time zone or overdue, overdue first; limit 1 to 100, default 50), brief.latest (the latest run of the brief pipeline, daily-brief unless --brief-pipeline says otherwise, and the note.* paths it journalled, never their content; run: null when it never ran) and runs.recent (newest first, live skill evals left out as in /runs; limit 1 to 50, default 10). The names are the ones of PLAN §3.5. pipeline.run is #55 and is not here; the server has no resource and no prompt.
    • B, contracts. Each result is a strict pydantic model (horae.contracts.mcp), exported as schemas/mcp/tasks-today/v1.json, brief-latest/v1.json and runs-recent/v1.json (export --check guards them) and published as the tool's outputSchema; the client receives it as structuredContent. A run is the HTTP API's representation (horae.run_view.run_json, decision 51 C), shared, not copied. Caps: 100 tasks, 50 runs, 20 targets; titles 200, targets 256, errors 500 characters.
    • C, untrusted text. The client is an LLM and a note can say anything. Task title and target, a target in brief.latest and a run error are marked x-untrusted in the schema, redacted with the process registry, reduced to one printable line (control characters become spaces), clipped, and declared as data in every tool description and in the server's instructions. The server never interprets them. Marking reduces, and does not remove, the risk that a hostile title steers a client; the tools cannot act on it.
    • D, read-only and no network. Each call opens the store mode=ro (Store.open(read_only=True): no migration, no write, no file created; a missing store is empty), takes no path, command or secret from the client, and closes it. No socket is opened, so there is nothing to authenticate here; token auth for a network transport is #56. A store failure is the fixed tool error store_unreadable (no path, no exception text). The tools are annotated readOnlyHint, idempotentHint, not destructiveHint, not openWorldHint.
    • E, exit and logging. stdout carries the protocol only; problems go to stderr. Exit 0 when the client closes the connection, 1 configuration problem, 2 usage error, 70 internal error (decision 37).

Provisional decisions (#132, pending maintainer review)

  1. Local-network grants in horae.lock, and how plugins reach the M5 egress proxy (#132). permissions.network holds public DNS names reached over https (decisions 6, 10, 63) and cannot express a service on the user's network: a self-hosted ntfy at ntfy.lan over http, Home Assistant at homeassistant.local:8123 or 192.168.1.10:8123, Proton Mail Bridge at 127.0.0.1:1143. Decision 62 is taken by open PR #155; 63 to 65 are merged.
    • A, a separate grant. New permissions.network_local (plugin manifest and lock, both schemas regenerated): a unique list of LocalEndpoint strings, host:port, e.g. ["127.0.0.1:1143", "[::1]:1143", "192.168.1.10:8123", "homeassistant.local:8123"]. A string, not {host, port, scheme}: it sorts and diffs like the other lock lists, and the scheme is not part of the grant (below). network is unchanged and still refuses IP literals, localhost and ports, so nothing that was refused before becomes allowed there.
    • B, what a local endpoint is. The port is always explicit (1 to 65535, no leading zero). The host is one of: a lowercase name ending in .local (mDNS), .lan, .internal or .home.arpa with at least one label before the suffix; an IPv4 literal in 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 or 169.254.0.0/16; or a bracketed IPv6 literal ::1, in fc00::/7 (ULA) or fe80::/10 (no zone id). IP literals must be canonical (str(ipaddress.ip_address(...)): no leading zeros, compressed lowercase IPv6, no IPv4-mapped form), so one service has one spelling and exact matching is sound. Never a public address or name, localhost, a single-label name, a wildcard, a scheme or a path. Cloud metadata services are refused even as an explicit grant: the addresses 169.254.169.254, 169.254.170.2, 169.254.170.23, fd00:ec2::254 and fd00:ec2::23, and every name whose first label is metadata or instance-data (metadata.google.internal, metadata.internal, instance-data.ec2.internal). The JSON Schema checks the shape (suffixes, private prefixes, port, the metadata not); the model adds the ranges and the canonical form. CGNAT (100.64.0.0/10, e.g. Tailscale) and single-label Docker service names are left out on purpose: a Docker service gets a .internal alias, and widening is a later, compatible change.
    • C, plaintext. Plain http is allowed only on a local endpoint, never on a network host. The grant names a host and port, not a scheme: http and https (and, for address_allowed, any protocol) may use it, since what is approved is reaching that service, and TLS on a LAN is the user's choice. http.post intents, mcp-http runtimes and task links keep HttpsUrl and network: a local grant is for the plugin's own connections only.
    • D, approval. Manifest-declared versus lock-approved stays as decision 63: the host refuses a plugin whose manifest asks for a network_local entry the lock does not grant (permissions not approved (network_local: ...)), and the lock's list is the one in force. The approval flow (#46) must show these entries apart from network, under "local network (plain http allowed)", one line per endpoint. Until then a lock is hand-written: the lockfile contract accepts the key, and a lock without local grants is written exactly as before (network_local is left out when empty), so an older core still reads it.
    • E, the wire. Every plugin call also carries _meta["horae/network_local"]: the locked list, always present from this core ([] when none). horae-sdk 0.6.0: host_allowed(url) is True for an https URL on an approved host (decision 63) or an http/https URL whose host and port are exactly an approved local endpoint (no port in the URL means 80 for http, 443 for https); address_allowed(host, port) does the same for other protocols (IMAP); local_endpoints is the list. True / False / None stay: no horae/network at all is unknown (None); horae/network without horae/network_local (a decision-63 core, which could not grant one) means no local endpoint. No normalisation and no DNS: a public name never matches a local grant (ntfy.lan.evil.test, 127.0.0.1.nip.io), nor do user info, another spelling of an address or another port. Old plugins and SDKs ignore the new key; an older core sends neither key and the SDK reports unknown.
    • F, the M5 egress proxy (to be followed by #49 and #50). The proxy is exposed by an explicit variable, not transparently: in M5 isolation only, the core sets HORAE_EGRESS_PROXY (an http:// URL of the allow-listing proxy) in the plugin's clean environment; *_PROXY stays on the deny list (decision 28) and plugins keep trust_env=False. A plugin sends its connections to public hosts (network) through HORAE_EGRESS_PROXY (HTTP CONNECT), and connects to local endpoints directly. The plugin container's network has no default route: the proxy, which resolves names itself and refuses private, loopback, link-local and metadata addresses (T07), is the only way out for public hosts, and each network_local grant becomes an explicit route or firewall allow rule for exactly that address and port (a local name is resolved once by the core when the container starts, and refused if it resolves outside B's ranges or to a metadata address). Before M5 the variable is unset: a plugin connects directly, as today. A plugin that sees the variable and cannot use a proxy must fail, not bypass it (it could not anyway). Loopback in M5 means the plugin's own container; reaching a service on the Docker host's loopback (Proton Mail Bridge) needs that route to the host (#49/#50 decide how, e.g. a host-gateway route limited to the granted port).
    • G, limits before M5. A local name can still resolve to a metadata or public address: the grant checks what is written, not what DNS answers. Refusing that at connect time is the proxy's and the route's job (#50); a plugin that resolves names itself keeps refusing a resolved metadata address (plugin-ntfy already does). As in decision 63 B, the _meta lists are advice a good plugin enforces on itself, not isolation (T05). A grant of 127.0.0.1:<port> before M5 reaches whatever listens on the core's own loopback (e.g. the HTTP API, decision 51 B): the approval shows it as a local-network grant for the user to judge.
    • H, plugin follow-ups (not changed here). plugin-imap: declare its Bridge endpoint in network_local (e.g. 127.0.0.1:1143, 127.0.0.1:1025 for SMTP), require horae-sdk 0.6, and check call.address_allowed(host, port) before connecting (False refuses, None falls back to its own config); drop the 0.1.0 note that a local Bridge is always refused. plugin-homeassistant: accept an IP-literal or .local / .lan base URL (http allowed), check it with call.host_allowed(url), and document network_local with an explicit port instead of refusing IP literals. plugin-ntfy: accept an http:// server on a local endpoint through request.host_allowed(url) (port 80 or an explicit one), keep https for public servers and its resolved-address checks, and document the network_local entry.

Provisional decisions (#160, pending maintainer review)

  1. An llm step can be skipped on an empty input, and a skill can bind task.create fingerprints to the viewed input (#160). Provisional. Two compatible, opt-in additions: an optional llm.skip_when_empty in pipeline/v1.json and an optional task_fingerprint in skill/v1.json. Neither is in a pipeline or skill that does not write it, and the pipeline digest is unchanged for one that omits skip_when_empty (null is left out of the canonical form). Decision 66 is added by PR #159 and 62 by PR #155. Found building plugin-gmail#3 (plugin-gmail PR #5). A task.create link built from the fingerprint (item 3 of the issue) is not part of this decision; see F.
    • A, skip_when_empty. On an llm step, true, or a list of 1 to 16 input view paths (ViewPath, the syntax of a skill's input_view). It is evaluated on the viewed input (after the skill's view, before de-identification, the cache lookup and any model call). true: the whole viewed input is empty. A list: the values the paths reach are all empty (a path that reaches nothing is empty), so one non-empty listed field runs the step. A list path must lie on the skill's input view (be a prefix of a view path or extend one), else the plan fails with params_invalid: a path the model is never shown would be empty on every run.
    • B, what empty means. null, "", [], {}, and a list or object whose members are all empty in this sense, recursively. Any other string, any number (0 too) and any boolean (false too) is not empty. A view that does not match the input at all is still input_invalid (a degraded step), not an empty skip. A pipeline whose collect source also returns a label (source: "gmail.triage") is therefore not empty as a whole: list the field that matters ([].data.needs_interpretation), or drop the label from the skill's view.
    • C, how a skip is recorded. No llm[] entry (no call was made, so there is no backend, model or usage to state): the step is recorded with status skipped, no error, and output: {"skipped": "empty_input", "skill": "<skill>"}. Later steps run, as after an unchanged-input reuse; a skipped step is ok for the run's status, and a run that proposes no intent at all ends noop (the same rule as a reuse). RunRecord.input_hash stays unset and nothing is written to the LLM cache (no accepted output exists, and the cache is not even looked up). Cost is zero. A replay re-evaluates the same rule on the same recorded input.
    • D, task_fingerprint. A skill may declare task_fingerprint: {ids: <ViewPath>, prefix: <text>}. ids is an input_view path (or below one) whose string values (or the strings of a list value) are the ids; prefix is 1 to 64 characters of the fingerprint alphabet (A-Z a-z 0-9 . _ : -), e.g. gmail:. A task.create the skill proposes must carry a fingerprint equal to prefix + one of those ids, as exact strings in the viewed input; anything else (an id the input never held, the id without its prefix, a different prefix) refuses the whole batch. The manifest is invalid if ids is not in the input view or if task.create is not in intents (pydantic-only rules). Without the rule a task.create fingerprint stays free text, as before; the rule's content joins the skill digest (so the cache key) only when declared. Only strings are ids: a numeric id is never matched.
    • E, a refusal is a guard violation. The rule is part of the action guard (horae.engine.guard.check_intents, task_fingerprint), so a refusal is the existing guard violation and a guard_violation step error (the step is degraded, nothing of the batch is routed), and a cached output is re-guarded on reuse and dropped when refused (decision 46). The detail is fixed text with the position and the field, never the fingerprint: skill:<skill> proposed task.create #<n> with a fingerprint not from the input infingerprint`. Skill evals run the same check (judge_intents). It does not reusecheck_task_fingerprints(thetask.update_statuscheck, routing rule 4, which lives inhorae.engine.executorand fails asintent_unrouted): the executor imports the guard, and the issue asks for a guard violation. Both read the viewed input as exact strings;horae.engine.viewpath` holds the path reading the new code shares.
    • F, not done: a link template. Item 3 (link_template under links: none, built by the core from the fingerprint) is left out. Routing picks the tasks entry from the task's link, so an entry-owned template would have to choose the entry before the link exists; that circularity is not small. A skill under links: none proposes tasks without a link for now. A follow-up could add the template to the act entry (link_template + link_fingerprint_prefix, id URL-encoded, result checked against the entry's own link_prefix).
    • G, what plugin-gmail changes. In skills/gmail/triage-mail/skill.yaml, add task_fingerprint: {ids: "[].data.needs_interpretation[].id", prefix: "gmail:"}; in examples/triage-mail.pipeline.yaml, replace on_unchanged_input: skip by (keeping it is harmless) skip_when_empty: ["[].data.needs_interpretation"], and say in the prompt that a task's fingerprint is gmail: + the mail id.

Provisional decisions (#162, pending maintainer review)

  1. Accent folding, and plugin-declared personal fields the core enforces (#162). Provisional. Found by plugin-school-fr#4 (plugin-school-fr PR #7). Compatible additions: an optional provides.personal_fields in plugin-manifest/v1.json and an optional plugins.<name>.personal_fields in lockfile/v1.json (both regenerated; skill/v1.json is unchanged). Decision 62 is taken by open PR #155; 63 to 67 are merged. It amends decision 47 C (matching) and E (when de-identification runs).

    • A, accent folding. The matcher compares letters accent-folded on both sides, the known value and the scanned text: case-folded, decomposed (NFD), nonspacing marks (Mn) dropped (horae.llm.deid.fold). Zoe, ZOE, zoé and an NFD Zoé all match a known Zoé, and a known Zoe matches all of them. A letter run now also holds the combining marks that follow a letter (the main combining blocks), so a mark NFKC could not compose (Zo̱e) does not cut a name in two; a token made of marks only folds to itself (a symbol is never empty). Whole letter runs only, as before: Léo never matches inside Léonard, unless Léonard is itself a known value. The span of the text is replaced, whatever its spelling; re-identification puts back the canonical text (the classed leaf, personal value or vocabulary term first registered for those folded tokens), never the span as written: ZOE comes back as Zoé, as ALICE already came back as Alice (decision 47 G). Two classed values that fold alike (Zoé, Zoe) share a pseudonym. DEID_VERSION is 3 (part of the cloud cache key: older entries are a miss once).
    • B, the declaration. provides.personal_fields: {<tool ref>: [view paths]}, e.g. {school-fr.homework: ["children[].first_name", "homework[].teacher"]}. A key is one of the plugin's sources or transforms; the paths use the ViewPath syntax of a skill's input_view, relative to that tool's output (not to the step input), 1 to MAX_PERSONAL_FIELDS (64) per tool, none under another and none disagreeing with another on a value's shape (pydantic-only rules). A mapping keyed by ref, not sources[] objects: provides.sources stays a list of refs that every reader (host, replay, marketplace, SDK) already uses. The lock records it with the approved plugin (LockedPlugin.personal_fields, paths sorted, left out when empty, so a lock without any is written exactly as before and an older core still reads it). The installer (#46, after PR #155's Installed.lock_entry) copies the manifest's declaration; no approval is needed, since a declaration only adds protection. In force is the union of the installed manifest's and the lock's (each tool's paths reduced to the outermost ones, merge_personal_fields): a manifest edited after approval, or a stale lock, can never drop a field. horae replay reads the lock's (LockRegistry), so a replay de-identifies as the run did.
    • C, which output reaches which step. One value flows through a run (the engine's "data between steps"); the plan follows the declared paths along it:
    • after a collect step, each declared path p of a source of that step is at [].data.p of the step's output ([].data[].x for [].x). The class applies to every element of the list, so another source's field at the same path is protected too (over-protection, never under);
    • a later collect step starts a new value: its own sources' paths replace them;
    • a transform that declares personal_fields replaces them with its own paths, relative to its output: it takes responsibility for where personal data went; a transform that declares none, when personal paths are in force, loses them (the core cannot know where it put them); one that runs before any personal path changes nothing;
    • every tool that ran adds the values found at its declared paths (every string leaf and object key at or below them, NFC, non-empty) to the run's personal values, whichever step it ran in;
    • at the llm step, the located paths are added to the skill's input view options as {class: person}, applied to the viewed input (the view keeps the input's shape): a skill class person, email, phone, place or amount at or above a path already hides it and is kept; a free_text class at or above it (which means the same as no class) and any class below it are dropped, so no classed path lies under another. The personal values are known person values (with their name parts, decision 47 C) looked for in every string and key of the viewed input. So a skill without classes is protected, and so is a name mentioned in a description the skill views while it does not view the field itself.
    • A personal path the skill's view does not select is not an error: that field is not sent at all, and its values are still looked for in what is sent.
    • D, cloud only. As decision 47: a local alias is sent the viewed input unchanged. The request is marked classified whenever personal paths or values reach the step, so without a policy ModelBackends refuses it for a cloud alias (deid_required).
    • E, fail closed (nothing is sent, nothing is billed; the messages name a tool and a path, never a value), only for a cloud alias:
    • while planning, an llm step after a transform that lost personal paths fails with deid_unavailable before any plugin is called (an alias the policy cannot classify counts as cloud);
    • at the step, an output that contradicts the shape of its declared path (an object where the path reads an array, a scalar where it reads either; an absent key or null is fine) degrades it with deid_unavailable: the field cannot be located;
    • the pseudonymizer refuses (deid_unavailable) more than MAX_PERSONAL_VALUES (4096) values, a value longer than 1 KiB or 48 tokens (it could not be found in text), and, after rewriting, any personal value still found in clear in a string or key of what would be sent (pseudonyms put aside; a check against its own bugs). The cache, a replay's reuse and the repair retry all use the same de-identified input (decision 47 E: an entry is reused only with the same de-identified digest).
    • F, horae eval. A case's input is read as a collect output: an element whose source is a tool with personal_fields gets the same paths and values, offline and live. Amended by M (#165): the source is resolved among every plugin horae eval knows, not only the skill's own.
    • G, limits. Not matched: a value of fewer than 2 characters in text, a name part of fewer than 3 letters (Al of Al Martin; 2 in a script without spaces, J), nicknames, initials, typos and transliterations (Zoë is Zoe by folding, Zoja is not). A whole number of fewer than MIN_NUMBER_DIGITS digits, or a fraction, under a personal path is protected where the path is located, not in text (L). Folding over-matches (Zoe and Zoé are one name). The declaration is as good as the plugin that writes it.
    • H, SDK 0.7.0. Plugin.source(ref, personal_fields=[...]), Plugin.transform(ref, personal_fields=[...]) (also the personal_fields= argument of Source / Transform), and manifest(..., personal_fields={ref: [paths]}), written as provides.personal_fields only when non-empty and checked like the core (a tool of the plugin, a path, 1 to 64, no duplicate, overlap or shape disagreement).
    • I, what plugin-school-fr changes. Require horae-sdk>=0.7; register each source that returns normalize(...) data with personal_fields=list(DEIDENTIFIED_FIELDS) (children[].first_name, homework[].teacher, grades[].teacher) and regenerate plugin.yaml (python -m horae_school_fr --manifest), which then holds provides.personal_fields: {<source ref>: [...]}; keep input_view() as guidance; drop NameScrubber (the core now folds accents) or keep it as harmless defence in depth, and flip tests/test_deid.py's accent test from documenting the gap to asserting that Zoe is caught, plus a test that a skill without classes sends no name; update the README's "Limits" (accent folding done, a skill without classes is now protected).

    Amendment (#165, the review of #163). DEID_VERSION is 4 (the matching changed: older cloud cache entries are a miss once). plugin-manifest/v1.json and lockfile/v1.json are regenerated (a personal_fields path may carry the free_text: prefix); horae-sdk 0.9.0. - J, scripts without spaces, names glued to another script. A letter run is cut where its script changes (the first word of the letter's Unicode name: LATIN, CYRILLIC, GREEK...), and into single letters (each with its combining marks) in a script written without spaces between words: Han, kana, Bopomofo, Hangul (a particle is glued to a name: 민수가), Thai, Lao, Khmer, Myanmar, Tibetan, Yi (horae.llm.deid._spans). Known values and scanned text are cut the same way, so Zoé is found in Zoé様, 宿題はZoéが and ZoéΣ, 山田 in 山田さんは, 山田花子 in 今日は山田花子さんが. Within one script that has spaces the whole-word rule stands: Léo never matches inside Léonard, nor Zoé inside MarieZoé (a limit: cutting at a case change would also cut McDonald or DeVries, whose folded forms must keep matching Mcdonald and DEVRIES, and match names inside ordinary words). A name part written in a script without spaces needs 2 letters, not 3 (花子 of 山田 花子; a Han or Hangul letter is a syllable); a single letter is never looked for. The middle dots · and ・ separate name parts (玛丽·杜邦, マリー・デュポン). In those scripts a value over-matches inside a longer word (山田 in 山田町), privacy over meaning, and a value of more than 48 letters is too long to be looked for (one token per letter). The check after rewriting (E) reads text with the same tokens, so the scanner and the backstop share every rule. - K, scan-only free-text fields. A personal_fields path may be prefixed by free_text: (free_text:messages[].body): free text that may mention personal data. It is followed through the plan like any personal path (a transform that drops it fails closed for a cloud alias), its shape is checked, and at the llm step it is classed free_text (scanned for the personal values and the vocabulary; the request is classified, so de-identification runs, or a cloud alias without a policy is refused), unless a classed path lies at, above or below it. Its content is not a personal value: it is neither replaced as a whole nor looked for elsewhere, so a long body never makes the step refuse. A plain personal field keeps the hard refusal of a value over 1 KiB or 48 tokens (E). A prefix, not a new key or an object: the declaration stays a list of strings, so the installer copies it into the lock as before; the approval prompt lists scan-only paths apart ("scanned ... not de-identified as values"), and horae plugin upgrade (decision 73) shows turning x into free_text:x as the personal field x removed, a widening that needs approval, and x (scan-only free text, not de-identified as a value) added. In the union of the manifest's and the lock's (B), a path personal in one and scan-only in the other stays personal, and a scan-only path at or under a personal path is dropped. One tool's paths, prefix or not, may not overlap or disagree on a shape. - L, personal numbers. Every whole number (not a boolean) of at least MIN_NUMBER_DIGITS (6) digits at or below a personal path is a personal value too (its decimal digits, without a sign; an integral float too): it is looked for in text (a whole digit run), whatever the separators in a run of digits and phone separators: by its last nine digits anywhere in the run when it has nine or more (33612345678 is found as 06 12 34 56 78), by all its digits at the end of the run after at most four other digits (a trunk 0, a country code) when it has 6 to 8 (91234567 in +65 9123 4567, 123456 in 123-456 and 0123456); the same for a personal string written as a phone number. A number of the input (an integral float too) outside its own field is replaced ([PERSON_n], a string) when its digits equal a personal number's or match it by the same rule (612345678 for 33612345678). The check after rewriting applies the same rules to text and numbers. Six digits: phone numbers, national, student and account identifiers have six or more, while years, days, counts, quantities and most amounts have fewer and would otherwise be replaced all over the input. Shorter numbers and fractions are still pseudonymized where they sit (their path is classed person). - M, horae eval across plugins. A case element's source is resolved as a collect step resolves its tool (PluginRegistry.plugin_for_tool), through every plugin horae eval knows: the instance's HostRegistry (manifests and horae.lock, the declarations in force a run uses, B), or, with --plugin-dir, every valid manifest of the folder (horae.evals.ManifestRegistry; two plugins providing one tool are refused, as the host does). A limit remains: a case is read as a collect output, so a case that stands for a transform's output (no source elements) gets no declared fields; eval cases are synthetic.

    Amendment (#189, a follow-up of the review of #187). DEID_VERSION is 5 (more text is matched: older cloud cache entries are a miss once). - N, given names of unspaced CJK and Hangul names. A full name stored without a space (王小明, 김민수, 山田花子) had no name parts, so its given name alone (小明的作业, 민수야, 花子さん) was sent in clear, and a one-letter surname is never a part (王老师 for 王 小明). Now each name part written only in Han letters (with or without kana) or only in Hangul syllables, of at most 6 letters (MAX_UNSPACED_NAME_LETTERS), is also split into a surname and a given name at every length its script allows (horae.llm.deid._surname_lengths), and each piece of at least 2 letters is a name part of its own, mapped to the whole name: - Korean: a surname of one letter (김 + 민수), of two for a compound surname of a short known list (KOREAN_COMPOUND_SURNAMES: 남궁, 황보, 제갈, 선우...), one or two for an unknown name of four letters or more; - Chinese and Japanese (Han alone cannot tell them apart): one or two letters up to four (王 + 小明, 欧阳 + 娜娜, 山田 + 花子, 林 + 花子; a 3-letter name also gives 王小, a 4-letter one 田花子), one to three from five (長谷川 + 一郎). Every split is kept, so a wrong guess pseudonymizes more, never less; a Chinese compound surname needs no list (the two-letter split covers it); - kana alone is not split (mostly a foreign name, マリー), nor a longer part, nor a part in any other script. A one-letter surname (a one-letter part, or the first letter of a part split after it; of a two-letter part only when it is the whole name, 王明) is looked for only when a title follows it, glued or after one white-space run (HONORIFICS: 老师, 先生, 女士, 小姐, 校长, さん, サン, 様, 君, ちゃん, 씨, 님, 선생님... simplified and traditional; halfwidth kana reads as fullwidth); only the surname is replaced ([PERSON_1]老师), and re-identified as the whole name (王小明老师, privacy over meaning, as for any part). A single letter is still never matched alone (王是, 国王, 김가). Every title entry is added after every person's name parts (in the scanner and the backstop), so a real part always wins (君 of 王君 Wang is never taken as the title of 王 of 王小明). Overlaps. Matching is leftmost-longest without overlap, so a piece of one name could end inside another known value and leave its rest in clear (王小 of 王小红 in 王小明, 明 sent). A match that ends inside a run of letters of a script without spaces is therefore replaced together with every known value that starts inside it and ends past it, extended until none does, as one pseudonym (the first match's person): 王小明 is [PERSON_1], 양양민 for 양민 is [PERSON_1]; a title is kept only when no other known value starts inside the match (王 君华 for 王君华 is [PERSON_1], not [PERSON_1] 君华). Elsewhere a match ends at a word's edge and the rest is unchanged. The scanner and the backstop (E) build their parts and titles with the same functions (_name_parts, _titles), for every personal value whatever its length (王 with 王老师). Names in scripts with spaces are split exactly as before; MarieZoé (glued within one script) stays a limit. The tradeoff. Two Han or Hangul letters are a common word as often as a name, so a given name over-matches: 小明 inside 大小明显, 花子 in unrelated text, 민수 inside 시민수업 (a civics class), and the extra splits (王小, 田花子) do the same. It pseudonymizes more text than the name, which can blur what the model reads (and, at worst, a sentence comes back with the whole name where only the word was), but it never sends a name in clear: the failure is toward refusing, the direction decision 47 chose; an overlap union replaces a whole run of letters that held two names under the first one's pseudonym. A title before the surname (老王, 小王), or split from it by a sign (王・老师) or inside itself (王老 师), is not looked for: 小 + surname would also hit common names and words (小林), and it leaks one letter at most.

Provisional decisions (#45, pending maintainer review)

  1. Per-plugin virtual environments (#45). No schema change. horae plugin add passes horae.marketplace.environment.PluginEnvironment as install(..., prepare=) (decision 62 G): it builds the plugin's own venv in the verified scratch tree, <tree>/.venv, before the atomic rename, so plugins/<name>/.venv exists exactly when the plugin does, and a failure leaves nothing. Plugins never share a dependency.
    • A, what a plugin ships. A pyproject.toml with a [project] name and a committed uv.lock, else the install is refused before uv runs. In the lock, every package but the plugin's own project (whose source is the tree, .) comes from an index or URL, has at least one wheel, and has a sha256 hash for each of its files. An sdist-only package, a git source (no hash), another in-tree package or one outside the tree is refused, the message naming it. A committed .venv is refused.
    • B, the build backend allow-list. build-system.build-backend must be one of hatchling.build, setuptools.build_meta, uv_build, flit_core.buildapi, pdm.backend; build-system.requires may name only that backend's distribution (and wheel for setuptools), never with a direct URL; backend-path (an in-tree backend) and tool.uv.package = false (a virtual project, which would not be installed) are refused. The allow-list covers the only build that happens (dependencies are never built, C). It narrows, but does not remove, code execution at install time: a backend runs the project's own build code (setup.py, a hatch build hook) as the Horae user, before #46 shows the permissions, and the backend's own version is not hash-pinned (uv resolves build requirements, which are not in uv.lock). uv_build is recommended: uv carries it, nothing is fetched. Isolation is M5 (#51, #52); accepted for first-party plugins meanwhile (T04, docs/security.md T39). Provisional amendment (#191, decision 79 G). A plugin that is not first-party is never built: uv sync --locked --no-dev --no-install-project installs only its dependencies (same hashed-wheel rule), dynamic metadata is refused (uv would run the backend for it), and a .pth makes the tree's sources importable inside its container. So the residual risk above is first-party only. Such an install also uses its own uv cache, never <state_dir>/uv-cache, and every lock's registry files must come from the registry's own host (decision 79 H).
    • C, the commands. uv venv --relocatable --no-project --python <python> .venv, then uv sync --locked --no-dev --no-editable --python .venv/bin/python --no-build-package=<name> for every dependency of the lock, both with --no-config. Only the plugin's own project is ever built: a dependency installs from a hashed wheel, and when none fits the machine uv refuses rather than build its sdist (whose backend, not on any allow-list, would run code). --locked reads the lock and fails if it no longer matches pyproject.toml (never re-resolves, never writes; --frozen is not used, it would skip that check); uv checks every file against its hash; the project is built and installed non-editable, so the tree's sources are not imported at run time. The venv is relocatable (its scripts find their interpreter relative to themselves), so it works after the rename; the install checks pyvenv.cfg still says so.
    • D, the interpreter. <python> is Horae's own interpreter (sys.executable; in the image /opt/venv/bin/python, i.e. the image's CPython), a constructor argument. requires-python is honoured: a plugin that does not accept it is refused. No Python is ever downloaded (UV_PYTHON_DOWNLOADS=never), so what the venv links to is on the machine at run time too.
    • E, uv's environment. Built from scratch: PATH=/usr/local/bin:/usr/bin:/bin, an empty temporary HOME/TMPDIR, LANG=C.UTF-8, UV_NO_CONFIG=1, UV_PYTHON_DOWNLOADS=never, UV_LINK_MODE=copy, UV_PROJECT_ENVIRONMENT=<tree>/.venv, UV_CACHE_DIR=<state_dir>/uv-cache. Only the proxy and CA variables (*_PROXY, SSL_CERT_FILE, SSL_CERT_DIR) are inherited: they say how to reach the network, never what to fetch. No UV_*/PIP_* index setting is inherited; the index is uv's default or the plugin's own pyproject.toml, and the hashes pin the bytes either way. index_url (--default-index) is a constructor argument only, never a horae.yaml setting: tests pass a local file:// index.
    • F, limits. Each uv call at most 600 s; what the install writes at most 1 GiB: the venv, uv's temporary directory (sdist and build environments) and what it adds to the shared cache (its size before the install is the baseline), measured while uv runs (killed past it); pyproject.toml and uv.lock at most 4 MiB each. uv's failures are InstallRefused (exit 3) when the lock, a hash or requires-python is at fault, else InstallError (exit 1); uv missing is InstallError.
    • G, run time: how runtime.command maps onto the venv. A plugin directory with .venv/pyvenv.cfg and .venv/bin/python has a venv (horae.plugins.host.env. plugin_venv). For such a plugin, a bare command[0] (python, python3, or a console script the project declares) is looked up in <plugin>/.venv/bin first, then on the base PATH, and kept as found (not symlink-resolved: the venv's python is a symlink its interpreter needs as argv[0]). So a plugin writes command: [python, -m, <module>] or command: [<console-script>]. An absolute command and a relative path are unchanged (the contract before #45; a relative .venv/bin/python resolves outside the plugin and stays refused). The child's PATH starts with <plugin>/.venv/bin and VIRTUAL_ENV names the venv. Every plugin child, with a venv or not, gets UV_OFFLINE=1, UV_PYTHON_DOWNLOADS=never and PIP_NO_INDEX=1 (OFFLINE_ENV; they were already denied as secret names). Running a plugin needs neither uv nor the network.
    • H, upgrade. The venv belongs to the installed tree. An upgrade (#47) installs the new version through the same install(..., prepare=PluginEnvironment(...)) into its own scratch directory, so it gets a fresh venv from its own lock, and swaps the tree; a venv is never updated in place. #48 (install from a git URL) passes the same prepare.
    • I, the container image. The image ships no uv (decision for #40: no package manager at run time) and needs none to run plugins. horae plugin add inside the container fails with "uv is not installed" (exit 1). A venv links to the interpreter that built it, so it must be built by the image's own Python: giving the image an install-time uv (or an installer variant) is a follow-up. The built-in plugins run from /opt/venv, unaffected.

Provisional decisions (#46, pending maintainer review)

  1. Permission approval at install, and horae.lock written by horae plugin add (#46). No schema change (lockfile/v1.json is as decision 68 left it). Decision 69 is left to #45. It completes decision 62 F: an install is now approved and pinned in one command.
    • A, the prompt. After the verified install (decision 62 A to D), before the tree is moved into place (the prepare hook), horae plugin add shows what plugin.yaml asks for, grouped and labelled: network (https hosts); local network (plain http allowed) on its own (decision 66); secrets, required and optional; intents, each with a one-line meaning (horae.marketplace.approval.INTENT_MEANINGS, one for every intent of the closed set, tested); paths, read and read-and-write. provides.personal_fields are shown as information ("de-identified before cloud models"), never approved (decision 68 B). With --json the prompt goes to stderr and stdout keeps one JSON document.
    • B, approval. Interactive confirmation, default no (an empty answer, end of input or Ctrl-C is a no). --yes / -y approves only when horae.lock already has an entry for this name with the same version and commit and permissions identical to what is asked (canonical comparison, extra grants included), e.g. a Docker build from a committed lock; otherwise it is refused, naming the difference. No terminal (stdin is not a TTY) and no --yes is refused. Every refusal is exit 3 (approval_refused) and leaves nothing in plugins/ and horae.lock unchanged. An interactive approval of a plugin whose lock entry differs (another version, from a lock with no installed tree) replaces that entry, and says so first.
    • C, extra grants. --allow-host HOST (a Hostname) and --allow-local HOST:PORT (a LocalEndpoint), repeatable, add grants beyond the manifest; they are shown "(added by you)" and written to the lock. A lock may grant more than a manifest declares (the host refuses only less, decision 66): this is how a user approves their own school or Home Assistant host. An invalid value is a usage error (exit 2). With --yes they must be given again (the request must be identical to the lock). Nothing else can be added (paths, secrets, intents come from the manifest only).
    • D, the lock file. horae.marketplace.lock: the whole lock is rewritten atomically (temporary file in the instance directory, fsync, rename, fsync of the directory, the file's mode kept) under an exclusive, non-blocking flock on <state_dir>/horae.lock.guard held for the whole add (read, install, prompt, write); a second writer is refused with exit 5 (lock_busy). Canonical text: the contract's serialization (plugins and lists sorted, empty network_local / personal_fields omitted), then block-style YAML with sorted keys, no wrapping, a trailing newline, after the leading comment lines of the existing file (a new file gets a short default header). Re-serializing is byte-stable, and adding a plugin adds only its own lines (tested). horae init writes its lock with the same function. A horae.lock that does not validate is never rewritten. The entry is Installed.lock_entry(approved); it must equal the approved one or the install is undone. If the lock cannot be written, the placed tree is removed (exit 1, lock_write_failed).
    • E, tier (docs/security.md T04). Before M5, horae plugin add refuses a plugin whose marketplace tier is not first-party, before anything is fetched (exit 3, tier_refused, pointing to M5). The tier is a claim in the index file, so first-party is believed only from the default Horae marketplace (FIRST_PARTY_INDEXES): an index the user added cannot vouch for itself. require_installable(name, tier, index) is the one check; a direct install from a git URL (#48) passes tier=None, which is refused the same way. Provisional amendment (#191, decision 79). "Before M5" is now "under the process runtime": a plugin that is not first-party (another tier, first-party claimed by an index the user added, a direct install) installs when its effective runtime in horae.yaml is container, and only then; first-party plugins install under either runtime. require_installable(name, tier, index, runtime=...) stays the one check, and the lock records tier and index for such a plugin so the host can enforce it at run time.
    • F, at run. HostRegistry.from_directory already refuses a manifest asking for more than the lock grants and a version other than the locked one. It now also reads the install record plugins/<name>/.horae-install.json (decision 62 F) when there is one: its name, version, repo and commit must be the lock entry's, else the plugin is refused (plugins_invalid): an installed tree that is not the approved one. The record must be a regular file (no symlink) of at most 64 KiB holding a JSON object. A plugin without a record (the built-in ones horae init installs, a plugin copied by hand) is checked by its manifest only: an accepted gap until the files of a plugin are pinned (#47 or M5).

Provisional decisions (#48, pending maintainer review)

  1. Direct install from a git URL (#48). No schema change. horae plugin add https://<host>/<owner>/<repo>@<sha> installs without any marketplace.
    • A, the reference (horae.marketplace.direct). An argument holding : or / (a plugin name never does) is a git URL. It must start with https:// (no http, file, ssh, git, ext:: or scp-style git@host:path), carry no user info, be a GitRepoUrl (the contract horae.lock stores: DNS host, no port, IP literal or localhost, no ./.. segment, query or fragment) and be pinned after its last @ to a full commit SHA (CommitSha: 40 lowercase hex digits, or 64 for a SHA-256 repository). A tag, branch or abbreviated SHA is refused: what is approved is one commit. Any refusal is a usage error (exit 2, usage); no error repeats the URL (a token may sit in its user info, query or fragment). --pre and --offline do not apply to a URL (no index is read, the repository must be fetched): each is a usage error (exit 2).
    • B, the gate (docs/security.md T04). A direct install has no marketplace tier, so require_installable(url, None, None) refuses it before M5, after the reference and the instance are read and before anything is fetched (exit 3, tier_refused). The whole path behind the gate is implemented and tested with it open; lifting it in M5 is approval.DIRECT_INSTALLS = True. Provisional amendment (#191, decision 79). DIRECT_INSTALLS is gone: the runtime is the one switch. A direct install is refused before anything is fetched when horae.yaml runs no plugin in a container, and once the commit's plugin.yaml names the plugin (before approval) unless that name's effective runtime is container.
    • C, the fetch (PluginInstaller.install_commit). The commit is never fetched by its id: a forge may serve, through a repository's URL, objects that exist only in a fork or a pull request (GitHub does), and the approval and the lock would then name the trusted repository for a fork's code. Instead git ls-remote --refs -- <url> refs/heads/* refs/tags/* lists the repository's own tips (names of A-Z a-z 0-9 . _ / - only; refs/pull/* and anything else is ignored; none is a refusal, more than MAX_DIRECT_REFS = 1000 too), an empty bare repository fetches exactly those refs (--depth=MAX_REACH_DEPTH, 1000 commits, --no-tags --no-recurse-submodules, the byte budget of the download), and merge-base --is-ancestor <sha> <tip>^{commit} must hold for at least one tip. Otherwise, a commit further than the depth from every tip included, the install is refused (exit 3, install_refused): fail closed. No tag is compared: the SHA is the pin. Then the same steps and limits as decision 62: the tree checks (paths, file count and size, no submodule, no escaping symlink), the hardened git (https only, no hook, no LFS smudge, no filter, no user or system config), the checkout without .git, and the atomic placement. The name and version are those of the commit's plugin.yaml; the name is checked against plugins/ once the manifest is read, before approval.
    • D, approval and lock. The same prepare chain as a marketplace install (decision 70): the permissions are shown and approved first, then the venv is built (decision 69), so a declined plugin's dependencies are never installed. The horae.lock entry is the usual one: version from the manifest, repo the URL as given, commit the SHA. --yes passes only when the lock's entry for that name has the same repository (exact string), version, commit and permissions. The --json report has tier and index null.
    • E, open. A lock entry does not say whether it came from a marketplace or a direct install (LockedPlugin.commit is documented as the commit the version's tag points to, which a direct install does not check). upgrade (#47) will need to tell them apart: a source field, or "no index lists this repo", is left to it. (Settled by decision 73 A: source: direct; #191 adds the upgrade of a direct install, decision 79 E.)

Provisional decisions (#133, pending maintainer review)

  1. A pipeline pack's pipelines are installed by horae plugin add into pipelines/<plugin>/, approved with the plugin and pinned in horae.lock (#133). One additive schema change: lockfile/v1.json gains plugins.<name>.pipelines (G). (#48 took 71.)
    • A, where. <instance>/pipelines/<plugin>/<pipeline>.yaml, one directory per pack. The instance loader (horae.config.loader) reads pipelines/*.yaml as before and now also pipelines/<dir>/*.yaml, one level down; a directory whose name starts with . or has a suffix, and a symlinked directory, are skipped. A pipeline's name is still its file's stem and still unique in the whole instance (a second definition is the existing "defined twice" problem). A directory per pack, not a prefix in the file name, because the name of a pipeline is the file's stem and a prefix would change what horae run is called by; and so that remove and upgrade (#47) delete exactly one directory.
    • B, what is a pack. A plugin whose manifest lists provides.pipelines. The pack's pipelines/ holds exactly those names as plain <name>.yaml files (a missing file, an undeclared one, a .yml, a directory or a symlink is a refusal). A plugin that lists none is not a pack and installs nothing here.
    • C, when and how. Inside the existing flow, as a prepare step before the tree is moved into place. The check runs first (it only reads, so the approval can show what it found); the approval and the venv build follow: every file is read once (at most 1 MiB, regular file, no symlink, resolving inside the tree), parsed with the loader's safe YAML reader and validated as a Pipeline, and its name must be its file's. The installer itself refuses a symlink under pipelines/ in the git tree (a checkout with core.symlinks=false would turn it into a file holding the link target). Any failure is install_refused (exit 3) and nothing is written. The validated bytes are written to a scratch directory pipelines/.install-* and renamed to pipelines/<plugin>/ after the tree is placed; if that or the horae.lock write fails, both are undone.
    • D, never overwrite. The install is refused if pipelines/<plugin>/ exists (the plugin is not installed at that point, so it is not ours) or if another pipeline of the instance already has the name of one of the pack's. #47 must delete the recorded files before a reinstall, which is what makes "a file this pack installed before" replaceable.
    • E, the record. The relative paths are added to the install record, key pipelines (plugins/<plugin>/.horae-install.json, decision 62 F), for #47. The host compares only name, version, repo and commit, so the extra key is ignored there. --json carries pipelines too.
    • F, what is not checked. Instance-level references (a model alias, a tool nobody provides, a time zone) are checked by horae doctor and at run time, as for a pipeline written by hand: a pack cannot know the instance.
    • G, approval and the lock (security review). A pipeline is code the core runs on a schedule, so it is approved like a permission. The prompt lists, per pipeline, its name, its trigger (cron and time zone, or "manual or external trigger only") and the tools and skills it calls. horae.lock records pipelines: {<name>: <sha256 of the file>} for the pack (left out when empty, names sorted); lock_mismatch compares it, so --yes refuses a pack whose pipelines differ, and the entry written must equal the approved one.
    • H, only an enabled, locked pack runs. The loader reads pipelines/<plugin>/*.yaml only if <plugin> is listed under plugins: in horae.yaml and has an entry in horae.lock, and a file only if its SHA-256 is the locked one for that name (else a problem naming the file; an unlisted name counts as not approved). So the scheduler, horae run and the budgets see no pipeline of a disabled or removed plugin. Installing does not enable: the output says so.
    • I, tools of other plugins: warn, not refuse. A pack's own manifest has no dependency list, and real packs exist to call other plugins (obsidian.*, ntfy.*), so refusing would make every pack unusable. The prompt instead prints, under each such pipeline, a warning: calls plugins other than <pack> (<namespaces>) line; those tools run with the permissions of the plugins that provide them, which horae.lock already pins. A pack dependency list is a possible follow-up.
    • J, review fixes. A pack is recognised by structure, never by name: the loader treats a file as a pack's when its directory is not <instance>/pipelines itself, so a plugin named pipelines (installed to pipelines/pipelines/) gets every gate; the name pipelines is also refused at install. A pipelines/<dir> is a pack's only if the lock entry of that plugin has a non-empty pipelines map; otherwise the directory is ignored (as before this decision, so an instance upgraded from an older lock keeps working) with a logged warning. The prompt also prints each call's parameters (act and notify targets: path, mode, url, link_prefix, topic...; at most 160 characters each) and each llm step's model and budget.
    • K, amendment (#173): exclusive placement. D's "never overwrite" was a lexists check followed by rename, which on POSIX silently replaces an empty directory created in between. The scratch directory is now placed with rename_noreplace: renameat2(RENAME_NOREPLACE) on Linux, an exclusive mkdir of the target plus a move of the files through directory descriptors elsewhere. A target that exists, empty or not, is refused (install_refused, nothing left behind, the lock not written). The same primitive moves an upgraded pack's old directory aside and puts it back on rollback (decision 73); remove only deletes. No schema change.

Provisional decisions (#47, pending maintainer review)

  1. horae plugin upgrade with a permission diff, remove and audit (#47). One additive schema change: lockfile/v1.json gains plugins.<name>.source (A). Commands in horae.cli_plugin_manage; the diff and the swap in horae.marketplace.upgrade, what is read from disk in horae.marketplace.audit.
    • A, where a plugin came from (settles decision 71 E). LockedPlugin.source is direct for a direct install from a git URL and absent for a marketplace install, so every lock written before stays byte-identical and valid (a built-in plugin of horae init has none either). It is approved with the rest: lock_mismatch compares it, so --yes never turns one kind into the other. The install record (decision 62 F) also gets source and, for a marketplace install, the tier and index that resolved it: information for audit only (the host still compares name, version, repo and commit). A lock entry, not "no index lists this repo", because the answer must not change when an index does, and because the lock is what the user reviews and commits.
    • B, horae plugin upgrade NAME[@VERSION] (--pre, --offline, --yes, --allow-host, --allow-local, --allow-downgrade, --json). Only a plugin installed by horae plugin add (a lock entry and a tree, a real directory with an install record naming it) can be upgraded; a built-in or hand-copied plugin is not_installed (exit 3). A source: direct entry goes through require_installable(name, None, None): refused before M5 (tier_refused), and behind the gate still refused, pointing to remove then add URL@SHA (an upgrade resolves through a marketplace). Superseded by decision 79 E (#191): upgrade URL@SHA upgrades a direct install. The new version is resolved as add does (marketplace_pins, --pre) and the tier rule applies again (a plugin whose index no longer says first-party is refused). A lower version than the installed one is refused (downgrade_refused, exit 3) unless --allow-downgrade; a version the index now pins to another commit than the installed one is refused (install_refused, a moved release or a tampered index); the installed version and commit with nothing new asked is a no-op (exit 0, upgraded: false).
    • C, the permission diff. Against the horae.lock entry (what was approved), item by item, + added, - removed, ~ changed: repository, source, network, network_local, secrets (required and optional together; a move between them is ~), intents, paths read and write, personal fields and pack pipelines (by digest). Widening, marked "new: needs approval": anything added; a pipeline added or changed (new code the core runs); a personal field dropped (less protection, decision 68); another repository or source. Removals are shown but need nothing. When something widens, the full request (decision 70 A, with the pipelines' calls) follows the diff.
    • D, grants. The hosts and local endpoints the user added (--allow-host, --allow-local) are kept and said so, and do not widen. New flags add to them and do widen. Nothing else is carried over: a host the old manifest declared and the new one drops is gone. Amendment (#175). The first version worked the user's grants out as the lock's hosts minus the hosts of the installed plugins/<name>/plugin.yaml. That file is not verified (a plugin running as the user can rewrite it, and a killed upgrade can leave the new tree in place under the old lock), so a host the old version declared could be relabelled "added by you" and stay granted. add and upgrade now record the user's grants in the lock entry, plugins.<name>.user_grants (network, network_local), and an upgrade carries over only those. A lock entry, not the install record: the lock is what the user reviews, commits and approves, it is written atomically with the approval, and user_grants must be a subset of permissions (a lock that lists a grant it does not give is invalid); the record lives in the plugin's own tree, the very place the bug came from, and a killed upgrade leaves the new version's record there. The field is optional and omitted when empty, so a lock written before it, or for an install with no --allow-*, is byte-identical; lockfile/v1.json gains the optional property (additive). lock_mismatch does not compare it (the permissions it grants are what --yes approves). Legacy entries have no record: the manifest at the pinned commit would need a fetch of the old commit (no clone is kept, and --offline must work), so nothing is carried over, failing toward fewer grants. The upgrade prints a note naming the old hosts and endpoints the new version drops and asks to pass --allow-host / --allow-local again if the user added them; the next upgrade records them.
    • E, approval. Interactive confirmation, default no. --yes passes only when nothing widens, which includes a lock that already approves the target (a lock committed from another machine: the diff is then empty). Without a terminal and without --yes, refused. Every refusal is approval_refused (exit 3) with nothing changed.
    • F, atomic. Under the lock guard (decision 70 D), held from reading the lock to writing it: the new version goes through the same hardened install (decision 62, install(..., replace=True)), its pack pipelines are checked, the approval runs, and its venv is built (decision 69) in the scratch tree, which is then renamed to plugins/.upgrade-new-<name>-* (swept after an hour if a kill leaves it). Then, in order: the old tree to plugins/.upgrade-old-<name>-*, the new one to plugins/<name>, the old pack directory aside and the new one in, the lock written. Any failure undoes the steps done, newest first: the old tree, venv, pipelines and lock are as before (exit 1, upgrade_failed, or the install's own error). The old copies are deleted only once the lock is written. A kill between the two tree renames leaves no plugins/<name> (the host refuses to run, plugins_invalid) and the old tree in .upgrade-old-*, never swept: audit reports it. The venv is relocatable (decision 69 C), so the rename keeps it working. write_lock's commit point is its rename: the fsync of the directory after it is best effort, and its failure is a warning, never a rollback. An error (or Ctrl-C) that arrives once the lock write has started is checked against the file: if the new lock is in place, the upgrade (or a remove, or an add) is treated as committed and finished, so a lock and a tree never disagree while the message says nothing changed.
    • G, a pack's pipelines at upgrade. pipelines/<plugin>/ may exist only as a real directory holding nothing but the old version's own files: regular <name>.yaml files the lock approves for the plugin, each still with its locked digest. A file edited after approval, or any other entry, refuses the upgrade (it is never deleted: move it away or restore it). The name clash check of decision 72 D skips the pack's own directory. A plugin that was not a pack never touches pipelines/<plugin>/.
    • H, horae plugin remove NAME (--delete-secrets, --json). Refused while the plugin is listed under plugins: in horae.yaml (plugin_enabled, exit 3): the loader then reports a missing plugin and the instance stops loading, and its scheduled pipelines would stop mid-flight; disabling is an explicit step first. Refuse, not warn, so that remove never breaks a running instance. It removes the tree (with its venv, plugins/<name>/.venv), the lock entry and the pack's pipelines. The tree must be a real directory (a symlink is refused, never followed) with an install record naming the plugin; it is renamed aside (plugins/.remove-*) first, then the lock is written (on failure the tree is renamed back, lock_write_failed, exit 1), then deleted. A lock entry whose tree is gone is removed too (its pipelines checked against the lock).
    • I, what remove deletes in pipelines/. Only files that are a pipeline the lock approved for this plugin and that the install record lists as exactly pipelines/<plugin>/<name>.yaml (a record naming any other path is ignored), each opened with O_NOFOLLOW through a descriptor of pipelines/<plugin>/ itself opened with O_NOFOLLOW (a symlinked directory or file is never followed), a regular file whose SHA-256 is still the locked one. An edited, foreign or extra file is kept and listed; the directory is removed only if it is then empty.
    • J, what remove keeps. Its secrets (each listed with the reason), the files it wrote under its paths, and the run history in the store: listed under kept. No flag deletes the files under its paths (they are the user's vault) or the run history (shared by every pipeline). --delete-secrets deletes <secrets.dir>/<file> of each of its secrets that nothing else uses: no other locked plugin, no manifest under plugins/ (locked or not, built-in included), no secrets.refs name (a secret with an explicit reference is kept: delete it there by hand), model alias, push monitor or core secret, and no other {file:} reference or the de-identification vocabulary naming the same file, compared case-insensitively and by device and inode (a symlink or a second hard link to it keeps it). Only a regular file with one link is deleted (lstat through a descriptor of the directory, O_NOFOLLOW). Fail closed: a manifest under plugins/ that cannot be read keeps every secret. A secret read from an environment variable, a symlink, or a file that cannot be deleted is kept too; each is listed with the reason. Values are never read or printed.
    • K, horae plugin audit (--json). One row per plugin of horae.lock or of plugins/ (hidden entries apart): version locked and installed, source (marketplace, direct, or local without a record), tier and index from the record (null when not recorded), enabled, the granted permissions, personal fields and pipelines, and the last activity: when the latest stored run whose record lists the plugin started (Store.plugin_activity, the store opened read-only; null without a store). It reads horae.yaml and horae.lock alone, not the whole instance, so it runs on an instance the loader refuses because of the drift it reports.
    • L, drift (exit 4, EXIT_DIFFERENT; the JSON document is printed as usual with drift: true): not_installed (locked, no tree), not_locked (a tree, no lock entry), tree_invalid (not a real directory), record_invalid, record_mismatch (record vs lock), host_refuses (HostRegistry.from_directory refuses it: a manifest asking for more, another version), venv_missing (a recorded install without .venv), pipeline_missing, pipeline_changed, pipeline_unapproved (against the locked digests), and leftover (plugins/.upgrade-old-*, .upgrade-new-*, .remove-*, pipelines/.upgrade-old-*). A plugin without a record is checked by its manifest only (decision 70 F).
    • M, exits. upgrade and remove: 0 done, 1 configuration problem, a repository or index that cannot be fetched, an invalid or unwritable lock, 2 usage (a URL given to upgrade, a bad name or grant), 3 refused as above, 5 lock_busy. audit: 0 no drift, 1 configuration problem or invalid lock, 4 drift.

Provisional decisions (#49, pending maintainer review)

  1. A per-plugin container runtime (#49). One additive schema change to instance/v1.json: plugin_defaults.runtime, plugins.<name>.runtime and a container section (A, G). Code in horae.plugins.host.container; operator guide in docs/operations/plugin-containers.md.
    • A, where it is chosen. runtime: process | container, in horae.yaml: plugin_defaults.runtime (default process, the behaviour before #49) and plugins.<name>.runtime, which wins. The operator chooses, never the plugin: the manifest and the lock do not carry it, so a plugin cannot opt out. A plugin of horae.lock without a plugins.<name> entry gets the default.
    • B, the engine: Docker, through its CLI. docker run --interactive speaks MCP over the container's stdin and stdout, as the process runtime does over a child's pipes; the host's transport, timeouts, restarts and redaction are unchanged. Podman is not supported yet: its networking (netavark) and rootless user mapping differ, and the guarantees below were verified on Docker only. The CLI is container.docker (an absolute path) or docker on the base PATH (/usr/local/bin:/usr/bin:/bin); it runs with an allow-listed environment (the DOCKER_* connection variables, HOME, XDG_*), never a plugin secret. The engine must be local: DOCKER_HOST, when set, and the endpoint of the context the CLI uses (docker context inspect) must be a unix:// socket; tcp://, ssh:// or anything else is refused (a remote engine would receive the secrets over the network and bind its own host's paths).
    • C, the container. docker run --interactive --rm --init --pull never --log-driver none --user <uid>:<gid> --read-only --cap-drop ALL --security-opt no-new-privileges --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m,mode=1777 --network horae-plugin-<name> --mount type=bind,source=<plugin dir>,target=/plugin,readonly --workdir /tmp --entrypoint /usr/local/bin/python3 <image> -I -S -c <launcher> <command>. Docker's default seccomp profile applies (no --security-opt seccomp= is ever passed, nor --privileged, --cap-add, --device or a host namespace). The user is Horae's own uid and gid (so the plugin can read its tree, owned by Horae), and Horae refuses to start a container as root (uid 0). Only the plugin's directory is mounted, read-only; it holds the plugin's venv (.venv, decision 69), so nothing else of the host is visible: not horae.yaml, the store, /run/secrets, other plugins or Horae's environment. --init makes Docker's init PID 1, so a plugin's children are reaped and signalled with it. --log-driver none: the daemon keeps no copy of what a plugin writes (stderr may echo a secret). --pull never: nothing is fetched at run time.
    • D, the network. Each plugin gets its own bridge network, horae-plugin-<name>, created on first use with --internal (no route out), com.docker.network.bridge.enable_icc=false (no container talks to another) and com.docker.network.bridge.inhibit_ipv4=true (the host gets no address on it). The last one matters: on a plain internal network the host's own bridge address is the gateway, and every host service listening on 0.0.0.0 (Horae's API on a bare-metal install, sshd, a database) is reachable from the plugin; it was measured on Docker 29. Before every run's first start of a plugin, the network is inspected and must have exactly these properties, carry the label dev.horae.network=plugin, be neither ConfigOnly nor take its configuration from another network (ConfigFrom), and every container already attached must be labelled dev.horae.plugin=<name> (a concurrent run of the same plugin) or dev.horae.egress-proxy (reserved for #50's proxy); a network of that name that does not (created by hand, by an older Horae) is refused, never repaired or deleted. Containers that join after that check are not re-checked during the run. #50 attaches its egress proxy to these networks; until then a container has no egress at all, and permissions.network and network_local grant nothing in this runtime (they still travel in _meta).
    • E, secrets. Never on a command line and never in the container's configuration (docker inspect shows the image's ENV only). The host sends the plugin's environment (the same one the process runtime builds, decision 28, with container paths: HOME=/tmp/home, TMPDIR=/tmp/tmp, VIRTUAL_ENV=/plugin/.venv, its declared secrets) as the first line of the container's stdin, one JSON object; a launcher run by the image's interpreter (python3 -I -S -c, its source is a constant of horae.plugins.host.container, visible in docker inspect and secret-free) reads exactly that line, byte by byte so nothing of the MCP stream is consumed, sets umask 077, creates the directories, and runs the plugin command as its child with exactly that environment (#188: it stays, so that it can read the cgroup's OOM count once the plugin is gone; it passes the stop signals on). The values cross the CLI's connection to the daemon (the local socket) and live in the plugin process inside the container, readable by root on the host as any process's environment is. The host zeroes the preamble's bytearray once written, best effort only: the values were also strings (Secret.reveal(), the environment mapping, the json.dumps output) and the event loop may copy the bytes, so copies remain in Horae's heap until collected. The write is bounded by the plugin's startup timeout (startup_timeout past it), so an engine that stalls cannot hang a run.
    • F, the command. Resolved against the plugin's venv only: a bare command[0] must exist in <plugin>/.venv/bin (python, a console script) and runs as /plugin/.venv/bin/<name>; a relative path must stay inside the plugin directory (as in the process runtime) and runs as /plugin/<path>. An absolute command names a host path and is refused, and so is a plugin without its own venv (the built-in plugins, which run from Horae's own interpreter: set plugins.<name>.runtime: process for them).
    • G, the image. container.image, default python:3.12-slim-bookworm@sha256:<digest>: the same pinned base image the Horae image is built from (the PYTHON_IMAGE of the Dockerfile; a test keeps both equal and Renovate bumps them together). It must be pinned by digest (@sha256: and 64 hex characters), else horae.yaml is invalid. No image is built: a plugin's venv is linked to the interpreter that built it (decision 69 D), and the Horae image builds venvs with /usr/local/bin/python3.12, which this image has at the same path. So before a start the venv's pyvenv.cfg must name home = /usr/local/bin and a 3.12 version, else the plugin is refused with a message saying so (a venv built by another interpreter, e.g. on a developer's machine, cannot run in it). The image must be present (docker pull <image> once; checked with docker image inspect on each run's first container start).
    • H, fail closed. With runtime: container, a missing CLI, an unreachable daemon, a missing image, a network that is not as in D, a venv as in G, a refused command, Horae running as root, or a path Docker's --mount cannot carry (a , or ") fails the plugin with the new host error kind runtime_unavailable (nothing started; the plugin is unavailable for the rest of the run, like any failed start). The process runtime is never used instead.
    • I, stop. As in the process runtime (stdin closed, then SIGTERM, then SIGKILL of the CLI's process group; the CLI forwards the signals to the container), then always docker rm --force <name> (bounded, 10 s): a container whose plugin ignores EOF and signals is removed with everything it started. Containers are named horae-<plugin>-<random> and labelled dev.horae.plugin=<name>. A Horae killed with SIGKILL leaves its CLI's container running until the plugin exits on EOF; docker ps --filter label=dev.horae.plugin lists such leftovers (no automatic sweep: it could remove the container of a concurrent run).
    • J, Horae inside Docker. The image ships no Docker CLI and mounts no socket: the container runtime is not available to the Horae image as published. The options and their risks are documented in the operator guide (a socket mount is host root, T26; a socket proxy narrows the API but not what docker run can do; rootless Docker or Podman on the host; a sidecar). Enabling one is a follow-up, and so is lifting the M5 tier gate (approval.DIRECT_INSTALLS and the first-party rule, decision 70 E), which needs #50, #51 and #52 too. (Lifted for runtime: container only by decision 79, #191.)
    • K, left to the sibling stories. CPU, memory and PID limits and declared mounts are #51; the egress proxy is #50; the malicious-plugin suite is #52. The argument builder (run_argv) is the one place they add flags.
    • L, cost. Measured (operator guide, "Latency and sizing"): a container start adds about 0.25 s and a stop about 0.2 s per plugin; a call costs the same as in the process runtime; an idle container holds about 9 MiB. Threat rows T26, T27 and T42 to T45 of docs/security.md.

Provisional decisions (#56, pending maintainer review)

  1. MCP server authentication (#56). horae mcp serve gains a network transport, streamable HTTP (--http), and every request on it needs a bearer token. New module horae.mcp_auth, commands horae mcp token create|list|revoke (horae.cli_mcp_token), store migration 9 (mcp_tokens). The tools and their contracts (decision 65) are unchanged.
    • A, tokens. hmcp_ and 32 bytes from secrets.token_bytes as unpadded base64url (256 bits, 48 characters). The prefix makes a leaked token recognisable by secret scanners and by Horae's log scrubber (F). A token is printed once by create (stdout; --json puts it in token) and never again: the store keeps SHA-256("horae-mcp-token/v1\0" || token) only. Why SHA-256 and not a password hash: a slow KDF (argon2, scrypt, bcrypt) protects low-entropy secrets from guessing once the digest leaks; a 256-bit random token cannot be guessed whatever the hash speed, so a slow hash would only add a per-request CPU cost that any client could use to load the server. The label keeps this digest distinct from any other SHA-256 of the same bytes. No pepper: it would need a second secret and adds nothing against a 2^256 search.
    • B, stdio needs no token. A stdio server is a child process of the user's own MCP client, reading the instance with the user's rights: whoever can start it can already read the store and run horae run. The operating system has authenticated the caller, and a token in the client's config would sit next to the instance path and add nothing. A stdio session is granted every scope (STDIO_SCOPES), the same as its user at the CLI; for #55, the approval of a pipeline.run stays required over stdio too (the approval, not the transport, protects against a client steered by note text). The transport decides this, not the absence of an HTTP request: a tool served over HTTP without an authenticated user gets no scope (fail closed), and build_server takes stdio as a required keyword (no default that would grant every scope).
    • C, scopes. read (the three read-only tools; each tool checks it, else the tool error insufficient_scope) and pipeline.run (reserved for #55: lets a client ask for a pipeline's dry run and an approval; it never approves anything, the approval stays the user's, out of band). create grants read unless --scope says otherwise (repeatable). No wildcard, no admin scope, no token management over MCP.
    • D, store. Table mcp_tokens in the instance store (<state_dir>/horae.db, 0600, state directory 0700, as every store): id, name (1 to 64 of [A-Za-z0-9._-], first a letter or digit; unique among the tokens not revoked), token_sha256 (32 bytes, unique), scopes (space-separated), created_at, optional expires_at (--expires-in DAYS, 1 to 3650), last_used_at (written at most once a minute per token, best effort with a 100 ms busy timeout) and revoked_at. Revoked rows are kept (list shows them); a revoked name can be reused. The store, not a JSON file, so a revocation and a last-use update never overwrite each other.
    • E, verification. Every request opens the store read-only (a WAL reader, so a revocation committed a moment ago is seen: revocation applies to the next request; no cache), reads every row, digests the presented token (a fixed dummy when it is not token-shaped) and compares the digest with every row's using hmac.compare_digest, without stopping at a match; revocation and expiry are checked only after. A missing, malformed, unknown, wrong, revoked or expired token costs the same work and gets the same answer: 401, body {"error":"invalid_token","error_description":"a valid bearer token is required"}, WWW-Authenticate: Bearer realm="horae", error="invalid_token", Cache-Control: no-store. Only Authorization: Bearer <token> is read (scheme case insensitive, exactly one header); never a query parameter or a cookie. Every path and method is behind the check (no unauthenticated route, no OAuth metadata). A store that cannot be read is 503 (fail closed). An authenticated request carries the SDK's AuthenticatedUser (its client_id is the token's row id, never the token), which is what the tools check scopes against.
    • F, never logged. No Horae code logs the header or the token; uvicorn's access log is off and its log configuration not applied (Horae's redacting record factory stays). As a last resort the record factory replaces anything matching hmcp_[A-Za-z0-9_-]{16,} with [REDACTED:mcp_token] (horae.secrets.logs.MCP_TOKEN_SHAPE): a token a client sent is not a secret this process resolved, so value-based redaction cannot know it. list shows name, scopes, times and status, never a token or a digest. Refusals are logged without detail as a count, at most one INFO line a minute (RefusalLog), so a client sending bad tokens cannot flood the log.
    • G, the listener. horae mcp serve --http [--host 127.0.0.1] [--port 8765] [--allowed-host NAME]...: stateless streamable HTTP with JSON responses at /mcp (no MCP session, no server-sent stream: each request stands alone). It binds to loopback by default and refuses to start (exit 1, no_token) while no token is usable (none, all revoked or expired). A non-loopback --host prints a warning: the token travels in clear text unless a TLS reverse proxy terminates in front. The SDK's DNS-rebinding check is always on: Host must be a loopback name or an --allowed-host (any port), and an Origin, when sent, one of them. --host, --port and --allowed-host without --http are a usage error. SIGINT / SIGTERM stop it (exit 0; a second signal forces).
    • H, not done here. No rate limit: a 256-bit token cannot be guessed, and a client flooding refusals costs one store read each (loopback by default; a proxy can limit). No TLS in Horae (a reverse proxy's job, as for horae serve). No token rotation command: create a new one, switch the client, revoke the old one. The plain-HTTP horae serve API keeps relying on the SSO proxy (decision 51); this decision is the MCP server's.

Provisional decisions (#50, pending maintainer review)

  1. The egress allow-list proxy of plugin containers (#50). No schema changes: the policy is the lock's existing permissions.network and permissions.network_local, and blocked attempts use the existing egress_blocked violation kind of the run record. The code is in horae.plugins.host.egress_proxy (the proxy, standard library only) and horae.plugins.host.egress (starting it, reading its reports). The operator guide is docs/operations/plugin-containers.md. Only runtime: container (decision 74) has a proxy. The process runtime is unchanged (it has no isolation, T05).
    • A, implementation: a small asyncio proxy in Horae, run in its own container. It is about 500 lines with no dependency. The core passes its source to the image's interpreter (python3 -I -S -c <source> <policy JSON>), so it runs from the digest-pinned image the plugin already uses (decision 74 G), with no extra image to build, pin or pull. The tests import the same module. An off-the-shelf proxy (tinyproxy, squid, Envoy) was rejected because none of them resolves a name once, checks every answer against private, loopback, link-local and metadata ranges, and connects to the checked address. Each would also add an image to pin and a configuration generator, so the policy would live in two places.
    • B, one proxy per plugin start. ContainerRuntime.spawn starts the proxy before the plugin and waits for its ready line (30 s). The container is docker run --interactive --rm --init --pull never --log-driver none --user 65534:65534 --read-only --cap-drop ALL --security-opt no-new-privileges --pids-limit 64 --memory 128m --sysctl net.ipv4.ip_forward=0 --label dev.horae.egress-proxy=<plugin> --network horae-plugin-<plugin> --network horae-egress. That is decision 74 C's hardening; the proxy runs as nobody because it reads no file, has no mount at all, and never forwards packets between its two networks. The policy argument is built from the plugin's locked lists only, so no plugin can use another's allow-list. It also carries the plugin network's subnet: the proxy listens on port 3128 of its own address on that network only (never on horae-egress), and serves only the client admitted in C. horae-egress is created on first use: a bridge that is not --internal, labelled dev.horae.network=egress, with enable_icc=false and no IPv6. Each run checks it like a plugin network: no ConfigOnly/ConfigFrom, and every attached container must carry dev.horae.egress-proxy. A network of that name that fails the check is refused, never repaired. Its enable_icc=false is defence in depth only: it was not enforced on OrbStack's engine (containers on an ICC-off bridge reached each other), so the proxy's own listening address and client check are the real barrier. Docker 25 or later is needed, because docker run takes two --network flags.
    • C, amendment to decision 74 D. A plugin network now has enable_icc=true, because the plugin must reach its proxy on that bridge. It keeps --internal and inhibit_ipv4, so the host still has no address there. Only the plugin's own containers (dev.horae.plugin=<name>) and its own proxy (dev.horae.egress-proxy=<name>; the value is now checked, where before any value passed) may be attached. #49's networks (enable_icc=false) are refused with "remove it" and recreated on the next run. Each proxy serves one container. Two concurrent runs of one plugin share its network, so without more a run's plugin could use the other run's proxy (and its lock, if it changed in between). Once the plugin's container has started and finished its handshake, the host reads its address on the plugin network (docker container inspect) and writes it to the proxy's stdin ({"client": "<address>"}); the proxy admits that one address (once, and only inside the plugin network's subnet), confirms (admitted, within 10 s, else the plugin is stopped: runtime_unavailable), and drops every other connection without an answer, including any before the admission. Chosen over the alternatives: a fixed --ip for the plugin needs subnets Horae picks itself (Docker refuses --ip on a network whose subnet it allocated), with collisions between runs to handle; a network per plugin start adds about 0.4 s per start and leaks a subnet of Docker's limited address pool whenever Horae is killed before removing it. The admission keeps one network per plugin and binds the proxy to exactly one container. A plugin cannot connect out before its handshake is done.
    • D, the plugin's environment. HTTPS_PROXY, HTTP_PROXY, https_proxy, http_proxy and HORAE_EGRESS_PROXY all hold http://<proxy IPv4 on the plugin network>:3128, read from docker container inspect once the proxy is ready. They are set by the core in the secret-free part of the environment (horae.plugins.host.env.PROXY_KEYS). *_PROXY and HORAE_* stay on the secret deny list, so a plugin cannot override them, and NO_PROXY is never set. This replaces decision 66 F in two ways. The standard variables are set too, so clients that read the environment (urllib, requests, httpx by default) work unchanged. And local grants also go through the proxy instead of per-grant routes, which would need privileges (iptables in the plugin's namespace) that Horae does not have. A client with trust_env=False ignores the variables: it has no route, so it fails closed. horae-sdk 0.8 adds egress_proxy() to pass the proxy explicitly. Other protocols (IMAP) must tunnel with CONNECT.
    • E, the policy. Each connection carries one request:
    • CONNECT host:port to a network host is allowed on port 443 only. Decision 10 accepted any port, but the lock has no port syntax for public hosts, so the proxy caps it. A port syntax would be a later, compatible change.
    • CONNECT or an absolute-form plain-HTTP request is allowed to an exact network_local host:port. Plain HTTP is never allowed to a public host (decision 66 C). It is forwarded in origin form with Connection: close, and the Proxy-*, Connection, Keep-Alive, TE, Trailer and Upgrade headers are dropped.
    • An IP literal is allowed only when it is exactly a local grant (canonical form; IPv6 in brackets). Every other literal is refused, including the legacy numeric forms the C resolver reads as addresses (127.1, 0x7f000001).
    • Names are lowercased and must be plain DNS names with no trailing dot.
    • The proxy resolves the name itself. Every answer must pass: for a public name, globally routable (not private, CGNAT, documentation, multicast or site-local fec0::/10), and never an IPv6 address carrying an IPv4 one (IPv4-mapped, IPv4-compatible, NAT64, 6to4: embedded_address); for a local name, in decision 66 B's private ranges, never link-local (169.254.0.0/16, fe80::/10: link_local_address), which only an explicit IP-literal grant reaches. Metadata addresses (decision 66 B's and Azure's 168.63.129.16, a public address) and loopback (the proxy's own container) are always refused. One bad answer refuses the whole request, so a resolver mixing answers gets nothing.
    • The connection then goes to the first IPv4 answer, an address, never the name again, so DNS rebinding cannot change what was checked. Each new connection resolves again and is checked again.
    • No TLS interception. Bounds: an 8 KiB head read within 10 s, DNS and connect timeouts of 10 s, 300 s idle per tunnel, 64 connections.
    • Refusals answer 403 with the reason code. A name that does not resolve or an unreachable upstream answers 502, and so does an answer with no IPv4 address, because horae-egress has no IPv6.
    • F, blocked attempts. The proxy writes one JSON line to stdout per refusal: {"event": "blocked", "host", "port", "reason"}, where reason is a fixed code. Policy refusals (403): host_not_allowed, ip_literal, port_not_allowed, plain_http_not_allowed, private_address, embedded_address, link_local_address, loopback_address, metadata_address, not_local_address. Targets it cannot parse (400: 127.1, hex or octal forms, user info, a trailing dot, an https:// absolute form): malformed_target, with an empty host and port 0, so nothing the plugin wrote is repeated. Resolution failures (502): dns_failed, no_ipv4_address. It never writes a URL, path, query, header or body. It lists at most 200 per minute; what the cap hides is counted and reported as {"event": "suppressed", "count": N} every second while the count is not zero, so a flood of junk requests cannot silence later attempts. The host reads the lines (ProxyHandle.watch), checks them again (host shape, port range, reason shape), logs each at WARNING and keeps them (capped) until the end of the next call. They then become egress_blocked violations, <plugin>: egress blocked to <host>:<port> (<reason>) (egress refused, unreadable target (malformed_target) without a host), plus one <plugin>: N more blocked egress attempts on each call during which suppressed counts arrived, redacted like any message, since a refused name can carry a secret. They attach to the call's ToolResult or, if the call fails, to its ToolCallError.violations, which the engine now records too. They appear in the run record's violations (their kinds in horae run --json) and the log. Attempts reported after a plugin's last call are only logged.
    • G, stop. After the plugin's container is removed, its proxy's stdin is closed (the proxy exits), its CLI is killed if still there, and docker rm --force always runs, bounded. The proxy's attachment to horae-egress goes with it, and the network itself is kept for the next run.
    • H, fail closed. If the proxy cannot start (the CLI or image fails, it has no address on the plugin network, or horae-egress is not as in B), the proxy is removed and the plugin is not started (runtime_unavailable); if it cannot be bound to the plugin's container (C), both are stopped and removed. A proxy that dies during the run leaves the plugin with no route at all.
    • I, limits. A network_local grant on loopback (127.0.0.1:1143, Proton Mail Bridge on the Docker host) is refused (loopback_address): loopback in the proxy is its own container. Reaching a service on the host needs a grant of the host's address on the LAN, or a host-gateway route (a follow-up). A Docker service name declared in network resolves to a private address and is refused. A link-local service (169.254.x.y) is reachable only through a literal grant of its address. A blocked attempt that never reaches the proxy (a direct connection) is not recorded: it fails with "network unreachable". The proxy limits where a plugin connects, not what it sends there: an approved host can still receive the plugin's data (T05).

Provisional decisions (#55, pending maintainer review)

  1. Approval-gated pipeline.run (#55). One new MCP tool, pipeline.run, a store migration (10: approvals, approval_events), a new result contract (schemas/mcp/pipeline-run/v1.json) and a new command group, horae approval list|show|approve|deny|revoke (horae.approval, horae.cli_approval). Decision 76 is taken by #50, in parallel.
    • A, the tool only asks. pipeline.run {pipeline} needs the scope pipeline.run (decision 75 C; granted over stdio, decision 75 B). It runs the pipeline as a dry run (Runner.run(dry_run=True): the engine applies nothing either way, and no sink is asked to apply; collect steps and the LLM run as in horae run --dry-run, charged to the daily budgets), plans it (plan_changes, which only calls Sink.read) and returns a summary of what would be applied (counts and one line per change: kind, action, a clipped x-untrusted target; never a note body, a diff, a notification text or an HTTP body) and, when there is something applicable, an approval id with its expiry. It takes no template variables, path or command: what runs is the pipeline as configured. A run that failed, a plan with problems or refused, or an empty plan get no approval (reason).
    • B, the approval channel is the CLI, on a terminal. horae approval approve <id> is run by the user on the instance. It re-plans, shows the whole change set (as horae diff, HTTP bodies in full; when a note change is binary or larger than 1 MiB and so cannot be shown, it refuses, not_reviewable, and the approval stays pending) and asks the user to retype a short code printed with it (the last 6 characters of the binding digest; y does not do). Without a TTY on stdin it refuses (not_interactive); there is no --yes. Why the CLI: the MCP server must never be able to approve, so the approval travels a channel an MCP client cannot reach through MCP: a token holder over HTTP and an MCP-only stdio client have no way to run a command on the instance. What it does not stop: an agent that also has a shell as the same user (Claude Code's Bash tool, say) can allocate a pseudo-terminal (pty.fork(), script, expect), read the code and type it; the review reproduced this. The TTY check and the code are friction against approving by accident or by habit, not a boundary; such an agent can already run horae run itself (decision 75 B). Do not give one client both this MCP server and a shell as you if you rely on the approval. ntfy action buttons (/act, decision 54) were rejected for now: an /act link is a bearer capability that reaches the phone through a third-party push service, it would put a state-changing approval behind one tap with a small screen for the diff, and /act intents are fixed task actions, not an arbitrary run's plan. The API behind the SSO proxy was rejected because horae serve is optional and has no write route today. Both remain possible later, on top of the same store transitions. The MCP server registers no approve, deny or revoke tool; it imports only request_dry_run, and the approving transitions (approval_claim, approval_decide, approval_finish, Runner.apply_planned) are not referenced from horae.mcp_server.
    • C, what an approval is bound to. The approval row keeps a binding digest, SHA-256 of the canonical JSON of: the pipeline name; the pipeline's digest, the instance's config_digest and lock_digest; the run context (date, time zone, variables) and the run's input_hash; every proposed intent with its route; and the planned change set (horae.apply.to_dict without the run id, the dry-run flag and the notification dedupe keys, which depend on the run id): note paths with before and after SHA-256 and the diff, task changes, notifications (with whether each was already sent), HTTP calls. At request time the digests are the dry run's own; at approval time they are the current instance's. Applying does not run the pipeline again: the dry run's record is copied into a new run (new id, not a dry run, no LLM calls or cost of its own) whose intents are re-planned against the vault under the apply lock, and the change set is applied only if the recomputed digest equals the approved one (hmac.compare_digest); otherwise the run is saved failed (approval_mismatch, nothing applied) and the approval is refused. A changed note, pipeline, plugin set, model configuration or lockfile, a notification sent meanwhile, or a task that changed in the index therefore all refuse. The apply itself is the normal one (journal first, compare-and-swap on note bytes), so horae undo <run> reverts it like any run.
    • D, lifetime. An approval is pending for a TTL set by the server, horae mcp serve --approval-ttl MINUTES (1 to 60, default 15). Statuses: planning (the dry run is running), pending, approving (claimed, the apply is running), and the final applied, failed (the apply failed), refused (binding mismatch), denied (horae approval deny <id>), revoked (horae approval revoke --all, or the requesting token was revoked: horae mcp token revoke moves its pending approvals to revoked in the same transaction, and the claim also requires the token not to be revoked), expired (seen past its TTL) and void (the dry run gave nothing to approve). Only pending can be approved, denied or revoked.
    • E, single use. Approving first claims the row with one compare-and-set (UPDATE … SET status = 'approving' WHERE id = ? AND status = 'pending' AND expires_at > now AND the requesting token, if any, is not revoked), taken with the pipeline lock held: two concurrent approvals of one id apply once; the loser is told the current status. The run that applies it is recorded on the row as soon as it begins. Interruptions: a cancellation (a signal) during the apply lets the shielded apply finish and save its run; the approval then ends from that record (applied for ok, noop, degraded, else failed or refused), and failed "interrupted" only when no record was saved. A crash leaves approving (never re-applied); it is settled under the pipeline lock (on the next approval of that pipeline, or by list, show and approve when the lock is free): the dead run is recovered, then the approval ends from its record, or failed "interrupted" when there is none (horae undo reverts what an abandoned run wrote).
    • F, journal. Every transition appends a row to approval_events (approval, time, event, run id, short reason) in the same transaction as the status change; horae approval show <id> prints them, list shows the latest status, the dry run and the applied run. The applied run is an ordinary run in horae runs and the apply journal.
    • G, flood limits. Per requester (a token's id, or stdio), at most 3 approvals planning or pending at once and at most 12 requests per rolling hour; above that the tool error is too_many_pending / rate_limited and no dry run starts. The check and the insert of the planning row are one transaction.
    • H, not done here. No approval over ntfy or the HTTP API (B); no template variables from the client; approvals are not shown in runs.recent or /runs (the run view keeps its contract; the approval log is horae approval list).

Provisional decisions (#51, pending maintainer review)

  1. Declared mounts and resource limits of plugin containers (#51). One additive schema change to instance/v1.json: plugin_defaults.limits, plugins.<name>.limits and container.mount_roots. One new host error kind, oom_killed. Code in horae.plugins.host.mounts (the mount plan and the sweep) and run_argv (horae.plugins.host.container, still the one place container flags are built); operator guide in docs/operations/plugin-containers.md. Only runtime: container (decision 74) changes; the process runtime is unchanged (T04).
    • A, the same path inside. Each path of the plugin's locked permissions.paths (decision 70: what the user approved, never the manifest's own) is bind-mounted at the same path in the container: --mount type=bind,source=<path>,target=<path>,bind-recursive=disabled plus ,readonly unless the path is in write (write implies read; a path in both is writable). The plugin learns where its paths are through the existing configuration channel, _meta["dev.horae/paths"] on every request (decision 35, unchanged): since the paths are the same inside, that list, a pipeline parameter naming a file under them, and a path in a plugin's result all mean the same file on both sides. No environment variable is added. bind-recursive=disabled (Docker 25, already required by decision 76 B): a filesystem mounted below a declared path on the host is not carried in, so it cannot appear, nor stay writable under a read-only mount (kernels before 5.12 have no recursive read-only).
    • B, what may be mounted. Every declared path is checked before anything starts (the egress proxy included); one refused path refuses the plugin, runtime_unavailable naming the path and why (fail closed, decision 74 H). In order:
    • --mount must carry it: no ,, " or control character (as decision 74 H for the plugin directory);
    • canonical: realpath(path) == path, so no symbolic link anywhere in it (the host could otherwise be steered by a link a plugin planted in a writable parent, and the container would see the link's target under the declared name). The operator declares the real path;
    • it exists and is a directory or a regular file (never a socket, device or FIFO: the Docker socket itself is refused here);
    • it is, or lies inside, the instance directory or a container.mount_roots entry (operator-set in horae.yaml, default none: a vault outside the instance must be listed there). An entry that is /, Horae's home or an ancestor of it is refused (it is dropped from the roots, and a path under it is refused naming it): list the vault itself;
    • it neither is, contains nor lies inside a sensitive path, compared in both lexical and real forms: the instance's horae.yaml, horae.lock, plugins/, pipelines/, skills/, .git/, its state_dir and secrets.dir; the engine's socket (the context's endpoint) and /var/run/docker.sock, /run/docker.sock, /run/containerd; in Horae's home .ssh, .gnupg, .docker, .aws, .azure, .kube, .config, .local, .netrc, .git-credentials, .pypirc, the shell start-up files .bashrc, .bash_profile, .profile, .zshrc, .zprofile, and Library/LaunchAgents, Library/Keychains; macOS's /System, /Library, /Applications; and /bin, /boot, /dev, /etc, /lib*, /proc, /root, /run, /sbin, /sys, /usr, /var/lib/docker, /var/lib/containerd, /var/lock, /var/run, and the container's own /plugin;
    • it is neither /tmp nor contains it (it may lie inside it: the bind is mounted over the container's tmpfs);
    • a writable path is not, nor holds, a git repository: no .git (in any letter case, since volumes may ignore it) and no git directory layout under any name (a directory holding a HEAD together with any of objects, refs, commondir, gitdir, config, hooks, index, info, packed-refs or worktrees, any case: a bare repository or a linked worktree's directory, which GIT_DIR, a gitdir: file or safe.bareRepository=all would use; deliberately broad) as one of its components or anywhere below it (a walk of at most 100 000 entries, which refuses at its bound), and no git directory layout in a directory above it up to its mount root; a plugin could plant hooks the user's git runs. It may lie inside a git work tree (the maintainer's choice on #182: an instance kept in git with vault/ gitignored, as horae init lays it out, mounts its vault writable) as long as that repository's git directory stays out of the plugin's reach: for each .git found in a directory above it up to its mount root, its git directory (that directory, the one a .git file's gitdir: names, and a linked worktree's commondir) must neither be nor lie inside any path the plugin is given, read-only or writable, compared by device and inode; a git directory that cannot be told (a .git file without a gitdir: line, too long, naming nothing, a .git of another type) refuses the plugin (fail closed);
    • it does not lie strictly inside a writable path of another container plugin of the lock: that plugin could swap a directory of it for a link while this one starts. A writable path also must not be, nor hold, another container plugin's writable path: no two container plugins write the same tree, so nothing in a container races a sweep (C). A read-only path that is or holds another's writable one is allowed: that is how two plugins share data (one writes the vault, the other reads it), and swapping the declared path itself needs write access to its parent. Process-runtime plugins are not counted: they run unconfined as Horae's user anyway (T04), so excluding their paths would refuse common setups (file-sink writing the vault) and protect nothing. The sensitive-path and other-plugin comparisons are made on path strings and on file identities (device and inode of the path, its ancestors and the other path after realpath), so another letter case on a case-insensitive volume (the macOS default) or an alias (a link, a bind mount) is recognised; another plugin's writable path that cannot be read refuses the plugin (fail closed). A host built without an instance (tests, tools) refuses every declared path. A plugin in quarantine (C) is refused first. The check is run three times: when the mounts are planned; again right before docker run, after the egress proxy has started (mounts.recheck: each path still passes and is the same file, device and inode); and once the container has started and finished its handshake, before its egress proxy admits it (decision 76 C): docker container inspect must show exactly the plugin directory and the planned bind mounts, each from its own path with its declared access, and recheck must pass again; otherwise the plugin is stopped (runtime_unavailable). It has then received its environment (secrets included) but never had a route out.
    • C, nesting, and what a bind mount cannot do. Mounts are ordered parent first (Docker orders them by depth too), so each declared path behaves as declared: a writable child of a read-only parent is writable and the rest of the parent read-only; a read-only child of a writable parent stays read-only. Docker's --mount type=bind takes no nosuid, nodev, noexec or nosymfollow: a declared mount has the host filesystem's flags. What holds instead: no capability (--cap-drop ALL: no mknod of a device, no chown, no CAP_FSETID), a non-root user, no-new-privileges (a set-user-ID file never raises privileges inside), and a hard link cannot cross mounts (EXDEV). What a plugin can do in a writable path, and the host must then not trip over: make a symbolic link to anywhere (harmless inside, where it resolves in the container; dangerous to a host process following it), make a FIFO or a socket, set the set-user-ID bit on a file it owns (it is Horae's uid, so on the host that file runs as Horae's user). So once the container is removed, mounts.sweep checks each writable mount itself and walks it (not following links) and, for each entry whose st_ctime is at or after the container's start (less 2 s; a plugin cannot set ctime back, so a user's own older files are never touched) and that the plugin could write (not in a read-only child): removes a symbolic link strictly (when in doubt, it goes): any whose target is absolute or has a .. component, and any whose resolution by the kernel (realpath, once the container has exited, so chains of links and a .. through a linked directory are followed, never read lexically) lands where the plugin could not write itself (outside its writable paths, or in a read-only child of one: a host process following the link would act there for it); removes a device, FIFO or socket; clears a set-user-ID bit (and set-group-ID on a file). It also checks every declared path is still the same file (device and inode) as when it was checked. No race with the sweep: it walks with directory descriptors (each directory opened relative to its parent with O_DIRECTORY|O_NOFOLLOW, listed by descriptor, entries lstated, readlinked and unlinked relative to it; a file opened O_NOFOLLOW|O_NONBLOCK and checked by fstat to be the object lstat saw before its fchmod); any object that changed in between is a failure. A plugin with a writable path holds a per-plugin run lock (flock on <state_dir>/quarantine/<plugin>.lock) from before docker run until its sweep is done, so a concurrent run of the same plugin is refused (runtime_unavailable), and B keeps other container plugins out of its writable tree; only writers outside containers (a process plugin, the user) can still race it, and they meet the descriptors. A sweep that never ran: before docker run the host writes <state_dir>/quarantine/<plugin>.pending (O_EXCL, O_NOFOLLOW; failing to write it refuses the start) and removes it only after a clean sweep or a written quarantine; found at a start (taken under the run lock), it quarantines the plugin. A quarantine file that cannot be written leaves the marker, and the plugin is refused for the rest of the run. The quarantine and the marker are checked again once the run lock is held, so a concurrent run that quarantined the plugin in between is seen. The sweep fails closed, and none of its checks swallows an error (each becomes a failure): a new .git entry (any case), or a git directory layout anywhere in a writable path whatever its age (B refuses to mount one, so it is the plugin's) (the operator guide recommends safe.bareRepository=explicit), a declared path replaced or removed, a directory it cannot list, an entry it cannot lstat or undo, an entry on another device that is not a host mount point (/proc/self/mountinfo; a plugin cannot mount anything, so anything else is unexplained), more than 100 000 entries new since the start or 2 000 000 in all, or a container docker rm --force could not remove (no sweep at all) quarantines the plugin: a file <state_dir>/quarantine/<plugin> (0600) listing the reasons refuses its next start (runtime_unavailable, naming the file) until the operator has checked the paths and removed it; the runtime also remembers it for the rest of the run. Each finding is logged at WARNING (at most 50 lines a sweep, then a count); like egress attempts after a plugin's last call (decision 76 F), they are not run violations (the call they belong to is over). Residual: a swap of a path component for a link and back between the last recheck and the engine's mount, by a writer of a parent directory that is not another container plugin (a process-runtime plugin, the user; a concurrent run of the same plugin now waits for the run lock): docker inspect shows paths, not files, so the post-start check cannot see a swap undone in time (the in-container device and inode differ from the host's on Docker Desktop and OrbStack, so they are not compared); a writable parent can rename the directories between it and a read-only child (the child's contents move along, still read-only, and its host path may then name a directory the plugin made: the sweep reports it); while the plugin runs, what it wrote is on the host as it wrote it. Horae's own host-side writer of notes (horae.apply.local.LocalFileSink, used by the built-in sink and file-sink) already opens every path component relative to its parent with O_NOFOLLOW (O_DIRECTORY for directories) and refuses a link anywhere, so it does not follow a link a plugin left during its run either.
    • D, resource limits. Operator-set in horae.yaml like runtime: plugin_defaults.limits and plugins.<name>.limits, each field of which wins over the default's (the manifest and the lock carry none, so a plugin cannot ask for more). Flags: --cpus, --memory with --memory-swap equal (no swap), --pids-limit, --ulimit nofile=N:N, and the /tmp tmpfs size. Defaults, for a 4-core / 16 GB home server running a handful of plugins (each with its proxy, decision 76 B) at once: cpus: 1.0 (one plugin never takes more than a core), memory_mb: 512 (ten plugins at their limit still leave over 10 GB), pids: 128 (a Python plugin with a thread pool and a few children; a fork loop stops there), tmp_mb: 64 (#49's size), nofile: 1024. Bounds in the schema: cpus 0.1 to 64, memory_mb 64 to 65 536, pids 16 to 4096, tmp_mb 1 to 1024 and less than memory_mb (the tmpfs is charged to the container's memory; pydantic-only rule, checked for the merged limits of every plugins.<name>), nofile 64 to 65 536. A cpus above the host's CPU count is refused by the engine when the container starts.
    • E, an out-of-memory kill is reported as such. The plugin container is no longer --rm: when its process dies during a call or its start, the host reads the container's exit status before removing it: the launcher exits 247 when the plugin died of SIGKILL while the cgroup's memory.events oom_kill count went up (#188; the engine's {{json .State.OOMKilled}} counts too, but the engine can lose that event), and a kill by the memory limit fails the call with the new host error kind oom_killed (plugin <name> (runtime container) was killed by its memory limit (512 MiB, ...)) instead of plugin_crashed or handshake_failed; the restart rule is unchanged (one restart a run). docker rm --force still always runs once the CLI is gone (decision 74 I); a Horae killed with SIGKILL may now also leave an exited container: before each start of a plugin, its exited or dead containers (label=dev.horae.plugin=<name>) are removed with docker rm (never --force, never a running one). A concurrent run's container that has just exited may go with them, and its kill is then reported as a crash. A PID-limit hit is not a kill: the plugin's fork fails (EAGAIN) and the plugin reports it. CPU is throttled, never killed.
    • F, left to #52. The malicious-plugin suite exercises these: an undeclared path, a write to a read-only path, an escaping link, a fork bomb, a memory hog. Threat rows T51 to T53 of docs/security.md. horae doctor does not check mounts yet (a follow-up): the first run reports them.

Provisional decisions (#191, pending maintainer review)

  1. Third-party and direct installs only under runtime: container (#191). The maintainer chose the policy: lift both gates of decisions 70 E and 71 B, but only for plugins that run in a container (decisions 74, 76, 78). One additive schema change: lockfile/v1.json gains plugins.<name>.tier and plugins.<name>.index (B). One new host error kind, runtime_refused (C). Threat rows T04, T05 and T20 of docs/security.md.
    • A, the install gate. "First-party" is unchanged: tier first-party claimed by an index of FIRST_PARTY_INDEXES (the default Horae marketplace). A first-party plugin installs and runs under either runtime. Anything else (a community tier, first-party claimed by an index the user added, a direct install from a git URL) installs only when its effective runtime in horae.yaml is container: plugins.<name>.runtime, else plugin_defaults.runtime (InstanceConfig.plugin_runtime). Otherwise tier_refused (exit 3), saying how to enable it: set plugins.<name>.runtime: container (or the default) and make sure Docker is available. require_installable(name, tier, index, runtime=...) is the one check for every source, and approval.DIRECT_INSTALLS is removed (the runtime is the one switch, nothing can drift). A marketplace plugin is checked before anything is fetched. A direct install's name is known only from its plugin.yaml: it is refused before anything is fetched when horae.yaml runs no plugin in a container, then checked again (the first prepare step, before the approval and the venv) with the name. To make plugins.<name>.runtime settable before the install, horae plugin add loads the instance with installing=True: a plugin configured in horae.yaml but not in horae.lock yet is not a problem there (only there; every other command still reports it). Configuring it also enables it, as for any plugin.
    • B, the lock records the trust. LockedPlugin.tier and LockedPlugin.index are set, together, for a marketplace plugin that is not first-party, and absent for a first-party one, so every lock written before stays byte-identical and valid; a direct install keeps source: direct and has neither (a validator refuses tier without index, either without the other, and either with source). LockedPlugin.first_party is "no source and no tier". The lock, not the install record, because it is what the user reviews, commits and approves, and what --yes compares (lock_mismatch refuses a different tier or index). Absent means first-party because, before this decision, the tier gate let only first-party marketplace plugins write an entry without source.
    • C, the run-time gate. HostRegistry marks each plugin first-party or not from its lock entry, never from the manifest. The install record (.horae-install.json) can only take first-party away: a record saying source: direct, or a tier and index that are not first-party, makes the plugin not first-party whatever the lock says (a lock edited or written by an older core); a record that says nothing (none, or written before it recorded the tier) leaves the lock's answer. So a lock entry without the information and without a record (the built-in plugins of horae init, a plugin copied by hand, decision 70 F) is first-party: the operator put it there. PluginHost refuses to start a plugin that is not first-party unless its effective runtime is container, as the first thing of a start: before any secret is resolved for it or written, before any process or container. The new host error kind is runtime_refused (a start failure: the plugin is unavailable for the rest of the run, and a dry run with it as a sink exits 1). This holds when horae.yaml is changed after the install. Never a fallback.
    • D, approval. The prompt starts with the plugin's source (marketplace or direct, with the repository), its tier and index, and either "runs in a container (runtime: container)" or, for a first-party plugin, the runtime it will use. add --json reports first_party, runtime and enabled (a plugin configured before the install is enabled at once).
    • E, upgrade. The gate applies again with the instance's runtime: a plugin whose index no longer says first-party needs container. The permission diff has a tier item (~ first-party (Horae marketplace) -> community (<index>)) that widens when the new entry is not first-party, so --yes refuses it. A direct install can now be upgraded: horae plugin upgrade https://<host>/<owner>/<repo>@<full sha>. The URL must be the repo of exactly one source: direct entry (compared as written; never repeated in a message), the tree must hold a direct install's record, the gate must pass, and the commit is fetched as add does (decision 71 C: reachable from the repository's own branches or tags, never fetched by its id) and placed in a staging directory (install_commit(..., replace=NAME)); its plugin.yaml must name the same plugin, and a lower version needs --allow-downgrade. Then the same diff, approval, swap and rollback as decision 73 F. --pre and --offline are usage errors with a URL; a name given for a direct install points to upgrade URL@SHA or remove then add.
    • F, audit and remove. audit reports first_party and runtime per plugin (as the host decides them) and the new drift kind runtime_not_container: a plugin that is not first-party whose effective runtime is not container (the host will refuse it). The tier and index columns fall back to the lock's when there is no record. remove needs nothing new.
    • G, no build for a plugin that is not first-party (security review of this PR). A build backend on the allow-list of decision 69 B still runs plugin code on the host as the Horae user (setup.py under setuptools, a hatch build hook, pdm_build.py): fine for first-party code, arbitrary code execution outside the container for anything else. So PluginEnvironment(install_project=False) (chosen by cli_plugin.environment_for for every plugin that is not first-party, at add and upgrade): uv sync --locked --no-dev --no-install-project --no-build --no-build-package=<each dependency> installs the dependencies only, from their hashed wheels, and uv refuses to build anything at all. check_project also refuses, before uv runs, [project] dynamic (verified: with dynamic metadata uv calls the backend even with --no-install-project), a tool.uv.workspace, any tool.uv.sources entry that is not an index (path, git, url, workspace, editable), and a direct reference (name @ ...) in the dependencies, optional dependencies or dependency groups; backend-path stays refused, and the lock must still list nothing but hashed index or URL packages besides the root project (check_lock: path, git, directory, editable and virtual sources refused). Tested with a path dependency whose setup.py would write a marker: refused, never written. Horae then writes site-packages/_horae_plugin.pth (created exclusively, a dependency shipping that name is refused) naming /plugin/src when the tree has a real src/ directory (lstat, never through a symlink), else /plugin: the path the container sees (the plugin's mount, decision 74 C), which is the only place such a plugin runs (C). Without an installed project there is no console script, so runtime.command[0] must be the venv's python or python3 ([python, -m, <module>]); anything else is refused (install_refused) by the first prepare step, before approval. The prompt says "installed without running its build". First-party plugins are built and installed as before. Tested with a setuptools setup.py and a hatch custom hook that would each write a marker: none is written.
    • H, trust classes never share uv's cache (independent review of this PR). The review reproduced a poisoning: a third-party uv.lock lists flit-core under the real index but with its wheel URL on the attacker's host and the attacker's hash; uv fetched it and cached it under the index, and the next first-party build, whose backend uv resolves without hashes, imported it on the host. Fixed twice over: (1) a plugin that is not first-party installs (and upgrades) with its own uv cache, inside the install's temporary home and deleted with it; <state_dir>/uv-cache is for first-party installs only. (2) check_lock, for every plugin, requires each file of a registry package to be served by that registry's host over https (same host and port), or by its known files host (pypi.org serves from files.pythonhosted.org/packages/...), or to lie inside a local directory index: no other host, no http, no credentials, query or fragment. For a plugin that is not first-party the registry itself must be the default index (https://pypi.org/simple) and a url source is refused, so a third-party lock cannot make the host fetch an arbitrary URL (the review's SSRF finding). Existing first-party locks from PyPI pass unchanged. A regression test serves a good and an evil flit-core wheel of the same file name from two local HTTP servers, installs a third-party tree then builds a first-party one on the same instance: with the host check removed, only the private cache keeps the marker from being written (and without it, it is written). (3) Hash-pinned build requirements for first-party builds were not done: uv sync has no --build-constraints (only uv pip and uv build do), and tool.uv.build-constraint-dependencies is plugin-controlled and takes no hashes; a Horae-maintained, hashed set for the five allowed backends and their own dependencies, per Python version, is a follow-up. Until then a first-party build trusts the index over https for its backend, as decision 69 B already says.
    • I, what this does not do. It does not make a container safe by itself: the guarantees and gaps of decisions 74, 76 and 78 (egress through the proxy only, declared mounts, the limits, the Docker socket of T26) are what a third-party plugin is confined by. Horae in the published image still cannot start containers (decision 74 J): there a third-party plugin installs once horae.yaml says container, but fails runtime_unavailable until the operator gives Horae an engine. horae doctor (#194) reports each plugin that is not first-party (as the host decides it) whose effective runtime is not container, with the same check as audit (audit.runtime_drift), and, when a plugin runs in a container, a missing or unusable local Docker engine (container.engine_problem: the CLI, a local unix:// DOCKER_HOST and context, a daemon that answers; nothing is started or pulled). Both are errors, as every doctor problem that makes a run fail. An end-to-end test (tests/test_plugin_nobuild_container.py, marked malicious, container and live) installs a synthetic third-party plugin without building it, with its venv made inside the plugin image, and makes one real tool call under runtime: container: the .pth makes python -m <module> importable at /plugin/src and no setup.py or build hook runs.