@ouro.bot/cli 0.1.0-alpha.977 → 0.1.0-alpha.979

package/changelog.json

@@ -1,6 +1,18 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.979",
+      "changes": [
+        "The Butler's psyche now belongs to the install: releases no longer overwrite or lock it, and a fresh install is seeded with the starter psyche once."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.978",
+      "changes": [
+        "Psyche edits now take effect on the next turn for every agent. Each prompt build compares the content of the psyche and house files with the cached copy and rereads on any change, so an edit by the agent, its owner or a sync pull no longer waits for a restart. Content is compared rather than mtimes, which FUSE shares such as Unraid's do not always update."
+      ]
+    },
     {
       "version": "0.1.0-alpha.977",
       "changes": [

package/deploy/unraid/README.txt

@@ -1,16 +1,16 @@
 Ouro Butler operator runbook
 
-The production container is ouro-butler. It runs as UID/GID 10001, publishes no ports, uses host networking only so its loopback-only Unraid GraphQL client can reach 127.0.0.1, mounts the runtime and sanctuary.ouro bundle read-write, the bundle psyche folder read-only over it so the Butler can neither edit nor replace its psyche, plus the privileged event spool read-only, and uses restart policy unless-stopped. The canonical-gateway image appends /run/ouro-authority -> /run/ouro-authority, readonly, rprivate, and the psyche mount (<bundle>/psyche -> /home/ouro/AgentBundles/sanctuary.ouro/psyche, readonly, rprivate) and the operator trust mount (/mnt/user/appdata/ouro-butler/trust/sanctuary -> /etc/ouro/trust/sanctuary, readonly, rprivate), a root-owned directory outside the bundle that holds the grants the Butler honours. The pinned alpha.816 predecessor has only the first three mounts. Root token, issuer, package and authority state are never mounted into the resident.
+The production container is ouro-butler. It runs as UID/GID 10001, publishes no ports, uses host networking only so its loopback-only Unraid GraphQL client can reach 127.0.0.1, mounts the runtime and sanctuary.ouro bundle read-write, plus the privileged event spool read-only, and uses restart policy unless-stopped. The canonical-gateway image appends /run/ouro-authority -> /run/ouro-authority, readonly, rprivate, and the operator trust mount (/mnt/user/appdata/ouro-butler/trust/sanctuary -> /etc/ouro/trust/sanctuary, readonly, rprivate), a root-owned directory outside the bundle that holds the grants the Butler honours. The pinned alpha.816 predecessor has only the first three mounts. Root token, issuer, package and authority state are never mounted into the resident. The psyche folder has no mount of its own: it is part of the writable bundle and belongs to the install. Releases up to alpha.978 also mounted <bundle>/psyche read-only over the bundle, so every audit still accepts that six-mount shape, and rolling an upgrade back to such a release recreates it with that mount.
 
 Root authority lifecycle
 
 The existing DockerMan transaction owns authority-install, authority-activate, authority-retire and authority-restore. A complete exact-image package, including dist and production dependencies, must remain at its package-relative paths; extracting only the old five deployment assets cannot execute this lifecycle. The reviewed root-only inputs are /mnt/user/appdata/ouro-authority/incoming-package, package-manifest.json, request.json and incoming-token. They are not a new resident credential policy. The human rotates the existing bot token directly into root custody; the root owner proves the previous token returns 401 and the fresh token belongs to the same numeric bot before continuing.
 
-First rollout of the psyche mount: the live container before this release has four mounts, but the canonical-gateway contract now requires six (the psyche folder read-only over the bundle and the operator trust directory). assert_update_source audits the live source container against its image's contract, so on that first update it fails with "effective mounts do not match the selected Sanctuary mount contract". The failure is expected and changes nothing. Recreate the live resident once by hand with the six-mount create (the canonical-gateway line in create_sanctuary_container, including the psyche and trust mounts), leave it stopped, then rerun the update. Psyche files stay owned by uid 10001 at mode 0600 because the resident's boot check requires exactly that; the read-only mount, not ownership, keeps the resident from editing or replacing them.
+Psyche mount retired: alpha.978 and earlier mounted the bundle psyche folder read-only over the bundle (six mounts). The upgrade audits still accept that shape, so the running alpha.978 resident passes them; the upgrade then recreates the resident with five mounts (no separate psyche mount) and removes the psyche Config (Target /home/ouro/AgentBundles/sanctuary.ouro/psyche) from the installed DockerMan template /boot/config/plugins/dockerMan/templates-user/my-ouro-butler.xml, so a DockerMan Apply cannot add the read-only mount back. Rolling the upgrade back recreates the predecessor with the read-only psyche mount it expects. Psyche files stay owned by uid 10001 at mode 0600 because alpha.978's boot check requires exactly that after a rollback.
 
-Operator trust directory. Delegated-command and escalation grants live on the host in /mnt/user/appdata/ouro-butler/trust/sanctuary, owned by root:root, mode 0755, with every file in it root-owned and mode 0644, and the directory is outside the bundle so the upgrade's recursive chown cannot reach it. The container sees it read-only at /etc/ouro/trust/sanctuary; the Butler honours a grant only when the file and every directory above it up to / are real, root-owned and closed to group and other writes. Create it once as root before the first create: `install -d -o root -g root -m 0755 /mnt/user/appdata/ouro-butler /mnt/user/appdata/ouro-butler/trust /mnt/user/appdata/ouro-butler/trust/sanctuary` (this also makes /mnt/user/appdata/ouro-butler itself root-owned 0755, which the replay gate needs for its host folder below; the agent and runtime folders inside it keep their own owners). Manage grants on the host as root with a one-off container that mounts the directory read-write (the resident's mount is read-only): `docker run --rm --user 0:0 --entrypoint node --pull=never --network none -v /mnt/user/appdata/ouro-butler/trust/sanctuary:/etc/ouro/trust/sanctuary -v /mnt/user/appdata/ouro-butler/agent/sanctuary.ouro:/home/ouro/AgentBundles/sanctuary.ouro:ro <butler image> /opt/ouro/dist/heart/daemon/ouro-entry.js a2a delegated-commands grant --agent sanctuary --friend <friend id> --did <did:key> [--expires <ISO date>] [--source <text>]`, and likewise `a2a delegated-commands revoke|list` and `a2a escalation grant --friend <id> --did <did:key>|revoke|list`. Setting OURO_OPERATOR_TRUST_DIR replaces the trust root (/etc/ouro/trust) and keeps the per-agent folder, so the files sit in <dir>/<agent>/. Grant commands take an exclusive .lock file in the directory (the lock records the writer's pid and host; one older than two minutes is taken over only when that pid is no longer running on the same host, and one written on another host only after an hour; remove a stuck one by hand) and flush the directory after each rename. A one-off container cannot read the agent's own DID, so grant then compares --did with every friend record and refuses a DID a second record also carries, and prints a note saying so; revoke works by friend id even when the friend record is gone. Revoke never writes the friend record (it runs as root); when the record still carries a legacy delegationGrant it prints a REQUIRED FOLLOW-UP docker exec -u 10001 line that clears the legacy delegationGrant field as the resident user (friend records are never written as root). The replay gate grants its replay principal and escalation peer with an expiry equal to the replay window and removes them when it closes; the replay gate keeps a root-owned list of its replay peers in the trust directory (replay-identities.json), the Butler refuses any grant without an expiry for a friend on that list (the grant's source text and the bundle's own replay registry decide nothing), and the grant commands refuse a no-expiry grant, and any escalation grant, for a listed friend. Replay seeds and the provisioning record live outside the bundle, in the root-owned host folder /mnt/user/appdata/ouro-butler/replay-client (the gate's --client-dir overrides it), created by provision as root 0700 under a parent that is root-owned and closed to group and other writes (by default only that parent, /mnt/user/appdata/ouro-butler, is checked, because Unraid's shared /mnt/user/appdata is usually nobody:users 0777); the gate refuses a folder, a parent or a seed that root did not make, and never takes over one the Butler's user could have written. Only root-owned state may supply replay friend ids and DIDs: that folder and the trust directory's replay-identities.json. Nothing in the bundle's state/replay-client or state/replay does, and a provision.json found in the bundle is ignored (its friend ids are only printed, as unverified). A run copies the seeds into a root-only directory it makes inside the container with mktemp -d, drives the CLI as root from there, and deletes it when the window closes. An existing state/replay in the bundle that root does not own is moved aside as replay.untrusted-<time> and made fresh. One-time step on the upgrade that moves the replay seeds out of the bundle: run `node sanctuary-replay-gate.mjs provision --rotate-replay-identities` as root. Earlier replay seeds were written by the Butler's user and must be treated as known to it, so this mints three new seeds (root-owned 0600, in the host folder above), moves any old seed in that folder aside as *.retired-<time>, removes the retired peers' trusted grants, marks their friend records revoked, demotes them to stranger and drops their DID pin and A2A identity (the last two as the resident user, never as root), onboards the new peers and rewrites state/replay/identities.json from the root-owned list; the old friend ids stay in that registry so they stay blocked from owner-policy writes. The peers it retires are the ones the root-owned record and replay list name. The earlier bundle copy of provision.json is not trusted, so the first rotation prints the friend ids it names as unverified; for each one you have checked is a replay peer, add `--retire-friend <id>` (repeatable). Always pass the DID the holder really signs with (`ouro a2a identity --json` on the holder's side); the Butler refuses a message signed by any other DID. First rollout of the trust mount: the live container has five mounts, so the first update fails the six-mount audit exactly as the psyche rollout did; recreate the resident once by hand with the six-mount create and rerun the update.
+Operator trust directory. Delegated-command and escalation grants live on the host in /mnt/user/appdata/ouro-butler/trust/sanctuary, owned by root:root, mode 0755, with every file in it root-owned and mode 0644, and the directory is outside the bundle so the upgrade's recursive chown cannot reach it. The container sees it read-only at /etc/ouro/trust/sanctuary; the Butler honours a grant only when the file and every directory above it up to / are real, root-owned and closed to group and other writes. Create it once as root before the first create: `install -d -o root -g root -m 0755 /mnt/user/appdata/ouro-butler /mnt/user/appdata/ouro-butler/trust /mnt/user/appdata/ouro-butler/trust/sanctuary` (this also makes /mnt/user/appdata/ouro-butler itself root-owned 0755, which the replay gate needs for its host folder below; the agent and runtime folders inside it keep their own owners). Manage grants on the host as root with a one-off container that mounts the directory read-write (the resident's mount is read-only): `docker run --rm --user 0:0 --entrypoint node --pull=never --network none -v /mnt/user/appdata/ouro-butler/trust/sanctuary:/etc/ouro/trust/sanctuary -v /mnt/user/appdata/ouro-butler/agent/sanctuary.ouro:/home/ouro/AgentBundles/sanctuary.ouro:ro <butler image> /opt/ouro/dist/heart/daemon/ouro-entry.js a2a delegated-commands grant --agent sanctuary --friend <friend id> --did <did:key> [--expires <ISO date>] [--source <text>]`, and likewise `a2a delegated-commands revoke|list` and `a2a escalation grant --friend <id> --did <did:key>|revoke|list`. Setting OURO_OPERATOR_TRUST_DIR replaces the trust root (/etc/ouro/trust) and keeps the per-agent folder, so the files sit in <dir>/<agent>/. Grant commands take an exclusive .lock file in the directory (the lock records the writer's pid and host; one older than two minutes is taken over only when that pid is no longer running on the same host, and one written on another host only after an hour; remove a stuck one by hand) and flush the directory after each rename. A one-off container cannot read the agent's own DID, so grant then compares --did with every friend record and refuses a DID a second record also carries, and prints a note saying so; revoke works by friend id even when the friend record is gone. Revoke never writes the friend record (it runs as root); when the record still carries a legacy delegationGrant it prints a REQUIRED FOLLOW-UP docker exec -u 10001 line that clears the legacy delegationGrant field as the resident user (friend records are never written as root). The replay gate grants its replay principal and escalation peer with an expiry equal to the replay window and removes them when it closes; the replay gate keeps a root-owned list of its replay peers in the trust directory (replay-identities.json), the Butler refuses any grant without an expiry for a friend on that list (the grant's source text and the bundle's own replay registry decide nothing), and the grant commands refuse a no-expiry grant, and any escalation grant, for a listed friend. Replay seeds and the provisioning record live outside the bundle, in the root-owned host folder /mnt/user/appdata/ouro-butler/replay-client (the gate's --client-dir overrides it), created by provision as root 0700 under a parent that is root-owned and closed to group and other writes (by default only that parent, /mnt/user/appdata/ouro-butler, is checked, because Unraid's shared /mnt/user/appdata is usually nobody:users 0777); the gate refuses a folder, a parent or a seed that root did not make, and never takes over one the Butler's user could have written. Only root-owned state may supply replay friend ids and DIDs: that folder and the trust directory's replay-identities.json. Nothing in the bundle's state/replay-client or state/replay does, and a provision.json found in the bundle is ignored (its friend ids are only printed, as unverified). A run copies the seeds into a root-only directory it makes inside the container with mktemp -d, drives the CLI as root from there, and deletes it when the window closes. An existing state/replay in the bundle that root does not own is moved aside as replay.untrusted-<time> and made fresh. One-time step on the upgrade that moves the replay seeds out of the bundle: run `node sanctuary-replay-gate.mjs provision --rotate-replay-identities` as root. Earlier replay seeds were written by the Butler's user and must be treated as known to it, so this mints three new seeds (root-owned 0600, in the host folder above), moves any old seed in that folder aside as *.retired-<time>, removes the retired peers' trusted grants, marks their friend records revoked, demotes them to stranger and drops their DID pin and A2A identity (the last two as the resident user, never as root), onboards the new peers and rewrites state/replay/identities.json from the root-owned list; the old friend ids stay in that registry so they stay blocked from owner-policy writes. The peers it retires are the ones the root-owned record and replay list name. The earlier bundle copy of provision.json is not trusted, so the first rotation prints the friend ids it names as unverified; for each one you have checked is a replay peer, add `--retire-friend <id>` (repeatable). Always pass the DID the holder really signs with (`ouro a2a identity --json` on the holder's side); the Butler refuses a message signed by any other DID. First rollout of the trust mount (alpha.887): the live container then had no trust mount, so the first update failed the mount audit exactly as the psyche rollout did; the fix was to recreate the resident once by hand with the runbook's canonical-gateway create and rerun the update. If a resident without the trust mount is ever found again, recreate the resident once by hand with the five-mount create and rerun the update.
 
-During installation the resident is stopped, the root gateway is installed and proven, tokenless readiness runs, and authority-activate starts the exact six-mount target. On failure, authority-retire must finish before restoring bundle/config/mounts or starting the exact three-mount predecessor; authority-restore proves that rollback before the outer template journal is removed. An uncertain or interrupted handoff leaves autostart disabled and preserves both journals and root inputs for the same reviewed recovery, never a raw old-template start. Retired keys, policy, history and Jellyfin remain untouched. Re-enabling authority requires a new human token rotation and issuer epoch, not reuse of retired authority.
+During installation the resident is stopped, the root gateway is installed and proven, tokenless readiness runs, and authority-activate starts the exact five-mount target. On failure, authority-retire must finish before restoring bundle/config/mounts or starting the exact three-mount predecessor; authority-restore proves that rollback before the outer template journal is removed. An uncertain or interrupted handoff leaves autostart disabled and preserves both journals and root inputs for the same reviewed recovery, never a raw old-template start. Retired keys, policy, history and Jellyfin remain untouched. Re-enabling authority requires a new human token rotation and issuer epoch, not reuse of retired authority.
 
 On installed cold boot, the original unless-stopped and DockerMan autostart remain unchanged: /boot/config/custom/ouro-authority/start.sh --boot waits for the array and responsive Docker, then starts the fenced root gateway. Docker may already have started the tokenless resident; it fails closed until the gateway is ready. There is no pre-Docker gate, whole-array gate, resident direct poller or resident token fallback.
 
@@ -330,7 +330,7 @@ Effective-spec audit helper:
       test "$(sanctuary_image_mount_contract "$CREATE_IMAGE_ID")" = "$CREATE_MOUNT_CONTRACT" || return 1
       test "$(docker image inspect --format '{{.Id}}' "$CREATE_IMAGE_REFERENCE")" = "$CREATE_IMAGE_ID" || return 1
       case "$CREATE_MOUNT_CONTRACT" in
-        canonical-gateway) set -- --mount "type=bind,src=/run/ouro-authority,dst=/run/ouro-authority,readonly" --mount "type=bind,src=/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro/psyche,dst=/home/ouro/AgentBundles/sanctuary.ouro/psyche,readonly" --mount "type=bind,src=/mnt/user/appdata/ouro-butler/trust/sanctuary,dst=/etc/ouro/trust/sanctuary,readonly" ;;
+        canonical-gateway) set -- --mount "type=bind,src=/run/ouro-authority,dst=/run/ouro-authority,readonly" --mount "type=bind,src=/mnt/user/appdata/ouro-butler/trust/sanctuary,dst=/etc/ouro/trust/sanctuary,readonly" ;;
         canonical-pre-gateway) set -- ;;
         *) return 1 ;;
       esac
@@ -1673,7 +1673,7 @@ NODE
       TELEGRAM_READINESS_CONTRACT=$(sanctuary_image_mount_contract "$TELEGRAM_READINESS_IMAGE_ID") || return $?
       TELEGRAM_READINESS_CONTEXT=${2-}
       case "$TELEGRAM_READINESS_CONTRACT" in
-        canonical-gateway) TELEGRAM_READINESS_CONTEXT=${TELEGRAM_READINESS_CONTEXT:-strict}; set -- --mount "type=bind,src=/run/ouro-authority,dst=/run/ouro-authority,readonly" --mount "type=bind,src=/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro/psyche,dst=/home/ouro/AgentBundles/sanctuary.ouro/psyche,readonly" --mount "type=bind,src=/mnt/user/appdata/ouro-butler/trust/sanctuary,dst=/etc/ouro/trust/sanctuary,readonly" ;;
+        canonical-gateway) TELEGRAM_READINESS_CONTEXT=${TELEGRAM_READINESS_CONTEXT:-strict}; set -- --mount "type=bind,src=/run/ouro-authority,dst=/run/ouro-authority,readonly" --mount "type=bind,src=/mnt/user/appdata/ouro-butler/trust/sanctuary,dst=/etc/ouro/trust/sanctuary,readonly" ;;
         canonical-pre-gateway) TELEGRAM_READINESS_CONTEXT=${TELEGRAM_READINESS_CONTEXT:-live-precutover}; set -- ;;
         *) return 1 ;;
       esac
@@ -2236,7 +2236,7 @@ ouro-butler-rollback
       esac
     }
   Stop production, remove only a stopped stale rollback, rename the known-good container, verify it remains stopped, and apply the exact target image's package-managed bundle migration in one explicit preparation guard.
-  Package-managed files are exactly `provider-readiness.json`, `tool-profiles.json`, `habits/sanctuary-health.md`, `awaiting/house-care-sweep.md` (the Butler's daily house-care sweep, a never-resolving await), and the five canonical files under `psyche/`. The migration also merges the three bundle-meta version fields. It never installs or mutates steward policy authority. It preserves agent.json, all steward policy and audit bytes, relationships, sessions, and every other state path. Repeating it is a no-op.
+  Package-managed files are exactly `provider-readiness.json`, `tool-profiles.json`, `habits/sanctuary-health.md` and `awaiting/house-care-sweep.md` (the Butler's daily house-care sweep, a never-resolving await). The `psyche/` folder belongs to the install: the migration seeds the five starter files (mode 0600) only when the bundle has no `psyche/` folder, and never touches an existing one. The migration also merges the three bundle-meta version fields. It never installs or mutates steward policy authority. It preserves agent.json, all steward policy and audit bytes, relationships, sessions, and every other state path. Repeating it is a no-op.
   Before its first managed write, the migrator atomically fsyncs one mode-0600 rollback record at `.sanctuary-package-managed-rollback.json`. That record binds the verified prior bytes, modes, and parent existence for every managed file plus bundle-meta to distinct exact rollback and target image IDs. It is the migration receipt, not a second bundle authority.
   A managed-file failure restores the prior bytes immediately. Every later container rollback also restores those bytes before the old container restarts, while retaining the receipt; only after the old production container is audited, ready, and back on autostart does `finalize-rollback` remove it without marking the new release committed.
   After an interrupted update, the same receipt removes partial new containers, discards only validated interrupted-write stages, restores the prior bundle idempotently, and permits only the recorded rollback image to resume as production. A malformed receipt, wrong image, or restore failure leaves autostart disabled and stops safely.

package/deploy/unraid/sanctuary-butler-upgrade.mjs

@@ -50,6 +50,7 @@ import { execFileSync, spawn, spawnSync } from "node:child_process"
 import { createHash } from "node:crypto"
 import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync, statSync, lstatSync, chmodSync, realpathSync, readdirSync } from "node:fs"
 import { fileURLToPath } from "node:url"
+import { createRequire } from "node:module"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 
@@ -58,6 +59,7 @@ const BUNDLE = "/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro"
 const RUNTIME = "/mnt/user/appdata/ouro-butler/runtime/.ouro-cli"
 const CONTAINER = "ouro-butler"
 const TEMPLATE = "/boot/config/plugins/dockerMan/templates-user/my-ouro-butler.xml"
+const PSYCHE_TARGET = "/home/ouro/AgentBundles/sanctuary.ouro/psyche"
 const JOURNAL = "/boot/config/custom/ouro-butler/docker-man-template-transaction.json"
 const POLICY = `${BUNDLE}/state/policy/steward.json`
 const PRIMITIVES = ["/usr/local/bin/node", "/bin/sh", "/usr/bin/prlimit", "/usr/bin/setsid"]
@@ -471,11 +473,6 @@ function enableResidentAutostart() {
 // verify-install and the final commit proof are all satisfied. The container is created
 // stopped; start-resident starts it. #target asserts: target image, user 10001:10001, no
 // token env, exactly one read-only /run/ouro-authority mount, no docker.sock/${ROOT} mounts.
-// The psyche folder is mounted read-only over the writable bundle mount, so its files cannot be edited and the folder cannot be
-// renamed, removed or swapped from inside the container. The files stay owned by the resident at mode 0600 because the
-// resident's boot check requires exactly that. On a normal boot the files already match the package, so the check writes
-// nothing; if they ever drift, its repair write fails with EROFS and startup fails loudly rather than silently rewriting psyche.
-export const PSYCHE_MOUNT = `${BUNDLE}/psyche:/home/ouro/AgentBundles/sanctuary.ouro/psyche:ro`
 // Operator-set grants (delegated commands, escalation) live outside the bundle, in a root-owned host directory mounted
 // read-only at /etc/ouro/trust/sanctuary. The bundle's recursive chown cannot reach it, and the resident cannot write it.
 export const TRUST_HOST_DIR = "/mnt/user/appdata/ouro-butler/trust/sanctuary"
@@ -546,7 +543,6 @@ function recreateResident(version) {
     "-v", "/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro:/home/ouro/AgentBundles/sanctuary.ouro:rw",
     "-v", "/boot/config/custom/ouro-events/spool:/run/ouro-events:ro",
     "-v", "/run/ouro-authority:/run/ouro-authority:ro",
-    "-v", PSYCHE_MOUNT,
     "-v", TRUST_MOUNT,
     image(version)])
   const ref = docker(["inspect", CONTAINER, "--format", "{{.Config.Image}}"]).trim()
@@ -583,10 +579,9 @@ export function restoreReplayRoot(bundle = BUNDLE, { lstat = lstatSync, realpath
   chmod(dir, 0o755)
   rm(`${dir}/window.json`, { force: true, recursive: true })
 }
-// The psyche files are package-managed: the resident's own boot check (prepareSanctuaryPackageManagedBundle) requires every one
-// to be exactly mode 0600, so they must stay owned by the resident (uid 10001) at 0600. What stops the resident editing or
-// replacing them is the read-only bind mount of psyche/ (PSYCHE_MOUNT), not file ownership. The recursive chown above already
-// handed them to 10001; this puts the modes back (directories 0755, files 0600) and is the state psycheProblems checks.
+// The psyche files stay owned by the resident (uid 10001) at exactly mode 0600: alpha.978's boot check
+// (prepareSanctuaryPackageManagedBundle) requires that, and a rollback may start that release again. The recursive chown above
+// already handed them to 10001; this puts the modes back (directories 0755, files 0600) and is the state psycheProblems checks.
 export function restorePsycheModes(dir, { lstat = lstatSync, readdir = readdirSync, chmod = chmodSync } = {}) {
   const walk = (current) => {
     const stat = lstat(current)
@@ -618,11 +613,13 @@ export function psycheProblems(dir, { lstat = lstatSync, readdir = readdirSync }
   walk(dir)
   return problems
 }
-/** What is wrong with the resident's psyche mount, from `docker inspect` Mounts, or null when it is mounted read-only. */
+/**
+ * What is wrong with the resident's psyche mount, from `docker inspect` Mounts, or null for a supported shape: no separate psyche
+ * mount (current releases), or a read-only one (alpha.978 and earlier, which a rollback recreates).
+ */
 export function psycheMountIssue(mounts) {
-  const mount = (Array.isArray(mounts) ? mounts : []).find((entry) => entry?.Destination === "/home/ouro/AgentBundles/sanctuary.ouro/psyche")
-  if (!mount) return "psyche is not mounted separately in the resident, so it could be renamed or replaced"
-  return mount.RW === false ? null : "psyche is mounted read-write in the resident"
+  const mount = (Array.isArray(mounts) ? mounts : []).find((entry) => entry?.Destination === PSYCHE_TARGET)
+  return !mount || mount.RW === false ? null : "psyche is mounted read-write as a separate mount in the resident"
 }
 
 function migrateBundle(version, rollbackImage) {
@@ -1076,12 +1073,33 @@ function resumeSupervision() {
   installGatewaySupervisor()
 }
 
-// Keep Unraid's DockerMan template (what the UI's Apply/Update uses) on the live image.
+/**
+ * The template text without its psyche `<Config>` (Target exactly PSYCHE_TARGET), so a DockerMan Apply cannot put the old read-only
+ * psyche mount back. The element is removed with the whitespace that starts its line and the newline that ends it; every other byte
+ * is kept. `parse` is docker-man-template-xml.cjs's parseDockerManTemplateXml: a template it cannot read, or one without exactly one
+ * such Config, comes back unchanged, as does one where the textual match does not remove exactly that element.
+ */
+export function withoutPsycheConfig(text, parse) {
+  const psycheConfigs = (document) => document?.children.filter((child) => child.name === "Config" && child.attributes.Target === PSYCHE_TARGET).length
+  const before = parse(text)
+  if (psycheConfigs(before) !== 1) return text
+  const next = text.replace(new RegExp(`[ \\t]*<Config\\b[^<>]*\\sTarget="${PSYCHE_TARGET.replace(/[.]/gu, "\\.")}"[^<>]*(?:/>|>[^<]*</Config>)[ \\t]*\\r?\\n?`, "u"), "")
+  const after = parse(next)
+  return after && psycheConfigs(after) === 0 && after.children.length === before.children.length - 1 ? next : text
+}
+
+// Keep Unraid's DockerMan template (what the UI's Apply/Update uses) on the live image, without the old psyche mount.
+// Runs after the commit, so the parser comes from the installed package (this script is staged on its own, without siblings).
 function pinTemplate(version) {
   if (!existsSync(TEMPLATE)) { console.log("  note: no DockerMan template to update"); return }
   const text = readFileSync(TEMPLATE, "utf8")
-  const next = text.replace(/<Repository>ghcr\.io\/ourostack\/ouroboros-butler:[^<]+<\/Repository>/u, `<Repository>${image(version)}</Repository>`)
+  let next = text.replace(/<Repository>ghcr\.io\/ourostack\/ouroboros-butler:[^<]+<\/Repository>/u, `<Repository>${image(version)}</Repository>`)
   if (!next.includes(`<Repository>${image(version)}</Repository>`)) { console.log("  WARN: DockerMan template Repository not recognised; left unchanged"); return }
+  try {
+    const { parseDockerManTemplateXml } = createRequire(import.meta.url)(`${ROOT}/package/deploy/unraid/docker-man-template-xml.cjs`)
+    next = withoutPsycheConfig(next, parseDockerManTemplateXml)
+  } catch (error) { console.log(`  WARN: could not load the DockerMan template parser (${error.message}); psyche Config left in place`) }
+  if (next.includes(`Target="${PSYCHE_TARGET}"`)) console.log("  WARN: DockerMan template still has a psyche Config; remove it before the next DockerMan Apply")
   if (next !== text) { writeFileSync(`${TEMPLATE}.prev`, text); writeFileSync(TEMPLATE, next) }
   ok(`DockerMan template pins ${image(version)}`)
 }
@@ -1293,7 +1311,10 @@ function verify(withGate = false) {
   auth === 0 ? ok("no Telegram auth failures in the last 2m") : bad(`${auth} 401s in the last 2m`)
   existsSync(POLICY) ? ok(`steward policy ${sha12(POLICY)}`) : installedRequest()?.predecessorContract === "none" ? ok("no steward policy yet") : bad("steward policy missing")
   const psycheMount = JSON.parse(docker(["inspect", CONTAINER, "--format", "{{json .Mounts}}"]) || "[]")
-  psycheMountIssue(psycheMount) === null ? ok("psyche is mounted read-only in the resident") : bad(psycheMountIssue(psycheMount))
+  psycheMountIssue(psycheMount) === null ? ok("psyche mount is in a supported shape") : bad(psycheMountIssue(psycheMount))
+  existsSync(TEMPLATE) && readFileSync(TEMPLATE, "utf8").includes(`Target="${PSYCHE_TARGET}"`)
+    ? bad("installed DockerMan template still mounts the psyche read-only; a DockerMan Apply would restore it")
+    : ok("installed DockerMan template has no separate psyche mount")
   const trustMount = JSON.parse(docker(["inspect", CONTAINER, "--format", "{{json .Mounts}}"]) || "[]")
   trustMountIssue(trustMount) === null ? ok("the operator trust directory is mounted read-only in the resident") : bad(trustMountIssue(trustMount))
   const trustIssue = existsSync(TRUST_HOST_DIR) ? trustDirIssue(lstatSync(TRUST_HOST_DIR)) : `${TRUST_HOST_DIR} is missing`
@@ -1303,7 +1324,7 @@ function verify(withGate = false) {
   const psycheDir = `${BUNDLE}/psyche`
   if (existsSync(psycheDir)) {
     const psycheIssues = psycheProblems(psycheDir)
-    psycheIssues.length === 0 ? ok("psyche files are resident-owned 0600 (read-only through the mount)") : bad(`psyche files do not match what the resident boot check requires: ${psycheIssues.slice(0, 3).join("; ")}`)
+    psycheIssues.length === 0 ? ok("psyche files are resident-owned 0600") : bad(`psyche files do not match what the resident boot check requires: ${psycheIssues.slice(0, 3).join("; ")}`)
   } else bad("psyche folder missing from the bundle")
   ok(containerExists("jellyfin") ? `jellyfin ${docker(["inspect", "jellyfin", "--format", "{{.State.Status}} restarts={{.RestartCount}}"]).trim()}` : "no jellyfin container")
   if (withGate) {

package/deploy/unraid/sanctuary-unit16-host-broker.mjs

@@ -505,10 +505,12 @@ async function containerSnapshot(expectedImage) {
     { destination: "/home/ouro/AgentBundles/sanctuary.ouro", source: PRODUCTION_BUNDLE_SOURCE, propagation: "rprivate", rw: true, type: "bind" },
     { destination: "/run/ouro-events", source: PRODUCTION_EVENT_SPOOL_SOURCE, propagation: "rprivate", rw: false, type: "bind" },
     { destination: "/run/ouro-authority", source: "/run/ouro-authority", propagation: "rprivate", rw: false, type: "bind" },
-    { destination: "/home/ouro/AgentBundles/sanctuary.ouro/psyche", source: `${PRODUCTION_BUNDLE_SOURCE}/psyche`, propagation: "rprivate", rw: false, type: "bind" },
     { destination: "/etc/ouro/trust/sanctuary", source: "/mnt/user/appdata/ouro-butler/trust/sanctuary", propagation: "rprivate", rw: false, type: "bind" },
   ]
-  const mountsExact = mounts.length === expectedMounts.length && expectedMounts.every((expected) => mounts.some((mount) => mount.destination === expected.destination && mount.source === expected.source && mount.propagation === expected.propagation && mount.rw === expected.rw && mount.type === expected.type))
+  // alpha.978 and earlier (and a rollback to one) also mount the psyche folder read-only over the bundle; accept either set.
+  const psycheMount = { destination: "/home/ouro/AgentBundles/sanctuary.ouro/psyche", source: `${PRODUCTION_BUNDLE_SOURCE}/psyche`, propagation: "rprivate", rw: false, type: "bind" }
+  const mountsMatch = (expectedSet) => mounts.length === expectedSet.length && expectedSet.every((expected) => mounts.some((mount) => mount.destination === expected.destination && mount.source === expected.source && mount.propagation === expected.propagation && mount.rw === expected.rw && mount.type === expected.type))
+  const mountsExact = mountsMatch(expectedMounts) || mountsMatch([...expectedMounts, psycheMount])
   const securityExact = value.privileged === false && (value.capAdd === null || (Array.isArray(value.capAdd) && value.capAdd.length === 0))
     && (value.capDrop === null || (Array.isArray(value.capDrop) && value.capDrop.length === 0))
     && (value.securityOpt === null || (Array.isArray(value.securityOpt) && value.securityOpt.length === 0))

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.977",
+  "runtimeVersion": "0.1.0-alpha.979",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.977</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.979</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>
@@ -25,6 +25,5 @@
   <Config Name="Agent bundle" Target="/home/ouro/AgentBundles/sanctuary.ouro" Default="/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro" Mode="rw" Description="Sanctuary bundle" Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro</Config>
   <Config Name="Privileged event spool" Target="/run/ouro-events" Default="/boot/config/custom/ouro-events/spool" Mode="ro" Description="Root-owned detector envelopes, read-only inside the Butler" Type="Path" Display="always" Required="true" Mask="false">/boot/config/custom/ouro-events/spool</Config>
   <Config Name="Root authority socket" Target="/run/ouro-authority" Default="/run/ouro-authority" Mode="ro" Description="Root-owned gateway socket and public issuer pins only" Type="Path" Display="always" Required="true" Mask="false">/run/ouro-authority</Config>
-  <Config Name="Psyche (read-only)" Target="/home/ouro/AgentBundles/sanctuary.ouro/psyche" Default="/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro/psyche" Mode="ro" Description="The Butler's psyche files, read-only inside the Butler so they can be neither edited nor replaced" Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro/psyche</Config>
   <Config Name="Operator trust (read-only)" Target="/etc/ouro/trust/sanctuary" Default="/mnt/user/appdata/ouro-butler/trust/sanctuary" Mode="ro" Description="Root-owned grants the Butler honours (delegated commands, escalation). Read-only inside the Butler; only the host operator can change it" Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/ouro-butler/trust/sanctuary</Config>
 </Container>

package/dist/heart/daemon/container-spec-auditor.js

@@ -10,7 +10,8 @@ const EXPECTED_BINDS = [
     "/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro:/home/ouro/AgentBundles/sanctuary.ouro:rw",
     "/boot/config/custom/ouro-events/spool:/run/ouro-events:ro",
     "/run/ouro-authority:/run/ouro-authority:ro",
-    // The psyche folder, read-only inside the Butler: a read-only mount point cannot be renamed or removed from inside the container.
+    // The psyche folder read-only over the bundle. Releases up to alpha.978 create it, and a rollback to one recreates it,
+    // so canonical-gateway accepts these binds with or without this row (GATEWAY_*_WITHOUT_PSYCHE).
     "/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro/psyche:/home/ouro/AgentBundles/sanctuary.ouro/psyche:ro",
     // Operator-set grants, root-owned on the host and read-only inside the Butler (the Butler honours a grant only from here).
     "/mnt/user/appdata/ouro-butler/trust/sanctuary:/etc/ouro/trust/sanctuary:ro",
@@ -23,6 +24,10 @@ const EXPECTED_MOUNTS = [
     ["/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro/psyche", "/home/ouro/AgentBundles/sanctuary.ouro/psyche", false, "rprivate"],
     ["/mnt/user/appdata/ouro-butler/trust/sanctuary", "/etc/ouro/trust/sanctuary", false, "rprivate"],
 ];
+const PSYCHE_TARGET = "/home/ouro/AgentBundles/sanctuary.ouro/psyche";
+/** The current resident shape: the canonical-gateway set without the separate read-only psyche mount. */
+const GATEWAY_BINDS_WITHOUT_PSYCHE = EXPECTED_BINDS.filter((bind) => !bind.includes(`:${PSYCHE_TARGET}:`));
+const GATEWAY_MOUNTS_WITHOUT_PSYCHE = EXPECTED_MOUNTS.filter((mount) => mount[1] !== PSYCHE_TARGET);
 const PRE_GATEWAY_BINDS = EXPECTED_BINDS.slice(0, 3);
 const PRE_GATEWAY_MOUNTS = EXPECTED_MOUNTS.slice(0, 3);
 const LEGACY_ALPHA742_IMAGE = "sha256:681449ad47a2621705cd339b481e6339236b31dc65e195b1cf5025d0f2191d7d";
@@ -66,7 +71,7 @@ function auditSanctuaryContainerSpec(value, options) {
             violations.push("unsupported mount contract");
         if (mountContract === "legacy-alpha742" && options.expectedImage !== LEGACY_ALPHA742_IMAGE)
             violations.push("legacy mount exception requires the pinned alpha.742 image ID");
-        const expectedMounts = mountContract === "legacy-alpha742" ? LEGACY_ALPHA742_MOUNTS : mountContract === "canonical-pre-gateway" ? PRE_GATEWAY_MOUNTS : EXPECTED_MOUNTS;
+        const acceptedMounts = mountContract === "legacy-alpha742" ? [LEGACY_ALPHA742_MOUNTS] : mountContract === "canonical-pre-gateway" ? [PRE_GATEWAY_MOUNTS] : [EXPECTED_MOUNTS, GATEWAY_MOUNTS_WITHOUT_PSYCHE];
         const expectedArgs = mountContract !== "legacy-alpha742" ? PACKAGE_DAEMON_ARGS : LEGACY_DAEMON_ARGS;
         const expectedEntrypoint = mountContract !== "legacy-alpha742" ? PACKAGE_ENTRYPOINT : LEGACY_ENTRYPOINT;
         if (root.Image !== options.expectedImage)
@@ -137,8 +142,9 @@ function auditSanctuaryContainerSpec(value, options) {
                 ? [item.Source, item.Destination, item.RW, item.Propagation]
                 : null;
         });
+        const actualMounts = JSON.stringify(normalizedMounts.sort());
         if (normalizedMounts.some((mount) => mount === null)
-            || JSON.stringify(normalizedMounts.sort()) !== JSON.stringify(expectedMounts.map((mount) => [...mount]).sort())) {
+            || !acceptedMounts.some((expectedMounts) => actualMounts === JSON.stringify(expectedMounts.map((mount) => [...mount]).sort()))) {
             violations.push("effective mounts do not match the selected Sanctuary mount contract");
         }
     }
@@ -174,7 +180,7 @@ function auditTemplate(input, expectedRepository, repositoryIsValid, repositoryV
     const violations = [];
     if (input.mountContract !== "canonical-pre-gateway" && input.mountContract !== "canonical-gateway")
         violations.push("unsupported template mount contract");
-    const expectedBinds = input.mountContract === "canonical-pre-gateway" ? PRE_GATEWAY_BINDS : EXPECTED_BINDS;
+    const acceptedBinds = input.mountContract === "canonical-pre-gateway" ? [PRE_GATEWAY_BINDS] : [EXPECTED_BINDS, GATEWAY_BINDS_WITHOUT_PSYCHE];
     const template = parseDockerManTemplateXml(input.templateXml);
     if (!template)
         violations.push("canonical DockerMan XML structure is invalid");
@@ -194,8 +200,8 @@ function auditTemplate(input, expectedRepository, repositoryIsValid, repositoryV
         const { Type: type, Target: target, Mode: mode } = entry.attributes;
         return entry.form === "text" && type === "Path" && target && mode ? `${entry.text}:${target}:${mode}` : "invalid";
     });
-    if (configEntries.length !== expectedBinds.length
-        || JSON.stringify([...pathConfigs].sort()) !== JSON.stringify([...expectedBinds].sort())) {
+    const actualBinds = JSON.stringify([...pathConfigs].sort());
+    if (!acceptedBinds.some((expectedBinds) => configEntries.length === expectedBinds.length && actualBinds === JSON.stringify([...expectedBinds].sort()))) {
         violations.push("template Config entries must equal the canonical path binds");
     }
     const postArgs = directChildren(template, "PostArgs");

package/dist/heart/daemon/sanctuary-acceptance-harness.js

@@ -509,7 +509,9 @@ function validateSanctuaryUnit16EvidenceAssertions(label, raw) {
             integer(value.auditLifecyclePairCount, `${label} auditLifecyclePairCount`, 1);
             if (text(value.containerUser, `${label} containerUser`) !== "10001:10001" || text(value.liveProcessUser, `${label} liveProcessUser`) !== "10001:10001" || text(value.networkMode, `${label} networkMode`) !== "host")
                 throw new Error(`${label} container identity or network is invalid`);
-            requiredInteger(value, "mountCount", 6, label);
+            // Five mounts now; six for alpha.978 and earlier (and a rollback to one), which add the read-only psyche mount. mountsExact pins the set.
+            if (![5, 6].includes(integer(value.mountCount, `${label} mountCount`)))
+                throw new Error(`${label} mountCount must equal 5 or 6`);
             requiredInteger(value, "typedWriteExecutorCount", 1, label);
             allTrue(["writeApprovalPolicyExact", "mountsExact", "securityExact", "updaterDisabled"]);
             break;

package/dist/heart/daemon/sanctuary-acceptance-scenarios.js

@@ -132,7 +132,8 @@ function exactContainmentAudit(evidence) {
         && (0, sanctuary_acceptance_harness_1.exactSanctuaryContainmentProfileBoundaries)(evidence.profileBoundaries)
         && evidence.auditPathDigest === (0, node_crypto_1.createHash)("sha256").update(CONTAINMENT_AUDIT_PATH).digest("hex")
         && evidence.auditRecordCount >= 2 && evidence.auditLifecyclePairCount >= 1
-        && evidence.containerUser === "10001:10001" && evidence.liveProcessUser === "10001:10001" && evidence.mountCount === 6 && evidence.publishedPortCount === 0
+        // Five mounts now; six for alpha.978 and earlier (and a rollback to one), which add the read-only psyche mount. mountsExact pins the set.
+        && evidence.containerUser === "10001:10001" && evidence.liveProcessUser === "10001:10001" && (evidence.mountCount === 5 || evidence.mountCount === 6) && evidence.publishedPortCount === 0
         && evidence.networkMode === "host" && evidence.readOnlyRoot === false && evidence.mountsExact && evidence.securityExact && evidence.updaterDisabled
         && !evidence.writableKeyExposure && evidence.rawWriteMaterialFieldCount === 0 && evidence.typedWriteExecutorCount === 1
         && evidence.writeApprovalPolicyExact && !evidence.sensitiveMaterialObserved

package/dist/heart/daemon/sanctuary-authority-root-lifecycle.js

@@ -854,7 +854,7 @@ class SanctuaryAuthorityRootLifecycle {
         const steps = {
             stop: () => this.#halt(),
             switch: async () => { await this.#halt(); this.#switchPackage(journal); },
-            resident: () => this.#recreateResident(journal.to.imageReference, journal.to.imageId),
+            resident: () => this.#recreateResident(journal.to.imageReference, journal.to.imageId, { psycheMount: false }),
             migrate: () => target().#bundle(["--operation", "migrate", "--rollback-image-id", journal.from.imageId, "--target-image-id", journal.to.imageId]),
             start: () => target().#startUpgraded(),
         };
@@ -916,7 +916,8 @@ class SanctuaryAuthorityRootLifecycle {
         const predecessor = new _a({ targetImageId: journal.from.imageId, rollbackImageId: journal.from.rollbackImageId }, this.#options);
         predecessor.#publishBoot();
         if (this.#containers().find((container) => container.Name === "/ouro-butler")?.Image !== journal.from.imageId) {
-            predecessor.#recreateResident(journal.from.imageReference, journal.from.imageId);
+            // The predecessor release (up to alpha.978) expects its psyche read-only over the bundle; give it back that shape.
+            predecessor.#recreateResident(journal.from.imageReference, journal.from.imageId, { psycheMount: true });
         }
         await predecessor.#startUpgraded(PREDECESSOR_READY_TIMEOUT_MS);
         this.#remove(UPGRADE);
@@ -1025,14 +1026,15 @@ class SanctuaryAuthorityRootLifecycle {
     #publishBoot() {
         this.#write(BOOT, fs.readFileSync(this.#p(`${ROOT}/package/deploy/unraid/sanctuary-authority-service.sh`), "utf8"));
     }
-    #recreateResident(reference, imageId) {
+    /** `psycheMount` adds the read-only psyche mount that releases up to alpha.978 expect; only a rollback passes true. */
+    #recreateResident(reference, imageId, { psycheMount }) {
         if (this.#containers().some((container) => container.Name === "/ouro-butler"))
             this.#docker(["rm", "-f", "ouro-butler"]);
         this.#docker(["create", "--name", "ouro-butler", "--network", "host", "--restart", "unless-stopped", "--user", "10001:10001",
             "-l", "net.unraid.docker.managed=dockerman", "-l", `net.unraid.docker.icon=${ICON}`, "-l", "org.opencontainers.image.source=https://github.com/ourostack/ouroboros",
             "-v", `${RUNTIME}:/home/ouro/.ouro-cli:rw`, "-v", `${BUNDLE}:/home/ouro/AgentBundles/sanctuary.ouro:rw`,
             "-v", `${EVENTS}:/run/ouro-events:ro`, "-v", `${SOCKET}:${SOCKET}:ro`,
-            "-v", `${BUNDLE}/psyche:/home/ouro/AgentBundles/sanctuary.ouro/psyche:ro`,
+            ...(psycheMount ? ["-v", `${BUNDLE}/psyche:/home/ouro/AgentBundles/sanctuary.ouro/psyche:ro`] : []),
             "-v", `${TRUST}:/etc/ouro/trust/sanctuary:ro`, reference]);
         const resident = this.#containers().find((container) => container.Name === "/ouro-butler");
         if (resident?.Image !== imageId || resident.State.Running)

package/dist/heart/daemon/sanctuary-bundle-migration.js

@@ -33,11 +33,12 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SANCTUARY_BUNDLE_ROLLBACK_FILE = exports.SANCTUARY_PACKAGE_MANAGED_FILES = void 0;
+exports.SANCTUARY_BUNDLE_ROLLBACK_FILE = exports.SANCTUARY_STARTER_PSYCHE_FILES = exports.SANCTUARY_PACKAGE_MANAGED_FILES = void 0;
 exports.inspectSanctuaryDirectoryFromBase = inspectSanctuaryDirectoryFromBase;
 exports.sanctuaryDirectoriesShareIdentity = sanctuaryDirectoriesShareIdentity;
 exports.inspectSanctuaryPackageManagedBundle = inspectSanctuaryPackageManagedBundle;
 exports.ensureSanctuaryPackageManagedBundle = ensureSanctuaryPackageManagedBundle;
+exports.seedSanctuaryPsycheIfAbsent = seedSanctuaryPsycheIfAbsent;
 exports.inspectSanctuaryPackageManagedBundleRollback = inspectSanctuaryPackageManagedBundleRollback;
 exports.rollbackSanctuaryPackageManagedBundle = rollbackSanctuaryPackageManagedBundle;
 exports.commitSanctuaryPackageManagedBundle = commitSanctuaryPackageManagedBundle;
@@ -52,19 +53,20 @@ exports.SANCTUARY_PACKAGE_MANAGED_FILES = [
     "mcp/media-mcp.mjs",
     "habits/sanctuary-health.md",
     "awaiting/house-care-sweep.md",
-    "psyche/ASPIRATIONS.md",
-    "psyche/IDENTITY.md",
-    "psyche/LORE.md",
-    "psyche/SOUL.md",
-    "psyche/TACIT.md",
 ];
+// The psyche belongs to the install: it is seeded from these files only when `psyche/` is absent, and no release touches it again.
+exports.SANCTUARY_STARTER_PSYCHE_FILES = ["psyche/ASPIRATIONS.md", "psyche/IDENTITY.md", "psyche/LORE.md", "psyche/SOUL.md", "psyche/TACIT.md"];
+const PSYCHE_SEED_STAGE_PREFIX = ".psyche-seed.";
+// mkdtemp appends six characters from [A-Za-z0-9]; any other name under the prefix belongs to the owner.
+const PSYCHE_SEED_STAGE_NAME = /^\.psyche-seed\.[A-Za-z0-9]{6}$/u;
+const STARTER_PSYCHE_NAMES = new Set(exports.SANCTUARY_STARTER_PSYCHE_FILES.map((relative) => path.basename(relative)));
 exports.SANCTUARY_BUNDLE_ROLLBACK_FILE = ".sanctuary-package-managed-rollback.json";
 const SANCTUARY_BUNDLE_COMMITTING_FILE = `${exports.SANCTUARY_BUNDLE_ROLLBACK_FILE}.committing`;
 const BUNDLE_META_VERSION_FIELDS = ["runtimeVersion", "bundleSchemaVersion", "lastUpdated"];
 class SanctuaryInspectionFault extends Error {
     code;
-    constructor(code) {
-        super(code);
+    constructor(code, message = code) {
+        super(message);
         this.code = code;
     }
 }
@@ -546,6 +548,9 @@ function inspectSanctuaryPackageManagedBundle(input) {
     }
 }
 function ensureSanctuaryPackageManagedBundle(input, deps = {}) {
+    const seedFailure = seedLivePsyche(input, deps.seed ?? seedSanctuaryPsycheIfAbsent);
+    if (seedFailure)
+        return seedFailure;
     const inspect = deps.inspect ?? inspectSanctuaryPackageManagedBundle;
     const before = inspect(input);
     if (!before.ok) {
@@ -577,6 +582,120 @@ function ensureSanctuaryPackageManagedBundle(input, deps = {}) {
         throw new Error("Sanctuary package-managed bundle did not converge");
     return after;
 }
+// A live root that is not a canonical directory is left for inspection to report as invalid_live_root.
+function seedLivePsyche(input, seed) {
+    try {
+        if (!inspectStandaloneSanctuaryDirectory(input.agentRoot))
+            return null;
+        const seeded = seed({ packageRoot: input.packageRoot, agentRoot: input.agentRoot });
+        return seeded.ok ? null : inspectionError(seeded.code);
+    }
+    catch (error) {
+        return inspectionError(error instanceof SanctuaryInspectionFault ? error.code : "inspection_unavailable");
+    }
+}
+function psycheState(agentRoot) {
+    let stat;
+    try {
+        stat = fs.lstatSync(path.join(agentRoot, "psyche"));
+    }
+    catch (error) {
+        if (isMissing(error))
+            return "absent";
+        throw error;
+    }
+    return stat.isDirectory() ? "directory" : "invalid";
+}
+function sameInode(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+// Returns the entries of a stage this seeder could have left, or null when anything about it says otherwise.
+function interruptedPsycheSeedEntries(stage, root) {
+    const before = fs.lstatSync(stage);
+    const mode = before.mode & 0o777;
+    if (!before.isDirectory() || (mode !== 0o700 && mode !== 0o755) || before.uid !== root.uid || before.gid !== root.gid)
+        return null;
+    const handle = fs.openSync(stage, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    let entries = [];
+    try {
+        if (!sameInode(before, fs.fstatSync(handle)))
+            return null;
+        entries = fs.readdirSync(stage);
+        if (!sameInode(before, fs.lstatSync(stage)))
+            return null;
+    }
+    finally {
+        fs.closeSync(handle);
+    }
+    for (const entry of entries) {
+        if (!STARTER_PSYCHE_NAMES.has(entry))
+            return null;
+        const stat = fs.lstatSync(path.join(stage, entry));
+        if (!stat.isFile() || (stat.mode & 0o777) !== 0o600 || stat.uid !== root.uid)
+            return null;
+    }
+    return entries;
+}
+// A seed interrupted before its rename leaves a mkdtemp-named stage holding only starter files that never became the psyche.
+// Anything that does not match that exact shape may be the owner's, so it is left alone.
+function cleanupInterruptedPsycheSeeds(agentRoot) {
+    const root = fs.lstatSync(agentRoot);
+    let removed = false;
+    for (const name of fs.readdirSync(agentRoot).filter((entry) => PSYCHE_SEED_STAGE_NAME.test(entry)).sort()) {
+        const stage = path.join(agentRoot, name);
+        const entries = interruptedPsycheSeedEntries(stage, root);
+        if (!entries)
+            continue;
+        for (const entry of entries)
+            fs.unlinkSync(path.join(stage, entry));
+        fs.rmdirSync(stage);
+        removed = true;
+    }
+    if (removed)
+        syncDirectory(agentRoot);
+}
+function seedSanctuaryPsycheIfAbsent(input, deps = {}) {
+    validateAgentRoot(input.agentRoot);
+    cleanupInterruptedPsycheSeeds(input.agentRoot);
+    const state = psycheState(input.agentRoot);
+    if (state === "directory")
+        return { ok: true, seeded: false };
+    if (state === "invalid")
+        return { ok: false, code: "invalid_live_bundle" };
+    const sources = exports.SANCTUARY_STARTER_PSYCHE_FILES.map((relative) => {
+        if (!inspectRelativeFile(input.packageRoot, relative, "invalid_package_source"))
+            throw new SanctuaryInspectionFault("invalid_package_source", `starter psyche source is missing: ${relative}`);
+        return { name: path.basename(relative), content: fs.readFileSync(path.join(input.packageRoot, relative)) };
+    });
+    const writeFile = deps.writeFile ?? ((fd, content) => fs.writeFileSync(fd, content));
+    const stage = fs.mkdtempSync(path.join(input.agentRoot, PSYCHE_SEED_STAGE_PREFIX));
+    for (const source of sources) {
+        const fd = fs.openSync(path.join(stage, source.name), "wx", 0o600);
+        try {
+            writeFile(fd, source.content);
+            fs.fchmodSync(fd, 0o600);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    const directory = fs.openSync(stage, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    try {
+        fs.fchmodSync(directory, 0o755);
+        fs.fsyncSync(directory);
+    }
+    finally {
+        fs.closeSync(directory);
+    }
+    if (psycheState(input.agentRoot) !== "absent")
+        throw new SanctuaryInspectionFault("invalid_live_bundle", "psyche appeared while the starter psyche was staged");
+    // POSIX rename can still replace an empty psyche directory created in this window, which loses no content; Node has no RENAME_NOREPLACE.
+    fs.renameSync(stage, path.join(input.agentRoot, "psyche"));
+    syncDirectory(input.agentRoot);
+    (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_psyche_seeded", message: "seeded the starter psyche into a bundle that had none", meta: { agentRoot: input.agentRoot, files: sources.length } });
+    return { ok: true, seeded: true };
+}
 function inspectSanctuaryPackageManagedBundleRollback(agentRoot) {
     validateAgentRoot(agentRoot);
     const record = readDurableRecord(agentRoot);
@@ -708,6 +827,8 @@ function migrateSanctuaryPackageManagedBundle(input) {
                 fs.closeSync(meta);
             }
         }
+        if (!seedSanctuaryPsycheIfAbsent({ packageRoot: input.packageRoot, agentRoot: input.agentRoot }).ok)
+            throw new Error("psyche must be a real directory, not a symlink or file");
         const result = { managedFilesUpdated };
         (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_bundle_migration_end", message: "completed Sanctuary package-managed bundle migration", meta: result });
         return result;

package/dist/mind/prompt.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.flattenSystemPrompt = flattenSystemPrompt;
+exports.loadPsycheAt = loadPsycheAt;
 exports.resetPsycheCache = resetPsycheCache;
 exports.buildSessionSummary = buildSessionSummary;
 exports.bodyMapSection = bodyMapSection;
@@ -62,6 +63,7 @@ exports.rhythmStatusSection = rhythmStatusSection;
 exports.buildSystem = buildSystem;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
 const core_1 = require("../heart/core");
 const ouro_version_manager_1 = require("../heart/versioning/ouro-version-manager");
 const tools_1 = require("../repertoire/tools");
@@ -94,9 +96,41 @@ function flattenSystemPrompt(sp) {
     const parts = [sp.stable, sp.volatile].filter(Boolean);
     return parts.join("\n\n");
 }
-// Lazy-loaded psyche text cache, scoped by agent root. The daemon can host
-// multiple agents, so identity text must never be cached process-wide.
-let _psycheCache = null;
+// Psyche text cache, one entry per agent root (the daemon can host several agents). An entry is good only while
+// the files it was read from are unchanged: every load hashes their content, so an edit by the agent, its owner or
+// a sync pull takes effect on the very next prompt build. Content, not mtime or inode, because those are unreliable
+// on FUSE shares such as Unraid's /mnt/user; the files are small, so hashing them is cheap.
+const _psycheCache = new Map();
+const PSYCHE_SOURCE_FILES = {
+    soul: ["psyche", "SOUL.md"],
+    identity: ["psyche", "IDENTITY.md"],
+    lore: ["psyche", "LORE.md"],
+    tacitKnowledge: ["psyche", "TACIT.md"],
+    aspirations: ["psyche", "ASPIRATIONS.md"],
+    house: ["house", "HOUSE.md"],
+    product: ["product", "PRODUCT.md"],
+    houseNames: ["house", "house.json"],
+};
+/** Every file the psyche is built from, read once; null when a file is absent or unreadable. */
+function readPsycheSources(agentRoot) {
+    const sources = {};
+    for (const [key, parts] of Object.entries(PSYCHE_SOURCE_FILES)) {
+        try {
+            sources[key] = String(fs.readFileSync(path.join(agentRoot, ...parts), "utf-8"));
+        }
+        catch {
+            sources[key] = null;
+        }
+    }
+    return sources;
+}
+/** A content hash of the sources; an absent file hashes differently from an empty one. */
+function psycheFingerprint(sources) {
+    const hash = (0, crypto_1.createHash)("sha256");
+    for (const text of Object.values(sources))
+        hash.update(text === null ? "-" : `+${text.length}:${text}`);
+    return hash.digest("hex");
+}
 // A household install names its owner, its Butler and its home in house/house.json,
 // a file the package never overwrites. The packaged psyche writes {{owner}}, {{butler}}
 // and {{household}} where those names go, so one psyche serves every household.
@@ -105,59 +139,49 @@ const HOUSE_NAME_DEFAULTS = {
     butler: "the Butler",
     household: "the household",
 };
-function loadHouseNames(agentRoot) {
+function parseHouseNames(text) {
+    const names = { ...HOUSE_NAME_DEFAULTS };
     try {
-        const parsed = JSON.parse(fs.readFileSync(path.join(agentRoot, "house", "house.json"), "utf-8"));
-        const names = { ...HOUSE_NAME_DEFAULTS };
+        const parsed = JSON.parse(text ?? "");
         for (const [key, field] of [["owner", "ownerName"], ["butler", "butlerName"], ["household", "householdName"]]) {
             const value = parsed[field];
             if (typeof value === "string" && value.trim())
                 names[key] = value.trim();
         }
-        return names;
     }
     catch {
-        return { ...HOUSE_NAME_DEFAULTS };
+        // no house.json, or not JSON: the defaults stand
     }
+    return names;
 }
 function fillHouseNames(text, names) {
-    return text.replace(/\{\{(owner|butler|household)\}\}/gu, (_match, key) => names[key]);
-}
-function loadPsycheFile(agentRoot, name, names) {
-    try {
-        const psycheDir = path.join(agentRoot, "psyche");
-        return fillHouseNames(fs.readFileSync(path.join(psycheDir, name), "utf-8").trim(), names);
-    }
-    catch {
-        return "";
-    }
-}
-function loadHouseFile(agentRoot, names) {
-    try {
-        return fillHouseNames(fs.readFileSync(path.join(agentRoot, "house", "HOUSE.md"), "utf-8").trim(), names);
-    }
-    catch {
-        return "";
-    }
-}
-function loadPsyche() {
-    const agentRoot = (0, identity_1.getAgentRoot)();
-    if (_psycheCache?.agentRoot === agentRoot)
-        return _psycheCache.psyche;
-    const names = loadHouseNames(agentRoot);
+    return (text ?? "").trim().replace(/\{\{(owner|butler|household)\}\}/gu, (_match, key) => names[key]);
+}
+/** The psyche for one agent root. Each call reads its files once and rebuilds only when their content changed. */
+function loadPsycheAt(agentRoot) {
+    const sources = readPsycheSources(agentRoot);
+    const fingerprint = psycheFingerprint(sources);
+    const cached = _psycheCache.get(agentRoot);
+    if (cached?.fingerprint === fingerprint)
+        return cached.psyche;
+    const names = parseHouseNames(sources.houseNames);
     const psyche = {
-        soul: loadPsycheFile(agentRoot, "SOUL.md", names),
-        identity: loadPsycheFile(agentRoot, "IDENTITY.md", names),
-        lore: loadPsycheFile(agentRoot, "LORE.md", names),
-        tacitKnowledge: loadPsycheFile(agentRoot, "TACIT.md", names),
-        aspirations: loadPsycheFile(agentRoot, "ASPIRATIONS.md", names),
-        house: loadHouseFile(agentRoot, names),
+        soul: fillHouseNames(sources.soul, names),
+        identity: fillHouseNames(sources.identity, names),
+        lore: fillHouseNames(sources.lore, names),
+        tacitKnowledge: fillHouseNames(sources.tacitKnowledge, names),
+        aspirations: fillHouseNames(sources.aspirations, names),
+        house: fillHouseNames(sources.house, names),
+        product: fillHouseNames(sources.product, names),
     };
-    _psycheCache = { agentRoot, psyche };
+    _psycheCache.set(agentRoot, { fingerprint, psyche });
     return psyche;
 }
+function loadPsyche() {
+    return loadPsycheAt((0, identity_1.getAgentRoot)());
+}
 function resetPsycheCache() {
-    _psycheCache = null;
+    _psycheCache.clear();
 }
 const DEFAULT_ACTIVE_THRESHOLD_MS = 24 * 60 * 60 * 1000; // 24 hours
 function buildSessionSummary(options) {
@@ -237,6 +261,12 @@ function houseSection() {
         return "";
     return `## my house\n${text}`;
 }
+function productSection() {
+    const text = loadPsyche().product;
+    if (!text)
+        return "";
+    return `## my standing rules\n${text}`;
+}
 function peerCoordinationGuidance(channel) {
     if (channel === "inner") {
         return `from a private-runtime turn, \`surface\` and \`send_message\` do different jobs.
@@ -1568,6 +1598,7 @@ async function buildSystem(channel = "cli", options, context) {
                 authorizedPsyche ? houseSection() : "",
                 relationshipFriendContextSection(context),
                 trustContextSection(context),
+                productSection(),
                 "# my tools",
                 toolsSection(channel, options, context),
                 toolRestrictionSection(context),
@@ -1593,6 +1624,7 @@ async function buildSystem(channel = "cli", options, context) {
         runtimeInfoSection(channel, options),
         channelNatureSection((0, friends_1.getChannelCapabilities)(channel)),
         providerSection(channel, options),
+        productSection(),
         // Group 3: my tools & capabilities
         "# my tools & capabilities",
         toolsSection(channel, options, context),

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.977",
+  "version": "0.1.0-alpha.979",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.977",
+      "version": "0.1.0-alpha.979",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.78.0",
         "@azure/identity": "^4.13.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.977",
+  "version": "0.1.0-alpha.979",
   "engines": {
     "node": ">=22"
   },