@xenosystem/agent-interface-host 0.1.3

package/dist/coordination/CoordinationService.d.ts

@@ -0,0 +1,166 @@
+/**
+ * The host's coordination surface — the three primitives as one service.
+ *
+ * `XENO_AGENT_COORDINATION_SPEC.md` §1 treats message, query and claim as one
+ * capability rather than three features, and this is where that becomes true:
+ * a claim refusal names the holder so the requester can *message* them, and a
+ * message is only actionable because the receiver can *query* what the sender
+ * changed. Composed here so no caller has to wire the relationship itself.
+ *
+ * ## Gate 8 — coordination is visible in the timeline, and causal
+ *
+ * §9 requires messages and claims to be auditable, and gate 8 requires "a diff
+ * can be traced back to the message that caused it". Two halves:
+ *
+ * 1. Every send, delivery, claim and refusal emits a runtime event, so the
+ *    timeline shows coordination alongside the work it produced.
+ * 2. A delivered message becomes the receiving run's **current cause** until its
+ *    turn ends. Work the run performs while that cause is set carries the
+ *    message id, so a diff points at the sentence that prompted it rather than
+ *    leaving a reader to infer it from timestamps.
+ *
+ * The second half is the one that is easy to get wrong by making it implicit.
+ * Inferring cause from "the message arrived shortly before the edit" is a guess
+ * that looks like a fact — and this codebase has spent enough time removing
+ * outputs that cannot distinguish a measurement from an assumption.
+ */
+import { type AcquireClaimResult, type Claim, type ClaimScope } from './claims.js';
+import { type DeliveredMessage, type AgentMessage, type InboundPolicy, type MessageBusOptions, type MessageOutcome } from './messages.js';
+import { type PeerDescriptor, type RunRecord, type RunSummary } from './query.js';
+export type CoordinationEvent = {
+    type: 'coordination.message.sent';
+    fromRunId: string;
+    toRunId: string;
+    messageId: string;
+    outcome: MessageOutcome['status'];
+} | {
+    type: 'coordination.message.delivered';
+    toRunId: string;
+    messageId: string;
+    fromRunId: string;
+} | {
+    type: 'coordination.claim.acquired';
+    runId: string;
+    scope: ClaimScope;
+    claimId: string;
+} | {
+    type: 'coordination.claim.refused';
+    runId: string;
+    scope: ClaimScope;
+    heldByRunId: string;
+} | {
+    type: 'coordination.claim.released';
+    runId: string;
+    released: number;
+};
+export interface CoordinationServiceOptions extends MessageBusOptions {
+    /**
+     * Where coordination events go. Injected rather than imported so the service
+     * has no opinion about the event store, and so a test observes exactly what a
+     * timeline would.
+     */
+    emit?: (event: CoordinationEvent) => void;
+    maxFiles?: number;
+    maxCommands?: number;
+    canSee?: (caller: RunRecord, candidate: RunRecord) => boolean;
+}
+export declare class CoordinationService {
+    #private;
+    constructor(options?: CoordinationServiceOptions);
+    /**
+     * Redirects coordination events after construction.
+     *
+     * Mirrors `WorkspaceHostService.setEventSink`, and exists for the same
+     * reason: the host is constructed with its services, so a sink passed at
+     * construction time would have to be built before the host that owns it. A
+     * service that can only be wired at construction cannot be mounted onto an
+     * existing host at all.
+     *
+     * Replaces rather than adds. Coordination events are the audit record gate 8
+     * rests on, and fanning them to two sinks makes "the timeline" ambiguous
+     * exactly where a reader needs it to be singular.
+     */
+    setEventSink(emit: (event: CoordinationEvent) => void): void;
+    /**
+     * Where coordination goes to become a durable timeline entry.
+     *
+     * Gate 8 is unusually blunt about the stakes: *"A reviewer looking at a
+     * surprising diff must be able to trace it back to the message that prompted
+     * it. **If they cannot, this section is not implemented.**"* Without this sink
+     * wired, coordination is visible live and absent from the record.
+     */
+    setTimelineSink(record: (event: CoordinationEvent, text?: string) => void): void;
+    registerRun(record: RunRecord): void;
+    /**
+     * A run ended. Claims release immediately rather than waiting for their lease
+     * (§5): waiting a full lease for a run we KNOW is gone is a stall nobody can
+     * explain, and the lease is the backstop for a host that never got the news.
+     */
+    endRun(runId: string): void;
+    send(input: {
+        fromRunId: string;
+        toRunId: string;
+        text: string;
+    }): MessageOutcome;
+    /**
+     * Delivers queued messages at a turn boundary (§6) and sets the receiving
+     * run's cause to the last one, so subsequent work is attributable.
+     */
+    deliverTo(runId: string): DeliveredMessage[];
+    /** The turn ended; work after this is no longer attributed to that message. */
+    endTurn(runId: string): void;
+    /**
+     * Gate 8: what caused this run's current work, or `undefined` when nothing
+     * did.
+     *
+     * `undefined` rather than a best guess: attributing a change to a message that
+     * merely arrived nearby would be an inference presented as a record, and a
+     * timeline that does that is worse than one that says nothing.
+     */
+    causeFor(runId: string): string | undefined;
+    acquireClaim(scope: ClaimScope, runId: string): AcquireClaimResult;
+    claims(): Claim[];
+    peers(callerRunId: string): PeerDescriptor[];
+    runSummary(callerRunId: string, targetRunId: string): RunSummary | undefined;
+    setInboundPolicy(runId: string, policy: InboundPolicy): void;
+    /** Returns a run to §6's derived default. See `MessageBus.clearInboundPolicy`. */
+    clearInboundPolicy(runId: string): void;
+    /**
+     * What policy a run is under, and whether a human chose it.
+     *
+     * Both halves, from ONE call, because they are read together and a surface
+     * that fetched them separately could render an effective policy against a
+     * stale notion of whether it was explicit — the two-reads-one-screen mistake.
+     *
+     * `effective` is computed against a NAMED peer rather than in the abstract:
+     * §6's derivation is comparative, so "what happens to a message" has no answer
+     * until you say who sent it. Absent a peer this reports the explicit override
+     * only, and says the derivation is what would decide.
+     */
+    inboundPolicyFor(runId: string, fromRunId?: string): {
+        explicit: InboundPolicy | undefined;
+        effective: InboundPolicy | undefined;
+    };
+    /**
+     * Messages withheld from this run, awaiting a human (§6 `hold`).
+     *
+     * 🔴 Without this and `releaseHeld` below, `hold` was a TRAP. The bus
+     * implements the whole lifecycle — set the policy, list what it withheld,
+     * release one — and this service exposed only the first third. Anything
+     * that set `hold` would have stranded messages where nothing above the bus
+     * could see or approve them, which is why nothing ever set it.
+     *
+     * §6 is explicit that a held message is "surfaced to the human for
+     * approval"; a hold nobody can act on is a silent drop with extra steps.
+     */
+    heldFor(runId: string): AgentMessage[];
+    /**
+     * A human approves a held message; it then follows the ordinary queue path.
+     *
+     * Returns the OUTCOME rather than a boolean, because §6 requires the sender
+     * to learn what became of every message — and a release can legitimately
+     * find nothing, which is `expired`, not failure.
+     */
+    releaseHeld(runId: string, messageId: string): MessageOutcome;
+}
+//# sourceMappingURL=CoordinationService.d.ts.map

package/dist/coordination/CoordinationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoordinationService.d.ts","sourceRoot":"","sources":["../../src/coordination/CoordinationService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAqC,KAAK,kBAAkB,EAAE,KAAK,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AACrH,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAqB,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAA;AAEpG,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,2BAA2B,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAA;CAAE,GAC/H;IAAE,IAAI,EAAE,gCAAgC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACjG;IAAE,IAAI,EAAE,6BAA6B,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC1F;IAAE,IAAI,EAAE,4BAA4B,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC7F;IAAE,IAAI,EAAE,6BAA6B,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAA;AAE5E,MAAM,WAAW,0BAA2B,SAAQ,iBAAiB;IACnE;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,KAAK,OAAO,CAAA;CAC9D;AAED,qBAAa,mBAAmB;;gBAmBlB,OAAO,GAAE,0BAA+B;IAmBpD;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI;IAI5D;;;;;;;OAOG;IACH,eAAe,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAShF,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAIpC;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAO3B,IAAI,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc;IAgBjF;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAe5C,+EAA+E;IAC/E,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI5B;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI3C,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,kBAAkB;IAoBlE,MAAM,IAAI,KAAK,EAAE;IAIjB,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,EAAE;IAI5C,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI5E,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI;IAI5D,kFAAkF;IAClF,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIvC;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG;QACnD,QAAQ,EAAE,aAAa,GAAG,SAAS,CAAA;QACnC,SAAS,EAAE,aAAa,GAAG,SAAS,CAAA;KACrC;IAYD;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE;IAItC;;;;;;OAMG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,cAAc;CAG9D"}

package/dist/coordination/CoordinationService.js

@@ -0,0 +1,247 @@
+/**
+ * The host's coordination surface — the three primitives as one service.
+ *
+ * `XENO_AGENT_COORDINATION_SPEC.md` §1 treats message, query and claim as one
+ * capability rather than three features, and this is where that becomes true:
+ * a claim refusal names the holder so the requester can *message* them, and a
+ * message is only actionable because the receiver can *query* what the sender
+ * changed. Composed here so no caller has to wire the relationship itself.
+ *
+ * ## Gate 8 — coordination is visible in the timeline, and causal
+ *
+ * §9 requires messages and claims to be auditable, and gate 8 requires "a diff
+ * can be traced back to the message that caused it". Two halves:
+ *
+ * 1. Every send, delivery, claim and refusal emits a runtime event, so the
+ *    timeline shows coordination alongside the work it produced.
+ * 2. A delivered message becomes the receiving run's **current cause** until its
+ *    turn ends. Work the run performs while that cause is set carries the
+ *    message id, so a diff points at the sentence that prompted it rather than
+ *    leaving a reader to infer it from timestamps.
+ *
+ * The second half is the one that is easy to get wrong by making it implicit.
+ * Inferring cause from "the message arrived shortly before the edit" is a guess
+ * that looks like a fact — and this codebase has spent enough time removing
+ * outputs that cannot distinguish a measurement from an assumption.
+ */
+import { ClaimRegistry, describeClaimScope } from './claims.js';
+import { MessageBus, } from './messages.js';
+import { CoordinationQuery } from './query.js';
+export class CoordinationService {
+    #claims;
+    #bus;
+    #query;
+    #emit;
+    /**
+     * The TIMELINE sink, separate from the live feed on purpose.
+     *
+     * §9 requires the message TEXT on the timeline — *"a reviewer following an id
+     * to a message they cannot read has traced a pointer, not a reason"* — while
+     * the host's live event feed is stamped `redactionState: 'safe'` and must
+     * carry ids and outcomes only. One sink cannot satisfy both, and collapsing
+     * them would either put message contents on every subscriber or leave the
+     * audit record unreadable. So: two sinks, and the text travels on exactly one.
+     */
+    #timeline = () => { };
+    /** runId -> the message currently being acted on, for gate-8 attribution. */
+    #cause = new Map();
+    constructor(options = {}) {
+        this.#claims = new ClaimRegistry(options.now === undefined ? {} : { now: options.now });
+        // 🔴 The posture resolver is supplied HERE and overrides anything a caller
+        // passed, because a run's posture is a fact this service owns: it arrives on
+        // the `RunRecord` the host registers. Letting a caller inject its own would
+        // create a second source of truth for the input to a safety rule, and the
+        // one that decided policy would not be the one the fleet view displays.
+        // Reading through a closure rather than a captured value keeps it LIVE — a
+        // posture that changes on the next `registerRun` upsert is the posture the
+        // next message is judged against.
+        this.#bus = new MessageBus({ ...options, posture: (runId) => this.#query.postureOf(runId) });
+        this.#query = new CoordinationQuery({
+            ...(options.maxFiles === undefined ? {} : { maxFiles: options.maxFiles }),
+            ...(options.maxCommands === undefined ? {} : { maxCommands: options.maxCommands }),
+            ...(options.canSee === undefined ? {} : { canSee: options.canSee }),
+        });
+        this.#emit = options.emit ?? (() => { });
+    }
+    /**
+     * Redirects coordination events after construction.
+     *
+     * Mirrors `WorkspaceHostService.setEventSink`, and exists for the same
+     * reason: the host is constructed with its services, so a sink passed at
+     * construction time would have to be built before the host that owns it. A
+     * service that can only be wired at construction cannot be mounted onto an
+     * existing host at all.
+     *
+     * Replaces rather than adds. Coordination events are the audit record gate 8
+     * rests on, and fanning them to two sinks makes "the timeline" ambiguous
+     * exactly where a reader needs it to be singular.
+     */
+    setEventSink(emit) {
+        this.#emit = emit;
+    }
+    /**
+     * Where coordination goes to become a durable timeline entry.
+     *
+     * Gate 8 is unusually blunt about the stakes: *"A reviewer looking at a
+     * surprising diff must be able to trace it back to the message that prompted
+     * it. **If they cannot, this section is not implemented.**"* Without this sink
+     * wired, coordination is visible live and absent from the record.
+     */
+    setTimelineSink(record) {
+        this.#timeline = record;
+    }
+    #publish(event, text) {
+        this.#emit(event);
+        this.#timeline(event, text);
+    }
+    registerRun(record) {
+        this.#query.upsertRun(record);
+    }
+    /**
+     * A run ended. Claims release immediately rather than waiting for their lease
+     * (§5): waiting a full lease for a run we KNOW is gone is a stall nobody can
+     * explain, and the lease is the backstop for a host that never got the news.
+     */
+    endRun(runId) {
+        const released = this.#claims.releaseRun(runId);
+        this.#cause.delete(runId);
+        this.#query.removeRun(runId);
+        if (released > 0)
+            this.#publish({ type: 'coordination.claim.released', runId, released });
+    }
+    send(input) {
+        // A message sent while handling another inherits its chain, so §8 loop
+        // detection works without the caller having to thread the id itself — which
+        // it would forget exactly when a loop was forming.
+        const causedBy = this.#cause.get(input.fromRunId);
+        const outcome = this.#bus.send({ ...input, ...(causedBy === undefined ? {} : { causedBy }) });
+        this.#publish({
+            type: 'coordination.message.sent',
+            fromRunId: input.fromRunId,
+            toRunId: input.toRunId,
+            messageId: outcome.messageId,
+            outcome: outcome.status,
+        }, input.text);
+        return outcome;
+    }
+    /**
+     * Delivers queued messages at a turn boundary (§6) and sets the receiving
+     * run's cause to the last one, so subsequent work is attributable.
+     */
+    deliverTo(runId) {
+        const delivered = this.#bus.drainFor(runId);
+        for (const item of delivered) {
+            this.#publish({
+                type: 'coordination.message.delivered',
+                toRunId: runId,
+                messageId: item.message.id,
+                fromRunId: item.message.fromRunId,
+            }, item.message.text);
+        }
+        const last = delivered.at(-1);
+        if (last)
+            this.#cause.set(runId, last.message.id);
+        return delivered;
+    }
+    /** The turn ended; work after this is no longer attributed to that message. */
+    endTurn(runId) {
+        this.#cause.delete(runId);
+    }
+    /**
+     * Gate 8: what caused this run's current work, or `undefined` when nothing
+     * did.
+     *
+     * `undefined` rather than a best guess: attributing a change to a message that
+     * merely arrived nearby would be an inference presented as a record, and a
+     * timeline that does that is worse than one that says nothing.
+     */
+    causeFor(runId) {
+        return this.#cause.get(runId);
+    }
+    acquireClaim(scope, runId) {
+        const result = this.#claims.acquire(scope, runId);
+        if (result.acquired) {
+            this.#publish({
+                type: 'coordination.claim.acquired',
+                runId,
+                scope: result.claim.scope,
+                claimId: result.claim.id,
+            });
+        }
+        else {
+            this.#publish({
+                type: 'coordination.claim.refused',
+                runId,
+                scope,
+                heldByRunId: result.heldBy.runId,
+            });
+        }
+        return result;
+    }
+    claims() {
+        return this.#claims.list();
+    }
+    peers(callerRunId) {
+        return this.#query.peers(callerRunId);
+    }
+    runSummary(callerRunId, targetRunId) {
+        return this.#query.runSummary(callerRunId, targetRunId, this.#claims.list());
+    }
+    setInboundPolicy(runId, policy) {
+        this.#bus.setInboundPolicy(runId, policy);
+    }
+    /** Returns a run to §6's derived default. See `MessageBus.clearInboundPolicy`. */
+    clearInboundPolicy(runId) {
+        this.#bus.clearInboundPolicy(runId);
+    }
+    /**
+     * What policy a run is under, and whether a human chose it.
+     *
+     * Both halves, from ONE call, because they are read together and a surface
+     * that fetched them separately could render an effective policy against a
+     * stale notion of whether it was explicit — the two-reads-one-screen mistake.
+     *
+     * `effective` is computed against a NAMED peer rather than in the abstract:
+     * §6's derivation is comparative, so "what happens to a message" has no answer
+     * until you say who sent it. Absent a peer this reports the explicit override
+     * only, and says the derivation is what would decide.
+     */
+    inboundPolicyFor(runId, fromRunId) {
+        const explicit = this.#bus.explicitPolicyFor(runId);
+        if (explicit !== undefined)
+            return { explicit, effective: explicit };
+        return {
+            explicit: undefined,
+            // `undefined` rather than a guess: without a sender there is nothing to
+            // compare, and reporting the permissive answer here would be the same
+            // failure the derivation itself refuses.
+            effective: fromRunId === undefined ? undefined : this.#bus.deriveInboundPolicy(fromRunId, runId),
+        };
+    }
+    /**
+     * Messages withheld from this run, awaiting a human (§6 `hold`).
+     *
+     * 🔴 Without this and `releaseHeld` below, `hold` was a TRAP. The bus
+     * implements the whole lifecycle — set the policy, list what it withheld,
+     * release one — and this service exposed only the first third. Anything
+     * that set `hold` would have stranded messages where nothing above the bus
+     * could see or approve them, which is why nothing ever set it.
+     *
+     * §6 is explicit that a held message is "surfaced to the human for
+     * approval"; a hold nobody can act on is a silent drop with extra steps.
+     */
+    heldFor(runId) {
+        return this.#bus.heldFor(runId);
+    }
+    /**
+     * A human approves a held message; it then follows the ordinary queue path.
+     *
+     * Returns the OUTCOME rather than a boolean, because §6 requires the sender
+     * to learn what became of every message — and a release can legitimately
+     * find nothing, which is `expired`, not failure.
+     */
+    releaseHeld(runId, messageId) {
+        return this.#bus.releaseHeld(runId, messageId);
+    }
+}
+//# sourceMappingURL=CoordinationService.js.map

package/dist/coordination/CoordinationService.js.map

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

package/dist/coordination/claims.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Task claiming — the third coordination primitive.
+ *
+ * `XENO_AGENT_COORDINATION_SPEC.md` §1 is blunt about why this exists: shared
+ * state means another run *could* know something and a message means it *does*,
+ * but **neither prevents two agents from starting the same work.** Only a claim
+ * does. §5 names the failure it closes: two agents independently rewriting the
+ * same module, each with a green suite, producing a merge that is wrong in a way
+ * neither could have detected alone.
+ *
+ * ## Why the host owns this
+ *
+ * §2.1: overlap is computed by the host **because the host is the only party
+ * that sees all runs**. A run cannot arbitrate a claim it cannot observe, and
+ * peer-to-peer discovery breaks at the container boundary — which is not a
+ * theory, it is Claude Code's own documented limitation, and we sandbox every
+ * run. A claim registry that lived in the fleet rather than above it would be
+ * unable to answer the one question it exists to answer.
+ *
+ * ## Scopes are paths, deliberately
+ *
+ * Spec §13 lists claim granularity as an OPEN DECISION: path, module, or free
+ * label. This implements **paths**, which §13 calls "the obvious start and the
+ * easiest to compute overlap for". Recorded as a decision rather than left
+ * implicit: free labels are more expressive and much harder to arbitrate, and
+ * nothing here forecloses adding them behind the same interface.
+ *
+ * The overlap rule is the same one `xeno-use` applies to sandbox mount targets,
+ * and for the same reason — a claim on `src/` must conflict with a claim on
+ * `src/app.ts`, or the coarser claim silently means nothing.
+ */
+/**
+ * A claim over WORKING TREE CONTENT — the original scope kind, unchanged.
+ *
+ * `kind` is optional so every existing `{ path }` literal, wire payload and stored claim stays
+ * valid. This is a protected host-protocol type; widening it additively is the only shape that
+ * does not force every consumer to change on the same commit.
+ */
+export interface PathClaimScope {
+    kind?: 'path';
+    path: string;
+}
+/**
+ * A claim over a GIT BRANCH — ADE step 5's branch permit.
+ *
+ * 🔴 This is an EXTENSION of the claim primitive rather than a second subsystem, and that was
+ * the whole design decision. The CLI's `waitForBranchPermit` would have arrived in the host
+ * carrying its own lease clock, its own expiry, its own release-on-crash path and its own audit
+ * trail — four things `ClaimRegistry` already does, and would then do twice, differently.
+ * Coordination §1 already names claim as one of the three primitives; a branch permit IS a
+ * claim whose unit of work happens not to be a path.
+ */
+export interface BranchClaimScope {
+    kind: 'branch';
+    branch: string;
+}
+export type ClaimScope = PathClaimScope | BranchClaimScope;
+export declare function isBranchScope(scope: ClaimScope): scope is BranchClaimScope;
+/** Canonical form for storage, so `refs/heads/x` and `x` cannot both be held. */
+export declare function normalizeClaimScope(scope: ClaimScope): ClaimScope;
+/** A stable one-line rendering for events and diagnostics. */
+export declare function describeClaimScope(scope: ClaimScope): string;
+export interface Claim {
+    id: string;
+    scope: ClaimScope;
+    runId: string;
+    acquiredAt: number;
+    /** Leases expire so a crashed run cannot deadlock the fleet (§5). */
+    expiresAt: number;
+}
+/**
+ * §5: "A refused claim returns WHO HOLDS IT, so the requesting agent can message
+ * that run rather than spin or silently proceed." A bare `false` would leave the
+ * caller with exactly the two behaviours the spec is trying to prevent.
+ */
+export type AcquireClaimResult = {
+    acquired: true;
+    claim: Claim;
+} | {
+    acquired: false;
+    heldBy: Claim;
+};
+export interface ClaimRegistryOptions {
+    /** Injected so lease expiry is deterministic in tests rather than wall-clock. */
+    now?: () => number;
+    leaseMs?: number;
+}
+/**
+ * Two scopes overlap when they name the same work or one contains the other.
+ *
+ * The containment half is what makes a coarse claim mean anything: without it a
+ * run holding `src/` would not conflict with a run holding `src/app.ts`, and the
+ * coarse claim would be decorative. Compared segment-wise so `src` does not
+ * swallow `srcgen` — the same prefix-boundary bug that widens a scoped grant.
+ */
+export declare function scopesOverlap(a: ClaimScope, b: ClaimScope): boolean;
+/**
+ * Host-held claim registry.
+ *
+ * Advisory to the agent, authoritative to the human (§5): a refusal tells the
+ * requester who holds the scope so it can coordinate, and the fleet view shows
+ * the collision before it becomes a merge.
+ */
+export declare class ClaimRegistry {
+    #private;
+    constructor(options?: ClaimRegistryOptions);
+    /** Live claims, expired ones already removed. */
+    list(): Claim[];
+    acquire(scope: ClaimScope, runId: string): AcquireClaimResult;
+    /** Extends a live lease. Returns false when it has already lapsed. */
+    renew(claimId: string): boolean;
+    release(claimId: string): boolean;
+    /**
+     * §5: "released automatically when a run terminates. A crashed run must never
+     * deadlock the fleet." Called by the host on run termination — the expiry
+     * sweep is the backstop for a host that never got the news, not the primary
+     * path, because waiting a full lease for a run we KNOW is gone is a stall
+     * nobody can explain.
+     */
+    releaseRun(runId: string): number;
+}
+//# sourceMappingURL=claims.d.ts.map

package/dist/coordination/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../src/coordination/claims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAgBH;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,QAAQ,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,gBAAgB,CAAA;AAE1D,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,KAAK,IAAI,gBAAgB,CAE1E;AAcD,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAIjE;AAED,8DAA8D;AAC9D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAI5D;AAED,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,UAAU,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAChC;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,KAAK,CAAA;CAAE,CAAA;AAEtC,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAWD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAoBnE;AAED;;;;;;GAMG;AACH,qBAAa,aAAa;;gBAKZ,OAAO,GAAE,oBAAyB;IAoB9C,iDAAiD;IACjD,IAAI,IAAI,KAAK,EAAE;IAKf,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,kBAAkB;IAyB7D,sEAAsE;IACtE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAQ/B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIjC;;;;;;OAMG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAUlC"}