@gaia-ai/addon-herdr 0.7.0 → 0.8.0

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutorCapabilities, ExecutorPlugin, GaiaExecutor, HookContext, HookName, HookResult, SpawnedSession, SpawnRunInput } from '@gaia-ai/conductor/contract';
+import type { ExecutorCapabilities, ExecutorPlugin, GaiaExecutor, HookContext, HookName, HookResult, SpawnedSession, SpawnRunInput, WorktreeTeardown } from '@gaia-ai/conductor/contract';
 import type { ConductorLogger } from '@gaia-ai/core';
 import { type HerdrExecutorOptions } from './config.js';
 import { type HerdrExec } from './pane-layout.js';
@@ -87,11 +87,21 @@ export declare class HerdrExecutor implements GaiaExecutor {
      *   1. restores owner-write (Drupal hardens web/sites/default 0555 +
      *      settings.php 0444 — chmod-restorable by the owning user, no sudo);
      *   2. `git worktree remove --force <path>` from the PARENT repo root, which
-     *      unlinks the directory AND drops the `.git/worktrees/<name>` entry;
+     *      unlinks the directory AND drops the `.git/worktrees/<name>` entry —
+     *      but ONLY when the path really is a registered worktree (GAIA-293):
+     *      against an unregistered path git exits 128 and the shared exec helper
+     *      logs `ERROR: exec failed` for a condition this code expects and
+     *      handles. The guard lives here rather than at the caller because this
+     *      method has a second call site (the path resolved via
+     *      {@link findGitWorktree});
      *   3. guarantees the directory is gone (a raw force-remove) in case git
-     *      refused (the path was never a registered worktree) — a no-op if git
-     *      already removed it;
+     *      refused or was skipped — a no-op if git already removed it;
      *   4. prunes the repo so any now-stale admin entry is swept.
+     *
+     * Returns whether the directory is gone afterwards. A reclaim that cannot
+     * remove it REPORTS instead of throwing (GAIA-293, spec D5): the raw EACCES
+     * used to propagate all the way out of {@link removeWorktree} and reach the
+     * reaper as an opaque exception.
      */
     private gitAwareRemove;
     /**
@@ -99,10 +109,40 @@ export declare class HerdrExecutor implements GaiaExecutor {
      * persisted, the PARENT repo's `git worktree list` still knows it (GAIA-141
      * RC-2 — the ~28 never-touched leftovers). Resolve the lost worktree's on-disk
      * path there, preferring an exact `worktreePath` match, then a branch match;
-     * never the main worktree (the repo root itself). Returns null when nothing
-     * matches. Best-effort: a git failure resolves to null.
+     * never the main worktree. Returns null when nothing matches. Best-effort: a
+     * git failure resolves to null.
+     *
+     * `cwd` is only where git is RUN. The main worktree is excluded by git's own
+     * porcelain ordering (it is always the first record) rather than by comparing
+     * against `cwd`, because the two coincide only when a parent root is
+     * configured. Without one the probe falls back to running git inside the
+     * worktree itself, and a `path !== cwd` filter then dropped the very entry
+     * being asked about — so `registered: true` was unreachable for a rootless
+     * executor (GAIA-293 review, finding 1). The configured root is excluded too,
+     * belt and braces, so a caller that anchors elsewhere still never resolves the
+     * main checkout as a ticket worktree.
      */
     private findGitWorktree;
+    /**
+     * Ask — passively — whether this worktree still exists, in BOTH dimensions
+     * that can come apart (GAIA-293): git's registration, and the directory on
+     * disk. The reported failure was exactly a case where they disagreed — the
+     * directory was there, the registration was not — so a single-dimension
+     * check cannot decide what to do.
+     *
+     * Passive by construction: it writes nothing, calls no herdr, and NEVER
+     * throws. A git failure yields `registered: false`, degrading the verdict to
+     * the on-disk answer rather than failing the teardown.
+     *
+     * The persisted `worktreePath` is the stable key and wins when given;
+     * `registered` then describes THAT path, never a branch match pointing
+     * somewhere else (the checked-out branch is mutable — GAIA-114).
+     *
+     * git is run at the configured parent root when there is one, else inside the
+     * worktree itself — `git worktree list` enumerates the whole repo from any of
+     * its worktrees, so the rootless answer is the same list.
+     */
+    private probeWorktree;
     /**
      * GAIA-166 focus guard. herdr's `worktree remove` deletes the ticket
      * worktree's on-disk directory; if that workspace is the CURRENTLY FOCUSED
@@ -131,20 +171,26 @@ export declare class HerdrExecutor implements GaiaExecutor {
      * mean "error"; it means herdr no longer tracks this ticket's worktree. When
      * herdr has lost track, teardown is resolved off git itself (never a foreign
      * worktree), git-awarely so no `.git/worktrees/<name>` metadata is orphaned
-     * (GAIA-141 RC-1):
-     *   - `worktreePath` still on disk → reclaim it git-awarely;
-     *   - `worktreePath` known but gone from disk → already torn down; sweep any
-     *     orphaned metadata and report verified;
-     *   - `worktreePath` unknown → resolve the lost worktree via the parent repo's
-     *     `git worktree list` (GAIA-141 RC-2) and reclaim it git-awarely.
+     * (GAIA-141 RC-1). Since GAIA-293 that resolution starts by ASKING — a passive
+     * {@link probeWorktree} reads both dimensions of existence and the four cases
+     * branch explicitly:
+     *   - neither registered nor on disk → nothing to do at all;
+     *   - registered but gone from disk → sweep the prunable admin entry;
+     *   - on disk but not registered → reclaim the directory, WITHOUT asking git
+     *     to remove a worktree it does not know (the bogus `ERROR: exec failed`);
+     *   - both → reclaim it git-awarely, `git worktree remove` included.
+     * A path that resolves in NEITHER dimension is not "absent" — it is
+     * unresolved, and still reported `unverified` (GAIA-141 RC-2).
      *
-     * Returns whether the teardown was VERIFIED on THIS host: `true` when the
-     * worktree is gone (removed by us, an on-disk orphan reclaimed, or confirmed
-     * already absent), `false` ONLY when nothing was resolvable and the teardown
-     * could not be verified — the reaper then leaves the ticket on its work list
-     * for a later retry instead of falsely flagging it cleaned (GAIA-141 RC-2).
+     * Reports what the teardown DID (GAIA-293): `removed` when the worktree is
+     * gone because this host removed it (or reclaimed an on-disk orphan, or swept
+     * the prunable admin entry it left behind), `already_absent` when a RESOLVED
+     * worktree existed in neither dimension, and `unverified` ONLY when nothing
+     * was resolvable or the directory could not be reclaimed — the reaper then
+     * leaves the ticket on its work list for a later retry instead of falsely
+     * flagging it cleaned (GAIA-141 RC-2).
      */
-    removeWorktree(branch: string, worktreePath?: string): Promise<boolean>;
+    removeWorktree(branch: string, worktreePath?: string): Promise<WorktreeTeardown>;
     startRun(input: SpawnRunInput): Promise<SpawnedSession>;
     /** Best-effort cleanup: close only the just-created tab. Swallows errors. */
     private rollback;

package/dist/src/index.js

@@ -326,43 +326,78 @@ export class HerdrExecutor {
      *   1. restores owner-write (Drupal hardens web/sites/default 0555 +
      *      settings.php 0444 — chmod-restorable by the owning user, no sudo);
      *   2. `git worktree remove --force <path>` from the PARENT repo root, which
-     *      unlinks the directory AND drops the `.git/worktrees/<name>` entry;
+     *      unlinks the directory AND drops the `.git/worktrees/<name>` entry —
+     *      but ONLY when the path really is a registered worktree (GAIA-293):
+     *      against an unregistered path git exits 128 and the shared exec helper
+     *      logs `ERROR: exec failed` for a condition this code expects and
+     *      handles. The guard lives here rather than at the caller because this
+     *      method has a second call site (the path resolved via
+     *      {@link findGitWorktree});
      *   3. guarantees the directory is gone (a raw force-remove) in case git
-     *      refused (the path was never a registered worktree) — a no-op if git
-     *      already removed it;
+     *      refused or was skipped — a no-op if git already removed it;
      *   4. prunes the repo so any now-stale admin entry is swept.
+     *
+     * Returns whether the directory is gone afterwards. A reclaim that cannot
+     * remove it REPORTS instead of throwing (GAIA-293, spec D5): the raw EACCES
+     * used to propagate all the way out of {@link removeWorktree} and reach the
+     * reaper as an opaque exception.
      */
-    async gitAwareRemove(path) {
+    async gitAwareRemove(path, registered) {
         restoreWritable(path);
         const root = this.gitRoot(path);
-        try {
-            await this.runGit(['worktree', 'remove', '--force', path], root);
-        }
-        catch {
-            // Not a registered worktree (or git refused) — reclaim the dir directly.
+        if (registered) {
+            try {
+                await this.runGit(['worktree', 'remove', '--force', path], root);
+            }
+            catch (err) {
+                // Registered yet refused — genuinely unexpected. Say so, then reclaim
+                // the directory directly below.
+                this.logger.warn({ path, err: String(err) }, 'git worktree remove failed on a registered worktree');
+            }
         }
         if (existsSync(path)) {
-            forceRemoveDir(path);
+            try {
+                forceRemoveDir(path);
+            }
+            catch (err) {
+                // GAIA-293 (spec D5): a leftover we cannot unlink — most likely
+                // foreign-owned (a container wrote it under another uid), which chmod
+                // cannot repair. Name the failing step; the reaper retries.
+                this.logger.warn({ path, err: String(err) }, 'worktree directory reclaim failed');
+                return false;
+            }
         }
         await this.pruneWorktrees(root);
+        return true;
     }
     /**
      * When herdr has lost track of a worktree and its `worktreePath` was never
      * persisted, the PARENT repo's `git worktree list` still knows it (GAIA-141
      * RC-2 — the ~28 never-touched leftovers). Resolve the lost worktree's on-disk
      * path there, preferring an exact `worktreePath` match, then a branch match;
-     * never the main worktree (the repo root itself). Returns null when nothing
-     * matches. Best-effort: a git failure resolves to null.
+     * never the main worktree. Returns null when nothing matches. Best-effort: a
+     * git failure resolves to null.
+     *
+     * `cwd` is only where git is RUN. The main worktree is excluded by git's own
+     * porcelain ordering (it is always the first record) rather than by comparing
+     * against `cwd`, because the two coincide only when a parent root is
+     * configured. Without one the probe falls back to running git inside the
+     * worktree itself, and a `path !== cwd` filter then dropped the very entry
+     * being asked about — so `registered: true` was unreachable for a rootless
+     * executor (GAIA-293 review, finding 1). The configured root is excluded too,
+     * belt and braces, so a caller that anchors elsewhere still never resolves the
+     * main checkout as a ticket worktree.
      */
-    async findGitWorktree(root, branch, worktreePath) {
+    async findGitWorktree(cwd, branch, worktreePath) {
         let output;
         try {
-            output = await this.runGit(['worktree', 'list', '--porcelain'], root);
+            output = await this.runGit(['worktree', 'list', '--porcelain'], cwd);
         }
         catch {
             return null;
         }
-        const candidates = parseGitWorktreePorcelain(output).filter((e) => normPath(e.path) !== normPath(root));
+        const mainRoot = this.options.root;
+        const candidates = parseGitWorktreePorcelain(output).filter((e, i) => i > 0 && (!mainRoot || normPath(e.path) !== normPath(mainRoot)));
         if (worktreePath) {
             const want = normPath(worktreePath);
             const byPath = candidates.find((e) => normPath(e.path) === want);
@@ -372,6 +407,34 @@ export class HerdrExecutor {
         }
         return candidates.find((e) => e.branch === branch)?.path ?? null;
     }
+    /**
+     * Ask — passively — whether this worktree still exists, in BOTH dimensions
+     * that can come apart (GAIA-293): git's registration, and the directory on
+     * disk. The reported failure was exactly a case where they disagreed — the
+     * directory was there, the registration was not — so a single-dimension
+     * check cannot decide what to do.
+     *
+     * Passive by construction: it writes nothing, calls no herdr, and NEVER
+     * throws. A git failure yields `registered: false`, degrading the verdict to
+     * the on-disk answer rather than failing the teardown.
+     *
+     * The persisted `worktreePath` is the stable key and wins when given;
+     * `registered` then describes THAT path, never a branch match pointing
+     * somewhere else (the checked-out branch is mutable — GAIA-114).
+     *
+     * git is run at the configured parent root when there is one, else inside the
+     * worktree itself — `git worktree list` enumerates the whole repo from any of
+     * its worktrees, so the rootless answer is the same list.
+     */
+    async probeWorktree(branch, worktreePath) {
+        const cwd = this.options.root ?? worktreePath ?? null;
+        const gitPath = cwd
+            ? await this.findGitWorktree(cwd, branch, worktreePath)
+            : null;
+        const path = worktreePath ?? gitPath;
+        const registered = gitPath !== null && path !== null && normPath(gitPath) === normPath(path);
+        return { registered, onDisk: path !== null && existsSync(path), path };
+    }
     /**
      * GAIA-166 focus guard. herdr's `worktree remove` deletes the ticket
      * worktree's on-disk directory; if that workspace is the CURRENTLY FOCUSED
@@ -432,50 +495,62 @@ export class HerdrExecutor {
      * mean "error"; it means herdr no longer tracks this ticket's worktree. When
      * herdr has lost track, teardown is resolved off git itself (never a foreign
      * worktree), git-awarely so no `.git/worktrees/<name>` metadata is orphaned
-     * (GAIA-141 RC-1):
-     *   - `worktreePath` still on disk → reclaim it git-awarely;
-     *   - `worktreePath` known but gone from disk → already torn down; sweep any
-     *     orphaned metadata and report verified;
-     *   - `worktreePath` unknown → resolve the lost worktree via the parent repo's
-     *     `git worktree list` (GAIA-141 RC-2) and reclaim it git-awarely.
+     * (GAIA-141 RC-1). Since GAIA-293 that resolution starts by ASKING — a passive
+     * {@link probeWorktree} reads both dimensions of existence and the four cases
+     * branch explicitly:
+     *   - neither registered nor on disk → nothing to do at all;
+     *   - registered but gone from disk → sweep the prunable admin entry;
+     *   - on disk but not registered → reclaim the directory, WITHOUT asking git
+     *     to remove a worktree it does not know (the bogus `ERROR: exec failed`);
+     *   - both → reclaim it git-awarely, `git worktree remove` included.
+     * A path that resolves in NEITHER dimension is not "absent" — it is
+     * unresolved, and still reported `unverified` (GAIA-141 RC-2).
      *
-     * Returns whether the teardown was VERIFIED on THIS host: `true` when the
-     * worktree is gone (removed by us, an on-disk orphan reclaimed, or confirmed
-     * already absent), `false` ONLY when nothing was resolvable and the teardown
-     * could not be verified — the reaper then leaves the ticket on its work list
-     * for a later retry instead of falsely flagging it cleaned (GAIA-141 RC-2).
+     * Reports what the teardown DID (GAIA-293): `removed` when the worktree is
+     * gone because this host removed it (or reclaimed an on-disk orphan, or swept
+     * the prunable admin entry it left behind), `already_absent` when a RESOLVED
+     * worktree existed in neither dimension, and `unverified` ONLY when nothing
+     * was resolvable or the directory could not be reclaimed — the reaper then
+     * leaves the ticket on its work list for a later retry instead of falsely
+     * flagging it cleaned (GAIA-141 RC-2).
      */
     async removeWorktree(branch, worktreePath) {
         const entries = await this.listWorktrees();
         const entry = resolveWorktreeEntry(entries, branch, worktreePath);
         if (!entry) {
-            // herdr no longer tracks it. Resolve teardown off git, never a foreign
-            // worktree, and git-awarely so no `.git/worktrees/<name>` is orphaned.
-            if (worktreePath && existsSync(worktreePath)) {
-                await this.gitAwareRemove(worktreePath);
-                return true;
-            }
-            if (worktreePath) {
-                // Path known but already gone from disk → verified (idempotent) teardown;
-                // still sweep any orphaned metadata it left behind.
-                if (this.options.root) {
-                    await this.pruneWorktrees(this.options.root);
+            // herdr no longer tracks it. GAIA-293: ask before acting. An
+            // already-absent worktree is a FINISHED teardown, not a failure to retry
+            // — and running `git worktree remove` against an unregistered path is
+            // what produced the bogus `ERROR: exec failed` (git exits 128 on an
+            // expected, handled condition). herdr still tracking the worktree is
+            // itself evidence that something is there to release, which is why the
+            // probe governs only this lost-track path and the tracked path below
+            // keeps its behaviour unchanged.
+            const probe = await this.probeWorktree(branch, worktreePath);
+            if (probe.path) {
+                if (!probe.onDisk) {
+                    if (!probe.registered) {
+                        this.logger.info({ branch, worktreePath: probe.path }, 'worktree already absent — nothing to tear down');
+                        return 'already_absent';
+                    }
+                    // A prunable admin entry whose directory has vanished: the metadata
+                    // sweep IS the teardown here (GAIA-141).
+                    await this.pruneWorktrees(this.gitRoot(probe.path));
+                    return 'removed';
                 }
-                return true;
+                return (await this.gitAwareRemove(probe.path, probe.registered))
+                    ? 'removed'
+                    : 'unverified';
             }
-            // Path unknown (never persisted). The parent repo's git worktree list may
-            // still know the lost worktree — resolve + reclaim it (GAIA-141 RC-2).
+            // Nothing resolvable in either dimension — the path was never persisted
+            // and git does not know the branch either. Sweep pre-existing orphans,
+            // then report the teardown UNVERIFIED so the reaper retries rather than
+            // falsely cleaning (GAIA-141 RC-2). NOT `already_absent`: absence can
+            // only be claimed about a worktree that was actually located.
             if (this.options.root) {
-                const gitPath = await this.findGitWorktree(this.options.root, branch);
-                if (gitPath) {
-                    await this.gitAwareRemove(gitPath);
-                    return true;
-                }
-                // Nothing resolvable — sweep pre-existing orphans, then report the
-                // teardown UNVERIFIED so the reaper retries rather than falsely cleaning.
                 await this.pruneWorktrees(this.options.root);
             }
-            return false;
+            return 'unverified';
         }
         let workspaceId = entry.open_workspace_id ?? null;
         if (!workspaceId) {
@@ -509,7 +584,7 @@ export class HerdrExecutor {
         // stranded in a deleted cwd. If a needed focus switch can't be made safely,
         // abort UNVERIFIED so the reaper retries rather than stranding the user.
         if (!(await this.ensureFocusSafeToRemove(workspaceId))) {
-            return false;
+            return 'unverified';
         }
         // Drupal hardens web/sites/default (0555) and settings.php/.htaccess (0444);
         // herdr's remove performs the actual unlink and would hit EACCES on those
@@ -527,14 +602,14 @@ export class HerdrExecutor {
         // report the teardown UNVERIFIED (false) so the reaper retries instead of
         // falsely flagging the ticket cleaned.
         if (existsSync(entry.path)) {
-            return false;
+            return 'unverified';
         }
         // Sweep any orphaned `.git/worktrees/<name>` admin entries at the parent
         // root (this teardown's and any pre-existing prunable ones — GAIA-141).
         if (this.options.root) {
             await this.pruneWorktrees(this.options.root);
         }
-        return true;
+        return 'removed';
     }
     async startRun(input) {
         const branchName = input.ticket.branchName;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaia-ai/addon-herdr",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "GAIA herdr integration: spawn executor + per-ticket worktree workspace.",
   "type": "module",
   "license": "MIT",
@@ -20,10 +20,10 @@
     "directory": "gaia-cli/addons/herdr"
   },
   "dependencies": {
-    "@gaia-ai/addon-workspace-git": "^0.7.0"
+    "@gaia-ai/addon-workspace-git": "^0.8.0"
   },
   "peerDependencies": {
-    "@gaia-ai/conductor": "^0.7.0",
-    "@gaia-ai/core": "^0.7.0"
+    "@gaia-ai/conductor": "^0.8.0",
+    "@gaia-ai/core": "^0.8.0"
   }
 }