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>

src/agent-case-marker.ts

@@ -0,0 +1,183 @@
+/**
+ * @fileoverview The marker file that records a case directory as one Codeman scaffolded
+ * FOR an agent-spawned session, so scratch worker workspaces can be told apart from the
+ * user's real projects long after the sessions that created them are gone.
+ *
+ * Why a file in the case directory rather than a central registry in `~/.codeman`:
+ * the thing being labelled is a directory on the user's disk, and the label has to
+ * survive everything that can happen to Codeman's own state (a wiped data dir, a
+ * different instance, a hand-moved case). A registry would also need stale-entry
+ * pruning and owner scoping of its own, while a marker is deleted by the same `rm -rf`
+ * that deletes the case, and is discoverable by a user who just runs `ls -a`.
+ *
+ * ⚠️ Written ONLY on the path that CREATES the directory (`POST /api/quick-start`'s
+ * `!existsSync` branch). A linked case, a cloned repo, a git worktree or any other
+ * pre-existing directory must never be labelled agent-created: the label drives a
+ * cleanup affordance, and mislabelling someone's repo there is the one failure mode
+ * that costs real work. `POST /api/sessions` takes an existing `workingDir` and so
+ * writes no marker at all, by construction.
+ *
+ * ⚠️ Reading is strict and total: anything that does not parse as a version-1 marker
+ * (truncated write, hand-edited junk, a user's unrelated file of the same name) reads
+ * as "not agent-created" rather than as a partially-trusted entry. A marker is
+ * metadata; deleting the file is the supported way to adopt a scratch case as a real
+ * one, which is what the `note` field written into it tells the user.
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/** Marker filename inside the case directory. Dot-prefixed so it stays out of the way. */
+export const AGENT_CASE_MARKER_FILE = '.codeman-agent-case.json';
+
+/** Current marker schema version. A marker of any other version reads as absent. */
+export const AGENT_CASE_MARKER_VERSION = 1;
+
+/**
+ * Origin recorded when a create request carried a resolvable spawning session but no
+ * explicit origin of its own (an agent driving the API by hand, or an older copy of
+ * the skill). Nothing in the browser UI sets lineage, so this really does mean "another
+ * session spawned this", not "a human clicked Run".
+ */
+export const AGENT_ORIGIN_SPAWNED_BY_SESSION = 'agent-session';
+
+/** Origin the packaged agent skill sends on its shared curl invocation. */
+export const AGENT_ORIGIN_CODEMAN_SKILL = 'codeman-skill';
+
+/** Longest accepted origin token (the value is echoed into the UI and the marker). */
+const MAX_ORIGIN_LENGTH = 32;
+
+/** Longest accepted free-text field read back out of a marker. */
+const MAX_MARKER_FIELD_LENGTH = 200;
+
+/** Lowercase token: what an origin may look like on the wire and on disk. */
+const AGENT_ORIGIN_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+
+/** Explains the file to whoever finds it in their case directory. */
+const MARKER_NOTE =
+  'Created by a Codeman agent worker (see the Manage tab in Add Case). ' +
+  'Delete this file to keep the case out of the agent-case cleanup list; ' +
+  'deleting the whole directory removes the case.';
+
+/**
+ * What a case directory records about the agent spawn that created it.
+ * Every field beyond `version`/`createdAt`/`createdBy` is decoration for the cleanup UI.
+ */
+export interface AgentCaseMarker {
+  version: typeof AGENT_CASE_MARKER_VERSION;
+  /** ISO timestamp of the spawn that created the directory. */
+  createdAt: string;
+  /** Who asked: `codeman-skill`, `agent-session`, or another caller's own token. */
+  createdBy: string;
+  /** Full id of the session that spawned the worker, when one resolved. */
+  parentSessionId?: string;
+  /** That session's display name at spawn time, so the user recognises it later. */
+  parentSessionName?: string;
+  /** Run mode the worker was started in (`claude`, `deepseek`, …). */
+  mode?: string;
+  /** Owner the case was created for, in multi-user mode. */
+  owner?: string;
+}
+
+/**
+ * Validate an origin token coming off the wire (`agentOrigin` body field or the
+ * `X-Codeman-Agent-Origin` header). Returns `undefined` for anything that is not a
+ * short lowercase token — the value reaches the UI and a JSON file, so it is
+ * allowlisted rather than escaped at each use.
+ */
+export function normalizeAgentOrigin(raw: unknown): string | undefined {
+  if (typeof raw !== 'string') return undefined;
+  const value = raw.trim().toLowerCase();
+  if (!value || value.length > MAX_ORIGIN_LENGTH) return undefined;
+  return AGENT_ORIGIN_PATTERN.test(value) ? value : undefined;
+}
+
+/** Trim an optional free-text marker field to something safe to store and render. */
+function normalizeField(raw: unknown): string | undefined {
+  if (typeof raw !== 'string') return undefined;
+  const value = raw.trim();
+  return value ? value.slice(0, MAX_MARKER_FIELD_LENGTH) : undefined;
+}
+
+/**
+ * Build a marker from a spawn's details. Pure, so the route can hand it straight to
+ * the writer and the tests can assert on the shape without touching a disk.
+ */
+export function buildAgentCaseMarker(input: {
+  createdBy: string;
+  createdAt?: Date;
+  parentSessionId?: string;
+  parentSessionName?: string;
+  mode?: string;
+  owner?: string;
+}): AgentCaseMarker {
+  const marker: AgentCaseMarker = {
+    version: AGENT_CASE_MARKER_VERSION,
+    createdAt: (input.createdAt ?? new Date()).toISOString(),
+    createdBy: normalizeAgentOrigin(input.createdBy) ?? AGENT_ORIGIN_SPAWNED_BY_SESSION,
+  };
+  const parentSessionId = normalizeField(input.parentSessionId);
+  const parentSessionName = normalizeField(input.parentSessionName);
+  const mode = normalizeField(input.mode);
+  const owner = normalizeField(input.owner);
+  if (parentSessionId) marker.parentSessionId = parentSessionId;
+  if (parentSessionName) marker.parentSessionName = parentSessionName;
+  if (mode) marker.mode = mode;
+  if (owner) marker.owner = owner;
+  return marker;
+}
+
+/**
+ * Parse marker JSON. Returns `null` for anything that is not a well-formed version-1
+ * marker, including a valid-JSON object of the wrong shape — see the strictness note
+ * in the file header.
+ */
+export function parseAgentCaseMarker(raw: string): AgentCaseMarker | null {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+
+  const record = value as Record<string, unknown>;
+  if (record.version !== AGENT_CASE_MARKER_VERSION) return null;
+
+  const createdAt = normalizeField(record.createdAt);
+  const createdBy = normalizeAgentOrigin(record.createdBy);
+  if (!createdAt || !createdBy || Number.isNaN(Date.parse(createdAt))) return null;
+
+  return buildAgentCaseMarker({
+    createdBy,
+    createdAt: new Date(createdAt),
+    parentSessionId: normalizeField(record.parentSessionId),
+    parentSessionName: normalizeField(record.parentSessionName),
+    mode: normalizeField(record.mode),
+    owner: normalizeField(record.owner),
+  });
+}
+
+/**
+ * Write the marker into `casePath`. Best-effort by design: the marker is metadata for
+ * a later cleanup, and a failed write must never fail the worker spawn that is the
+ * point of the request. Returns whether it landed.
+ */
+export async function writeAgentCaseMarker(casePath: string, marker: AgentCaseMarker): Promise<boolean> {
+  try {
+    const body = JSON.stringify({ ...marker, note: MARKER_NOTE }, null, 2);
+    await writeFile(join(casePath, AGENT_CASE_MARKER_FILE), `${body}\n`, 'utf-8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Read the marker out of `casePath`, or `null` if there isn't a valid one. */
+export async function readAgentCaseMarker(casePath: string): Promise<AgentCaseMarker | null> {
+  try {
+    return parseAgentCaseMarker(await readFile(join(casePath, AGENT_CASE_MARKER_FILE), 'utf-8'));
+  } catch {
+    return null;
+  }
+}

src/hooks-config.ts

@@ -1066,9 +1066,80 @@ export async function installAgentSkillInto(skillDir: string): Promise<AgentSkil
  */
 export async function seedAgentSessionPreamble(sessionId: string): Promise<void> {
   const content = await readFile(join(agentSkillSourceDir(), 'preamble.sh'), 'utf-8');
-  const cacheDir = process.env.XDG_CACHE_HOME || join(homedir(), '.cache');
-  await mkdir(cacheDir, { recursive: true });
-  await writeFile(join(cacheDir, `codeman-agent-${sessionId}.sh`), content, { mode: 0o600 });
+  await mkdir(agentPreambleCacheDir(), { recursive: true });
+  await writeFile(agentPreamblePath(sessionId), content, { mode: 0o600 });
+}
+
+/** Where the preamble caches live. One formula, shared by seed / remove / prune. */
+function agentPreambleCacheDir(): string {
+  return process.env.XDG_CACHE_HOME || join(homedir(), '.cache');
+}
+
+/** `codeman-agent-<sessionId>.sh` in that directory. */
+function agentPreamblePath(sessionId: string): string {
+  return join(agentPreambleCacheDir(), `codeman-agent-${sessionId}.sh`);
+}
+
+/** Matches exactly what seedAgentSessionPreamble writes, and nothing else in ~/.cache. */
+const AGENT_PREAMBLE_FILE_PATTERN = /^codeman-agent-(.+)\.sh$/;
+
+/** How long a preamble cache with no live session behind it is kept before the sweep takes it. */
+export const AGENT_PREAMBLE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Drop one session's preamble cache. Called when a session is deleted, which is the
+ * precise counterpart to seeding it at create: one file per claude session was being
+ * written and nothing ever removed them (236 leftovers measured on a working machine,
+ * the oldest three weeks old). Best-effort — a file that will not delete is litter,
+ * never a reason to fail a teardown.
+ */
+export async function removeAgentSessionPreamble(sessionId: string): Promise<void> {
+  await unlink(agentPreamblePath(sessionId)).catch(() => {});
+}
+
+/**
+ * Sweep preamble caches left by sessions that are gone: the delete path above covers
+ * an orderly teardown, and this covers everything else (a crash, a killed server, a
+ * session deleted by an older build, another instance's leftovers).
+ *
+ * ⚠️ Two guards, and both matter: a file whose session is in `keepSessionIds` is never
+ * touched however old it is, and everything else needs `maxAgeMs` of age on top. A live
+ * session's cache is load-bearing — remove it and the skill's two-line loader fails its
+ * version check mid-run — and the age floor is what keeps a session belonging to
+ * ANOTHER instance (whose ids this process cannot see) out of the blast radius. Losing
+ * one is degradation rather than breakage: the §0 fallback block rewrites it.
+ *
+ * Returns how many it removed. Best-effort throughout; a missing cache dir is 0.
+ */
+export async function pruneAgentSessionPreambles(
+  keepSessionIds: Iterable<string>,
+  maxAgeMs: number = AGENT_PREAMBLE_MAX_AGE_MS
+): Promise<number> {
+  const cacheDir = agentPreambleCacheDir();
+  const keep = new Set(keepSessionIds);
+  const cutoff = Date.now() - maxAgeMs;
+  let removed = 0;
+
+  let entries: string[];
+  try {
+    entries = await readdir(cacheDir);
+  } catch {
+    return 0;
+  }
+
+  for (const entry of entries) {
+    const sessionId = AGENT_PREAMBLE_FILE_PATTERN.exec(entry)?.[1];
+    if (!sessionId || keep.has(sessionId)) continue;
+    const path = join(cacheDir, entry);
+    try {
+      if ((await lstat(path)).mtimeMs > cutoff) continue;
+      await unlink(path);
+      removed++;
+    } catch {
+      /* best-effort — a vanished or unreadable file is not our problem */
+    }
+  }
+  return removed;
 }
 
 /**

src/types/api.ts

@@ -157,6 +157,20 @@ export interface CaseInfo {
   location?: 'local' | 'linked-local' | 'remote' | 'docker';
   /** Whether this is a linked local folder */
   linked?: boolean;
+  /**
+   * Present when Codeman scaffolded this case directory for an AGENT-spawned session
+   * (the packaged skill's workers, or any spawn naming a parent session), read back
+   * from the case's own marker file — see `src/agent-case-marker.ts`. Absent for every
+   * case a human created, linked or cloned, which is what makes it usable as the
+   * "safe to clean up" signal in the Manage tab.
+   */
+  agentCreated?: {
+    createdAt: string;
+    createdBy: string;
+    parentSessionId?: string;
+    parentSessionName?: string;
+    mode?: string;
+  };
   /** Remote case metadata for display and session creation */
   remote?: {
     hostId: string;
@@ -192,6 +206,25 @@ export interface CaseInfo {
   };
 }
 
+/**
+ * One agent-created case as `GET /api/cases/agent-created` reports it: the cleanup
+ * view over `CaseInfo.agentCreated`, with the two facts a human needs before deleting
+ * a directory — whether an agent is still working in it, and when it was last touched.
+ */
+export interface AgentCaseSummary {
+  name: string;
+  path: string;
+  createdAt: string;
+  createdBy: string;
+  parentSessionId?: string;
+  parentSessionName?: string;
+  mode?: string;
+  /** A live session's working directory is this case — deleting it would pull the rug. */
+  inUse: boolean;
+  /** Directory mtime, so "nothing has touched this in a week" is answerable. */
+  modifiedAt?: string;
+}
+
 // ========== Error Handling Utilities ==========
 
 /**

src/web/public/session-ui.js

@@ -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', {

src/web/public/styles.css

@@ -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);

src/web/route-helpers.ts

@@ -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(...)`.

src/web/routes/case-routes.ts

@@ -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);
 

src/web/routes/session-routes.ts

@@ -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

src/web/schemas.ts

@@ -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 ==========

src/web/server.ts

@@ -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) {