@gapi/gcli 1.8.243 → 1.8.245

package/.agents/skills/local-ai-runners/SKILL.md

@@ -29,6 +29,11 @@ security, symptom table): `graphql-server/docs/features/local-ai-runners.md`.
   for "token refused" in sync with `RestartPreventExitStatus`. Tests must
   pass an explicit home dir to `SystemdUserService` (os.homedir() ignored a
   changed HOME under jest and wrote into the real `~/.config` once).
+  `runner:daemon:start`/`:restart` check the outcome after ~2 s
+  (`reportStarted`, exit 78 -> the `--reset` hint) - a refused runner exits
+  within a second, so "started" alone would be a lie. Your local `gcli` and
+  the installed unit may both run this repo's `release/index.js` (npm link),
+  so a build changes what the service runs on its next restart.
 
 ## Run it against a dev stack
 
@@ -44,3 +49,12 @@ node release/index.js runner:models --show qwen3.8:27b   # keep the picker short
 Lambforge socket (acks, operation replies, pushes requests), `fakeOllama`
 plays Ollama (tags/show/streamed body, optional hold). Add a case there for
 any protocol change.
+
+## Shared with `workspace:*`
+
+The WebSocket client is `TunnelConnection` (`src/commands/runner/tunnel.ts`);
+`RunnerConnection` (Ollama) and `WorkspaceConnection` (local workspaces,
+`src/commands/workspace/`, feature `local-workspaces`) are its two
+subclasses. Protocol changes (frames, ack/ping, reconnect) go in the base
+class and must keep both test files green (`test/runner.spec.ts`,
+`test/workspace.spec.ts`).

package/AGENTS.md

@@ -34,7 +34,7 @@ fragment in every repo the change touches.
 |---|---|
 | `gcli-command` | Adding a command: registration, lazy actions, `GraphqlClienAPI`, tests, build/release, regenerating `README-CLI.md` |
 | `cluster-targeting` | Commands touching resources that can live on a private cluster (`--clusterId/--clusterName`) |
-| `local-ai-runners` | `runner:*` - the outbound WS client bridging a user's Ollama to the chat |
+| `local-ai-runners` | `runner:*` - the outbound WS client bridging a user's Ollama to the chat (its `TunnelConnection` base also serves `workspace:*`) |
 | `changelog` | Feature-keyed changelog fragments + feature docs |
 
 ## Documentation map
@@ -46,6 +46,7 @@ fragment in every repo the change touches.
 | Features (current state) | [`docs/features/README.md`](docs/features/README.md) |
 | Change history of a feature | `node scripts/changelog.mjs render --feature <slug>` |
 | Local AI runner (slice; canonical in graphql-server) | [`docs/features/local-ai-runners.md`](docs/features/local-ai-runners.md) |
+| Local workspaces - `workspace:*` (slice; canonical in graphql-server) | [`docs/features/local-workspaces.md`](docs/features/local-workspaces.md) |
 | Claude Code config in this package | [`.claude/README.md`](.claude/README.md) |
 
 ## Key patterns
@@ -102,4 +103,4 @@ to debug" live.
   gateway points every later command (and `runner:start`) at dev.
 - Jest needs the `moduleNameMapper` in `jest.config.js` for the `~/` alias -
   without it any spec importing command code fails to resolve.
-- `runner:start` needs Node >= 22 (global `WebSocket`).
+- `runner:start` and `workspace:start` need Node >= 22 (global `WebSocket`).

package/README-CLI.md

@@ -58,11 +58,17 @@ Commands:
   runner:start [options]                               Connect this machine's Ollama to the Lambforge chat as a local AI runner (outbound connection only - works behind NAT, Ollama is never exposed)
   runner:daemon:install|runner:start:daemon [options]  Run the runner in the background as a systemd user service: starts with your session, restarts on failure (Linux)
   runner:daemon:status [options]                       Show the runner service status (systemctl --user status)
+  runner:daemon:start [options]                        Start the installed runner service, and report whether it stays up
+  runner:daemon:stop [options]                         Stop the runner service (it stays installed and starts at your next login)
+  runner:daemon:restart [options]                      Restart the runner service (e.g. after `gcli login` to another server)
   runner:daemon:logs [options]                         Follow the runner service log (journalctl --user -f)
   runner:daemon:uninstall [options]                    Stop and remove the runner service (the runner stays registered)
   runner:list                                          List your local AI runners and the models they serve
   runner:models [options]                              Choose which of a runner's models appear in the chat model picker (no flags: list them)
   runner:delete [options]                              Delete a local AI runner and revoke its token
+  workspace:start [options]                            Connect the current directory to the Lambforge chat as a local workspace: the AI agents can read/edit its files and run commands here (outbound connection only - works behind NAT)
+  workspace:list [options]                             List your local workspaces (online status, directory, processes)
+  workspace:delete [options]                           Delete a local workspace and revoke its token (default: the one registered for this directory)
   help [command]                                       display help for command
 
 --- Subcommand: login ---
@@ -132,6 +138,7 @@ Options:
   --configs <configs...>                           List of kubernetes config names
   --secrets <secrets...>                           List of kubernetes secret names
   --envSecrets <envSecrets...>                     List of kubernetes secret names projected into process.env (graphql environment only)
+  --bodyLimit <bodyLimit>                          Largest request body the lambda accepts, e.g. 20mb (default 10mb, max 100mb)
   --network <network>                              Can be private or public meaning exposed to the router or just for private available can be both also --network private --network public
   --route <route>                                  Lambda route in which will be accessible
   --code <code>                                    URL or local path for single file source code
@@ -174,6 +181,7 @@ Options:
   --configs <configs...>                           List of kubernetes config names
   --secrets <secrets...>                           List of kubernetes secret names
   --envSecrets <envSecrets...>                     List of kubernetes secret names projected into process.env (graphql environment only)
+  --bodyLimit <bodyLimit>                          Largest request body the lambda accepts, e.g. 20mb (default 10mb, max 100mb)
   --network <network>                              Can be private or public meaning exposed to the router or just for private available can be both also --network private --network public
   --route <route>                                  Lambda route in which will be accessible
   --code <code>                                    URL or local path for single file source code
@@ -289,6 +297,7 @@ Options:
   --configs <configs...>                           List of kubernetes config names
   --secrets <secrets...>                           List of kubernetes secret names
   --envSecrets <envSecrets...>                     List of kubernetes secret names projected into process.env (graphql environment only)
+  --bodyLimit <bodyLimit>                          Largest request body the lambda accepts, e.g. 20mb (default 10mb, max 100mb)
   --network <network>                              Can be private or public meaning exposed to the router or just for private available can be both also --network private --network public
   --route <route>                                  Lambda route in which will be accessible
   --code <code>                                    URL or local path for single file source code
@@ -873,6 +882,33 @@ Usage: gcli runner:daemon:status [options]
 
 Show the runner service status (systemctl --user status)
 
+Options:
+  --service <name>  systemd unit name (default: lambforge-runner)
+  -h, --help        display help for command
+
+--- Subcommand: runner:daemon:start ---
+Usage: gcli runner:daemon:start [options]
+
+Start the installed runner service, and report whether it stays up
+
+Options:
+  --service <name>  systemd unit name (default: lambforge-runner)
+  -h, --help        display help for command
+
+--- Subcommand: runner:daemon:stop ---
+Usage: gcli runner:daemon:stop [options]
+
+Stop the runner service (it stays installed and starts at your next login)
+
+Options:
+  --service <name>  systemd unit name (default: lambforge-runner)
+  -h, --help        display help for command
+
+--- Subcommand: runner:daemon:restart ---
+Usage: gcli runner:daemon:restart [options]
+
+Restart the runner service (e.g. after `gcli login` to another server)
+
 Options:
   --service <name>  systemd unit name (default: lambforge-runner)
   -h, --help        display help for command
@@ -924,3 +960,52 @@ Delete a local AI runner and revoke its token
 Options:
   --id <id>   Runner id (default: the runner saved on this machine)
   -h, --help  display help for command
+
+--- Subcommand: workspace:start ---
+Usage: gcli workspace:start [options]
+
+Connect the current directory to the Lambforge chat as a local workspace: the AI agents can read/edit its files and run commands here (outbound connection only - works behind NAT)
+
+Options:
+  -n, --name <name>          Workspace name shown in the chat (default:
+                             directory name)
+  -p, --project <projectId>  Project the workspace belongs to (default: `gcli
+                             project:use`)
+  -t, --token <token>        Workspace token (instead of registering with `gcli
+                             login`)
+  --allow <commands>         Comma-separated commands that run without
+                             approval; * matches anything (e.g. "npm test,npm
+                             run *")
+  --no-default-allow         Do not pre-allow read-only commands (git
+                             status/diff/log, ls, ...)
+  --yolo                     Run EVERY command without asking (only in a
+                             sandbox / a repo you can reset)
+  --no-terminal-approval     Approve commands only in the chat, never prompt in
+                             this terminal
+  --env <names>              Comma-separated environment variables to pass to
+                             commands (default: a minimal environment)
+  --inherit-env              Pass your whole shell environment to commands
+  --allow-secrets            Let the chat read/write .env files, keys and other
+                             secrets files
+  --wsUrl <url>              Lambforge subscriptions endpoint override
+  --reset                    Forget the workspace saved for this directory and
+                             register a new one
+  -h, --help                 display help for command
+
+--- Subcommand: workspace:list ---
+Usage: gcli workspace:list [options]
+
+List your local workspaces (online status, directory, processes)
+
+Options:
+  -p, --project <projectId>  Only this project
+  -h, --help                 display help for command
+
+--- Subcommand: workspace:delete ---
+Usage: gcli workspace:delete [options]
+
+Delete a local workspace and revoke its token (default: the one registered for this directory)
+
+Options:
+  --id <id>   Workspace id (see `gcli workspace:list`)
+  -h, --help  display help for command

package/README.md

@@ -890,7 +890,7 @@ running until Ctrl+C and reconnects on its own.
 | `gcli runner:list` | Your runners: online status, last seen, models |
 | `gcli runner:models` | List which models are shown in the chat; `--show a,b` shows only those, `--all` shows every model, `--none` hides them all; `--id` picks a runner (default: this machine's) |
 | `gcli runner:delete` | Delete a runner and revoke its token (`--id`, default: this machine's) |
-| `gcli runner:start:daemon` / `runner:daemon:install` | Install + start the runner as a systemd user service (Linux); `runner:daemon:status`, `runner:daemon:logs`, `runner:daemon:uninstall` manage it |
+| `gcli runner:start:daemon` / `runner:daemon:install` | Install + start the runner as a systemd user service (Linux); `runner:daemon:start`, `:stop`, `:restart`, `:status`, `:logs`, `:uninstall` manage it |
 
 ### Run it in the background (systemd, Linux)
 
@@ -899,6 +899,9 @@ npm i -g @gapi/gcli                 # a stable install - not the npx cache
 gcli login
 gcli runner:start:daemon            # = runner:daemon:install; same options as runner:start
 gcli runner:daemon:status
+gcli runner:daemon:stop             # stop it (stays installed, starts at next login)
+gcli runner:daemon:start            # start it again; tells you if it does not stay up
+gcli runner:daemon:restart          # e.g. after `gcli login` to another server
 gcli runner:daemon:logs             # follow the log (Ctrl+C to stop following)
 gcli runner:daemon:uninstall        # stop + remove the service (runner stays registered)
 ```
@@ -920,6 +923,56 @@ Notes:
 - Use Profile -> Local AI runners in the web app to see runners, choose
   models with checkboxes, and create tokens.
 
+## Local Workspaces (the chat works in your own project)
+
+`gcli workspace:start` connects the **current directory** to the Lambforge
+chat: the AI agents can read and edit its files, run commands (`npm install`,
+`npm test`, `git diff`, `tsc`) and keep dev servers running (`npm start`) -
+on your machine, in your real (git) project. Same **outbound** WebSocket as
+the Ollama runner: works behind NAT, opens no port. Web workspaces keep
+working as before; this is an additional, local kind.
+
+```bash
+gcli login
+gcli project:use <projectId>           # the workspace belongs to one project
+cd ~/code/my-app
+gcli workspace:start                   # --allow "npm test,npm run *" to skip approvals for those
+```
+
+Then, in a chat of that project (mode Auto): "run the tests in my local
+project and fix what fails", "start the dev server and check it boots". The
+agents only touch files under that directory.
+
+**Commands need your approval** - in this terminal (`[y]es / [a]lways for
+this session / [N]o`) or on the card in the chat; whichever you answer first
+wins. Read-only commands (`git status/diff/log/show`, `ls`, `pwd`, ...) and
+your `--allow` rules run unasked. Destructive ones (`git push`, `git reset
+--hard`, `git clean`, `git commit`, `rm -r`, `sudo`, `curl ... | sh`, ...)
+always ask. `--yolo` runs everything unasked - only for a sandbox or a repo
+you can reset. Nobody answers in 5 minutes = denied.
+
+| Command | Description |
+|---|---|
+| `gcli workspace:start` | Connect this directory. First run registers it (saved in `~/.graphql-server/workspaces.json`, per directory). Options: `--name`, `--project <id>` (default: `gcli project:use`), `--allow <list>` (comma-separated, `*` wildcard), `--no-default-allow`, `--yolo`, `--no-terminal-approval` (approve only in the chat), `--env A,B` (pass these variables to commands), `--inherit-env` (pass your whole environment), `--allow-secrets` (let the chat read `.env`/keys), `--token`, `--wsUrl`, `--reset` |
+| `gcli workspace:list` | Your local workspaces: online, project, directory, running processes (`--project`) |
+| `gcli workspace:delete` | Remove a workspace and revoke its token (`--id`, default: this directory's). Nothing on disk is deleted |
+
+What the chat can and can't do:
+
+- Files: only under the directory (symlinks resolved); `.git` is read-only;
+  `.env*`, private keys, `.npmrc`, ... are invisible unless `--allow-secrets`;
+  `node_modules` and `.gitignore`d files are not listed or searched.
+- Commands run as you, in a minimal environment (PATH, HOME, nvm/pnpm
+  dirs - none of your shell's tokens) unless `--env` / `--inherit-env`.
+- Background processes (`npm start`) live until the chat stops them or you
+  stop gcli - Ctrl+C stops every one of them.
+- Every operation is printed here (`->` read, `✎` write, `$` command,
+  `▶` process), so you can watch what the agent does.
+- Review with `git diff` and commit yourself - the agents are told not to
+  commit, push or reset.
+
+Requires Node.js >= 22.
+
 ## Build System & Local Development
 
 `gcli` includes a high-performance bundler powered by **esbuild**.

package/docs/changelog.d/2026-10-23-local-workspaces-gcli-workspace-start-list-delete-the-chat-agents-work-in-a-l.md

@@ -0,0 +1,13 @@
+## 2026-10-23 - local-workspaces: gcli workspace:start/list/delete - the chat agents work in a local directory
+
+**Feature:** local-workspaces · **Type:** feat
+
+- New `workspace:start` (connect the current directory; registers it with the `gcli login` account in the `--project` / `project:use` project, token saved per directory in `~/.graphql-server/workspaces.json`), `workspace:list`, `workspace:delete`. Options: `--allow`, `--no-default-allow`, `--yolo`, `--no-terminal-approval`, `--env`, `--inherit-env`, `--allow-secrets`, `--token`, `--wsUrl`, `--reset`.
+- The runner's WebSocket client is now a shared base class `TunnelConnection` (`src/commands/runner/tunnel.ts`); `RunnerConnection` keeps its behaviour (same tests) and `WorkspaceConnection` (`src/commands/workspace/connection.ts`) serves `POST /workspace/<op>`.
+- `WorkspaceFiles`: everything confined to the root (symlinks resolved), `.git` read-only, secrets files hidden unless `--allow-secrets`, git-aware listing/search (`.gitignore` respected, `node_modules` skipped), edits by exact unique match with content-hash conflict checks.
+- `CommandPolicy` + `ApprovalGate`: read-only defaults and `--allow` rules run unasked; everything else asks in the terminal AND on the chat card (first answer wins, 5-min expiry); destructive commands always ask unless `--yolo`; "always" remembers program + verb for the session.
+- `runCommand` / `ProcessManager`: process groups (children die too), timeouts, output tails, background processes with a ring buffer and `waitFor`; all stopped when gcli exits. Commands get a minimal environment unless `--env` / `--inherit-env`.
+- Backend half in graphql-server (registry, tunnel, agent tools, LOCAL worker), UI in gql-fission. Canonical doc: `graphql-server/docs/features/local-workspaces.md`.
+- **Test:** `npx jest --coverage=false test/workspace test/runner` - files (escape, symlink, secrets, .gitignore, edit/hash), policy, approvals (web wins, early web answer, terminal deny, expiry), commands/processes (exit codes, timeout kill, waitFor/logs/stop), the connection end to end against a fake server.
+- **Debug:** gcli's own log (`->`, `✎`, `$`, `▶`, `?`, `x`); "refused this workspace" = deleted -> `--reset`; wrong environment -> `~/.graphql-server/url`.
+- **Verification:** full gcli suite 99/99 passing, `npx tsc --noEmit -p .` clean, `npx eslint src test` clean. Not yet run against a live backend.

package/docs/changelog.d/2026-10-24-local-ai-runners-runner-daemon-start-stop-restart-and-start-reports-whether-t.md

@@ -0,0 +1,25 @@
+## 2026-10-24 - local-ai-runners: runner:daemon:start / stop / restart, and start reports whether the runner stays up
+
+**Feature:** local-ai-runners · **Type:** feat
+
+Why: after `runner:daemon:install` there was no gcli way to start or stop the service (only raw `systemctl --user`), and a service whose token Lambforge refuses failed silently: `runner:daemon:status` showed `status=78` with no explanation of what to do.
+
+- New commands (`src/commands/runner/index.ts`, `daemon-commands.ts`), all with `--service`:
+  - `runner:daemon:start` and `runner:daemon:restart` run `systemctl --user start/restart`. After ~2 s, `reportStarted` reads `ActiveState`/`ExecMainStatus` (`SystemdUserService.outcome`) and reports:
+    - running: says so;
+    - exit 78 (`RUNNER_AUTH_EXIT_CODE`): the token was refused - the runner was deleted, or registered on another server than `~/.graphql-server/url` - with the hint to re-register via `gcli runner:daemon:install --reset`;
+    - any other exit: points to `runner:daemon:logs`.
+  - `runner:daemon:stop`: `systemctl --user stop`. The unit stays enabled and starts at the next login; `uninstall` removes it.
+  - All three refuse with "not installed - run `gcli runner:daemon:install` first" when the unit file is missing.
+- `SystemdUserService`: `installed()`, `start()`, `stop()`, `restart()`, `outcome()`.
+- README, `README-CLI.md` (regenerated) and `docs/features/local-ai-runners.md` updated.
+- **Test:**
+  - `npx jest --coverage=false test/runner-daemon.spec.ts` covers: the systemctl calls, `installed()`, and the three `reportStarted` outcomes.
+  - Live: `gcli runner:daemon:stop`, `gcli runner:daemon:start`, then `gcli runner:daemon:status`.
+- **Debug:**
+  - "did not stay up": `gcli runner:daemon:logs`.
+  - "refused this runner's token": compare `~/.graphql-server/url` with the server the runner was registered on, then `runner:daemon:install --reset`.
+- **Verification:**
+  - jest: 11 suites, 103 tests pass (4 new). `tsc --noEmit` and eslint are clean.
+  - `npm run build`: `--help` lists the new commands.
+  - Not run against the real systemd unit.

package/docs/features/README.md

@@ -31,6 +31,7 @@ Outline (drop sections that don't apply):
 | Feature | Doc | Notes |
 |---|---|---|
 | `local-ai-runners` | [local-ai-runners.md](local-ai-runners.md) | `runner:*` commands; canonical doc in graphql-server |
+| `local-workspaces` | [local-workspaces.md](local-workspaces.md) | `workspace:*` commands - the chat agents edit files and run commands in a local directory; canonical doc in graphql-server |
 | `lambforge-agent-skill` | [lambforge-agent-skill.md](lambforge-agent-skill.md) | The agent skill that teaches gcli + `mcp:start`; canonical doc in gql-fission |
 | `dedicated-platform-cluster` | [dedicated-platform-cluster.md](dedicated-platform-cluster.md) | `cluster:status/health/scale/autoscale/...` commands; canonical doc in lambforge-agent |
 | `ci-token-scopes` | [ci-token-scopes.md](ci-token-scopes.md) | Which permission each command needs; `mq-trigger:*` commands; canonical doc in graphql-server |

package/docs/features/local-ai-runners.md

@@ -14,6 +14,8 @@ what lives in gcli.
 | `gcli runner:models [--id] [--show a,b \| --all \| --none]` | Which models appear in the chat picker; no flag = list |
 | `gcli runner:delete [--id]` | Delete a runner and revoke its token (default: the saved one) |
 | `gcli runner:daemon:install` (alias `runner:start:daemon`) `[runner:start options] [--service] [--dry-run]` | Resolve/register the runner now (saves `runner.json`), then install + enable + restart a systemd USER unit running `runner:start --ollama <resolved>` (Linux) |
+| `gcli runner:daemon:start` / `:restart` `[--service]` | `systemctl --user start/restart`, then after ~2 s reads `ActiveState`/`ExecMainStatus` (`SystemdUserService.outcome`): running, or an error - exit 78 = token refused (deleted, or registered on another server than `~/.graphql-server/url`) with the `runner:daemon:install --reset` hint. Refuses when the unit is not installed |
+| `gcli runner:daemon:stop` `[--service]` | `systemctl --user stop` (stays enabled: starts again at the next login) |
 | `gcli runner:daemon:status` / `:logs` / `:uninstall` | `systemctl --user status`, `journalctl --user -f`, disable --now + remove the unit |
 
 Endpoints: `--wsUrl` > `runner.json` > derived from the `gcli login` URL

package/docs/features/local-workspaces.md

@@ -0,0 +1,42 @@
+# Local workspaces (gcli slice)
+
+**Status:** built 2026-10-23. **Feature slug:** `local-workspaces`.
+Canonical doc (flow, backend, security model, debugging):
+`graphql-server/docs/features/local-workspaces.md`.
+
+`gcli workspace:start` serves the current directory to the chat agents over
+the outbound WebSocket tunnel local AI runners use.
+
+## Files
+
+| Path | Responsibility |
+|---|---|
+| `src/commands/runner/tunnel.ts` | `TunnelConnection` - the shared subscriptions-transport-ws client (connect/reconnect, heartbeat timer, request dispatch, ack/ping, `FrameSender`); `RunnerConnection` and `WorkspaceConnection` extend it |
+| `src/commands/workspace/connection.ts` | `WorkspaceConnection`: `workspaceToken`, `localWorkspaceHeartbeat`, the ops allow-list (`WORKSPACE_OPS`, mirrors the backend), `dispatch(op)`, approval frames |
+| `src/commands/workspace/files.ts` | `WorkspaceFiles`: root confinement (incl. symlinks), `.git` read-only, secrets files, git-aware list/search, read/write/edit with content hashes |
+| `src/commands/workspace/policy.ts` | `CommandPolicy`: default allow rules, `--allow`, always-ask patterns, segment matching, "always" rules |
+| `src/commands/workspace/approvals.ts` | `ApprovalGate` (policy -> web card + terminal prompt race, timeout, settle), `TerminalPrompt` |
+| `src/commands/workspace/processes.ts` | `runCommand` (timeout, process-group kill, output tails), `ProcessManager` (background processes, ring buffer, waitFor), `buildEnv` |
+| `src/commands/workspace/{start,list,delete,config,index}.ts` | the commands; `~/.graphql-server/workspaces.json` (0600, keyed by directory) |
+
+## Protocol (what the backend sends)
+
+`POST /workspace/<op>` with a JSON body, answered `head(status) + chunks + end`
+with a JSON body; errors are `{ error }` with 400/403/404/409/500. Ops:
+`info list read write edit delete search exec process/start process/list
+process/logs process/stop`. Anything else is refused before the ack.
+`type: 'approval'` frames carry `{ decision: allow|always|deny }` for an
+approval id this client created with `requestLocalWorkspaceApproval`.
+
+## How to test
+
+`npx jest --coverage=false test/workspace` - real files and processes in a
+temp dir; the connection runs against a fake subscriptions server
+(edit over the tunnel, refused paths, web approval -> command runs, denial).
+
+## How to debug
+
+gcli prints every op: `->` read/list/search, `✎` write/edit/delete, `$`
+command (+ exit code and duration), `▶` / `■` processes, `?` approval
+needed, `x` failed/cancelled. "refused this workspace" = deleted on the web
+(`--reset`). Pointing at the wrong environment: `~/.graphql-server/url`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gapi/gcli",
-  "version": "1.8.243",
+  "version": "1.8.245",
   "repository": {
     "type": "git",
     "url": "https://github.com/Stradivario/gapi.git"