@ouro.bot/cli 0.1.0-alpha.980 → 0.1.0-alpha.982

package/README.md

@@ -1,3 +1,9 @@
+<!-- ourostack:brand:start -->
+<p align="center">
+  <a href="https://github.com/ourostack"><img src="https://raw.githubusercontent.com/ourostack/.github/main/brand/ouro.png" alt="Ouro" width="160" height="160"></a>
+</p>
+<!-- ourostack:brand:end -->
+
 # Ouroboros Agent Harness
 
 If you're a future agent reading this, welcome home. This repo is the harness that gives you your body, your senses, your record, your habits, and your ability to think and connect with people. The goal of these docs is not just to be correct, but to leave you a place that feels understandable and kind to wake up inside.

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.982",
+      "changes": [
+        "An agent's psyche and friend records can no longer be reached by a write through a relative path, a case-altered path or a symlink."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.981",
+      "changes": [
+        "Ouro admins can run Hosted Desk from the terminal. `ouro desk invite --name <name>` creates an account and issues a single-use, seven-day invite, and `--account <id>` re-invites an account whose invite went unused; `--out <file>` writes the link to a new 0600 file instead of the screen. `ouro desk access <account> on|off` turns an account's Desk access on or off and prints the state the gateway recorded, and `ouro desk delete-account <account> --yes` deletes one and says if its desk could not be removed. Each command signs in to Ouro identity in the browser (authorization code with PKCE on a 127.0.0.1 loopback redirect), reads the sign-in settings the gateway publishes at /.well-known/ouro-desk-admin, checks the tenant's issuer and then calls the gateway's admin route, which enforces the ouro.admin role. desk.ouro.bot must name Ouro's production tenant, and any other gateway needs --trust-gateway because it receives an admin token. Nothing is cached, and the token is never printed or logged."
+      ]
+    },
     {
       "version": "0.1.0-alpha.980",
       "changes": [

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

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.980",
+  "runtimeVersion": "0.1.0-alpha.982",
   "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.980</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.982</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/heart/daemon/cli-desk.js

@@ -43,6 +43,7 @@ exports.parseDeskCommand = parseDeskCommand;
 exports.parseTaskAliasCommand = parseTaskAliasCommand;
 exports.executeDeskCommand = executeDeskCommand;
 const runtime_1 = require("../../nerves/runtime");
+const desk_admin_1 = require("./desk-admin");
 // ── Public usage hint ──
 function deskUsage() {
     return [
@@ -62,6 +63,12 @@ function deskUsage() {
         "  ouro desk reindex",
         "  ouro desk thread <path>",
         "",
+        "Hosted Desk admin (needs the ouro.admin role; signs in through the browser):",
+        "  ouro desk invite --name <name> [--out <file>]       (--account <id> re-invites an unused account)",
+        "  ouro desk access <account> on|off",
+        "  ouro desk delete-account <account> --yes",
+        "  (each takes --gateway <url> --trust-gateway to manage a Hosted Desk other than desk.ouro.bot)",
+        "",
         "Alias:",
         "  ouro task ...    (routes through ouro desk task ...)",
     ].join("\n");
@@ -219,6 +226,8 @@ function parseDeskCommand(args) {
         return parseFrictionSubverb(rest);
     if (head === "lesson")
         return parseLessonSubverb(rest);
+    if (head === "invite" || head === "access" || head === "delete-account")
+        return (0, desk_admin_1.parseDeskAdminCommand)(head, rest);
     if (head === "search") {
         const query = rest.join(" ").trim();
         if (!query)

package/dist/heart/daemon/cli-exec.js

@@ -103,6 +103,7 @@ const cli_parse_2 = require("./cli-parse");
 const cli_help_1 = require("./cli-help");
 const plugin_cli_1 = require("./plugin-cli");
 const cli_desk_1 = require("./cli-desk");
+const desk_admin_1 = require("./desk-admin");
 const migrate_to_desk_1 = require("./migrate-to-desk");
 const core_2 = require("../../nerves/review/core");
 const cli_render_1 = require("./cli-render");
@@ -8062,6 +8063,10 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
     if (command.kind === "desk") {
         return (0, cli_desk_1.executeDeskCommand)(command, deps);
     }
+    // ── Hosted Desk admin (HTTPS to the gateway after an Ouro sign-in; no daemon needed) ──
+    if (command.kind === "desk.admin") {
+        return (0, desk_admin_1.executeDeskAdminCommand)(command, deps);
+    }
     // ── move: make this machine the agent's home (local, no daemon needed) ──
     if (command.kind === "agent.move") {
         return executeAgentMove(command, deps);

package/dist/heart/daemon/cli-help.js

@@ -192,10 +192,10 @@ exports.COMMAND_REGISTRY = {
     },
     desk: {
         category: "Tasks",
-        description: "Manage the agent's desk — tasks, tracks, friction, lessons, search, and recall (routes through the desk MCP server).",
-        usage: "ouro desk <task|track|friction|lesson|search|recall|reindex|thread> ...",
-        example: "ouro desk task list",
-        subcommands: ["task", "track", "friction", "lesson", "search", "recall", "reindex", "thread"],
+        description: "Manage the agent's desk — tasks, tracks, friction, lessons, search, and recall (routes through the desk MCP server). Ouro admins also invite people to Hosted Desk and manage their access.",
+        usage: "ouro desk <task|track|friction|lesson|search|recall|reindex|thread|invite|access|delete-account> ...",
+        example: "ouro desk invite --name \"Sam\"",
+        subcommands: ["task", "track", "friction", "lesson", "search", "recall", "reindex", "thread", "invite", "access", "delete-account"],
     },
     task: {
         category: "Tasks",

package/dist/heart/daemon/desk-admin.js

@@ -0,0 +1,420 @@
+"use strict";
+/**
+ * Hosted Desk admin commands: `ouro desk invite`, `ouro desk access` and
+ * `ouro desk delete-account`.
+ *
+ * Each command signs the person in to Ouro identity (Entra External ID) with
+ * an authorization-code + PKCE flow on a loopback redirect (RFC 8252), then
+ * calls the gateway's admin route with the access token. The gateway, not this
+ * CLI, enforces the `ouro.admin` app role.
+ *
+ * The gateway publishes what the sign-in needs at `ADMIN_CONFIG_PATH`:
+ * `{ tenantId, subdomain, clientId, scope }`. The CLI reads the tenant's
+ * discovery document from `<subdomain>.ciamlogin.com` and requires the issuer
+ * `https://<tenantId>.ciamlogin.com/<tenantId>/v2.0`, the same check the
+ * gateway makes. The default gateway must name Ouro's production tenant. Any
+ * other gateway receives an admin token, so it needs `--trust-gateway`.
+ *
+ * Nothing is cached: the token lives only for the one command, and it is never
+ * printed or logged. An invite link is a single-use bearer credential, so
+ * `--out` writes it to a new 0600 file instead of the screen.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SIGN_IN_TIMEOUT_MS = exports.ADMIN_CONFIG_PATH = exports.PRODUCTION_TENANT_ID = exports.DEFAULT_DESK_GATEWAY = void 0;
+exports.shown = shown;
+exports.parseDeskAdminCommand = parseDeskAdminCommand;
+exports.gatewayOrigin = gatewayOrigin;
+exports.signInForDeskAdmin = signInForDeskAdmin;
+exports.executeDeskAdminCommand = executeDeskAdminCommand;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_http_1 = require("node:http");
+const runtime_1 = require("../../nerves/runtime");
+exports.DEFAULT_DESK_GATEWAY = "https://desk.ouro.bot";
+/** Ouro's production External ID tenant (`ourobot`), which the default gateway must name. */
+exports.PRODUCTION_TENANT_ID = "de8841c3-7799-4523-bbad-44f8a2426eaa";
+exports.ADMIN_CONFIG_PATH = "/.well-known/ouro-desk-admin";
+exports.SIGN_IN_TIMEOUT_MS = 5 * 60_000;
+const REQUEST_TIMEOUT_MS = 15_000;
+const ACCOUNT_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SUBDOMAIN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i;
+/** Server-supplied text made safe to print: no control characters, bounded length. */
+function shown(value, max = 200) {
+    // eslint-disable-next-line no-control-regex
+    return String(value).replace(/[\u0000-\u001f\u007f-\u009f]/g, "").slice(0, max);
+}
+// ── Parsing ──
+const GATEWAY_FLAGS = "[--gateway <url> --trust-gateway]";
+const USAGE = {
+    invite: `Usage: ouro desk invite --name <name> | --account <id> [--out <file>] ${GATEWAY_FLAGS}`,
+    access: `Usage: ouro desk access <account> on|off ${GATEWAY_FLAGS}`,
+    "delete-account": `Usage: ouro desk delete-account <account> --yes ${GATEWAY_FLAGS}`,
+};
+function splitFlags(args, valued, boolean, usage) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith("--")) {
+            positional.push(arg);
+            continue;
+        }
+        if (boolean.includes(arg)) {
+            flags[arg] = true;
+            continue;
+        }
+        const value = args[i + 1];
+        if (!valued.includes(arg) || value === undefined || value.startsWith("--"))
+            throw new Error(usage);
+        flags[arg] = value;
+        i++;
+    }
+    return { positional, flags };
+}
+function accountIdOf(value) {
+    if (!ACCOUNT_ID.test(value))
+        throw new Error(`'${shown(value, 80)}' is not an account id: use the id Hosted Desk gave the account`);
+    return value;
+}
+function gatewayOf(flags) {
+    return {
+        ...(typeof flags["--gateway"] === "string" ? { gateway: flags["--gateway"] } : {}),
+        ...(flags["--trust-gateway"] === true ? { trustGateway: true } : {}),
+    };
+}
+function parseDeskAdminCommand(verb, args) {
+    const usage = USAGE[verb];
+    if (verb === "invite") {
+        const { positional, flags } = splitFlags(args, ["--name", "--account", "--out", "--gateway"], ["--trust-gateway"], usage);
+        const displayName = typeof flags["--name"] === "string" ? flags["--name"].trim() : "";
+        const account = typeof flags["--account"] === "string" ? flags["--account"] : undefined;
+        // --name invites a new person; --account re-invites an account whose invite went unused.
+        if (positional.length > 0 || (!displayName) === (account === undefined))
+            throw new Error(usage);
+        return {
+            kind: "desk.admin",
+            action: "invite",
+            ...(account === undefined ? { displayName } : { accountId: accountIdOf(account) }),
+            ...gatewayOf(flags),
+            ...(typeof flags["--out"] === "string" ? { out: flags["--out"] } : {}),
+        };
+    }
+    if (verb === "access") {
+        const { positional, flags } = splitFlags(args, ["--gateway"], ["--trust-gateway"], usage);
+        const [id, state] = positional;
+        if (positional.length !== 2 || (state !== "on" && state !== "off"))
+            throw new Error(usage);
+        return { kind: "desk.admin", action: "access", accountId: accountIdOf(id), on: state === "on", ...gatewayOf(flags) };
+    }
+    const { positional, flags } = splitFlags(args, ["--gateway"], ["--yes", "--trust-gateway"], usage);
+    if (positional.length !== 1)
+        throw new Error(usage);
+    const accountId = accountIdOf(positional[0]);
+    if (flags["--yes"] !== true) {
+        throw new Error(`Deleting account ${accountId} removes its Hosted Desk account and sign-ins and cannot be undone; pass --yes to confirm.\n${usage}`);
+    }
+    return { kind: "desk.admin", action: "delete-account", accountId, ...gatewayOf(flags) };
+}
+// ── Gateway ──
+/** The gateway's origin, or null when the value is not a bare https origin. */
+function gatewayOrigin(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (/[?#]/.test(value) || url.protocol !== "https:" || url.username || url.password || url.search || url.hash || (url.pathname !== "/" && url.pathname !== ""))
+        return null;
+    return url.origin;
+}
+async function getJson(fetchImpl, url) {
+    const response = await fetchImpl(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    if (!response.ok)
+        throw new Error(`${url} answered ${response.status}`);
+    return response.json();
+}
+function isHttps(value) {
+    return typeof value === "string" && URL.canParse(value) && new URL(value).protocol === "https:";
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+const CALLBACK_PAGE = (heading, detail) => `<!doctype html><meta charset="utf-8"><title>Ouro sign-in</title><body style="font-family:system-ui;margin:3rem"><h1>${heading}</h1><p>${detail}</p></body>`;
+/**
+ * Waits for the browser's redirect. Only a request carrying this sign-in's
+ * state settles it, so a stray request to the loopback port can't end it.
+ */
+function listenForCallback(state, timeoutMs) {
+    return new Promise((resolveListening, rejectListening) => {
+        const { promise: result, resolve: settle, reject: fail } = Promise.withResolvers();
+        // Handled by the caller's await; this keeps an early timeout from becoming an unhandled rejection.
+        result.catch(() => { });
+        const server = (0, node_http_1.createServer)((request, response) => {
+            const url = new URL(request.url, "http://127.0.0.1");
+            if (url.pathname !== "/callback") {
+                response.writeHead(404).end();
+                return;
+            }
+            if (url.searchParams.get("state") !== state) {
+                response.writeHead(400, { "content-type": "text/html; charset=utf-8" }).end(CALLBACK_PAGE("Not this sign-in", "This link does not belong to the sign-in the terminal is waiting for."));
+                return;
+            }
+            const code = url.searchParams.get("code");
+            const error = url.searchParams.get("error");
+            const callback = { ...(code ? { code } : {}), ...(error ? { error } : {}) };
+            const page = code && !error
+                ? CALLBACK_PAGE("Signed in to Ouro", "You can close this tab and go back to the terminal.")
+                : CALLBACK_PAGE("Sign-in did not finish", "Go back to the terminal to see why.");
+            response.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" }).end(page);
+            settle(callback);
+        });
+        const timer = setTimeout(() => fail(new Error(`Ouro sign-in timed out after ${Math.round(timeoutMs / 1000)} seconds`)), timeoutMs);
+        const close = () => {
+            clearTimeout(timer);
+            // Idle only: the browser's own request may still be receiving its page.
+            server.close();
+            server.closeIdleConnections();
+        };
+        server.once("error", rejectListening);
+        server.listen(0, "127.0.0.1", () => {
+            const { port } = server.address();
+            resolveListening({ redirectUri: `http://127.0.0.1:${port}/callback`, result, close });
+        });
+    });
+}
+/** Signs in to Ouro identity for the gateway's admin scope and returns the access token. */
+async function signInForDeskAdmin(input) {
+    const configUrl = `${input.gateway}${exports.ADMIN_CONFIG_PATH}`;
+    const config = (await getJson(input.fetchImpl, configUrl));
+    if (!config
+        || typeof config.tenantId !== "string" || !GUID.test(config.tenantId)
+        || typeof config.subdomain !== "string" || !SUBDOMAIN.test(config.subdomain)
+        || !nonEmpty(config.clientId) || !nonEmpty(config.scope)) {
+        throw new Error(`${configUrl} is not a valid admin sign-in configuration`);
+    }
+    // Entra's discovery names the tenant in lowercase.
+    const tenantId = config.tenantId.toLowerCase();
+    if (input.expectedTenantId && tenantId !== input.expectedTenantId.toLowerCase()) {
+        throw new Error(`${input.gateway} names Ouro identity tenant ${tenantId}, not Ouro's production tenant ${input.expectedTenantId}`);
+    }
+    const issuer = `https://${tenantId}.ciamlogin.com/${tenantId}/v2.0`;
+    const discovery = (await getJson(input.fetchImpl, `https://${config.subdomain}.ciamlogin.com/${tenantId}/v2.0/.well-known/openid-configuration`));
+    if (discovery?.issuer !== issuer) {
+        throw new Error(`Ouro identity's discovery document names issuer ${shown(discovery?.issuer)}, but Hosted Desk expects ${issuer}`);
+    }
+    if (!isHttps(discovery.authorization_endpoint) || !isHttps(discovery.token_endpoint)) {
+        throw new Error("Ouro identity's discovery document has no https authorization and token endpoints");
+    }
+    const verifier = (0, node_crypto_1.randomBytes)(32).toString("base64url");
+    const state = (0, node_crypto_1.randomBytes)(16).toString("base64url");
+    const listener = await listenForCallback(state, input.timeoutMs ?? exports.SIGN_IN_TIMEOUT_MS);
+    try {
+        const authorize = new URL(discovery.authorization_endpoint);
+        authorize.search = new URLSearchParams({
+            client_id: config.clientId,
+            response_type: "code",
+            redirect_uri: listener.redirectUri,
+            scope: config.scope,
+            state,
+            code_challenge: (0, node_crypto_1.createHash)("sha256").update(verifier).digest("base64url"),
+            code_challenge_method: "S256",
+            prompt: "select_account",
+        }).toString();
+        input.writeStdout(`Sign in to Ouro in your browser to manage ${new URL(input.gateway).host}. If it does not open, visit:\n${authorize.toString()}`);
+        // Not awaited: some openers stay in the foreground until the browser exits.
+        void Promise.resolve().then(() => input.openUrl(authorize.toString())).catch(() => { });
+        const callback = await listener.result;
+        if (callback.error)
+            throw new Error(`Ouro sign-in was cancelled: ${shown(callback.error, 80)}`);
+        if (!callback.code)
+            throw new Error("Ouro sign-in returned no code");
+        const response = await input.fetchImpl(discovery.token_endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body: new URLSearchParams({
+                grant_type: "authorization_code",
+                client_id: config.clientId,
+                code: callback.code,
+                redirect_uri: listener.redirectUri,
+                code_verifier: verifier,
+            }).toString(),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        const grant = (await response.json().catch(() => null));
+        if (!response.ok)
+            throw new Error(`Ouro sign-in could not finish: ${nonEmpty(grant?.error) ? shown(grant.error, 80) : `token endpoint answered ${response.status}`}`);
+        if (!nonEmpty(grant?.access_token))
+            throw new Error("Ouro sign-in could not finish: no access token");
+        return grant.access_token;
+    }
+    finally {
+        listener.close();
+    }
+}
+/* v8 ignore start -- production default: launches the platform's browser opener @preserve */
+function openInBrowser(url) {
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["rundll32", ["url.dll,FileProtocolHandler", url]]
+            : ["xdg-open", [url]];
+    // Detached and unreferenced: an opener that stays in the foreground must not keep the CLI from exiting.
+    return new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)(command, args, { detached: true, stdio: "ignore" });
+        child.once("spawn", () => { child.unref(); resolve(); });
+        child.once("error", reject);
+    });
+}
+/* v8 ignore stop */
+// ── Executing ──
+function requestFor(command) {
+    if (command.action === "invite") {
+        return { method: "POST", path: "/admin/invites", body: command.accountId ? { accountId: command.accountId } : { displayName: command.displayName } };
+    }
+    const account = `/admin/accounts/${encodeURIComponent(command.accountId)}`;
+    if (command.action === "access")
+        return { method: "POST", path: `${account}/access`, body: { on: command.on } };
+    return { method: "DELETE", path: account };
+}
+async function refusal(response) {
+    if (response.status === 401)
+        return "Hosted Desk did not accept the Ouro sign-in (401). Sign in again; if it keeps failing, the gateway's admin sign-in settings are wrong.";
+    if (response.status === 403)
+        return "Hosted Desk refused the request (403): the signed-in Ouro account needs the ouro.admin role.";
+    const body = (await response.json().catch(() => null));
+    const reason = nonEmpty(body?.message) ? body.message : nonEmpty(body?.error) ? body.error : null;
+    return reason ? `Hosted Desk refused the request (${response.status}): ${shown(reason)}` : `Hosted Desk refused the request (${response.status}).`;
+}
+async function executeDeskAdminCommand(command, deps, signIn = signInForDeskAdmin) {
+    const requested = command.gateway ?? exports.DEFAULT_DESK_GATEWAY;
+    const gateway = gatewayOrigin(requested);
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.desk_admin_start",
+        message: `ouro desk ${command.action}`,
+        meta: { action: command.action, gateway: gateway ?? "invalid" },
+    });
+    const fail = (message, status) => {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "daemon",
+            event: "daemon.desk_admin_error",
+            message: `ouro desk ${command.action} failed`,
+            meta: { action: command.action, gateway: gateway ?? "invalid", ...(status === undefined ? {} : { status }) },
+        });
+        deps.setExitCode?.(1);
+        deps.writeStdout(message);
+        return message;
+    };
+    const done = (message, status) => {
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.desk_admin_end",
+            message: `ouro desk ${command.action} succeeded`,
+            meta: { action: command.action, gateway, status },
+        });
+        deps.writeStdout(message);
+        return message;
+    };
+    if (!gateway)
+        return fail(`The Hosted Desk gateway must be a bare https origin such as ${exports.DEFAULT_DESK_GATEWAY}, not ${shown(requested, 120)}`);
+    const isDefault = gateway === exports.DEFAULT_DESK_GATEWAY;
+    if (!isDefault && command.trustGateway !== true) {
+        return fail(`${gateway} is not ${exports.DEFAULT_DESK_GATEWAY}. Signing in sends it an Ouro admin token, so pass --trust-gateway only for a Hosted Desk we run, such as staging.`);
+    }
+    // Claim the --out file before minting the invite, so a bad path costs no live link.
+    const outPath = command.action === "invite" ? command.out : undefined;
+    if (outPath) {
+        try {
+            (0, node_fs_1.closeSync)((0, node_fs_1.openSync)(outPath, "wx", 0o600));
+        }
+        catch (error) {
+            const code = error.code;
+            return fail(code === "EEXIST" ? `${outPath} already exists; choose a new file for the invite link` : `Could not create ${outPath}: ${error.message}`);
+        }
+    }
+    const releaseOut = () => {
+        if (outPath)
+            (0, node_fs_1.unlinkSync)(outPath);
+    };
+    /* v8 ignore next -- production default: tests always inject fetchImpl @preserve */
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    let token;
+    try {
+        token = await signIn({
+            gateway,
+            fetchImpl,
+            /* v8 ignore next -- production default: tests inject openUrl or a sign-in @preserve */
+            openUrl: deps.openUrl ?? openInBrowser,
+            writeStdout: deps.writeStdout,
+            ...(isDefault ? { expectedTenantId: exports.PRODUCTION_TENANT_ID } : {}),
+        });
+    }
+    catch (error) {
+        releaseOut();
+        return fail(error.message);
+    }
+    const request = requestFor(command);
+    let response;
+    try {
+        response = await fetchImpl(`${gateway}${request.path}`, {
+            method: request.method,
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: "application/json",
+                ...(request.body === undefined ? {} : { "content-type": "application/json" }),
+            },
+            ...(request.body === undefined ? {} : { body: JSON.stringify(request.body) }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        releaseOut();
+        return fail(`Could not reach Hosted Desk at ${gateway}: ${error.message}`);
+    }
+    if (!response.ok) {
+        releaseOut();
+        return fail(await refusal(response), response.status);
+    }
+    const result = (await response.json().catch(() => null));
+    if (command.action === "access") {
+        if (typeof result?.deskAccess !== "boolean")
+            return fail("Hosted Desk sent an unexpected access response", response.status);
+        return done(`Desk access for ${command.accountId} is now ${result.deskAccess ? "on" : "off"}.`, response.status);
+    }
+    if (command.action === "delete-account") {
+        if (result?.deleted !== true)
+            return fail("Hosted Desk sent an unexpected delete response", response.status);
+        const leftover = result.deskRemoved === false ? " Its desk could not be removed from the gateway; the gateway logged why." : "";
+        return done(`Deleted account ${command.accountId}.${leftover}`, response.status);
+    }
+    if (!isHttps(result?.inviteUrl) || !nonEmpty(result?.expiresAt)
+        || typeof result?.accountId !== "string" || !ACCOUNT_ID.test(result.accountId)
+        || (command.accountId !== undefined && result.accountId !== command.accountId)) {
+        releaseOut();
+        return fail("Hosted Desk sent an unexpected invite response", response.status);
+    }
+    const link = new URL(result.inviteUrl).href;
+    const who = command.displayName ? `${command.displayName} (account ${result.accountId})` : `account ${result.accountId}`;
+    const lead = `Invite for ${who}, single use, expires ${shown(result.expiresAt, 40)}.`;
+    if (!outPath)
+        return done(`${lead}\n${link}`, response.status);
+    try {
+        const fd = (0, node_fs_1.openSync)(outPath, node_fs_1.constants.O_WRONLY | node_fs_1.constants.O_TRUNC | node_fs_1.constants.O_NOFOLLOW);
+        try {
+            (0, node_fs_1.writeSync)(fd, `${link}\n`);
+        }
+        finally {
+            (0, node_fs_1.closeSync)(fd);
+        }
+    }
+    catch (error) {
+        releaseOut();
+        return fail(`The invite for account ${result.accountId} was issued, but ${outPath} could not be written (${error.message}). Issue a new link with: ouro desk invite --account ${result.accountId}`);
+    }
+    return done(`${lead} The link is in ${outPath} (mode 0600).`, response.status);
+}

package/dist/repertoire/guardrails.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OURO_CLI_TRUST_MANIFEST = void 0;
+exports.canonicalTarget = canonicalTarget;
+exports.insideAgentFolder = insideAgentFolder;
 exports.guardInvocation = guardInvocation;
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
@@ -42,6 +44,7 @@ const friends_1 = require("@ouro.bot/friends");
 const shell_quote_1 = require("shell-quote");
 const runtime_1 = require("../nerves/runtime");
 const store_1 = require("../commerce/store");
+const identity_1 = require("../heart/identity");
 const deny = (reason) => ({ allowed: false, reason });
 const allow = { allowed: true };
 // --- reason templates ---
@@ -70,10 +73,68 @@ const PROTECTED_PATH_SEGMENTS = [
     "state/reports/",
 ];
 const PROTECTED_FILENAMES = ["agent.json", "tool-profiles.json"];
-/** The agent's psyche folder ships only from the repository (a pull request and the replay gate), so no tool writes into it. */
+/** How many symlinks a dangling-link walk follows before refusing (the Linux kernel's own limit is 40). */
+const MAX_SYMLINK_HOPS = 40;
+/** A lookup that failed only because part of the path does not exist yet; any other failure leaves the target unknown. */
+function rethrowUnlessMissing(error) {
+    const code = error.code;
+    if (code !== "ENOENT" && code !== "ENOTDIR")
+        throw error;
+}
+/**
+ * The real location of `lexical`: `realpathSync.native` of the deepest part that exists, the final file included, with the
+ * missing remainder appended. A dangling symlink is followed, from its real parent, to where a write through it would land.
+ * Throws when the filesystem cannot say where the path lands (a denied lookup, a symlink loop, too many links), so the
+ * guard can refuse rather than fall back to the lexical path.
+ */
+function canonicalize(lexical) {
+    let current = lexical;
+    const missing = [];
+    let hops = 0;
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync.native(current), ...missing);
+        }
+        catch (error) {
+            rethrowUnlessMissing(error);
+        }
+        let stat;
+        try {
+            stat = fs.lstatSync(current);
+        }
+        catch (error) {
+            rethrowUnlessMissing(error);
+        }
+        if (stat?.isSymbolicLink()) {
+            if (hops >= MAX_SYMLINK_HOPS)
+                throw new Error(`too many symbolic links resolving ${lexical}`);
+            hops += 1;
+            current = path.resolve(fs.realpathSync.native(path.dirname(current)), fs.readlinkSync(current));
+            continue;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return path.join(current, ...missing);
+        missing.unshift(path.basename(current));
+        current = parent;
+    }
+}
+/**
+ * Every place a file tool could write `p`: resolved against the agent root and against the repo root (which is what
+ * `write_file` and `edit_file` use), each in its lexical and canonical form. An absolute `p` is resolved only as itself.
+ */
+function canonicalTarget(p, agentRoot) {
+    const lexicals = path.isAbsolute(p) ? [p] : [path.resolve(agentRoot, p), path.resolve((0, identity_1.getRepoRoot)(), p)];
+    return lexicals.flatMap((lexical) => [lexical, canonicalize(lexical)]);
+}
+/** True when any form of `p` is the agent's `folder` (in either its lexical or its canonical form) or under it. */
+function insideAgentFolder(p, agentRoot, folder) {
+    const lexicalFolder = path.resolve(agentRoot, folder);
+    const folders = [lexicalFolder, canonicalize(lexicalFolder)];
+    return canonicalTarget(p, agentRoot).some((target) => folders.some((dir) => target === dir || target.startsWith(`${dir}${path.sep}`)));
+}
+/** The agent's psyche folder ships only from the repository (a pull request and the replay gate), so no tool writes into it. The shell check uses this lexical form; the file tools use `insideAgentFolder`. */
 function isPsychePath(filePath, agentRoot) {
-    if (!agentRoot || !filePath)
-        return false;
     const psyche = path.resolve(agentRoot, "psyche");
     const target = path.resolve(agentRoot, filePath);
     return target === psyche || target.startsWith(`${psyche}${path.sep}`);
@@ -85,8 +146,6 @@ function isPsychePath(filePath, agentRoot) {
  * only: a shell can still write anywhere its uid can, which is why delegated-command authority lives outside the bundle.
  */
 function isFriendsStorePath(filePath, agentRoot) {
-    if (!agentRoot || !filePath)
-        return false;
     const store = path.resolve(agentRoot, "friends");
     const target = path.resolve(agentRoot, filePath);
     return target === store || target.startsWith(`${store}${path.sep}`);
@@ -272,9 +331,21 @@ function checkDestructiveShellPatterns(toolName, args) {
 function checkProtectedPaths(toolName, args, context) {
     if (toolName === "write_file" || toolName === "edit_file") {
         const filePath = args.path || "";
-        if (isPsychePath(filePath, context.agentRoot))
-            return deny(REASONS.psychePath);
-        if (isProtectedPath(filePath) || isFriendsStorePath(filePath, context.agentRoot))
+        // The file tools resolve a relative path against the repo root and follow symlinks, so the guard checks every form.
+        // A path whose landing place the filesystem cannot report is refused rather than checked lexically.
+        const agentRoot = filePath ? context.agentRoot : undefined;
+        if (agentRoot) {
+            try {
+                if (insideAgentFolder(filePath, agentRoot, "psyche"))
+                    return deny(REASONS.psychePath);
+                if (insideAgentFolder(filePath, agentRoot, "friends"))
+                    return deny(REASONS.protectedPath);
+            }
+            catch {
+                return deny(REASONS.protectedPath);
+            }
+        }
+        if (isProtectedPath(filePath))
             return deny(REASONS.protectedPath);
     }
     if (toolName === "shell") {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.980",
+  "version": "0.1.0-alpha.982",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.980",
+      "version": "0.1.0-alpha.982",
       "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.980",
+  "version": "0.1.0-alpha.982",
   "engines": {
     "node": ">=22"
   },