chore(e2e): stop and reap leaked isolated Obsidian E2E instances (#197)

Add stop:e2e-obsidian + reap-on-start (worktree-gone marker) + orca.yaml archive hook so removed/merged worktrees no longer leak an Obsidian process tree or /private/tmp vault dir. Targets only this worktree's instance; never touches the shared dev vault, other worktrees, or quickadd. Tooling only; no plugin behavior change.

Author: chhoumann

AGENTS.md

@@ -141,6 +141,40 @@ npm run obsidian:e2e -- dev:errors
   `main.js` to exist). `start:e2e-obsidian` reloads PodNotes when it reuses a
   running instance, so the exported instance is never stale.
 
+### Stopping an isolated instance (avoid leaks)
+
+Each started instance is a real Obsidian process tree plus a private profile
+directory under `/private/tmp/podnotes-obsidian-e2e/<vault>-<hash>/`. Removing a
+worktree does **not** stop it, so a finished worktree would leak an Obsidian
+process tree and a `/private/tmp` directory. Stop it explicitly:
+
+```bash
+npm run stop:e2e-obsidian            # stop THIS worktree's instance + remove its tmp dir
+npm run stop:e2e-obsidian -- --dry-run   # show what would be stopped/removed
+npm run stop:e2e-obsidian -- --prune     # also reap orphaned instances (worktree gone)
+```
+
+The teardown identifies only this worktree's instance by its private
+`--user-data-dir` token (which contains a per-worktree hash), terminates that
+process tree (SIGTERM, then SIGKILL for stragglers), and removes its profile
+directory. It never touches the shared `dev` vault, other worktrees, or quickadd
+instances.
+
+Two layers keep instances from leaking, so you rarely need to run `stop` by hand:
+
+- **Orca archive hook** — `orca.yaml` defines a `scripts.archive` hook that runs
+  this teardown for the worktree being removed. Remove worktrees with
+  `orca worktree rm --worktree <selector> --run-hooks` so the hook fires (Orca
+  skips archive hooks without `--run-hooks`).
+- **Reap on next start** — `start:e2e-obsidian` and `obsidian:e2e` reap any
+  orphaned instance (one whose backing worktree no longer exists on disk, i.e.
+  it was removed) before launching, even if its Obsidian is still running. An
+  idle instance for a worktree that still exists is left alone so concurrent
+  workers can reuse it. Reaping scans the default profile root
+  (`/tmp/podnotes-obsidian-e2e`); instances started under a custom
+  `--profile-root` are only reaped by a start that uses that same root, so stop
+  those explicitly.
+
 ## Documentation
 Docs live in `docs/docs/` and are configured by `docs/mkdocs.yml`. Update docs
 with user-facing behavior changes, new commands, API changes, template syntax,

orca.yaml

@@ -0,0 +1,28 @@
+# Orca worktree lifecycle hooks for PodNotes.
+# See AGENTS.md > "Isolated worktree vault" for the full workflow.
+#
+# `archive` runs on `orca worktree rm --run-hooks`, before the worktree is
+# removed, with the cwd set to the worktree and $ORCA_WORKTREE_PATH pointing at
+# it. It stops this worktree's isolated Obsidian E2E instance and removes its
+# /private/tmp profile directory, so a merged or deleted worktree never leaks an
+# Obsidian process tree or vault dir. It targets only this worktree's instance
+# (matched by its private --user-data-dir token); the shared dev vault, other
+# worktrees, and quickadd instances are untouched.
+#
+# Notes:
+# - Orca skips this hook unless `--run-hooks` is passed; `start:e2e-obsidian`
+#   also reaps orphaned instances on the next start as a safety net.
+# - A failed archive hook is logged by Orca but never blocks removal. `|| true`
+#   keeps the archive log clean when no instance was ever started.
+# - This assumes the default per-worktree vault name (podnotes-<worktree>) and
+#   profile root. If you started an instance with a custom --vault or
+#   --profile-root, stop it with the matching
+#   `npm run stop:e2e-obsidian -- --vault <name> [--profile-root <path>]` before
+#   removing the worktree.
+# - The hook needs `node` on the GUI app's PATH (Orca runs it via non-login
+#   /bin/bash). It is guarded with `command -v node` so a missing node degrades
+#   to a no-op (the reap-on-next-start safety net then handles cleanup) instead
+#   of erroring.
+scripts:
+  archive: |
+    command -v node >/dev/null 2>&1 && node scripts/stop-obsidian-e2e-instance.mjs --worktree "$ORCA_WORKTREE_PATH" || true

package.json

@@ -16,6 +16,7 @@
 		"obsidian:e2e": "node scripts/obsidian-e2e-cli.mjs",
 		"provision:e2e-vault": "node scripts/provision-obsidian-e2e-vault.mjs",
 		"start:e2e-obsidian": "node scripts/start-obsidian-e2e-instance.mjs",
+		"stop:e2e-obsidian": "node scripts/stop-obsidian-e2e-instance.mjs",
 		"check:a11y": "svelte-check --fail-on-warnings",
 		"docs:build": "mkdocs build -f docs/mkdocs.yml -d site",
 		"docs:deploy": "npm run docs:build && npx wrangler pages deploy docs/site --project-name podnotes --branch master"

scripts/obsidian-e2e-cli.mjs

@@ -7,6 +7,7 @@ import {
 	launchObsidianInstance,
 	parseArgs as parseInstanceArgs,
 	prepareObsidianProfile,
+	reapStaleInstances,
 	reloadPodNotes,
 	resolveInstanceOptions,
 	trustVaultAndVerifyPodNotes,
@@ -165,6 +166,7 @@ async function main() {
 	const options = resolveInstanceOptions(
 		parseInstanceArgs(parsed.instanceArgs),
 	);
+	await reapStaleInstances(options);
 	await ensureObsidianInstance(options);
 	process.exitCode = await spawnObsidian(options, parsed.commandArgs);
 }

scripts/start-obsidian-e2e-instance.mjs

@@ -14,6 +14,10 @@ import {
 
 const execFileAsync = promisify(execFile);
 const DEFAULT_PROFILE_ROOT = "/tmp/podnotes-obsidian-e2e";
+// Sidecar written at the instance root recording which worktree the instance
+// belongs to. The teardown reaper reads it to reap an instance only once its
+// worktree is gone (a removed/merged worktree) — the reliable leak signal.
+export const INSTANCE_MARKER_FILE = "podnotes-e2e-instance.json";
 const DEFAULT_OBSIDIAN_APP = "Obsidian";
 const DEFAULT_OBSIDIAN_BIN = "obsidian";
 const READY_TIMEOUT_MS = 30_000;
@@ -168,6 +172,14 @@ export async function prepareObsidianProfile(options) {
 		},
 	});
 
+	// Record which worktree this instance belongs to so the teardown reaper can
+	// reap it once that worktree is removed (see INSTANCE_MARKER_FILE).
+	await writeJson(path.join(options.instancePath, INSTANCE_MARKER_FILE), {
+		worktreePath: options.worktreePath,
+		vaultName: options.vaultName,
+		vaultPath: options.vaultPath,
+	});
+
 	return {
 		obsidianJsonPath,
 		userDataPath,
@@ -406,6 +418,29 @@ function shellQuote(value) {
 	return `'${String(value).replaceAll("'", "'\\''")}'`;
 }
 
+// Self-healing safety net: before launching our own instance, reap any leaked
+// instances whose backing worktree is gone (e.g. removed on merge without the
+// orca archive hook running). Best-effort — a reap failure must never block a
+// start. The reaper is imported lazily so the static module graph stays acyclic
+// (the stop module imports our option resolver; we only need its reaper at
+// runtime). Logs go to stderr so `--print-env` keeps stdout to `export …` lines.
+export async function reapStaleInstances(options) {
+	try {
+		const { reapOrphanedInstances } = await import(
+			"./stop-obsidian-e2e-instance.mjs"
+		);
+		await reapOrphanedInstances({
+			profileRoot: options.profileRoot,
+			exceptInstancePath: options.instancePath,
+			log: console.error,
+		});
+	} catch (error) {
+		console.error(
+			`Skipping stale-instance reap: ${error instanceof Error ? error.message : error}`,
+		);
+	}
+}
+
 async function main() {
 	const rawOptions = parseArgs(process.argv.slice(2));
 	if (rawOptions.help) {
@@ -414,6 +449,7 @@ async function main() {
 	}
 
 	const options = resolveInstanceOptions(rawOptions);
+	await reapStaleInstances(options);
 	const provisionResult = await provisionVault(options);
 	const profileResult = await prepareObsidianProfile(options);
 	options.userDataPath = profileResult.userDataPath;