@agou/dsh-worktrees 0.0.0-stage → 1.0.0

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+- insert:
+    - id: worktrees
+      name: dsh-worktrees
+      config:
+        directory: !!js dshHomePath('worktrees')
+        maxRetained: 15

package/discovery.js

@@ -0,0 +1,232 @@
+import path from 'node:path';
+import { bounded, canonical, commitAt, digest, git, repository, samePath, WorktreeError } from './lib/git.js';
+
+const CONCURRENCY = 4;
+const EMPTY = Object.freeze({ records: Object.freeze([]), diagnostics: Object.freeze([]) });
+
+function pathKey(value) {
+  return process.platform === 'win32' ? value.toLowerCase() : value;
+}
+
+function missingPath(error) {
+  return ['INVALID_PATH', 'ENOENT', 'ENOTDIR'].includes(error?.code);
+}
+
+function notWorktree(error) {
+  return error?.code === 'GIT_FAILED' && /fatal: (?:not a git repository \(or any (?:of the parent directories|parent up to mount point)[^\r\n]*\)|this operation must be run in a work tree)/i.test(error.message);
+}
+
+function diagnostic(error, directory, sessionIds) {
+  return Object.freeze({
+    ...(directory ? { path: directory } : {}),
+    ...(sessionIds ? { sessionIds: Object.freeze([...sessionIds]) } : {}),
+    code: typeof error?.code === 'string' ? error.code : 'DISCOVERY_FAILED',
+    message: error instanceof Error ? error.message : String(error),
+  });
+}
+
+function managedSessions(state) {
+  return new Set(Object.values(state?.bindings ?? {}).filter(binding => binding?.mode === 'new' && binding.worktreeId).map(binding => binding.sessionId));
+}
+
+/** Read-only linked-checkout metadata. No refs, index entries, or worktree files are changed. */
+async function inspectDirectory(directory, signal) {
+  let inspected;
+  try {
+    inspected = await repository(directory, signal);
+  } catch (error) {
+    if (notWorktree(error)) return null;
+    throw error;
+  }
+  const gitDirResult = await git(inspected.root, ['rev-parse', '--absolute-git-dir'], { signal, maxOutput: 64 * 1024 });
+  const gitDir = await canonical(gitDirResult.stdout.replace(/\r?\n$/, ''));
+  if (samePath(gitDir, inspected.commonDir)) return null;
+  const branch = await git(inspected.root, ['symbolic-ref', '--quiet', '--short', 'HEAD'], { signal, allowed: [0, 1], maxOutput: 64 * 1024 });
+  const head = await commitAt(inspected.root, 'HEAD', signal, true);
+  return Object.freeze({
+    id: `external:${digest(pathKey(inspected.root))}`,
+    path: inspected.root,
+    currentBranch: branch.code === 0 ? branch.stdout.replace(/\r?\n$/, '') : null,
+    head,
+    baseRef: null,
+    status: 'ready',
+    external: true,
+  });
+}
+
+/**
+ * Observe existing linked worktrees without adopting them into managed state.
+ * ctx only needs sessionController.list({}, signal) and workspaceRegistry.list().
+ * Each refresh reads session membership; Git metadata is cached for cacheMs.
+ * Concurrent refresh calls share one scan. Cancelling the final waiter stops it.
+ */
+export class LinkedWorktreeDiscovery {
+  constructor(ctx, { cacheMs = 30_000, maxDirectories = 256, scanTimeoutMs = 10_000 } = {}) {
+    for (const [name, value, minimum] of [['cacheMs', cacheMs, 0], ['maxDirectories', maxDirectories, 1], ['scanTimeoutMs', scanTimeoutMs, 1]]) {
+      if (!Number.isSafeInteger(value) || value < minimum) throw new TypeError(`${name} must be an integer of at least ${minimum}.`);
+    }
+    this.ctx = ctx;
+    this.cacheMs = cacheMs;
+    this.maxDirectories = maxDirectories;
+    this.scanTimeoutMs = scanTimeoutMs;
+    this.cache = new Map();
+    this.value = EMPTY;
+    this.pending = null;
+    this.managed = new Set();
+    this.generation = 0;
+    this.disposed = false;
+  }
+
+  snapshot() {
+    return this.value;
+  }
+
+  invalidate() {
+    this.generation += 1;
+    this.cache.clear();
+    this.pending?.controller.abort(new WorktreeError('DISCOVERY_INVALIDATED', 'Worktree discovery was invalidated.'));
+    this.pending = null;
+  }
+
+  dispose() {
+    this.disposed = true;
+    this.invalidate();
+    this.value = EMPTY;
+  }
+
+  refresh(state, signal) {
+    signal?.throwIfAborted();
+    if (this.disposed) return Promise.reject(new WorktreeError('DISCOVERY_DISPOSED', 'Worktree discovery is disposed.'));
+    this.managed = managedSessions(state);
+    this.value = this.excludeManaged(this.value);
+    let pending = this.pending;
+    if (!pending || pending.controller.signal.aborted) {
+      pending = { controller: new AbortController(), waiters: 0, promise: null };
+      const generation = this.generation;
+      const timer = setTimeout(() => pending.controller.abort(new WorktreeError('DISCOVERY_TIMEOUT', `Worktree discovery exceeded ${this.scanTimeoutMs} ms.`)), this.scanTimeoutMs);
+      timer.unref();
+      pending.promise = this.scan(pending.controller.signal, generation).then(value => {
+        if (!pending.controller.signal.aborted && generation === this.generation && !this.disposed) this.value = this.excludeManaged(value);
+        return this.value;
+      }).finally(() => {
+        clearTimeout(timer);
+        if (this.pending === pending) this.pending = null;
+      });
+      this.pending = pending;
+    }
+    pending.waiters += 1;
+    return bounded(pending.promise, signal).finally(() => {
+      pending.waiters -= 1;
+      if (pending.waiters === 0 && this.pending === pending) pending.controller.abort(new WorktreeError('ABORTED', 'Worktree discovery has no remaining callers.'));
+    });
+  }
+
+  excludeManaged(value) {
+    const records = value.records.map(record => {
+      const sessionIds = record.sessionIds.filter(id => !this.managed.has(id));
+      return sessionIds.length === record.sessionIds.length ? record : Object.freeze({ ...record, sessionIds: Object.freeze(sessionIds) });
+    }).filter(record => record.sessionIds.length);
+    if (records.length === value.records.length && records.every((record, index) => record === value.records[index])) return value;
+    return Object.freeze({ records: Object.freeze(records), diagnostics: value.diagnostics });
+  }
+
+  async inspect(directory, signal, inFlight, generation) {
+    let real;
+    try {
+      real = await canonical(directory);
+    } catch (error) {
+      if (missingPath(error)) return { record: null };
+      throw error;
+    }
+    signal.throwIfAborted();
+    const key = pathKey(real);
+    const cached = this.cache.get(key);
+    if (cached) {
+      this.cache.delete(key);
+      if (cached.expiresAt > Date.now()) {
+        this.cache.set(key, cached);
+        return cached.result;
+      }
+    }
+    if (inFlight.has(key)) return inFlight.get(key);
+    const promise = inspectDirectory(real, signal).then(record => ({ record }), error => {
+      signal.throwIfAborted();
+      // ENOENT here can be a missing Git executable, so it remains observable.
+      return { error };
+    }).then(result => {
+      if (generation === this.generation && !signal.aborted) {
+        this.cache.set(key, { result, expiresAt: Date.now() + this.cacheMs });
+        while (this.cache.size > this.maxDirectories) this.cache.delete(this.cache.keys().next().value);
+      }
+      return result;
+    });
+    inFlight.set(key, promise);
+    return promise;
+  }
+
+  async scan(signal, generation) {
+    const value = await bounded(this.ctx.sessionController.list({}, signal), signal);
+    signal.throwIfAborted();
+    if (!Array.isArray(value?.items)) throw new TypeError('Session list must contain an items array.');
+    const workspaces = this.ctx.workspaceRegistry.list();
+    if (!Array.isArray(workspaces)) throw new TypeError('Workspace list must be an array.');
+    const membership = new Map();
+    for (const workspace of workspaces) {
+      for (const sessionId of workspace.sessionIds) if (!membership.has(sessionId)) membership.set(sessionId, workspace);
+    }
+    const directories = new Map();
+    for (const session of value.items) {
+      if (typeof session?.sessionId !== 'string' || !session.sessionId || this.managed.has(session.sessionId)) continue;
+      const projected = session.projections?.values?.workingDirectory;
+      const directory = projected === undefined ? session.cwd : projected;
+      if (typeof directory !== 'string' || !path.isAbsolute(directory) || directory.includes('\0')) continue;
+      const key = pathKey(directory);
+      if (!directories.has(key)) directories.set(key, { directory, sessionIds: new Set() });
+      directories.get(key).sessionIds.add(session.sessionId);
+    }
+    const diagnostics = [];
+    const entries = [...directories.values()];
+    if (entries.length > this.maxDirectories) diagnostics.push(diagnostic(new WorktreeError('DISCOVERY_LIMIT', `Inspected at most ${this.maxDirectories} of ${entries.length} session directories.`)));
+    const queue = entries.slice(0, this.maxDirectories);
+    const results = new Array(queue.length);
+    const inFlight = new Map();
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, queue.length) }, async () => {
+      while (next < queue.length) {
+        signal.throwIfAborted();
+        const index = next++;
+        try {
+          results[index] = await this.inspect(queue[index].directory, signal, inFlight, generation);
+        } catch (error) {
+          signal.throwIfAborted();
+          results[index] = { error };
+        }
+      }
+    }));
+    signal.throwIfAborted();
+    const records = new Map();
+    for (let index = 0; index < queue.length; index += 1) {
+      const { directory, sessionIds } = queue[index];
+      const { record, error } = results[index];
+      if (error) { diagnostics.push(diagnostic(error, directory, sessionIds)); continue; }
+      if (!record) continue;
+      let grouped = records.get(record.id);
+      if (!grouped) { grouped = { ...record, sessionIds: new Set() }; records.set(record.id, grouped); }
+      for (const sessionId of sessionIds) {
+        grouped.sessionIds.add(sessionId);
+        const workspace = membership.get(sessionId);
+        if (!grouped.workspaceId && workspace) {
+          grouped.workspaceId = workspace.id;
+          grouped.workspaceTitle = workspace.title;
+        }
+      }
+    }
+    // Bound cached metadata even when sessions keep moving between directories.
+    const now = Date.now();
+    for (const [key, cached] of this.cache) if (cached.expiresAt <= now) this.cache.delete(key);
+    return Object.freeze({
+      records: Object.freeze([...records.values()].map(record => Object.freeze({ ...record, sessionIds: Object.freeze([...record.sessionIds]) }))),
+      diagnostics: Object.freeze(diagnostics),
+    });
+  }
+}

package/host.js

@@ -0,0 +1,412 @@
+import path from 'node:path';
+import { stat } from 'node:fs/promises';
+import { z } from 'zod';
+import { WorktreeManager } from './lib/manager.js';
+import { LinkedWorktreeDiscovery } from './discovery.js';
+
+const id = z.string().min(1).max(256);
+const schemas = {
+  workspace: z.object({ workspaceId: id }).strict(),
+  checkout: z.object({ workspaceId: id, branch: z.string().min(1).max(4096) }).strict(),
+  prepare: z.object({
+    sessionId: id,
+    operationId: id,
+    choice: z.object({ mode: z.enum(['local', 'new']), baseRef: z.string().min(1).max(4096).optional() }).strict().optional(),
+  }).strict(),
+  settle: z.object({ sessionId: id, operationId: id }).strict(),
+  list: z.object({ refresh: z.boolean().optional() }).strict(),
+  restore: z.object({ worktreeId: id }).strict(),
+  remove: z.object({ worktreeId: id }).strict(),
+  configure: z.object({
+    directory: z.string().min(1).max(32767).optional(),
+    maxRetained: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).optional(),
+    expectedRevision: z.number().int().nonnegative(),
+  }).strict(),
+};
+export const RPC_ENDPOINTS = Object.freeze(Object.keys(schemas));
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function within(root, target) {
+  if (!root || !target) return false;
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  return relative === '' || relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+function workspaceValue(workspace) {
+  return { workspaceId: workspace.id, path: workspace.path, title: workspace.title };
+}
+
+/** Extract only accepted human input, including queued messages, from a durable inbox splice. */
+export function acceptedMessages(event) {
+  if (event.type !== 'agent/inbox/spliced') return [];
+  return (event.data.inserted ?? []).filter(message => message.source?.kind === 'user').map(message => ({
+    requestId: message.source.rpcId ?? message.id ?? `${event.seq}`,
+    acceptedAt: event.time,
+  }));
+}
+
+/** Host adapter: explicit Session/Workspace identities; no ambient active Session. */
+export class WorktreeHost {
+  constructor(ctx, config, storage, Manager = WorktreeManager) {
+    this.ctx = ctx;
+    this.config = config;
+    this.controller = new AbortController();
+    this.operations = new Set();
+    this.reservations = new Map();
+    this.accepting = new Map();
+    this.reconciled = new Map();
+    this.discovery = new LinkedWorktreeDiscovery(ctx);
+    this.discoveryPending = null;
+    this.discoveryNext = 0;
+    this.discoveryDiagnostics = '';
+    this.cleanupTimer = null;
+    this.cleanupRunning = false;
+    this.cleanupRequested = false;
+    this.retryDelay = 30_000;
+    this.manager = new Manager({
+      storage,
+      getConfig: () => this.configuration(),
+      setDirectory: (sessionId, directory) => this.setDirectory(sessionId, directory),
+      isProtected: record => this.protection(record),
+      archiveSessions: async ids => {
+        for (const sessionId of ids) await this.ctx.workspaceRegistry.archiveSession(sessionId);
+      },
+    });
+  }
+
+  configuration() {
+    return { directory: this.config.directory.get(), maxRetained: this.config.maxRetained.get() };
+  }
+
+  track(operation) {
+    this.operations.add(operation);
+    operation.then(() => this.operations.delete(operation), () => this.operations.delete(operation));
+    return operation;
+  }
+
+  report(error) {
+    if (!this.controller.signal.aborted) this.ctx.logger.warn(`worktrees: ${errorMessage(error)}`);
+  }
+
+  workspace(workspaceId) {
+    const workspace = this.ctx.workspaceRegistry.get(workspaceId);
+    if (!workspace) throw new Error('The workspace is no longer registered.');
+    return workspaceValue(workspace);
+  }
+
+  workspaceFor(session) {
+    const workspace = this.ctx.workspaceRegistry.list().find(item => item.sessionIds.includes(session.id));
+    if (workspace) return workspaceValue(workspace);
+    const binding = this.manager.list().bindings[session.id];
+    return binding ? { workspaceId: binding.workspaceId, path: binding.workspacePath, title: binding.workspaceTitle } : undefined;
+  }
+
+  async resolveAgent(sessionId) {
+    const result = await this.ctx.sessionController.resolveAgent(sessionId);
+    if ('error' in result) throw result.error;
+    this.controller.signal.throwIfAborted();
+    return result.agent;
+  }
+
+  async setDirectory(sessionId, directory) {
+    const agent = this.ctx.agents.get(sessionId);
+    if (!agent) throw new Error('The session was closed before its worktree was ready.');
+    const current = this.ctx.workingDirectory.get(agent.session);
+    const binding = this.manager.list().bindings[sessionId];
+    // Local sessions retain native navigation; managed sessions retain navigation inside their checkout.
+    if (binding?.acceptedAt != null && (binding.mode === 'local' || within(directory, current))) return;
+    await this.ctx.workingDirectory.set(agent, directory, this.controller.signal);
+  }
+
+  async assertAvailable(agent, signal) {
+    if (!this.manager.list().bindings[agent.id]?.worktreeId) return;
+    const binding = await this.manager.assertAvailable(agent.id, signal);
+    if (binding?.mode !== 'new') return;
+    const current = this.ctx.workingDirectory.get(agent.session);
+    if (!within(binding.path, current)) return;
+    let currentDirectory;
+    try { currentDirectory = await stat(current); }
+    catch (error) {
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error;
+    }
+    signal?.throwIfAborted();
+    // Native ensure() falls back to the immutable source cwd. Keep recovery inside this verified checkout.
+    if (!currentDirectory?.isDirectory()) await this.ctx.workingDirectory.set(agent, binding.path, signal);
+  }
+
+  async protection(record) {
+    const reasons = [];
+    const pinned = new Set(this.ctx.workspaceRegistry.pinnedSessionIds);
+    for (const sessionId of record.sessionIds) {
+      if (pinned.has(sessionId)) reasons.push('pinned');
+      if (this.reservations.has(sessionId)) reasons.push('sending');
+      try {
+        const activity = await this.ctx.waterfall('workspace/session-activity', { sessionId }, async () => []);
+        if (activity.length) reasons.push('active');
+      } catch (error) {
+        reasons.push('activity-unavailable');
+        this.report(error);
+      }
+    }
+    // An explicitly registered workspace rooted in a checkout is never disposable.
+    if (this.ctx.workspaceRegistry.list().some(item => within(record.path, item.path))) reasons.push('workspace');
+    return [...new Set(reasons)];
+  }
+
+  observe(session, event) {
+    const binding = this.manager.list().bindings[session.id];
+    const accepted = acceptedMessages(event).filter(item => binding && item.acceptedAt >= binding.preparedAt);
+    if (!accepted.length) return Promise.resolve();
+    const previous = this.accepting.get(session.id) ?? Promise.resolve();
+    const operation = previous.catch(() => {}).then(async () => {
+      for (const item of accepted) await this.manager.remember({ sessionId: session.id, ...item });
+    });
+    this.accepting.set(session.id, operation);
+    this.track(operation).catch(error => this.report(error));
+    return operation;
+  }
+
+  async reconcile(session) {
+    const events = session.snapshotEvents();
+    const cursor = this.reconciled.get(session.id) ?? 0;
+    for (const event of events.slice(cursor)) await this.observe(session, event);
+    this.reconciled.set(session.id, events.length);
+  }
+
+  async inherit(agent, signal) {
+    const session = agent.session;
+    if (!session.header.parentSession || this.manager.list().bindings[session.id]) return;
+    const parent = this.manager.list().bindings[session.header.parentSession];
+    if (!parent?.worktreeId) return;
+    const workspace = this.workspaceFor(session) ?? { workspaceId: parent.workspaceId, path: parent.workspacePath, title: parent.workspaceTitle };
+    await this.manager.bindInheritedSession(session.id, session.header.parentSession, workspace, this.ctx.workingDirectory.get(session), signal);
+  }
+
+  async prepare(request, peer, signal) {
+    const present = this.reservations.get(request.sessionId);
+    if (present && (present.operationId !== request.operationId || present.peerId !== peer.id)) {
+      const error = new Error('Another message is preparing this session. Wait for it to finish, then send again.');
+      error.code = 'SEND_IN_PROGRESS';
+      throw error;
+    }
+    let reservation = present;
+    if (!reservation) {
+      const release = () => {
+        if (this.reservations.get(request.sessionId) === reservation) this.reservations.delete(request.sessionId);
+      };
+      reservation = { operationId: request.operationId, peerId: peer.id, release, unsubscribe: () => peer.signal.removeEventListener('abort', release) };
+      this.reservations.set(request.sessionId, reservation);
+      peer.signal.addEventListener('abort', release, { once: true });
+    }
+    try {
+      const agent = await this.resolveAgent(request.sessionId);
+      await this.inherit(agent, signal);
+      await this.reconcile(agent.session);
+      const workspace = this.workspaceFor(agent.session);
+      if (!workspace) {
+        await this.settle(request, peer);
+        return { ready: true, actualDirectory: this.ctx.workingDirectory.get(agent.session), passthrough: true };
+      }
+      const binding = this.manager.list().bindings[request.sessionId];
+      const hasHumanHistory = agent.session.snapshotEvents().some(event => acceptedMessages(event).length > 0 || event.type === 'user/message' && event.data.source?.kind === 'user');
+      if (!binding && hasHumanHistory) {
+        if (request.choice?.mode === 'new') throw new Error('A new worktree can only be selected before this session’s first message.');
+        await this.settle(request, peer);
+        return { ready: true, actualDirectory: this.ctx.workingDirectory.get(agent.session), passthrough: true };
+      }
+      const choice = request.choice ?? (binding ? { mode: binding.mode, ...(binding.baseRef ? { baseRef: binding.baseRef } : {}) } : (await this.manager.inspectWorkspace(workspace, signal)).choice);
+      const prepared = await this.manager.prepare({ sessionId: request.sessionId, workspace, choice, operationId: request.operationId }, signal);
+      if (prepared.requiresRestore && !prepared.worktree.snapshotCommit) throw Object.assign(new Error(`The worktree directory is missing and no recovery snapshot is available: ${prepared.worktree.path}`), { code: 'DIRECTORY_MISSING' });
+      if (prepared.requiresRestore) return {
+        requiresRestore: true,
+        worktreeId: prepared.worktree.id,
+        path: prepared.worktree.path,
+        snapshotRef: prepared.worktree.snapshotRef,
+      };
+      this.requestCleanup();
+      return { ready: true, actualDirectory: this.ctx.workingDirectory.get(agent.session), ...(prepared.worktree ? { worktreeId: prepared.worktree.id } : {}) };
+    } catch (error) {
+      await this.settle(request, peer).catch(settleError => this.report(settleError));
+      throw error;
+    }
+  }
+
+  async settle(request, peer) {
+    const reservation = this.reservations.get(request.sessionId);
+    if (!reservation || reservation.operationId !== request.operationId || reservation.peerId !== peer.id) return { settled: true };
+    const agent = this.ctx.agents.get(request.sessionId);
+    try {
+      if (agent) await this.reconcile(agent.session);
+      await this.accepting.get(request.sessionId);
+    } finally {
+      reservation.unsubscribe();
+      reservation.release();
+    }
+    this.requestCleanup();
+    return { settled: true };
+  }
+
+  descriptor() {
+    const descriptor = this.ctx.settings.describe({ redactSecrets: true }).find(item => item.ns === 'worktrees');
+    if (!descriptor) throw new Error('The worktrees settings entry is not active.');
+    return descriptor;
+  }
+
+  requestDiscovery(invalidate = false) {
+    if (this.controller.signal.aborted) return;
+    if (invalidate) {
+      this.discovery.invalidate();
+      this.discoveryNext = 0;
+    }
+    if (this.discoveryPending || Date.now() < this.discoveryNext) return;
+    this.discoveryNext = Date.now() + 30_000;
+    this.discoveryPending = this.track(this.discovery.refresh(this.manager.list(), this.controller.signal).then(value => {
+      const diagnostics = JSON.stringify(value.diagnostics);
+      if (diagnostics !== this.discoveryDiagnostics) {
+        this.discoveryDiagnostics = diagnostics;
+        for (const item of value.diagnostics) this.report(new Error(`Worktree discovery: ${item.message}`));
+      }
+    }).catch(error => {
+      if (error.code !== 'DISCOVERY_INVALIDATED') this.report(error);
+    }).finally(() => {
+      this.discoveryPending = null;
+      if (this.discoveryNext === 0) this.requestDiscovery();
+    }));
+  }
+
+  async list(refresh, signal) {
+    if (refresh) await this.manager.refresh(signal);
+    this.requestDiscovery();
+    const state = this.manager.list();
+    const records = [];
+    for (const record of Object.values(state.worktrees)) {
+      signal?.throwIfAborted();
+      const protectionReasons = await this.protection(record);
+      const { token: _token, ...visible } = record;
+      records.push({ ...visible, snapshotRef: record.snapshotCommit ? record.snapshotRef : null, repositoryRoot: record.sourceRoot, protected: protectionReasons.length > 0, protectionReasons });
+    }
+    return {
+      records,
+      observed: this.discovery.snapshot().records,
+      bindings: Object.values(state.bindings),
+      preferences: Object.entries(state.preferences).map(([workspaceId, choice]) => ({ workspaceId, ...choice })),
+      config: this.configuration(),
+      revision: this.descriptor().revision,
+      directoryPickerKind: this.ctx.get('directoryPicker')?.capability().kind ?? null,
+    };
+  }
+
+  async restore(worktreeId, signal) {
+    const record = await this.manager.restore(worktreeId, signal);
+    this.requestCleanup();
+    return { worktreeId: record.id, path: record.path };
+  }
+
+  async remove(worktreeId, signal) {
+    const record = await this.manager.remove(worktreeId, signal);
+    this.requestCleanup();
+    return { worktreeId: record.id, status: record.status };
+  }
+
+  async configure(request) {
+    const { expectedRevision, ...patch } = schemas.configure.parse(request);
+    if (patch.directory && !path.isAbsolute(patch.directory)) throw new Error('Worktree directory must be an absolute path on the Host.');
+    await this.ctx.settings.update('worktrees', patch, expectedRevision);
+    this.requestCleanup();
+    return { config: this.configuration(), revision: this.descriptor().revision };
+  }
+
+  async dispatch(endpoint, input, signal, peer) {
+    if (peer?.principal?.kind !== 'owner') throw Object.assign(new Error('Worktree management requires the Host owner.'), { code: 'FORBIDDEN' });
+    if (!Object.hasOwn(schemas, endpoint)) throw Object.assign(new Error('Unknown worktree operation.'), { code: 'NOT_FOUND' });
+    const request = schemas[endpoint].parse(input ?? {});
+    signal.throwIfAborted();
+    switch (endpoint) {
+      case 'workspace': return this.manager.inspectWorkspace(this.workspace(request.workspaceId), signal);
+      case 'checkout': return this.manager.checkout(this.workspace(request.workspaceId), request.branch, signal);
+      case 'prepare': return this.prepare(request, peer, signal);
+      case 'settle': return this.settle(request, peer);
+      case 'list': return this.list(request.refresh === true, signal);
+      case 'restore': return this.restore(request.worktreeId, signal);
+      case 'remove': return this.remove(request.worktreeId, signal);
+      case 'configure': return this.configure(request);
+      default: throw new Error('Unknown worktree operation.');
+    }
+  }
+
+  rpc(endpoint, input, signal, peer) {
+    const control = AbortSignal.any([signal, this.controller.signal, peer.signal]);
+    return this.track(this.dispatch(endpoint, input, control, peer).then(value => ({ ok: true, value }), error => ({
+      ok: false,
+      error: { code: typeof error.code === 'string' ? error.code : 'WORKTREE_ERROR', message: errorMessage(error), details: {} },
+    })));
+  }
+
+  requestCleanup(delay = 1000) {
+    if (this.controller.signal.aborted) return;
+    this.cleanupRequested = true;
+    if (this.cleanupRunning || this.cleanupTimer) return;
+    this.cleanupTimer = setTimeout(() => {
+      this.cleanupTimer = null;
+      this.track(this.clean()).catch(error => this.report(error));
+    }, delay);
+    this.cleanupTimer.unref?.();
+  }
+
+  async clean() {
+    if (this.controller.signal.aborted || this.cleanupRunning || !this.cleanupRequested) return;
+    this.cleanupRequested = false;
+    this.cleanupRunning = true;
+    try {
+      const result = await this.manager.cleanup(this.controller.signal);
+      if (result.errors.length) {
+        for (const item of result.errors) this.report(new Error(item.message));
+        this.requestCleanup(this.retryDelay);
+        this.retryDelay = Math.min(this.retryDelay * 2, 300_000);
+      } else {
+        this.retryDelay = 30_000;
+        if (result.removed.length && result.eligible - result.removed.length > this.configuration().maxRetained) this.cleanupRequested = true;
+      }
+    } finally {
+      this.cleanupRunning = false;
+      if (this.cleanupRequested) this.requestCleanup(this.retryDelay);
+    }
+  }
+
+  async start() {
+    // Recover only sends prepared since the last recorded admission; reading never resumes an Agent.
+    for (const binding of Object.values(this.manager.list().bindings)) {
+      if (binding.acceptedAt != null && binding.preparedAt <= binding.acceptedAt) continue;
+      try {
+        const inspected = await this.ctx.sessionController.inspect(binding.sessionId, this.controller.signal);
+        for (const event of inspected.events) {
+          for (const accepted of acceptedMessages(event).filter(item => item.acceptedAt >= binding.preparedAt)) await this.manager.remember({ sessionId: binding.sessionId, ...accepted });
+        }
+      } catch (error) { this.report(error); }
+    }
+    await this.manager.refresh(this.controller.signal);
+    this.requestDiscovery();
+    this.requestCleanup();
+  }
+
+  context(agent) {
+    const binding = agent && this.manager.list().bindings[agent.id];
+    const record = binding?.worktreeId && this.manager.list().worktrees[binding.worktreeId];
+    if (!record || record.status === 'removed') return '';
+    return `Managed Git worktree: ${JSON.stringify(record.path)}. Created from ${JSON.stringify(record.baseRef)} at ${record.baseCommit}. This checkout was created detached. Before making authorized code changes, inspect Git HEAD and create a task branch from the current HEAD if still detached; honor a branch name requested by the user. Do not create a branch for a read-only task, or commit or push without the user's instruction.`;
+  }
+
+  async dispose() {
+    this.controller.abort(new Error('Worktree plugin disposed.'));
+    this.discovery.dispose();
+    if (this.cleanupTimer) clearTimeout(this.cleanupTimer);
+    this.cleanupTimer = null;
+    for (const reservation of this.reservations.values()) reservation.unsubscribe();
+    this.reservations.clear();
+    await this.manager.dispose();
+    await Promise.allSettled([...this.operations]);
+  }
+}

package/icon.svg

@@ -0,0 +1,18 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <g transform="translate(1.8 1.8) scale(0.9)">
+    <path d="M11 12V24M11 19H16C20.4 19 25 16.4 25 12" stroke="url(#worktree-branches)" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" />
+    <rect x="7.5" y="7" width="7" height="7" rx="2" fill="#86B8F5" />
+    <rect x="7.5" y="22" width="7" height="7" rx="2" fill="#5269E1" />
+    <rect x="21.5" y="7" width="7" height="7" rx="2" fill="url(#worktree-leaf)" />
+  </g>
+  <defs>
+    <linearGradient id="worktree-branches" x1="11" y1="12" x2="18" y2="24" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#86B8F5" />
+      <stop offset="1" stop-color="#5269E1" />
+    </linearGradient>
+    <linearGradient id="worktree-leaf" x1="22" y1="7" x2="28" y2="14" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#51CFDB" />
+      <stop offset="1" stop-color="#108792" />
+    </linearGradient>
+  </defs>
+</svg>