@flyingrobots/graft 0.5.0 → 0.6.1

package/src/mcp/workspace-router-history.ts

@@ -0,0 +1,233 @@
+// ---------------------------------------------------------------------------
+// workspace-router-history — persisted local history query operations
+//
+// Pure functions that query and observe persisted local history state.
+// Extracted from WorkspaceRouter to separate history concerns from
+// workspace lifecycle orchestration.
+// ---------------------------------------------------------------------------
+import { buildRuntimeStagedTarget } from "./runtime-staged-target.js";
+import {
+  buildWorkspaceReadObservation,
+  type AttributedReadToolName,
+} from "./workspace-read-observation.js";
+import type {
+  PersistedLocalActivityWindow,
+  PersistedLocalHistoryStore,
+  RepoConcurrencySummary,
+  PersistedLocalHistorySummary,
+  PersistedLocalHistoryContext,
+} from "./persisted-local-history.js";
+import type { PersistedLocalHistoryGraphContext } from "./persisted-local-history-graph.js";
+import type { RepoObservation } from "./repo-state.js";
+import type { RuntimeCausalContext } from "./runtime-causal-context.js";
+import type {
+  WorkspaceExecutionContext,
+  WorkspaceStatus,
+} from "./workspace-router-model.js";
+import type { JsonObject } from "../contracts/json-object.js";
+import type { BoundWorkspace } from "./workspace-router-runtime.js";
+
+// ---------------------------------------------------------------------------
+// Unbound fallback — returned when no workspace is bound
+// ---------------------------------------------------------------------------
+
+export const UNBOUND_PERSISTED_LOCAL_HISTORY_SUMMARY: PersistedLocalHistorySummary = Object.freeze({
+  availability: "none",
+  persistence: "persisted_local_history",
+  historyPath: null,
+  totalContinuityRecords: 0,
+  active: false,
+  lastOperation: null,
+  lastObservedAt: null,
+  continuityKey: null,
+  causalSessionId: null,
+  strandId: null,
+  checkoutEpochId: null,
+  continuedFromCausalSessionId: null,
+  continuityConfidence: "unknown",
+  continuityEvidence: [],
+  attribution: Object.freeze({
+    actor: Object.freeze({
+      actorId: "unknown",
+      actorKind: "unknown",
+      displayName: "Unknown",
+      source: "persisted_local_history.fallback",
+      authorityScope: "inferred",
+    }),
+    confidence: "unknown",
+    basis: "unknown_fallback",
+    evidence: [],
+  }),
+  latestReadEvent: null,
+  latestStageEvent: null,
+  latestTransitionEvent: null,
+  preserves: Object.freeze([
+    "continuity_operations",
+    "read_events",
+    "stage_events",
+    "transition_events",
+    "runtime_context_ids",
+    "workspace_overlay_snapshots",
+  ]),
+  excludes: Object.freeze([
+    "raw_chat_transcripts",
+    "queue_bookkeeping",
+    "canonical_provenance",
+    "canonical_structural_truth",
+  ]),
+  nextAction: "bind_workspace_to_begin_local_history",
+} as PersistedLocalHistorySummary);
+
+export const UNBOUND_PERSISTED_LOCAL_ACTIVITY_WINDOW = Object.freeze({
+  historyPath: null,
+  totalMatchingItems: 0,
+  truncated: false,
+  items: Object.freeze([]),
+});
+
+// ---------------------------------------------------------------------------
+// History query functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Retrieve the persisted local history summary for a bound workspace,
+ * including side-effect observations for semantic transitions and staged targets.
+ */
+export async function queryPersistedLocalHistorySummary(input: {
+  readonly persistedLocalHistory: PersistedLocalHistoryStore;
+  readonly binding: BoundWorkspace;
+  readonly status: WorkspaceStatus;
+  readonly buildCausalContext: (
+    binding: BoundWorkspace,
+    observation: { readonly checkoutEpoch: number },
+  ) => RuntimeCausalContext;
+  readonly buildHistoryContext: (
+    binding: BoundWorkspace,
+    observation: RepoObservation,
+  ) => PersistedLocalHistoryContext;
+  readonly buildGraphContext: (
+    binding: BoundWorkspace,
+  ) => Promise<PersistedLocalHistoryGraphContext | null>;
+}): Promise<PersistedLocalHistorySummary> {
+  const { persistedLocalHistory, binding, status, buildCausalContext, buildHistoryContext, buildGraphContext } = input;
+  const repoState = binding.slice.repoState;
+  if (repoState === null) {
+    return UNBOUND_PERSISTED_LOCAL_HISTORY_SUMMARY;
+  }
+  const observation = repoState.getState();
+  const causalContext = buildCausalContext(binding, observation);
+  const graph = await buildGraphContext(binding);
+  let summary = await persistedLocalHistory.summarize(status, causalContext, graph);
+
+  if (observation.semanticTransition !== null) {
+    await persistedLocalHistory.noteSemanticTransitionObservation({
+      current: buildHistoryContext(binding, observation),
+      semanticTransition: observation.semanticTransition,
+      transition: observation.lastTransition,
+      attribution: summary.attribution,
+      graph,
+    });
+    summary = await persistedLocalHistory.summarize(status, causalContext, graph);
+  }
+
+  const stagedTarget = buildRuntimeStagedTarget(status, causalContext, observation, summary.attribution);
+
+  if (stagedTarget.availability === "full_file") {
+    await persistedLocalHistory.noteStageObservation({
+      current: buildHistoryContext(binding, observation),
+      stagedTarget,
+      attribution: summary.attribution,
+      graph,
+    });
+    return persistedLocalHistory.summarize(status, causalContext, graph);
+  }
+
+  return summary;
+}
+
+/**
+ * Retrieve the repo concurrency summary for a bound workspace.
+ */
+export async function queryRepoConcurrencySummary(input: {
+  readonly persistedLocalHistory: PersistedLocalHistoryStore;
+  readonly status: WorkspaceStatus;
+  readonly buildGraphContext: (
+    binding: BoundWorkspace,
+  ) => Promise<PersistedLocalHistoryGraphContext | null>;
+  readonly binding: BoundWorkspace;
+}): Promise<RepoConcurrencySummary | null> {
+  return input.persistedLocalHistory.summarizeRepoConcurrency(
+    input.status,
+    await input.buildGraphContext(input.binding),
+  );
+}
+
+/**
+ * Retrieve the persisted local activity window for a bound workspace.
+ */
+export async function queryPersistedLocalActivityWindow(input: {
+  readonly persistedLocalHistory: PersistedLocalHistoryStore;
+  readonly binding: BoundWorkspace;
+  readonly status: WorkspaceStatus;
+  readonly limit: number;
+  readonly buildCausalContext: (
+    binding: BoundWorkspace,
+    observation: { readonly checkoutEpoch: number },
+  ) => RuntimeCausalContext;
+  readonly buildGraphContext: (
+    binding: BoundWorkspace,
+  ) => Promise<PersistedLocalHistoryGraphContext | null>;
+  readonly refreshSummary: () => Promise<void>;
+}): Promise<PersistedLocalActivityWindow> {
+  const { persistedLocalHistory, binding, status, limit, buildCausalContext, buildGraphContext, refreshSummary } = input;
+  const repoState = binding.slice.repoState;
+  if (repoState === null) {
+    return { ...UNBOUND_PERSISTED_LOCAL_ACTIVITY_WINDOW, limit } as PersistedLocalActivityWindow;
+  }
+  await refreshSummary();
+  const observation = repoState.getState();
+  const causalContext = buildCausalContext(binding, observation);
+  const graph = await buildGraphContext(binding);
+  return persistedLocalHistory.listRecentActivity(status, causalContext, limit, graph);
+}
+
+/**
+ * Record a read observation against persisted local history.
+ */
+export async function noteReadObservation(input: {
+  readonly persistedLocalHistory: PersistedLocalHistoryStore;
+  readonly execution: WorkspaceExecutionContext;
+  readonly toolName: AttributedReadToolName;
+  readonly args: JsonObject;
+  readonly result: JsonObject;
+  readonly buildHistoryContextFromExecution: (
+    execution: WorkspaceExecutionContext,
+    observation: RepoObservation,
+  ) => PersistedLocalHistoryContext;
+  readonly buildGraphContextFromExecution: (
+    execution: WorkspaceExecutionContext,
+  ) => Promise<PersistedLocalHistoryGraphContext | null>;
+}): Promise<void> {
+  const {
+    persistedLocalHistory, execution, toolName, args, result,
+    buildHistoryContextFromExecution, buildGraphContextFromExecution,
+  } = input;
+
+  const readObservation = buildWorkspaceReadObservation(execution, toolName, args, result);
+  if (readObservation === null) {
+    return;
+  }
+
+  const summary = await persistedLocalHistory.summarize(
+    execution.status,
+    execution.getCausalContext(),
+    await buildGraphContextFromExecution(execution),
+  );
+
+  await persistedLocalHistory.noteReadObservation({
+    current: buildHistoryContextFromExecution(execution, execution.repoState.getState()),
+    attribution: summary.attribution,
+    graph: await buildGraphContextFromExecution(execution),
+    ...readObservation,
+  });
+}

package/src/mcp/workspace-router-model.ts

@@ -0,0 +1,131 @@
+import type { ObservationCache } from "./cache.js";
+import type { Metrics } from "./metrics.js";
+import type { RepoStateTracker } from "./repo-state.js";
+import type { RuntimeCausalContext } from "./runtime-causal-context.js";
+import type { PersistedLocalHistorySummary } from "./persisted-local-history.js";
+import type { GovernorTracker } from "../session/tracker.js";
+import type { WarpHandle } from "../ports/warp.js";
+
+export type WorkspaceMode = "repo_local" | "daemon";
+export type WorkspaceBindState = "bound" | "unbound";
+export type WorkspaceBindAction = "bind" | "rebind";
+
+export interface WorkspaceCapabilityProfile {
+  readonly boundedReads: boolean;
+  readonly structuralTools: boolean;
+  readonly precisionTools: boolean;
+  readonly stateBookmarks: boolean;
+  readonly runtimeLogs: "session_local_only";
+  readonly runCapture: boolean;
+}
+
+export interface WorkspaceStatus {
+  readonly sessionMode: WorkspaceMode;
+  readonly bindState: WorkspaceBindState;
+  readonly repoId: string | null;
+  readonly worktreeId: string | null;
+  readonly worktreeRoot: string | null;
+  readonly gitCommonDir: string | null;
+  readonly graftDir: string | null;
+  readonly capabilityProfile: WorkspaceCapabilityProfile | null;
+}
+
+export interface WorkspaceActionResult extends WorkspaceStatus {
+  readonly ok: boolean;
+  readonly action: WorkspaceBindAction;
+  readonly freshSessionSlice: boolean;
+  readonly errorCode?: string;
+  readonly error?: string;
+}
+
+export interface CausalAttachResult extends WorkspaceStatus {
+  readonly ok: boolean;
+  readonly action: "attach";
+  readonly persistedLocalHistory: PersistedLocalHistorySummary;
+  readonly errorCode?: string;
+  readonly error?: string;
+}
+
+export interface WorkspaceBindRequest {
+  readonly cwd: string;
+  readonly worktreeRoot?: string | undefined;
+  readonly gitCommonDir?: string | undefined;
+  readonly repoId?: string | undefined;
+}
+
+export class WorkspaceBindingRequiredError extends Error {
+  readonly code = "UNBOUND_WORKSPACE";
+
+  constructor(toolName: string) {
+    super(`Tool ${toolName} requires an active workspace binding. Call workspace_bind first.`);
+    this.name = "WorkspaceBindingRequiredError";
+  }
+}
+
+export class WorkspaceCapabilityDeniedError extends Error {
+  readonly code = "CAPABILITY_DENIED";
+
+  constructor(toolName: string) {
+    super(`Tool ${toolName} is not enabled in the daemon default capability profile.`);
+    this.name = "WorkspaceCapabilityDeniedError";
+  }
+}
+
+export interface WorkspaceExecutionContext {
+  readonly sliceId: string;
+  readonly repoId: string;
+  readonly worktreeId: string;
+  readonly projectRoot: string;
+  readonly worktreeRoot: string;
+  readonly gitCommonDir: string;
+  readonly graftignorePatterns: readonly string[];
+  readonly resolvePath: (input: string) => string;
+  readonly capabilityProfile: WorkspaceCapabilityProfile;
+  readonly warpWriterId: string;
+  getCausalContext(): RuntimeCausalContext;
+  readonly status: WorkspaceStatus;
+  readonly governor: GovernorTracker;
+  readonly cache: ObservationCache;
+  readonly metrics: Metrics;
+  readonly graftDir: string;
+  readonly repoState: RepoStateTracker;
+  readonly getWarp: () => Promise<WarpHandle>;
+}
+
+export interface ResolvedWorkspace {
+  readonly repoId: string;
+  readonly worktreeId: string;
+  readonly worktreeRoot: string;
+  readonly gitCommonDir: string;
+}
+
+export interface WorkspaceAuthorizationPolicy {
+  getCapabilityProfile(resolved: ResolvedWorkspace): Promise<WorkspaceCapabilityProfile | null>;
+  noteBound(resolved: ResolvedWorkspace): Promise<void>;
+}
+
+export interface WorkspaceSharedAttachPolicy {
+  resolveSharedAttachSource(input: {
+    readonly sessionId: string;
+    readonly repoId: string;
+    readonly worktreeId: string;
+  }): import("./persisted-local-history.js").PersistedLocalHistorySharedAttachSource | null;
+}
+
+export const DEFAULT_DAEMON_CAPABILITY_PROFILE: WorkspaceCapabilityProfile = Object.freeze({
+  boundedReads: true,
+  structuralTools: true,
+  precisionTools: true,
+  stateBookmarks: true,
+  runtimeLogs: "session_local_only",
+  runCapture: false,
+});
+
+export const DEFAULT_REPO_LOCAL_CAPABILITY_PROFILE: WorkspaceCapabilityProfile = Object.freeze({
+  boundedReads: true,
+  structuralTools: true,
+  precisionTools: true,
+  stateBookmarks: true,
+  runtimeLogs: "session_local_only",
+  runCapture: true,
+});

package/src/mcp/workspace-router-resolution.ts

@@ -0,0 +1,71 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { GitClient } from "../ports/git.js";
+import type { ResolvedWorkspace, WorkspaceBindRequest } from "./workspace-router-model.js";
+
+interface WorkspaceBindError {
+  readonly code: string;
+  readonly message: string;
+}
+
+export function stableWorkspaceId(prefix: string, input: string): string {
+  return `${prefix}:${crypto.createHash("sha256").update(input).digest("hex").slice(0, 16)}`;
+}
+
+async function readGitValue(git: GitClient, cwd: string, args: readonly string[]): Promise<string | null> {
+  const result = await git.run({ args, cwd });
+  if (result.error !== undefined || result.status !== 0) {
+    return null;
+  }
+  const trimmed = result.stdout.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function toAbsolutePath(base: string, value: string): string {
+  return path.isAbsolute(value) ? value : path.resolve(base, value);
+}
+
+/**
+ * Resolve symlinks to get the canonical filesystem path.
+ * Prevents identity drift from path aliases (e.g. /tmp vs /private/tmp on macOS).
+ * Falls back to the input path if realpath fails (e.g. path does not exist yet).
+ */
+function canonicalize(inputPath: string): string {
+  try {
+    return fs.realpathSync(inputPath);
+  } catch {
+    return inputPath;
+  }
+}
+
+export async function resolveWorkspaceRequest(
+  git: GitClient,
+  request: WorkspaceBindRequest,
+): Promise<ResolvedWorkspace | WorkspaceBindError> {
+  const cwd = path.resolve(request.cwd);
+  const worktreeRoot = await readGitValue(git, cwd, ["rev-parse", "--path-format=absolute", "--show-toplevel"]);
+  if (worktreeRoot === null) {
+    return {
+      code: "NOT_A_GIT_REPO",
+      message: `cwd is not inside a git worktree: ${cwd}`,
+    };
+  }
+
+  const rawGitCommonDir = await readGitValue(git, cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+  if (rawGitCommonDir === null) {
+    return {
+      code: "WORKSPACE_RESOLUTION_FAILED",
+      message: `Unable to resolve git common dir from ${cwd}`,
+    };
+  }
+
+  const gitCommonDir = canonicalize(toAbsolutePath(worktreeRoot, rawGitCommonDir));
+  const canonicalWorktreeRoot = canonicalize(worktreeRoot);
+  return {
+    repoId: stableWorkspaceId("repo", gitCommonDir),
+    worktreeId: stableWorkspaceId("worktree", canonicalWorktreeRoot),
+    worktreeRoot: canonicalWorktreeRoot,
+    gitCommonDir,
+  };
+}

package/src/mcp/workspace-router-runtime.ts

@@ -0,0 +1,243 @@
+import * as path from "node:path";
+import { createRepoPathResolver } from "../adapters/repo-paths.js";
+import type { FileSystem } from "../ports/filesystem.js";
+import type { GitClient } from "../ports/git.js";
+import type { WarpHandle } from "../ports/warp.js";
+import { DEFAULT_WARP_WRITER_ID } from "../warp/writer-id.js";
+import { GovernorTracker } from "../session/tracker.js";
+import { ObservationCache } from "./cache.js";
+import { Metrics } from "./metrics.js";
+import { loadProjectGraftignore } from "./policy.js";
+import {
+  type PersistedLocalHistoryContext,
+  type PersistedLocalHistoryStore,
+} from "./persisted-local-history.js";
+import type { PersistedLocalHistoryGraphContext } from "./persisted-local-history-graph.js";
+import { RepoStateTracker, type RepoObservation } from "./repo-state.js";
+import { buildRuntimeCausalContext, type RuntimeCausalContext } from "./runtime-causal-context.js";
+import {
+  buildRuntimeWorkspaceOverlayFooting,
+  type GitTransitionHookEvent,
+} from "./runtime-workspace-overlay.js";
+import type {
+  ResolvedWorkspace,
+  WorkspaceCapabilityProfile,
+  WorkspaceExecutionContext,
+  WorkspaceMode,
+  WorkspaceStatus,
+} from "./workspace-router-model.js";
+import type { WarpPool } from "./warp-pool.js";
+
+export interface WorkspaceSlice {
+  readonly sliceId: string;
+  readonly governor: GovernorTracker;
+  readonly cache: ObservationCache;
+  readonly metrics: Metrics;
+  readonly graftDir: string;
+  readonly repoState: RepoStateTracker | null;
+}
+
+export interface BoundWorkspace {
+  readonly repoId: string;
+  readonly worktreeId: string;
+  readonly worktreeRoot: string;
+  readonly gitCommonDir: string;
+  readonly graftignorePatterns: readonly string[];
+  readonly resolvePath: (input: string) => string;
+  readonly capabilityProfile: WorkspaceCapabilityProfile;
+  readonly warpWriterId: string;
+  readonly transportSessionId: string;
+  readonly slice: WorkspaceSlice;
+  readonly getWarp: () => Promise<WarpHandle>;
+}
+
+export function createWorkspaceSlice(input: {
+  readonly graftDir: string;
+  readonly projectRoot?: string;
+  readonly fs: FileSystem;
+  readonly git: GitClient;
+  readonly nextSliceId: string;
+}): WorkspaceSlice {
+  return {
+    sliceId: input.nextSliceId,
+    governor: new GovernorTracker(),
+    cache: new ObservationCache(),
+    metrics: new Metrics(),
+    graftDir: input.graftDir,
+    repoState: input.projectRoot !== undefined
+      ? new RepoStateTracker(input.projectRoot, input.fs, input.git)
+      : null,
+  };
+}
+
+export async function createBoundWorkspace(input: {
+  readonly resolved: ResolvedWorkspace;
+  readonly graftDir: string;
+  readonly capabilityProfile: WorkspaceCapabilityProfile;
+  readonly actionName?: string | undefined;
+  readonly slice: WorkspaceSlice;
+  readonly fs: FileSystem;
+  readonly transportSessionId: string;
+  readonly warpWriterId?: string | undefined;
+  readonly warpPool: WarpPool;
+}): Promise<BoundWorkspace> {
+  if (input.actionName !== undefined) {
+    input.slice.governor.recordMessage();
+    input.slice.governor.recordToolCall(input.actionName);
+  }
+
+  return {
+    ...input.resolved,
+    graftignorePatterns: await loadProjectGraftignore(input.fs, input.resolved.worktreeRoot),
+    resolvePath: createRepoPathResolver(input.resolved.worktreeRoot),
+    capabilityProfile: input.capabilityProfile,
+    transportSessionId: input.transportSessionId,
+    warpWriterId: input.warpWriterId ?? DEFAULT_WARP_WRITER_ID,
+    slice: input.slice,
+    getWarp: () => input.warpPool.getOrOpen(
+      input.resolved.repoId,
+      input.resolved.worktreeRoot,
+      input.warpWriterId ?? DEFAULT_WARP_WRITER_ID,
+    ),
+  };
+}
+
+export function buildWorkspaceCausalContext(
+  binding: BoundWorkspace,
+  observation: { readonly checkoutEpoch: number },
+): RuntimeCausalContext {
+  return buildRuntimeCausalContext({
+    transportSessionId: binding.transportSessionId,
+    workspaceSliceId: binding.slice.sliceId,
+    repoId: binding.repoId,
+    worktreeId: binding.worktreeId,
+    checkoutEpoch: observation.checkoutEpoch,
+    warpWriterId: binding.warpWriterId,
+  });
+}
+
+export function buildPersistedLocalHistoryContext(input: {
+  readonly persistedLocalHistory: PersistedLocalHistoryStore;
+  readonly mode: WorkspaceMode;
+  readonly binding: BoundWorkspace;
+  readonly observation: RepoObservation;
+  readonly hookEvent?: GitTransitionHookEvent | null;
+}): PersistedLocalHistoryContext {
+  const context = input.persistedLocalHistory.buildContext(
+    {
+      sessionMode: input.mode,
+      bindState: "bound",
+      repoId: input.binding.repoId,
+      worktreeId: input.binding.worktreeId,
+      worktreeRoot: input.binding.worktreeRoot,
+      gitCommonDir: input.binding.gitCommonDir,
+      graftDir: input.binding.slice.graftDir,
+      capabilityProfile: input.binding.capabilityProfile,
+    },
+    buildWorkspaceCausalContext(input.binding, input.observation),
+    input.observation,
+    input.hookEvent ?? null,
+  );
+  if (context === null) {
+    throw new Error("persisted local history context unavailable for bound workspace");
+  }
+  return context;
+}
+
+export function buildPersistedLocalHistoryContextFromExecution(input: {
+  readonly persistedLocalHistory: PersistedLocalHistoryStore;
+  readonly execution: WorkspaceExecutionContext;
+  readonly observation: RepoObservation;
+}): PersistedLocalHistoryContext {
+  const context = input.persistedLocalHistory.buildContext(
+    input.execution.status,
+    input.execution.getCausalContext(),
+    input.observation,
+  );
+  if (context === null) {
+    throw new Error("persisted local history context unavailable for execution");
+  }
+  return context;
+}
+
+export async function resolveCheckoutBoundaryHookEvent(input: {
+  readonly fs: FileSystem;
+  readonly git: GitClient;
+  readonly binding: BoundWorkspace;
+  readonly previousObservedAt: string;
+  readonly observation: RepoObservation;
+}): Promise<GitTransitionHookEvent | null> {
+  const footing = await buildRuntimeWorkspaceOverlayFooting(
+    input.fs,
+    input.git,
+    input.binding.worktreeRoot,
+    input.binding.gitCommonDir,
+    input.observation,
+  );
+  const latestHookEvent = footing.latestHookEvent;
+  if (latestHookEvent === null) {
+    return null;
+  }
+
+  const previousObservedAtMs = Date.parse(input.previousObservedAt);
+  const hookObservedAtMs = Date.parse(latestHookEvent.observedAt);
+  if (
+    Number.isFinite(previousObservedAtMs) &&
+    Number.isFinite(hookObservedAtMs) &&
+    hookObservedAtMs < previousObservedAtMs
+  ) {
+    return null;
+  }
+  return latestHookEvent;
+}
+
+export async function buildPersistedLocalHistoryGraphContext(
+  worktreeRoot: string,
+  getWarp: () => Promise<WarpHandle>,
+): Promise<PersistedLocalHistoryGraphContext | null> {
+  try {
+    return {
+      warp: await getWarp(),
+      worktreeRoot,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function boundWorkspaceStatus(
+  mode: WorkspaceMode,
+  binding: BoundWorkspace,
+): WorkspaceStatus {
+  return {
+    sessionMode: mode,
+    bindState: "bound",
+    repoId: binding.repoId,
+    worktreeId: binding.worktreeId,
+    worktreeRoot: binding.worktreeRoot,
+    gitCommonDir: binding.gitCommonDir,
+    graftDir: binding.slice.graftDir,
+    capabilityProfile: binding.capabilityProfile,
+  };
+}
+
+export function unboundWorkspaceStatus(mode: WorkspaceMode): WorkspaceStatus {
+  return {
+    sessionMode: mode,
+    bindState: "unbound",
+    repoId: null,
+    worktreeId: null,
+    worktreeRoot: null,
+    gitCommonDir: null,
+    graftDir: null,
+    capabilityProfile: null,
+  };
+}
+
+export function nextBindingSliceDir(graftDir: string, nextBindingCounter: number): string {
+  return path.join(
+    graftDir,
+    "bindings",
+    `slice-${String(nextBindingCounter).padStart(4, "0")}`,
+  );
+}