@ouro.bot/cli 0.1.0-alpha.918 → 0.1.0-alpha.919

package/changelog.json

@@ -1,6 +1,14 @@
 {
   "_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.919",
+      "changes": [
+        "Shepherd now sends the agent's owner a short Teams message for every coding-agent return it judges, saying what it did and why; set senses.shepherd.notify to needs-me or off to hear less.",
+        "Link a new account, such as Teams, to yourself by sending your agent a one-time code from it, and merge duplicate friend records with ouro friend dedupe.",
+        "Your agent can now type an instruction or press a key in one of your coding agents' terminals when you ask it to, so you can steer them from your phone."
+      ]
+    },
     {
       "version": "0.1.0-alpha.918",
       "changes": [

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

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

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

@@ -62,6 +62,8 @@ const semver = __importStar(require("semver"));
 const identity_1 = require("../identity");
 const runtime_1 = require("../../nerves/runtime");
 const friends_1 = require("@ouro.bot/friends");
+const friend_merge_1 = require("../../mind/friend-merge");
+const friend_link_codes_1 = require("../../mind/friend-link-codes");
 const runtime_metadata_1 = require("./runtime-metadata");
 const runtime_mode_1 = require("./runtime-mode");
 const platform_1 = require("../platform");
@@ -506,6 +508,9 @@ function agentResolutionFailureMode(command) {
         case "friend.show":
         case "friend.create":
         case "friend.update":
+        case "friend.linkCode":
+        case "friend.merge":
+        case "friend.dedupe":
         case "habit.list":
         case "habit.create":
         case "habit.runs":
@@ -6145,7 +6150,30 @@ async function performSystemSetup(deps) {
     await registerOuroBundleTypeNonBlocking(deps);
 }
 // ── Friend command execution ──
-async function executeFriendCommand(command, store) {
+async function executeFriendCommand(command, store, paths) {
+    if (command.kind === "friend.linkCode")
+        return executeFriendLinkCode(command, store, paths.agentRoot);
+    if (command.kind === "friend.merge") {
+        const result = await (0, friend_merge_1.mergeFriends)({
+            store,
+            friendsDir: paths.friendsDir,
+            targetId: command.targetId,
+            sourceIds: command.sourceIds,
+            actor: "cli:friend-merge",
+            reason: "owner merged records from the CLI",
+            dryRun: !command.apply,
+        });
+        if (!result.ok)
+            return `error: ${result.message}`;
+        return renderFriendMerge(result.target, result.retired.map((retired) => retired.friendId), result.preservedNoteKeys, result.addedExternalIds, result.dryRun);
+    }
+    if (command.kind === "friend.dedupe") {
+        const result = await (0, friend_merge_1.dedupeFriends)({ store, friendsDir: paths.friendsDir, actor: "cli:friend-dedupe", dryRun: !command.apply });
+        if (result.groups.length === 0)
+            return "no duplicate friend records found";
+        const blocks = result.groups.map((group) => renderFriendMerge(group.canonical, group.duplicateIds, group.preservedNoteKeys, group.addedExternalIds, result.dryRun));
+        return [...blocks, ...(result.dryRun ? ["", "dry run: nothing changed. Re-run with --apply to merge."] : [])].join("\n");
+    }
     if (command.kind === "friend.list") {
         const listAll = store.listAll;
         if (!listAll)
@@ -6229,6 +6257,50 @@ async function executeFriendCommand(command, store) {
         return `identity not linked: ${command.provider}:${command.externalId}`;
     return `unlinked ${command.provider}:${command.externalId} from ${command.friendId}`;
 }
+function renderFriendMerge(target, retiredIds, preservedNoteKeys, addedExternalIds, dryRun) {
+    const verb = dryRun ? "would merge" : "merged";
+    const lines = [`${verb} ${retiredIds.length} record(s) into ${target.id} (${target.name}, ${target.trustLevel})`];
+    for (const id of retiredIds)
+        lines.push(`  ${dryRun ? "would retire" : "retired"} ${id}`);
+    for (const externalId of addedExternalIds)
+        lines.push(`  ${dryRun ? "would link" : "linked"} ${externalId.provider}:${externalId.externalId}${externalId.tenantId ? ` (tenant ${externalId.tenantId})` : ""}`);
+    if (preservedNoteKeys.length > 0)
+        lines.push(`  kept conflicting notes as: ${preservedNoteKeys.join(", ")}`);
+    return lines.join("\n");
+}
+async function executeFriendLinkCode(command, store, agentRoot) {
+    let friend;
+    if (command.friendId) {
+        friend = await store.get(command.friendId);
+        if (!friend || friend.id !== command.friendId)
+            return `friend not found: ${command.friendId}`;
+    }
+    else {
+        // The person at this terminal owns the agent: their family record carries a local identity for this OS user.
+        const owner = (0, friends_1.machineOwnerUsername)();
+        const all = store.listAll ? await store.listAll() : [];
+        const candidates = all.filter((record) => record.trustLevel === "family"
+            && record.externalIds.some((externalId) => (0, friends_1.isLocalMachineOwnerIdentity)(externalId.provider, externalId.externalId, owner)));
+        if (candidates.length === 0)
+            return "error: no family record names this machine's owner. Pass --friend <friend-id>.";
+        if (candidates.length > 1)
+            return `error: ${candidates.length} family records name this machine's owner. Run \`ouro friend dedupe --apply\` first, or pass --friend <friend-id>.`;
+        friend = candidates[0];
+    }
+    const issued = (0, friend_link_codes_1.issueLinkCode)({
+        agentRoot,
+        friend,
+        ...(command.channel ? { channel: command.channel } : {}),
+        ...(command.ttlMinutes ? { ttlMs: command.ttlMinutes * 60 * 1000 } : {}),
+        issuedBy: "cli",
+    });
+    const minutes = Math.round((Date.parse(issued.expiresAt) - Date.now()) / 60000);
+    const where = issued.channel ? `from your ${issued.channel} account` : "from the account you want to link";
+    return [
+        `link code for ${friend.name} (${friend.trustLevel}): ${issued.code}`,
+        `Send exactly this code to ${path.basename(agentRoot, ".ouro")} ${where}, in a 1:1 chat, within ${minutes} minutes. It works once.`,
+    ].join("\n");
+}
 async function executeA2AClientCommand(command, deps) {
     const { loadOrMintA2AIdentityFile } = await Promise.resolve().then(() => __importStar(require("../../a2a/identity")));
     /* v8 ignore next -- production CLI keeps the client key under the home dir; tests pass an explicit file @preserve */
@@ -8107,19 +8179,16 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
     }
     // ── friend subcommands (local, no daemon socket needed) ──
     if (command.kind === "friend.list" || command.kind === "friend.show" || command.kind === "friend.create" ||
-        command.kind === "friend.update" || command.kind === "friend.link" || command.kind === "friend.unlink") {
-        /* v8 ignore start -- production default: requires full identity setup @preserve */
-        let store = deps.friendStore;
-        if (!store) {
-            // Derive agent-scoped friends dir from --agent flag or link/unlink's agent field
-            const agentName = ("agent" in command && command.agent) ? command.agent : undefined;
-            const friendsDir = agentName
-                ? path.join(deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)(), `${agentName}.ouro`, "friends")
-                : path.join(deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)(), "friends");
-            store = new friends_1.FileFriendStore(friendsDir);
-        }
-        /* v8 ignore stop */
-        const message = await executeFriendCommand(command, store);
+        command.kind === "friend.update" || command.kind === "friend.link" || command.kind === "friend.unlink" ||
+        command.kind === "friend.linkCode" || command.kind === "friend.merge" || command.kind === "friend.dedupe") {
+        // Derive agent-scoped friends dir from --agent flag or link/unlink's agent field
+        const agentName = ("agent" in command && command.agent) ? command.agent : undefined;
+        const bundlesRoot = deps.bundlesRoot ?? /* v8 ignore next -- production default @preserve */ (0, identity_1.getAgentBundlesRoot)();
+        const agentRoot = agentName ? path.join(bundlesRoot, `${agentName}.ouro`) : bundlesRoot;
+        const friendsDir = path.join(agentRoot, "friends");
+        /* v8 ignore next -- production default: requires full identity setup @preserve */
+        const store = deps.friendStore ?? new friends_1.FileFriendStore(friendsDir);
+        const message = await executeFriendCommand(command, store, { agentRoot, friendsDir });
         deps.writeStdout(message);
         return message;
     }

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

@@ -240,9 +240,9 @@ exports.COMMAND_REGISTRY = {
     friend: {
         category: "Friends",
         description: "Manage agent friends and identity links",
-        usage: "ouro friend <subcommand> [--agent <name>]",
-        example: "ouro friend list",
-        subcommands: ["list", "show", "create", "update", "link", "unlink"],
+        usage: "ouro friend <subcommand> [--agent <name>]  (link --channel <channel> issues a one-time code; merge/dedupe preview unless --apply)",
+        example: "ouro friend link --agent ouroboros --channel teams",
+        subcommands: ["list", "show", "create", "update", "link", "unlink", "merge", "dedupe"],
     },
     link: {
         category: "Friends",

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

@@ -1631,12 +1631,76 @@ function parseFriendCommand(args) {
             ...(agent ? { agent } : {}),
         };
     }
-    if (sub === "link")
-        return parseLinkCommand(rest, "friend.link");
+    if (sub === "link") {
+        // Without an explicit identity, `link` issues a code the person sends from the new account.
+        if (!rest.includes("--provider") && !rest.includes("--external-id") && (agent || rest[0]?.startsWith("--"))) {
+            return parseFriendLinkCodeCommand(rest, agent);
+        }
+        return parseLinkCommand(agent ? [agent, ...rest] : rest, "friend.link");
+    }
     if (sub === "unlink")
-        return parseLinkCommand(rest, "friend.unlink");
+        return parseLinkCommand(agent ? [agent, ...rest] : rest, "friend.unlink");
+    if (sub === "merge") {
+        const usage = "Usage: ouro friend merge --into <friend-id> <friend-id>... [--agent <name>] [--apply]";
+        let targetId;
+        let apply = false;
+        const sourceIds = [];
+        for (let i = 0; i < rest.length; i += 1) {
+            const token = rest[i];
+            if (token === "--into") {
+                targetId = rest[i + 1];
+                i += 1;
+            }
+            else if (token === "--apply") {
+                apply = true;
+            }
+            else if (token.startsWith("--")) {
+                throw new Error(usage);
+            }
+            else {
+                sourceIds.push(token);
+            }
+        }
+        if (!targetId || sourceIds.length === 0)
+            throw new Error(usage);
+        return { kind: "friend.merge", targetId, sourceIds, apply, ...(agent ? { agent } : {}) };
+    }
+    if (sub === "dedupe") {
+        const usage = "Usage: ouro friend dedupe [--agent <name>] [--apply]";
+        if (rest.some((token) => token !== "--apply"))
+            throw new Error(usage);
+        return { kind: "friend.dedupe", apply: rest.includes("--apply"), ...(agent ? { agent } : {}) };
+    }
     throw new Error(`Usage\n${usage()}`);
 }
+const FRIEND_LINK_CODE_USAGE = "Usage: ouro friend link --agent <name> [--channel <teams|bluebubbles|telegram|mail|voice|mcp|cli>] [--friend <friend-id>] [--ttl-minutes <n>]";
+const LINK_CODE_CHANNELS = ["cli", "teams", "bluebubbles", "mail", "voice", "a2a", "mcp", "telegram"];
+function parseFriendLinkCodeCommand(rest, agent) {
+    let friendId;
+    let channel;
+    let ttlMinutes;
+    for (let i = 0; i < rest.length; i += 2) {
+        const token = rest[i];
+        const value = rest[i + 1];
+        if (!value)
+            throw new Error(FRIEND_LINK_CODE_USAGE);
+        if (token === "--friend")
+            friendId = value;
+        else if (token === "--channel" && LINK_CODE_CHANNELS.includes(value))
+            channel = value;
+        else if (token === "--ttl-minutes" && /^[1-9][0-9]*$/.test(value))
+            ttlMinutes = Number(value);
+        else
+            throw new Error(FRIEND_LINK_CODE_USAGE);
+    }
+    return {
+        kind: "friend.linkCode",
+        ...(agent ? { agent } : {}),
+        ...(friendId ? { friendId } : {}),
+        ...(channel ? { channel } : {}),
+        ...(ttlMinutes ? { ttlMinutes } : {}),
+    };
+}
 function parseA2ACommand(args) {
     const { agent, rest: cleaned } = extractAgentFlag(args);
     const [sub, ...rest] = cleaned;

package/dist/heart/identity.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HARNESS_CANONICAL_REPO_URL = exports.DEFAULT_AGENT_SENSES = exports.LEGACY_VAULT_SERVER_URL_ALIASES = exports.DEFAULT_VAULT_SERVER_URL = exports.DEFAULT_AGENT_PHRASES = exports.DEFAULT_AGENT_CONTEXT = exports.PROVIDER_CREDENTIALS = exports.normalizeHabitPaidTurnsPerDay = void 0;
+exports.HARNESS_CANONICAL_REPO_URL = exports.DEFAULT_AGENT_SENSES = exports.LEGACY_VAULT_SERVER_URL_ALIASES = exports.DEFAULT_VAULT_SERVER_URL = exports.DEFAULT_AGENT_PHRASES = exports.DEFAULT_AGENT_CONTEXT = exports.SHEPHERD_NOTICE_POLICIES = exports.PROVIDER_CREDENTIALS = exports.normalizeHabitPaidTurnsPerDay = void 0;
 exports.normalizeVaultServerUrl = normalizeVaultServerUrl;
 exports.getVaultServerUrlCandidates = getVaultServerUrlCandidates;
 exports.defaultStableVaultEmail = defaultStableVaultEmail;
@@ -75,6 +75,7 @@ exports.PROVIDER_CREDENTIALS = {
     "openai-compatible": { required: ["apiKey", "baseUrl"], envVars: {}, promptLabels: { apiKey: "Z.ai API key", baseUrl: "Z.ai canonical base URL" } },
     "openai-compatible-gemini": { required: ["apiKey", "baseUrl"], envVars: {}, promptLabels: { apiKey: "Gemini API key", baseUrl: "Gemini canonical base URL" } },
 };
+exports.SHEPHERD_NOTICE_POLICIES = ["every", "needs-me", "off"];
 exports.DEFAULT_AGENT_CONTEXT = {
     maxTokens: 80000,
     contextMargin: 20,
@@ -215,6 +216,21 @@ function normalizeSenses(value, configFile) {
             defaults[senseName] = { enabled, hostUsername: hostUsername.trim() };
             continue;
         }
+        const notify = rawSense.notify;
+        if (senseName === "shepherd" && notify !== undefined) {
+            if (!exports.SHEPHERD_NOTICE_POLICIES.includes(notify)) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "error",
+                    event: "config_identity.error",
+                    component: "config/identity",
+                    message: "agent config has invalid Shepherd notice policy",
+                    meta: { path: configFile, sense: senseName },
+                });
+                throw new Error(`agent.json at ${configFile}: senses.shepherd.notify must be one of ${exports.SHEPHERD_NOTICE_POLICIES.join(", ")}.`);
+            }
+            defaults[senseName] = { enabled, notify: notify };
+            continue;
+        }
         defaults[senseName] = { enabled };
     }
     return defaults;

package/dist/mind/friend-link-codes.js

@@ -0,0 +1,209 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LINK_CODE_TTL_MS = void 0;
+exports.parseLinkCode = parseLinkCode;
+exports.formatLinkCode = formatLinkCode;
+exports.issueLinkCode = issueLinkCode;
+exports.redeemLinkCode = redeemLinkCode;
+// Identity link codes: how a person proves that a new channel identity is theirs.
+//
+// A friend on a surface the agent already trusts (the owner's CLI, or a family chat)
+// asks for a short code. When that exact code arrives as a 1:1 message from an
+// identity the agent does not yet trust, that identity's record merges into the
+// friend who asked, and the new identity is treated as them from then on.
+//
+// Codes are single use and expire. Only a SHA-256 digest of each code is stored, under
+// the agent's `state/` directory, which bundle sync does not carry. A code is consumed
+// by its first presentation, whatever the outcome, by an atomic rename, so a replay or a
+// race between two senders finds nothing to redeem.
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../nerves/runtime");
+const friend_merge_1 = require("./friend-merge");
+const CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+const CODE_BODY_LENGTH = 8;
+exports.DEFAULT_LINK_CODE_TTL_MS = 10 * 60 * 1000;
+const MAX_LINK_CODE_TTL_MS = 24 * 60 * 60 * 1000;
+const CODE_SHAPE = new RegExp(`^OURO-?([${CODE_ALPHABET}]{4})-?([${CODE_ALPHABET}]{4})$`);
+function codesRoot(agentRoot) {
+    return path.join(agentRoot, "state", "friend-link-codes");
+}
+function digest(codeBody) {
+    return (0, node_crypto_1.createHash)("sha256").update(codeBody).digest("hex");
+}
+/**
+ * The code body when `text` is exactly one link code (case, spacing, dashes and simple
+ * markup ignored), otherwise null. Anything else in the message means it is not a code.
+ */
+function parseLinkCode(text) {
+    const plain = text
+        .replace(/<at>[^<]*<\/at>/gi, " ")
+        .replace(/<[^>]*>/g, " ")
+        .replace(/&nbsp;/g, " ")
+        .replace(/\s+/g, "")
+        .toUpperCase();
+    const match = CODE_SHAPE.exec(plain);
+    return match ? `${match[1]}${match[2]}` : null;
+}
+function formatLinkCode(codeBody) {
+    return `OURO-${codeBody.slice(0, 4)}-${codeBody.slice(4)}`;
+}
+function issueLinkCode(input) {
+    const now = (input.now ?? (() => new Date()))();
+    const ttlMs = Math.min(Math.max(input.ttlMs ?? exports.DEFAULT_LINK_CODE_TTL_MS, 60 * 1000), MAX_LINK_CODE_TTL_MS);
+    let codeBody = "";
+    for (let index = 0; index < CODE_BODY_LENGTH; index += 1)
+        codeBody += CODE_ALPHABET[(0, node_crypto_1.randomInt)(CODE_ALPHABET.length)];
+    const record = {
+        schemaVersion: 1,
+        friendId: input.friend.id,
+        friendName: input.friend.name,
+        ...(input.channel ? { channel: input.channel } : {}),
+        issuedAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+        issuedBy: input.issuedBy,
+    };
+    const pendingDir = path.join(codesRoot(input.agentRoot), "pending");
+    fs.mkdirSync(pendingDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(path.join(pendingDir, `${digest(codeBody)}.json`), `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    (0, runtime_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.link_code_issued",
+        message: "issued an identity link code",
+        meta: { friendId: input.friend.id, channel: input.channel ?? "any", expiresAt: record.expiresAt, issuedBy: input.issuedBy },
+    });
+    return { code: formatLinkCode(codeBody), friendId: record.friendId, friendName: record.friendName, ...(record.channel ? { channel: record.channel } : {}), expiresAt: record.expiresAt };
+}
+const REJECTION_REPLIES = {
+    unknown_or_used: "That link code isn't valid. Ask for a new one.",
+    expired: "That link code has expired. Ask for a new one.",
+    group_chat: "Link codes only work in a 1:1 chat with me. Ask for a new code and send it to me directly.",
+    wrong_channel: "That link code was issued for a different channel. Ask for a new one.",
+    already_linked: "This account is already linked to you.",
+    claimant_trusted: "This account is already known to me as someone I trust, so a code can't relink it. The owner can merge the records instead.",
+    friend_missing: "The person this code was issued for no longer exists. Ask for a new code.",
+};
+function reject(reason, meta) {
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "friends",
+        event: "friends.link_code_rejected",
+        message: "rejected an identity link code",
+        meta: { reason, ...meta },
+    });
+    return { status: "rejected", reason, reply: REJECTION_REPLIES[reason] };
+}
+/** Atomically take the code out of `pending/`. Null when no pending code has this body. */
+function consumeCode(agentRoot, codeBody, nowIso) {
+    const root = codesRoot(agentRoot);
+    const name = `${digest(codeBody)}.json`;
+    const usedDir = path.join(root, "used");
+    fs.mkdirSync(usedDir, { recursive: true, mode: 0o700 });
+    const usedPath = path.join(usedDir, name);
+    try {
+        fs.renameSync(path.join(root, "pending", name), usedPath);
+    }
+    catch (error) {
+        /* v8 ignore next -- only ENOENT is expected; other filesystem failures propagate @preserve */
+        if (error.code !== "ENOENT")
+            throw error;
+        return null;
+    }
+    const record = JSON.parse(fs.readFileSync(usedPath, "utf-8"));
+    fs.writeFileSync(usedPath, `${JSON.stringify({ ...record, consumedAt: nowIso }, null, 2)}\n`, { mode: 0o600 });
+    return { record, usedPath };
+}
+function recordOutcome(usedPath, outcome) {
+    const current = JSON.parse(fs.readFileSync(usedPath, "utf-8"));
+    fs.writeFileSync(usedPath, `${JSON.stringify({ ...current, ...outcome }, null, 2)}\n`, { mode: 0o600 });
+}
+/**
+ * Redeem a link code sent by `claimant`. Returns null when `text` is not a link code, so
+ * callers can run this on every inbound message and fall through to a normal turn.
+ */
+async function redeemLinkCode(input) {
+    const codeBody = parseLinkCode(input.text);
+    if (!codeBody)
+        return null;
+    const now = (input.now ?? (() => new Date()))();
+    const nowIso = now.toISOString();
+    const baseMeta = { claimantId: input.claimant.id, channel: input.channel };
+    const consumed = consumeCode(input.agentRoot, codeBody, nowIso);
+    if (!consumed)
+        return reject("unknown_or_used", baseMeta);
+    const { record, usedPath } = consumed;
+    const meta = { ...baseMeta, friendId: record.friendId };
+    const refuse = (reason) => {
+        recordOutcome(usedPath, { outcome: "rejected", reason, claimantId: input.claimant.id, channel: input.channel });
+        return reject(reason, meta);
+    };
+    if (Date.parse(record.expiresAt) <= now.getTime())
+        return refuse("expired");
+    if (input.isGroupChat)
+        return refuse("group_chat");
+    if (record.channel && record.channel !== input.channel)
+        return refuse("wrong_channel");
+    if (input.claimant.id === record.friendId)
+        return refuse("already_linked");
+    // A code can only bring in an identity the agent does not already trust; trusted
+    // records are merged deliberately by the owner, not by whoever holds a code.
+    if (input.claimant.trustLevel !== "stranger" && input.claimant.trustLevel !== "acquaintance")
+        return refuse("claimant_trusted");
+    const merged = await (0, friend_merge_1.mergeFriends)({
+        store: input.store,
+        friendsDir: input.friendsDir,
+        targetId: record.friendId,
+        sourceIds: [input.claimant.id],
+        actor: `link-code:${record.issuedBy}`,
+        reason: `identity link code redeemed on ${input.channel}`,
+        now: () => now,
+    });
+    if (!merged.ok)
+        return refuse("friend_missing");
+    recordOutcome(usedPath, { outcome: "linked", claimantId: input.claimant.id, channel: input.channel, linkedExternalIds: merged.addedExternalIds.map((externalId) => externalId.provider) });
+    (0, runtime_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.link_code_redeemed",
+        message: "linked a new identity through a link code",
+        meta: { ...meta, trustLevel: merged.target.trustLevel, linkedExternalIds: merged.addedExternalIds.map((externalId) => externalId.provider) },
+    });
+    return {
+        status: "linked",
+        friend: merged.target,
+        reply: `Linked. I'll recognize this ${input.channel} account as ${merged.target.name} from now on.`,
+    };
+}