@namzu/sdk 0.1.8 → 0.3.0

package/dist/session/handoff/broadcast.js

@@ -0,0 +1,311 @@
+/**
+ * Multi-recipient (broadcast) handoff — atomic fan-out with compensating
+ * rollback.
+ *
+ * See session-hierarchy.md §6.2 (Multi-recipient broadcast flow — atomic),
+ * §5.4 (broadcast source-session post-fan-out), §6.5 (capacity enforcement).
+ *
+ * **Atomicity contract** — one transaction boundary: either the full fan-out
+ * commits (source CAS-lock + N assignments + N sub-sessions + N worktrees),
+ * or none of it is externally observable. On any step failure the kernel
+ * executes a compensating rollback and emits `onBroadcastRollback` with
+ * accurate `partialState` counts. The rollback itself is idempotent per
+ * roadmap Risk #3.
+ *
+ * Commit / rollback sequence (pattern doc §6.2):
+ * ```
+ * COMMIT:   idle → locked(CAS) → N assignments → N sub-sessions → N worktrees → awaiting_merge
+ * ROLLBACK: ( ← tear down partial worktrees ← delete partial sub-sessions ←
+ *             delete partial assignments ← release CAS ) emit broadcast.rollback;
+ *             source → idle
+ * ```
+ */
+import { TenantIsolationError } from '../errors.js';
+import { NOOP_RUN_STATUS_RESOLVER } from './single.js';
+import { HandoffLockRejected, HandoffVersionConflict } from './version.js';
+/**
+ * Executes a broadcast fan-out. All assignments MUST share the same
+ * `sourceSessionId`, `expectedOwnerVersion`, `broadcastId`, and `projectId`.
+ * Duplicate recipients (same actor kind + id) are rejected before any write.
+ *
+ * Returns one {@link HandoffOutcome} per recipient on success. On failure the
+ * source session is restored, every provisioned resource is torn down, and
+ * the underlying error propagates after `onBroadcastRollback` is emitted.
+ */
+export async function executeBroadcastHandoff(deps, assignments, tenantId) {
+    // 1. Shape validation -----------------------------------------------------
+    if (assignments.length === 0) {
+        throw new Error('executeBroadcastHandoff: assignments must not be empty');
+    }
+    if (assignments.length === 1) {
+        throw new Error('executeBroadcastHandoff: single-recipient handoffs must use executeSingleHandoff');
+    }
+    const first = assignments[0];
+    if (!first)
+        throw new Error('executeBroadcastHandoff: assignments[0] undefined');
+    if (first.mode !== 'broadcast') {
+        throw new Error(`executeBroadcastHandoff: mode must be 'broadcast' (got '${first.mode}')`);
+    }
+    if (!first.broadcastId) {
+        throw new Error('executeBroadcastHandoff: broadcastId required on every assignment');
+    }
+    for (const a of assignments) {
+        if (a.tenantId !== tenantId) {
+            throw new TenantIsolationError({
+                requested: tenantId,
+                resource: `handoff-assignment(${a.id})`,
+            });
+        }
+        if (a.sourceSessionId !== first.sourceSessionId) {
+            throw new Error('executeBroadcastHandoff: all assignments must share sourceSessionId');
+        }
+        if (a.broadcastId !== first.broadcastId) {
+            throw new Error('executeBroadcastHandoff: all assignments must share broadcastId');
+        }
+        if (a.expectedOwnerVersion !== first.expectedOwnerVersion) {
+            throw new Error('executeBroadcastHandoff: all assignments must share expectedOwnerVersion');
+        }
+        if (a.threadId !== first.threadId) {
+            throw new Error('executeBroadcastHandoff: all assignments must share threadId');
+        }
+        if (a.projectId !== first.projectId) {
+            throw new Error('executeBroadcastHandoff: all assignments must share projectId');
+        }
+        if (a.mode !== 'broadcast') {
+            throw new Error('executeBroadcastHandoff: every assignment must have mode="broadcast"');
+        }
+    }
+    // 2. Dedupe recipients — same concern as the collab doc's Codex R: two rows
+    //    targeting the same actor would produce duplicate sub-sessions + racy
+    //    worktree paths. Reject before any side effect.
+    const seen = new Set();
+    for (const a of assignments) {
+        const key = recipientKey(a.recipientActor);
+        if (seen.has(key)) {
+            throw new Error(`executeBroadcastHandoff: duplicate recipient detected (${key}). Dedupe before submitting.`);
+        }
+        seen.add(key);
+    }
+    // Thread archive gate (Phase 2.6) — runs BEFORE source load/capacity so an
+    // archived thread fails fastest with `ThreadClosedError`. All assignments
+    // share `threadId` by the shape validation above. Runs BEFORE the CAS
+    // lock so a denied fan-out leaves the source session untouched.
+    await deps.threadManager.requireOpen(first.threadId, tenantId);
+    // 3. Load source + tenant check.
+    const source = await deps.store.getSession(first.sourceSessionId, tenantId);
+    if (!source) {
+        throw new Error(`Source session ${first.sourceSessionId} not found`);
+    }
+    if (source.tenantId !== tenantId) {
+        throw new TenantIsolationError({
+            requested: tenantId,
+            resource: `session(${source.id})`,
+        });
+    }
+    if (source.threadId !== first.threadId) {
+        throw new Error(`Assignment threadId ${first.threadId} does not match source threadId ${source.threadId}`);
+    }
+    if (source.projectId !== first.projectId) {
+        throw new Error(`Assignment projectId ${first.projectId} does not match source projectId ${source.projectId}`);
+    }
+    // 4. Status check.
+    if (source.status !== 'idle') {
+        throw new HandoffLockRejected({
+            sessionId: source.id,
+            reason: source.status === 'active'
+                ? 'active_run'
+                : source.status === 'awaiting_hitl'
+                    ? 'pending_hitl'
+                    : 'pending_subsession',
+        });
+    }
+    // 5. Non-terminal Run fan-in (§5.1).
+    const runResolver = deps.runStatus ?? NOOP_RUN_STATUS_RESOLVER;
+    const blocking = await runResolver.blockingRun(source.id, tenantId);
+    if (blocking) {
+        throw new HandoffLockRejected({ sessionId: source.id, reason: blocking.reason });
+    }
+    // 6. Capacity — width + depth. Width covers N new children in one shot
+    //    (§6.5); depth covers `source.depth + 1 ≤ maxDepth`.
+    const project = await deps.store.getProject(source.projectId, tenantId);
+    if (!project) {
+        throw new Error(`Project ${source.projectId} not found`);
+    }
+    await deps.capacity.validateWidth(source.id, assignments.length, project.config.maxDelegationWidth, tenantId);
+    await deps.capacity.validateDepth(source.id, project.config.maxDelegationDepth, tenantId);
+    // 7. CAS → source `idle → locked`.
+    if (source.ownerVersion !== first.expectedOwnerVersion) {
+        throw new HandoffVersionConflict({
+            sessionId: source.id,
+            expected: first.expectedOwnerVersion,
+            actual: source.ownerVersion,
+        });
+    }
+    const locked = { ...source, status: 'locked' };
+    await deps.store.updateSession(locked, tenantId);
+    emit(deps.events.onLocked, { sessionId: source.id, at: new Date() });
+    // 8. Fan-out provisioning. Track per-recipient partial state so rollback
+    //    can compensate precisely.
+    const partials = [];
+    let assignmentsWritten = 0;
+    let subsessionsCreated = 0;
+    let worktreesProvisioned = 0;
+    try {
+        const driver = deps.workspaceRegistry.get('git-worktree');
+        for (const assignment of assignments) {
+            // Per-recipient: new isolated workspace → new child session → new
+            // sub-session edge. Each sub-op advances the partial-state counters.
+            const partial = {
+                assignmentId: assignment.id,
+                recipientActor: assignment.recipientActor,
+                workspace: null,
+                createdSessionId: null,
+                createdSubSessionId: null,
+            };
+            partials.push(partial);
+            partial.workspace = await driver.create({ label: `broadcast-${assignment.id}` });
+            worktreesProvisioned += 1;
+            const childSession = await deps.store.createSession({
+                threadId: source.threadId,
+                projectId: source.projectId,
+                currentActor: assignment.recipientActor,
+            }, tenantId);
+            partial.createdSessionId = childSession.id;
+            const subSession = await deps.store.createSubSession({
+                parentSessionId: source.id,
+                childSessionId: childSession.id,
+                kind: 'user_handoff',
+                spawnedBy: assignment.sourceActor,
+            }, tenantId);
+            partial.createdSubSessionId = subSession.id;
+            subsessionsCreated += 1;
+            // "Assignments written" is the last per-recipient step — counts any
+            // recipient whose full row reached store-durable state.
+            assignmentsWritten += 1;
+        }
+        // 9. Commit source: `locked → awaiting_merge` (§5.4 — broadcast source is
+        //    not `idle` until all recipients terminalize; coordinator role).
+        const committed = {
+            ...source,
+            status: 'awaiting_merge',
+            ownerVersion: source.ownerVersion + 1,
+        };
+        await deps.store.updateSession(committed, tenantId);
+        emit(deps.events.onCommitted, {
+            sessionId: source.id,
+            newVersion: committed.ownerVersion,
+            handoffIds: assignments.map((a) => a.id),
+            at: new Date(),
+        });
+        return partials.map((p) => {
+            if (!p.workspace || !p.createdSessionId) {
+                // Unreachable — success path populates both fields on every partial.
+                throw new Error(`Broadcast partial for ${p.assignmentId} missing post-commit fields`);
+            }
+            return {
+                assignmentId: p.assignmentId,
+                newSessionId: p.createdSessionId,
+                workspaceId: p.workspace.id,
+                committedOwnerVersion: committed.ownerVersion,
+            };
+        });
+    }
+    catch (failure) {
+        await rollbackBroadcast(deps, source, partials, tenantId, {
+            broadcastId: first.broadcastId,
+            reason: failure instanceof Error ? failure.message : String(failure),
+            assignmentsWritten,
+            subsessionsCreated,
+            worktreesProvisioned,
+        });
+        throw failure;
+    }
+}
+/**
+ * Compensating rollback — idempotent per Risk #3.
+ *
+ * Order (reverse of commit): tear down worktrees → delete partially created
+ * sub-sessions → delete partially created child sessions → release source
+ * CAS lock → emit `onBroadcastRollback`. Every sub-op swallows its own
+ * secondary error so the primary failure remains the surfaced cause.
+ *
+ * Phase 8 closed the Phase 4 Known Delta (INTERP #2): previous implementation
+ * flipped partial recipient sessions to `status: 'archived'` as a stopgap
+ * because the store had no `deleteSession` primitive. The store now exposes
+ * `deleteSession` + `deleteSubSession` (idempotent), so rollback is total —
+ * no orphan records remain.
+ */
+async function rollbackBroadcast(deps, source, partials, tenantId, meta) {
+    // a. Dispose any provisioned worktrees (idempotent by driver contract).
+    for (const partial of partials) {
+        if (!partial.workspace)
+            continue;
+        try {
+            const driver = deps.workspaceRegistry.get('git-worktree');
+            await driver.dispose(partial.workspace);
+        }
+        catch {
+            // Idempotent — secondary failure must not mask the primary one.
+        }
+    }
+    // b. Delete any partially created sub-sessions (reverse order of creation
+    //    so child-side constraints release before the session below them).
+    for (const partial of partials) {
+        if (!partial.createdSubSessionId)
+            continue;
+        try {
+            await deps.store.deleteSubSession(partial.createdSubSessionId, tenantId);
+        }
+        catch {
+            // Idempotent.
+        }
+    }
+    // c. Delete partially created recipient sessions (total cleanup — pattern
+    //    doc §6.2: fan-out is atomic, partial state is externally
+    //    unobservable).
+    for (const partial of partials) {
+        if (!partial.createdSessionId)
+            continue;
+        try {
+            await deps.store.deleteSession(partial.createdSessionId, tenantId);
+        }
+        catch {
+            // Idempotent.
+        }
+    }
+    // d. Release source CAS — `locked → idle`, preserving ownerVersion.
+    try {
+        const reverted = { ...source, status: 'idle' };
+        await deps.store.updateSession(reverted, tenantId);
+    }
+    catch {
+        // Idempotent — the write-tmp-rename primitive is itself idempotent
+        // against the same payload.
+    }
+    emit(deps.events.onBroadcastRollback, {
+        sessionId: source.id,
+        broadcastId: meta.broadcastId,
+        reason: meta.reason,
+        partialState: {
+            assignmentsWritten: meta.assignmentsWritten,
+            subsessionsCreated: meta.subsessionsCreated,
+            worktreesProvisioned: meta.worktreesProvisioned,
+        },
+        at: new Date(),
+    });
+}
+function recipientKey(actor) {
+    switch (actor.kind) {
+        case 'user':
+            return `user:${actor.userId}`;
+        case 'agent':
+            return `agent:${actor.agentId}`;
+        case 'system':
+            return `system:${actor.role}`;
+    }
+}
+function emit(handler, event) {
+    if (handler)
+        handler(event);
+}
+//# sourceMappingURL=broadcast.js.map

package/dist/session/handoff/broadcast.js.map

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

package/dist/session/handoff/capacity.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Delegation capacity validation — depth + width caps applied at the kernel
+ * boundary before any write (session-hierarchy.md §6.5).
+ *
+ * Both `spawnSubSession()` and `broadcastHandoff()` call this module before
+ * committing; violations abort with typed {@link DelegationCapacityExceeded}
+ * and no partial writes occur (Convention #0: no workarounds; Convention #5:
+ * deny-by-default).
+ */
+import type { SessionId, TenantId } from '../../types/ids/index.js';
+import type { SessionStore } from '../../types/session/store.js';
+/** Capacity dimension under validation. */
+export type CapacityDimension = 'depth' | 'width';
+/**
+ * Raised when a spawn / broadcast would exceed the project's configured
+ * capacity caps. The check is a precondition — no partial writes occur on
+ * violation (session-hierarchy.md §6.5).
+ */
+export declare class DelegationCapacityExceeded extends Error {
+    readonly details: {
+        dimension: CapacityDimension;
+        current: number;
+        limit: number;
+        sessionId: SessionId;
+    };
+    constructor(details: {
+        dimension: CapacityDimension;
+        current: number;
+        limit: number;
+        sessionId: SessionId;
+    });
+}
+/**
+ * Capacity validator abstraction. Lets the handoff flows inject a validator
+ * without carrying the full {@link SessionStore} surface area into their
+ * dependency envelope (Convention #9: function-based flow keeps deps narrow).
+ *
+ * Both methods throw {@link DelegationCapacityExceeded} on violation and
+ * return void on success.
+ */
+export interface CapacityValidator {
+    /**
+     * Asserts `parentSession.depth + 1 ≤ projectMaxDepth`. Depth is computed by
+     * walking the ancestry via {@link SessionStore.getAncestry} — root-to-self
+     * length minus one equals the session's depth in the delegation tree.
+     */
+    validateDepth(parentSessionId: SessionId, projectMaxDepth: number, tenantId: TenantId): Promise<void>;
+    /**
+     * Asserts `existingDirectChildren + pendingNewChildren ≤ projectMaxWidth`
+     * under `parentSessionId`. The width cap applies to a single spawn call —
+     * a broadcast of N recipients passes `pendingNewChildren = N`.
+     */
+    validateWidth(parentSessionId: SessionId, pendingNewChildren: number, projectMaxWidth: number, tenantId: TenantId): Promise<void>;
+}
+/**
+ * Default validator backed by {@link SessionStore}. Uses `getAncestry` for
+ * depth (root-to-self chain length) and `getChildren` for width (count of
+ * existing direct sub-sessions).
+ */
+export declare class DefaultCapacityValidator implements CapacityValidator {
+    private readonly store;
+    constructor(store: SessionStore);
+    validateDepth(parentSessionId: SessionId, projectMaxDepth: number, tenantId: TenantId): Promise<void>;
+    validateWidth(parentSessionId: SessionId, pendingNewChildren: number, projectMaxWidth: number, tenantId: TenantId): Promise<void>;
+}
+//# sourceMappingURL=capacity.d.ts.map

package/dist/session/handoff/capacity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capacity.d.ts","sourceRoot":"","sources":["../../../src/session/handoff/capacity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAEhE,2CAA2C;AAC3C,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,OAAO,CAAA;AAEjD;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACpD,QAAQ,CAAC,OAAO,EAAE;QACjB,SAAS,EAAE,iBAAiB,CAAA;QAC5B,OAAO,EAAE,MAAM,CAAA;QACf,KAAK,EAAE,MAAM,CAAA;QACb,SAAS,EAAE,SAAS,CAAA;KACpB,CAAA;gBAEW,OAAO,EAAE;QACpB,SAAS,EAAE,iBAAiB,CAAA;QAC5B,OAAO,EAAE,MAAM,CAAA;QACf,KAAK,EAAE,MAAM,CAAA;QACb,SAAS,EAAE,SAAS,CAAA;KACpB;CAOD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,aAAa,CACZ,eAAe,EAAE,SAAS,EAC1B,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,QAAQ,GAChB,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhB;;;;OAIG;IACH,aAAa,CACZ,eAAe,EAAE,SAAS,EAC1B,kBAAkB,EAAE,MAAM,EAC1B,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,QAAQ,GAChB,OAAO,CAAC,IAAI,CAAC,CAAA;CAChB;AAED;;;;GAIG;AACH,qBAAa,wBAAyB,YAAW,iBAAiB;IACrD,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,YAAY;IAE1C,aAAa,CAClB,eAAe,EAAE,SAAS,EAC1B,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,QAAQ,GAChB,OAAO,CAAC,IAAI,CAAC;IAeV,aAAa,CAClB,eAAe,EAAE,SAAS,EAC1B,kBAAkB,EAAE,MAAM,EAC1B,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,QAAQ,GAChB,OAAO,CAAC,IAAI,CAAC;CAYhB"}

package/dist/session/handoff/capacity.js

@@ -0,0 +1,60 @@
+/**
+ * Delegation capacity validation — depth + width caps applied at the kernel
+ * boundary before any write (session-hierarchy.md §6.5).
+ *
+ * Both `spawnSubSession()` and `broadcastHandoff()` call this module before
+ * committing; violations abort with typed {@link DelegationCapacityExceeded}
+ * and no partial writes occur (Convention #0: no workarounds; Convention #5:
+ * deny-by-default).
+ */
+/**
+ * Raised when a spawn / broadcast would exceed the project's configured
+ * capacity caps. The check is a precondition — no partial writes occur on
+ * violation (session-hierarchy.md §6.5).
+ */
+export class DelegationCapacityExceeded extends Error {
+    details;
+    constructor(details) {
+        super(`Delegation capacity exceeded: ${details.dimension} ${details.current}/${details.limit} on ${details.sessionId}`);
+        this.name = 'DelegationCapacityExceeded';
+        this.details = details;
+    }
+}
+/**
+ * Default validator backed by {@link SessionStore}. Uses `getAncestry` for
+ * depth (root-to-self chain length) and `getChildren` for width (count of
+ * existing direct sub-sessions).
+ */
+export class DefaultCapacityValidator {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async validateDepth(parentSessionId, projectMaxDepth, tenantId) {
+        const ancestry = await this.store.getAncestry(parentSessionId, tenantId);
+        // depth is 0-indexed — root session has depth 0. New child depth =
+        // ancestry length (root-to-parent inclusive).
+        const newDepth = ancestry.length;
+        if (newDepth > projectMaxDepth) {
+            throw new DelegationCapacityExceeded({
+                dimension: 'depth',
+                current: newDepth,
+                limit: projectMaxDepth,
+                sessionId: parentSessionId,
+            });
+        }
+    }
+    async validateWidth(parentSessionId, pendingNewChildren, projectMaxWidth, tenantId) {
+        const existing = await this.store.getChildren(parentSessionId, tenantId);
+        const total = existing.length + pendingNewChildren;
+        if (total > projectMaxWidth) {
+            throw new DelegationCapacityExceeded({
+                dimension: 'width',
+                current: total,
+                limit: projectMaxWidth,
+                sessionId: parentSessionId,
+            });
+        }
+    }
+}
+//# sourceMappingURL=capacity.js.map

package/dist/session/handoff/capacity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capacity.js","sourceRoot":"","sources":["../../../src/session/handoff/capacity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;;;GAIG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC3C,OAAO,CAKf;IAED,YAAY,OAKX;QACA,KAAK,CACJ,iCAAiC,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,KAAK,OAAO,OAAO,CAAC,SAAS,EAAE,CAChH,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAA;QACxC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACvB,CAAC;CACD;AAmCD;;;;GAIG;AACH,MAAM,OAAO,wBAAwB;IACP;IAA7B,YAA6B,KAAmB;QAAnB,UAAK,GAAL,KAAK,CAAc;IAAG,CAAC;IAEpD,KAAK,CAAC,aAAa,CAClB,eAA0B,EAC1B,eAAuB,EACvB,QAAkB;QAElB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAA;QACxE,mEAAmE;QACnE,8CAA8C;QAC9C,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAA;QAChC,IAAI,QAAQ,GAAG,eAAe,EAAE,CAAC;YAChC,MAAM,IAAI,0BAA0B,CAAC;gBACpC,SAAS,EAAE,OAAO;gBAClB,OAAO,EAAE,QAAQ;gBACjB,KAAK,EAAE,eAAe;gBACtB,SAAS,EAAE,eAAe;aAC1B,CAAC,CAAA;QACH,CAAC;IACF,CAAC;IAED,KAAK,CAAC,aAAa,CAClB,eAA0B,EAC1B,kBAA0B,EAC1B,eAAuB,EACvB,QAAkB;QAElB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAA;QACxE,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,kBAAkB,CAAA;QAClD,IAAI,KAAK,GAAG,eAAe,EAAE,CAAC;YAC7B,MAAM,IAAI,0BAA0B,CAAC;gBACpC,SAAS,EAAE,OAAO;gBAClB,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,eAAe;gBACtB,SAAS,EAAE,eAAe;aAC1B,CAAC,CAAA;QACH,CAAC;IACF,CAAC;CACD"}

package/dist/session/handoff/events.d.ts

@@ -0,0 +1,66 @@
+/**
+ * HandoffEventSink — pluggable event sink for Phase 4.
+ *
+ * Phase 4 does NOT extend `RunEvent` with handoff variants (they land in a
+ * later phase that wires the full `SessionHierarchyEvent` union referenced
+ * by roadmap §1). In the meantime the flow functions invoke this sink so
+ * consumers + tests can observe state transitions without a concrete event
+ * bus. Every callback is optional; {@link NOOP_HANDOFF_SINK} is the
+ * deny-by-default instance to pass when observation is not needed.
+ */
+import type { SessionId } from '../../types/ids/index.js';
+import type { HandoffId } from '../../types/session/ids.js';
+/** Fired when a source session transitions `idle → locked` for handoff. */
+export interface HandoffLockedEvent {
+    sessionId: SessionId;
+    at: Date;
+}
+/**
+ * Fired when a compensating rollback returns a source session
+ * `locked → idle` (either CAS failure or downstream provisioning failure).
+ */
+export interface HandoffUnlockedEvent {
+    sessionId: SessionId;
+    at: Date;
+}
+/**
+ * Fired once per handoff commit. For `single` the `handoffIds` array has one
+ * entry; for `broadcast` it contains every recipient's assignment id.
+ */
+export interface HandoffCommittedEvent {
+    sessionId: SessionId;
+    newVersion: number;
+    handoffIds: readonly HandoffId[];
+    at: Date;
+}
+/**
+ * Fired when a broadcast fan-out mid-flight rolls back. `partialState` carries
+ * the per-stage counts of resources that were provisioned before the failure
+ * was detected — consumers can correlate with their own observability signals
+ * to verify the rollback is complete.
+ */
+export interface HandoffBroadcastRollbackEvent {
+    sessionId: SessionId;
+    broadcastId: string;
+    reason: string;
+    partialState: {
+        assignmentsWritten: number;
+        subsessionsCreated: number;
+        worktreesProvisioned: number;
+    };
+    at: Date;
+}
+/**
+ * Pluggable observer interface. All callbacks optional; consumers implement
+ * only what they need (Convention #5 deny-by-default applies to event
+ * consumers too — they must opt in explicitly).
+ */
+export interface HandoffEventSink {
+    onLocked?(ev: HandoffLockedEvent): void;
+    onUnlocked?(ev: HandoffUnlockedEvent): void;
+    onCommitted?(ev: HandoffCommittedEvent): void;
+    onBroadcastRollback?(ev: HandoffBroadcastRollbackEvent): void;
+}
+/** No-op sink — inject when the caller does not need handoff observability. */
+export declare const NOOP_HANDOFF_SINK: HandoffEventSink;
+//# sourceMappingURL=events.d.ts.map

package/dist/session/handoff/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/session/handoff/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAE3D,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,SAAS,CAAA;IACpB,EAAE,EAAE,IAAI,CAAA;CACR;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACpC,SAAS,EAAE,SAAS,CAAA;IACpB,EAAE,EAAE,IAAI,CAAA;CACR;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACrC,SAAS,EAAE,SAAS,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,SAAS,SAAS,EAAE,CAAA;IAChC,EAAE,EAAE,IAAI,CAAA;CACR;AAED;;;;;GAKG;AACH,MAAM,WAAW,6BAA6B;IAC7C,SAAS,EAAE,SAAS,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE;QACb,kBAAkB,EAAE,MAAM,CAAA;QAC1B,kBAAkB,EAAE,MAAM,CAAA;QAC1B,oBAAoB,EAAE,MAAM,CAAA;KAC5B,CAAA;IACD,EAAE,EAAE,IAAI,CAAA;CACR;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,CAAC,EAAE,EAAE,kBAAkB,GAAG,IAAI,CAAA;IACvC,UAAU,CAAC,CAAC,EAAE,EAAE,oBAAoB,GAAG,IAAI,CAAA;IAC3C,WAAW,CAAC,CAAC,EAAE,EAAE,qBAAqB,GAAG,IAAI,CAAA;IAC7C,mBAAmB,CAAC,CAAC,EAAE,EAAE,6BAA6B,GAAG,IAAI,CAAA;CAC7D;AAED,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB,EAAE,gBAAoC,CAAA"}

package/dist/session/handoff/events.js

@@ -0,0 +1,13 @@
+/**
+ * HandoffEventSink — pluggable event sink for Phase 4.
+ *
+ * Phase 4 does NOT extend `RunEvent` with handoff variants (they land in a
+ * later phase that wires the full `SessionHierarchyEvent` union referenced
+ * by roadmap §1). In the meantime the flow functions invoke this sink so
+ * consumers + tests can observe state transitions without a concrete event
+ * bus. Every callback is optional; {@link NOOP_HANDOFF_SINK} is the
+ * deny-by-default instance to pass when observation is not needed.
+ */
+/** No-op sink — inject when the caller does not need handoff observability. */
+export const NOOP_HANDOFF_SINK = Object.freeze({});
+//# sourceMappingURL=events.js.map

package/dist/session/handoff/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/session/handoff/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA6DH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,iBAAiB,GAAqB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA"}

package/dist/session/handoff/index.d.ts

@@ -0,0 +1,12 @@
+export type { HandoffAssignment, HandoffMode, HandoffOutcome } from './assignment.js';
+export { DefaultCapacityValidator, DelegationCapacityExceeded, } from './capacity.js';
+export type { CapacityDimension, CapacityValidator } from './capacity.js';
+export { HandoffLockRejected, HandoffVersionConflict } from './version.js';
+export type { HandoffLockRejectedReason } from './version.js';
+export { NOOP_HANDOFF_SINK } from './events.js';
+export type { HandoffBroadcastRollbackEvent, HandoffCommittedEvent, HandoffEventSink, HandoffLockedEvent, HandoffUnlockedEvent, } from './events.js';
+export { executeSingleHandoff, NOOP_RUN_STATUS_RESOLVER } from './single.js';
+export type { RunStatusResolver, SingleHandoffDeps } from './single.js';
+export { executeBroadcastHandoff } from './broadcast.js';
+export type { BroadcastHandoffDeps } from './broadcast.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/session/handoff/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/session/handoff/index.ts"],"names":[],"mappings":"AAIA,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErF,OAAO,EACN,wBAAwB,EACxB,0BAA0B,GAC1B,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAEzE,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAC1E,YAAY,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAA;AAE7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC/C,YAAY,EACX,6BAA6B,EAC7B,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,GACpB,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAC5E,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AACxD,YAAY,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/session/handoff/index.js

@@ -0,0 +1,9 @@
+// Sub-barrel for the handoff state machine (Convention #4).
+// Concrete flow functions + types live in sibling files; re-export the public
+// surface here. See session-hierarchy.md §6.
+export { DefaultCapacityValidator, DelegationCapacityExceeded, } from './capacity.js';
+export { HandoffLockRejected, HandoffVersionConflict } from './version.js';
+export { NOOP_HANDOFF_SINK } from './events.js';
+export { executeSingleHandoff, NOOP_RUN_STATUS_RESOLVER } from './single.js';
+export { executeBroadcastHandoff } from './broadcast.js';
+//# sourceMappingURL=index.js.map

package/dist/session/handoff/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/session/handoff/index.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,8EAA8E;AAC9E,6CAA6C;AAI7C,OAAO,EACN,wBAAwB,EACxB,0BAA0B,GAC1B,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAG1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAS/C,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAG5E,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/session/handoff/single.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Single-recipient handoff flow — `idle → locked → CAS → commit | revert`.
+ *
+ * See session-hierarchy.md §6.1 (single-recipient flow) and §6.4 (concurrent
+ * CAS). Function-based per Convention #9 — dependencies arrive as an
+ * explicit `deps` envelope so tests can inject mocks and production code
+ * composes flows without a class hierarchy.
+ *
+ * Flow (pattern doc §5.1 + §6.1):
+ *   1. Load source session; verify tenant.
+ *   2. Check status (must be `idle`); no non-terminal Runs.
+ *   3. Validate capacity (depth + width).
+ *   4. Transition source `idle → locked` with CAS on `ownerVersion`.
+ *   5. Emit `onLocked`.
+ *   6. Spawn recipient sub-session + provision isolated workspace.
+ *   7. On any step 6 failure: compensating revert (`locked → idle`, version
+ *      unchanged, dispose any partial worktree), emit `onUnlocked`, rethrow.
+ *   8. On success: commit `locked → idle` with updated `currentActor` +
+ *      appended `previousActors` + bumped `ownerVersion`.
+ *   9. Emit `onCommitted` with the new version.
+ */
+import type { ThreadManager } from '../../manager/thread/lifecycle.js';
+import type { SessionId, TenantId } from '../../types/ids/index.js';
+import type { SessionStore } from '../../types/session/store.js';
+import type { WorkspaceBackendRegistry } from '../workspace/registry.js';
+import type { HandoffAssignment, HandoffOutcome } from './assignment.js';
+import type { CapacityValidator } from './capacity.js';
+import type { HandoffEventSink } from './events.js';
+/**
+ * Minimal surface the handoff flow queries for Run fan-in status. A Run is
+ * considered "blocking" if it is in any non-terminal status that prevents the
+ * source session from transitioning to `locked` (session-hierarchy.md §5.1).
+ *
+ * The flow injects the resolver so Phase 4 stays decoupled from Phase 6's
+ * Run persistence refactor. Production wires the real Run store; tests stub.
+ */
+export interface RunStatusResolver {
+    /**
+     * Returns the reason the session has a non-terminal Run, or `null` when
+     * all Runs are terminal and the lock is allowed.
+     */
+    blockingRun(sessionId: SessionId, tenantId: TenantId): Promise<{
+        reason: 'active_run' | 'pending_hitl' | 'pending_subsession';
+    } | null>;
+}
+/** Null resolver — treats every session as unblocked. Used by tests that do not exercise Run fan-in. */
+export declare const NOOP_RUN_STATUS_RESOLVER: RunStatusResolver;
+export interface SingleHandoffDeps {
+    store: SessionStore;
+    workspaceRegistry: WorkspaceBackendRegistry;
+    capacity: CapacityValidator;
+    events: HandoffEventSink;
+    runStatus?: RunStatusResolver;
+    /**
+     * Gate the recipient-session creation on the Thread being `'open'`.
+     * Added in Phase 2.6 to mirror spawn — a handoff into an archived
+     * Thread would otherwise undermine `ThreadManager.archive`.
+     */
+    threadManager: ThreadManager;
+}
+/**
+ * Executes a single-recipient handoff against `deps.store`. Throws
+ * {@link HandoffLockRejected}, {@link HandoffVersionConflict},
+ * {@link TenantIsolationError}, or {@link DelegationCapacityExceeded} on
+ * invariant violations. Workspace provisioning failures surface as
+ * {@link WorkspaceBackendError} after the compensating revert.
+ */
+export declare function executeSingleHandoff(deps: SingleHandoffDeps, assignment: HandoffAssignment, tenantId: TenantId): Promise<HandoffOutcome>;
+//# sourceMappingURL=single.d.ts.map