@awebai/oats 0.22.14 → 0.22.17

package/capabilities/oats-okf/bin/oats-okf.mjs

@@ -23,29 +23,44 @@
  *      OATS_TASK (spawn), OATS_REPO/OATS_BRANCH/OATS_WORK (spawn), OATS_META (retire).
  * Output: JSON { meta, brief, warning } on stdout. Failures warn, never block.
  */
-import { existsSync, mkdirSync, mkdtempSync, writeFileSync, readFileSync, readdirSync, realpathSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync, readFileSync, readdirSync, realpathSync, rmSync, writeSync } from "node:fs";
 import { join, isAbsolute, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { execFile, spawnSync } from "node:child_process";
 import { reclaimHarvestBranch } from "../lib/harvest-branch.mjs";
 
-const out = (o) => { process.stdout.write(JSON.stringify(o) + "\n"); process.exit(0); };
+// Every answer leaves through here: written whole, then exit. stdout is a
+// pipe when the kernel's operation runner, a Desktop or a test reads it, and
+// on macOS Node writes to a pipe asynchronously: process.exit right after
+// process.stdout.write drops whatever has not left Node's buffer (64 KiB,
+// so a view of one long STATE.md arrived cut). fs.writeSync on fd 1 blocks
+// until the OS has the bytes; EAGAIN (a non-blocking fd whose reader is
+// slower than us) is retried after a short wait. The exit stays synchronous,
+// which the call sites below rely on to end their flow.
+const emit = (text, code) => {
+  const buf = Buffer.from(text, "utf8");
+  for (let off = 0; off < buf.length;) {
+    try { off += writeSync(1, buf, off, buf.length - off); }
+    catch (e) { if (e.code !== "EAGAIN") throw e; Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5); }
+  }
+  process.exit(code);
+};
+const out = (o) => emit(JSON.stringify(o) + "\n", 0);
 const warn = (m) => out({ warning: `oats-okf: ${String(m).slice(0, 300)}` });
 // A reported failure must not exit 0: callers and hooks read the status.
-const warnFail = (m) => { process.stdout.write(JSON.stringify({ warning: `oats-okf: ${String(m).slice(0, 300)}` }) + "\n"); process.exit(1); };
+const warnFail = (m) => emit(JSON.stringify({ warning: `oats-okf: ${String(m).slice(0, 300)}` }) + "\n", 1);
 
 // Desktop CLI API v1: `oats okf harvest --json` emits EXACTLY ONE envelope
 // object on stdout — {schemaVersion:1,ok,result|error} — and a nonzero exit
 // on failure. Ordinary (non---json) output keeps the hook JSON shape above.
 const JSON_MODE = process.argv.includes("--json");
-const jsonOk = (result) => { process.stdout.write(JSON.stringify({ schemaVersion: 1, ok: true, result }) + "\n"); process.exit(0); };
-const jsonFail = (code, message) => { process.stdout.write(JSON.stringify({ schemaVersion: 1, ok: false, error: { code, message: String(message).slice(0, 300) } }) + "\n"); process.exit(1); };
+const jsonOk = (result) => emit(JSON.stringify({ schemaVersion: 1, ok: true, result }) + "\n", 0);
+const jsonFail = (code, message) => emit(JSON.stringify({ schemaVersion: 1, ok: false, error: { code, message: String(message).slice(0, 300) } }) + "\n", 1);
 
 // --help/-h never runs a command here either (the kernel answers it from the
 // manifest since 0.22.6; this keeps an older kernel from spawning a harvester).
 if (process.argv.slice(2).some((a) => a === "--help" || a === "-h")) {
-  process.stdout.write("oats okf harvest [--json] [--from-record] [--force]  promote this instance's pending notes (and record windows) into its soul by spawning a memory-harvest worker; --help never spawns\noats okf status [--json]\n");
-  process.exit(0);
+  emit("oats okf harvest [--json] [--from-record] [--force]  promote this instance's pending notes (and record windows) into its soul by spawning a memory-harvest worker; --help never runs it\noats okf inspect [--json]  answer this instance's working knowledge (STATE.md, log.md, pending notes) as labeled documents\n", 0);
 }
 const event = process.env.OATS_EVENT || process.argv[2];
 const instance = process.env.OATS_INSTANCE;
@@ -473,6 +488,30 @@ _(the single next action — keep this current; a fresh session on any model res
     if (JSON_MODE) jsonFail(e.code || "E_HARVEST_FAILED", `harvest spawn failed (notes are safe on disk): ${e.message || e}`);
     warnFail(`harvest spawn failed (notes are safe on disk): ${e.message || e}`);
   }
+} else if (event === "inspect") {
+  // VIEW OPERATION (kernel contract, docs/design/operations-contract.md):
+  // the instance's working knowledge as labeled documents, read from the
+  // home this command runs in. Text only; paths are provenance for the
+  // reader. Answers the JSON-v1 envelope regardless of --json.
+  try {
+    const CAP = 256 * 1024;
+    const doc = (label, file) => {
+      if (!existsSync(file)) return null;
+      const bytes = readFileSync(file);
+      const truncated = bytes.length > CAP;
+      let text = truncated ? bytes.subarray(0, CAP).toString("utf8") : bytes.toString("utf8");
+      if (truncated && text.endsWith("\uFFFD")) text = text.slice(0, -1);
+      return { label, kind: "markdown", path: file, text, ...(truncated ? { truncated: true, bytes: bytes.length } : {}) };
+    };
+    const documents = [doc("Working state (STATE.md)", join(home, "STATE.md")), doc("Log (log.md)", join(home, "log.md"))].filter(Boolean);
+    const notesDir = join(home, "notes");
+    const notes = existsSync(notesDir) ? readdirSync(notesDir).filter((f) => f.endsWith(".md")).sort() : [];
+    for (const f of notes) { const d = doc(`Pending note: ${f}`, join(notesDir, f)); if (d) documents.push(d); }
+    const summary = documents.length ? `${documents.length} document${documents.length === 1 ? "" : "s"}: ${existsSync(join(home, "STATE.md")) ? "state" : "no state"}, ${existsSync(join(home, "log.md")) ? "log" : "no log"}, ${notes.length} pending note${notes.length === 1 ? "" : "s"}` : "no working memory in this home yet (STATE.md, log.md and notes/ are written by the instance)";
+    jsonOk({ summary, documents });
+  } catch (e) {
+    jsonFail("E_INSPECT_FAILED", e.message || e);
+  }
 } else if (event === "retire") {
   // Retirement is intentionally a no-op for knowledge (for now): promotion happens
   // continuously via agent-initiated harvest. Uncommitted notes die with the home —
@@ -480,5 +519,5 @@ _(the single next action — keep this current; a fresh session on any model res
   // before finishing.
   out({ meta: {} });
 } else {
-  warn(`unknown event "${event}" (expected soul-scaffold|spawn|retire)`);
+  warn(`unknown event "${event}" (expected soul-scaffold|spawn|retire|harvest|inspect)`);
 }

package/capabilities/oats-okf/oats.json

@@ -1,12 +1,12 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "1.5.2",
+  "version": "1.6.1",
   "compatibility": {
     "oats": ">=0.22.3"
   },
   "layer": "knowledge",
-  "description": "Knowledge layer via OKF: soul bundles, instance memory (STATE.md/log.md/notes/), continuous post-commit harvest into the soul (commit, PR, or direct-edit for local souls), craft + memory skills, validator.",
+  "description": "Knowledge layer via OKF: soul bundles, instance memory (STATE.md/log.md/notes/), continuous post-commit harvest into the soul (commit, PR, or direct-edit for local souls), craft + memory skills, validator; declares the operations a GUI or schedule may run (inspect, harvest).",
   "requires": [],
   "settings": {
     "harvest-runtime": {
@@ -29,11 +29,26 @@
     "skills"
   ],
   "commands": {
-    "harvest": "bin/oats-okf.mjs harvest"
+    "harvest": "bin/oats-okf.mjs harvest",
+    "inspect": "bin/oats-okf.mjs inspect"
   },
   "inject": "injects/okf.md",
   "hooks": {
     "soul-scaffold": "bin/oats-okf.mjs soul-scaffold",
     "spawn": "bin/oats-okf.mjs spawn"
+  },
+  "operations": {
+    "inspect": {
+      "kind": "view",
+      "command": "inspect",
+      "context": "home",
+      "description": "Show this instance's working knowledge: STATE.md, log.md and pending notes"
+    },
+    "harvest": {
+      "kind": "action",
+      "command": "harvest",
+      "context": "home",
+      "description": "Promote this instance's pending notes (or captured record) into its soul by spawning a memory-harvest worker"
+    }
   }
 }

package/docs/capabilities.md

@@ -503,3 +503,10 @@ The source packages live under `capabilities/`. Acquired packages live under
 `<level>/.agents/capabilities/installed/` (gitignored, restorable); packages
 authored at a scope live under `<level>/.agents/capabilities/owned/`
 (committed where the scope is a git repo). Within one scope `owned/` overrides `installed/` on ID collision.
+
+## Operations a capability declares
+
+A manifest may declare `operations` (named actions or views delegating to
+its own commands) that a GUI or a schedule invokes through `oats operation
+run <layer>:<name>`; `oats inspect --json` reports them with availability.
+See [docs/design/operations-contract.md](design/operations-contract.md).

package/docs/capability-manifest.schema.json

@@ -150,6 +150,38 @@
         "minLength": 1
       }
     },
+    "operations": {
+      "description": "Named operations a GUI or scheduler may invoke through `oats operation run`, each delegating to one of this manifest's commands. kind \"view\" answers { documents: [{label, kind, path, text}] }; \"action\" (default) runs something. context \"home\" (default) runs in an instance home, \"scope\" in the config scope.",
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["command"],
+        "additionalProperties": false,
+        "properties": {
+          "command": { "type": "string", "minLength": 1 },
+          "kind": { "enum": ["action", "view"] },
+          "context": { "enum": ["home", "scope"] },
+          "description": { "type": "string" },
+          "args": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["name"],
+              "additionalProperties": false,
+              "properties": {
+                "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+                "flag": { "type": "string", "pattern": "^--[a-z][a-z0-9-]*$" },
+                "required": { "type": "boolean" },
+                "description": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
     "hooks": {
       "type": "object",
       "properties": {

package/docs/design/2026-09-07-desktop-souls-capabilities.md

@@ -0,0 +1,50 @@
+# Souls and capabilities in Desktop
+
+Selecting a soul opens its details. Launch and Schedule are explicit actions;
+Quick Open and Enter inspect instead of launching. The existing local Files
+browser remains available. It is separate from provider knowledge inspection.
+
+The inspector reads the kernel's `oats inspect --json` answer on selection,
+Refresh, or after an explicit mutation. The roster's eight-second poll never
+rescans capabilities or replaces an editor. Workspace changes invalidate old
+responses. Same-named souls are addressed by name plus agents root; instances
+are addressed by their exact home.
+
+The Capabilities button inspects workspace defaults, with a member-scope
+selector where a workspace contains several roots. Installed version, source
+and health are separate from effective activation, provenance and settings.
+Enable, explicit disable and return to inheritance call `oats use`; layer-wide
+disable is distinct from excluding a single capability, and is available only
+when inspecting a workspace or member scope, never an individual soul. These changes apply to
+future instances. Existing homes retain their captured bindings and settings.
+
+Authored souls expose only the fields the kernel reports as editable. Desktop
+edits runtime, model, backend, YOLO, description and instructions through
+`oats soul set`. Packaged souls remain read-only and explain where their source
+must be changed. Instructions use a private temporary file; the CLI owns remote
+transfer and mutation. Desktop does not modify YAML or resolve capabilities.
+
+An instance's action menu opens Knowledge & capabilities. The kernel supplies
+its snapshot, differences from current configuration, and declared provider
+operations. View operations return labeled documents; Desktop renders their
+text and treats remote paths as provenance, never as local files to open. Actions
+without required arguments can run here. Operations requiring arguments explain
+that they need the CLI. No provider is assumed to support harvesting.
+
+Schedules store an operation address and exact home with the kernel's generic
+`operation` job kind. The form discovers declared, available actions on demand.
+The server verifies that declaration again at save time, and the kernel resolves
+and validates the provider at execution time. Existing command schedules remain
+visible and runnable, but the GUI does not reverse-parse their argv to edit them.
+
+Every capability request requires an exact advertised workspace. Remote requests
+require its saved server registration and the CLI's operations API feature; all
+routing stays in OATS. The consumer never performs SSH or silently substitutes a
+local workspace. The proxy allows the CLI's bounded operation to return its
+receipt before timing out.
+
+Validation: scope/identity and remote-route refusal; private instructions and
+failure cleanup; declared schedule actions; stale inspection/save responses;
+provider text rendering; explicit launch and existing runtime flows. Native
+Electron rendering is checked with a temporary fixture frame in the existing
+GUI, without starting a model, agent, or another application instance.

package/docs/design/operations-contract.md

@@ -0,0 +1,123 @@
+# Provider operations and inspection contract
+
+Implemented 2026-09-07 on the existing capability engine. The kernel
+resolves providers; a GUI reads one answer and calls the commands below.
+Nothing here names a provider: what a knowledge, messaging or tasks
+capability offers is what its manifest declares.
+
+## Manifest: operations
+
+```json
+"operations": {
+  "harvest": { "kind": "action", "command": "harvest", "context": "home", "description": "Promote this instance's notes into its soul" },
+  "inspect": { "kind": "view",   "command": "inspect", "context": "home", "description": "Show this instance's working knowledge" }
+}
+```
+
+`command` names one of the manifest's `commands`. `kind` is `action`
+(default) or `view`. `context` is `home` (default; runs in an instance
+home) or `scope` (runs in the config scope). Optional `args` declare
+`{name, flag, required, description}`; the runner passes `--arg name=value`
+pairs as those flags and refuses unknown or missing required ones. A view
+must answer `{ documents: [{ label, kind: "markdown"|"text", path?, text? }],
+summary? }`; the kernel validates that shape and relays it. Paths are
+provenance for the reader; the kernel reads nothing for a view. Validation
+happens when the manifest loads (`docs/capability-manifest.schema.json`).
+
+## oats inspect
+
+`oats inspect [--dir <scope>] [--soul <name> [--agents-root <abs>]] [--home
+<abs>] [--server <id>] --json` answers, in one envelope: `scope` (context,
+workspace, team, chain, agentsRoots); `souls` (persistent, local and
+packaged, each with runtime defaults, `editable {fields, instructions,
+reason}`, instances, and for the selected soul its `instructions {file,
+text, sha256, bytes, truncated, error}` capped at 256 KiB of bytes on a
+character boundary); `layers` (effective provider per layer); `capabilities`
+(installed state and `health` from the package engine, `missingRequires`,
+and separately `activation {enabled, source, target, level, provenance,
+settings, declaredAt}` plus `operations` with `available` and a `reason`);
+`knowledge` (the effective knowledge provider's operations); `snapshot` and
+`currentConfig` with `--home`; `problems`.
+
+A `--home` answer is authoritative for that home: activation, settings,
+layers and operation availability come from the home's captured bindings
+with the currently acquired manifests and current trust, marked `source:
+"snapshot"`; the live config is `currentConfig`, and `snapshot.drift`
+lists activation, settings and integrity differences. The home selects its
+own soul under its own agents root (its recorded work repository may be
+another repository); `--dir`, if given, must be the recorded repository or
+the workspace of that root, and `--agents-root` must be that root
+(`E_HOME_MISMATCH`). Without a home, `--dir` is the config context and
+same-named souls under two member roots need `--agents-root`
+(`E_SOUL_AMBIGUOUS`). The ambient `PI_AGENTS_ROOT` never redirects these
+commands. Integrity scanning happens only in this command.
+
+## oats operation run
+
+`oats operation run <layer>:<name> (--home <abs> | --soul <name> [--dir
+<scope>] [--agents-root <abs>]) [--arg k=v ...] --json` resolves the
+provider that fills `<layer>` for the home (captured bindings and settings)
+or for the soul in the scope (config), requires the operation to be declared
+(`E_OPERATION_UNKNOWN`), a provider to exist (`E_OPERATION_UNAVAILABLE`,
+also for a home-context operation without `--home`), the executable surface
+to be trusted (`E_CAPABILITY_BLOCKED`) and its `requires` to be on PATH
+(`E_CAPABILITY_REQUIRES`), then runs the provider's own command exactly as
+`oats <ns> <cmd>` would, with cwd and identity set to the selected target
+(`OATS_HOME`, `OATS_INSTANCE`, `OATS_AGENT`, `OATS_SOUL`, `OATS_ROOT`,
+`OATS_CONTEXT`, `OATS_WORKSPACE`, `OATS_OPERATION`, `OATS_SETTINGS`,
+`OATS_CLI_BIN`, team variables) and every ambient identity of the invoking
+process removed. The answer is `{ operation, capability, version, argv,
+cwd, target: {home, instance}|null, result, instance?, home? }`; top-level
+`instance`/`home` appear only when the provider's answer names something it
+launched, never the source home.
+
+The receipt must be exactly one JSON-v1 envelope on stdout from a process
+that exits 0. Otherwise the outcome is unconfirmed: `E_OPERATION_TIMEOUT`
+(240 s, below every wrapper) or `E_OPERATION_RESULT` (no valid envelope,
+contaminated output, or a success envelope contradicted by the exit
+status), with `error.details {unconfirmed: true, exit, envelope?, stderr?}`
+carrying what was observed. A provider's own `ok: false` is relayed with
+its code.
+
+## Schedules
+
+Kind `operation` `{operation: "<layer>:<name>", home}` runs `oats operation
+run <op> --home <home>` as a command job: same admission, tracking and
+reconciliation. An unconfirmed outcome keeps the slot as unknown and any
+name the provider answered is kept for `oats schedule reconcile`.
+
+## Mutations
+
+`oats use ... --json` answers `{ capability, action: enable|disable|
+layer-none|inherit, target, layer, level, file, settings, before, after
+{..., effective}, remaining?, note?, missingRequires }`. `--inherit`
+removes only the addressed target at this level; other bindings stay and
+are listed. `use none --layer l` is a level statement and takes no soul or
+type. A layer bound to another capability at a level is never overwritten
+(`E_LAYER_BOUND` with the exact remedy).
+
+`oats soul set <name> [--dir] [--agents-root] [--runtime] [--model |
+--no-model] [--yolo | --no-yolo] [--backend] [--description |
+--no-description] [--instructions-file <path>] --json` edits only the given
+`soul.yaml` lines and replaces `AGENTS.md`; packaged souls are refused
+(`E_SOUL_READONLY`). The receipt carries before/after and sha256s.
+
+## Remote
+
+`inspect`, `operation`, `use` and `soul` route with `--server <id>` through
+the saved route. The gate is the destination's `features` list containing
+`operations` and its `operationsApi: 1` (`E_REMOTE_INCOMPATIBLE` before
+anything is sent): `features` describes what a kernel can do locally, which
+is what runs on the host. The probe's `remote` list describes what a CLI
+can ROUTE to a server and is what a GUI checks on the local CLI before
+offering remote actions; it is not a gate on the destination. An explicit `--dir` is the exact member context and
+travels as is; `--home` is its own context; otherwise the registered
+workspace is the scope. Soul instructions travel as bytes on the ssh stdin
+(`--instructions-stdin` on the host), never as a local path.
+
+## Replaceability
+
+`test/inspect.test.mjs`, `test/operation.test.mjs` and
+`test/operations-routing.test.mjs` use an owned alternative knowledge
+provider (namespace `notes`, one `MEMORY.md`, operations `harvest` and
+`inspect`) and never mention the official provider.

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

@@ -0,0 +1,48 @@
+# OATS v0.22.15
+
+Souls and capabilities become something you inspect and manage, through
+one kernel contract, and knowledge providers declare what they can do.
+
+## Provider operations and inspection (kernel)
+
+`oats inspect --json` answers everything a GUI needs in one envelope for a
+scope, a selected soul or a running home: souls with runtime defaults,
+editability and instructions; installed capabilities with health from the
+package engine, separately from their effective activation, provenance and
+settings; effective layer bindings; and the operations each provider
+declares, with availability and the reason when unavailable. For a home the
+answer is its captured bindings (with current manifests and trust), the live
+config beside it, and the drift between them. Same-named souls in member
+repositories are addressed by name plus agents root; a home selects its own
+soul under its own root.
+
+`oats operation run <layer>:<name>` resolves the provider that fills a layer
+for a home or a soul, checks declaration, trust and host requirements, runs
+the provider's own command in the right place with the right identity, and
+relays its receipt; a view answers labeled documents. Unconfirmed outcomes
+carry what was observed and a scheduled operation keeps its slot until
+reconciled. Manifests declare `operations`. Schedules gain kind
+`operation`. `oats use --json` answers receipts and `--inherit` returns a
+level to inheritance; `oats soul set` edits an editable soul's defaults and
+instructions in place. All four route to a registered server through the
+saved route; the probe advertises `operations` and `operationsApi: 1`. The
+retire receipt no longer implies a harvest. See
+docs/design/operations-contract.md.
+
+## oats.okf 1.6.0
+
+The official knowledge provider declares `inspect` (a view of STATE.md,
+log.md and pending notes) and `harvest` (the existing action); the catalog
+pins v1.6.0. Existing scopes keep their locked 1.5.2 until their owners
+update them; the GUI then shows no operations for those providers, which is
+the truthful state.
+
+## Desktop
+
+Souls & capabilities replaces the launch-centric roster: select a soul to
+inspect it, Launch and Schedule are explicit, defaults and instructions are
+editable where the kernel says so, installed capabilities are shown apart
+from activation with enable, disable and inherit at an exact scope, an
+instance's menu opens Knowledge & capabilities, provider views render as
+text, and schedules run declared provider operations. See
+docs/design/2026-09-07-desktop-souls-capabilities.md.

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

@@ -0,0 +1,53 @@
+# OATS v0.22.16
+
+The same reviewed content as the unpublished v0.22.15 tag, whose hosted
+run failed in frozen test data (retirement goldens still carrying the
+removed `harvested` field, and a Desktop harvest fixture predating the
+operations gate) before anything was published; only tests changed.
+
+Souls and capabilities become something you inspect and manage, through
+one kernel contract, and knowledge providers declare what they can do.
+
+## Provider operations and inspection (kernel)
+
+`oats inspect --json` answers everything a GUI needs in one envelope for a
+scope, a selected soul or a running home: souls with runtime defaults,
+editability and instructions; installed capabilities with health from the
+package engine, separately from their effective activation, provenance and
+settings; effective layer bindings; and the operations each provider
+declares, with availability and the reason when unavailable. For a home the
+answer is its captured bindings (with current manifests and trust), the live
+config beside it, and the drift between them. Same-named souls in member
+repositories are addressed by name plus agents root; a home selects its own
+soul under its own root.
+
+`oats operation run <layer>:<name>` resolves the provider that fills a layer
+for a home or a soul, checks declaration, trust and host requirements, runs
+the provider's own command in the right place with the right identity, and
+relays its receipt; a view answers labeled documents. Unconfirmed outcomes
+carry what was observed and a scheduled operation keeps its slot until
+reconciled. Manifests declare `operations`. Schedules gain kind
+`operation`. `oats use --json` answers receipts and `--inherit` returns a
+level to inheritance; `oats soul set` edits an editable soul's defaults and
+instructions in place. All four route to a registered server through the
+saved route; the probe advertises `operations` and `operationsApi: 1`. The
+retire receipt no longer implies a harvest. See
+docs/design/operations-contract.md.
+
+## oats.okf 1.6.0
+
+The official knowledge provider declares `inspect` (a view of STATE.md,
+log.md and pending notes) and `harvest` (the existing action); the catalog
+pins v1.6.0. Existing scopes keep their locked 1.5.2 until their owners
+update them; the GUI then shows no operations for those providers, which is
+the truthful state.
+
+## Desktop
+
+Souls & capabilities replaces the launch-centric roster: select a soul to
+inspect it, Launch and Schedule are explicit, defaults and instructions are
+editable where the kernel says so, installed capabilities are shown apart
+from activation with enable, disable and inherit at an exact scope, an
+instance's menu opens Knowledge & capabilities, provider views render as
+text, and schedules run declared provider operations. See
+docs/design/2026-09-07-desktop-souls-capabilities.md.

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

@@ -0,0 +1,25 @@
+# OATS v0.22.17
+
+Two corrections found by installed acceptance of 0.22.16, nothing else.
+
+## oats.okf 1.6.1
+
+A provider view larger than one pipe buffer arrived cut at 65536 bytes
+with exit 0 when the kernel's operation runner or a Desktop read it: the
+provider wrote its envelope and exited at once, and on macOS Node writes
+to a pipe asynchronously. Every answer now leaves the provider whole
+before it exits. The catalog pins v1.6.1; scopes on 1.6.0 keep working
+for small views until their owners run
+`oats update oats.okf --to v1.6.1 --dir <scope>` and re-trust. The
+kernel's runner is unchanged; the regression covers a 128 KiB view
+through an actual pipe, directly and through `oats operation run`, and a
+300 KiB view from any provider.
+
+## Desktop
+
+Workspaces added at runtime survive an app restart: the opened set is
+persisted on its own (not the recent-suggestion store), restored and
+re-validated at startup with absent paths skipped and aliases collapsed,
+and a backend is reused only when it covers every restored workspace. A
+failed persistence write keeps the previous set and reports the failed
+add.

package/docs/schedules.md

@@ -56,6 +56,15 @@ and no queue.
   home is started again only at due minutes, never every minute, so a
   harness that keeps exiting is not restarted in a loop. A job holds at most
   one pending delivery: a due minute while one is pending adds nothing.
+- **operation** `{id, enabled, cron, tz, kind: "operation", operation, home}`
+  — runs a provider operation such as `knowledge:harvest` in the instance at
+  `home` through `oats operation run <layer>:<name> --home <home>`. The
+  provider is whatever fills that layer for the home when the job runs (its
+  snapshot), not something stored in the job, so the job stays valid across
+  provider changes and a GUI can list and edit it without parsing argv.
+  Admission, tracking and reconciliation are those of a command job: a
+  launch receipt the provider answers (a harvester it spawned) is followed
+  until that home is gone; the source home is never treated as a launch.
   Unobservable or still starting: skipped with the reason, delivery kept
   pending. Whether a running harness is busy cannot be seen from the
   terminal: delivery is terminal input (bracketed paste plus Enter), never an

package/lib/core.mjs

@@ -987,9 +987,45 @@ function loadManifestAt(idir, origin) {
     if (hookDeclaration(value)?.required && hook !== "spawn") throw new Error(`capability ${id} hook "${hook}" cannot be required — only the spawn hook is enforced (retire and soul-scaffold run outside a spawn transaction)`);
   }
   if (m.agents !== undefined && (!Array.isArray(m.agents) || m.agents.some((a) => typeof a !== "string"))) throw new Error(`capability ${id} "agents" must be an array of package-relative soul directories`);
+  validateManifestOperations(m, id);
   return { ...m, _dir: idir, _origin: origin };
 }
 
+/** `operations`: what a capability offers a GUI or scheduler by name, each
+ *  delegating to one of its own `commands`. kind "action" runs something;
+ *  kind "view" answers { documents: [...] } for presentation (a knowledge
+ *  provider's own view of an instance's working knowledge). context "home"
+ *  runs in an instance home; "scope" runs in the config scope. */
+const OPERATION_NAME_RE = /^[a-z][a-z0-9-]*$/;
+function validateManifestOperations(m, id) {
+  if (m.operations === undefined) return;
+  if (!m.operations || typeof m.operations !== "object" || Array.isArray(m.operations)) throw new Error(`capability ${id} "operations" must be an object map`);
+  for (const [name, op] of Object.entries(m.operations)) {
+    if (!OPERATION_NAME_RE.test(name)) throw new Error(`capability ${id} operation "${name}": name must match ${OPERATION_NAME_RE.source}`);
+    if (!op || typeof op !== "object" || Array.isArray(op)) throw new Error(`capability ${id} operation "${name}" must be an object`);
+    if (typeof op.command !== "string" || !Object.prototype.hasOwnProperty.call(m.commands || {}, op.command)) throw new Error(`capability ${id} operation "${name}": "command" must name one of the manifest's commands`);
+    if (op.kind !== undefined && !["action", "view"].includes(op.kind)) throw new Error(`capability ${id} operation "${name}": "kind" must be action or view`);
+    if (op.context !== undefined && !["home", "scope"].includes(op.context)) throw new Error(`capability ${id} operation "${name}": "context" must be home or scope`);
+    if (op.description !== undefined && typeof op.description !== "string") throw new Error(`capability ${id} operation "${name}": "description" must be a string`);
+    if (op.args !== undefined) {
+      if (!Array.isArray(op.args)) throw new Error(`capability ${id} operation "${name}": "args" must be an array`);
+      for (const a of op.args) {
+        if (!a || typeof a !== "object" || typeof a.name !== "string" || !OPERATION_NAME_RE.test(a.name)) throw new Error(`capability ${id} operation "${name}": each arg needs a name matching ${OPERATION_NAME_RE.source}`);
+        if (a.flag !== undefined && (typeof a.flag !== "string" || !/^--[a-z][a-z0-9-]*$/.test(a.flag))) throw new Error(`capability ${id} operation "${name}" arg "${a.name}": "flag" must look like --name`);
+        if (a.required !== undefined && typeof a.required !== "boolean") throw new Error(`capability ${id} operation "${name}" arg "${a.name}": "required" must be a boolean`);
+      }
+    }
+  }
+}
+/** The normalized operations a manifest declares (empty when none). */
+export function manifestOperations(manifest) {
+  return Object.entries(manifest?.operations || {}).map(([name, op]) => ({
+    name, kind: op.kind || "action", command: op.command, context: op.context || "home",
+    description: op.description || null,
+    args: (op.args || []).map((a) => ({ name: a.name, flag: a.flag || `--${a.name}`, required: !!a.required, description: a.description || null })),
+  }));
+}
+
 /** Discover capability manifests. Later sources take precedence: outer scopes < inner scopes; installed < owned within one scope. Duplicates inside one source layer are errors. */
 export function capabilityManifests(startDir) {
   // Capability-id keyed — never answer for `constructor`/`toString`. The ids
@@ -7230,7 +7266,6 @@ export function retireInstance(root, name, o = {}) {
       contextDir: meta.repo, workspaceDir: workspaceOf(root), rootDir: root, resolved, priorMeta: meta.capabilityMeta || {},
     });
   }
-  const harvested = hookResults?.meta?.["oats.okf"]?.harvested || [];
 
   // ORDINARY retirement must not delete a home whose cleanup did not finish.
   // The failures were already collected above; until now they were read ONLY on
@@ -7439,7 +7474,7 @@ export function retireInstance(root, name, o = {}) {
   }
 
 
-  const result = { retired: name, agent: found.agent.name, workRecovery, workRecoveries: workRecoveries.length > 1 ? workRecoveries : undefined, worktreeRemoved: isWorktree, branchDeleted: !!(o.deleteBranch && meta.branch) || quarantineBranchDeleted, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, harvested, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: hookResults?.warnings?.length ? hookResults.warnings : undefined };
+  const result = { retired: name, agent: found.agent.name, workRecovery, workRecoveries: workRecoveries.length > 1 ? workRecoveries : undefined, worktreeRemoved: isWorktree, branchDeleted: !!(o.deleteBranch && meta.branch) || quarantineBranchDeleted, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: hookResults?.warnings?.length ? hookResults.warnings : undefined };
   if (self) {
     // The caller is the instance: its process lives in the window we are about to
     // kill. Detach the kill so this function can return and the caller can report