Merge branch 'master' into worktree/dsh-arg-parser

Integrate the Commander adapter with master's `dsh web --workspace-root`
(workspace-aware session flow).

- args.ts: add `--workspace-root <path>` to the web subcommand; WebInvocation
  carries workspaceRoot.
- web.ts: keep the adapter-parsed signature, take (host, port, dev,
  workspaceRoot) and pass workspaceRoot through to AppCLIEntry (drop master's
  re-added parseArgs and CLI host/port validation — the schema owns those).
- bin.ts forwards invocation.workspaceRoot; args.spec + the Agent Note pair note
  the flag.

apps/cli/src/app-cli-entry.ts

@@ -77,6 +77,8 @@ export interface AppCLIEntryOptions {
    * browser).
    */
   port?: number
+  /** Parent directory for name-created Workspaces; undefined uses the gateway's cwd fallback. */
+  workspaceRoot?: string
 }
 
 /**
@@ -141,6 +143,7 @@ export class AppCLIEntry {
     // Source 2: CLI flags (field set disjoint from the json mappings).
     if (this.options.host !== undefined) put('webserver', 'host', this.options.host)
     if (this.options.port !== undefined) put('webserver', 'port', this.options.port)
+    if (this.options.workspaceRoot !== undefined) put('api-gateway', 'workspaceRoot', this.options.workspaceRoot)
 
     // Source 3: the frontend dist — an assembly fact of this app, never yml
     // user config. Workspace knowledge stays here.

apps/cli/src/args.ts

@@ -31,13 +31,15 @@ interface HeadlessInvocation {
  * `port` a natural ≤ 65535) is the single source of both the default (the
  * shipped `cordis.yml` value stands when a flag is absent) and validity (a bad
  * value fails loud at boot). `port` is `Number`-coerced only because the schema
- * wants a number, not a string. `dev` mounts the client HMR driver.
+ * wants a number, not a string. `dev` mounts the client HMR driver;
+ * `workspaceRoot` is the parent directory for name-created workspaces.
  */
 interface WebInvocation {
   mode: 'web'
   host?: string
   port?: number
   dev: boolean
+  workspaceRoot?: string
 }
 
 /** The resolved `dsh` invocation: exactly one mode. `--help`/`--version`/errors exit inside {@link parseDshArgs}. */
@@ -48,6 +50,7 @@ interface WebOptions {
   host?: string
   port?: string
   dev?: boolean
+  workspaceRoot?: string
 }
 
 /**
@@ -62,6 +65,7 @@ function resolveWeb(options: WebOptions): WebInvocation {
     ...options.host !== undefined && { host: options.host },
     ...options.port !== undefined && { port: Number(options.port) },
     dev: options.dev === true,
+    ...options.workspaceRoot !== undefined && { workspaceRoot: options.workspaceRoot },
   }
 }
 
@@ -112,6 +116,7 @@ export function parseDshArgs(argv: readonly string[], version: string): DshInvoc
     .option('--host <host>', 'override the config bind host (127.0.0.1 or 0.0.0.0)')
     .option('--port <port>', 'override the config listen port (0 requests an OS-assigned port)')
     .option('--dev', 'mount the client HMR driver and watch plugin bundles for rebuilds')
+    .option('--workspace-root <path>', 'parent directory for name-created workspaces')
     .action((options: WebOptions) => {
       // Commander parses the parent (default-surface) options on either side of
       // the subcommand into `program.opts()`. `web` shares none of them, so a

apps/cli/src/bin.ts

@@ -30,7 +30,7 @@ const invocation = parseDshArgs(process.argv.slice(2), readVersion())
 switch (invocation.mode) {
   case 'web': {
     const { runWeb } = await import('./web.ts')
-    await runWeb(invocation.host, invocation.port, invocation.dev)
+    await runWeb(invocation.host, invocation.port, invocation.dev, invocation.workspaceRoot)
     break
   }
   case 'headless': {

apps/cli/src/web.ts

@@ -24,13 +24,20 @@ const ALL_INTERFACES_HOST = '0.0.0.0'
  * @param host - the bind host, or `undefined` to keep the config default.
  * @param port - the listen port (`0` requests an OS-assigned port), or `undefined` to keep the config default.
  * @param dev - mount the client HMR driver and watch plugin bundles for rebuilds.
+ * @param workspaceRoot - parent directory for name-created workspaces, or `undefined` for the gateway's cwd fallback.
  */
-export async function runWeb(host: string | undefined, port: number | undefined, dev: boolean): Promise<void> {
+export async function runWeb(
+  host: string | undefined,
+  port: number | undefined,
+  dev: boolean,
+  workspaceRoot: string | undefined,
+): Promise<void> {
   const entry = new AppCLIEntry({
     configPath: CONFIG_PATH,
     dev,
     ...host !== undefined && { host },
     ...port !== undefined && { port },
+    ...workspaceRoot !== undefined && { workspaceRoot },
   })
   const { ctx, port: boundPort } = await entry.run()