@ouro.bot/friends 0.1.0-alpha.5 → 0.1.0-alpha.7

package/dist/connect-authority.d.ts

@@ -0,0 +1,43 @@
+import type { SenseType } from "./types";
+import type { AccountMembershipResult } from "./account-roster";
+/** Input to the management-sense authority predicate. `senseType` is the sense the
+ * `connect_to` arrived through (the MCP boundary supplies `local` for the owner-only
+ * stdio path; a network transport passes its real senseType). `membership` is the
+ * PRE-COMPUTED account-roster decision for the `closed` branch — the caller runs
+ * evaluateAccountMembership and passes its result; absent ⇒ no membership proven. */
+export interface AuthorizeConnectInput {
+    senseType: SenseType;
+    membership?: AccountMembershipResult;
+}
+/** The authority decision (PINNED discriminated union). `commit` ⇒ the `connect_to`
+ * may link inline + audit. `downgrade` ⇒ it must NOT commit; the caller raises a
+ * confirm-prompt instead. The `reason` names exactly why the inline commit was
+ * withheld, so the prompt copy + the audit/no-audit branch are unambiguous. */
+export type ConnectAuthorization = {
+    decision: "commit";
+} | {
+    decision: "downgrade";
+    reason: "open_sense_needs_confirmation" | "closed_sense_not_member" | "internal_sense_not_management";
+};
+/** Decide whether a `connect_to` may COMMIT inline from the given management sense.
+ *
+ * `local` is the owner-only management sense (stdio/CLI — the user who launched the
+ * process). `closed` is org-gated but NOT inherently the owner, so it commits ONLY
+ * when the peer is proven same-account family via the signed roster (the caller's
+ * pre-computed `membership`); any other decision — or no membership at all — downgrades
+ * (NEVER a blanket allow on `closed`). An `open` sense (anyone can reach it) never
+ * commits inline regardless of membership. `internal` is the agent's inner dialog —
+ * not a management surface at all. Every non-commit is a structured downgrade RETURN.
+ *
+ * ┌─ PRE-CONDITION before any non-local / networked `controlContext` is ever wired ──────┐
+ * │ (security review inc-2 findings 2-3): this gate authenticates the CALLER's           │
+ * │ sense/membership but places NO constraint on the TARGET, and connectAgents defaults  │
+ * │ the introduce trust to `family`. Both are correct + safe ONLY because the path is     │
+ * │ owner-only stdio today (every wire supplies `senseType: "local"`; no wire constructs  │
+ * │ a non-`local` controlContext). The `connect` commit MUST add target-side roster      │
+ * │ verification (the target did must ALSO be roster-checked, not just TOFU-upserted)     │
+ * │ AND validate the caller-supplied `trustLevel` against the authority decision BEFORE   │
+ * │ any non-`local`/networked controlContext is wired. The current `family` default +     │
+ * │ unconstrained target are safe only for the owner-only-stdio path.                     │
+ * └──────────────────────────────────────────────────────────────────────────────────────┘ */
+export declare function authorizeConnect(input: AuthorizeConnectInput): ConnectAuthorization;

package/dist/connect-authority.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authorizeConnect = authorizeConnect;
+// authorizeConnect — the management-sense authority predicate (brick 8, greenfield).
+//
+// The control-plane gate for `connect_to`: a PURE function that decides whether the
+// owner introducing one of their own agents into the calling agent's fleet may
+// COMMIT inline, or must DOWNGRADE to a confirm-prompt. Brick 8 is genuinely
+// greenfield in friends — there is NO trust-gate.ts / handleStranger to patch (those
+// live in ouroboros); this predicate is the management-sense authority from scratch.
+//
+// CORE-CLEAN by construction: the `closed`-branch membership decision arrives
+// PRE-COMPUTED via the injected seam. The CALLER runs evaluateAccountMembership
+// against the increment-1 roster surface and passes the `AccountMembershipResult` in;
+// this module never calls it, so it imports NO a2a-client / libsodium (the lint
+// enforces the direction). It is a pure value→value map with one observability emit.
+//
+// The contract (every branch — see connect-authority.test.ts):
+//   - local                                  → commit  (owner-only stdio/CLI — the management sense)
+//   - closed + membership family_same_account → commit  (org-gated AND a roster-verified same-account peer)
+//   - closed + any other / absent membership  → downgrade closed_sense_not_member  (NEVER a blanket allow)
+//   - open (a2a/mail/bluebubbles)             → downgrade open_sense_needs_confirmation  (regardless of membership)
+//   - internal                               → downgrade internal_sense_not_management
+// A downgrade is ALWAYS a structured RETURN value, never a throw — the caller turns it
+// into a confirm-prompt and writes no audit / makes no link.
+const observability_1 = require("./observability");
+/** Decide whether a `connect_to` may COMMIT inline from the given management sense.
+ *
+ * `local` is the owner-only management sense (stdio/CLI — the user who launched the
+ * process). `closed` is org-gated but NOT inherently the owner, so it commits ONLY
+ * when the peer is proven same-account family via the signed roster (the caller's
+ * pre-computed `membership`); any other decision — or no membership at all — downgrades
+ * (NEVER a blanket allow on `closed`). An `open` sense (anyone can reach it) never
+ * commits inline regardless of membership. `internal` is the agent's inner dialog —
+ * not a management surface at all. Every non-commit is a structured downgrade RETURN.
+ *
+ * ┌─ PRE-CONDITION before any non-local / networked `controlContext` is ever wired ──────┐
+ * │ (security review inc-2 findings 2-3): this gate authenticates the CALLER's           │
+ * │ sense/membership but places NO constraint on the TARGET, and connectAgents defaults  │
+ * │ the introduce trust to `family`. Both are correct + safe ONLY because the path is     │
+ * │ owner-only stdio today (every wire supplies `senseType: "local"`; no wire constructs  │
+ * │ a non-`local` controlContext). The `connect` commit MUST add target-side roster      │
+ * │ verification (the target did must ALSO be roster-checked, not just TOFU-upserted)     │
+ * │ AND validate the caller-supplied `trustLevel` against the authority decision BEFORE   │
+ * │ any non-`local`/networked controlContext is wired. The current `family` default +     │
+ * │ unconstrained target are safe only for the owner-only-stdio path.                     │
+ * └──────────────────────────────────────────────────────────────────────────────────────┘ */
+function authorizeConnect(input) {
+    const result = decide(input);
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.connect_authorized",
+        message: "evaluated connect_to management-sense authority",
+        meta: {
+            senseType: input.senseType,
+            decision: result.decision,
+            ...(result.decision === "downgrade" ? { reason: result.reason } : {}),
+        },
+    });
+    return result;
+}
+/** The pure decision, factored out so the single observability emit wraps every
+ * branch (the one return path keeps the emit DRY and fully covered). */
+function decide(input) {
+    switch (input.senseType) {
+        case "local":
+            // Owner-only management sense — the user who launched the process. Commit.
+            return { decision: "commit" };
+        case "closed":
+            // Org-gated but not inherently the owner: commit ONLY for a roster-verified
+            // same-account peer. Anything else (incl. absent membership) downgrades — there
+            // is NO blanket allow on `closed`.
+            return input.membership?.decision === "family_same_account"
+                ? { decision: "commit" }
+                : { decision: "downgrade", reason: "closed_sense_not_member" };
+        case "open":
+            // Anyone can reach an open sense — it can NEVER commit a control-plane link
+            // inline, regardless of any membership claim.
+            return { decision: "downgrade", reason: "open_sense_needs_confirmation" };
+        case "internal":
+            // The agent's inner dialog — not a management surface.
+            return { decision: "downgrade", reason: "internal_sense_not_management" };
+    }
+}

package/dist/connect.d.ts

@@ -0,0 +1,55 @@
+import type { FriendStore } from "./store";
+import type { AuditSink } from "./audit";
+import type { ConnectAuthorization } from "./connect-authority";
+import type { AccountMembershipResult } from "./account-roster";
+import type { FriendRecord, SenseType, TrustLevel } from "./types";
+/** The named peer to link, by any of the three handles the owner might supply. An
+ * `agentId` or `did` is a resolvable handle on its own; a bare `name` resolves ONLY by
+ * hitting an existing record (§3.3 — never fabricated). */
+export interface ConnectPeer {
+    agentId?: string;
+    did?: string;
+    name?: string;
+}
+export interface ConnectAgentsInput {
+    peer: ConnectPeer;
+    /** The management sense the connect_to arrived through (the MCP boundary supplies
+     * `local` for the owner-only stdio path; a network transport its real senseType). */
+    senseType: SenseType;
+    /** The PRE-COMPUTED account-roster membership for the `closed` branch (the caller
+     * runs evaluateAccountMembership). Absent ⇒ no membership proven. */
+    membership?: AccountMembershipResult;
+    /** The trust to link the peer at. Own-fleet linked agents default to `family`. */
+    trustLevel?: TrustLevel;
+}
+export interface ConnectAgentsDeps {
+    /** The control-plane audit sink. Absent ⇒ the link is made but no audit is appended
+     * (no-sink no-op, mirroring setFriendTrust / the onboard_agent seat). */
+    audit?: AuditSink;
+    /** WHO performed the connect (e.g. "owner:stdio"). */
+    actor: string;
+    /** WHENCE — the origin sense string stamped on the audit (e.g. "stdio"). */
+    originSense: string;
+}
+export type ConnectStatus = "connected" | "needs_handle_or_introduction" | "downgraded";
+export type ConnectResult = {
+    ok: true;
+    status: "connected";
+    record: FriendRecord;
+} | {
+    ok: false;
+    status: "needs_handle_or_introduction";
+} | {
+    ok: false;
+    status: "downgraded";
+    downgrade: ConnectAuthorization;
+};
+/**
+ * Link a named peer into the calling agent's store from the owner's vantage. Composes:
+ * authority gate (authorizeConnect) → disambiguation (resolvePeer, never fabricates) →
+ * the introduce effect (upsertAgentPeer at the linked trust, default family) → the
+ * action:"connect" control-plane audit (mirroring the onboard_agent seat). A downgrade
+ * authorization makes NO link and writes NO audit (mirrors setFriendTrust's no-audit
+ * early return); an unresolvable bare name returns needs_handle_or_introduction.
+ */
+export declare function connectAgents(store: FriendStore, input: ConnectAgentsInput, deps: ConnectAgentsDeps): Promise<ConnectResult>;

package/dist/connect.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connectAgents = connectAgents;
+// connectAgents — the `connect_to` library fn (brick 8, greenfield).
+//
+// The owner's first-class capability to link one of their OWN agents into the calling
+// agent's fleet (introduce a target peer INTO this store). It is the single entry point
+// for "go connect to @peer" (spec §3.2), gated to a management sense (§3.1) and audited
+// (§3.4). Brick 8 is greenfield in friends — there is NO trust-gate.ts to patch (that
+// lives in ouroboros); this composes the new authority predicate (connect-authority.ts)
+// with the increment-1 roster-pre-computed membership + the increment-1 control-plane
+// audit (AuditSink / action:"connect").
+//
+// MENTAL MODEL (resolves "A↔B on separate stores"): A and B live in SEPARATE
+// stores/processes (own-fleet on two machines), so a single connectAgents call operates
+// on ONE store — it upserts the named peer as an agent-peer at the linked trust + audits
+// action:"connect". The bidirectional A↔B link is the owner running the introduction on
+// EACH side (the LOCAL proof drives both). The fn does NOT reach across stores.
+//
+// CORE-CLEAN: the `membership` arrives PRE-COMPUTED via `input` (the caller runs
+// evaluateAccountMembership against the increment-1 roster surface), so this module
+// imports NO a2a-client / libsodium. The lint enforces the direction.
+//
+// DISAMBIGUATION HONESTY (spec §3.3): given a bare name with no resolvable handle/DID
+// and no record hit, connectAgents returns a structured "need a handle or an
+// introduction" result rather than FABRICATING a target. An agentId or a did IS an
+// owner-supplied/resolved handle; a bare name resolves ONLY by matching an existing
+// record (the BUILT FileFriendStore name-fallback scan) — never invented.
+const observability_1 = require("./observability");
+const connect_authority_1 = require("./connect-authority");
+const agent_peer_1 = require("./agent-peer");
+const friend_lookup_1 = require("./friend-lookup");
+const identity_1 = require("./identity");
+/** Read an agent record's join-key agentId — the durable `a2a.agentId`, falling back
+ * to the `a2a-agent` externalId. Returns undefined when the record names no agentId
+ * (e.g. a human record), so it can never be linked as an agent target. */
+function agentIdOf(record) {
+    return record.agentMeta?.a2a?.agentId ?? record.externalIds.find((e) => e.provider === "a2a-agent")?.externalId;
+}
+/** Resolve the peer to a usable handle WITHOUT fabricating one (§3.3):
+ *  - `agentId` present → it IS the handle; enrich from any existing record by it.
+ *  - else `did` present → resolve an existing record by did (the did is the handle);
+ *    a did with no matching record does NOT resolve (needs a handle/introduction).
+ *  - else `name` present → match an existing record by case-insensitive name (the
+ *    FileFriendStore name-fallback semantics, made store-agnostic via listAll); a bare
+ *    name with no hit does NOT resolve.
+ *  - else (nothing) → does not resolve.
+ * Returns null when the peer cannot be resolved to a real handle. */
+async function resolvePeer(store, peer) {
+    if (peer.agentId) {
+        const existing = await store.findByExternalId("a2a-agent", peer.agentId);
+        return { agentId: peer.agentId, existing: existing ?? undefined, name: peer.name ?? existing?.name ?? peer.agentId };
+    }
+    if (peer.did) {
+        const existing = await (0, friend_lookup_1.findFriendByDid)(store, peer.did);
+        if (!existing)
+            return null;
+        const agentId = agentIdOf(existing);
+        if (!agentId)
+            return null;
+        return { agentId, existing, name: peer.name ?? existing.name };
+    }
+    if (peer.name) {
+        const existing = await findByName(store, peer.name);
+        if (!existing)
+            return null;
+        const agentId = agentIdOf(existing);
+        if (!agentId)
+            return null;
+        return { agentId, existing, name: peer.name };
+    }
+    return null;
+}
+/** Case-insensitive name match over the store's records (the §3.3 name-fallback scan,
+ * made store-agnostic by using listAll). Returns the first match, or null. A store with
+ * no listAll yields null (best-effort, never a throw). */
+async function findByName(store, name) {
+    if (typeof store.listAll !== "function")
+        return null;
+    const all = await store.listAll();
+    const lower = name.toLowerCase();
+    return all.find((f) => f.name.toLowerCase() === lower) ?? null;
+}
+/**
+ * Link a named peer into the calling agent's store from the owner's vantage. Composes:
+ * authority gate (authorizeConnect) → disambiguation (resolvePeer, never fabricates) →
+ * the introduce effect (upsertAgentPeer at the linked trust, default family) → the
+ * action:"connect" control-plane audit (mirroring the onboard_agent seat). A downgrade
+ * authorization makes NO link and writes NO audit (mirrors setFriendTrust's no-audit
+ * early return); an unresolvable bare name returns needs_handle_or_introduction.
+ */
+async function connectAgents(store, input, deps) {
+    // 1) Authority FIRST. A downgrade never commits inline (no link, no audit).
+    const authorization = (0, connect_authority_1.authorizeConnect)({ senseType: input.senseType, membership: input.membership });
+    if (authorization.decision === "downgrade") {
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.connect_downgraded",
+            message: "connect_to downgraded to confirm-prompt (not committed inline)",
+            meta: { senseType: input.senseType, reason: authorization.reason },
+        });
+        return { ok: false, status: "downgraded", downgrade: authorization };
+    }
+    // 2) Disambiguation honesty — resolve the peer to a real handle, never fabricate.
+    const resolved = await resolvePeer(store, input.peer);
+    if (!resolved) {
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.connect_needs_handle",
+            message: "connect_to could not resolve the peer to a handle — needs a handle or an introduction",
+            meta: {},
+        });
+        return { ok: false, status: "needs_handle_or_introduction" };
+    }
+    // 3) The introduce effect — upsert the peer as an agent-peer at the linked trust.
+    // Own-fleet linked agents default to family; the level is overridable. Pass any
+    // existing a2a coords through so the upsert preserves them (incl. a legacy a2a.did).
+    //
+    // ┌─ PRE-CONDITION before any non-local / networked `controlContext` is ever wired ──────┐
+    // │ (security review inc-2 findings 2-3): the `family` DEFAULT here, and the fact that    │
+    // │ the TARGET is upserted with no roster constraint (TOFU — see resolvePeer above),      │
+    // │ are correct + safe ONLY because the authority gate (authorizeConnect) only COMMITs    │
+    // │ on the owner-only `local` stdio sense today (no wire constructs a non-`local`         │
+    // │ controlContext). BEFORE any non-`local`/networked controlContext is ever wired, the   │
+    // │ `connect` commit MUST add target-side roster verification (the target did must ALSO   │
+    // │ be roster-checked, not just TOFU-upserted) AND validate the caller-supplied           │
+    // │ `trustLevel` against the authority decision. The current `family` default +           │
+    // │ unconstrained target are safe only for the owner-only-stdio path.                     │
+    // └──────────────────────────────────────────────────────────────────────────────────────┘
+    const trustLevel = input.trustLevel ?? "family";
+    const a2a = resolved.existing?.agentMeta?.a2a;
+    const record = await (0, agent_peer_1.upsertAgentPeer)(store, {
+        name: resolved.name,
+        agentId: resolved.agentId,
+        trustLevel,
+        ...(a2a ? { a2a } : {}),
+    });
+    // 4) The control-plane audit — ONE action:"connect" record through the wired sink
+    // (mirrors the onboard_agent seat writer). No sink ⇒ a clean no-op.
+    if (deps.audit) {
+        const targetDid = (0, identity_1.resolveAgentIdentity)(record.agentMeta).did;
+        const auditRecord = {
+            action: "connect",
+            targetId: record.id,
+            ...(targetDid !== undefined ? { targetDid } : {}),
+            level: trustLevel,
+            actor: deps.actor,
+            originSense: deps.originSense,
+            ts: record.updatedAt,
+        };
+        await deps.audit.append(auditRecord);
+    }
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.connect_linked",
+        message: "connect_to linked an own-fleet agent peer",
+        meta: { targetId: record.id, level: trustLevel },
+    });
+    return { ok: true, status: "connected", record };
+}

package/dist/coordination.d.ts

@@ -1,7 +1,7 @@
 import type { MissionStore } from "./mission-store";
 import type { FriendStore } from "./store";
 import type { GrantStore } from "./grant-store";
-import type { AgentAttribution, CoordinationIntent, MissionRecord, TrustLevel } from "./types";
+import type { AgentAttribution, CoordinationIntent, MissionRecord, MissionTaskSpec, TrustLevel } from "./types";
 import type { ConsentPolicy } from "./consent";
 import type { AgentVerifier } from "./verifier";
 /** The cross-agent coordination envelope (brick 5). Names the subject by JOIN KEY
@@ -25,6 +25,12 @@ export interface CoordinationEnvelope {
      * PROPOSES as the new assignee (named by join-key agentId). The receiver's own
      * accept is what actually sets it — a handoff never forces an assignment. */
     proposedAssignee?: AgentAttribution;
+    /** The delegation task-spec, meaningful ONLY on intent:"request" (gap-1, p11 inc2):
+     * the structured "what B is being asked to do", carrying the minted `requestId` the
+     * result-return correlates against. Present only when the producer was given a task on
+     * a request; a plain coordination request omits it (back-compat). Mirrors how
+     * `proposedAssignee` rides only `handoff`. */
+    task?: MissionTaskSpec;
     /** Opaque, verifier-specific proof slot. The TOFU verifier ignores it. */
     proof?: string;
     issuedAt: string;
@@ -43,6 +49,16 @@ export interface PrepareCoordinationInput {
     /** This agent's own join-key agentId — the asserter of the first-party log entry
      * (and, on an `accept`, the assignee it claims for itself). */
     selfAgentId: string;
+    /** Optional delegation task-spec (gap-1, p11 inc2), meaningful ONLY on
+     * intent:"request". When provided on a request, the producer MINTS a `requestId`,
+     * stamps the full `MissionTaskSpec` on the envelope's `task`, and records it first-party
+     * under the mission's `delegations[requestId]`. Ignored on any non-request intent.
+     * Absent ⇒ a plain coordination request, byte-identical to today (back-compat). */
+    task?: {
+        summary: string;
+        details?: string;
+        inputs?: Record<string, string>;
+    };
     /** Optional proof to stamp on the envelope (for a non-TOFU recipient verifier). */
     proof?: string;
 }

package/dist/coordination.js

@@ -49,8 +49,12 @@ function holdsAssignment(record, selfAgentId) {
 /** Apply the OUTGOING intent to the producer's own mission record as a first-party
  * step: always append the intent to `coordination.log`; on an `accept`, also claim
  * the assignment for self (the accepter is taking it). No other intent moves the
- * producer's `assignee`. Mirrors how recordMission stamps first-party provenance. */
-function applyOutgoingIntent(record, input, now) {
+ * producer's `assignee`. When a `taskSpec` is supplied (a request carrying a task,
+ * gap-1), ALSO record it first-party under `delegations[requestId]` — the task-spec, the
+ * delegated-TO `assignee` (`input.toAgentId`), and first-party provenance. The assignee is
+ * the anchor importMissionResult checks the result's source against (security-review inc-2
+ * finding 1). Mirrors how recordMission stamps first-party provenance. */
+function applyOutgoingIntent(record, input, now, taskSpec) {
     const entry = {
         intent: input.intent,
         fromAgentId: input.selfAgentId,
@@ -62,7 +66,38 @@ function applyOutgoingIntent(record, input, now) {
     const coordination = input.intent === "accept"
         ? { ...withLog, assignee: { agentId: input.selfAgentId }, assignedAt: now }
         : withLog;
-    return { ...record, coordination, updatedAt: now };
+    // gap-1: record the issued delegation first-party under delegations[requestId]. PERSIST
+    // the ASSIGNEE — the agent this task is delegated TO (input.toAgentId) — alongside the
+    // task-spec (security-review inc-2 finding 1). This is the anchor importMissionResult
+    // checks the result's SOURCE against: A only accepts a result for this requestId from the
+    // very agent it delegated TO. Without it, a trusted non-assignee who learned the
+    // requestId could inject a forged result.
+    const delegations = taskSpec
+        ? {
+            ...(record.delegations ?? {}),
+            [taskSpec.requestId]: { task: taskSpec, assignee: { agentId: input.toAgentId }, provenance: { origin: "first_party" } },
+        }
+        : record.delegations;
+    return {
+        ...record,
+        coordination,
+        ...(delegations ? { delegations } : {}),
+        updatedAt: now,
+    };
+}
+/** Build the MissionTaskSpec for a request carrying a task (gap-1): mint the
+ * `requestId` and carry the optional details/inputs only when present. Returns undefined
+ * when there is no task to attach, or the intent is not a request (a task on any other
+ * intent is ignored). */
+function buildTaskSpec(input) {
+    if (input.intent !== "request" || input.task === undefined)
+        return undefined;
+    return {
+        requestId: (0, node_crypto_1.randomUUID)(),
+        summary: input.task.summary,
+        ...(input.task.details !== undefined ? { details: input.task.details } : {}),
+        ...(input.task.inputs !== undefined ? { inputs: input.task.inputs } : {}),
+    };
 }
 /**
  * Producer half of the coordination primitive. Consent-gated (subject = the
@@ -101,6 +136,10 @@ async function prepareCoordination(missions, store, grants, input, consent = con
         return { ok: false, status: "not_assignee" };
     }
     const now = new Date().toISOString();
+    // gap-1: a request carrying a task mints a requestId + a MissionTaskSpec (undefined on
+    // any non-request intent, or when no task was given). Minted ONCE so the envelope's
+    // task and the first-party delegations[requestId] share the same correlation key.
+    const taskSpec = buildTaskSpec(input);
     const envelope = {
         subject: { missionKey: record.missionKey, title: record.title },
         fromAgentId: input.selfAgentId,
@@ -110,11 +149,13 @@ async function prepareCoordination(missions, store, grants, input, consent = con
         ...(input.intent === "handoff" && input.proposedAssignee !== undefined
             ? { proposedAssignee: input.proposedAssignee }
             : {}),
+        ...(taskSpec ? { task: taskSpec } : {}),
         ...(input.proof !== undefined ? { proof: input.proof } : {}),
     };
     // Record the outgoing intent on the producer's own mission (first-party), so the
-    // sender's record reflects "I asked / I offered / I accepted".
-    const updated = applyOutgoingIntent(record, input, now);
+    // sender's record reflects "I asked / I offered / I accepted" — and, for a request
+    // with a task, the issued delegation under delegations[requestId].
+    const updated = applyOutgoingIntent(record, input, now, taskSpec);
     await missions.put(updated.id, updated);
     (0, observability_1.emitNervesEvent)({
         component: "friends",
@@ -174,8 +215,41 @@ function applyIncomingIntent(record, envelope, fromAgentId, now) {
             : withLog;
         return { record: { ...record, coordination, updatedAt: now }, assigned: isLater };
     }
+    // gap-1: a request carrying a task lands the task-spec QUARANTINED under
+    // importedDelegations[fromAgentId][requestId] (attributed, imported), NEVER touching
+    // first-party `delegations`/`learnings`/`notes`/`status`. Idempotent per (agentId,
+    // requestId): an existing entry is preserved (never re-stamped).
+    const importedDelegations = envelope.intent === "request" && envelope.task !== undefined
+        ? mergeImportedDelegation(record, envelope.task, fromAgentId, now)
+        : record.importedDelegations;
     // request / offer / decline / handoff → log only; assignee untouched.
-    return { record: { ...record, coordination: withLog, updatedAt: now }, assigned: false };
+    return {
+        record: {
+            ...record,
+            coordination: withLog,
+            ...(importedDelegations ? { importedDelegations } : {}),
+            updatedAt: now,
+        },
+        assigned: false,
+    };
+}
+/** Land one imported task-spec under `importedDelegations[fromAgentId][requestId]`,
+ * returning a NEW namespace (never mutates the input). First-party `delegations` are NOT
+ * passed in and stay physically untouched. Idempotent per (agentId, requestId): an entry
+ * that already exists is preserved unchanged (never re-stamped with a new importedAt). */
+function mergeImportedDelegation(record, task, fromAgentId, now) {
+    const existing = record.importedDelegations ?? {};
+    const forAgent = existing[fromAgentId] ?? {};
+    // Idempotent: keep the existing entry for this requestId (do not re-stamp on replay).
+    if (forAgent[task.requestId])
+        return existing;
+    return {
+        ...existing,
+        [fromAgentId]: {
+            ...forAgent,
+            [task.requestId]: { task, provenance: { origin: "imported", assertedBy: { agentId: fromAgentId }, importedAt: now } },
+        },
+    };
 }
 /** Create a freshly-seeded mission for a previously-unknown key, carrying the
  * subject's join key + title, `status:"active"`, empty first-party `learnings`. The

package/dist/file-bundle.d.ts

@@ -1,12 +1,17 @@
 import { FileFriendStore } from "./store-file";
 import { FileGrantStore } from "./grant-store-file";
 import { FileMissionStore } from "./mission-store-file";
+import { FileAuditSink } from "./audit";
 export interface FileBundle {
     store: FileFriendStore;
     grants: FileGrantStore;
     missions: FileMissionStore;
+    /** Control-plane audit sink (Bug B, finding 3) over the sibling `_audit/control.jsonl`,
+     * so the live MCP `set_trust` / `onboard_agent` trust seat write audit records. */
+    audit: FileAuditSink;
     friendsDir: string;
     grantsDir: string;
     missionsDir: string;
+    auditPath: string;
 }
 export declare function openFileBundle(friendsDir: string): FileBundle;

package/dist/file-bundle.js

@@ -7,17 +7,21 @@ exports.openFileBundle = openFileBundle;
 const store_file_1 = require("./store-file");
 const grant_store_file_1 = require("./grant-store-file");
 const mission_store_file_1 = require("./mission-store-file");
+const audit_1 = require("./audit");
 const observability_1 = require("./observability");
 function openFileBundle(friendsDir) {
     const grantsDir = (0, grant_store_file_1.grantsDirFor)(friendsDir);
     const missionsDir = (0, mission_store_file_1.missionsDirFor)(friendsDir);
+    const auditPath = (0, audit_1.auditPathFor)(friendsDir);
     (0, observability_1.emitNervesEvent)({ component: "friends", event: "friends.file_bundle_opened", message: "opened file bundle", meta: {} });
     return {
         store: new store_file_1.FileFriendStore(friendsDir),
         grants: new grant_store_file_1.FileGrantStore(grantsDir),
         missions: new mission_store_file_1.FileMissionStore(missionsDir),
+        audit: new audit_1.FileAuditSink(auditPath),
         friendsDir,
         grantsDir,
         missionsDir,
+        auditPath,
     };
 }

package/dist/friend-lookup.d.ts

@@ -0,0 +1,9 @@
+import type { FriendStore } from "./store";
+import type { FriendRecord } from "./types";
+/** Find the friend record whose durable identity DID equals `did`. A DUPLICATE did is
+ * an anomaly: it emits a loud `friends.duplicate_did` warning and resolves
+ * deterministically WITHOUT rewarding back-dating — a pinned/verified record wins, else
+ * the lowest record `id` (a stable, non-temporal tie-break) — see {@link preferOverBest}.
+ * Returns null when no record matches, the query did is falsy, or the store has no
+ * `listAll`. */
+export declare function findFriendByDid(store: FriendStore, did: string): Promise<FriendRecord | null>;

package/dist/friend-lookup.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findFriendByDid = findFriendByDid;
+// did-aware friend lookup (p11 Item 2 — the DID re-key).
+//
+// `did` is the durable cross-agent primary key. This pure helper finds a friend
+// record by did WITHOUT changing the FriendStore interface contract: it scans
+// `store.listAll?.()` and matches on the record's resolved identity
+// (`resolveAgentIdentity(f.agentMeta).did`, which already prefers identity.did and
+// migrates a2a.did on read). Additive — `findByExternalId` is untouched. A store
+// with no `listAll` yields null (the lookup is best-effort, never a throw).
+const observability_1 = require("./observability");
+const identity_1 = require("./identity");
+/** Whether `candidate` should replace the current best among duplicate-did records.
+ *
+ * SECURITY (finding 5, MEDIUM): the tie-break must NOT reward back-dating — the old
+ * "lowest createdAt wins" rule let an attacker mint a duplicate-did record with an
+ * earlier createdAt to silently shadow a legit one. Instead:
+ *  1) Prefer a trust-relevant signal — a record carrying a TOFU-pinned key
+ *     (`pinnedKey`) is the verified one and beats an unpinned duplicate.
+ *  2) When pinned-status is equal, break the tie by the record `id` (a stable,
+ *     non-temporal key) — back-dating `createdAt` no longer gains anything. */
+function preferOverBest(candidate, best) {
+    const candidatePinned = (0, identity_1.resolveAgentIdentity)(candidate.agentMeta).pinnedKey !== undefined;
+    const bestPinned = (0, identity_1.resolveAgentIdentity)(best.agentMeta).pinnedKey !== undefined;
+    if (candidatePinned !== bestPinned)
+        return candidatePinned; // pinned beats unpinned
+    return candidate.id < best.id; // stable, non-temporal tie-break
+}
+/** Find the friend record whose durable identity DID equals `did`. A DUPLICATE did is
+ * an anomaly: it emits a loud `friends.duplicate_did` warning and resolves
+ * deterministically WITHOUT rewarding back-dating — a pinned/verified record wins, else
+ * the lowest record `id` (a stable, non-temporal tie-break) — see {@link preferOverBest}.
+ * Returns null when no record matches, the query did is falsy, or the store has no
+ * `listAll`. */
+async function findFriendByDid(store, did) {
+    // SECURITY (finding 4, MEDIUM): a falsy did query must never match. Without this,
+    // findFriendByDid(store, undefined|"") matched the first did-less record (a did-less
+    // record resolves to `undefined`, and `undefined !== undefined` is false → match).
+    if (!did)
+        return null;
+    if (typeof store.listAll !== "function")
+        return null;
+    const all = await store.listAll();
+    let best = null;
+    let matchCount = 0;
+    for (const f of all) {
+        const resolvedDid = (0, identity_1.resolveAgentIdentity)(f.agentMeta).did;
+        // Skip records whose resolved did is falsy (absent/empty) so they can never match —
+        // belt-and-braces with resolveAgentIdentity's own empty-string guard (finding 6).
+        if (!resolvedDid || resolvedDid !== did)
+            continue;
+        matchCount += 1;
+        if (best === null || preferOverBest(f, best))
+            best = f;
+    }
+    // SECURITY (finding 5): a duplicate did is itself an anomaly — surface it loudly so a
+    // shadowing attempt is visible, rather than silently resolving it away.
+    if (matchCount > 1) {
+        (0, observability_1.emitNervesEvent)({
+            level: "warn",
+            component: "friends",
+            event: "friends.duplicate_did",
+            message: `duplicate did detected across ${matchCount} friend records — resolving to the pinned/lowest-id record (NOT lowest-createdAt); investigate possible record shadowing`,
+            meta: { did, matchCount },
+        });
+    }
+    return best;
+}

package/dist/identity.d.ts

@@ -0,0 +1,17 @@
+import type { AgentMeta } from "./types";
+/** The resolved durable identity of an agent peer — independent of which on-disk
+ * shape carried it. All fields optional: a did-less legacy record reads clean. */
+export interface ResolvedAgentIdentity {
+    did?: string;
+    pinnedKey?: string;
+    handle?: string;
+    pinnedAt?: string;
+}
+/** Read an agent's durable identity, preferring `meta.identity` and lifting the
+ * legacy `meta.a2a.did` on a miss (migrate-on-read). Returns `{}` for a did-less
+ * or absent meta. (Unit 4a stub — not implemented.) */
+export declare function resolveAgentIdentity(meta: AgentMeta | undefined): ResolvedAgentIdentity;
+/** Return a meta whose `identity.did` is backfilled from `a2a.did` when the durable
+ * home is absent (migrate-on-write); a meta already carrying `identity` is returned
+ * unchanged (no clobber). Absent meta is returned as-is. (Unit 4a stub.) */
+export declare function withMigratedIdentity(meta: AgentMeta | undefined): AgentMeta | undefined;