mixdog 1.4.1 → 1.4.3

package/src/session-runtime/workflow-agents-api/agent-connectors.mjs

@@ -4,6 +4,9 @@ import {
   assertConnectorPolicyNotWidened,
   CONNECTOR_PERMISSIONS,
   connectorEnabled,
+  connectorGroupId,
+  connectorToolEntries,
+  connectorToolPermission,
   DENY_ALL_CONNECTORS,
   migrateLegacyConnectorPolicy,
   NO_WIDEN_MESSAGE,
@@ -108,8 +111,8 @@ export function createAgentConnectorsApi(deps, editor) {
     return getAgentConnectors(agentId);
   }
 
-  // Older per-tool overrides keep working (the profile no longer shows them):
-  // `permission` null drops the tool's entry, so the tool is auto again.
+  // One tool's permission (the profile's tool list, getAgentConnectorTools):
+  // `permission` null drops the tool's entry, so the tool is on its default again.
   async function setAgentConnectorToolPermission(agentId, connectorId, toolName, permission, options) {
     if (permission != null && !CONNECTOR_PERMISSIONS.includes(permission)) {
       throw new Error(`permission must be one of ${CONNECTOR_PERMISSIONS.join(', ')}`);
@@ -117,19 +120,25 @@ export function createAgentConnectorsApi(deps, editor) {
     const server = requireId(connectorId, 'connector id');
     const tool = requireId(toolName, 'tool name');
     const policy = editablePolicy(agentId);
-    const own = { ...policy.tools[server] };
+    // The accounts of one connector (`gmail`, `gmail-2`…) share the permission,
+    // stored once under the connector's id; an entry an account kept of its own
+    // for this tool goes in the same write.
+    const group = connectorGroupId(server);
+    const tools = Object.fromEntries(
+      Object.entries(policy.tools).map(([id, entries]) => {
+        if (id === group || connectorGroupId(id) !== group) return [id, entries];
+        const { [tool]: _dropped, ...rest } = entries;
+        return [id, rest];
+      })
+    );
+    const own = { ...tools[group] };
     if (permission == null) delete own[tool];
     else own[tool] = permission;
+    tools[group] = own;
     if (options?.noWiden) {
-      assertConnectorPolicyNotWidened(editor.getAgentConnectorPolicy(agentId), {
-        off: policy.off,
-        tools: { ...policy.tools, [server]: own },
-      });
+      assertConnectorPolicyNotWidened(editor.getAgentConnectorPolicy(agentId), { off: policy.off, tools });
     }
-    return editor.setAgentConnectorPolicy(
-      agentId,
-      storedConnectorPolicy({ off: policy.off, tools: { ...policy.tools, [server]: own } })
-    );
+    return editor.setAgentConnectorPolicy(agentId, storedConnectorPolicy({ off: policy.off, tools }));
   }
 
   // A card's "항상 허용" for a connector tool saves through this same writer.
@@ -149,6 +158,31 @@ export function createAgentConnectorsApi(deps, editor) {
       .sort((a, b) => a.connector.localeCompare(b.connector) || a.tool.localeCompare(b.tool));
   }
 
+  /** `[{ connector, tool, permission, explicit }]`: each installed connector's
+   *  tools (the connected server's own, and any the agent's policy names) with
+   *  the permission the agent has for the tool itself, so a connector switched
+   *  off does not change it, and whether that is an entry of its own policy
+   *  rather than the tool's default. The profile's per-tool editor reads it. */
+  function getAgentConnectorTools(agentId) {
+    const { tools } = editablePolicy(agentId);
+    return installedIds().flatMap((connector) => {
+      const group = connectorGroupId(connector);
+      const accounts = Object.entries(tools).filter(([id]) => connectorGroupId(id) === group);
+      const names = new Set([
+        ...listConnectorTools(connector).map(({ name }) => name),
+        ...accounts.flatMap(([, entries]) => Object.keys(entries)),
+      ]);
+      // Accounts share one permission (stored under the connector); entries an
+      // account kept of its own follow the topmost.
+      return [...names].map((tool) => ({
+        connector,
+        tool,
+        permission: connectorToolPermission({ off: [], tools }, { mcpServerName: connector, mcpToolName: tool }),
+        explicit: connectorToolEntries(tools, group, tool).length > 0,
+      }));
+    });
+  }
+
   /** Replace the agent's connector policy (null removes it). With `options.noWiden`
    *  the replacement may not give any tool more authority than the stored policy. */
   async function setAgentConnectors(agentId, connectors, options) {
@@ -279,6 +313,7 @@ export function createAgentConnectorsApi(deps, editor) {
     setAgentConnectorEnabled,
     setAgentConnectorToolPermission,
     getAgentAlwaysAllowedTools,
+    getAgentConnectorTools,
     getProjectConnectors,
     setProjectConnectorEnabled,
     migrateConnectorPolicies,

package/src/session-runtime/workflow-agents-api/agent-route.mjs

@@ -226,5 +226,7 @@ export function createAgentRouteApi(deps) {
     return stayOff ? { ...routeToSave, id, disabled: true } : routeToSave;
   }
 
+  // Explore's route decides whether the explore tool exists; sessions take a
+  // change of it at their next turn start (reconcileTurnSettings).
   return { setAgentRoute };
 }

package/src/session-runtime/workflow-agents-api/instruction-files.mjs

@@ -0,0 +1,165 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { writeFileAtomicSync } from '../../runtime/shared/atomic-file.mjs';
+import { normalizeText } from '../../runtime/shared/shipped-definitions.mjs';
+import { decodeInstructionFile, INSTRUCTION_FILE_MAX_BYTES } from '../../lib/instruction-text.cjs';
+import { outputStyleMetaFromMarkdown } from '../../lib/output-style-meta.cjs';
+import {
+  readInstructionFile,
+  shippedOrchestrationPath,
+  userOrchestrationPath,
+} from '../../runtime/agent/orchestrator/runtime-core/orchestration.mjs';
+import { ORCHESTRATION_MODES } from '../../runtime/shared/orchestration.mjs';
+import { publishAgentProfileChange } from '../agent-profile-changes.mjs';
+import { STANDALONE_ROOT } from '../runtime-paths.mjs';
+import { resolveDataDir } from './shared.mjs';
+
+// The editable instruction texts: the four orchestration modes (delegation)
+// and the four output-style depth levels. Each has a shipped .md file and a
+// same-name user file in the data dir that replaces it; the set is fixed.
+export const INSTRUCTION_FILE_CONFLICT = 'INSTRUCTION_FILE_CONFLICT';
+
+const MODE_LABELS = { none: 'Solo', focused: 'Focused', balanced: 'Balanced', swarm: 'Swarm' };
+const STYLES = [
+  ['detailed', 'Detailed'],
+  ['simple', 'Simple'],
+  ['minimal', 'Minimal'],
+  ['extreme-minimal', 'Extreme Minimal'],
+];
+const INSTRUCTION_GROUPS = Object.freeze(['delegation', 'outputStyle']);
+
+const FRONTMATTER = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;
+const bodyOfStyle = (text) =>
+  String(text || '')
+    .replace(FRONTMATTER, '')
+    .trim();
+const hashOf = (text) => createHash('sha256').update(String(text)).digest('hex').slice(0, 24);
+
+// One item's files and the text <-> file mapping. The style editor shows and
+// saves the file's body only: the shipped front matter (name, title,
+// description) is kept, and common.md is not part of it.
+function itemFor(group, id, deps) {
+  if (group === 'delegation') {
+    if (!ORCHESTRATION_MODES.includes(id))
+      throw new Error(`orchestration mode must be one of ${ORCHESTRATION_MODES.join(', ')}`);
+    return {
+      group,
+      id,
+      label: MODE_LABELS[id],
+      shipped: shippedOrchestrationPath(id),
+      user: userOrchestrationPath(id),
+      body: (text) => text,
+      file: (body) => `${body}\n`,
+      accepts: () => true,
+    };
+  }
+  if (group === 'outputStyle') {
+    const style = STYLES.find(([styleId]) => styleId === id);
+    if (!style) throw new Error(`output style must be one of ${STYLES.map(([styleId]) => styleId).join(', ')}`);
+    const shipped = join(deps.rootDir ?? STANDALONE_ROOT, 'output-styles', `${id}.md`);
+    return {
+      group,
+      id,
+      label: style[1],
+      shipped,
+      user: join(resolveDataDir(deps), 'output-styles', `${id}.md`),
+      body: bodyOfStyle,
+      file: (body, shippedText) => `${(FRONTMATTER.exec(shippedText) || [''])[0].trimEnd()}\n\n${body}\n`,
+      // A file whose front matter names another style defines that one instead
+      // (the prompt builder registers it by name): it does not replace this one.
+      accepts: (text) => outputStyleMetaFromMarkdown(text, `${id}.md`)?.id === id,
+    };
+  }
+  throw new Error(`instruction group must be one of ${INSTRUCTION_GROUPS.join(', ')}`);
+}
+
+export function createInstructionFilesApi(deps) {
+  function stateOf(item) {
+    const shipped = readInstructionFile(item.shipped);
+    const defaultBody = item.body(shipped?.text ?? '');
+    const user = readInstructionFile(item.user);
+    const accepted = Boolean(user?.text) && item.accepts(user.text);
+    const userBody = accepted ? item.body(user.text) : '';
+    // An existing user file that cannot serve (empty, too large, not text, a
+    // style under another name) is passed over by the prompt builders: the
+    // built-in applies.
+    const usable = Boolean(userBody);
+    const problem = user && !usable ? (user.problem ?? (accepted ? 'empty' : 'invalid')) : undefined;
+    const body = usable ? userBody : defaultBody;
+    return {
+      group: item.group,
+      id: item.id,
+      label: item.label,
+      body,
+      defaultBody,
+      userOverride: Boolean(user),
+      modified: usable && normalizeText(userBody) !== normalizeText(defaultBody),
+      ...(problem ? { problem } : {}),
+      ...(user ? { path: item.user } : {}),
+      revision: hashOf(`${usable ? 'user' : 'default'}\0${problem ?? ''}\0${body}`),
+    };
+  }
+
+  // A write or reset made against a state that has moved on is refused.
+  function assertCurrent(payloadRevision, before, item) {
+    if (payloadRevision === undefined || String(payloadRevision) === before.revision) return;
+    const conflict = new Error(`${INSTRUCTION_FILE_CONFLICT}: "${item.id}" changed since it was loaded`);
+    conflict.code = INSTRUCTION_FILE_CONFLICT;
+    throw conflict;
+  }
+
+  const get = (group, id) => stateOf(itemFor(group, id, deps));
+
+  function list() {
+    return [...ORCHESTRATION_MODES.map((id) => get('delegation', id)), ...STYLES.map(([id]) => get('outputStyle', id))];
+  }
+
+  async function announce() {
+    deps.invalidateContextStatusCache?.();
+    await publishAgentProfileChange();
+  }
+
+  async function save(payload = {}) {
+    const item = itemFor(payload.group, payload.id, deps);
+    const body = String(payload.body ?? '')
+      .replace(/\r\n/g, '\n')
+      .trim();
+    if (!body) throw new Error('instruction text must not be empty');
+    if (body.includes('\0')) throw new Error('instruction text must be plain text');
+    const before = stateOf(item);
+    assertCurrent(payload.expectedRevision, before, item);
+    if (normalizeText(body) === normalizeText(before.defaultBody)) {
+      // Equal to the shipped text: keep no copy, so it follows the shipped version.
+      rmSync(item.user, { force: true });
+    } else {
+      // The bytes that reach the disk — front matter and newline included —
+      // must pass the reader's check, or the saved file would be ignored.
+      const bytes = Buffer.from(item.file(body, readInstructionFile(item.shipped)?.text ?? ''));
+      if (bytes.length > INSTRUCTION_FILE_MAX_BYTES) throw new Error('instruction text is larger than 256 KB');
+      const problem = decodeInstructionFile(bytes).problem;
+      if (problem) throw new Error(`instruction text cannot be saved (${problem})`);
+      mkdirSync(dirname(item.user), { recursive: true });
+      writeFileAtomicSync(item.user, bytes, { backup: true, mode: 0o644 });
+    }
+    await announce();
+    return stateOf(item);
+  }
+
+  async function reset(group, id, expectedRevision) {
+    const item = itemFor(group, id, deps);
+    if (!existsSync(item.user)) throw new Error(`"${item.id}" has no user override to reset`);
+    assertCurrent(expectedRevision, stateOf(item), item);
+    rmSync(item.user, { force: true });
+    rmSync(`${item.user}.bak`, { force: true });
+    await announce();
+    return stateOf(item);
+  }
+
+  return {
+    listInstructionFiles: list,
+    getInstructionFile: get,
+    saveInstructionFile: save,
+    resetInstructionFile: reset,
+  };
+}

package/src/session-runtime/workflow-agents-api/style-and-mode.mjs

@@ -30,7 +30,9 @@ export function createStyleAndModeApi(deps) {
     scheduleOutputStyleSave(selected.id);
     const freshStatus = { configured: selected.id, current: selected, styles: before.styles };
     seedOutputStyleStatusCache(freshStatus);
-    const appliedToCurrentSession = !getSession()?.id;
+    // An empty session is rebuilt at its next turn start; a conversation is
+    // told then and folds the style in at its next cold point.
+    const appliedToCurrentSession = deps.settingsReachCurrentSession?.() ?? !getSession()?.id;
     invalidateContextStatusCache();
     return { ...freshStatus, appliedToCurrentSession };
   }
@@ -53,10 +55,9 @@ export function createStyleAndModeApi(deps) {
       }
     }
     saveConfigAndAdopt({ ...getConfig(), orchestrationMode: mode });
-    const applied = await deps.refreshEmptySessionToolPolicy?.();
-    deps.invalidatePreSessionToolSurface?.();
+    // An empty session takes it at its next turn start (reconcileTurnSettings).
     invalidateContextStatusCache();
-    return { mode, appliedToCurrentSession: applied?.appliedToCurrentSession !== false };
+    return { mode, appliedToCurrentSession: deps.settingsReachCurrentSession?.() !== false };
   }
 
   return {

package/src/session-runtime/workflow-agents-api/workflow-packs.mjs

@@ -66,9 +66,8 @@ export function createWorkflowPacksApi(deps) {
       if (switched) return { ...switched.workflow, ...switched };
     }
     saveActiveWorkflow(id);
-    const applied = await deps.refreshEmptySessionToolPolicy?.();
-    deps.invalidatePreSessionToolSurface?.();
-    return { ...workflowSummary(pack), appliedToCurrentSession: applied?.appliedToCurrentSession !== false };
+    // An empty session takes it at its next turn start (reconcileTurnSettings).
+    return { ...workflowSummary(pack), appliedToCurrentSession: deps.settingsReachCurrentSession?.() !== false };
   }
 
   function getWorkflowPack(workflowId) {

package/src/session-runtime/workflow-agents-api.mjs

@@ -4,6 +4,7 @@ import { createAgentConnectorsApi } from './workflow-agents-api/agent-connectors
 import { createAgentRouteApi } from './workflow-agents-api/agent-route.mjs';
 import { createWorkflowPacksApi } from './workflow-agents-api/workflow-packs.mjs';
 import { createStyleAndModeApi } from './workflow-agents-api/style-and-mode.mjs';
+import { createInstructionFilesApi } from './workflow-agents-api/instruction-files.mjs';
 
 // Onboarding + agents/workflows/output-style selection surface. Stateless
 // helpers are imported by the phase modules under workflow-agents-api/; the
@@ -20,5 +21,6 @@ export function createWorkflowAgentsApi(deps) {
     ...routeApi,
     ...createWorkflowPacksApi(deps),
     ...createStyleAndModeApi(deps),
+    ...createInstructionFilesApi(deps),
   };
 }

package/src/session-runtime/workspace/activity-guards.mjs

@@ -0,0 +1,176 @@
+/**
+ * The activity checks every workspace change runs first: whether the hosted
+ * Lead (its turn, workers and background shells) is idle, and whether other
+ * sessions work in a shared checkout — then holding that checkout so new
+ * turns there wait until the change settles (admission gate).
+ */
+import { worktreeError, worktreeRefusal } from '../../runtime/shared/worktrees/contract.mjs';
+import { isWithin } from '../../runtime/shared/worktrees/paths.mjs';
+import {
+  holdWorkspaceActivity,
+  isExternalCheckout,
+  releaseAll,
+} from '../../runtime/shared/worktrees/activity-gate.mjs';
+import { AGENT_OWNER } from '../../runtime/agent/orchestrator/agent-owner.mjs';
+import { holdCheckoutFolder } from './admission-gate.mjs';
+
+const ACTIVE_STAGES = new Set(['connecting', 'requesting', 'streaming', 'tool_running', 'running', 'cancelling']);
+const BUSY_WORKER_STATES = new Set([...ACTIVE_STAGES, 'starting', 'spawning', 'queued', 'pending']);
+const BUSY_JOB_STATES = new Set(['starting', 'spawning', 'queued', 'pending', 'running']);
+
+const lower = (value) => String(value || '').toLowerCase();
+
+/** @param {object} deps The activity sources of createWorkspaceTransitions. */
+export function createActivityGuards({
+  getActiveTurnCount,
+  agentStatusState,
+  countOwnShellJobs,
+  listLiveSessions,
+  sessionManager,
+  listWorkspaceConsumers,
+  listWorkspaceJobs,
+}) {
+  function isSessionActive(session) {
+    const runtime = sessionManager?.getSessionRuntime?.(session.id);
+    if (runtime?.controller?.signal && !runtime.controller.signal.aborted) return true;
+    return ACTIVE_STAGES.has(lower(runtime?.stage || session.status));
+  }
+
+  const workersOf = (session) =>
+    listLiveSessions().filter(
+      (candidate) =>
+        candidate?.id &&
+        candidate.id !== session.id &&
+        candidate.owner === AGENT_OWNER &&
+        candidate.closed !== true &&
+        (candidate.ownerSessionId === session.id || candidate.parentSessionId === session.id)
+    );
+
+  /**
+   * WORKTREE_BUSY_JOBS while this Lead has a turn, workers or background
+   * shells running (`shellJobs: false` tolerates background shells).
+   */
+  async function assertLeadIdle(session, { ownTurn = false, shellJobs: checkShellJobs = true } = {}) {
+    if (!ownTurn && getActiveTurnCount() > 0) {
+      throw worktreeError('WORKTREE_BUSY_JOBS', 'The session is running a turn; wait for it to finish.', {
+        reason: 'turn',
+      });
+    }
+    const status = agentStatusState?.() || {};
+    const workers = Array.isArray(status.agentWorkers) ? status.agentWorkers : [];
+    const jobs = Array.isArray(status.agentJobs) ? status.agentJobs : [];
+    const busyWorkers = workers.filter(
+      (row) => BUSY_WORKER_STATES.has(lower(row?.status)) || BUSY_WORKER_STATES.has(lower(row?.stage))
+    ).length;
+    const busyJobs = jobs.filter((row) => BUSY_JOB_STATES.has(lower(row?.status))).length;
+    if (busyWorkers || busyJobs) {
+      throw worktreeError('WORKTREE_BUSY_JOBS', undefined, { reason: 'workers', workers: busyWorkers, jobs: busyJobs });
+    }
+    if (!checkShellJobs) return;
+    const ids = new Set([session.id, ...workers.map((row) => row?.sessionId).filter(Boolean)]);
+    for (const worker of workersOf(session)) ids.add(worker.id);
+    const shellJobs = await countOwnShellJobs([...ids]);
+    if (shellJobs > 0) throw worktreeError('WORKTREE_BUSY_JOBS', undefined, { reason: 'shell-jobs', shellJobs });
+  }
+
+  /**
+   * A checkout or merge in the shared checkout `folder` refuses while another
+   * session (not this Lead's own workers) works there, then holds the folder
+   * until the returned release: other sessions' turns that arrive meanwhile
+   * wait (admission gate). `sessionId` null: a session-less (draft) change.
+   * @returns {() => void}
+   */
+  function holdProjectFolder(sessionId, folder, { hold = true } = {}) {
+    const users = listLiveSessions().filter(
+      (candidate) =>
+        candidate?.id &&
+        candidate.id !== sessionId &&
+        candidate.closed !== true &&
+        (!sessionId || (candidate.ownerSessionId !== sessionId && candidate.parentSessionId !== sessionId)) &&
+        typeof candidate.cwd === 'string' &&
+        isWithin(folder, candidate.cwd) &&
+        isSessionActive(candidate)
+    );
+    if (users.length) throw worktreeRefusal('folder-in-use', { sessions: users.map((candidate) => candidate.id) });
+    return holdCheckoutFolder(sessionId, folder, { hold });
+  }
+
+  /** Run `fn` holding the checkout `folder` (holdProjectFolder); released when it settles. */
+  async function withProjectFolder(sessionId, folder, fn) {
+    const release = holdProjectFolder(sessionId, folder);
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+
+  /**
+   * Before a carry clears the shared checkout `folder` (held by the caller,
+   * so no new turn starts there): WORKTREE_BUSY_JOBS while any other session
+   * working in it — idle or not, this Lead's workers included — owns a
+   * running background shell (holdProjectFolder already refused running
+   * turns and agents there, assertLeadIdle this Lead's own). Processes
+   * outside Mixdog (editors, watchers) cannot be excluded.
+   */
+  async function assertCheckoutQuiet(session, folder) {
+    const sharing = listLiveSessions()
+      .filter(
+        (candidate) =>
+          candidate?.id &&
+          candidate.id !== session.id &&
+          candidate.closed !== true &&
+          typeof candidate.cwd === 'string' &&
+          isWithin(folder, candidate.cwd)
+      )
+      .map((candidate) => candidate.id);
+    if (!sharing.length) return;
+    const shellJobs = await countOwnShellJobs(sharing);
+    if (shellJobs > 0) throw worktreeRefusal('folder-shell-jobs', { shellJobs });
+  }
+
+  /**
+   * The shared admission of every merge and folder cleanup (manageProjectBranch):
+   * refuses while a session or worker runs in an affected folder, or a
+   * background command does; `removing` refuses while any session still uses
+   * one. Then holds the folders — Mixdog checkouts only; an external checkout
+   * takes no lease from this profile — so new Mixdog work there waits until `run`
+   * settles. `actor`: the session acting on its own checkout, whose own turn
+   * and workers its caller already checked (assertLeadIdle).
+   */
+  async function withManagementFolders(folders, removing, run, { actor = null } = {}) {
+    const release = [];
+    try {
+      for (const folder of [...new Set(folders)].sort()) {
+        release.push(holdProjectFolder(actor, folder, { hold: !isExternalCheckout(folder) }));
+      }
+      release.push(holdWorkspaceActivity(folders, { sessionId: actor }));
+      const stored = await listWorkspaceConsumers();
+      const consumers = new Map(stored.map((session) => [session.id, session]));
+      for (const session of listLiveSessions()) if (session?.closed !== true) consumers.set(session.id, session);
+      const affected = [...consumers.values()].filter((session) =>
+        folders.some((folder) => session.cwd && isWithin(folder, session.cwd))
+      );
+      const blocking = removing
+        ? affected
+        : affected.filter(
+            (session) =>
+              !(actor && [session.id, session.ownerSessionId, session.parentSessionId].includes(actor)) &&
+              isSessionActive(session)
+          );
+      if (blocking.length) throw worktreeRefusal('folder-in-use', { sessions: blocking.map((session) => session.id) });
+      const jobs = await listWorkspaceJobs();
+      if (jobs.some((job) => !job.terminal && folders.some((folder) => isWithin(folder, job.cwd)))) {
+        throw worktreeRefusal('folder-shell-jobs');
+      }
+      if ((await countOwnShellJobs(affected.map((session) => session.id))) > 0) {
+        throw worktreeRefusal('folder-shell-jobs');
+      }
+      return await run([...consumers.keys()]);
+    } finally {
+      releaseAll(release);
+    }
+  }
+
+  return { workersOf, assertLeadIdle, withProjectFolder, assertCheckoutQuiet, withManagementFolders };
+}

package/src/session-runtime/workspace/project-branches.mjs

@@ -52,7 +52,7 @@ export function createProjectBranchOps({
     return {
       // Detached: branch null and the checked-out commit in baseCommit.
       workspace: project.currentBranch ? workspace : { ...workspace, baseCommit: project.headCommit ?? null },
-      branches: branchMenuEntries(menu.branches, menu.occupancy),
+      branches: branchMenuEntries(menu.branches, menu.occupancy, menu.committedAt),
       occupancy: menu.occupancy,
       retainedWorktree: null,
     };

package/src/session-runtime/workspace/session-view.mjs

@@ -0,0 +1,149 @@
+/**
+ * The hosted Lead's workspace as the transitions read it: the session this
+ * runtime hosts, its stored (or project-folder) workspace record, the live
+ * view the session snapshot publishes and the branch menu.
+ */
+import { isDeepStrictEqual } from 'node:util';
+import {
+  branchMenuEntries,
+  isWorktreeBound,
+  normalizeSessionWorkspace,
+  worktreeError,
+} from '../../runtime/shared/worktrees/contract.mjs';
+import { samePath } from '../../runtime/shared/worktrees/paths.mjs';
+import { readGitHead } from '../../runtime/shared/worktrees/git-head.mjs';
+import { readSessionWorkspace } from './workspace-state.mjs';
+
+/**
+ * @param {object} deps The host hooks of createWorkspaceTransitions plus its
+ *   `backend()` loader and `pendingWorktree()` (the armed worktree intent).
+ */
+export function createSessionWorkspaceView({
+  getSession,
+  getCurrentCwd,
+  getDesktopSession,
+  createCurrentSession,
+  inspectProject,
+  backend,
+  pendingWorktree,
+}) {
+  function hostedSession(sessionRef) {
+    const session = getSession();
+    const requested = String(sessionRef?.sessionId || '').trim();
+    if (!session?.id || (requested && requested !== session.id)) {
+      throw new Error(`workspace: session ${requested || '(none)'} is not hosted by this runtime.`);
+    }
+    return session;
+  }
+
+  async function ensureSession() {
+    if (!getSession()?.id && typeof createCurrentSession === 'function') await createCurrentSession('workspace');
+    return hostedSession(null);
+  }
+
+  function projectPathOf(session) {
+    const desktop = getDesktopSession?.() || session?.desktopSession;
+    if (desktop?.classification === 'project' && desktop.projectPath) return desktop.projectPath;
+    return session?.cwd || getCurrentCwd();
+  }
+
+  /** The stored record, or the project-folder workspace (revision 0) of a session that never moved. */
+  function currentWorkspace(session) {
+    const stored = readSessionWorkspace(session);
+    if (stored) return stored;
+    const projectPath = projectPathOf(session);
+    return normalizeSessionWorkspace({ projectPath, cwd: getCurrentCwd() || projectPath, revision: 0 });
+  }
+
+  let liveWorkspace = null;
+
+  /**
+   * The workspace the session publishes: a worktree-bound record as stored; a
+   * project-folder session (never moved, back from a worktree, or carrying a
+   * transition stub) with the folder's checked-out branch / detached commit and
+   * repoCommonDir read straight from HEAD — no git process. Null outside a git
+   * repository for a session without a record. Identity-stable while equal.
+   */
+  function getLiveWorkspace() {
+    const session = getSession();
+    const stored = readSessionWorkspace(session);
+    if (isWorktreeBound(stored)) return session.workspace;
+    let base;
+    try {
+      base = stored ?? currentWorkspace(session);
+    } catch {
+      return session?.workspace ?? null;
+    }
+    const head = readGitHead(base.cwd);
+    if (!head) return session?.workspace ?? null;
+    const next = {
+      ...base,
+      repoCommonDir: head.repoCommonDir,
+      branch: head.branch,
+      baseCommit: head.branch ? base.baseCommit : head.commit,
+    };
+    if (!liveWorkspace || !isDeepStrictEqual(liveWorkspace, next)) liveWorkspace = next;
+    return liveWorkspace;
+  }
+
+  /** WORKTREE_PROJECT_MISMATCH unless `repoCommonDir` (when given) is the session Project's repository. */
+  async function sessionProject(session, repoCommonDir) {
+    const workspace = currentWorkspace(session);
+    const project = await inspectProject(workspace.projectPath);
+    if (repoCommonDir && !samePath(repoCommonDir, project.repoCommonDir)) {
+      throw worktreeError(
+        'WORKTREE_PROJECT_MISMATCH',
+        "Managed worktrees belong to this session's Project repository; run the command there.",
+        { projectPath: workspace.projectPath, repoCommonDir }
+      );
+    }
+    return { workspace, project };
+  }
+
+  async function getBranchMenu() {
+    const session = getSession();
+    const workspace = session?.id
+      ? currentWorkspace(session)
+      : normalizeSessionWorkspace({ projectPath: projectPathOf(null), cwd: getCurrentCwd(), revision: 0 });
+    const menu = await (await backend()).listBranchOccupancy({
+      projectPath: workspace.projectPath,
+      sessionId: session?.id || null,
+    });
+    const selectedEntry = workspace.worktreeId ? await (await backend()).findWorktreeContaining(workspace.cwd) : null;
+    // A session outside a managed worktree (the project folder — never moved,
+    // or back from a worktree — or a linked checkout of the selected branch)
+    // is on whatever that folder has checked out now.
+    // Its repository is the project's (a never-moved session has no stored
+    // record), and a detached checkout shows branch null with the commit in
+    // baseCommit — never mistaken for "not a repository".
+    let view = workspace;
+    if (!isWorktreeBound(workspace)) {
+      const project = await inspectProject(workspace.cwd);
+      const checkedOut = project.currentBranch ?? null;
+      view = {
+        ...workspace,
+        repoCommonDir: project.repoCommonDir ?? workspace.repoCommonDir,
+        branch: checkedOut,
+        baseCommit: checkedOut ? workspace.baseCommit : (project.headCommit ?? null),
+      };
+    }
+    return {
+      workspace: view,
+      pendingWorktree: pendingWorktree(),
+      branches: branchMenuEntries(menu.branches, menu.occupancy, menu.committedAt),
+      occupancy: menu.occupancy,
+      retainedWorktree: selectedEntry ?? menu.retainedWorktree ?? null,
+      // Creation notes of the retained worktree (submodules, include entries).
+      warnings: Array.isArray(menu.retainedWorktree?.warnings) ? [...menu.retainedWorktree.warnings] : [],
+    };
+  }
+
+  return {
+    hostedSession,
+    ensureSession,
+    currentWorkspace,
+    getLiveWorkspace,
+    sessionProject,
+    getBranchMenu,
+  };
+}