@shepai/cli 1.54.0 → 1.55.0

package/README.md

@@ -198,7 +198,7 @@ Running AI agents is easy. **Managing many of them through a full SDLC is the ha
 
 ## Features
 
-> 🚧 **Under active development** — Web UI screenshots are from the design spec. Core CLI (`feat new`, `feat ls`, `feat show`, `settings`, `ui`) works today. Some commands (`mem`, `start`) are still WIP.
+> 🚧 **Under active development** — Web UI screenshots are from the design spec. Core CLI (`feat new`, `feat ls`, `feat show`, `settings`, `ui`, `start`, `stop`, `status`) works today. The `mem` command is still WIP.
 
 <table>
 <tr>
@@ -338,25 +338,39 @@ Running AI agents is easy. **Managing many of them through a full SDLC is the ha
 ## Quick Start
 
 ```bash
-# Navigate to any repo and create a feature
-cd ~/projects/your-app
-shep feat new "Add user authentication with OAuth 2.0"
+# 1. Install
+npm i -g @shepai/cli
+
+# 2. Run Shep — completes setup on first run, then opens the web UI
+shep
+
+# 3. Browser opens at http://localhost:4050 — you're in
+```
 
-# Open the control center to watch progress
-shep ui
+## Daemon Management
+
+`shep` runs the web UI as a background daemon so your terminal stays free. Use these commands to manage it:
+
+```bash
+shep start              # Start (or re-open) the web UI daemon
+shep stop               # Gracefully stop the daemon
+shep status             # Show live PID, port, uptime, CPU%, and memory
 ```
 
 ## CLI
 
 ```
-shep start                            Start background service
+shep                                  Start daemon (onboarding on first run)
+shep start [--port <number>]          Start the web UI as a background daemon
+shep stop                             Stop the running web UI daemon
+shep status                           Show daemon status and live metrics
 shep feat new <description>           Create a new feature
 shep feat new --interactive           Interactive mode with human checkpoints
 shep feat new --allow-all             Full autonomous mode
 shep feat ls                          List features across repos
 shep feat show <id>                   Show feature details
 shep feat preview <id>                Preview feature dev environment
-shep ui                               Open the web control center
+shep ui                               Start the web UI in the foreground
 shep settings show                    Display current configuration
 shep settings agent                   Configure AI coding agent
 shep mem add <text> --global|--repo   Add agent memory

package/dist/packages/core/src/application/ports/output/services/daemon-service.interface.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Daemon Service Interface
+ *
+ * Output port for managing the daemon state file (~/.shep/daemon.json).
+ * Infrastructure layer provides the concrete DaemonPidService implementation.
+ */
+/**
+ * Shape of the daemon state persisted to ~/.shep/daemon.json.
+ */
+export interface DaemonState {
+    /** PID of the running daemon process */
+    pid: number;
+    /** Port the daemon web server is listening on */
+    port: number;
+    /** ISO 8601 timestamp of when the daemon was started */
+    startedAt: string;
+}
+/**
+ * Port interface for reading and writing daemon lifecycle state.
+ *
+ * Implementations must:
+ * - Write atomically (write-to-temp + rename) to prevent corruption
+ * - Return null from read() when no daemon.json exists (ENOENT)
+ * - Swallow ENOENT in delete() — safe to call when file is absent
+ * - Validate pid before any process.kill() call
+ */
+export interface IDaemonService {
+    /**
+     * Read the daemon state from daemon.json.
+     * Returns null if the file does not exist.
+     */
+    read(): Promise<DaemonState | null>;
+    /**
+     * Atomically write daemon state to daemon.json.
+     * Uses write-to-temp + fs.rename to prevent partial writes.
+     */
+    write(data: DaemonState): Promise<void>;
+    /**
+     * Delete daemon.json. Safe to call when file is absent (ENOENT swallowed).
+     */
+    delete(): Promise<void>;
+    /**
+     * Check whether a process with the given PID is alive.
+     * Uses process.kill(pid, 0) — returns true if alive, false on ESRCH.
+     * Validates that pid is a positive finite integer before checking.
+     */
+    isAlive(pid: number): boolean;
+}
+//# sourceMappingURL=daemon-service.interface.d.ts.map

package/dist/packages/core/src/application/ports/output/services/daemon-service.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-service.interface.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/daemon-service.interface.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAEpC;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B"}

package/dist/packages/core/src/application/ports/output/services/daemon-service.interface.js

@@ -0,0 +1,7 @@
+/**
+ * Daemon Service Interface
+ *
+ * Output port for managing the daemon state file (~/.shep/daemon.json).
+ * Infrastructure layer provides the concrete DaemonPidService implementation.
+ */
+export {};

package/dist/packages/core/src/application/ports/output/services/index.d.ts

@@ -15,4 +15,5 @@ export type { INotificationService } from './notification-service.interface.js';
 export type { IGitPrService, CiStatus, CiStatusResult, DiffSummary, MergeStrategy, PrCreateResult, } from './git-pr-service.interface.js';
 export { GitPrError, GitPrErrorCode } from './git-pr-service.interface.js';
 export type { IIdeLauncherService, LaunchIdeInput, LaunchIdeResult, LaunchIdeSuccess, LaunchIdeFailed, } from './ide-launcher-service.interface.js';
+export type { IDaemonService, DaemonState } from './daemon-service.interface.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/packages/core/src/application/ports/output/services/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AAClG,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,uCAAuC,CAAC;AAC/C,YAAY,EACV,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACnF,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,YAAY,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAChF,YAAY,EACV,aAAa,EACb,QAAQ,EACR,cAAc,EACd,WAAW,EACX,aAAa,EACb,cAAc,GACf,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC3E,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,eAAe,GAChB,MAAM,qCAAqC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AAClG,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,uCAAuC,CAAC;AAC/C,YAAY,EACV,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACnF,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,YAAY,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAChF,YAAY,EACV,aAAa,EACb,QAAQ,EACR,cAAc,EACd,WAAW,EACX,aAAa,EACb,cAAc,GACf,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC3E,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,eAAe,GAChB,MAAM,qCAAqC,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/packages/core/src/infrastructure/di/container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/infrastructure/di/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AA2GrC;;;;;;GAMG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,OAAO,SAAS,CAAC,CAsPrE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/infrastructure/di/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AA6GrC;;;;;;GAMG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,OAAO,SAAS,CAAC,CAuPrE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/packages/core/src/infrastructure/di/container.js

@@ -24,6 +24,7 @@ import { WorktreeService } from '../services/git/worktree.service.js';
 import { ToolInstallerServiceImpl } from '../services/tool-installer/tool-installer.service.js';
 import { GitPrService } from '../services/git/git-pr.service.js';
 import { JsonDrivenIdeLauncherService } from '../services/ide-launchers/json-driven-ide-launcher.service.js';
+import { DaemonPidService } from '../services/daemon/daemon-pid.service.js';
 import { AgentExecutorFactory } from '../services/agents/common/agent-executor-factory.service.js';
 import { AgentExecutorProvider } from '../services/agents/common/agent-executor-provider.service.js';
 import { StructuredAgentCallerService } from '../services/agents/common/structured-agent-caller.service.js';
@@ -132,6 +133,7 @@ export async function initializeContainer() {
     container.registerSingleton('IToolInstallerService', ToolInstallerServiceImpl);
     container.registerSingleton('IGitPrService', GitPrService);
     container.registerSingleton('IIdeLauncherService', JsonDrivenIdeLauncherService);
+    container.registerSingleton('IDaemonService', DaemonPidService);
     // Register agent infrastructure
     container.register('IAgentRunRepository', {
         useFactory: (c) => {

package/dist/packages/core/src/infrastructure/services/browser-opener.service.d.ts

@@ -3,6 +3,7 @@ export interface BrowserOpenerDeps {
     platform: NodeJS.Platform;
     execFile: (cmd: string, args: readonly string[], callback: (error: Error | null) => void) => ChildProcess;
     warn: (msg: string) => void;
+    isTTY: boolean;
 }
 export declare class BrowserOpenerService {
     private deps;

package/dist/packages/core/src/infrastructure/services/browser-opener.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-opener.service.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/infrastructure/services/browser-opener.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE/E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,QAAQ,EAAE,CACR,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,KACpC,YAAY,CAAC;IAClB,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAeD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,IAAI,CAAoB;gBAEpB,IAAI,GAAE,OAAO,CAAC,iBAAiB,CAAM;IAIjD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAWxB"}
+{"version":3,"file":"browser-opener.service.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/infrastructure/services/browser-opener.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE/E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,QAAQ,EAAE,CACR,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,KACpC,YAAY,CAAC;IAClB,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;CAChB;AAgBD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,IAAI,CAAoB;gBAEpB,IAAI,GAAE,OAAO,CAAC,iBAAiB,CAAM;IAIjD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAcxB"}

package/dist/packages/core/src/infrastructure/services/browser-opener.service.js

@@ -4,6 +4,7 @@ const defaultDeps = {
     execFile: cpExecFile,
     // eslint-disable-next-line no-console
     warn: (msg) => console.warn(msg),
+    isTTY: !!process.stdout.isTTY,
 };
 const PLATFORM_COMMANDS = {
     darwin: { cmd: 'open', args: (url) => [url] },
@@ -16,6 +17,9 @@ export class BrowserOpenerService {
         this.deps = { ...defaultDeps, ...deps };
     }
     open(url) {
+        // Skip browser opening in non-interactive environments (tests, CI, piped output).
+        if (!this.deps.isTTY)
+            return;
         const entry = PLATFORM_COMMANDS[this.deps.platform];
         if (!entry)
             return;

package/dist/packages/core/src/infrastructure/services/daemon/daemon-pid.service.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DaemonPidService
+ *
+ * Infrastructure service for managing the daemon state file (~/.shep/daemon.json).
+ * Implements IDaemonService output port.
+ *
+ * Uses atomic write (write-to-temp + rename) to prevent partial-write corruption.
+ */
+import type { IDaemonService, DaemonState } from '../../../application/ports/output/services/daemon-service.interface.js';
+export declare class DaemonPidService implements IDaemonService {
+    read(): Promise<DaemonState | null>;
+    write(data: DaemonState): Promise<void>;
+    delete(): Promise<void>;
+    isAlive(pid: number): boolean;
+}
+//# sourceMappingURL=daemon-pid.service.d.ts.map

package/dist/packages/core/src/infrastructure/services/daemon/daemon-pid.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-pid.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/daemon/daemon-pid.service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACZ,MAAM,wEAAwE,CAAC;AAGhF,qBACa,gBAAiB,YAAW,cAAc;IAC/C,IAAI,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAWnC,KAAK,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAU7B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAS9B"}

package/dist/packages/core/src/infrastructure/services/daemon/daemon-pid.service.js

@@ -0,0 +1,72 @@
+/**
+ * DaemonPidService
+ *
+ * Infrastructure service for managing the daemon state file (~/.shep/daemon.json).
+ * Implements IDaemonService output port.
+ *
+ * Uses atomic write (write-to-temp + rename) to prevent partial-write corruption.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { readFile, writeFile, unlink, rename } from 'node:fs/promises';
+import { injectable } from 'tsyringe';
+import { getDaemonStatePath } from '../filesystem/shep-directory.service.js';
+let DaemonPidService = class DaemonPidService {
+    async read() {
+        const filePath = getDaemonStatePath();
+        try {
+            const raw = await readFile(filePath, 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            if (isEnoent(err))
+                return null;
+            throw err;
+        }
+    }
+    async write(data) {
+        const finalPath = getDaemonStatePath();
+        const tmpPath = `${finalPath}.tmp`;
+        await writeFile(tmpPath, JSON.stringify(data), 'utf-8');
+        await rename(tmpPath, finalPath);
+    }
+    async delete() {
+        const filePath = getDaemonStatePath();
+        try {
+            await unlink(filePath);
+        }
+        catch (err) {
+            if (isEnoent(err))
+                return;
+            throw err;
+        }
+    }
+    isAlive(pid) {
+        if (!isValidPid(pid))
+            return false;
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+};
+DaemonPidService = __decorate([
+    injectable()
+], DaemonPidService);
+export { DaemonPidService };
+function isEnoent(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'code' in err &&
+        err.code === 'ENOENT');
+}
+function isValidPid(pid) {
+    return Number.isFinite(pid) && Number.isInteger(pid) && pid > 0;
+}

package/dist/packages/core/src/infrastructure/services/filesystem/shep-directory.service.d.ts

@@ -19,6 +19,13 @@ export declare function getShepHomeDir(): string;
  * @returns Path to the database file
  */
 export declare function getShepDbPath(): string;
+/**
+ * Gets the path to the daemon state file.
+ * Uses SHEP_HOME env var if set (for test isolation), otherwise ~/.shep/daemon.json
+ *
+ * @returns Path to daemon.json
+ */
+export declare function getDaemonStatePath(): string;
 /**
  * Ensures the shep home directory exists with correct permissions.
  * Creates the directory if it doesn't exist.

package/dist/packages/core/src/infrastructure/services/filesystem/shep-directory.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shep-directory.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/filesystem/shep-directory.service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAiBzD"}
+{"version":3,"file":"shep-directory.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/filesystem/shep-directory.service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAiBzD"}

package/dist/packages/core/src/infrastructure/services/filesystem/shep-directory.service.js

@@ -34,6 +34,15 @@ export function getShepHomeDir() {
 export function getShepDbPath() {
     return join(resolveShepHomeDir(), 'data');
 }
+/**
+ * Gets the path to the daemon state file.
+ * Uses SHEP_HOME env var if set (for test isolation), otherwise ~/.shep/daemon.json
+ *
+ * @returns Path to daemon.json
+ */
+export function getDaemonStatePath() {
+    return join(resolveShepHomeDir(), 'daemon.json');
+}
 /**
  * Ensures the shep home directory exists with correct permissions.
  * Creates the directory if it doesn't exist.

package/dist/src/presentation/cli/commands/_serve.command.d.ts

@@ -0,0 +1,32 @@
+/**
+ * _serve Command (hidden daemon entry point)
+ *
+ * Runs the web server in-process as a detached daemon child.
+ * This command is hidden from --help output and is invoked internally by
+ * the startDaemon() helper via child_process.spawn({detached: true}).
+ *
+ * NOTE: The DI container and settings are already initialized by index.ts
+ * bootstrap() before Commander dispatches to this action. This command
+ * only needs to start the web server and notification watcher.
+ *
+ * Lifecycle:
+ *   1. Start WebServerService on the provided --port
+ *   2. Initialize notification watcher
+ *   3. Block until SIGTERM or SIGINT triggers graceful shutdown
+ *
+ * The shutdown sequence mirrors ui.command.ts:
+ *   - Set isShuttingDown flag (idempotent — prevents double-shutdown)
+ *   - Start 5s forceExit timer (unref'd so it doesn't block)
+ *   - Stop notification watcher
+ *   - Stop WebServerService
+ *   - process.exit(0)
+ *
+ * Usage (internal only):
+ *   process.execPath _serve --port <N>
+ */
+import { Command } from 'commander';
+/**
+ * Create the hidden _serve command (daemon child entry point).
+ */
+export declare function createServeCommand(): Command;
+//# sourceMappingURL=_serve.command.d.ts.map

package/dist/src/presentation/cli/commands/_serve.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_serve.command.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/cli/commands/_serve.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,OAAO,EAAwB,MAAM,WAAW,CAAC;AAuB1D;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAwD5C"}

package/dist/src/presentation/cli/commands/_serve.command.js

@@ -0,0 +1,91 @@
+/**
+ * _serve Command (hidden daemon entry point)
+ *
+ * Runs the web server in-process as a detached daemon child.
+ * This command is hidden from --help output and is invoked internally by
+ * the startDaemon() helper via child_process.spawn({detached: true}).
+ *
+ * NOTE: The DI container and settings are already initialized by index.ts
+ * bootstrap() before Commander dispatches to this action. This command
+ * only needs to start the web server and notification watcher.
+ *
+ * Lifecycle:
+ *   1. Start WebServerService on the provided --port
+ *   2. Initialize notification watcher
+ *   3. Block until SIGTERM or SIGINT triggers graceful shutdown
+ *
+ * The shutdown sequence mirrors ui.command.ts:
+ *   - Set isShuttingDown flag (idempotent — prevents double-shutdown)
+ *   - Start 5s forceExit timer (unref'd so it doesn't block)
+ *   - Stop notification watcher
+ *   - Stop WebServerService
+ *   - process.exit(0)
+ *
+ * Usage (internal only):
+ *   process.execPath _serve --port <N>
+ */
+import { Command, InvalidArgumentError } from 'commander';
+import { container } from '../../../../packages/core/src/infrastructure/di/container.js';
+import { setVersionEnvVars } from '../../../../packages/core/src/infrastructure/services/version.service.js';
+import { resolveWebDir } from '../../../../packages/core/src/infrastructure/services/web-server.service.js';
+import { initializeNotificationWatcher, getNotificationWatcher, } from '../../../../packages/core/src/infrastructure/services/notifications/notification-watcher.service.js';
+function parsePort(value) {
+    const port = parseInt(value, 10);
+    if (isNaN(port) || port < 1024 || port > 65535) {
+        throw new InvalidArgumentError('Port must be an integer between 1024 and 65535');
+    }
+    return port;
+}
+/**
+ * Create the hidden _serve command (daemon child entry point).
+ */
+export function createServeCommand() {
+    const cmd = new Command('_serve')
+        .description('Start the web server daemon (internal use only)')
+        .helpOption(false)
+        .addHelpCommand(false)
+        .option('-p, --port <number>', 'Port to listen on', parsePort)
+        .action(async (options) => {
+        try {
+            const port = options.port ?? 4050;
+            const { dir, dev } = resolveWebDir();
+            // Set version env vars for the web UI
+            const versionService = container.resolve('IVersionService');
+            setVersionEnvVars(versionService.getVersion());
+            // Start the web server
+            const service = container.resolve('IWebServerService');
+            await service.start(port, dir, dev);
+            // Start notification watcher
+            const runRepo = container.resolve('IAgentRunRepository');
+            const phaseTimingRepo = container.resolve('IPhaseTimingRepository');
+            const featureRepo = container.resolve('IFeatureRepository');
+            const notificationService = container.resolve('INotificationService');
+            initializeNotificationWatcher(runRepo, phaseTimingRepo, featureRepo, notificationService);
+            getNotificationWatcher().start();
+            // Graceful shutdown handler — identical pattern to ui.command.ts
+            let isShuttingDown = false;
+            const shutdown = async () => {
+                if (isShuttingDown)
+                    return;
+                isShuttingDown = true;
+                // Force exit after 5s if graceful shutdown stalls
+                const forceExit = setTimeout(() => process.exit(0), 5000);
+                forceExit.unref();
+                getNotificationWatcher().stop();
+                await service.stop();
+                process.exit(0);
+            };
+            process.on('SIGTERM', shutdown);
+            process.on('SIGINT', shutdown);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            // Write to stderr so it appears in daemon logs if redirected
+            process.stderr.write(`[_serve] Fatal error: ${err.message}\n`);
+            process.exit(1);
+        }
+    });
+    // Mark hidden so Commander omits it from --help output
+    cmd._hidden = true;
+    return cmd;
+}

package/dist/src/presentation/cli/commands/daemon/start-daemon.d.ts

@@ -0,0 +1,27 @@
+/**
+ * startDaemon() — Shared daemon-spawn helper
+ *
+ * Contains the parent-side logic for starting the Shep web UI as a
+ * detached background daemon. Used by both:
+ *   - The default `shep` action (index.ts)
+ *   - The `shep start` command (start.command.ts)
+ *
+ * Flow:
+ *   1. Resolve available port (respects --port override)
+ *   2. Check if daemon is already running (idempotent — print URL and return)
+ *   3. Spawn the daemon with execArgv propagated (supports tsx in dev mode)
+ *      {detached: true, stdio: ['ignore','ignore','pipe']} + child.unref()
+ *   4. Wait briefly to confirm the child is alive; surface stderr on crash
+ *   5. Write daemon.json atomically via IDaemonService
+ *   6. Print formatted URL to stdout
+ *   7. Open browser via BrowserOpenerService
+ */
+export interface StartDaemonOptions {
+    port?: number;
+}
+/**
+ * Start the Shep web UI as a detached background daemon.
+ * Idempotent: if a daemon is already running, prints the existing URL and returns.
+ */
+export declare function startDaemon(opts?: StartDaemonOptions): Promise<void>;
+//# sourceMappingURL=start-daemon.d.ts.map

package/dist/src/presentation/cli/commands/daemon/start-daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-daemon.d.ts","sourceRoot":"","sources":["../../../../../../src/presentation/cli/commands/daemon/start-daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAkBH,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0F9E"}

package/dist/src/presentation/cli/commands/daemon/start-daemon.js

@@ -0,0 +1,135 @@
+/**
+ * startDaemon() — Shared daemon-spawn helper
+ *
+ * Contains the parent-side logic for starting the Shep web UI as a
+ * detached background daemon. Used by both:
+ *   - The default `shep` action (index.ts)
+ *   - The `shep start` command (start.command.ts)
+ *
+ * Flow:
+ *   1. Resolve available port (respects --port override)
+ *   2. Check if daemon is already running (idempotent — print URL and return)
+ *   3. Spawn the daemon with execArgv propagated (supports tsx in dev mode)
+ *      {detached: true, stdio: ['ignore','ignore','pipe']} + child.unref()
+ *   4. Wait briefly to confirm the child is alive; surface stderr on crash
+ *   5. Write daemon.json atomically via IDaemonService
+ *   6. Print formatted URL to stdout
+ *   7. Open browser via BrowserOpenerService
+ */
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import { container } from '../../../../../packages/core/src/infrastructure/di/container.js';
+import { findAvailablePort, DEFAULT_PORT } from '../../../../../packages/core/src/infrastructure/services/port.service.js';
+import { BrowserOpenerService } from '../../../../../packages/core/src/infrastructure/services/browser-opener.service.js';
+import { fmt, messages, spinner } from '../../ui/index.js';
+/** How long to wait (ms) after spawn to verify the child is still alive. */
+const SPAWN_SETTLE_MS = 500;
+/** Max time (ms) to wait for the server to become reachable before opening the browser. */
+const READY_TIMEOUT_MS = 30_000;
+/** Interval (ms) between readiness probes. */
+const READY_POLL_MS = 300;
+/**
+ * Start the Shep web UI as a detached background daemon.
+ * Idempotent: if a daemon is already running, prints the existing URL and returns.
+ */
+export async function startDaemon(opts = {}) {
+    const daemonService = container.resolve('IDaemonService');
+    // Check for an already-running daemon
+    const existing = await daemonService.read();
+    if (existing && daemonService.isAlive(existing.pid)) {
+        const url = `http://localhost:${existing.port}`;
+        messages.newline();
+        messages.info(`Shep is already running at ${fmt.code(url)}`);
+        messages.newline();
+        return;
+    }
+    // Resolve the port
+    const startPort = opts.port ?? DEFAULT_PORT;
+    const port = await findAvailablePort(startPort);
+    // Spawn the daemon as a detached child process.
+    // Propagate process.execArgv so tsx loader hooks (--require / --import) are
+    // available in dev mode. In production (compiled JS), execArgv is empty.
+    const child = spawn(process.execPath, [...process.execArgv, process.argv[1], '_serve', '--port', String(port)], {
+        detached: true,
+        // Keep stderr piped so we can surface startup errors; stdin/stdout detached.
+        stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    // Collect stderr in case the child crashes during startup.
+    let stderrChunks = [];
+    child.stderr.on('data', (chunk) => stderrChunks.push(chunk));
+    // Wait briefly for the child to either settle or crash.
+    const exitCode = await Promise.race([
+        new Promise((resolve) => child.on('exit', (code) => resolve(code))),
+        new Promise((resolve) => setTimeout(() => resolve(undefined), SPAWN_SETTLE_MS)),
+    ]);
+    if (exitCode !== undefined) {
+        // Child exited during the settle window — startup failed.
+        const stderr = Buffer.concat(stderrChunks).toString().trim();
+        messages.newline();
+        messages.error(`Daemon failed to start (exit code ${exitCode ?? 'unknown'}).`);
+        if (stderr) {
+            console.error(stderr);
+        }
+        messages.newline();
+        // Clean up stale daemon.json if it exists
+        await daemonService.delete();
+        return;
+    }
+    // Child is alive — detach fully.
+    // Unref stderr so the parent event loop is not held open, then unref the child.
+    child.stderr.destroy();
+    stderrChunks = [];
+    child.unref();
+    // Write daemon.json atomically
+    await daemonService.write({
+        pid: child.pid,
+        port,
+        startedAt: new Date().toISOString(),
+    });
+    const url = `http://localhost:${port}`;
+    messages.newline();
+    console.log(fmt.heading('Shep Web UI'));
+    messages.newline();
+    // Poll until the server responds, with a spinner on stderr.
+    // Skip readiness check in E2E / CI environments where the daemon child
+    // cannot actually start a Next.js server within the test's time window.
+    if (process.env.SHEP_SKIP_READINESS_CHECK) {
+        messages.success(`Daemon spawned at ${fmt.code(url)}`);
+    }
+    else {
+        const ready = await spinner('Starting server', () => waitForServer(url, READY_TIMEOUT_MS));
+        if (ready) {
+            messages.success(`Server ready at ${fmt.code(url)}`);
+        }
+        else {
+            messages.warning(`Server may still be starting at ${fmt.code(url)}`);
+        }
+    }
+    messages.newline();
+    const opener = new BrowserOpenerService({ warn: messages.warning });
+    opener.open(url);
+}
+/**
+ * Poll a URL until it returns any HTTP response (even 500).
+ * Resolves true when reachable, false on timeout.
+ */
+function waitForServer(url, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    return new Promise((resolve) => {
+        const probe = () => {
+            if (Date.now() > deadline)
+                return resolve(false);
+            const req = http.get(url, () => {
+                resolve(true);
+            });
+            req.on('error', () => {
+                setTimeout(probe, READY_POLL_MS);
+            });
+            req.setTimeout(2000, () => {
+                req.destroy();
+                setTimeout(probe, READY_POLL_MS);
+            });
+        };
+        probe();
+    });
+}

package/dist/src/presentation/cli/commands/start.command.d.ts

@@ -0,0 +1,15 @@
+/**
+ * start Command
+ *
+ * Starts the Shep web UI as a detached background daemon.
+ * All spawn logic lives in the shared startDaemon() helper to avoid
+ * duplication between this command and the default `shep` action.
+ *
+ * Usage: shep start [--port <number>]
+ */
+import { Command } from 'commander';
+/**
+ * Create the start command.
+ */
+export declare function createStartCommand(): Command;
+//# sourceMappingURL=start.command.d.ts.map

package/dist/src/presentation/cli/commands/start.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.command.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/cli/commands/start.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAwB,MAAM,WAAW,CAAC;AAW1D;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAc5C"}