feat(agent-cases): tag agent-spawned case dirs and sweep their leftovers

A long orchestration creates one case directory per worker and deleting the sessions never removed them, so ~/codeman-cases accumulated scratch folders that were indistinguishable from real projects. They are now labelled and have a cleanup path. - src/agent-case-marker.ts: a case dir quick-start CREATES for an agent-driven spawn gets a .codeman-agent-case.json marker (when, by whom, parent session, mode). Only the create branch writes it, so a linked case, a cloned repo or any pre-existing path is never labelled; reading is total, so a malformed marker means "not agent-created" rather than a half-trusted entry. - The signal is the new X-Codeman-Agent-Origin header the skill preamble sets on its shared curl (preamble bumped to 1.22.0), or an agentOrigin body field, falling back to a resolved parentSessionId so a worker spawned by a stale skill copy is still labelled. - GET /api/cases publishes it as agentCreated; GET /api/cases/agent-created is a read-only cleanup listing adding inUse and modifiedAt; Add Case -> Manage badges each case and offers a review-then-delete sweep that names every directory in its confirm and skips any case a live session is working in. Removal stays on the existing DELETE /api/cases/:name. - Agent preamble caches are collected too: ~/.cache/codeman-agent-<id>.sh was written per claude session and never removed (236 leftovers measured on a working machine). Now deleted with the session and swept at boot, guarded by a live-session keep set plus a 7-day age floor. Verified end to end on an isolated instance: marker written for header, body and lineage-only spawns, absent with no agent signal and for a pre-existing directory; inUse flipping on session end; badge, sticky bar, confirm and sweep driven in a browser; preamble seeded on create, removed on delete, boot sweep taking only the aged orphans. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-10-04 14:39:42 +02:00 · 2026-09-07 19:09:24 +02:00
parent 61d22eee1c
commit 8ee7926e27
19 changed files with 1072 additions and 26 deletions
@@ -3595,17 +3595,33 @@ Object.assign(CodemanApp.prototype, {
      return;
    }

-    let html = '';
+    // Cases an agent worker created (server-side marker file, see agent-case-marker.ts).
+    // A long orchestration leaves one scratch directory per worker behind, so they get
+    // a badge and a bulk cleanup entry point rather than having to be recognised by name.
+    const agentCases = cases.filter(c => c.agentCreated);
+    let html = agentCases.length > 0
+      ? `<div class="case-manage-agent-bar">
+          <span class="case-manage-agent-count">${agentCases.length} case${agentCases.length === 1 ? '' : 's'} created by agent workers</span>
+          <button class="case-manage-btn case-manage-btn-cleanup" onclick="app.cleanupAgentCases()"
+                  title="Review and delete the scratch cases agent workers left behind">Clean up</button>
+         </div>`
+      : '';
    cases.forEach((c, idx) => {
      const isFirst = idx === 0;
      const isLast = idx === cases.length - 1;
      // Was `/Users/<user>` only, the mirror image of the Run menu's bug: every
      // case path on a Linux host rendered in full, unabbreviated.
      const pathDisplay = c.path ? this._shortenHomePath(c.path) : '';
+      const agentTitle = c.agentCreated
+        ? `Created by an agent worker${c.agentCreated.parentSessionName ? ` from ${c.agentCreated.parentSessionName}` : ''}` +
+          ` (${c.agentCreated.createdBy})${c.agentCreated.createdAt ? ` on ${new Date(c.agentCreated.createdAt).toLocaleString()}` : ''}`
+        : '';
      html += `
        <div class="case-manage-item" data-case="${escapeHtml(c.name)}">
          <div class="case-manage-info">
-            <span class="case-manage-name">${escapeHtml(c.name)}</span>
+            <span class="case-manage-name">${escapeHtml(c.name)}${
+              c.agentCreated ? `<span class="case-manage-tag-agent" title="${escapeHtml(agentTitle)}" data-i18n-skip>agent</span>` : ''
+            }</span>
            <span class="case-manage-path">${escapeHtml(pathDisplay)}</span>
          </div>
          <div class="case-manage-actions">
@@ -3683,6 +3699,80 @@ Object.assign(CodemanApp.prototype, {
    }
  },

+  /**
+   * Review-then-delete the scratch cases agent workers left behind.
+   *
+   * ⚠️ Never silently bulk-deletes: the confirm names every directory, and a case a
+   * LIVE session is still working in is excluded outright rather than confirmed away
+   * (`inUse` from the server, which knows every session's working directory). Removal
+   * reuses `DELETE /api/cases/:name` one name at a time, so there is no second
+   * recursive-delete path to keep in step with the first.
+   */
+  async cleanupAgentCases() {
+    let agentCases;
+    try {
+      const res = await fetch('/api/cases/agent-created');
+      const body = await res.json();
+      if (!body.success) {
+        this.showToast(body.error || 'Failed to list agent cases', 'error');
+        return;
+      }
+      agentCases = body.data.cases || [];
+    } catch (err) {
+      this.showToast('Failed to list agent cases: ' + err.message, 'error');
+      return;
+    }
+
+    const busy = agentCases.filter(c => c.inUse);
+    const removable = agentCases.filter(c => !c.inUse);
+    if (removable.length === 0) {
+      this.showToast(
+        busy.length > 0
+          ? `All ${busy.length} agent case(s) are still in use by a running session`
+          : 'No agent-created cases to clean up',
+        'info'
+      );
+      return;
+    }
+
+    const names = removable.map(c => `  ${c.name}`).join('\n');
+    const busyNote = busy.length > 0 ? `\n\nSkipping ${busy.length} case(s) still in use by a running session.` : '';
+    if (!confirm(`Permanently delete ${removable.length} agent-created case folder(s) and everything in them?\n\n${names}${busyNote}`)) {
+      return;
+    }
+
+    let deleted = 0;
+    const failed = [];
+    for (const item of removable) {
+      try {
+        const res = await fetch(`/api/cases/${encodeURIComponent(item.name)}`, { method: 'DELETE' });
+        const body = await res.json();
+        if (body.success) deleted++;
+        else failed.push(item.name);
+      } catch {
+        failed.push(item.name);
+      }
+    }
+
+    this.showToast(
+      failed.length === 0
+        ? `Deleted ${deleted} agent case(s)`
+        : `Deleted ${deleted}, failed: ${failed.join(', ')}`,
+      failed.length === 0 ? 'success' : 'error'
+    );
+
+    // Refresh the picker (its selected case may be one we just deleted) and the list.
+    const select = document.getElementById('quickStartCase');
+    const currentCase = select?.value;
+    const currentDeleted = removable.some(c => c.name === currentCase);
+    if (currentDeleted) select?.blur?.();
+    await this.loadQuickStartCases(currentDeleted ? null : currentCase);
+    if (currentDeleted) {
+      await this.saveLastUsedCase(document.getElementById('quickStartCase')?.value || 'testcase');
+    }
+    this.renderCaseManageList();
+  },
+
  async saveCaseOrder(order) {
    try {
      await fetch('/api/cases/order', {
@@ -5941,6 +5941,57 @@ body.touch-device .terminal-container .xterm .xterm-helper-textarea {
  color: #ef4444;
 }

+/* Agent-created cases: the badge on a scratch case, and the bulk cleanup bar above
+   the list. Tokens only (no hardcoded ink), so the light skins repaint with the rest. */
+.case-manage-tag-agent {
+  display: inline-block;
+  margin-left: 6px;
+  padding: 0 5px;
+  border: 1px solid var(--control-border);
+  border-radius: 3px;
+  background: var(--control-bg);
+  color: var(--text-muted);
+  font-size: 0.58rem;
+  font-weight: 500;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  vertical-align: 1px;
+}
+
+.case-manage-agent-bar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  margin-bottom: 4px;
+  padding: 8px 10px;
+  border: 1px solid var(--control-border);
+  border-radius: 6px;
+  /* Sticky, and therefore OPAQUE: it is the first child of the scrolling list
+     (.case-manage-list is a 320px-tall flex scroller), so a translucent bar would
+     have case rows sliding visibly under it, and a static one would put the cleanup
+     button out of reach the moment a long case list is scrolled. */
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  background: var(--bg-card);
+}
+
+.case-manage-agent-count {
+  font-size: 0.7rem;
+  color: var(--text-dim);
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* The shared .case-manage-btn is a 26px icon square; this one carries a word. */
+.case-manage-btn-cleanup {
+  width: auto;
+  padding: 0 10px;
+  white-space: nowrap;
+}
+
 .toolbar-input {
  padding: 0.4rem 0.5rem;
  background: var(--bg-input);
@@ -23,6 +23,7 @@ import { dataPath } from '../config/instance.js';
 import { getCasesDir } from '../config/cases-dir.js';
 import { isMultiUserMode, maxSessionsPerUser, userCasesDir } from '../config/multiuser.js';
 import { SYNTHETIC_ADMIN, findUser } from '../user-store.js';
+import { AGENT_ORIGIN_SPAWNED_BY_SESSION, normalizeAgentOrigin } from '../agent-case-marker.js';

 // Shared path constants used across route modules. CASES_DIR (project folders)
 // stays shared across instances; SETTINGS_PATH is per-instance runtime state.
@@ -361,6 +362,33 @@ export function resolveParentSessionId(
  return parent.id;
 }

+/**
+ * Resolve "an agent asked for this", the signal that labels a case directory
+ * Codeman is about to CREATE as an agent scratch workspace (see agent-case-marker.ts).
+ *
+ * Two signals, in order:
+ * 1. an explicit `agentOrigin` body field, or the `X-Codeman-Agent-Origin` header the
+ *    packaged skill sets once on its shared curl invocation, so every spawn recipe
+ *    carries it without a per-recipe edit. The body wins, mirroring parentSessionId;
+ * 2. failing that, an already-RESOLVED parent session id. A create request that names
+ *    the session that spawned it came from an agent by construction: nothing in the
+ *    browser UI sets lineage. This is what still labels workers spawned by a stale
+ *    skill copy or by hand-rolled curl that only carries the lineage header.
+ *
+ * ⚠️ Decoration, like parentSessionId: never an ownership or permission signal, and
+ * never a reason to fail a spawn. An unrecognised origin token is dropped by
+ * `normalizeAgentOrigin` rather than rejected.
+ */
+export function resolveAgentCaseOrigin(
+  req: FastifyRequest,
+  bodyValue: string | undefined,
+  resolvedParentSessionId: string | undefined
+): string | undefined {
+  const header = req.headers['x-codeman-agent-origin'];
+  const raw = bodyValue ?? (Array.isArray(header) ? header[0] : header);
+  return normalizeAgentOrigin(raw) ?? (resolvedParentSessionId ? AGENT_ORIGIN_SPAWNED_BY_SESSION : undefined);
+}
+
 /**
 * Parse and validate a request body against a Zod schema, or throw a structured 400 error.
 * Replaces the repeated pattern: `const r = Schema.safeParse(body); if (!r.success) return createErrorResponse(...)`.
@@ -13,7 +13,15 @@ import fs from 'node:fs/promises';
 import { join, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import type { ApiResponse, CaseInfo, DockerHost, RemoteSessionInfo, SessionDocker, SessionMode } from '../../types.js';
+import type {
+  AgentCaseSummary,
+  ApiResponse,
+  CaseInfo,
+  DockerHost,
+  RemoteSessionInfo,
+  SessionDocker,
+  SessionMode,
+} from '../../types.js';
 import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../../types.js';
 import {
  CreateCaseSchema,
@@ -42,6 +50,7 @@ import {
 } from '../../git-clone.js';
 import type { GitRemoteProbe, GitUrlParse } from '../../git-clone.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
+import { readAgentCaseMarker, type AgentCaseMarker } from '../../agent-case-marker.js';
 import { settingsWriteBlocker, writeHooksConfig } from '../../hooks-config.js';
 import {
  canAccessOwned,
@@ -144,6 +153,21 @@ function repoShipsClaudeSettings(casePath: string): boolean {
  return ['settings.json', 'settings.local.json'].some((file) => existsSync(join(casePath, '.claude', file)));
 }

+/**
+ * Project a case's marker onto the wire shape `CaseInfo.agentCreated` carries.
+ * `owner` stays server-side: the listings are already owner-scoped, and it is not
+ * something the case list needs to publish.
+ */
+function agentCreatedInfo(marker: AgentCaseMarker): NonNullable<CaseInfo['agentCreated']> {
+  return {
+    createdAt: marker.createdAt,
+    createdBy: marker.createdBy,
+    ...(marker.parentSessionId ? { parentSessionId: marker.parentSessionId } : {}),
+    ...(marker.parentSessionName ? { parentSessionName: marker.parentSessionName } : {}),
+    ...(marker.mode ? { mode: marker.mode } : {}),
+  };
+}
+
 /** Read and parse linked-cases.json, returning empty object on missing/invalid file. */
 async function readLinkedCases(): Promise<Record<string, string>> {
  return readJsonConfig<Record<string, string>>(LINKED_CASES_FILE, 'linked cases', {});
@@ -222,11 +246,16 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
      const entries = await fs.readdir(listBase, { withFileTypes: true });
      for (const e of entries) {
        if (e.isDirectory() && SAFE_CASE_NAME.test(e.name)) {
+          const casePath = join(listBase, e.name);
+          // Only a directory Codeman scaffolded for an agent spawn carries a marker,
+          // so this stays absent for every human-created, linked or cloned case.
+          const marker = await readAgentCaseMarker(casePath);
          cases.push({
            name: e.name,
-            path: join(listBase, e.name),
-            hasClaudeMd: existsSync(join(listBase, e.name, 'CLAUDE.md')),
+            path: casePath,
+            hasClaudeMd: existsSync(join(casePath, 'CLAUDE.md')),
            location: 'local',
+            ...(marker ? { agentCreated: agentCreatedInfo(marker) } : {}),
          });
        }
      }
@@ -326,6 +355,61 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
    return cases;
  });

+  // ========== Agent-created cases (cleanup listing) ==========
+
+  /**
+   * The scratch workspaces agent workers left behind, newest first.
+   *
+   * A long orchestration creates one case directory per worker, and deleting the
+   * sessions does not remove them, so without this the only way to tell an agent's
+   * `alpha`/`beta` from a real project was to remember which was which. Reads the same
+   * marker `GET /api/cases` exposes and adds the two facts a human needs before
+   * deleting a directory: whether a live session is still working in it, and when it
+   * was last touched.
+   *
+   * ⚠️ Read-only on purpose: removal goes through the existing `DELETE /api/cases/:name`,
+   * one name at a time, so this file keeps exactly one recursive-delete path. Scoped by
+   * construction — it only ever walks the caller's own case space.
+   */
+  app.get('/api/cases/agent-created', async (req): Promise<ApiResponse<{ cases: AgentCaseSummary[] }>> => {
+    const user = getAuthUser(req);
+    const listBase = resolveCasesDir(user);
+    const inUsePaths = new Set(
+      Array.from(ctx.sessions.values())
+        .filter((session) => canAccessOwned(user, session.owner))
+        .map((session) => session.workingDir)
+    );
+
+    let entries;
+    try {
+      entries = await fs.readdir(listBase, { withFileTypes: true });
+    } catch {
+      return { success: true, data: { cases: [] } }; // case space not created yet
+    }
+
+    const summaries: AgentCaseSummary[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !SAFE_CASE_NAME.test(entry.name)) continue;
+      const casePath = join(listBase, entry.name);
+      const marker = await readAgentCaseMarker(casePath);
+      if (!marker) continue;
+      const modifiedAt = await fs
+        .stat(casePath)
+        .then((stat) => stat.mtime.toISOString())
+        .catch(() => undefined);
+      summaries.push({
+        name: entry.name,
+        path: casePath,
+        ...agentCreatedInfo(marker),
+        inUse: inUsePaths.has(casePath),
+        ...(modifiedAt ? { modifiedAt } : {}),
+      });
+    }
+
+    summaries.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    return { success: true, data: { cases: summaries } };
+  });
+
  app.post('/api/cases', async (req): Promise<ApiResponse<{ case: { name: string; path: string } }>> => {
    const { name, description } = parseBody(CreateCaseSchema, req.body);

@@ -76,12 +76,14 @@ import {
  ownerFor,
  parseBody,
  persistAndBroadcastSession,
+  resolveAgentCaseOrigin,
  resolveCasesDir,
  resolveParentSessionId,
  sessionCapacityMessage,
  SETTINGS_PATH,
  validatePathWithinBase,
 } from '../route-helpers.js';
+import { buildAgentCaseMarker, writeAgentCaseMarker } from '../../agent-case-marker.js';
 import { canUsernameRunPrivilegedCommands, resolveClaudeModeForUsername } from '../../user-store.js';
 import { enabledClis, getCli } from '../../config/cli-registry/registry.js';
 import { resolveCliLaunchError } from '../../utils/cli-launcher.js';
@@ -2973,8 +2975,13 @@ export function registerSessionRoutes(
      envOverrides,
      effort,
      parentSessionId,
+      agentOrigin,
    } = parseBody(QuickStartSchema, req.body);

+    // Resolved ONCE here: the same value labels a case directory this request creates
+    // (agent-case-marker.ts) and draws the tab lineage line on the session below.
+    const qsParentSessionId = resolveParentSessionId(ctx, req, parentSessionId, owner);
+
    // Multi-user: shell mode is arbitrary host-account execution, gated by the grant.
    // Resolve the owner's grant from the store so a GRANTED regular user is not wrongly denied.
    if (getCli(mode)?.capabilities.privilegedCommandGate && !(await canUsernameRunPrivilegedCommands(owner))) {
@@ -3220,6 +3227,26 @@ export function registerSessionRoutes(
          await writeHooksConfig(resolvedCasePath);
        }

+        // Label a directory an AGENT asked us to create, so the scratch workspaces a
+        // long orchestration leaves behind can be told apart from the user's real
+        // projects later (see agent-case-marker.ts). This is the only branch that may
+        // write it: it is the only one that creates the directory, and a pre-existing
+        // case must never be labelled. Best-effort — a failed marker must not fail the
+        // spawn it decorates.
+        const qsAgentOrigin = resolveAgentCaseOrigin(req, agentOrigin, qsParentSessionId);
+        if (qsAgentOrigin) {
+          await writeAgentCaseMarker(
+            resolvedCasePath,
+            buildAgentCaseMarker({
+              createdBy: qsAgentOrigin,
+              parentSessionId: qsParentSessionId,
+              parentSessionName: qsParentSessionId ? ctx.sessions.get(qsParentSessionId)?.name : undefined,
+              mode,
+              owner,
+            })
+          );
+        }
+
        ctx.broadcast(SseEvent.CaseCreated, { name: caseName, path: resolvedCasePath });
      } catch (err) {
        return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to create case: ${getErrorMessage(err)}`);
@@ -3353,7 +3380,7 @@ export function registerSessionRoutes(
      docker,
      resumeSessionId: dockerResumeId,
      tmuxHistoryLimit: qsTerminalHistoryConfig.tmuxHistoryLimit,
-      parentSessionId: resolveParentSessionId(ctx, req, parentSessionId, owner),
+      parentSessionId: qsParentSessionId,
    });

    // Auto-detect completion phrase from CLAUDE.md BEFORE broadcasting
@@ -1025,6 +1025,16 @@ export const QuickStartSchema = z.object({
  envOverrides: safeEnvOverridesSchema,
  /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
  effort: effortLevelSchema,
+  /**
+   * Who is spawning this worker (`codeman-skill` from the packaged agent skill), or,
+   * equivalently, the `X-Codeman-Agent-Origin` header; the body wins when both are
+   * present. Used ONLY to label a case directory this request CREATES as an agent
+   * scratch workspace, so it can be found and cleaned up later — see
+   * `src/agent-case-marker.ts`. Never a permission signal, and an unrecognised token
+   * is dropped rather than rejected. `POST /api/sessions` has no equivalent field
+   * because it takes an existing `workingDir` and so never creates a directory to label.
+   */
+  agentOrigin: z.string().max(64).optional(),
 });

 // ========== Hook Events ==========
@@ -81,7 +81,7 @@ import { RunSummaryTracker } from '../run-summary.js';
 import { PlanOrchestrator } from '../plan-orchestrator.js';
 import { OrchestratorLoop } from '../orchestrator-loop.js';
 import { getLifecycleLog } from '../session-lifecycle-log.js';
-import { applyWorkspaceHooks } from '../hooks-config.js';
+import { applyWorkspaceHooks, pruneAgentSessionPreambles, removeAgentSessionPreamble } from '../hooks-config.js';
 import { PushSubscriptionStore } from '../push-store.js';
 import webpush from 'web-push';
 import { SseStreamManager } from './sse-stream-manager.js';
@@ -1370,6 +1370,12 @@ export class WebServer extends EventEmitter {
          // Best-effort cleanup
        }
      }
+      // Drop the agent skill's preamble cache for this session (seeded at create).
+      // killMux only: a detach leaves the session recoverable, and its agent would
+      // come back to a loader whose file we deleted.
+      if (killMux) {
+        void removeAgentSessionPreamble(sessionId);
+      }
      await session.stop(killMux);
      this.sessions.delete(sessionId);
      // Only remove from state.json if we're also killing the mux session.
@@ -2514,6 +2520,19 @@ export class WebServer extends EventEmitter {
      }
    }

+    // Sweep agent preamble caches whose sessions are gone (see
+    // pruneAgentSessionPreambles). Once per boot, after restore, so every session this
+    // instance owns is in the keep set. Best-effort and off the startup critical path.
+    if (!this.testMode) {
+      void pruneAgentSessionPreambles(this.sessions.keys())
+        .then((removed) => {
+          if (removed > 0) console.log(`[agent-skill] pruned ${removed} stale preamble cache file(s)`);
+        })
+        .catch(() => {
+          /* best-effort */
+        });
+    }
+
    // Bound disk use under heavy paste-image traffic: delete `paste-*` files
    // older than 7 days from each live session's .claude-images/ hourly.
    if (!this.testMode) {