dsh-wsr-execution 0.0.1 → 0.1.0

package/src/client/delivery-inventory/LICENSE.upstream

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/client/delivery-inventory/UPSTREAM.md

@@ -0,0 +1,20 @@
+# Fixed Workspace UI fork provenance
+
+This feature is a composition fork of
+`@deepseek-ai/dsh-client-ui-workspace@0.1.1-rc.2`. It invokes that exact
+browser module while intercepting its single `sidebar.workspaces` registration
+so the WSR shell owns the slot and renders the unmodified `WorkspaceBrowser`
+component as a React child under Workspace. It performs no DOM reparenting.
+
+- Upstream repository: `https://github.com/deepseek-ai/deepseek-harness.git`
+- Upstream source directory: `packages/client/ui-workspace`
+- npm package: `@deepseek-ai/dsh-client-ui-workspace@0.1.1-rc.2`
+- npm tarball integrity: `sha512-k/jB5ke2e+oNyNKzu4/PBlriwCHKVg5bY3kn7Co3MtWZdqbJ42hfwZkRNMnn+nmziQXCVXWRzuiHZt0xNTAveA==`
+- Installed upstream `lib/client.js` SHA-256: `75d8a09a43a820e0ff8470e7b9c87b6dced523764ee650a8382317f6ef7a314b`
+- Installed upstream `package.json` SHA-256: `d8f1788dbd53719690bec6f236602a02aa1d213494e241c2aa8d645e4bf05706`
+- Installed upstream `LICENSE` SHA-256: `ebb4f09972aee8608be255debaf78451a68e95c290f55c240dec2ecfa16ea6be`
+- Upstream license: MIT; exact text is retained in `LICENSE.upstream`.
+
+The WSR composition and Delivery code are Apache-2.0. The upstream Workspace
+UI implementation remains MIT-licensed and is not copied into this directory.
+

package/src/client/delivery-inventory/model.js

@@ -0,0 +1,116 @@
+const CONTROL_PLANE_SCHEMA = "execution.delivery-control-plane@1.0.0";
+const LIFECYCLES = new Set([
+  "BOUND", "START_UNCERTAIN", "RUNNING_CORRELATED", "START_FAILED",
+  "RESULT_UNRESOLVED", "TERMINAL_HANDLING", "TERMINAL",
+]);
+const WORKSPACE_KEY = "wsr.sidebar.workspace.expanded.v1";
+const DELIVERY_KEY = "wsr.sidebar.delivery.expanded.v1";
+
+function errorView(label = "Delivery inventory unavailable") {
+  return Object.freeze({ kind: "error", role: "alert", label, rows: Object.freeze([]) });
+}
+
+function validString(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= 512;
+}
+
+function lifecycleLabel(delivery) {
+  if (delivery.lifecycle === "TERMINAL") return delivery.terminal?.outcome ?? "Terminal";
+  return delivery.lifecycle.toLowerCase().replaceAll("_", " ").replace(/^./u, (value) => value.toUpperCase());
+}
+
+function rowsFrom(deliveries, selectedSessionId) {
+  if (!Array.isArray(deliveries)) return undefined;
+  const identities = new Set();
+  const rows = [];
+  for (const delivery of deliveries) {
+    const sessionCorrelation = delivery?.navigation?.sessionCorrelation ?? null;
+    if (delivery === null || typeof delivery !== "object" || Array.isArray(delivery)
+      || !validString(delivery.deliveryId) || identities.has(delivery.deliveryId)
+      || !LIFECYCLES.has(delivery.lifecycle)
+      || typeof delivery.detached !== "boolean" || typeof delivery.recoverable !== "boolean"
+      || !validString(delivery.task?.identity)
+      || !(delivery.task.displayName === null || validString(delivery.task.displayName))
+      || !(sessionCorrelation === null || validString(sessionCorrelation))) return undefined;
+    identities.add(delivery.deliveryId);
+    rows.push(Object.freeze({
+      deliveryId: delivery.deliveryId,
+      label: delivery.task.displayName ?? delivery.task.identity,
+      statusLabel: lifecycleLabel(delivery),
+      sessionId: sessionCorrelation,
+      availability: sessionCorrelation !== null ? "bound" : delivery.recoverable ? "recoverable" : "detached",
+      selected: sessionCorrelation !== null && sessionCorrelation === selectedSessionId,
+    }));
+  }
+  rows.sort((left, right) => left.deliveryId.localeCompare(right.deliveryId));
+  return Object.freeze(rows);
+}
+
+/** Project only the formal Execution DeliveryControlPlaneSnapshot. */
+export function projectDeliveryInventory(state, { selectedSessionId } = {}) {
+  if (state?.kind === "loading") return Object.freeze({ kind: "loading", role: "status", label: "Loading Deliveries", rows: Object.freeze([]) });
+  if (state?.kind === "error") return errorView(validString(state.message) ? state.message : undefined);
+  if (!new Set(["ready", "reconnecting"]).has(state?.kind)) return errorView();
+  const snapshot = state.snapshot;
+  if (snapshot === null || typeof snapshot !== "object" || Array.isArray(snapshot)
+    || snapshot.schemaVersion !== CONTROL_PLANE_SCHEMA
+    || !Number.isSafeInteger(snapshot.generation) || snapshot.generation < 1) return errorView();
+  const rows = rowsFrom(snapshot.deliveries, selectedSessionId);
+  if (rows === undefined) return errorView();
+  if (state.kind === "reconnecting") return Object.freeze({ kind: "reconnecting", role: "status", label: "Reconnecting to Delivery inventory", rows });
+  if (rows.length === 0) return Object.freeze({ kind: "empty", role: "status", label: "No Deliveries", rows });
+  return Object.freeze({ kind: "ready", role: "list", label: "Deliveries", rows });
+}
+
+export function createDeliveryInventoryController(inventory) {
+  if (inventory === null || typeof inventory !== "object"
+    || typeof inventory.getSnapshot !== "function" || typeof inventory.subscribe !== "function") {
+    throw new TypeError("Execution inventory projection must be read-only and subscribable");
+  }
+  const controller = {
+    getSnapshot() {
+      try { return projectDeliveryInventory(inventory.getSnapshot()); }
+      catch { return errorView(); }
+    },
+    subscribe(listener) {
+      if (typeof listener !== "function") throw new TypeError("inventory listener must be a function");
+      const unsubscribe = inventory.subscribe(() => listener(controller.getSnapshot()));
+      if (typeof unsubscribe !== "function") throw new TypeError("inventory subscription must return an unsubscribe function");
+      return unsubscribe;
+    },
+  };
+  return Object.freeze(controller);
+}
+
+function persistedBoolean(value) {
+  return value === "false" ? false : true;
+}
+
+export function createMemoryCollapseStore(storage = {}) {
+  const listeners = new Set();
+  const read = typeof storage.read === "function" ? storage.read : () => undefined;
+  const write = typeof storage.write === "function" ? storage.write : () => undefined;
+  let snapshot;
+  try {
+    snapshot = Object.freeze({
+      workspaceExpanded: persistedBoolean(read(WORKSPACE_KEY)),
+      deliveryExpanded: persistedBoolean(read(DELIVERY_KEY)),
+    });
+  } catch {
+    snapshot = Object.freeze({ workspaceExpanded: true, deliveryExpanded: true });
+  }
+  const update = (name, key, value) => {
+    const next = Boolean(value);
+    if (snapshot[name] === next) return;
+    snapshot = Object.freeze({ ...snapshot, [name]: next });
+    try { write(key, String(next)); } catch { /* persistence denial is non-fatal */ }
+    for (const listener of listeners) listener();
+  };
+  return Object.freeze({
+    getSnapshot: () => snapshot,
+    subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+    setWorkspaceExpanded(value) { update("workspaceExpanded", WORKSPACE_KEY, value); },
+    setDeliveryExpanded(value) { update("deliveryExpanded", DELIVERY_KEY, value); },
+  });
+}
+

package/src/client/delivery-inventory/sidebar.js

@@ -0,0 +1,85 @@
+import { projectDeliveryInventory } from "./model.js";
+
+const STYLE_ID = "dsh-wsr-execution-delivery-inventory";
+const CSS = ".wsr-sidebar-resources{min-height:0;flex:1;display:flex;flex-direction:column;gap:4px}.wsr-sidebar-resource{min-height:0;display:flex;flex-direction:column}.wsr-sidebar-resource:first-child{flex:1}.wsr-sidebar-resource-header{box-sizing:border-box;width:100%;height:36px;cursor:pointer;color:var(--dsw-alias-label-tertiary);background:transparent;border:0;border-radius:8px;display:flex;align-items:center;gap:6px;padding:0 8px;font-size:13px;text-align:left}.wsr-sidebar-resource-header:hover{background:var(--dsw-alias-interactive-bg-hover)}.wsr-delivery-row{box-sizing:border-box;width:100%;height:32px;cursor:pointer;color:var(--dsw-alias-label-primary);background:transparent;border:0;border-radius:8px;display:flex;align-items:center;gap:6px;padding:0 8px;font-size:14px;line-height:20px;text-align:left}.wsr-delivery-row:hover,.wsr-delivery-row[aria-current=page]{background:var(--dsw-alias-interactive-bg-hover)}.wsr-delivery-row:disabled{cursor:default}.wsr-delivery-row>span:first-child{text-overflow:ellipsis;white-space:nowrap;min-width:0;overflow:hidden;flex:1}.wsr-delivery-status{color:var(--dsw-alias-label-tertiary);font-size:12px;line-height:20px}.wsr-delivery-status-recoverable{color:var(--dsw-alias-state-warning-primary)}";
+
+function installStyle() {
+  if (typeof document === "undefined" || document.getElementById(STYLE_ID) !== null) return;
+  const tag = document.createElement("style");
+  tag.id = STYLE_ID;
+  tag.dataset.plugin = "dsh-wsr-execution";
+  tag.textContent = CSS;
+  document.head.append(tag);
+}
+
+function persisted(key) {
+  try { return typeof localStorage === "undefined" || localStorage.getItem(key) !== "false"; }
+  catch { return true; }
+}
+
+function persist(key, value) {
+  try { if (typeof localStorage !== "undefined") localStorage.setItem(key, String(value)); }
+  catch { /* browser storage is optional */ }
+}
+
+export function createSidebarResources(React, WorkspaceBrowser, inventory) {
+  return function WsrSidebarResources(props) {
+    const [workspaceExpanded, setWorkspaceExpanded] = React.useState(() => persisted("wsr.sidebar.workspace.expanded.v1"));
+    const [deliveryExpanded, setDeliveryExpanded] = React.useState(() => persisted("wsr.sidebar.delivery.expanded.v1"));
+    const selectedSessionId = props.useSessions((state) => state.current);
+    const state = React.useSyncExternalStore(inventory.subscribe, inventory.getSnapshot, inventory.getSnapshot);
+    const view = React.useMemo(() => projectDeliveryInventory(state, { selectedSessionId }), [state, selectedSessionId]);
+    const toggle = (kind) => {
+      if (kind === "workspace") {
+        const next = !workspaceExpanded;
+        setWorkspaceExpanded(next);
+        persist("wsr.sidebar.workspace.expanded.v1", next);
+      } else {
+        const next = !deliveryExpanded;
+        setDeliveryExpanded(next);
+        persist("wsr.sidebar.delivery.expanded.v1", next);
+      }
+    };
+    const header = (id, label, expanded, kind) => React.createElement("button", {
+      type: "button", className: "wsr-sidebar-resource-header",
+      "aria-controls": id, "aria-expanded": expanded, onClick: () => toggle(kind),
+      onKeyDown: (event) => {
+        if (event.key !== "Enter" && event.key !== " ") return;
+        event.preventDefault();
+        toggle(kind);
+      },
+    }, React.createElement("span", { "aria-hidden": "true" }, expanded ? "▾" : "▸"), label);
+    return React.createElement("div", { className: "wsr-sidebar-resources", "data-wsr-sidebar-resources": "true" },
+      React.createElement("section", { className: "wsr-sidebar-resource", "aria-label": "Workspace" },
+        header("wsr-sidebar-workspace", "Workspace", workspaceExpanded, "workspace"),
+        workspaceExpanded && React.createElement("div", { id: "wsr-sidebar-workspace" }, React.createElement(WorkspaceBrowser, props))),
+      React.createElement("section", { className: "wsr-sidebar-resource", "aria-label": "Delivery" },
+        header("wsr-sidebar-delivery", "Delivery", deliveryExpanded, "delivery"),
+        deliveryExpanded && React.createElement("div", {
+          id: "wsr-sidebar-delivery", role: view.kind === "error" ? "alert" : "region", "aria-live": "polite",
+        }, view.kind === "ready"
+          ? React.createElement("div", { role: "list", "aria-label": "Deliveries" }, view.rows.map((row) => React.createElement("button", {
+              key: row.deliveryId, type: "button", role: "listitem", className: "wsr-delivery-row",
+              "aria-current": row.selected ? "page" : undefined,
+              "aria-label": `${row.label}, ${row.statusLabel}`,
+              disabled: row.sessionId === null,
+              onClick: row.sessionId === null ? undefined : () => props.open(row.sessionId),
+            }, React.createElement("span", null, row.label), React.createElement("span", {
+              className: `wsr-delivery-status wsr-delivery-status-${row.availability}`,
+            }, row.statusLabel))))
+          : React.createElement("div", { role: view.role }, view.label))));
+  };
+}
+
+/** Fixed-version Workspace UI composition fork; WSR owns the single slot. */
+export function applyDeliverySidebar(ctx, { React, workspaceUi, inventory }) {
+  installStyle();
+  const originalSlots = ctx.slots;
+  const slots = Object.create(originalSlots);
+  slots.register = (definition, component) => definition?.name === "sidebar.workspaces"
+    ? originalSlots.register(definition, createSidebarResources(React, component, inventory))
+    : originalSlots.register(definition, component);
+  slots.inject = (name, factory) => originalSlots.inject(name, factory);
+  const forked = new Proxy(ctx, { get(target, property) { return property === "slots" ? slots : Reflect.get(target, property); } });
+  return workspaceUi.apply(forked);
+}

package/src/host/delivery-control-plane.js

@@ -0,0 +1,132 @@
+const CHANNEL = "/wsr-execution";
+const ERROR_CODES = new Set([
+  "DELIVERY_PROJECTION_CORRUPT",
+  "DELIVERY_PROJECTION_STALE_BINDING",
+  "DELIVERY_PROJECTION_RECOVERY_MISMATCH",
+  "DELIVERY_PROJECTION_UNAVAILABLE",
+]);
+
+function assertReadModel(readModel) {
+  if (readModel === null || typeof readModel !== "object"
+    || typeof readModel.snapshot !== "function"
+    || typeof readModel.session !== "function"
+    || typeof readModel.subscribe !== "function") {
+    throw new TypeError("DELIVERY_CONTROL_PLANE_READ_MODEL_INVALID");
+  }
+}
+
+function errorResult(error) {
+  const code = typeof error?.code === "string" && ERROR_CODES.has(error.code)
+    ? error.code
+    : "DELIVERY_PROJECTION_UNAVAILABLE";
+  return Object.freeze({
+    ok: false,
+    error: Object.freeze({ code, message: "Delivery control plane unavailable" }),
+  });
+}
+
+function validSessionPayload(payload) {
+  return payload !== null && typeof payload === "object" && !Array.isArray(payload)
+    && Object.keys(payload).join(",") === "sessionCorrelation"
+    && typeof payload.sessionCorrelation === "string"
+    && payload.sessionCorrelation.length > 0
+    && payload.sessionCorrelation.length <= 512;
+}
+
+/**
+ * Bridge the Execution-owned async read model into a bounded DSH Host channel.
+ * The gateway retains owner snapshots verbatim and has no mutation operation.
+ */
+export async function createDeliveryControlPlaneGateway(readModel) {
+  assertReadModel(readModel);
+  let current;
+  let failure;
+  let closed = false;
+  const dispose = await readModel.subscribe(
+    (snapshot) => { if (!closed) { current = snapshot; failure = undefined; } },
+    (error) => { if (!closed) failure = errorResult(error); },
+  );
+  if (typeof dispose !== "function") throw new TypeError("DELIVERY_CONTROL_PLANE_SUBSCRIPTION_INVALID");
+
+  return Object.freeze({
+    async handle(endpoint, payload) {
+      if (closed) throw new TypeError("DELIVERY_CONTROL_PLANE_GATEWAY_CLOSED");
+      if (endpoint === "inventory/read") {
+        if (payload === null || typeof payload !== "object" || Array.isArray(payload) || Object.keys(payload).length !== 0) {
+          throw new TypeError("CONTROL_PLANE_RPC_INVALID");
+        }
+        if (failure !== undefined) return failure;
+        if (current === undefined) {
+          try { current = await readModel.snapshot(); }
+          catch (error) { return errorResult(error); }
+        }
+        return Object.freeze({ ok: true, value: current });
+      }
+      if (endpoint === "session/read") {
+        if (!validSessionPayload(payload)) throw new TypeError("CONTROL_PLANE_RPC_INVALID");
+        try { return Object.freeze({ ok: true, value: await readModel.session(payload.sessionCorrelation) }); }
+        catch (error) { return errorResult(error); }
+      }
+      throw new TypeError("CONTROL_PLANE_RPC_INVALID");
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      await dispose();
+    },
+  });
+}
+
+/** Map the owner correlation coordinate to the DSH Session id at the Host edge. */
+export function createDshSessionControlPlaneReadModel(readModel, bindings) {
+  assertReadModel(readModel);
+  if (typeof bindings?.list !== "function" || typeof bindings?.bySession !== "function") {
+    throw new TypeError("DSH_SESSION_BINDINGS_REQUIRED");
+  }
+  const mapSnapshot = async (snapshot) => {
+    const rows = await bindings.list();
+    const sessions = new Map(rows.map((binding) => [binding.correlation, binding.sessionKey]));
+    return Object.freeze({
+      ...snapshot,
+      deliveries: Object.freeze(snapshot.deliveries.map((delivery) => {
+        if (delivery.navigation === null) return delivery;
+        const sessionCorrelation = sessions.get(delivery.navigation.sessionCorrelation);
+        if (sessionCorrelation === undefined) throw Object.assign(new Error("DELIVERY_PROJECTION_STALE_BINDING"), { code: "DELIVERY_PROJECTION_STALE_BINDING" });
+        return Object.freeze({ ...delivery, navigation: Object.freeze({ sessionCorrelation }) });
+      })),
+    });
+  };
+  return Object.freeze({
+    async snapshot() { return mapSnapshot(await readModel.snapshot()); },
+    async session(sessionCorrelation) {
+      const binding = await bindings.bySession(sessionCorrelation);
+      if (binding === undefined) return Object.freeze({ kind: "UNBOUND", sessionCorrelation });
+      const view = await readModel.session(binding.correlation);
+      if (view.kind === "UNBOUND") return Object.freeze({ kind: "UNBOUND", sessionCorrelation });
+      return Object.freeze({
+        kind: "BOUND",
+        sessionCorrelation,
+        delivery: Object.freeze({ ...view.delivery, navigation: Object.freeze({ sessionCorrelation }) }),
+      });
+    },
+    async subscribe(listener, onError) {
+      return readModel.subscribe(
+        (snapshot) => { void mapSnapshot(snapshot).then(listener, onError); },
+        onError,
+      );
+    },
+  });
+}
+
+export async function registerDeliveryControlPlaneGateway(ctx, readModel) {
+  if (typeof ctx?.connection?.rpc?.handle !== "function") throw new TypeError("DSH_CONNECTION_RPC_REQUIRED");
+  const gateway = await createDeliveryControlPlaneGateway(readModel);
+  const unregister = ctx.connection.rpc.handle(CHANNEL, gateway.handle, { authority: "loopback" });
+  ctx.effect(function* deliveryControlPlaneGatewayLifecycle() {
+    yield async () => {
+      await unregister?.();
+      await gateway.close();
+    };
+  }, "wsr-execution: Delivery control plane read gateway");
+  return gateway;
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export * from "./host/delivery-control-plane.js";
+export * from "./intake/binding-repository.js";
+export * from "./intake/command.js";
+export * from "./intake/plugin.js";

package/src/intake/binding-repository.js

@@ -0,0 +1,171 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+
+export class IntakeBindingError extends Error {
+  constructor(code) {
+    super(code);
+    this.name = "IntakeBindingError";
+    this.code = code;
+  }
+}
+
+function exact(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).sort().join(",") !== "correlation,deliveryBindingIdentity,deliveryId,sessionKey,state,worktree"
+    || typeof value.sessionKey !== "string" || value.sessionKey.length === 0
+    || typeof value.correlation !== "string" || value.correlation.length === 0
+    || typeof value.deliveryId !== "string" || value.deliveryId.length === 0
+    || typeof value.deliveryBindingIdentity !== "string" || !/^sha256:[0-9a-f]{64}$/u.test(value.deliveryBindingIdentity)
+    || typeof value.worktree !== "string" || !isAbsolute(value.worktree)
+    || !["BOUND", "DETACHED"].includes(value.state)) {
+    throw new IntakeBindingError("INTAKE_BINDING_INVARIANT_VIOLATION");
+  }
+  return Object.freeze({
+    sessionKey: value.sessionKey,
+    correlation: value.correlation,
+    deliveryId: value.deliveryId,
+    deliveryBindingIdentity: value.deliveryBindingIdentity,
+    worktree: resolve(value.worktree),
+    state: value.state,
+  });
+}
+
+function legacy(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).sort().join(",") !== "correlation,deliveryId,sessionKey,state,worktree"
+    || typeof value.sessionKey !== "string" || value.sessionKey.length === 0
+    || typeof value.correlation !== "string" || value.correlation.length === 0
+    || typeof value.deliveryId !== "string" || value.deliveryId.length === 0
+    || typeof value.worktree !== "string" || !isAbsolute(value.worktree)
+    || !["BOUND", "DETACHED"].includes(value.state)) {
+    throw new IntakeBindingError("INTAKE_BINDING_INVARIANT_VIOLATION");
+  }
+  return Object.freeze({ ...value, worktree: resolve(value.worktree) });
+}
+
+function validate(bindings) {
+  const accepted = bindings.map(exact);
+  if (new Set(accepted.map((entry) => entry.sessionKey)).size !== accepted.length
+    || new Set(accepted.map((entry) => entry.correlation)).size !== accepted.length
+    || new Set(accepted.map((entry) => entry.deliveryId)).size !== accepted.length
+    || new Set(accepted.map((entry) => entry.deliveryBindingIdentity)).size !== accepted.length
+    || new Set(accepted.map((entry) => entry.worktree)).size !== accepted.length) {
+    throw new IntakeBindingError("INTAKE_BINDING_INVARIANT_VIOLATION");
+  }
+  return accepted;
+}
+
+export class IntakeSessionBindingRepository {
+  #bindings = [];
+  #started = false;
+  constructor(file) {
+    if (typeof file !== "string" || !isAbsolute(file)) throw new IntakeBindingError("INTAKE_BINDING_INVARIANT_VIOLATION");
+    this.file = resolve(file);
+  }
+
+  async start(inventory = []) {
+    if (this.#started) return;
+    try {
+      const document = JSON.parse(await readFile(this.file, "utf8"));
+      if (document === null || typeof document !== "object" || Array.isArray(document)
+        || Object.keys(document).sort().join(",") !== "bindings,schemaVersion" || !Array.isArray(document.bindings)
+        || !["execution.intake-bindings@1.0.0", "execution.intake-bindings@2.0.0"].includes(document.schemaVersion)) {
+        throw new IntakeBindingError("INTAKE_BINDING_INVARIANT_VIOLATION");
+      }
+      if (document.schemaVersion === "execution.intake-bindings@2.0.0") {
+        this.#bindings = validate(document.bindings);
+      } else {
+        if (!Array.isArray(inventory)) throw new IntakeBindingError("INTAKE_BINDING_INVARIANT_VIOLATION");
+        this.#bindings = validate(document.bindings.map((candidate) => {
+          const entry = legacy(candidate);
+          const matches = inventory.filter((item) => item !== null && typeof item === "object"
+            && item.deliveryId === entry.deliveryId && typeof item.worktree === "string" && isAbsolute(item.worktree)
+            && resolve(item.worktree) === entry.worktree
+            && typeof item.deliveryBindingIdentity === "string" && /^sha256:[0-9a-f]{64}$/u.test(item.deliveryBindingIdentity));
+          if (matches.length !== 1) throw new IntakeBindingError("INTAKE_BINDING_INVARIANT_VIOLATION");
+          return { ...entry, deliveryBindingIdentity: matches[0].deliveryBindingIdentity };
+        }));
+        await this.#persist();
+      }
+    } catch (cause) {
+      if (cause?.code !== "ENOENT") {
+        if (cause instanceof IntakeBindingError) throw cause;
+        throw new IntakeBindingError("INTAKE_BINDING_INVARIANT_VIOLATION");
+      }
+      this.#bindings = [];
+    }
+    this.#started = true;
+  }
+
+  async claim(input) {
+    this.#ready();
+    const candidate = exact({ ...input, state: "BOUND" });
+    const session = this.#bindings.find((entry) => entry.sessionKey === candidate.sessionKey);
+    if (session !== undefined) {
+      if (session.deliveryId === candidate.deliveryId && session.correlation === candidate.correlation
+        && session.worktree === candidate.worktree && session.deliveryBindingIdentity === candidate.deliveryBindingIdentity) return session;
+      if (session.state === "DETACHED" && session.deliveryId === candidate.deliveryId
+        && session.worktree === candidate.worktree && session.deliveryBindingIdentity === candidate.deliveryBindingIdentity) {
+        this.#bindings.splice(this.#bindings.indexOf(session), 1, candidate);
+        await this.#persist();
+        return candidate;
+      }
+      throw new IntakeBindingError("SESSION_INTAKE_BOUND");
+    }
+    const delivery = this.#bindings.find((entry) => entry.deliveryId === candidate.deliveryId);
+    if (delivery?.state === "BOUND") throw new IntakeBindingError("DELIVERY_INTAKE_BOUND");
+    if (delivery?.state === "DETACHED") {
+      if (delivery.worktree !== candidate.worktree || delivery.deliveryBindingIdentity !== candidate.deliveryBindingIdentity) {
+        throw new IntakeBindingError("INTAKE_BINDING_INVARIANT_VIOLATION");
+      }
+      this.#bindings.splice(this.#bindings.indexOf(delivery), 1, candidate);
+    }
+    else this.#bindings.push(candidate);
+    await this.#persist();
+    return candidate;
+  }
+
+  async bySession(sessionKey) {
+    this.#ready();
+    return this.#bindings.find((entry) => entry.sessionKey === sessionKey);
+  }
+
+  async byDelivery(deliveryId) {
+    this.#ready();
+    return this.#bindings.find((entry) => entry.deliveryId === deliveryId);
+  }
+
+  async list() {
+    this.#ready();
+    return Object.freeze([...this.#bindings]);
+  }
+
+  async markDetached(deliveryId) {
+    this.#ready();
+    const index = this.#bindings.findIndex((entry) => entry.deliveryId === deliveryId);
+    if (index === -1 || this.#bindings[index].state === "DETACHED") return;
+    this.#bindings.splice(index, 1, Object.freeze({ ...this.#bindings[index], state: "DETACHED" }));
+    await this.#persist();
+  }
+
+  async detach(deliveryId) {
+    this.#ready();
+    const index = this.#bindings.findIndex((entry) => entry.deliveryId === deliveryId);
+    if (index === -1) return;
+    this.#bindings.splice(index, 1);
+    await this.#persist();
+  }
+
+  #ready() {
+    if (!this.#started) throw new IntakeBindingError("INTAKE_BINDING_INVARIANT_VIOLATION");
+  }
+
+  async #persist() {
+    await mkdir(dirname(this.file), { recursive: true, mode: 0o700 });
+    const temporary = `${this.file}.${randomUUID()}.tmp`;
+    const document = { schemaVersion: "execution.intake-bindings@2.0.0", bindings: this.#bindings };
+    await writeFile(temporary, `${JSON.stringify(document)}\n`, { flag: "wx", mode: 0o600 });
+    await rename(temporary, this.file);
+  }
+}

package/src/intake/command.js

@@ -0,0 +1,44 @@
+function invalid() {
+  throw new TypeError("WSR_COMMAND_INVALID");
+}
+
+function split(value) {
+  if (typeof value !== "string" || value.includes("\0")) invalid();
+  const normalized = value.startsWith(" ") ? value.slice(1) : value;
+  const lineEnd = normalized.indexOf("\n");
+  const line = (lineEnd === -1 ? normalized : normalized.slice(0, lineEnd)).trimEnd();
+  const remainder = lineEnd === -1 ? undefined : normalized.slice(lineEnd + 1);
+  return { line, remainder };
+}
+
+export function parseWsrCommand(value) {
+  const { line, remainder } = split(value);
+  if (line === "list") {
+    if (remainder !== undefined) invalid();
+    return Object.freeze({ operation: "list" });
+  }
+  if (line === "recover") return Object.freeze({ operation: "recover" });
+  if (line.startsWith("recover ")) {
+    const deliveryId = line.slice(8);
+    if (deliveryId.length === 0 || deliveryId.includes(" ") || remainder !== undefined) invalid();
+    return Object.freeze({ operation: "recover", deliveryId });
+  }
+  if (line === "status") return Object.freeze({ operation: "status" });
+  if (line.startsWith("status ")) {
+    const deliveryId = line.slice(7);
+    if (deliveryId.length === 0 || deliveryId.includes(" ") || remainder !== undefined) invalid();
+    return Object.freeze({ operation: "status", deliveryId });
+  }
+  if (line === "action finish") return Object.freeze({ operation: "action-finish", ...(remainder === undefined ? {} : { remainder }) });
+  if (line.startsWith("abandon ")) {
+    const deliveryId = line.slice(8);
+    if (deliveryId.length === 0 || deliveryId.includes(" ") || remainder !== undefined) invalid();
+    return Object.freeze({ operation: "abandon", deliveryId });
+  }
+  if (line.startsWith("create ")) {
+    const selector = line.slice(7);
+    if (selector.length === 0 || selector.includes(" ") || selector.startsWith("-") || selector.includes("--intent")) invalid();
+    return Object.freeze({ operation: "create", selector, directive: `/wsr create ${selector}`, ...(remainder === undefined ? {} : { remainder }) });
+  }
+  return invalid();
+}