omp: agent resource hygiene (scratch, tidy, docks-kit-omp plugin) #89

Goal

Agents remove what they create, while removal of the home directory and / stays blocked. The owner uses only omp, so the Claude and Codex SoT files stay unchanged.

End state:

• docks-kit gains scratch (guarded temporary directories) and tidy (safe leftover sweep plus a read-only --report of other disk and memory use).
• bash.patterns denies the bulk-deletion forms that can empty the home directory (find -delete, find -exec rm, xargs rm, in every position).
• docks-kit sync omp materializes and links a kit-owned omp plugin, docks-kit-omp, with an extension (native tools scratch_new, scratch_remove, tidy_report; creation reminders; a stop check; the automatic sweep), the workspace-hygiene skill, and the /cleanup command.
• The current workstation backlog is reclaimed with owner confirmation, one ask per group.
• The open omp session in the docks repository receives the plan-lifecycle teardown change request through intercom and owns that change (owner instruction, 2026-10-21).

Fixed requirements:

• Temporary directories are removed only through docks-kit scratch remove or scratch_remove, both of which check paths in code.
• An agent may run git worktree remove --force -- <path> once, after checks; never --force twice.
• No new deny or prompt rules for nohup, setsid, disown, or docker; those are prompt rules, skill text, and reminders only.
• At a main-session start the plugin runs docks-kit tidy --apply in the background, at most once per 12 h. The sweep sends SIGTERM to orphaned processes in agent directories.

Mode: plan-and-implement

Research

Guards (SoT/.omp/config.yml, ompYaml.ts mergeBashPatterns, cli/test/lib/ompBashPatterns.ts):

• bash.patterns are anchored text globs; * matches any text including / and spaces, so no glob can express "inside the temporary directory". The merge emits kit denies first, so a kit allow never precedes a kit deny. omp CRITICAL_BASH_PATTERNS does not cover find, xargs, or docker.
• Today find <home> -delete, cd <home> && find . -delete, find ~ -type f -exec rm {} +, and find ~ -type f | xargs rm match no deny rule and run under yolo. cli/test/unit/ompBashPatterns.test.ts lists xargs rm, find . -delete, and find . -name '*.tmp' -exec rm {} + as ALLOWED.
• git worktree remove refuses the main worktree and unregistered paths; without --force it refuses untracked or modified files; ignored files do not block it.

Workstation state (measured 2026-10-21): one repository has 68 linked worktrees (46 merged, 10.4 GB), 72 merged local branches, and 1 stash. Agent-invented cache directories hold about 14.6 GB. The system temporary directory is tmpfs with 3.9 GB used. Package caches total about 12 GB; Trash holds 2.1 GB with GNOME remove-old-trash-files false. Docker is rootless with 10 exited containers (8 per-worktree MySQL stacks) and 7.7 GB build cache; two named volumes hold owner data. Nine omp processes use 3.1 GB, swap use is 6.4 GB. The user systemd is the subreaper that adopts orphans.

omp plugin system (omp 18.12.5; omp://plugin-manager-installer-plumbing.md, omp://marketplace.md, omp://skills/authoring-extensions.md, upstream test packages/coding-agent/test/discovery/omp-plugins.test.ts, can1357/oh-my-pi#1498):

• omp plugin link <dir> symlinks a local package into <plugins>/node_modules/<name> and adds an enabled lockfile entry. A package with package.json omp.extensions loads those modules, and its sibling skills/, commands/, tools/, hooks/, rules/, prompts/, and .mcp.json are discovered. omp -e <dir> loads it for one run.
• omp plugin list --json returns { npm, marketplace }; an npm row carries name, version, and path (the node_modules symlink).
• pi.registerTool({ name, label, description, parameters, execute }) with pi.zod schemas; default loadMode discoverable, default approval exec. Events: tool_result (toolName, input, content, isError; may return additionalContext; fires in subagents), session_stop (main only; may return { continue: true, additionalContext }; stop_hook_active marks a continuation; cap 8), session_start (ctx.agent.kind main or sub). Module state is shared per omp process; handlers have a 30 s budget.
• Current omp values: task.agentIdleTtlMs 420000, browser.idleCloseSec 1800.

Kit code:

• CLI registration: cli/src/main.ts (Command.withSubcommands plus the manual root listing) and cli/src/argv.ts COMMANDS. Positional action words follow commands/toolchain.ts. engine.ts bail(message, code) reports usage errors; process.exitCode = 1 reports failures.
• exec.ts spawnProcess returns { exitCode, stdout, stderr, error? } and ignores stderr by default; exec.ts p slash-joins paths. harnesses.ts engineHome resolves home. commands/omp.ts builds the overlay directory as p(home, ".cache", "docks-kit").
• ompPlugins.ts syncPlugins reads the inventory once (installedPluginIdsFromCli, npm map of name to version), runs commands through runPluginCommand, records failures with recordFailure, and prints [dry-run] lines without running omp in a dry run. ompFileDeploy.ts ensureDirectory creates mode 0700 directories. payload.ts exports payloadText, payloadPaths(prefix), and payloadDisplayPath.
• The SoT payload is an explicit list (cli/scripts/generate-sot-payload.ts TEXT_PAYLOAD_PATHS); cli/test/unit/payload.test.ts asserts every SoT/ file is listed. cli/tsconfig.json typechecks only the Claude bin/*.mjs SoT files today.
• Unit tests run on Linux, macOS, and Windows (.github/workflows/parity.yml). Goldens snapshot the deployed home tree (cli/test/goldens/mutation.json) and dry-run and root-listing output (cli/test/goldens/dryrun.json).

plan-lifecycle 0.14.1: yolo removes its worktree only after Merge now; plan-manager never removes the linked worktree or stops stacks and processes. Agent worktrees live under $XDG_DATA_HOME/agent-worktrees/<repo>/<slug>.

Decisions:

• Durable fix: code-checked removal (scratch remove, tidy) plus deny rules for bulk deletion. It replaces the current state where bulk deletion is allowed and cleanup is manual.
• The plugin source lives in SoT/.omp/plugin/, ships in the payload, and is materialized to ~/.docks-kit/omp-plugin (kit-owned, no backups) and linked with omp plugin link.
• Thresholds: worktree, stack, and orphan idle 24 h; report process age 12 h; scratch expiry 7 d; sweep interval 12 h; lock stale 1 h; log rotation 256 KiB; task.agentIdleTtlMs 120000; browser.idleCloseSec 600.
• tidy never passes --force to git worktree remove and never removes named volumes; docker rm --volumes removes anonymous volumes only.
• Deployment waits for a release: the owner runs docks-kit update. Do not sync omp from the checkout while the global docks-kit lacks the new commands.
• Process detection fails closed (plan review rounds 1 and 2). TidyHost.processes returns undefined when the host cannot list processes with their working directories. Linux reads ps -u <uid> -o pid=,ppid=,etimes=,rss=,comm=,args= (every process of the user, with or without a terminal) plus /proc/<pid>/cwd; macOS reads ps -x -U <uid> -o pid=,ppid=,etime=,rss=,comm=,args= (-x includes processes without a controlling terminal) plus lsof -nP -a -u <uid> -d cwd -Fpn; Windows and any failed probe give undefined. With undefined, planTidy creates no remove-worktree, stop-containers, stop-process, or remove-scratch action, keeps those candidates with the reason process list unavailable, and adds a note. Only remove-containers for a directory that is gone still runs.
• No command interpreter in the extension (plan review round 1). Every extension subprocess uses execFile or spawn without shell. The extension resolves docks-kit on PATH itself; on Windows it accepts only a resolved .exe and refuses a .cmd or .bat shim with the not-on-PATH error, so a tool argument never reaches cmd.exe.
• One sweep per interval across processes (plan review round 1). session_start claims tidy.stamp.claim with openSync(path, "wx"); a claim older than 60 s is stale and is replaced. Only the claim winner re-reads the stamp mtime, writes the stamp when sweepDue still holds, spawns docks-kit tidy --apply, and then releases the claim. A loser spawns nothing.
• Production rule (owner decision, 2026-10-21). Local workstation resources are always development, so docks-kit tidy and its automatic sweep stay as designed. Cleanup of a remote resource that an agent reaches through SSH or a provider CLI (for example wrangler, vercel, netlify, fly, supabase, kubectl, or a remote Docker host) runs only when its target is named local, development, dev, test, homolog, homologation, staging, or preview, the plan-lifecycle definition of non-production. Every other target is production: its cleanup runs only after an ask immediately before it, must be rare, and never runs in a subagent. A yolo invocation does not answer that ask. wrangler delete without --env acts on the top-level Worker, which is usually production. The rule goes into SoT/.omp/AGENTS.md, the workspace-hygiene skill, /cleanup, and the extension's remote-resource and stop reminders. The plan-lifecycle teardown request to the docks session carries the same rule.
• Local Docker endpoint only (plan review rounds 4 and 5). Ordinary Docker commands use DOCKER_HOST, DOCKER_CONTEXT, or the selected context, so a compose working-directory label inside agent territory does not prove a local daemon. Before any container rule, tidy reads the effective endpoint with docker context inspect --format '{{.Endpoints.docker.Host}}', which honors DOCKER_HOST and DOCKER_CONTEXT. It accepts only a local-machine endpoint: unix:///<absolute socket path> (Linux and macOS) or npipe:////./pipe/<name> (Windows; the . server name is the local machine). A pipe with any other server name, such as npipe:////host/pipe/docker_engine, names a remote server and is refused. Tidy passes the accepted endpoint as --host <endpoint> to every later Docker call in the plan, the apply, and the report. Any other endpoint (ssh://, tcp://, a remote pipe, an empty value, or a failed inspect) skips every container rule and the Docker report section, with the note docker endpoint <value> is not local; skipped container rules. A remote Docker resource then falls under the production rule above.
• Unreadable process directories (owner decision after code review round 1; plan review round 7). The kernel hides the working directory of some of the user's own processes; on this workstation 4 of 169: systemd --user, (sd-pam), and two ssh-agent. A process that exits during the probe is dropped from the list. A row named systemd, (sd-pam), ssh-agent, or gpg-agent stays in the list with an unknown working directory: it keeps its PID and name, so the subreaper rule still recognizes systemd, and it protects no directory, because no agent starts these processes from a worktree. Any other live process whose working directory cannot be read makes the process list unavailable, with the fail-closed result above.
• Code review round 1 repairs (plan review round 7). The shared removal function scratch.ts removeTemporaryPath, which scratch remove, scratch_remove, and the tidy scratch rule all use, deletes a path only through a trusted directory chain. Every directory from / down to the parent of the target, the allowed root included, must be owned by the user or by root, and must not be writable by group or others, except a sticky directory (such as /tmp) whose next path component the user or root owns. POSIX lets only the owner of an entry, the owner of a sticky directory, or root rename an entry in a sticky directory, and only a user who can write a directory can rename entries in it, so no other user can replace a directory on that chain after the check. A root whose own chain fails this rule is dropped. Windows has no POSIX owner bits, so these ownership checks do not apply there. The function also refuses a target equal to any allowed root (nested roots such as a TMPDIR inside /tmp), and it checks the final entry without trailing separators, so <link>/ is refused as a symbolic link. Tidy treats a path whose state it cannot read as unknown, never as absent. The tidy lock and the sweep claim carry an owner token, are released only by their owner, and replace a stale entry only while they hold a takeover mutex created with wx. The extension keeps Docker daemon options (--context, --host, DOCKER_HOST, DOCKER_CONTEXT) in cleanup commands and existence checks, and keeps a cd inside a subshell or a command substitution in that scope.

Detailed design (function signatures, rule order, refusal reasons, tests) is carried in the Steps rows below.

Steps

Acceptance

Do not touch

• SoT/.claude/ and SoT/.codex/ files.
• Named Docker volumes, the owner database containers, the existing stash, and running omp processes.
• Deployed files under ~/.omp/agent/: no ./docks-kit sync omp from the checkout before the release.
• The vendored unslop skill.

Open questions

Verification Results

Run on the linked branch, 2026-10-21, Linux workstation.

• gate: bun run check exit 0 on the reviewed head (83 test files passed, 1 skipped; 1210 tests passed, 10 skipped; dry-run goldens OK with 49 cases, mutation goldens OK with 73 cases). bun run check:generated passes. The mutation golden needed cli/test/lib/goldenExecution.ts readArgvLog to write the per-run home as <HOME>, because omp plugin link names a path under that home.
• runtime_posix: bun run test:runtime:posix exit 0.
• sync_dry_run: ./docks-kit sync omp --dry-run prints the four plugin cp lines and [dry-run] omp plugin link <home>/.docks-kit/omp-plugin; the kit plugin directory does not exist afterwards.
• scratch_smoke: the new directory has mode 700; remove printed removed <path>, exit 0, and the path is gone.
• scratch_refuse: the home directory and /tmp were refused as outside the roots (exit 1); a symbolic link was refused (is a symbolic link), and after the code review round 1 repair <link>/ is refused the same way, also for a link whose target is inside the scratch root; the link targets survived.
• tidy_dry and tidy_report: worktree, container, and branch counts were the same before and after (69, 11, 75). The report showed swap 7.2 GB, /tmp 4.0 GB, Docker build cache 9.0 GB (5.2 GB reclaimable), Bun cache 2.8 GB, Trash 2.0 GB with the gsettings hint, and 27 merged branches. Two smoke findings were fixed: the Processes section listed omp's own worker broker (now excluded with the sweep's protected-process check, with a regression case), and the --repo dry-run hint named docks-kit tidy --apply instead of docks-kit tidy --repo <repo> --apply.
• guard_smoke: find /tmp/docks-smoke-none -delete was blocked with Blocked by bash pattern: find *-delete*; printf x | xargs echo ran and printed x.
• plugin_smoke: scratch_new returned a tool-smoke-* path, scratch_remove printed removed <path>, and skill://workspace-hygiene opened with # Workspace hygiene; no tool-smoke-* directory remained.
• reminder_smoke: the session transcript contains You created the scratch directory and These resources from this session still exist:; the final answer named the kept directory with its reason.
• cleanup_command: omp -e SoT/.omp/plugin -p '/cleanup' expanded the command (the transcript contains Follow the workspace-hygiene skill), ran the read-only report, and changed no file. This print-mode check replaced the interactive list check: an interactive attempt selected omp's built-in /cleanse, which started a repair run that was stopped before it changed any file.
• sweep_smoke: after the owner approved the 4-action dry run, the plugin sweep ran from one -p session and wrote tidy.log within seconds, and tidy.stamp exists again. The log has 5 removals: the 4 approved worktrees (3 with their exited MySQL container) and event-intake-skill, which crossed the 24 h idle threshold in the 25 minutes between the dry run and the sweep. It was merged into origin/main and clean, so its commits stay in the repository; ignored files in that checkout are gone.
• Backlog, each group approved by the owner: tidy --repo removed 51 worktrees of backstage_wp_theme and 1 of site-manager (a fresh dry run before the apply showed no action outside the approved list); 21 agent-invented cache entries (about 8 GB) moved into the scratch root as legacy-<name>, with three entries that hold git checkouts excluded; 7973 old /tmp entries removed and /tmp fell from 4.2 GB to 0.65 GB (one entry refused: EACCES inside a container bind mount); 2 exited containers removed; docker builder prune --filter until=168h freed 0 B; pnpm store -1.3 GB, npm cache -0.4 GB, Bun cache cleared (2.8 GB), uv -13 MiB; 27 merged branches deleted; GNOME old trash and temp files removal enabled; Trash emptied.
• post_release: not run; it waits for the owner's docks-kit update after the release.
• Repairs after code review round 1 were smoke-tested again: scratch remove refused <link>/ for a link inside the scratch root and kept its target; the plugin tools removed tool-smoke2-* and ext-smoke2-*, and the transcript has the creation reminder; ./docks-kit tidy still plans on this workstation (no process list unavailable note).
• docks_issue: the docks session took the request. Plan plan-lifecycle: tear down what a plan created docks#83 and pull request plan-lifecycle: tear down what a plan created docks#84 (merged) add a Teardown section after Archive to the plan-lifecycle contract with the production rule; follow-up yolo: archive only on Merge now when the answer starts a new run docks#85 and docs(omp): record the home and root glob gap for plain file removal #86 (merged) fix the yolo landing step order. plan-lifecycle is not released yet (still 0.14.1).
• Pull request feat(omp): agent resource hygiene with scratch, tidy, and the docks-kit-omp plugin; release 0.21.0 #90 checks: check, lint, both goldens, and portable on macOS and Windows pass. portable (ubuntu-24.04) fails at bun audit on advisories published after main's last green run, in dev-only test dependencies (vitest 5.0.0 and vite 7.3.6), not in this change. By owner decision the fix ships first as its own pull request chore(deps): patch vitest and vite advisories (vitest 5.0.3, vite 7.3.7) #91 (vitest 5.0.3, vite 7.3.7); feat(omp): agent resource hygiene with scratch, tidy, and the docks-kit-omp plugin; release 0.21.0 #90 merges main after that.