@awebai/oats 0.22.14 → 0.22.16

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

@@ -44,7 +44,7 @@ const jsonFail = (code, message) => { process.stdout.write(JSON.stringify({ sche
 // --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.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 runs it\noats okf inspect [--json]  answer this instance's working knowledge (STATE.md, log.md, pending notes) as labeled documents\n");
   process.exit(0);
 }
 const event = process.env.OATS_EVENT || process.argv[2];
@@ -473,6 +473,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)";
+    process.stdout.write(JSON.stringify({ schemaVersion: 1, ok: true, result: { summary, documents } }) + "\n"); process.exit(0);
+  } catch (e) {
+    process.stdout.write(JSON.stringify({ schemaVersion: 1, ok: false, error: { code: "E_INSPECT_FAILED", message: String(e.message || e).slice(0, 300) } }) + "\n"); process.exit(1);
+  }
 } 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 +504,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.0",
   "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/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

package/lib/schedule.mjs

@@ -40,11 +40,12 @@ export function scheduleError(code, message, extra) { return Object.assign(new E
  *  is never observed or executed, and is reported invalid on that job only. */
 export function shapeError(def) {
   if (!def || typeof def !== "object" || Array.isArray(def)) return "definition is not an object";
-  if (!["spawn", "command", "wake"].includes(def.kind)) return `kind ${JSON.stringify(def.kind)} is not spawn, command or wake`;
+  if (!["spawn", "command", "wake", "operation"].includes(def.kind)) return `kind ${JSON.stringify(def.kind)} is not spawn, command, wake or operation`;
   if (typeof def.cron !== "string" || typeof def.tz !== "string") return "cron and tz must be strings";
   if (def.kind === "spawn" && typeof def.agent !== "string") return "agent must be a string";
   if (def.kind === "command" && (typeof def.cwd !== "string" || !Array.isArray(def.argv))) return "cwd and argv are required";
   if (def.kind === "wake" && (typeof def.home !== "string" || typeof def.message !== "string")) return "home and message are required";
+  if (def.kind === "operation" && (typeof def.operation !== "string" || typeof def.home !== "string")) return "operation and home are required";
   return null;
 }
 
@@ -229,7 +230,14 @@ export function validateDefinition(ws, def, { checkAgent = true } = {}) {
     if (typeof def.home !== "string" || !isAbsolute(def.home) || !inside(ws, def.home) || !existsSync(join(def.home, "instance.json"))) throw scheduleError("E_SCHEDULE_INVALID", "home: an existing instance home inside the scope", { field: "home" });
     validateMessage(def.message, "message");
     out.home = resolve(def.home); out.message = def.message;
-  } else throw scheduleError("E_SCHEDULE_INVALID", "kind: spawn, command or wake", { field: "kind" });
+  } else if (def.kind === "operation") {
+    // A provider operation in a running home, resolved when the job runs
+    // (oats operation run <layer>:<name> --home): the provider is whatever
+    // fills that layer for the home then; nothing about it is stored here.
+    if (typeof def.operation !== "string" || !/^(knowledge|messaging|tasks):[a-z][a-z0-9-]*$/.test(def.operation)) throw scheduleError("E_SCHEDULE_INVALID", "operation: <layer>:<name>, e.g. knowledge:harvest", { field: "operation" });
+    if (typeof def.home !== "string" || !isAbsolute(def.home) || !inside(ws, def.home) || !existsSync(join(def.home, "instance.json"))) throw scheduleError("E_SCHEDULE_INVALID", "home: an existing instance home inside the scope", { field: "home" });
+    out.operation = def.operation; out.home = resolve(def.home);
+  } else throw scheduleError("E_SCHEDULE_INVALID", "kind: spawn, command, wake or operation", { field: "kind" });
   return out;
 }
 
@@ -320,6 +328,13 @@ function launchSpawn(ws, def, minute, io) {
   }
   return run;
 }
+/** The command job an operation job becomes when it runs: the kernel's own
+ *  operation runner in the home, which resolves the provider at that moment
+ *  and reports a launch receipt (instance/home) only for what the provider
+ *  launched, never for the source home. */
+export function operationAsCommand(def) {
+  return { ...def, kind: "command", cwd: def.home, argv: ["oats", "operation", "run", def.operation, "--home", def.home] };
+}
 /** Parse a command's stdout as one JSON document (remote output can be
  *  multi-line); fall back to the last {...} block; null when nothing parses. */
 export function parseEnvelopeText(text) {
@@ -355,9 +370,16 @@ function launchCommand(ws, def, io) {
   if (instance && !home) { const found = findHomesInScope(ws, instance); if (found.length === 1) home = found[0]; }
   if (envelope.ok && instance && !home) return { kind: "command", launched: true, instance, unconfirmed: true, error: `the envelope names instance ${instance} but no home for it is in this scope's roster; run oats schedule reconcile once it appears` };
   // A valid ok:false answer that reports an incomplete rollback (a harvest
-  // spawn whose compensation could not stop or remove everything) is not a
-  // confirmed failure either.
-  if (!envelope.ok && reportsRetainedEffects(envelope.error?.message)) return { kind: "command", launched: false, unconfirmed: true, ...(instance ? { instance } : {}), error: `command failed with retained effects: ${envelope.error?.message}`, errorCode: envelope.error?.code };
+  // spawn whose compensation could not stop or remove everything), or an
+  // operation runner's unconfirmed outcome (timeout, no valid receipt, a
+  // receipt contradicted by the exit status), is not a confirmed failure.
+  // Whatever name the provider managed to answer travels in error.details
+  // so reconcile can adopt it.
+  if (!envelope.ok && (UNCONFIRMED_ERROR_CODES.has(envelope.error?.code) || envelope.error?.details?.unconfirmed === true || reportsRetainedEffects(envelope.error?.message))) {
+    const partial = envelope.error?.details?.envelope?.result;
+    const named = instance || (partial && typeof partial.instance === "string" ? partial.instance : undefined);
+    return { kind: "command", launched: false, unconfirmed: true, ...(named ? { instance: named } : {}), error: `command outcome unconfirmed: ${envelope.error?.message}`, errorCode: envelope.error?.code };
+  }
   return { kind: "command", launched: envelope.ok === true, ...(instance ? { instance } : {}), ...(home ? { home } : {}), ...(envelope.ok ? {} : { error: envelope.error?.message || "command failed", errorCode: envelope.error?.code }) };
 }
 /** One wake. `startIfStopped` false between due minutes (a harness that
@@ -367,6 +389,8 @@ function launchCommand(ws, def, io) {
  *  confirm (spawn compensation's "rollback INCOMPLETE", a quarantined or
  *  retained home): the launch's effects are unconfirmed, never a confirmed
  *  failure. Shared by caught spawn errors and ok:false command envelopes. */
+/** Error codes whose meaning is "the effects are unconfirmed" by contract. */
+const UNCONFIRMED_ERROR_CODES = new Set(["E_OPERATION_TIMEOUT", "E_OPERATION_RESULT"]);
 export function reportsRetainedEffects(message) { return /INCOMPLETE|quarantin|retain|could not (?:be )?(?:verif|confirm)/i.test(String(message || "")); }
 function performWake(def, io, { startIfStopped = true, canStart = true, reserve } = {}) {
   const seen = observeHome(def.home, io);
@@ -498,7 +522,7 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
     js.lastLaunchedAt = now.toISOString();
     writeState(ws, st);
     let run;
-    try { run = def.kind === "command" ? launchCommand(ws, def, io) : launchSpawn(ws, def, minute, io); }
+    try { run = def.kind === "spawn" ? launchSpawn(ws, def, minute, io) : launchCommand(ws, def.kind === "operation" ? operationAsCommand(def) : def, io); }
     catch (e) {
       // spawnInstance compensates its own failures, but its rollback can be
       // INCOMPLETE (a pane it could not stop, a quarantined home it kept):
@@ -595,7 +619,7 @@ export function reconcile(ws, id, { io, now = new Date(), clear = false } = {})
       const homes = findHomesInScope(ws, `${def.agent}-${purpose}`);
       if (homes.length === 1) adopted = { instance: `${def.agent}-${purpose}`, home: homes[0] };
       else if (homes.length > 1) ambiguous = `${homes.length} homes named ${def.agent}-${purpose}: ${homes.join(", ")}`;
-    } else if (def.kind === "command") {
+    } else if (def.kind === "command" || def.kind === "operation") {
       const named = js.lastRun?.instance ? findHomesInScope(ws, js.lastRun.instance).map((home) => ({ instance: js.lastRun.instance, home })) : [];
       if (named.length === 1) adopted = named[0];
       else if (named.length > 1) ambiguous = `${named.length} homes named ${js.lastRun.instance}: ${named.map((c) => c.home).join(", ")}`;
@@ -651,7 +675,7 @@ export function updateSchedule(ws, id, spec, io) {
   return withHostLock(() => withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
     if (!defs.jobs[id]) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
-    const identity = (d) => JSON.stringify([d.kind, d.agent, d.agentsRoot, d.repo, d.purpose, d.home, d.cwd, d.argv]);
+    const identity = (d) => JSON.stringify([d.kind, d.agent, d.agentsRoot, d.repo, d.purpose, d.home, d.cwd, d.argv, d.operation]);
     const busy = !!jobLockInfo(ws, id) || !!readState(ws).jobs[id]?.attempt;
     if (busy && identity(defs.jobs[id]) !== identity(def)) throw scheduleError("E_SCHEDULE_RUNNING", `schedule ${id} is running or has an unresolved attempt; its kind, agent, agentsRoot, repo, purpose, home, cwd and argv cannot change until it ends (cron, tz, task, message, runtime, model and enabled can)`);
     defs.jobs[id] = { ...def, createdAt: defs.jobs[id].createdAt, updatedAt: new Date().toISOString() };