@shepai/cli 1.55.3 → 1.57.0

package/dist/packages/core/src/infrastructure/services/git/git-pr.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git-pr.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/git/git-pr.service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wEAAwE,CAAC;AAC5G,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,aAAa,EACb,cAAc,EACf,MAAM,wEAAwE,CAAC;AAOhF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,qBACa,YAAa,YAAW,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,YAAY;IAErE,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKxC,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuC9C,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKpD,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAWxD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAYvE,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAuClE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,GAAE,aAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IAUzF,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUnF,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAkBjE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAwCjF,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAWhF,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAevE,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWrF,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAW3F,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,oBAAoB;IAK5B,OAAO,CAAC,aAAa;CAiBtB"}
+{"version":3,"file":"git-pr.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/git/git-pr.service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wEAAwE,CAAC;AAC5G,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACb,MAAM,wEAAwE,CAAC;AAQhF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,qBACa,YAAa,YAAW,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,YAAY;IAErE,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKxC,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuC9C,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKpD,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAWxD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAYvE,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAuClE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,GAAE,aAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IAUzF,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUnF,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAkBjE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAwCjF,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAWhF,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAevE,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAkCpD,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWrF,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAW3F,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,oBAAoB;IAK5B,OAAO,CAAC,aAAa;CAiBtB"}

package/dist/packages/core/src/infrastructure/services/git/git-pr.service.js

@@ -203,6 +203,30 @@ let GitPrService = class GitPrService {
         const { stdout: logOutput } = await this.execFile('git', ['log', '--oneline', `${baseBranch}...HEAD`], { cwd });
         return this.parseDiffStat(diffStat, logOutput);
     }
+    async listPrStatuses(cwd) {
+        try {
+            const { stdout } = await this.execFile('gh', [
+                'pr',
+                'list',
+                '--json',
+                'number,state,url,headRefName',
+                '--state',
+                'all',
+                '--limit',
+                '100',
+            ], { cwd });
+            const prs = JSON.parse(stdout);
+            return prs.map((pr) => ({
+                number: pr.number,
+                state: this.normalizeGhState(pr.state),
+                url: pr.url,
+                headRefName: pr.headRefName,
+            }));
+        }
+        catch (error) {
+            throw this.parseGhError(error);
+        }
+    }
     async verifyMerge(cwd, featureBranch, baseBranch) {
         try {
             await this.execFile('git', ['merge-base', '--is-ancestor', featureBranch, baseBranch], {
@@ -230,6 +254,10 @@ let GitPrService = class GitPrService {
             return output;
         return `${output.slice(0, maxChars)}\n[Log truncated at ${maxChars} chars — full log available via gh run view ${runId}]`;
     }
+    normalizeGhState(state) {
+        const normalized = state.charAt(0).toUpperCase() + state.slice(1).toLowerCase();
+        return normalized;
+    }
     parseGitError(error) {
         const message = error instanceof Error ? error.message : String(error);
         const cause = error instanceof Error ? error : undefined;

package/dist/packages/core/src/infrastructure/services/ide-launchers/json-driven-ide-launcher.service.d.ts

@@ -17,7 +17,9 @@ export declare function resolvePlatformValue(value: string | Record<string, stri
 export declare class JsonDrivenIdeLauncherService implements IIdeLauncherService {
     private readonly editors;
     constructor();
-    launch(editorId: string, directoryPath: string): Promise<LaunchIdeResult>;
+    launch(editorId: string, directoryPath: string, options?: {
+        headless?: boolean;
+    }): Promise<LaunchIdeResult>;
     checkAvailability(editorId: string): Promise<boolean>;
 }
 //# sourceMappingURL=json-driven-ide-launcher.service.d.ts.map

package/dist/packages/core/src/infrastructure/services/ide-launchers/json-driven-ide-launcher.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-driven-ide-launcher.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/ide-launchers/json-driven-ide-launcher.service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EAChB,MAAM,8EAA8E,CAAC;AActF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAGnF;AAED,qBACa,4BAA6B,YAAW,mBAAmB;IACtE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;;IAgB1C,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAoD/E,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAWtD"}
+{"version":3,"file":"json-driven-ide-launcher.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/ide-launchers/json-driven-ide-launcher.service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EAChB,MAAM,8EAA8E,CAAC;AAetF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAGnF;AAED,qBACa,4BAA6B,YAAW,mBAAmB;IACtE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;;IAiB1C,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAC/B,OAAO,CAAC,eAAe,CAAC;IA8D3B,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAWtD"}

package/dist/packages/core/src/infrastructure/services/ide-launchers/json-driven-ide-launcher.service.js

@@ -40,12 +40,13 @@ let JsonDrivenIdeLauncherService = class JsonDrivenIdeLauncherService {
                     name: meta.name,
                     binary: meta.binary,
                     openDirectory: meta.openDirectory,
+                    terminalCommand: meta.terminalCommand,
                     spawnOptions: meta.spawnOptions,
                 });
             }
         }
     }
-    async launch(editorId, directoryPath) {
+    async launch(editorId, directoryPath, options) {
         const entry = this.editors.get(editorId);
         if (!entry) {
             const available = [...this.editors.keys()].join(', ');
@@ -55,7 +56,11 @@ let JsonDrivenIdeLauncherService = class JsonDrivenIdeLauncherService {
                 message: `No launcher found for editor: ${editorId}. Available: ${available}`,
             };
         }
-        const openCmd = resolvePlatformValue(entry.openDirectory);
+        // In headless mode (web UI), use terminalCommand to open CLI agents
+        // in a new terminal window instead of inheriting the server's stdio.
+        const useTerminal = options?.headless === true && entry.terminalCommand != null;
+        const cmdSource = useTerminal ? entry.terminalCommand : entry.openDirectory;
+        const openCmd = resolvePlatformValue(cmdSource);
         if (!openCmd.includes('{dir}')) {
             return {
                 ok: false,
@@ -64,10 +69,11 @@ let JsonDrivenIdeLauncherService = class JsonDrivenIdeLauncherService {
             };
         }
         const resolved = openCmd.replace('{dir}', directoryPath);
-        const useShell = entry.spawnOptions?.shell === true;
+        // Terminal commands always use shell mode and detach
+        const useShell = useTerminal || entry.spawnOptions?.shell === true;
         const opts = {
-            detached: entry.spawnOptions?.detached ?? !useShell,
-            stdio: (entry.spawnOptions?.stdio ?? 'ignore'),
+            detached: useTerminal ? true : (entry.spawnOptions?.detached ?? !useShell),
+            stdio: (useTerminal ? 'ignore' : (entry.spawnOptions?.stdio ?? 'ignore')),
             shell: useShell,
         };
         try {

package/dist/packages/core/src/infrastructure/services/notifications/notification.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notification.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/notifications/notification.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,iBAAiB,EAElB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8EAA8E,CAAC;AAEzH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAU7D,qBAAa,mBAAoB,YAAW,oBAAoB;IAC9D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;gBAEtC,GAAG,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe;IAKlE,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;CAmBvC"}
+{"version":3,"file":"notification.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/notifications/notification.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,iBAAiB,EAElB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8EAA8E,CAAC;AAEzH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAc7D,qBAAa,mBAAoB,YAAW,oBAAoB;IAC9D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;gBAEtC,GAAG,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe;IAKlE,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;CAmBvC"}

package/dist/packages/core/src/infrastructure/services/notifications/notification.service.js

@@ -16,6 +16,10 @@ const EVENT_TYPE_TO_CONFIG_KEY = {
     [NotificationEventType.WaitingApproval]: 'waitingApproval',
     [NotificationEventType.AgentCompleted]: 'agentCompleted',
     [NotificationEventType.AgentFailed]: 'agentFailed',
+    [NotificationEventType.PrMerged]: 'prMerged',
+    [NotificationEventType.PrClosed]: 'prClosed',
+    [NotificationEventType.PrChecksPassed]: 'prChecksPassed',
+    [NotificationEventType.PrChecksFailed]: 'prChecksFailed',
 };
 export class NotificationService {
     bus;

package/dist/packages/core/src/infrastructure/services/pr-sync/pr-sync-watcher.service.d.ts

@@ -0,0 +1,61 @@
+/**
+ * PR Sync Watcher Service
+ *
+ * Polls GitHub PR status and CI status for features in the Review lifecycle
+ * stage, updating feature records and emitting notifications when transitions
+ * are detected. Follows the NotificationWatcherService polling pattern.
+ *
+ * Maintains in-memory tracking of last-known PR and CI status per feature
+ * to avoid duplicate updates and notifications. Features are grouped by
+ * repositoryPath for batch `gh pr list` queries.
+ */
+import type { IFeatureRepository } from '../../../application/ports/output/repositories/feature-repository.interface.js';
+import type { IAgentRunRepository } from '../../../application/ports/output/agents/agent-run-repository.interface.js';
+import type { IGitPrService } from '../../../application/ports/output/services/git-pr-service.interface.js';
+import type { INotificationService } from '../../../application/ports/output/services/notification-service.interface.js';
+export declare class PrSyncWatcherService {
+    private readonly featureRepo;
+    private readonly agentRunRepo;
+    private readonly gitPrService;
+    private readonly notificationService;
+    private readonly pollIntervalMs;
+    private readonly trackedFeatures;
+    private readonly skippedRepos;
+    private intervalId;
+    constructor(featureRepo: IFeatureRepository, agentRunRepo: IAgentRunRepository, gitPrService: IGitPrService, notificationService: INotificationService, pollIntervalMs?: number);
+    isRunning(): boolean;
+    start(): void;
+    stop(): void;
+    private poll;
+    private processRepository;
+    private processFeature;
+    /** Mark associated agent run as completed so the UI reflects "done" state. */
+    private completeAgentRun;
+    private emitNotification;
+}
+/**
+ * Initialize the PR sync watcher singleton.
+ * Must be called once during web server startup.
+ *
+ * @throws Error if the watcher is already initialized
+ */
+export declare function initializePrSyncWatcher(featureRepo: IFeatureRepository, agentRunRepo: IAgentRunRepository, gitPrService: IGitPrService, notificationService: INotificationService, pollIntervalMs?: number): void;
+/**
+ * Get the PR sync watcher singleton.
+ *
+ * @returns The PR sync watcher service
+ * @throws Error if the watcher hasn't been initialized yet
+ */
+export declare function getPrSyncWatcher(): PrSyncWatcherService;
+/**
+ * Check if the PR sync watcher has been initialized.
+ */
+export declare function hasPrSyncWatcher(): boolean;
+/**
+ * Reset the PR sync watcher singleton (for testing purposes only).
+ * Stops the watcher if running before resetting.
+ *
+ * @internal
+ */
+export declare function resetPrSyncWatcher(): void;
+//# sourceMappingURL=pr-sync-watcher.service.d.ts.map

package/dist/packages/core/src/infrastructure/services/pr-sync/pr-sync-watcher.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-sync-watcher.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/pr-sync/pr-sync-watcher.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAWH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gFAAgF,CAAC;AACzH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4EAA4E,CAAC;AACtH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wEAAwE,CAAC;AAK5G,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8EAA8E,CAAC;AAiBzH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IACnD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;IAC7C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAuB;IAC3D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqC;IACrE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,UAAU,CAA+C;gBAG/D,WAAW,EAAE,kBAAkB,EAC/B,YAAY,EAAE,mBAAmB,EACjC,YAAY,EAAE,aAAa,EAC3B,mBAAmB,EAAE,oBAAoB,EACzC,cAAc,GAAE,MAAiC;IASnD,SAAS,IAAI,OAAO;IAIpB,KAAK,IAAI,IAAI;IAcb,IAAI,IAAI,IAAI;YASE,IAAI;YAuCJ,iBAAiB;YA6CjB,cAAc;IA4I5B,8EAA8E;YAChE,gBAAgB;IAW9B,OAAO,CAAC,gBAAgB;CAoBzB;AAMD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,kBAAkB,EAC/B,YAAY,EAAE,mBAAmB,EACjC,YAAY,EAAE,aAAa,EAC3B,mBAAmB,EAAE,oBAAoB,EACzC,cAAc,CAAC,EAAE,MAAM,GACtB,IAAI,CAYN;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,oBAAoB,CAQvD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAKzC"}

package/dist/packages/core/src/infrastructure/services/pr-sync/pr-sync-watcher.service.js

@@ -0,0 +1,286 @@
+/**
+ * PR Sync Watcher Service
+ *
+ * Polls GitHub PR status and CI status for features in the Review lifecycle
+ * stage, updating feature records and emitting notifications when transitions
+ * are detected. Follows the NotificationWatcherService polling pattern.
+ *
+ * Maintains in-memory tracking of last-known PR and CI status per feature
+ * to avoid duplicate updates and notifications. Features are grouped by
+ * repositoryPath for batch `gh pr list` queries.
+ */
+import { SdlcLifecycle, PrStatus, CiStatus, AgentRunStatus, NotificationEventType, NotificationSeverity, } from '../../../domain/generated/output.js';
+const DEFAULT_POLL_INTERVAL_MS = 3000;
+const TAG = '[PrSyncWatcher]';
+const CI_STATUS_MAP = {
+    success: CiStatus.Success,
+    failure: CiStatus.Failure,
+    pending: CiStatus.Pending,
+};
+export class PrSyncWatcherService {
+    featureRepo;
+    agentRunRepo;
+    gitPrService;
+    notificationService;
+    pollIntervalMs;
+    trackedFeatures = new Map();
+    skippedRepos = new Set();
+    intervalId = null;
+    constructor(featureRepo, agentRunRepo, gitPrService, notificationService, pollIntervalMs = DEFAULT_POLL_INTERVAL_MS) {
+        this.featureRepo = featureRepo;
+        this.agentRunRepo = agentRunRepo;
+        this.gitPrService = gitPrService;
+        this.notificationService = notificationService;
+        this.pollIntervalMs = pollIntervalMs;
+    }
+    isRunning() {
+        return this.intervalId !== null;
+    }
+    start() {
+        if (this.intervalId !== null)
+            return;
+        // eslint-disable-next-line no-console
+        console.log(`${TAG} Starting (poll every ${this.pollIntervalMs}ms)`);
+        // Run first poll immediately
+        void this.poll();
+        this.intervalId = setInterval(() => {
+            void this.poll();
+        }, this.pollIntervalMs);
+    }
+    stop() {
+        if (this.intervalId !== null) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+            // eslint-disable-next-line no-console
+            console.log(`${TAG} Stopped`);
+        }
+    }
+    async poll() {
+        try {
+            const allFeatures = await this.featureRepo.list({ lifecycle: SdlcLifecycle.Review });
+            // Include features with a valid repositoryPath (with or without PR data)
+            const features = allFeatures.filter((f) => f.repositoryPath);
+            if (features.length === 0) {
+                this.trackedFeatures.clear();
+                return;
+            }
+            // Group features by repositoryPath for batch queries
+            const byRepo = new Map();
+            for (const feature of features) {
+                const group = byRepo.get(feature.repositoryPath) ?? [];
+                group.push(feature);
+                byRepo.set(feature.repositoryPath, group);
+            }
+            // Process each repository
+            for (const [repoPath, repoFeatures] of byRepo) {
+                await this.processRepository(repoPath, repoFeatures);
+            }
+            // Prune features no longer in Review
+            const currentFeatureIds = new Set(features.map((f) => f.id));
+            for (const trackedId of this.trackedFeatures.keys()) {
+                if (!currentFeatureIds.has(trackedId)) {
+                    this.trackedFeatures.delete(trackedId);
+                }
+            }
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            // eslint-disable-next-line no-console
+            console.warn(`${TAG} Poll failed: ${msg}`);
+        }
+    }
+    async processRepository(repoPath, features) {
+        if (this.skippedRepos.has(repoPath))
+            return;
+        // Skip repos without a git remote — gh pr list will always fail
+        try {
+            if (!(await this.gitPrService.hasRemote(repoPath))) {
+                // eslint-disable-next-line no-console
+                console.log(`${TAG} Skipping ${repoPath} (no git remote)`);
+                this.skippedRepos.add(repoPath);
+                return;
+            }
+        }
+        catch {
+            return;
+        }
+        let prStatuses;
+        try {
+            prStatuses = await this.gitPrService.listPrStatuses(repoPath);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            // eslint-disable-next-line no-console
+            console.warn(`${TAG} listPrStatuses failed for ${repoPath}: ${msg}`);
+            return;
+        }
+        // Build lookups by PR number and by head branch name.
+        // Multiple PRs can share the same headRefName (e.g. old merged PR + new open PR).
+        // Prefer Open PRs so we don't match stale merged/closed ones.
+        const statusByNumber = new Map();
+        const statusByBranch = new Map();
+        for (const pr of prStatuses) {
+            statusByNumber.set(pr.number, pr);
+            if (pr.headRefName) {
+                const existing = statusByBranch.get(pr.headRefName);
+                if (!existing || (existing.state !== PrStatus.Open && pr.state === PrStatus.Open)) {
+                    statusByBranch.set(pr.headRefName, pr);
+                }
+            }
+        }
+        for (const feature of features) {
+            await this.processFeature(feature, statusByNumber, statusByBranch);
+        }
+    }
+    async processFeature(feature, statusByNumber, statusByBranch) {
+        // If feature has no PR data, try to discover an Open PR by matching branch name.
+        // Only link Open PRs — merged/closed PRs with the same branch are likely stale
+        // from a previous iteration. The watcher will catch Open→Merged transitions
+        // on subsequent polls once the PR is linked.
+        if (!feature.pr) {
+            const matchedPr = statusByBranch.get(feature.branch);
+            if (matchedPr?.state !== PrStatus.Open)
+                return;
+            // eslint-disable-next-line no-console
+            console.log(`${TAG} Discovered PR #${matchedPr.number} for "${feature.name}" via branch "${feature.branch}"`);
+            feature.pr = {
+                url: matchedPr.url,
+                number: matchedPr.number,
+                status: PrStatus.Open,
+            };
+            this.trackedFeatures.set(feature.id, {
+                prStatus: PrStatus.Open,
+                ciStatus: undefined,
+                featureName: feature.name,
+            });
+            await this.featureRepo.update(feature);
+            return;
+        }
+        const pr = feature.pr;
+        const prStatusInfo = statusByNumber.get(pr.number);
+        let needsUpdate = false;
+        // Initialize or retrieve tracked state
+        const prevState = this.trackedFeatures.get(feature.id);
+        if (!prevState) {
+            // First time seeing this feature — initialize tracking
+            this.trackedFeatures.set(feature.id, {
+                prStatus: pr.status,
+                ciStatus: pr.ciStatus,
+                featureName: feature.name,
+            });
+        }
+        const tracked = this.trackedFeatures.get(feature.id);
+        // Check PR status transition
+        if (prStatusInfo && prStatusInfo.state !== tracked.prStatus) {
+            const newPrStatus = prStatusInfo.state;
+            // eslint-disable-next-line no-console
+            console.log(`${TAG} PR #${pr.number} status changed: ${tracked.prStatus} -> ${newPrStatus} for "${feature.name}"`);
+            feature.pr = { ...pr, status: newPrStatus };
+            if (newPrStatus === PrStatus.Merged) {
+                feature.lifecycle = SdlcLifecycle.Maintain;
+                await this.completeAgentRun(feature);
+                this.emitNotification(NotificationEventType.PrMerged, feature.id, feature.agentRunId ?? '', feature.name, `PR #${pr.number} merged for ${feature.name}`, NotificationSeverity.Success);
+            }
+            else if (newPrStatus === PrStatus.Closed) {
+                this.emitNotification(NotificationEventType.PrClosed, feature.id, feature.agentRunId ?? '', feature.name, `PR #${pr.number} closed for ${feature.name}`, NotificationSeverity.Warning);
+            }
+            tracked.prStatus = newPrStatus;
+            needsUpdate = true;
+        }
+        // Check CI status transition
+        try {
+            const ciResult = await this.gitPrService.getCiStatus(feature.repositoryPath, feature.branch);
+            const newCiStatus = CI_STATUS_MAP[ciResult.status] ?? CiStatus.Pending;
+            if (newCiStatus !== tracked.ciStatus) {
+                // eslint-disable-next-line no-console
+                console.log(`${TAG} CI status changed: ${tracked.ciStatus ?? 'none'} -> ${newCiStatus} for "${feature.name}"`);
+                feature.pr = { ...(feature.pr ?? pr), ciStatus: newCiStatus };
+                if (newCiStatus === CiStatus.Success) {
+                    this.emitNotification(NotificationEventType.PrChecksPassed, feature.id, feature.agentRunId ?? '', feature.name, `CI checks passed for ${feature.name}`, NotificationSeverity.Success);
+                }
+                else if (newCiStatus === CiStatus.Failure) {
+                    this.emitNotification(NotificationEventType.PrChecksFailed, feature.id, feature.agentRunId ?? '', feature.name, `CI checks failed for ${feature.name}`, NotificationSeverity.Error);
+                }
+                tracked.ciStatus = newCiStatus;
+                needsUpdate = true;
+            }
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            // eslint-disable-next-line no-console
+            console.warn(`${TAG} getCiStatus failed for "${feature.name}": ${msg}`);
+        }
+        if (needsUpdate) {
+            await this.featureRepo.update(feature);
+        }
+    }
+    /** Mark associated agent run as completed so the UI reflects "done" state. */
+    async completeAgentRun(feature) {
+        if (!feature.agentRunId)
+            return;
+        try {
+            await this.agentRunRepo.updateStatus(feature.agentRunId, AgentRunStatus.completed);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            // eslint-disable-next-line no-console
+            console.warn(`${TAG} Failed to complete agent run ${feature.agentRunId}: ${msg}`);
+        }
+    }
+    emitNotification(eventType, featureId, agentRunId, featureName, message, severity) {
+        const event = {
+            eventType,
+            featureId,
+            agentRunId,
+            featureName,
+            message,
+            severity,
+            timestamp: new Date().toISOString(),
+        };
+        this.notificationService.notify(event);
+    }
+}
+// --- Singleton accessors (follows NotificationWatcherService pattern) ---
+let watcherInstance = null;
+/**
+ * Initialize the PR sync watcher singleton.
+ * Must be called once during web server startup.
+ *
+ * @throws Error if the watcher is already initialized
+ */
+export function initializePrSyncWatcher(featureRepo, agentRunRepo, gitPrService, notificationService, pollIntervalMs) {
+    if (watcherInstance !== null) {
+        throw new Error('PR sync watcher already initialized. Cannot re-initialize.');
+    }
+    watcherInstance = new PrSyncWatcherService(featureRepo, agentRunRepo, gitPrService, notificationService, pollIntervalMs);
+}
+/**
+ * Get the PR sync watcher singleton.
+ *
+ * @returns The PR sync watcher service
+ * @throws Error if the watcher hasn't been initialized yet
+ */
+export function getPrSyncWatcher() {
+    if (watcherInstance === null) {
+        throw new Error('PR sync watcher not initialized. Call initializePrSyncWatcher() during web server startup.');
+    }
+    return watcherInstance;
+}
+/**
+ * Check if the PR sync watcher has been initialized.
+ */
+export function hasPrSyncWatcher() {
+    return watcherInstance !== null;
+}
+/**
+ * Reset the PR sync watcher singleton (for testing purposes only).
+ * Stops the watcher if running before resetting.
+ *
+ * @internal
+ */
+export function resetPrSyncWatcher() {
+    if (watcherInstance !== null) {
+        watcherInstance.stop();
+    }
+    watcherInstance = null;
+}

package/dist/packages/core/src/infrastructure/services/tool-installer/tool-installer.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-installer.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/tool-installer/tool-installer.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sEAAsE,CAAC;AAClH,OAAO,KAAK,EACV,sBAAsB,EACtB,kBAAkB,EAEnB,MAAM,qCAAqC,CAAC;AA6B7C,qBACa,wBAAyB,YAAW,qBAAqB;IACpE;;OAEG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA8B1E;;;OAGG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAqB9D;;;OAGG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAChC,OAAO,CAAC,sBAAsB,CAAC;IAuElC;;OAEG;IACH,OAAO,CAAC,6BAA6B;CA4BtC"}
+{"version":3,"file":"tool-installer.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/tool-installer/tool-installer.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sEAAsE,CAAC;AAClH,OAAO,KAAK,EACV,sBAAsB,EACtB,kBAAkB,EAEnB,MAAM,qCAAqC,CAAC;AA6C7C,qBACa,wBAAyB,YAAW,qBAAqB;IACpE;;OAEG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA4B1E;;;OAGG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAqB9D;;;OAGG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAChC,OAAO,CAAC,sBAAsB,CAAC;IAuElC;;OAEG;IACH,OAAO,CAAC,6BAA6B;CA4BtC"}

package/dist/packages/core/src/infrastructure/services/tool-installer/tool-installer.service.js

@@ -33,12 +33,25 @@ function resolveBinary(metadata) {
 }
 /**
  * Check if a binary exists in the system PATH using 'which' command.
- * Returns both availability status and any error for detailed reporting.
+ *
+ * `which` exits with code 1 when the binary is simply not in PATH.
+ * Node's execFile wraps that as an Error, but it's a normal "not found"
+ * result. Only truly unexpected failures (ENOENT for `which` itself,
+ * EACCES, signals, etc.) are surfaced via the `error` field.
  */
 const checkBinaryExists = (binary) => {
     return new Promise((resolve) => {
         execFile('which', [binary], (err) => {
-            resolve(err ? { found: false, error: err } : { found: true });
+            if (!err)
+                return resolve({ found: true });
+            // execFile errors from a non-zero exit code have a numeric `code` property.
+            // That's the normal "binary not found in PATH" case.
+            const code = err.code;
+            if (code === undefined || typeof code === 'number') {
+                return resolve({ found: false, notInPath: true });
+            }
+            // Anything else (ENOENT for `which` itself, EACCES, etc.) is a real error.
+            resolve({ found: false, error: err });
         });
     });
 };
@@ -56,15 +69,13 @@ let ToolInstallerServiceImpl = class ToolInstallerServiceImpl {
             if (result.found) {
                 return createAvailableStatus(toolName);
             }
-            // Check if it's just "not found" or another error
-            if (result.error?.message.includes('not found')) {
-                // Binary doesn't exist in PATH - create suggestions for installation
+            if (result.notInPath) {
                 const suggestions = this.createInstallationSuggestions(metadata);
                 return createMissingStatus(toolName, suggestions);
             }
-            // Some other error occurred
+            // Genuine error (e.g. `which` binary missing, permission denied)
             const errorMessage = result.error?.message ?? 'Unknown error checking availability';
-            return createErrorStatus(toolName, `Failed to check availability: ${errorMessage}`);
+            return createErrorStatus(toolName, errorMessage);
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Unknown error';

package/dist/packages/core/src/infrastructure/services/tool-installer/tool-metadata.d.ts

@@ -15,7 +15,9 @@ export interface ToolMetadata {
     /** Detailed description */
     description: string;
     /** Tool tags for grouping in listings. A tool can belong to multiple categories. */
-    tags: ('ide' | 'cli-agent')[];
+    tags: ('ide' | 'cli-agent' | 'vcs')[];
+    /** URL to the tool's icon/logo image */
+    iconUrl?: string;
     /** Binary name to check with 'which' command (string or per-platform map) */
     binary: string | Record<string, string>;
     /** Package manager or installation method */
@@ -30,6 +32,8 @@ export interface ToolMetadata {
     verifyCommand: string;
     /** Whether the tool supports automated installation (default: true) */
     autoInstall?: boolean;
+    /** Whether this tool is required for the platform to function (default: false) */
+    required?: boolean;
     /** Command to open a directory in this tool.
      * String format: "code {dir}" — single command for all platforms.
      * Object format: { "linux": "antigravity {dir}", "darwin": "agy {dir}" } — per-platform commands. */
@@ -42,6 +46,12 @@ export interface ToolMetadata {
         stdio?: 'ignore' | 'inherit' | 'pipe';
         detached?: boolean;
     };
+    /** Platform-specific command to launch this tool in a new terminal window.
+     * Used when launching from the web UI where no terminal is available.
+     * When set, the launcher spawns a new terminal window with this command.
+     * Supports {dir} placeholder like openDirectory.
+     * Example: "x-terminal-emulator -e bash -c 'cd {dir} && claude'" */
+    terminalCommand?: string | Record<string, string>;
 }
 export declare const TOOL_METADATA: Record<string, ToolMetadata>;
 /**

package/dist/packages/core/src/infrastructure/services/tool-installer/tool-metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-metadata.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/tool-installer/tool-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IAEb,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAEhB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IAEpB,oFAAoF;IACpF,IAAI,EAAE,CAAC,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC;IAE9B,6EAA6E;IAC7E,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;IAEvB,wFAAwF;IACxF,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAEhB,iCAAiC;IACjC,gBAAgB,EAAE,MAAM,CAAC;IAEzB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;IAEtB,uEAAuE;IACvE,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;yGAEqG;IACrG,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhD;;iGAE6F;IAC7F,YAAY,CAAC,EAAE;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;QACtC,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;CACH;AA8CD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAsB,CAAC;AAE9E;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,CAExD"}
+{"version":3,"file":"tool-metadata.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/tool-installer/tool-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IAEb,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAEhB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IAEpB,oFAAoF;IACpF,IAAI,EAAE,CAAC,KAAK,GAAG,WAAW,GAAG,KAAK,CAAC,EAAE,CAAC;IAEtC,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;IAEvB,wFAAwF;IACxF,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAEhB,iCAAiC;IACjC,gBAAgB,EAAE,MAAM,CAAC;IAEzB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;IAEtB,uEAAuE;IACvE,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;yGAEqG;IACrG,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhD;;iGAE6F;IAC7F,YAAY,CAAC,EAAE;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;QACtC,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;IAEF;;;;wEAIoE;IACpE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnD;AA8CD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAsB,CAAC;AAE9E;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,CAExD"}

package/dist/packages/core/src/infrastructure/services/tool-installer/tools/CLAUDE.md

@@ -0,0 +1,63 @@
+# Tool JSON Definitions
+
+Each `.json` file defines a development tool that shep can install, verify, and launch.
+Files are loaded dynamically by `tool-metadata.ts` — the filename (minus `.json`) becomes the tool ID.
+
+## Schema
+
+| Field              | Type                              | Required | Description                                                              |
+| ------------------ | --------------------------------- | -------- | ------------------------------------------------------------------------ |
+| `name`             | `string`                          | Yes      | Human-readable display name                                              |
+| `summary`          | `string`                          | Yes      | One-line description                                                     |
+| `description`      | `string`                          | Yes      | Detailed description                                                     |
+| `tags`             | `("ide"\|"cli-agent"\|"vcs")[]`   | Yes      | Categories for filtering in UI and CLI                                   |
+| `iconUrl`          | `string`                          | No       | URL to SVG/PNG icon (use cdn.simpleicons.org when possible)              |
+| `binary`           | `string \| Record<string,string>` | Yes      | Binary name for `which` check. Per-platform map if differs               |
+| `packageManager`   | `string`                          | Yes      | Install method label (apt, brew, curl, manual, download)                 |
+| `commands`         | `Record<string,string>`           | Yes      | Platform-keyed install commands (`linux`, `darwin`)                      |
+| `timeout`          | `number`                          | Yes      | Install timeout in ms (typically 300000)                                 |
+| `documentationUrl` | `string`                          | Yes      | Official docs URL                                                        |
+| `verifyCommand`    | `string`                          | Yes      | Command to verify installation (e.g. `git --version`)                    |
+| `autoInstall`      | `boolean`                         | No       | `true` (default) = run commands automatically. `false` = manual download |
+| `required`         | `boolean`                         | No       | `true` = tool is required for platform to function                       |
+| `openDirectory`    | `string \| Record<string,string>` | No       | Command to open a directory. Use `{dir}` placeholder                     |
+| `spawnOptions`     | `object`                          | No       | Override spawn behavior (see below)                                      |
+| `terminalCommand`  | `string \| Record<string,string>` | No       | Command to open tool in a **new terminal window** from web UI            |
+
+## Spawn Options
+
+GUI tools (IDEs) use defaults: `{ detached: true, stdio: "ignore" }` — fire and forget.
+CLI agents need: `{ shell: true, stdio: "inherit", detached: false }` — run in current terminal.
+
+## Terminal Command
+
+CLI agents launched from the web UI have no terminal to inherit. The `terminalCommand` field
+provides a platform-specific command that opens a new terminal window:
+
+```json
+"terminalCommand": {
+  "linux": "x-terminal-emulator -e bash -c 'cd {dir} && exec claude'",
+  "darwin": "open -a Terminal.app bash -c 'cd {dir} && exec claude'"
+}
+```
+
+The launcher auto-detects TTY: CLI launch uses `openDirectory`, web launch uses `terminalCommand`.
+
+## Adding a New Tool
+
+1. Create `<tool-id>.json` in this directory
+2. Fill all required fields
+3. Validate icon URL returns 200: `curl -sI <url> | head -1`
+4. For manual-install tools: set `autoInstall: false`, use plain text in `commands` (no `echo`)
+5. For CLI agents: add `spawnOptions` + `terminalCommand`
+6. Run `pnpm build && pnpm test:unit` to verify
+
+## Tags
+
+| Tag         | Meaning                        | Examples                |
+| ----------- | ------------------------------ | ----------------------- |
+| `ide`       | GUI code editor                | VS Code, Cursor, Zed    |
+| `cli-agent` | Terminal-based AI coding agent | Claude Code, Cursor CLI |
+| `vcs`       | Version control tool           | Git, GitHub CLI         |
+
+Tools can have multiple tags. A tool appears in all matching filter tabs in the UI.