@openrig/cli 0.5.4 → 0.5.6

package/daemon/dist/domain/gateway/gateway-subsystem.js

@@ -0,0 +1,151 @@
+// S10 (OPR.0.5.5.10) — the gateway as an IN-DAEMON SUBSYSTEM. M1 §3 as amended 2026-08-26
+// (desk head-amendment under founder R2): the gateway runs in-process at daemon boot — the
+// shipped components (GatewayDispatcher + DispatchBuffer) reused verbatim, NO child process,
+// NO gateway↔connector socket wire. spawn-gateway.ts / gateway-process*.ts / transport.ts are
+// the retired process-split shape and must not gain callers (second-deployable ABSENCE is a
+// proof-contract red).
+//
+// Durability is the shipped contract, unchanged by the re-homing: a decision is persisted to
+// the durable buffer BEFORE delivery is attempted (dispatcher enqueues first), drained ONLY
+// after the delivery layer reports success (the in-process ack), and un-Acked decisions replay
+// on every subsystem (re)start — a delivery failure is retained, never dropped.
+//
+// Failure honesty (mini-req 1): a wiring failure at start() surfaces as state=failed with the
+// cause named, visible on the health surface — it never throws into daemon boot (a broken
+// gateway must not take the daemon down) and never reads as silently active.
+import { DispatchBuffer } from "./dispatch-buffer.js";
+import { GatewayDispatcher } from "./dispatcher.js";
+/** Compose the SHIPPED dispatcher + durable buffer in-process. The capability handshake
+ *  becomes a local declaration by the delivery layer (same closed contract, no socket);
+ *  ack-after-delivery becomes deliver() resolving ok. replayPending() at build time is the
+ *  restart no-loss leg: un-Acked decisions from a prior run re-enter delivery. */
+export function buildInProcessWire(opts) {
+    const log = opts.log ?? (() => { });
+    const buffer = new DispatchBuffer(opts.home);
+    const deliverAndAck = async (decision) => {
+        let outcome;
+        try {
+            outcome = await opts.deliver(decision);
+        }
+        catch (e) {
+            outcome = { ok: false, class: "delivery-threw", detail: e.message };
+        }
+        if (outcome.ok) {
+            dispatcher.onAck(decision.decisionId); // drain only after delivered
+        }
+        else {
+            log(`delivery failed ${decision.decisionId} (${outcome.class}${outcome.detail ? ": " + outcome.detail : ""}) — retained for replay`);
+        }
+    };
+    const dispatcher = new GatewayDispatcher({
+        buffer,
+        send: (decision) => { void deliverAndAck(decision); },
+    });
+    dispatcher.onCapability({
+        kind: "capability",
+        connectorId: opts.connectorId ?? "slack-subsystem",
+        platform: opts.platform ?? "slack",
+        protocolVersion: 1,
+        ops: opts.ops ?? [],
+    });
+    return {
+        dispatcher,
+        stop: () => { },
+        // Restart no-loss: un-Acked decisions re-enter delivery — a NETWORK action, so it rides
+        // startServices() (post-bind), never wire composition.
+        startServices: () => dispatcher.replayPending(),
+    };
+}
+export class GatewaySubsystem {
+    deps;
+    state = "inactive";
+    reason;
+    activatedAt;
+    wireHandle;
+    servicesStarted = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Activate in-process. NEVER throws: a wiring failure records state=failed with the cause
+     *  and returns — daemon boot proceeds and the health surface tells the truth. */
+    start() {
+        if (this.state === "active")
+            return;
+        try {
+            this.wireHandle = this.deps.wire();
+            this.state = "active";
+            this.reason = undefined;
+            this.activatedAt = (this.deps.now?.() ?? new Date()).toISOString();
+            this.deps.log?.("gateway subsystem active (in-process)");
+        }
+        catch (e) {
+            this.state = "failed";
+            this.reason = e.message;
+            this.wireHandle = undefined;
+            this.deps.log?.(`gateway subsystem FAILED to activate: ${this.reason}`);
+        }
+    }
+    /** Start the wire's network services (replay, pollers, sockets). Post-bind only — the
+     *  index.ts supervision tree calls this beside contextMonitor.start(); test-built daemons
+     *  never do, so composing a daemon never dials out. Idempotence is the wire's concern. */
+    startServices() {
+        if (this.state !== "active")
+            return;
+        try {
+            this.wireHandle?.startServices?.();
+            this.servicesStarted = true;
+        }
+        catch (e) {
+            // Service startup failure is honest but NOT fatal to the composed wire: dispatches
+            // still persist durably; the health surface names the degradation.
+            this.reason = `services failed to start: ${e.message}`;
+            this.deps.log?.(`gateway subsystem services FAILED to start: ${e.message}`);
+        }
+    }
+    /** Dispatch through the live wire (refused honestly when not active).
+     *  opts.decisionId: a caller-supplied durable episode-stable identity
+     *  (OPR.0.5.6.1 — redrive idempotence for deferral fires and digest posts). */
+    dispatch(op, entityBindingRef, payload, opts) {
+        if (this.state !== "active" || !this.wireHandle) {
+            return { ok: false, error: `dispatch refused: gateway subsystem is ${this.state}${this.reason ? ` (${this.reason})` : ""}` };
+        }
+        return this.wireHandle.dispatcher.dispatch(op, entityBindingRef, payload, opts);
+    }
+    status() {
+        const s = { state: this.state };
+        if (this.reason !== undefined)
+            s.reason = this.reason;
+        if (this.activatedAt !== undefined)
+            s.activatedAt = this.activatedAt;
+        if (this.state === "active" || this.state === "failed") {
+            try {
+                s.pendingDispatches = new DispatchBuffer(this.deps.home).pending().length;
+            }
+            catch { /* buffer unreadable — omit rather than lie */ }
+        }
+        return s;
+    }
+    /** Recovery half of recovers-or-reports: tear down and re-run the wiring. If services were
+     *  live (post-bind), the rebuilt wire's services start too — a config flip (enable/disable)
+     *  lands without a daemon restart. */
+    restart() {
+        const resumeServices = this.servicesStarted;
+        this.stop();
+        this.state = "inactive";
+        this.start();
+        if (resumeServices)
+            this.startServices();
+    }
+    stop() {
+        try {
+            this.wireHandle?.stop();
+        }
+        catch { /* best-effort */ }
+        this.wireHandle = undefined;
+        this.servicesStarted = false;
+        if (this.state !== "failed")
+            this.state = "stopped";
+        this.deps.log?.("gateway subsystem stopped");
+    }
+}
+//# sourceMappingURL=gateway-subsystem.js.map

package/daemon/dist/domain/gateway/gateway-subsystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-subsystem.js","sourceRoot":"","sources":["../../../src/domain/gateway/gateway-subsystem.ts"],"names":[],"mappings":"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"}

package/daemon/dist/domain/gateway/human-registry.d.ts

@@ -5,6 +5,7 @@ export declare const HUMAN_DELIVERY_CLASSES: Set<string>;
 export declare const ENTITY_ID_PATTERN: RegExp;
 export declare const ADDRESS_DOMAIN = "external";
 export declare const HANDLE_PATTERN: RegExp;
+export declare const HUMAN_AVAILABILITY_MODES: Set<string>;
 export interface HumanConnectorBinding {
     kind: "slack";
     connectorRef: string;
@@ -23,8 +24,12 @@ export interface HumanPrefs {
     /** Per-ENTITY loudness — a SELECTION from the notifications register (spec §6);
      *  A3 carries it, never redefines it. Forward-compatible if the register grows. */
     deliveryClass: "A" | "B" | "C" | "D";
-    /** The AWAY preset (optional). */
+    /** The AWAY preset (optional; LEGACY spelling — availability=away supersedes).
+     *  Read via the engine's resolveAvailability: consulted only when
+     *  `availability` is whole-field-absent. */
     away?: boolean;
+    /** OPR.0.5.6.1 — availability mode (available | focus | away | off). */
+    availability?: "available" | "focus" | "away" | "off";
 }
 export interface HumanFragment {
     entityId: string;
@@ -110,6 +115,115 @@ export type AddHumanResult = {
 export declare function addHumanFragment(raw: unknown, home?: string, opts?: {
     replace?: boolean;
 }): AddHumanResult;
+/** One in-flight item standing between a human and a clean remove. The registry does not
+ *  own the sources (queue rows live behind the daemon; conversations in the dispatch
+ *  buffer) — callers assemble the list; `pendingConversationsFor` covers the buffer half. */
+export interface InflightItem {
+    kind: "open-conversation" | "queue-row";
+    id: string;
+    detail: string;
+}
+export interface HumanBindingsSummary {
+    count: number;
+    primary: {
+        kind: string;
+        connectorRef: string;
+    };
+    /** true iff any binding carries a handle (outbound-only otherwise). */
+    inboundResolvable: boolean;
+}
+export interface HumanSummary {
+    entityId: string;
+    displayName: string;
+    address: string;
+    deliveryClass: HumanPrefs["deliveryClass"];
+    /** EFFECTIVE availability preset (default false when unauthored). */
+    away: boolean;
+    bindings: HumanBindingsSummary;
+    fragmentPath: string;
+}
+export type ListHumansResult = {
+    ok: true;
+    humans: HumanSummary[];
+    advisory?: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** Amendment A1 (founder R5): the 0.5.5 surface is SINGLE-HUMAN. Several fragments render
+ *  honestly, but enumeration is display, never management — the advisory names the boundary. */
+export declare const MULTI_HUMAN_ADVISORY = "several human fragments exist; this release's surface is single-human \u2014 multi-human management is 0.5.7 scope (fragments are displayed honestly; no plural management verbs exist)";
+/** A field value with its provenance: authored in the fragment, or filled by a default. */
+export interface ProvenancedValue<T> {
+    value: T;
+    source: "authored" | "default";
+}
+export interface EffectiveHumanRecord {
+    entityId: string;
+    address: string;
+    displayName: string;
+    fragmentPath: string;
+    prefs: {
+        deliveryClass: ProvenancedValue<HumanPrefs["deliveryClass"]>;
+        away: ProvenancedValue<boolean>;
+    };
+    connectorBindings: Array<HumanConnectorBinding & {
+        inboundResolvable: boolean;
+    }>;
+}
+export type ShowHumanResult = {
+    ok: true;
+    record: EffectiveHumanRecord;
+} | {
+    ok: false;
+    error: string;
+};
+export type SetHumanFieldResult = {
+    ok: true;
+    path: string;
+    fragment: HumanFragment;
+} | {
+    ok: false;
+    error: string;
+};
+export type RemoveHumanResult = {
+    ok: true;
+    removed: string;
+    archivedPath: string;
+    orphanRecordPath?: string;
+} | {
+    ok: false;
+    error: string;
+    inflight?: InflightItem[];
+};
+/** --binding / set-binding spec: kind:connectorRef:secretsRef:role[:handle=<id>]. secretsRef is
+ *  a vault POINTER and may itself contain ':', so kind/connectorRef are the first two fields,
+ *  role is the LAST positional, secretsRef is everything between. An optional handle= token may
+ *  appear anywhere. ONE source for add (CLI) and set (here) — the same parse both paths. */
+export declare function parseBindingSpec(spec: string): {
+    ok: true;
+    binding: {
+        kind: string;
+        connectorRef: string;
+        secretsRef: string;
+        role: string;
+        handle?: string;
+    };
+} | {
+    ok: false;
+    error: string;
+};
+export declare function listHumans(home?: string): ListHumansResult;
+export declare function showHuman(entityId: string, home?: string): ShowHumanResult;
+export declare function setHumanField(entityId: string, field: string, value: string, home?: string): SetHumanFieldResult;
+export declare function removeHumanFragment(entityId: string, opts: {
+    force?: boolean;
+    inflight: InflightItem[];
+}, home?: string): RemoveHumanResult;
+/** The dispatch-buffer half of the remove guard: un-Acked outbound decisions bound to this
+ *  entity are open conversations. Match rule (documented, not guessed): entityBindingRef equal
+ *  to the entityId, equal to its registered address, or prefixed "<entityId>:". */
+export declare function pendingConversationsFor(entityId: string, home?: string): InflightItem[];
 export type LoadResult = {
     ok: true;
     entities: HumanFragment[];
@@ -121,4 +235,7 @@ export type LoadResult = {
  *  the fragments are truth, so the on-disk projection must byte-match a fresh one.
  *  This is the drift pin's runtime half (the vitest parity pin is the CI half). */
 export declare function loadHumanRegistry(home?: string): LoadResult;
+/** Resolve every registered spelling of a human to its canonical external address.
+ * Identity comes from the registry entity, never from a domain/suffix allow-list. */
+export declare function resolveRegisteredHumanAddress(sessionRef: string | null | undefined, entities: readonly HumanFragment[]): string | null;
 //# sourceMappingURL=human-registry.d.ts.map

package/daemon/dist/domain/gateway/human-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"human-registry.d.ts","sourceRoot":"","sources":["../../../src/domain/gateway/human-registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"human-registry.d.ts","sourceRoot":"","sources":["../../../src/domain/gateway/human-registry.ts"],"names":[],"mappings":"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"}

package/daemon/dist/domain/gateway/human-registry.js

@@ -17,6 +17,8 @@ import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, readdir
 import { join, dirname } from "node:path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { getOpenRigHome } from "../../openrig-compat.js";
+import { DispatchBuffer } from "./dispatch-buffer.js";
+import { parseSessionName } from "../session-name.js";
 // ── Schema (closed enums; extend only additively behind the contract) ──
 export const HUMAN_ENTITY_CLASSES = new Set(["human"]); // M1's only class
 export const HUMAN_CONNECTOR_KINDS = new Set(["slack"]); // M1's only kind
@@ -36,7 +38,12 @@ const ALLOWED_BINDING_KEYS = new Set(["kind", "connectorRef", "secretsRef", "rol
 // connector (e.g. a Slack user id). Constrained so it can never forge a session ref (no ':' / '@'
 // / whitespace) — it is compared to an inbound sender id and spliced into teaching text.
 export const HANDLE_PATTERN = /^[A-Za-z0-9._-]+$/;
-const ALLOWED_PREFS_KEYS = new Set(["deliveryClass", "away"]);
+const ALLOWED_PREFS_KEYS = new Set(["deliveryClass", "away", "availability"]);
+// OPR.0.5.6.1 — the availability enum the delivery rules engine consumes.
+// Legacy `away: true` reads as availability=away ONLY when availability is
+// whole-field-absent (the D1 convention); a present-but-conflicting pair is
+// refused at validation, never silently resolved.
+export const HUMAN_AVAILABILITY_MODES = new Set(["available", "focus", "away", "off"]);
 function unknownKey(obj, allowed) {
     for (const k of Object.keys(obj))
         if (!allowed.has(k))
@@ -141,9 +148,19 @@ export function validateHumanFragment(raw) {
     if (prefs.away !== undefined && typeof prefs.away !== "boolean") {
         return { ok: false, error: "prefs.away must be a boolean when present" };
     }
+    if (prefs.availability !== undefined && !HUMAN_AVAILABILITY_MODES.has(String(prefs.availability))) {
+        return { ok: false, error: `prefs.availability "${String(prefs.availability)}" must be one of available|focus|away|off` };
+    }
+    // Two spellings of one truth are refused: a present availability is the
+    // authority; legacy away may only AGREE with it (away:true + availability=away).
+    if (prefs.availability !== undefined && prefs.away === true && prefs.availability !== "away") {
+        return { ok: false, error: `prefs.away=true conflicts with prefs.availability "${String(prefs.availability)}" — set availability alone (away is the legacy spelling)` };
+    }
     const validatedPrefs = { deliveryClass: prefs.deliveryClass };
     if (prefs.away !== undefined)
         validatedPrefs.away = prefs.away;
+    if (prefs.availability !== undefined)
+        validatedPrefs.availability = prefs.availability;
     return {
         ok: true,
         fragment: { entityId, class: "human", displayName, address, connectorBindings: bindings, prefs: validatedPrefs },
@@ -300,6 +317,255 @@ export function addHumanFragment(raw, home = getOpenRigHome(), opts = {}) {
         return { ok: false, error: `fragment written but re-projection failed: ${proj.error}` };
     return { ok: true, path: file, fragment: v.fragment };
 }
+/** Amendment A1 (founder R5): the 0.5.5 surface is SINGLE-HUMAN. Several fragments render
+ *  honestly, but enumeration is display, never management — the advisory names the boundary. */
+export const MULTI_HUMAN_ADVISORY = "several human fragments exist; this release's surface is single-human — multi-human management is 0.5.7 scope (fragments are displayed honestly; no plural management verbs exist)";
+/** --binding / set-binding spec: kind:connectorRef:secretsRef:role[:handle=<id>]. secretsRef is
+ *  a vault POINTER and may itself contain ':', so kind/connectorRef are the first two fields,
+ *  role is the LAST positional, secretsRef is everything between. An optional handle= token may
+ *  appear anywhere. ONE source for add (CLI) and set (here) — the same parse both paths. */
+export function parseBindingSpec(spec) {
+    const all = spec.split(":");
+    const handleTokens = all.filter((p) => p.startsWith("handle="));
+    if (handleTokens.length > 1)
+        return { ok: false, error: `binding spec must carry at most one handle= token (got "${spec}")` };
+    const handle = handleTokens.length === 1 ? handleTokens[0].slice("handle=".length) : undefined;
+    if (handle !== undefined && handle.length === 0)
+        return { ok: false, error: `binding handle= must be non-empty (got "${spec}")` };
+    const parts = all.filter((p) => !p.startsWith("handle="));
+    if (parts.length < 4)
+        return { ok: false, error: `binding spec must be kind:connectorRef:secretsRef:role[:handle=<id>] (got "${spec}")` };
+    const kind = parts[0];
+    const connectorRef = parts[1];
+    const role = parts[parts.length - 1];
+    const secretsRef = parts.slice(2, -1).join(":");
+    if (!kind || !connectorRef || !secretsRef || !role) {
+        return { ok: false, error: `binding spec fields must be non-empty: kind:connectorRef:secretsRef:role[:handle=<id>] (got "${spec}")` };
+    }
+    return { ok: true, binding: handle !== undefined ? { kind, connectorRef, secretsRef, role, handle } : { kind, connectorRef, secretsRef, role } };
+}
+function fragmentPathFor(entityId, home) {
+    return join(humansDir(home), `${entityId}.yaml`);
+}
+function knownEntityIds(home) {
+    const dir = humansDir(home);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".yaml") && !f.startsWith("."))
+        .map((f) => f.slice(0, -".yaml".length))
+        .sort();
+}
+function unknownHumanError(entityId, home) {
+    const known = knownEntityIds(home);
+    return `no human "${entityId}" is registered — known humans: ${known.length ? known.join(", ") : "(none)"}`;
+}
+export function listHumans(home = getOpenRigHome()) {
+    const proj = projectHumans(home);
+    if (!proj.ok)
+        return { ok: false, error: proj.error };
+    const humans = proj.entities.map((e) => {
+        const primary = e.connectorBindings.find((b) => b.role === "primary");
+        return {
+            entityId: e.entityId,
+            displayName: e.displayName,
+            address: e.address,
+            deliveryClass: e.prefs.deliveryClass,
+            away: e.prefs.away === true,
+            bindings: {
+                count: e.connectorBindings.length,
+                primary: { kind: primary.kind, connectorRef: primary.connectorRef },
+                inboundResolvable: e.connectorBindings.some((b) => b.handle !== undefined),
+            },
+            fragmentPath: fragmentPathFor(e.entityId, home),
+        };
+    });
+    return humans.length > 1 ? { ok: true, humans, advisory: MULTI_HUMAN_ADVISORY } : { ok: true, humans };
+}
+/** Read one fragment RAW (for authored-vs-default provenance) + validated. */
+function readFragment(entityId, home) {
+    const path = fragmentPathFor(entityId, home);
+    if (!existsSync(path))
+        return { ok: false, error: unknownHumanError(entityId, home) };
+    let raw;
+    try {
+        raw = parseYaml(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        return { ok: false, error: `failed to parse human fragment ${entityId}.yaml: ${err.message}` };
+    }
+    const v = validateHumanFragment(raw);
+    if (!v.ok)
+        return { ok: false, error: `invalid human fragment ${entityId}.yaml: ${v.error}` };
+    return { ok: true, raw: raw, fragment: v.fragment, path };
+}
+export function showHuman(entityId, home = getOpenRigHome()) {
+    const f = readFragment(entityId, home);
+    if (!f.ok)
+        return f;
+    const rawPrefs = isObj(f.raw.prefs) ? f.raw.prefs : {};
+    return {
+        ok: true,
+        record: {
+            entityId: f.fragment.entityId,
+            address: f.fragment.address,
+            displayName: f.fragment.displayName,
+            fragmentPath: f.path,
+            prefs: {
+                deliveryClass: { value: f.fragment.prefs.deliveryClass, source: "authored" },
+                away: {
+                    value: f.fragment.prefs.away === true,
+                    source: rawPrefs.away !== undefined ? "authored" : "default",
+                },
+            },
+            connectorBindings: f.fragment.connectorBindings.map((b) => ({ ...b, inboundResolvable: b.handle !== undefined })),
+        },
+    };
+}
+const SETTABLE_FIELDS_TEACHING = "settable fields: display-name, delivery-class, away, binding.<n> (binding.<n> takes a full kind:connectorRef:secretsRef:role[:handle=<id>] spec)";
+/** Cross-fragment handle-uniqueness: the same pre-write check add runs (one platform id =
+ *  one human), extracted so set enforces it identically. */
+function handleConflict(fragment, home) {
+    const existing = projectHumans(home);
+    if (!existing.ok)
+        return `cannot validate handle uniqueness — existing registry is invalid: ${existing.error}`;
+    const claimed = new Map();
+    for (const e of existing.entities) {
+        if (e.entityId === fragment.entityId)
+            continue;
+        for (const b of e.connectorBindings)
+            if (b.handle !== undefined)
+                claimed.set(`${b.kind}:${b.handle}`, e.entityId);
+    }
+    for (const b of fragment.connectorBindings) {
+        if (b.handle === undefined)
+            continue;
+        const owner = claimed.get(`${b.kind}:${b.handle}`);
+        if (owner !== undefined) {
+            return `${b.kind} handle "${b.handle}" is already registered to human "${owner}" — a handle maps to exactly one human (registration conflict)`;
+        }
+    }
+    return undefined;
+}
+export function setHumanField(entityId, field, value, home = getOpenRigHome()) {
+    const f = readFragment(entityId, home);
+    if (!f.ok)
+        return f;
+    // Edit the RAW mapping (not the normalized fragment) so an unauthored optional field
+    // stays unauthored — show's provenance depends on the authored shape surviving edits.
+    const raw = f.raw;
+    const rawPrefs = isObj(raw.prefs) ? raw.prefs : {};
+    if (field === "display-name") {
+        if (value.length === 0)
+            return { ok: false, error: "display-name must be a non-empty string" };
+        raw.displayName = value;
+    }
+    else if (field === "delivery-class") {
+        rawPrefs.deliveryClass = value; // enum validated below by the SAME add-time validator
+        raw.prefs = rawPrefs;
+    }
+    else if (field === "away") {
+        if (value !== "true" && value !== "false") {
+            return { ok: false, error: `away must be true|false (got "${value}")` };
+        }
+        rawPrefs.away = value === "true";
+        raw.prefs = rawPrefs;
+    }
+    else if (field.startsWith("binding.")) {
+        const idxRaw = field.slice("binding.".length);
+        const idx = /^\d+$/.test(idxRaw) ? Number.parseInt(idxRaw, 10) : NaN;
+        const bindings = Array.isArray(raw.connectorBindings) ? raw.connectorBindings : [];
+        if (!Number.isInteger(idx) || idx < 0 || idx >= bindings.length) {
+            const valid = bindings.map((_, i) => `binding.${i}`).join(", ");
+            return { ok: false, error: `"${field}" is out of range — this human has ${bindings.length} binding(s): ${valid || "(none)"}` };
+        }
+        const parsed = parseBindingSpec(value);
+        if (!parsed.ok)
+            return parsed;
+        bindings[idx] = parsed.binding;
+        raw.connectorBindings = bindings;
+    }
+    else {
+        return { ok: false, error: `unknown field "${field}" — ${SETTABLE_FIELDS_TEACHING}` };
+    }
+    // Full add-time parity: structural + closed enums + cross-field invariants...
+    const v = validateHumanFragment(raw);
+    if (!v.ok)
+        return { ok: false, error: v.error };
+    if (v.fragment.entityId !== entityId) {
+        return { ok: false, error: `set must not change entityId (fragment key)` };
+    }
+    // ...plus the cross-fragment handle-uniqueness pre-write check add runs.
+    const conflict = handleConflict(v.fragment, home);
+    if (conflict)
+        return { ok: false, error: conflict };
+    const w = atomicWrite(f.path, stringifyYaml(raw));
+    if (!w.ok)
+        return { ok: false, error: w.error };
+    const proj = writeProjection(home);
+    if (!proj.ok)
+        return { ok: false, error: `fragment written but re-projection failed: ${proj.error}` };
+    return { ok: true, path: f.path, fragment: v.fragment };
+}
+export function removeHumanFragment(entityId, opts, home = getOpenRigHome()) {
+    const path = fragmentPathFor(entityId, home);
+    if (!existsSync(path))
+        return { ok: false, error: unknownHumanError(entityId, home) };
+    if (!opts.force && opts.inflight.length > 0) {
+        const lines = opts.inflight.map((i) => `  - ${i.kind} ${i.id} — ${i.detail}`).join("\n");
+        return {
+            ok: false,
+            inflight: opts.inflight,
+            error: `refusing to remove "${entityId}" — ${opts.inflight.length} in-flight item(s) would be orphaned:\n${lines}\n` +
+                `Resolve them first, or pass --force to archive anyway (every in-flight item above will be recorded as orphaned, never silently dropped).`,
+        };
+    }
+    // Archive, never delete bytes. Collision-safe name (ms timestamp + counter fallback).
+    const archiveDir = join(humansDir(home), ".archive");
+    try {
+        mkdirSync(archiveDir, { recursive: true });
+    }
+    catch (err) {
+        return { ok: false, error: `failed to create archive dir ${archiveDir}: ${err.message}` };
+    }
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    let archivedPath = join(archiveDir, `${entityId}.${stamp}.yaml`);
+    for (let n = 1; existsSync(archivedPath); n++)
+        archivedPath = join(archiveDir, `${entityId}.${stamp}-${n}.yaml`);
+    try {
+        renameSync(path, archivedPath);
+    }
+    catch (err) {
+        return { ok: false, error: `failed to archive ${path}: ${err.message}` };
+    }
+    let orphanRecordPath;
+    if (opts.inflight.length > 0) {
+        orphanRecordPath = archivedPath.replace(/\.yaml$/, ".orphans.json");
+        const record = { entityId, archivedFragment: archivedPath, orphaned: opts.inflight };
+        const w = atomicWrite(orphanRecordPath, JSON.stringify(record, null, 2));
+        if (!w.ok)
+            return { ok: false, error: `fragment archived to ${archivedPath} but the orphan record failed: ${w.error}` };
+    }
+    const proj = writeProjection(home);
+    if (!proj.ok)
+        return { ok: false, error: `fragment archived to ${archivedPath} but re-projection failed: ${proj.error}` };
+    const base = { ok: true, removed: entityId, archivedPath };
+    return orphanRecordPath !== undefined ? { ...base, orphanRecordPath } : base;
+}
+/** The dispatch-buffer half of the remove guard: un-Acked outbound decisions bound to this
+ *  entity are open conversations. Match rule (documented, not guessed): entityBindingRef equal
+ *  to the entityId, equal to its registered address, or prefixed "<entityId>:". */
+export function pendingConversationsFor(entityId, home = getOpenRigHome()) {
+    const address = `${entityId}@${ADDRESS_DOMAIN}`;
+    return new DispatchBuffer(home)
+        .pending()
+        .filter((d) => d.entityBindingRef === entityId || d.entityBindingRef === address || d.entityBindingRef.startsWith(`${entityId}:`))
+        .map((d) => ({
+        kind: "open-conversation",
+        id: d.decisionId,
+        detail: `undelivered outbound decision ${d.decisionId} (op ${d.op}, binding ${d.entityBindingRef})`,
+    }));
+}
 /** Load the registry via the projection, but REFUSE a hand-edited/drifted projection:
  *  the fragments are truth, so the on-disk projection must byte-match a fresh one.
  *  This is the drift pin's runtime half (the vitest parity pin is the CI half). */
@@ -316,4 +582,19 @@ export function loadHumanRegistry(home = getOpenRigHome()) {
     }
     return { ok: true, entities: proj.entities };
 }
+/** Resolve every registered spelling of a human to its canonical external address.
+ * Identity comes from the registry entity, never from a domain/suffix allow-list. */
+export function resolveRegisteredHumanAddress(sessionRef, entities) {
+    if (!sessionRef)
+        return null;
+    const parsed = parseSessionName(sessionRef);
+    const identity = parsed.kind === "external"
+        ? parsed.local
+        : parsed.kind === "canonical"
+            ? parsed.member
+            : null;
+    if (!identity)
+        return null;
+    return entities.find((entity) => entity.entityId === identity)?.address ?? null;
+}
 //# sourceMappingURL=human-registry.js.map