@treeseed/cli 0.10.20 → 0.10.21

package/README.md

@@ -45,6 +45,7 @@ The main workflow commands exposed by the current CLI are:
 - `treeseed tasks [--json]`
 - `treeseed switch <branch-name> [--preview]`
 - `treeseed dev`
+- `treeseed dev start|status|logs|stop|restart`
 - `treeseed save [--preview] [--plan] "<commit message>"`
 - `treeseed stage "<resolution message>"`
 - `treeseed close "<close reason>"`
@@ -65,6 +66,7 @@ treeseed config
 treeseed switch feature/search-improvements --plan
 treeseed switch feature/search-improvements --preview
 treeseed dev
+treeseed dev start --web-runtime local
 treeseed save --preview "feat: add search filters"
 treeseed stage "feat: add search filters"
 treeseed release --patch
@@ -72,6 +74,27 @@ treeseed recover
 treeseed status --json
 ```
 
+## Development Server Instances
+
+`treeseed dev` remains the foreground local runtime supervisor. It delegates to `@treeseed/core`, starts the Market web/API/control-plane development surface, streams output in the active terminal, and exits when the shell-owned process is stopped.
+
+Managed dev instances use subcommands:
+
+```bash
+treeseed dev start --web-runtime local --json
+treeseed dev status --json
+treeseed dev status --all --json
+treeseed dev logs --follow
+treeseed dev stop --json
+treeseed dev restart --web-runtime local --json
+```
+
+Managed instances are scoped to the current physical worktree. The core runtime writes `.treeseed/dev/instances/<scope>.json`, `.treeseed/dev/pids/<scope>.pid`, and `.treeseed/logs/dev-<scope>.jsonl` in that worktree. A repository-family index under the git common dir makes sibling worktree instances discoverable to humans and AI agents.
+
+`--force` replaces only the current worktree instance. `--force-conflicts` is the explicit cross-worktree port-owner escape hatch. Additional worktrees receive stable alternate port blocks and worktree-specific local PostgreSQL/Mailpit names, so many agents can run development sessions in the same repository family.
+
+For the complete architecture, see the root workspace document `docs/local-dev-instances.md`.
+
 ## Agent-Safe Workflow
 
 Use planning mode before any destructive or multi-repo mutation:

package/dist/cli/handlers/dev.js

@@ -52,6 +52,11 @@ const handleDev = async (invocation, context) => {
     }
     const feedback = typeof invocation.args.feedback === "string" ? invocation.args.feedback : void 0;
     const watch = feedback !== "off";
+    const subcommand = typeof invocation.positionals[0] === "string" ? invocation.positionals[0] : "";
+    const managedSubcommands = /* @__PURE__ */ new Set(["start", "status", "logs", "stop", "restart"]);
+    if (subcommand && !managedSubcommands.has(subcommand)) {
+      return fail(`Unknown dev subcommand "${subcommand}". Use start, status, logs, stop, or restart.`);
+    }
     const passthroughArgs = ["--surfaces", "web,api"];
     const forwardStringOption = (name, flag) => {
       const value = invocation.args[name];
@@ -75,6 +80,9 @@ const handleDev = async (invocation, context) => {
     forwardBooleanOption("plan", "--plan");
     forwardBooleanOption("reset", "--reset");
     forwardBooleanOption("force", "--force");
+    forwardBooleanOption("forceConflicts", "--force-conflicts");
+    forwardBooleanOption("all", "--all");
+    forwardBooleanOption("follow", "--follow");
     forwardBooleanOption("json", "--json");
     const workspaceRoot = findNearestTreeseedWorkspaceRoot(context.cwd);
     const workspaceLinksMode = typeof invocation.args.workspaceLinks === "string" ? invocation.args.workspaceLinks : void 0;
@@ -83,7 +91,12 @@ const handleDev = async (invocation, context) => {
       context.write(`[workspace][link] Linked ${workspaceLinks.created.length} local workspace package paths.`, "stdout");
     }
     const resolved = resolveCoreDevEntrypoint(context.cwd);
-    const args = watch ? [...resolved.args, ...passthroughArgs, "--watch"] : [...resolved.args, ...passthroughArgs];
+    const args = [
+      ...resolved.args,
+      ...subcommand ? [subcommand] : [],
+      ...passthroughArgs,
+      ...watch && !subcommand ? ["--watch"] : []
+    ];
     const result = context.spawn(resolved.command, args, {
       cwd: context.cwd,
       env: resolveTreeseedLaunchEnvironment({

package/dist/cli/operations-registry.js

@@ -32,10 +32,53 @@ const DEV_RUNTIME_OPTIONS = [
   { name: "open", flags: "--open <mode>", description: "Control whether dev opens the browser after readiness. Defaults to off; use --open on to launch it.", kind: "enum", values: ["auto", "on", "off"] },
   { name: "plan", flags: "--plan", description: "Print the dev runtime plan and exit without starting services.", kind: "boolean" },
   { name: "reset", flags: "--reset", description: "Clear local dev runtime state before setup, migrations, and service startup.", kind: "boolean" },
-  { name: "force", flags: "--force", description: "Terminate overlapping Treeseed dev runtimes and listeners on required local dev ports before startup.", kind: "boolean" },
+  { name: "force", flags: "--force", description: "Replace the current worktree dev instance before startup.", kind: "boolean" },
+  { name: "forceConflicts", flags: "--force-conflicts", description: "Allow managed dev start to stop sibling worktree port owners when explicit ports conflict.", kind: "boolean" },
+  { name: "all", flags: "--all", description: "Apply managed dev status or stop to all worktrees in the repository family.", kind: "boolean" },
+  { name: "follow", flags: "--follow", description: "Follow managed dev logs when supported.", kind: "boolean" },
   { name: "json", flags: "--json", description: "Emit structured JSON or newline-delimited dev events.", kind: "boolean" },
   { name: "workspaceLinks", flags: "--workspace-links <mode>", description: "Control local workspace package links.", kind: "enum", values: ["auto", "off"] }
 ];
+const DEV_STATUS_OPTIONS = DEV_RUNTIME_OPTIONS.filter((option) => ["all", "json"].includes(option.name));
+const DEV_LOGS_OPTIONS = DEV_RUNTIME_OPTIONS.filter((option) => ["follow", "json"].includes(option.name));
+const DEV_STOP_OPTIONS = DEV_RUNTIME_OPTIONS.filter((option) => ["all", "json"].includes(option.name));
+const DEV_START_OPTIONS = DEV_RUNTIME_OPTIONS.filter((option) => !["all", "follow"].includes(option.name));
+function devManagedHelpCommand(subcommand, spec) {
+  return {
+    id: `dev.${subcommand}`,
+    name: `dev ${subcommand}`,
+    aliases: [],
+    group: "Local Development",
+    summary: spec.summary,
+    description: spec.description,
+    provider: "default",
+    related: ["dev"],
+    usage: spec.usage,
+    options: spec.options,
+    examples: spec.examples,
+    helpVisible: false,
+    helpFeatured: false,
+    executionMode: "handler",
+    handlerName: "dev",
+    help: {
+      workflowPosition: "managed dev instance",
+      longSummary: [spec.description],
+      whenToUse: spec.whenToUse,
+      beforeYouRun: spec.beforeYouRun,
+      outcomes: spec.outcomes,
+      examples: spec.examples,
+      automationNotes: [
+        "These managed dev subcommands use the same `dev` handler and core supervisor as foreground `treeseed dev`.",
+        "Use `--json` when another process needs stable instance records, ports, URLs, PIDs, ready checks, or log paths."
+      ],
+      warnings: spec.warnings ?? [],
+      relatedDetails: [
+        related("dev", "Use `dev` without a subcommand for the foreground supervisor.")
+      ],
+      seeAlso: ["dev"]
+    }
+  };
+}
 function genericWorkflowPosition(spec) {
   if (spec.group === "Workflow") {
     if (spec.name === "switch") return "start work";
@@ -1173,15 +1216,18 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
   })],
   ["dev", command({
     options: DEV_RUNTIME_OPTIONS,
-    examples: ["treeseed dev", "treeseed dev --reset", "treeseed dev --reset --plan --json", "treeseed dev --web-runtime local --plan --json", "treeseed dev --port 4322"],
+    arguments: [{ name: "subcommand", description: "Optional managed instance action: start, status, logs, stop, or restart.", required: false }],
+    examples: ["treeseed dev", "treeseed dev start", "treeseed dev status --all --json", "treeseed dev logs", "treeseed dev stop", "treeseed dev --web-runtime local --plan --json"],
     help: {
       longSummary: [
-        "Dev starts the local Treeseed Market web/API/runtime services as a foreground supervisor.",
+        "Dev starts or manages the local Treeseed Market web/API/runtime services.",
+        "Without a subcommand, dev runs as the existing foreground supervisor.",
         "Capacity provider lifecycle is package-owned and runs through `treeseed capacity ...`, not through `treeseed dev`."
       ],
       beforeYouRun: [
         "Run from the tenant or workspace root you want to develop.",
         "From the Market repo root, dev automatically starts the local Market API, managed local PostgreSQL, and Market operations runner alongside the web UI.",
+        "Use `dev start` for worktree-scoped background instance management that AI agents can discover and stop later.",
         "Use `--plan --json` when you want to inspect fixed web/API/runner commands, setup steps, readiness checks, watched paths, and restart policy without starting services.",
         "Use `--reset` when you want a fresh local D1 database, Market PostgreSQL state, Mailpit inbox, generated worker bundle, and Wrangler temp output without deleting configuration.",
         "Dev prints the local web URL after readiness; it does not open a browser unless you pass `--open on` or `--open auto`.",
@@ -1189,6 +1235,10 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
       ],
       examples: [
         example("treeseed dev", "Start local Market development", "Run web, API, managed PostgreSQL setup, and the Market operations runner locally."),
+        example("treeseed dev start", "Start a managed worktree instance", "Launch the same dev runtime detached, write worktree-local PID/log/state files, and return after readiness."),
+        example("treeseed dev status --all --json", "Inspect all worktree instances", "List managed dev instances discovered through the repository-family index."),
+        example("treeseed dev logs", "Show managed dev logs", "Print the current worktree managed dev log file."),
+        example("treeseed dev stop", "Stop managed dev", "Stop only the current worktree managed dev instance."),
         example("treeseed dev --reset", "Start from a fresh local runtime", "Clear disposable local dev state, rerun setup and database migrations, then start the dev supervisor."),
         example("treeseed dev --reset --plan --json", "Inspect reset actions", "Emit the reset, setup, readiness, command, and watch plan without deleting local state or starting services."),
         example("treeseed dev --plan --json", "Inspect the runtime plan", "Emit a structured plan with setup steps, commands, ports, URLs, readiness checks, and watch entries."),
@@ -1257,7 +1307,129 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
   })],
   ["starlight:patch", command({ examples: ["treeseed starlight:patch"], executionMode: "adapter" })]
 ]);
+const DEV_MANAGED_OPERATION_SPECS = [
+  devManagedHelpCommand("start", {
+    summary: "Start a detached worktree-scoped dev instance.",
+    description: "Start launches the same Market web/API/runner runtime as foreground `dev`, but detaches it, writes worktree-local instance state, captures logs, waits for readiness, and returns a summary.",
+    usage: "treeseed dev start [--web-runtime local|provider|auto] [--port <port>] [--api-port <port>] [--force] [--force-conflicts] [--json]",
+    options: DEV_START_OPTIONS,
+    whenToUse: [
+      "Use this when you want the local Market runtime to keep running after the shell command exits.",
+      "Use it for AI-agent workflows where later commands need discoverable PID, port, URL, and log state."
+    ],
+    beforeYouRun: [
+      "Run from the worktree that should own the managed instance.",
+      "Use `--web-runtime local` for fast Astro hot reload.",
+      "Use `--force` to replace only the current worktree instance. Use `--force-conflicts` only when you intentionally want to stop sibling worktree port owners."
+    ],
+    outcomes: [
+      "Writes `.treeseed/dev/instances/web-api.json`, `.treeseed/dev/pids/web-api.pid`, and `.treeseed/logs/dev-web-api.jsonl` in the current worktree.",
+      "Returns after readiness with URLs, ports, PID, process group, log path, and ready-check state."
+    ],
+    examples: [
+      example("treeseed dev start --web-runtime local --force", "Start the current worktree instance", "Launch the managed background runtime with local web hot reload and replace any stale current-worktree owner."),
+      example("treeseed dev start --port 4322 --api-port 3002 --json", "Start on explicit ports", "Pin web and API ports and emit a structured instance summary."),
+      example("trsd dev start --web-runtime local", "Use the short alias", "Start the same managed runtime through the shorter entrypoint.")
+    ]
+  }),
+  devManagedHelpCommand("status", {
+    summary: "Inspect managed dev instance state.",
+    description: "Status reads worktree-local managed dev state, checks process and readiness health, repairs stale records opportunistically, and can discover sibling worktree instances through the repository-family index.",
+    usage: "treeseed dev status [--all] [--json]",
+    options: DEV_STATUS_OPTIONS,
+    whenToUse: [
+      "Use this before starting a new managed instance to see whether one is already running.",
+      "Use `--all` when multiple worktrees or AI agents may be running sibling instances for the same repository family."
+    ],
+    beforeYouRun: [
+      "Run from the worktree you want to inspect.",
+      "Use `--json` for automation that needs the exact status, PID, ports, URLs, stale reason, or sibling conflicts."
+    ],
+    outcomes: [
+      "Prints ready, starting, degraded, stopped, or stale state for the current worktree instance.",
+      "With `--all`, includes instances discovered from sibling worktrees through the shared repository-family index."
+    ],
+    examples: [
+      example("treeseed dev status", "Inspect current worktree", "Show the managed instance state for the current worktree."),
+      example("treeseed dev status --all", "Inspect sibling worktrees", "List managed instances discoverable across the repository family."),
+      example("treeseed dev status --json", "Read status programmatically", "Emit machine-readable instance state for agents or scripts.")
+    ]
+  }),
+  devManagedHelpCommand("logs", {
+    summary: "Read managed dev logs.",
+    description: "Logs prints the current worktree managed dev log in human-readable form, rendering structured dev events as concise text and optionally following the stable log file.",
+    usage: "treeseed dev logs [--follow] [--json]",
+    options: DEV_LOGS_OPTIONS,
+    whenToUse: [
+      "Use this when `dev status` reports stale, degraded, or stopped and you need to see what happened.",
+      "Use `--follow` while iterating locally to watch the background runtime without reattaching to the supervisor process."
+    ],
+    beforeYouRun: [
+      "Run from the worktree that owns the managed instance.",
+      "Default human output shows a recent, readable tail. Use the reported log path if you need the full historical file."
+    ],
+    outcomes: [
+      "Prints the current managed log tail from `.treeseed/logs/dev-web-api.jsonl`.",
+      "With `--follow`, continues streaming appended log lines until interrupted."
+    ],
+    examples: [
+      example("treeseed dev logs", "Show recent managed logs", "Print the current worktree managed dev log tail in human-readable form."),
+      example("treeseed dev logs --follow", "Follow background runtime logs", "Stream appended log entries while the managed instance runs."),
+      example("treeseed dev status --json", "Find the log path", "Use status when automation needs the authoritative log file location.")
+    ]
+  }),
+  devManagedHelpCommand("stop", {
+    summary: "Stop managed dev instances.",
+    description: "Stop terminates the current worktree managed dev process group and leaves sibling worktree instances alone unless `--all` is explicitly provided.",
+    usage: "treeseed dev stop [--all] [--json]",
+    options: DEV_STOP_OPTIONS,
+    whenToUse: [
+      "Use this when you are done with the current worktree background runtime.",
+      "Use `--all` only when intentionally cleaning up every discoverable managed instance in the repository family."
+    ],
+    beforeYouRun: [
+      "Run from the worktree whose instance should be stopped.",
+      "Prefer `dev status --all` first when several agents may be working in sibling worktrees."
+    ],
+    outcomes: [
+      "Stops only the owned process group for the current worktree by default.",
+      "Marks stopped or stale records so later `dev start` and `dev status` calls see accurate state."
+    ],
+    warnings: [
+      "`--all` can interrupt sibling worktree sessions owned by other humans or agents."
+    ],
+    examples: [
+      example("treeseed dev stop", "Stop current worktree instance", "Terminate only the current managed dev process group."),
+      example("treeseed dev stop --all", "Stop repository-family instances", "Stop all discoverable managed instances for the repository family."),
+      example("treeseed dev stop --json", "Stop from automation", "Emit a structured stop summary.")
+    ]
+  }),
+  devManagedHelpCommand("restart", {
+    summary: "Restart a managed dev instance.",
+    description: "Restart stops the current worktree managed dev instance, then starts it again with the same managed-start semantics, state files, log path, readiness checks, and port ownership rules.",
+    usage: "treeseed dev restart [--web-runtime local|provider|auto] [--port <port>] [--api-port <port>] [--force] [--force-conflicts] [--json]",
+    options: DEV_START_OPTIONS,
+    whenToUse: [
+      "Use this after changing runtime configuration, package links, or local service state that needs a fresh supervisor.",
+      "Use it when the managed instance is degraded and a clean stop/start is preferable to inspecting every child process manually."
+    ],
+    beforeYouRun: [
+      "Run from the worktree that owns the managed instance.",
+      "Pass the same runtime options you would use with `dev start` when you want to change ports or web runtime mode during restart."
+    ],
+    outcomes: [
+      "Stops the current worktree managed instance and starts a new one.",
+      "Returns the new PID, process group, ports, URLs, log path, and readiness result."
+    ],
+    examples: [
+      example("treeseed dev restart --web-runtime local --force", "Restart local hot-reload runtime", "Replace the current worktree managed instance and wait for readiness."),
+      example("treeseed dev restart --port 4322 --api-port 3002 --json", "Restart on new ports", "Restart with explicit web/API ports and emit a structured summary."),
+      example("trsd dev restart", "Use the short alias", "Restart through the shorter entrypoint.")
+    ]
+  })
+];
 const CLI_ONLY_OPERATION_SPECS = [
+  ...DEV_MANAGED_OPERATION_SPECS,
   {
     id: "seed.plan",
     name: "seed",

package/dist/cli/runtime.js

@@ -22,6 +22,28 @@ function shouldRenderCommandHelp(spec, argv) {
   const treeseedArgs = separatorIndex >= 0 ? argv.slice(0, separatorIndex) : argv;
   return treeseedArgs.some(isHelpFlag);
 }
+function resolveNestedDevHelpTarget(argv) {
+  const managedSubcommands = /* @__PURE__ */ new Set(["start", "status", "logs", "stop", "restart"]);
+  const subcommand = argv.find((arg) => !arg.startsWith("-") && managedSubcommands.has(arg));
+  return subcommand ? `dev ${subcommand}` : null;
+}
+function resolveCommandHelpTarget(spec, argv) {
+  if (spec.name === "dev") {
+    return resolveNestedDevHelpTarget(argv) ?? spec.name;
+  }
+  return spec.name;
+}
+function resolveExplicitHelpTarget(args) {
+  const helpArgs = args.filter((arg) => !arg.startsWith("-"));
+  if (helpArgs.length === 0) return null;
+  for (let length = Math.min(3, helpArgs.length); length > 0; length -= 1) {
+    const candidate = helpArgs.slice(0, length).join(" ");
+    if (findTreeseedOperation(candidate)) {
+      return candidate;
+    }
+  }
+  return helpArgs[0] ?? null;
+}
 function isNoColorFlag(value) {
   return value === "--no-color";
 }
@@ -303,13 +325,14 @@ class TreeseedOperationsSdk {
       return writeTreeseedResult({ exitCode: 1, stderr: [lines.join("\n")] }, context);
     }
     if (shouldRenderCommandHelp(spec, argv)) {
+      const helpTarget = resolveCommandHelpTarget(spec, argv);
       if (shouldUseInkHelp(context)) {
-        const helpExitCode = await renderTreeseedHelpInk(spec.name, context);
+        const helpExitCode = await renderTreeseedHelpInk(helpTarget, context);
         if (typeof helpExitCode === "number") {
           return helpExitCode;
         }
       }
-      context.write(renderTreeseedHelp(spec.name), "stdout");
+      context.write(renderTreeseedHelp(helpTarget), "stdout");
       return 0;
     }
     return spec.executionMode === "adapter" ? this.executeAdapter(spec, argv, context) : spec.executionMode === "delegate" ? this.executeAgents(argv, context) : this.executeHandler(spec, argv, context);
@@ -318,7 +341,7 @@ class TreeseedOperationsSdk {
     const context = createTreeseedCommandContext(overrides);
     const [firstArg, ...restArgs] = argv;
     if (!firstArg || isHelpFlag(firstArg) || firstArg === "help") {
-      const commandName = firstArg === "help" ? restArgs[0] ?? null : null;
+      const commandName = firstArg === "help" ? resolveExplicitHelpTarget(restArgs) : null;
       if (shouldUseInkHelp(context)) {
         const helpExitCode = await renderTreeseedHelpInk(commandName, context);
         if (typeof helpExitCode === "number") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeseed/cli",
-  "version": "0.10.20",
+  "version": "0.10.21",
   "description": "Operator-facing Treeseed CLI package.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -45,7 +45,7 @@
     "release:publish": "node ./scripts/run-ts.mjs ./scripts/publish-package.ts"
   },
   "dependencies": {
-    "@treeseed/sdk": "github:treeseed-ai/sdk#0.10.26",
+    "@treeseed/sdk": "github:treeseed-ai/sdk#0.10.27",
     "ink": "^7.0.0",
     "react": "^19.2.5"
   },