@vibesdotdev/external 0.0.0-stage → 1.0.0-rc.0

package/dist/ambient/message-transport.impl.js

@@ -0,0 +1,300 @@
+/**
+ * Default `external/message-transport`.
+ *
+ * Two legs, one contract:
+ *  - LOCAL  — `external.agent_messages` in SQLite. Authoritative, offline-safe,
+ *             covers same-machine cross-session messaging.
+ *  - REMOTE — the declared `hq` service's ambient endpoint. Covers cross-machine.
+ *
+ * `claim()` reads both concurrently. A remote failure degrades to same-machine
+ * messaging; a total failure degrades to silence. Neither ever throws, because
+ * this runs on the fs hot path behind the same budget as the collision notice.
+ *
+ * DELIVERED-ONCE is implemented as CLAIM-AND-REMOVE on both legs — delete the
+ * local row, and let the server delete the remote key as it serves it. A
+ * read-then-mark design can redeliver into a context window if the process dies
+ * in between, which is the one failure mode this surface must not have.
+ */
+import * as z from 'zod/v4';
+import { getLogger } from '@vibesdotdev/logging';
+import { CapabilityError, CaughtFailureSchema, valueFreeFailure } from '@vibesdotdev/kernel';
+import { JsonValueSchema } from '@vibesdotdev/kernel/schemas/json';
+import { resolveAmbientBearer, resolveAmbientOrigin } from "./cloud-authenticated-json.js";
+import { attempt } from "./attempt.js";
+import { AgentMessageSchema, messageTargets } from "../schemas/agent-message.js";
+const CLAIM_TIMEOUT_MS = 400;
+const SEND_TIMEOUT_MS = 5_000;
+const SEND_PATH = '/api/ambient/messages';
+const CLAIM_PATH = '/api/ambient/messages/claim';
+/** A claim response carries its messages; anything else is not a claim. */
+const ClaimBodySchema = z.object({
+    messages: z.unknown().optional()
+});
+async function postJson(runtime, path, body, timeoutMs) {
+    // The provider is the declared `hq` service; none declared => local-only.
+    const origin = await resolveAmbientOrigin(runtime);
+    // The caller's bearer, read through the `auth/caller-bearer` context (rc05 §2.2).
+    const token = await resolveAmbientBearer(runtime);
+    if (!origin || !token)
+        return { ok: true, value: null };
+    try {
+        const response = await runtime.lifecycle.wait((signal) => fetch(`${origin}${path}`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${token}`
+            },
+            body: JSON.stringify(body),
+            signal
+        }), { timeoutMs, reason: `ambient-message-post:${path}` });
+        if (!response.ok)
+            return { ok: true, value: null };
+        const value = JsonValueSchema.parse(await response.json());
+        return { ok: true, value };
+    }
+    catch (error) {
+        // Declared-optional remote leg: log why, then degrade to local-only.
+        const failure = CaughtFailureSchema.parse(error);
+        getLogger('external.ambient.messages', runtime).warn('ambient message post failed', {
+            path,
+            error: valueFreeFailure(failure)
+        });
+        return { ok: false, cause: failure };
+    }
+}
+/** A rejection handler that keeps the failure as the outcome. */
+function claimOutcome(error) {
+    const failure = CaughtFailureSchema.parse(error);
+    return { ok: false, cause: failure };
+}
+function toRow(message) {
+    return {
+        id: message.id,
+        fromSessionId: message.fromSessionId,
+        fromMachineId: message.fromMachineId,
+        fromMachineName: message.fromMachineName,
+        fromWorkItemTitle: message.fromWorkItemTitle,
+        audienceKind: message.audience.kind,
+        audienceSessionId: message.audience.kind === 'session' ? message.audience.sessionId : undefined,
+        audienceFilePath: message.audience.kind === 'path' ? message.audience.filePath : undefined,
+        audienceWorkspaceRoot: message.audience.kind === 'path'
+            ? message.audience.workspaceRoot
+            : message.audience.kind === 'workspace'
+                ? message.audience.workspaceRoot
+                : undefined,
+        body: message.body,
+        sentAt: message.sentAt.toISOString(),
+        expiresAt: message.expiresAt.toISOString(),
+        createdAt: new Date().toISOString()
+    };
+}
+function fromRow(row) {
+    const audience = row.audienceKind === 'session'
+        ? { kind: 'session', sessionId: row.audienceSessionId ?? '' }
+        : row.audienceKind === 'path'
+            ? {
+                kind: 'path',
+                filePath: row.audienceFilePath ?? '',
+                workspaceRoot: row.audienceWorkspaceRoot
+            }
+            : { kind: 'workspace', workspaceRoot: row.audienceWorkspaceRoot ?? '' };
+    const parsed = AgentMessageSchema.safeParse({
+        id: row.id,
+        fromSessionId: row.fromSessionId,
+        fromMachineId: row.fromMachineId,
+        fromMachineName: row.fromMachineName,
+        fromWorkItemTitle: row.fromWorkItemTitle,
+        audience,
+        body: row.body,
+        sentAt: row.sentAt,
+        expiresAt: row.expiresAt
+    });
+    return parsed.success ? parsed.data : null;
+}
+export class DefaultMessageTransport {
+    runtime;
+    pending = [];
+    inFlight = null;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    async record() {
+        try {
+            return await this.runtime
+                .query('storage/record')
+                .withId('external.agent_messages')
+                .resolve();
+        }
+        catch (error) {
+            const failure = CaughtFailureSchema.parse(error);
+            if (!CapabilityError.isAbsenceOf(failure, 'storage/record', 'external.agent_messages')) {
+                throw error;
+            }
+            getLogger('external.ambient.messages', this.runtime).debug('agent message record unavailable', {
+                error: valueFreeFailure(failure)
+            });
+            return null;
+        }
+    }
+    /** Log an opportunistic claim-side failure the claim degrades past. */
+    noteClaimIssue(failure, message, id) {
+        getLogger('external.ambient.messages', this.runtime).debug(message, {
+            id,
+            error: valueFreeFailure(failure)
+        });
+    }
+    send(message) {
+        // LOCAL leg: written immediately so same-machine delivery works with no
+        // network at all. Best-effort: a message is not worth an error surface.
+        void attempt(this.runtime, async () => {
+            const rec = await this.record();
+            await rec?.create(toRow(message));
+        }, 'local message write');
+        // REMOTE leg: queued so a burst is one request.
+        this.pending.push(message);
+        void this.flush();
+    }
+    async flush() {
+        if (this.inFlight)
+            return this.inFlight;
+        const batch = this.pending;
+        if (batch.length === 0)
+            return;
+        this.pending = [];
+        this.inFlight = (async () => {
+            // The remote leg never throws into send(); a bearer that cannot be
+            // resolved is logged with its reason and the batch drops.
+            const outcome = await postJson(this.runtime, SEND_PATH, {
+                messages: batch.map((m) => ({
+                    ...m,
+                    sentAt: m.sentAt.toISOString(),
+                    expiresAt: m.expiresAt.toISOString()
+                }))
+            }, SEND_TIMEOUT_MS).catch((error) => {
+                const failure = CaughtFailureSchema.parse(error);
+                const facts = valueFreeFailure(failure);
+                getLogger('external.ambient.messages', this.runtime).warn('message projection could not resolve its provider origin or the caller bearer', { reason: facts.reason ?? 'unknown', error: facts });
+                return { ok: false, cause: failure };
+            });
+            if (!outcome.ok || outcome.value === null) {
+                // Not re-queued: same reasoning as the touch stream. The local
+                // leg already succeeded, so same-machine delivery is intact.
+                getLogger('external.ambient.messages', this.runtime).debug('message projection dropped a batch (offline or rejected)', { count: batch.length });
+            }
+        })().finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+    async claim(input) {
+        const [localOutcome, remoteOutcome] = await Promise.all([
+            this.claimLocal(input).then((messages) => ({ ok: true, value: messages }), claimOutcome),
+            this.claimRemote(input).then((messages) => ({ ok: true, value: messages }), claimOutcome)
+        ]);
+        if (!localOutcome.ok) {
+            getLogger('external.ambient.messages', this.runtime).warn('local message claim failed', {
+                error: valueFreeFailure(localOutcome.cause)
+            });
+        }
+        if (!remoteOutcome.ok) {
+            getLogger('external.ambient.messages', this.runtime).warn('remote message claim failed', {
+                error: valueFreeFailure(remoteOutcome.cause)
+            });
+        }
+        const local = localOutcome.ok ? localOutcome.value : [];
+        const remote = remoteOutcome.ok ? remoteOutcome.value : [];
+        // De-dupe by id: a message can arrive on both legs (it was written
+        // locally AND projected). Claiming both must not show it twice.
+        const byId = new Map();
+        for (const m of [...local, ...remote])
+            byId.set(m.id, m);
+        return Array.from(byId.values())
+            .sort((a, b) => a.sentAt.getTime() - b.sentAt.getTime())
+            .slice(0, input.limit);
+    }
+    async claimLocal(input) {
+        const rec = await this.record();
+        if (!rec)
+            return [];
+        const listed = await rec.list({ orderBy: { sentAt: 'asc' }, limit: 200 });
+        const now = new Date();
+        const claimed = [];
+        for (const row of listed.items) {
+            const message = fromRow(row);
+            if (!message)
+                continue;
+            // Expired rows are swept opportunistically: we are already here, and
+            // this is cheaper and more reliable than a cron nobody runs.
+            if (message.expiresAt.getTime() <= now.getTime()) {
+                try {
+                    await rec.delete(message.id);
+                }
+                catch (error) {
+                    this.noteClaimIssue(CaughtFailureSchema.parse(error), 'expired message sweep failed', message.id);
+                }
+                continue;
+            }
+            if (!messageTargets(message, input, now))
+                continue;
+            // CLAIM = REMOVE. Delete first, deliver second: if the delete fails
+            // we simply do not deliver, which is safer than delivering twice.
+            try {
+                await rec.delete(message.id);
+            }
+            catch (error) {
+                this.noteClaimIssue(CaughtFailureSchema.parse(error), 'message claim delete failed; not delivering', message.id);
+                continue;
+            }
+            claimed.push(message);
+            if (claimed.length >= input.limit)
+                break;
+        }
+        return claimed;
+    }
+    async claimRemote(input) {
+        const claimBody = {};
+        claimBody.sessionId = input.sessionId;
+        if (input.workspaceRoot !== undefined)
+            claimBody.workspaceRoot = input.workspaceRoot;
+        claimBody.filePaths = input.filePaths.slice(0, 20);
+        claimBody.limit = input.limit;
+        const outcome = await postJson(this.runtime, CLAIM_PATH, claimBody, CLAIM_TIMEOUT_MS);
+        if (!outcome.ok || outcome.value === null)
+            return [];
+        const parsed = ClaimBodySchema.safeParse(outcome.value);
+        if (!parsed.success)
+            return [];
+        const raw = parsed.data.messages;
+        if (!Array.isArray(raw))
+            return [];
+        const out = [];
+        for (const entry of raw) {
+            const parsedEntry = AgentMessageSchema.safeParse(entry);
+            if (!parsedEntry.success)
+                continue;
+            // Re-check targeting locally: never trust the wire about who a
+            // message was for.
+            if (!messageTargets(parsedEntry.data, input))
+                continue;
+            out.push(parsedEntry.data);
+        }
+        return out;
+    }
+}
+/**
+ * Resolve the configured transport, falling back to the built-in default.
+ * A host that composes no transport gets the default; a transport that fails
+ * to load fails the resolution, so an explicit send reports it instead of
+ * silently going nowhere.
+ */
+export async function resolveMessageTransport(runtime) {
+    if (!runtime.hasKind('external/message-transport')) {
+        return new DefaultMessageTransport(runtime);
+    }
+    const resolved = await runtime
+        .query('external/message-transport')
+        .resolve();
+    return resolved ?? new DefaultMessageTransport(runtime);
+}
+export default DefaultMessageTransport;
+//# sourceMappingURL=message-transport.impl.js.map

package/dist/ambient/message-transport.impl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-transport.impl.js","sourceRoot":"","sources":["../../src/ambient/message-transport.impl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EACN,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAIhB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAEnE,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC3F,OAAO,EAAE,OAAO,EAAuB,MAAM,cAAc,CAAC;AAE5D,OAAO,EACN,kBAAkB,EAClB,cAAc,EAGd,MAAM,6BAA6B,CAAC;AAGrC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAC7B,MAAM,eAAe,GAAG,KAAK,CAAC;AAC9B,MAAM,SAAS,GAAG,uBAAuB,CAAC;AAC1C,MAAM,UAAU,GAAG,6BAA6B,CAAC;AAEjD,2EAA2E;AAC3E,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC,CAAC;AAEH,KAAK,UAAU,QAAQ,CACtB,OAAqB,EACrB,IAAY,EACZ,IAAc,EACd,SAAiB;IAEjB,0EAA0E;IAC1E,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,CAAC;IACnD,kFAAkF;IAClF,MAAM,KAAK,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAExD,IAAI,CAAC;QACJ,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,IAAI,CAC5C,CAAC,MAAM,EAAE,EAAE,CACV,KAAK,CAAC,GAAG,MAAM,GAAG,IAAI,EAAE,EAAE;YACzB,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACR,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,KAAK,EAAE;aAChC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YAC1B,MAAM;SACN,CAAC,EACH,EAAE,SAAS,EAAE,MAAM,EAAE,wBAAwB,IAAI,EAAE,EAAE,CACrD,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACnD,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QAC3D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,qEAAqE;QACrE,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACjD,SAAS,CAAC,2BAA2B,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,6BAA6B,EAAE;YACnF,IAAI;YACJ,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC;SAChC,CAAC,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IACtC,CAAC;AACF,CAAC;AAED,iEAAiE;AACjE,SAAS,YAAY,CAAC,KAAc;IACnC,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACjD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACtC,CAAC;AAED,SAAS,KAAK,CAAC,OAAqB;IACnC,OAAO;QACN,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;QAC5C,YAAY,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;QACnC,iBAAiB,EAChB,OAAO,CAAC,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;QAC7E,gBAAgB,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;QAC1F,qBAAqB,EACpB,OAAO,CAAC,QAAQ,CAAC,IAAI,KAAK,MAAM;YAC/B,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa;YAChC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,KAAK,WAAW;gBACtC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAChC,CAAC,CAAC,SAAS;QACd,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE;QACpC,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,WAAW,EAAE;QAC1C,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACnC,CAAC;AACH,CAAC;AAED,SAAS,OAAO,CAAC,GAAoB;IACpC,MAAM,QAAQ,GACb,GAAG,CAAC,YAAY,KAAK,SAAS;QAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,SAAkB,EAAE,SAAS,EAAE,GAAG,CAAC,iBAAiB,IAAI,EAAE,EAAE;QACtE,CAAC,CAAC,GAAG,CAAC,YAAY,KAAK,MAAM;YAC5B,CAAC,CAAC;gBACA,IAAI,EAAE,MAAe;gBACrB,QAAQ,EAAE,GAAG,CAAC,gBAAgB,IAAI,EAAE;gBACpC,aAAa,EAAE,GAAG,CAAC,qBAAqB;aACxC;YACF,CAAC,CAAC,EAAE,IAAI,EAAE,WAAoB,EAAE,aAAa,EAAE,GAAG,CAAC,qBAAqB,IAAI,EAAE,EAAE,CAAC;IAEpF,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC;QAC3C,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,eAAe,EAAE,GAAG,CAAC,eAAe;QACpC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;QACxC,QAAQ;QACR,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,SAAS,EAAE,GAAG,CAAC,SAAS;KACxB,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5C,CAAC;AAED,MAAM,OAAO,uBAAuB;IAIN;IAHrB,OAAO,GAAmB,EAAE,CAAC;IAC7B,QAAQ,GAAyB,IAAI,CAAC;IAE9C,YAA6B,OAAqB;QAArB,YAAO,GAAP,OAAO,CAAc;IAAG,CAAC;IAE9C,KAAK,CAAC,MAAM;QACnB,IAAI,CAAC;YACJ,OAAO,MAAM,IAAI,CAAC,OAAO;iBACvB,KAAK,CAA6D,gBAAgB,CAAC;iBACnF,MAAM,CAAC,yBAAyB,CAAC;iBACjC,OAAO,EAAE,CAAC;QACb,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACjD,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC,OAAO,EAAE,gBAAgB,EAAE,yBAAyB,CAAC,EAAE,CAAC;gBACxF,MAAM,KAAK,CAAC;YACb,CAAC;YACD,SAAS,CAAC,2BAA2B,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,kCAAkC,EAAE;gBAC9F,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC;aAChC,CAAC,CAAC;YACH,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IAED,uEAAuE;IAC/D,cAAc,CAAC,OAAsB,EAAE,OAAe,EAAE,EAAU;QACzE,SAAS,CAAC,2BAA2B,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE;YACnE,EAAE;YACF,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC;SAChC,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,OAAqB;QACzB,wEAAwE;QACxE,wEAAwE;QACxE,KAAK,OAAO,CACX,IAAI,CAAC,OAAO,EACZ,KAAK,IAAI,EAAE;YACV,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QACnC,CAAC,EACD,qBAAqB,CACrB,CAAC;QAEF,gDAAgD;QAChD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3B,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,KAAK;QACV,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC;QACxC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC;QAC3B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC/B,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAElB,IAAI,CAAC,QAAQ,GAAG,CAAC,KAAK,IAAI,EAAE;YAC3B,mEAAmE;YACnE,0DAA0D;YAC1D,MAAM,OAAO,GAAoC,MAAM,QAAQ,CAC9D,IAAI,CAAC,OAAO,EACZ,SAAS,EACT;gBACC,QAAQ,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAC3B,GAAG,CAAC;oBACJ,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE;oBAC9B,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE;iBACpC,CAAC,CAAC;aACH,EACD,eAAe,CACf,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBAC1B,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBACjD,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;gBACxC,SAAS,CAAC,2BAA2B,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CACxD,+EAA+E,EAC/E,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,CACnD,CAAC;gBACF,OAAO,EAAE,EAAE,EAAE,KAAc,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;YAC/C,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;gBAC3C,+DAA+D;gBAC/D,6DAA6D;gBAC7D,SAAS,CAAC,2BAA2B,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,CACzD,0DAA0D,EAC1D,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,CACvB,CAAC;YACH,CAAC;QACF,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YACjB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACtB,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,QAAQ,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,KAKX;QACA,MAAM,CAAC,YAAY,EAAE,aAAa,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACvD,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,CAC1B,CAAC,QAAQ,EAAkC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,EAC7E,YAAY,CACZ;YACD,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,IAAI,CAC3B,CAAC,QAAQ,EAAkC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,EAC7E,YAAY,CACZ;SACD,CAAC,CAAC;QACH,IAAI,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC;YACtB,SAAS,CAAC,2BAA2B,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,4BAA4B,EAAE;gBACvF,KAAK,EAAE,gBAAgB,CAAC,YAAY,CAAC,KAAK,CAAC;aAC3C,CAAC,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,aAAa,CAAC,EAAE,EAAE,CAAC;YACvB,SAAS,CAAC,2BAA2B,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,6BAA6B,EAAE;gBACxF,KAAK,EAAE,gBAAgB,CAAC,aAAa,CAAC,KAAK,CAAC;aAC5C,CAAC,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,MAAM,MAAM,GAAG,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAE3D,mEAAmE;QACnE,gEAAgE;QAChE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAwB,CAAC;QAC7C,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,EAAE,GAAG,MAAM,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACzD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;aAC9B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;aACvD,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAEO,KAAK,CAAC,UAAU,CAAC,KAKxB;QACA,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QAChC,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,CAAC;QAEpB,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QAC1E,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,OAAO,GAAmB,EAAE,CAAC;QAEnC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YAChC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,CAAC,OAAO;gBAAE,SAAS;YAEvB,qEAAqE;YACrE,6DAA6D;YAC7D,IAAI,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;gBAClD,IAAI,CAAC;oBACJ,MAAM,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;gBAC9B,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBAChB,IAAI,CAAC,cAAc,CAClB,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,EAChC,8BAA8B,EAC9B,OAAO,CAAC,EAAE,CACV,CAAC;gBACH,CAAC;gBACD,SAAS;YACV,CAAC;YAED,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC;gBAAE,SAAS;YAEnD,oEAAoE;YACpE,kEAAkE;YAClE,IAAI,CAAC;gBACJ,MAAM,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAC9B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,IAAI,CAAC,cAAc,CAClB,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,EAChC,6CAA6C,EAC7C,OAAO,CAAC,EAAE,CACV,CAAC;gBACF,SAAS;YACV,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACtB,IAAI,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC,KAAK;gBAAE,MAAM;QAC1C,CAAC;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,KAKzB;QACA,MAAM,SAAS,GAA6B,EAAE,CAAC;QAC/C,SAAS,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QACtC,IAAI,KAAK,CAAC,aAAa,KAAK,SAAS;YAAE,SAAS,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;QACrF,SAAS,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACnD,SAAS,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC9B,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,gBAAgB,CAAC,CAAC;QACtF,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI;YAAE,OAAO,EAAE,CAAC;QACrD,MAAM,MAAM,GAAG,eAAe,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACxD,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,CAAC;QAEnC,MAAM,GAAG,GAAmB,EAAE,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;YACzB,MAAM,WAAW,GAAG,kBAAkB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACxD,IAAI,CAAC,WAAW,CAAC,OAAO;gBAAE,SAAS;YACnC,+DAA+D;YAC/D,mBAAmB;YACnB,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC;gBAAE,SAAS;YACvD,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QACD,OAAO,GAAG,CAAC;IACZ,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC5C,OAAqB;IAErB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,4BAA4B,CAAC,EAAE,CAAC;QACpD,OAAO,IAAI,uBAAuB,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,OAAO;SAC5B,KAAK,CAAoD,4BAA4B,CAAC;SACtF,OAAO,EAAE,CAAC;IACZ,OAAO,QAAQ,IAAI,IAAI,uBAAuB,CAAC,OAAO,CAAC,CAAC;AACzD,CAAC;AAED,eAAe,uBAAuB,CAAC"}

package/dist/ambient/pending-notices.d.ts

@@ -0,0 +1,11 @@
+/** Watcher-to-result bridge, owned by the handed runtime's activated client. */
+import { type RuntimeRef, type VibesRuntime } from '@vibesdotdev/kernel';
+import type { ExternalClient } from '../client/external-client.ts';
+import { type PendingNotice } from '../schemas/pending-notice.ts';
+export declare function activeExternalClient(runtime: RuntimeRef): ExternalClient;
+export declare function getAmbientSessionId(runtime: VibesRuntime, bound?: string): string;
+export declare function setPending(runtime: VibesRuntime, sessionId: string, entry: PendingNotice): void;
+export declare function drainPending(runtime: VibesRuntime, sessionId: string): PendingNotice | null;
+/** Ordered batches for delivery surfaces; the legacy drain retains its string fields. */
+export declare function drainPendingBatches(runtime: VibesRuntime, sessionId: string): PendingNotice[];
+//# sourceMappingURL=pending-notices.d.ts.map

package/dist/ambient/pending-notices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-notices.d.ts","sourceRoot":"","sources":["../../src/ambient/pending-notices.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,OAAO,EAAmB,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE1F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAEvF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,UAAU,GAAG,cAAc,CAIxE;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAE/F;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAE3F;AAED,yFAAyF;AACzF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,EAAE,CAE7F"}

package/dist/ambient/pending-notices.js

@@ -0,0 +1,24 @@
+/** Watcher-to-result bridge, owned by the handed runtime's activated client. */
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { tryGetVibesClient } from '@vibesdotdev/kernel/client';
+import { PendingNoticeSchema } from "../schemas/pending-notice.js";
+export function activeExternalClient(runtime) {
+    const resolved = tryGetVibesClient('external', runtime);
+    if (!resolved)
+        throw new CapabilityError('External must be activated before ambient producers.', 'UNAVAILABLE', { reason: 'external-client-not-active' });
+    return resolved;
+}
+export function getAmbientSessionId(runtime, bound) {
+    return activeExternalClient(runtime).ambientSessionId(bound);
+}
+export function setPending(runtime, sessionId, entry) {
+    activeExternalClient(runtime).queueNotice(sessionId, PendingNoticeSchema.parse(entry));
+}
+export function drainPending(runtime, sessionId) {
+    return activeExternalClient(runtime).drainNotice(sessionId);
+}
+/** Ordered batches for delivery surfaces; the legacy drain retains its string fields. */
+export function drainPendingBatches(runtime, sessionId) {
+    return activeExternalClient(runtime).drainNoticeBatches(sessionId);
+}
+//# sourceMappingURL=pending-notices.js.map

package/dist/ambient/pending-notices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-notices.js","sourceRoot":"","sources":["../../src/ambient/pending-notices.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,OAAO,EAAE,eAAe,EAAsC,MAAM,qBAAqB,CAAC;AAC1F,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAE/D,OAAO,EAAE,mBAAmB,EAAsB,MAAM,8BAA8B,CAAC;AAEvF,MAAM,UAAU,oBAAoB,CAAC,OAAmB;IACvD,MAAM,QAAQ,GAAG,iBAAiB,CAAiB,UAAU,EAAE,OAAO,CAAC,CAAC;IACxE,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,eAAe,CAAC,sDAAsD,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,4BAA4B,EAAE,CAAC,CAAC;IAC1J,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAqB,EAAE,KAAc;IACxE,OAAO,oBAAoB,CAAC,OAAO,CAAC,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAqB,EAAE,SAAiB,EAAE,KAAoB;IACxF,oBAAoB,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC,SAAS,EAAE,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;AACxF,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAqB,EAAE,SAAiB;IACpE,OAAO,oBAAoB,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;AAC7D,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,mBAAmB,CAAC,OAAqB,EAAE,SAAiB;IAC3E,OAAO,oBAAoB,CAAC,OAAO,CAAC,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;AACpE,CAAC"}

package/dist/ambient/subsystem-overlap.impl.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Detect two lanes working the same SUBSYSTEM from different worktrees.
+ *
+ * WHY THIS IS NOT THE COLLISION FILTER. `defaultCollisionFilter` answers "are we
+ * about to clobber each other's edits", and for that question it is right to
+ * say:
+ *
+ *     // Different worktree is not a collision.
+ *
+ * This answers a different question — "are we building the same thing twice" —
+ * and for THAT question a different worktree is the whole signal, not the
+ * exclusion. Same file, same worktree is an edit conflict. Same subsystem,
+ * different worktree is duplicated work, and it is invisible to a same-file
+ * check until both lanes have already written the code.
+ *
+ * MEASURED, 2026-08-05: two lanes independently built the same stacked-PR
+ * feature and both landed the same five commits under different shas, having
+ * independently reached the same two sub-conclusions (a drizzle renumber and a
+ * console.log fix). PR #276 — 125 files, +18,522 — was closed as superseded and
+ * its entire merge, 183 commits of drift and 13 conflicts, was wasted. That was
+ * the single largest loss of the day, larger than any individual defect.
+ *
+ * The existing ambient notice DID fire that day, but at PR-READ time and only
+ * for one shared file — long after both lanes had committed to the direction.
+ * Firing on the first edit inside a shared subsystem is early enough to matter.
+ *
+ * Reports, never blocks. Two lanes in one subsystem is often legitimate
+ * (different features in one package), so this is information for a human or
+ * agent to act on, not a gate. A gate here would be wrong and would be muted.
+ */
+import type { TouchPeer } from '../schemas/collision.ts';
+/**
+ * The unit a lane "commits to a direction" in. Split repositories put packages
+ * directly at the root (`forge/src`, `knowledge/src`); aggregate repositories
+ * may still group them (`apps/platform-web`, `org-apps/northwind-mechanical`).
+ */
+export declare function subsystemOf(filePath: string): string | null;
+export interface SubsystemOverlap {
+    subsystem: string;
+    sessionId: string;
+    /** What the other lane is on, when it declared one — the actionable part. */
+    gitBranch?: string;
+    workItemTitle?: string;
+    ageMs: number;
+}
+export interface SubsystemOverlapContext {
+    sessionId: string;
+    workspaceRoot?: string;
+}
+/**
+ * Peers active in the same subsystem from a DIFFERENT worktree.
+ *
+ * A peer with no declared workspaceRoot is not reported: without it we cannot
+ * tell a different lane from our own worktree, and a false "someone else is
+ * here" is worse than silence — it teaches people to ignore the notice.
+ */
+export declare function findSubsystemOverlaps(peers: readonly TouchPeer[], myPaths: readonly string[], context: SubsystemOverlapContext): SubsystemOverlap[];
+/** One line naming who, where, and on what — enough to go ask before building. */
+export declare function formatSubsystemOverlaps(overlaps: readonly SubsystemOverlap[]): string | null;
+//# sourceMappingURL=subsystem-overlap.impl.d.ts.map

package/dist/ambient/subsystem-overlap.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subsystem-overlap.impl.d.ts","sourceRoot":"","sources":["../../src/ambient/subsystem-overlap.impl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAyB3D;AAED,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,uBAAuB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,uBAAuB,GAC9B,gBAAgB,EAAE,CAqCpB;AASD,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,GAAG,IAAI,CAc5F"}

package/dist/ambient/subsystem-overlap.impl.js

@@ -0,0 +1,127 @@
+/**
+ * Detect two lanes working the same SUBSYSTEM from different worktrees.
+ *
+ * WHY THIS IS NOT THE COLLISION FILTER. `defaultCollisionFilter` answers "are we
+ * about to clobber each other's edits", and for that question it is right to
+ * say:
+ *
+ *     // Different worktree is not a collision.
+ *
+ * This answers a different question — "are we building the same thing twice" —
+ * and for THAT question a different worktree is the whole signal, not the
+ * exclusion. Same file, same worktree is an edit conflict. Same subsystem,
+ * different worktree is duplicated work, and it is invisible to a same-file
+ * check until both lanes have already written the code.
+ *
+ * MEASURED, 2026-08-05: two lanes independently built the same stacked-PR
+ * feature and both landed the same five commits under different shas, having
+ * independently reached the same two sub-conclusions (a drizzle renumber and a
+ * console.log fix). PR #276 — 125 files, +18,522 — was closed as superseded and
+ * its entire merge, 183 commits of drift and 13 conflicts, was wasted. That was
+ * the single largest loss of the day, larger than any individual defect.
+ *
+ * The existing ambient notice DID fire that day, but at PR-READ time and only
+ * for one shared file — long after both lanes had committed to the direction.
+ * Firing on the first edit inside a shared subsystem is early enough to matter.
+ *
+ * Reports, never blocks. Two lanes in one subsystem is often legitimate
+ * (different features in one package), so this is information for a human or
+ * agent to act on, not a gate. A gate here would be wrong and would be muted.
+ */
+/**
+ * The unit a lane "commits to a direction" in. Split repositories put packages
+ * directly at the root (`forge/src`, `knowledge/src`); aggregate repositories
+ * may still group them (`apps/platform-web`, `org-apps/northwind-mechanical`).
+ */
+export function subsystemOf(filePath) {
+    const normalized = filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+    const parts = normalized.split('/').filter(Boolean);
+    // Absolute paths: keep only the repo-relative tail we can reason about.
+    const rootIndex = parts.findIndex((part) => ['packages', 'apps', 'org-apps', 'internal-packages', 'libraries', 'consumer-apps'].includes(part));
+    if (rootIndex === -1) {
+        // Split-repo shape: identify the package immediately owning `src`. This is
+        // intentionally structural, not a copied package-name registry.
+        const srcIndex = parts.lastIndexOf('src');
+        if (srcIndex < 1)
+            return null;
+        return parts[srcIndex - 1] ?? null;
+    }
+    const root = parts[rootIndex];
+    const name = parts[rootIndex + 1];
+    if (!root || !name)
+        return null;
+    // org-apps nest one deeper: org-apps/<org>/<app>.
+    if (root === 'org-apps') {
+        const app = parts[rootIndex + 2];
+        return app ? `${root}/${name}/${app}` : `${root}/${name}`;
+    }
+    return `${root}/${name}`;
+}
+/**
+ * Peers active in the same subsystem from a DIFFERENT worktree.
+ *
+ * A peer with no declared workspaceRoot is not reported: without it we cannot
+ * tell a different lane from our own worktree, and a false "someone else is
+ * here" is worse than silence — it teaches people to ignore the notice.
+ */
+export function findSubsystemOverlaps(peers, myPaths, context) {
+    if (!context.workspaceRoot)
+        return [];
+    const mySubsystems = new Set(myPaths.map(subsystemOf).filter((value) => value !== null));
+    if (mySubsystems.size === 0)
+        return [];
+    const seen = new Set();
+    const overlaps = [];
+    for (const peer of peers) {
+        if (peer.sessionId === context.sessionId)
+            continue;
+        // The inversion: SAME worktree is the edit-collision case, already handled
+        // by defaultCollisionFilter. Only a different one is duplicated work.
+        if (!peer.workspaceRoot || peer.workspaceRoot === context.workspaceRoot)
+            continue;
+        const subsystem = subsystemOf(peer.filePath);
+        if (!subsystem || !mySubsystems.has(subsystem))
+            continue;
+        // One line per (peer, subsystem) — a lane editing forty files in one
+        // package is one piece of news, not forty.
+        const key = `${peer.sessionId}::${subsystem}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const overlap = {
+            subsystem,
+            sessionId: peer.sessionId,
+            ageMs: peer.ageMs
+        };
+        if (peer.gitBranch)
+            overlap.gitBranch = peer.gitBranch;
+        if (peer.workItemTitle)
+            overlap.workItemTitle = peer.workItemTitle;
+        overlaps.push(overlap);
+    }
+    return overlaps;
+}
+function humanAge(ageMs) {
+    const minutes = Math.round(ageMs / 60_000);
+    if (minutes < 1)
+        return 'just now';
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    return `${Math.round(minutes / 60)}h ago`;
+}
+/** One line naming who, where, and on what — enough to go ask before building. */
+export function formatSubsystemOverlaps(overlaps) {
+    if (overlaps.length === 0)
+        return null;
+    const parts = overlaps.map((overlap) => {
+        const who = overlap.sessionId.slice(0, 8);
+        const what = overlap.workItemTitle ? ` "${overlap.workItemTitle}"` : '';
+        const branch = overlap.gitBranch ? ` on ${overlap.gitBranch}` : '';
+        return `${overlap.subsystem} — ${who}${what}${branch}, ${humanAge(overlap.ageMs)}`;
+    });
+    const noun = overlaps.length === 1 ? 'lane is' : 'lanes are';
+    return (`Another ${noun} working in the same subsystem from a different worktree: ${parts.join('; ')}. ` +
+        'Different worktrees never collide on files, so this will not surface as an edit conflict — ' +
+        'check before building, or you may both ship it.');
+}
+//# sourceMappingURL=subsystem-overlap.impl.js.map

package/dist/ambient/subsystem-overlap.impl.js.map

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

package/dist/cli/dev.external.hooks-install.descriptor.d.ts

@@ -0,0 +1,7 @@
+/**
+ * External Hooks Install CLI Command Descriptor
+ */
+import type { CLICommandAssetDescriptor } from '@vibesdotdev/cli/schemas/types';
+declare const descriptor: CLICommandAssetDescriptor;
+export default descriptor;
+//# sourceMappingURL=dev.external.hooks-install.descriptor.d.ts.map

package/dist/cli/dev.external.hooks-install.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.external.hooks-install.descriptor.d.ts","sourceRoot":"","sources":["../../src/cli/dev.external.hooks-install.descriptor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAEhF,QAAA,MAAM,UAAU,EAAE,yBAuBjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/cli/dev.external.hooks-install.descriptor.js

@@ -0,0 +1,27 @@
+/**
+ * External Hooks Install CLI Command Descriptor
+ */
+const descriptor = {
+    kind: 'cli/command',
+    id: 'dev.external.hooks-install',
+    name: 'install',
+    description: 'Install hooks for a target tool',
+    group: 'dev.external.hooks',
+    arguments: [
+        {
+            name: 'target',
+            description: 'Registered external tool ID',
+            required: true,
+            variadic: false
+        }
+    ],
+    options: [
+        { flags: '--hooks <hooks>', description: 'Comma-separated list of hooks to install' },
+        { flags: '--global', description: 'Install globally' }
+    ],
+    surfaces: ['cli'],
+    hardware: ['consumer'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=dev.external.hooks-install.descriptor.js.map

package/dist/cli/dev.external.hooks-install.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.external.hooks-install.descriptor.js","sourceRoot":"","sources":["../../src/cli/dev.external.hooks-install.descriptor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,UAAU,GAA8B;IAC7C,IAAI,EAAE,aAAa;IACnB,EAAE,EAAE,4BAA4B;IAChC,IAAI,EAAE,SAAS;IACf,WAAW,EAAE,iCAAiC;IAC9C,KAAK,EAAE,oBAAoB;IAE3B,SAAS,EAAE;QACV;YACC,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,6BAA6B;YAC1C,QAAQ,EAAE,IAAI;YACd,QAAQ,EAAE,KAAK;SACf;KACD;IACD,OAAO,EAAE;QACR,EAAE,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,0CAA0C,EAAE;QACrF,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,kBAAkB,EAAE;KACtD;IAED,QAAQ,EAAE,CAAC,KAAK,CAAC;IACjB,QAAQ,EAAE,CAAC,UAAU,CAAC;IACtB,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/cli/dev.external.hooks-install.impl.d.ts

@@ -0,0 +1,9 @@
+/**
+ * External Hooks Install CLI Command Implementation
+ */
+import type { CommandContext, CommandOptions } from '@vibesdotdev/cli';
+declare const _default: {
+    execute(args: CommandOptions, opts: CommandOptions, context: CommandContext): Promise<void>;
+};
+export default _default;
+//# sourceMappingURL=dev.external.hooks-install.impl.d.ts.map

package/dist/cli/dev.external.hooks-install.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.external.hooks-install.impl.d.ts","sourceRoot":"","sources":["../../src/cli/dev.external.hooks-install.impl.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;;kBAWlD,cAAc,QAAQ,cAAc,WAAW,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;;AADlG,wBA6CE"}