@worca/app 1.4.0 → 1.5.0-rc.2

package/README.md

@@ -197,6 +197,11 @@ and durations, the clarify Q&A, agent transcripts, and logs:
   another project (or a workspace's metrics home) that already records.
 - **A Team metrics page** — project and workspace scope, spend/runs/duration/autonomy/review
   KPIs, breakdowns and a CSV export.
+- **A Timeline for planners** — work items as bars on a calendar (month → week → day), grouped
+  by work item or person: what shipped (the PR merged), what waits for review, what needs
+  attention. Merge dates come from an optional GitHub Action (`worca metrics pr-workflow`) or the
+  GitHub CLI, and the page still works without either. With the Action, pull requests made
+  outside Worca show too, so the calendar covers the whole team's delivery.
 - **`worca metrics push`** — flush pending run records from the CLI, e.g. on a headless machine.
 
 See [`docs/team-metrics.md`](docs/team-metrics.md).
@@ -238,7 +243,7 @@ See [`docs/team-policy.md`](docs/team-policy.md).
   in-process bridge lets the Claude Code CLI run against a Copilot subscription
   (Claude models through Copilot's native Anthropic endpoint, thinking intact;
   GPT, Gemini and the rest through a translation layer) or any
-  `/chat/completions` endpoint — no LiteLLM, no second daemon. Sign in once on
+  `/chat/completions` or `/responses` endpoint — no LiteLLM, no second daemon. Sign in once on
   Settings › Models › Providers, import Copilot's models, pick them anywhere.
   See [`docs/models.md`](docs/models.md).
 
@@ -270,6 +275,31 @@ Requirements:
   `postinstall` didn't run) or the layout isn't npm's, Worca says so rather than
   a bare `ENOENT`; `WORCA_CLAUDE_BIN` can always point at a `claude.exe` directly.
 
+### In a container
+
+Prefer the agents to run in a disposable Linux box instead of on your machine?
+The same Worca ships as an image (`ghcr.io/sinishadjukic/worca`) with a Compose
+file; the UI, the CLI, guardrails, plugins and your data work the same way.
+
+```bash
+worca container up        # from the npm install: writes ~/.worca-cc/container/, starts the box
+worca container login     # log Claude Code in, once; UI on http://localhost:4317
+```
+
+or, without npm, download `docker/compose.yml`, set `WORCA_PROJECTS` in a
+`.env` beside it and `docker compose up -d`. See [`docs/docker.md`](docs/docker.md)
+for login options, git credentials, the egress allowlist, clone-in mode and
+the Windows/WSL2 notes.
+
+### Hosted, behind Cloudflare Access
+
+The same image runs as an always-on service: on Railway (or any host), reachable only through a
+Cloudflare Tunnel with Cloudflare Access in front, and worca verifying the Access token itself.
+Step by step: [`docs/deploy-railway.md`](docs/deploy-railway.md); the Cloudflare side and the
+security model: [`docs/remote-access.md`](docs/remote-access.md). Upgrades, configuration and checks of a running
+deployment: [Operate your deployment](docs/deploy-railway.md#operate-your-deployment), with the
+`tools/railway/worca-railway.mjs` tool and the `/worca-railway` skill for Claude Code.
+
 ## Quick start
 
 ### Web UI
@@ -334,6 +364,9 @@ worca --project /path/to/your/project --prompt "demo task" --mock --yes
 # flush pending team-metrics run records (headless machines with no UI server)
 worca metrics push
 
+# record PR merges for the Team metrics Timeline (adds a GitHub Action; commit and push it)
+worca metrics pr-workflow
+
 # team policy: what applies to this project, fetch the branch now, meet the setup checklist
 worca policy show
 worca policy pull
@@ -387,6 +420,8 @@ The skill starts the same deterministic orchestrator.
 - [Models](docs/models.md) — the catalog, providers (GitHub Copilot, OpenAI-compatible) and the built-in bridge
 - [Getting started](docs/getting-started.md) — the in-app checklist, welcome and spotlight guides
 - [Storage](docs/storage.md) — where state lives, project keys, migration
+- [Remote access](docs/remote-access.md) — opt-in, behind Cloudflare Access, with worca checking the token
+- [Deploy on Railway](docs/deploy-railway.md) — the container as a hosted service behind Cloudflare Access
 - [Releasing](docs/RELEASING.md) — how `@worca/app` versions are published
 - [Contributing](CONTRIBUTING.md) — developing Worca from source
 

package/docker/.env.example

@@ -0,0 +1,54 @@
+# docker/.env.example — copy to .env next to compose.yml. Every line is optional.
+# chmod 600 .env if it holds a token.
+
+# The folder that holds your repositories (mounted at the same path inside;
+# see docs/docker.md for the Windows/WSL2 and /projects notes).
+WORCA_PROJECTS=/Users/me/dev
+# Mount it somewhere else inside the container (loses path parity):
+#WORCA_PROJECTS_MOUNT=/projects
+
+# Image tag: latest | rc | 1.3.0 | 1.3.0-full | dev
+#WORCA_TAG=latest
+
+# Host port the UI is published on (loopback only).
+#WORCA_PORT=4317
+
+# Scheduled runs use wall-clock time in this zone.
+TZ=Europe/Berlin
+
+# Git identity for the commits agents make in run worktrees.
+GIT_AUTHOR_NAME=Your Name
+GIT_AUTHOR_EMAIL=you@example.com
+
+# GitHub over HTTPS: PRs, GitHub Issues source, team metrics/policy branches, clone-in.
+#GH_TOKEN=github_pat_...
+
+# Claude Code auth. Prefer none of these and `docker compose run --rm worca claude`
+# to log in once into the volume. Otherwise ONE of:
+#CLAUDE_CODE_OAUTH_TOKEN=...      # from `claude setup-token` on a logged-in machine
+#ANTHROPIC_API_KEY=sk-ant-...     # Console key (visible to every child process)
+# API key as a compose secret instead (never in the environment):
+#   put the key in ./anthropic_api_key, then add to a compose.override.yml:
+#     services: { worca: { secrets: [anthropic_api_key] } }
+#     secrets: { anthropic_api_key: { file: ./anthropic_api_key } }
+
+# Linux Engine only: your uid/gid when not 1000 (`id -u`, `id -g`).
+#WORCA_UID=1000
+#WORCA_GID=1000
+
+# Resource caps.
+#WORCA_MEM=6g
+#WORCA_CPUS=4
+
+# Corporate proxy / TLS interception.
+#HTTPS_PROXY=http://proxy.corp:3128
+#NO_PROXY=127.0.0.1,localhost
+
+# Egress overlay (compose.egress.yml): allowlist, ".host" allows subdomains.
+#WORCA_EGRESS_ALLOW=api.anthropic.com,github.com,.github.com,.githubusercontent.com,registry.npmjs.org
+
+# SSH overlay (compose.ssh.yml), Linux Engine / Podman only.
+#WORCA_SSH_SOCK=/run/user/1000/keyring/ssh
+
+# Teams overlay (compose.teams.yml).
+#CLOUDFLARE_TUNNEL_TOKEN=...

package/docker/compose.clonein.yml

@@ -0,0 +1,24 @@
+# docker/compose.clonein.yml — clone-in mode: nothing from the host is mounted
+# (docs/docker.md, "Clone-in mode").
+#
+#   docker compose -f compose.yml -f compose.clonein.yml up -d
+#   docker compose -f compose.yml -f compose.clonein.yml run --rm worca \
+#       git clone https://github.com/acme/api.git /projects/api
+#   docker compose -f compose.yml -f compose.clonein.yml run --rm worca worca add --path /projects/api
+#
+# /projects becomes a named volume. Results leave the container only as pushed
+# branches and PRs, so git credentials (GH_TOKEN or the ssh overlay) are needed.
+# `!override` REPLACES the base file's volume list (compose merges lists by
+# target otherwise, which would keep the host bind mount).
+
+services:
+  worca:
+    volumes: !override
+      - worca-home:/worca
+      - claude-config:/home/worca/.claude
+      - projects:/projects
+    environment:
+      WORCA_PROJECTS_ROOT: /projects
+
+volumes:
+  projects:

package/docker/compose.dev.yml

@@ -0,0 +1,24 @@
+# docker/compose.dev.yml — hack on Worca itself inside the container (CONTRIBUTING.md).
+#
+#   cd docker
+#   docker compose -f compose.yml -f compose.dev.yml up            # server from ../ (this checkout)
+#   docker compose -f compose.yml -f compose.dev.yml run --rm worca npm test
+#
+# Bind-mounts the repository checkout over /app and runs the server from it,
+# so edits on the host are live in the container's Linux `claude`. node_modules
+# is a container-side tmpfs owned by the worca user (a named volume at a path
+# the image does not have would be created root-owned): the host's modules stay
+# untouched, and `npm ci` (about a second) runs on every start.
+
+services:
+  worca:
+    image: ghcr.io/sinishadjukic/worca:${WORCA_TAG:-dev}
+    working_dir: /app
+    volumes:
+      - ..:/app
+    tmpfs:
+      - /tmp:size=2g
+      - /app/node_modules:size=1g,uid=1000,gid=1000
+    environment:
+      WORCA_HOME: /worca
+    command: ["bash", "-c", "npm ci --no-audit --no-fund && exec node --disable-warning=ExperimentalWarning ui/server.mjs"]

package/docker/compose.egress.yml

@@ -0,0 +1,47 @@
+# docker/compose.egress.yml — egress allowlist overlay (docs/docker.md, "Egress allowlist").
+#
+#   docker compose -f compose.yml -f compose.egress.yml up -d
+#
+# Puts worca on an INTERNAL network (no route to the internet) and adds a
+# forward proxy from the same image that relays only to allowlisted hosts.
+# Tools that honour HTTPS_PROXY (claude, git, gh, npm, pip, curl) work for
+# allowed hosts; a raw socket from `node -e` or `python -c` cannot leave.
+#
+#   WORCA_EGRESS_ALLOW   comma-separated hosts; ".example.com" allows subdomains.
+#                        Default: api.anthropic.com, github.com, .github.com,
+#                        .githubusercontent.com, registry.npmjs.org
+
+services:
+  worca:
+    depends_on:
+      - egress
+    networks:
+      - internal
+    environment:
+      HTTPS_PROXY: http://egress:3128
+      HTTP_PROXY: http://egress:3128
+      NO_PROXY: 127.0.0.1,localhost
+      # Playwright downloads Chromium from a CDN; add it to the allowlist or
+      # pre-fetch it. Listed here so the failure is legible, not silent.
+      PLAYWRIGHT_DOWNLOAD_HOST: ${PLAYWRIGHT_DOWNLOAD_HOST:-}
+
+  egress:
+    image: ghcr.io/sinishadjukic/worca:${WORCA_TAG:-latest}
+    entrypoint: ["tini", "-s", "--", "node", "/usr/local/lib/worca-egress-proxy.mjs"]
+    command: []
+    environment:
+      WORCA_EGRESS_ALLOW: ${WORCA_EGRESS_ALLOW:-}
+    networks:
+      - internal
+      - default
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    pids_limit: 128
+    mem_limit: 256m
+    restart: unless-stopped
+
+networks:
+  internal:
+    internal: true

package/docker/compose.ssh.yml

@@ -0,0 +1,17 @@
+# docker/compose.ssh.yml — forward the host's SSH agent (docs/docker.md, "Git credentials").
+#
+#   docker compose -f compose.yml -f compose.ssh.yml up -d
+#
+# Keys never enter the container; the agent socket does. While it is mounted an
+# agent CAN use it, so pair this with the egress overlay for untrusted tasks.
+#
+#   Docker Desktop (macOS/Windows): the socket is /run/host-services/ssh-auth.sock
+#                                   inside the VM — leave WORCA_SSH_SOCK unset.
+#   Linux Engine / Podman:          WORCA_SSH_SOCK=$SSH_AUTH_SOCK in .env
+
+services:
+  worca:
+    volumes:
+      - ${WORCA_SSH_SOCK:-/run/host-services/ssh-auth.sock}:/ssh-agent.sock
+    environment:
+      SSH_AUTH_SOCK: /ssh-agent.sock

package/docker/compose.teams.yml

@@ -0,0 +1,25 @@
+# docker/compose.teams.yml — Microsoft Teams webhook ingress (docs/docker.md, "Teams").
+#
+#   docker compose -f compose.yml -f compose.teams.yml up -d
+#
+# Teams is the one chat channel that needs an inbound HTTPS URL (Bot Framework
+# has no polling mode). A cloudflared sidecar dials OUT to Cloudflare and
+# forwards to worca's token-guarded ingress route; nothing is published.
+#
+#   CLOUDFLARE_TUNNEL_TOKEN   a named tunnel's token (recommended; stable URL)
+#                             unset: a Quick Tunnel with a random trycloudflare.com
+#                             URL printed in `docker compose logs teams-tunnel`
+
+services:
+  teams-tunnel:
+    image: cloudflare/cloudflared:latest
+    command: >
+      tunnel --no-autoupdate
+      ${CLOUDFLARE_TUNNEL_TOKEN:+run --token }${CLOUDFLARE_TUNNEL_TOKEN:---url http://worca:4317}
+    depends_on:
+      - worca
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    restart: unless-stopped

package/docker/compose.yml

@@ -0,0 +1,57 @@
+# docker/compose.yml — run Worca in a container (docs/docker.md).
+#
+#   mkdir worca && cd worca
+#   curl -fsSLO https://raw.githubusercontent.com/SinishaDjukic/worca-cc/dev/docker/compose.yml
+#   echo "WORCA_PROJECTS=$HOME/dev" > .env
+#   docker compose up -d                    # http://localhost:4317
+#   docker compose run --rm worca claude    # log Claude Code in, once
+#
+# Everything you change is a variable in .env (see docker/.env.example); this
+# file is not edited. Overlays (egress allowlist, SSH agent, Teams tunnel,
+# clone-in, dev) are separate files added with -f.
+
+name: worca
+
+services:
+  worca:
+    image: ghcr.io/sinishadjukic/worca:${WORCA_TAG:-latest}
+    init: true
+    user: "${WORCA_UID:-1000}:${WORCA_GID:-1000}"
+    ports:
+      # Loopback only. The server's Host/Origin guard accepts localhost, and
+      # nothing else should reach an unauthenticated UI that runs agents.
+      - "127.0.0.1:${WORCA_PORT:-4317}:4317"
+    volumes:
+      - worca-home:/worca                       # DB, store, runs, plugins, ui.json
+      - claude-config:/home/worca/.claude       # Claude Code login, settings, memory
+      # Your repositories. Same path on both sides (path parity) so git
+      # worktree metadata stays valid on the host; see docs/docker.md.
+      - ${WORCA_PROJECTS:-${HOME}/dev}:${WORCA_PROJECTS_MOUNT:-${WORCA_PROJECTS:-${HOME}/dev}}
+    environment:
+      TZ: ${TZ:-UTC}
+      WORCA_PROJECTS_ROOT: ${WORCA_PROJECTS_MOUNT:-${WORCA_PROJECTS:-${HOME}/dev}}
+      GIT_AUTHOR_NAME: ${GIT_AUTHOR_NAME:-}
+      GIT_AUTHOR_EMAIL: ${GIT_AUTHOR_EMAIL:-}
+      GIT_COMMITTER_NAME: ${GIT_AUTHOR_NAME:-}
+      GIT_COMMITTER_EMAIL: ${GIT_AUTHOR_EMAIL:-}
+      GH_TOKEN: ${GH_TOKEN:-}
+      CLAUDE_CODE_OAUTH_TOKEN: ${CLAUDE_CODE_OAUTH_TOKEN:-}
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
+      HTTPS_PROXY: ${HTTPS_PROXY:-}
+      HTTP_PROXY: ${HTTP_PROXY:-}
+      NO_PROXY: ${NO_PROXY:-127.0.0.1,localhost}
+      WORCA_MOCK: ${WORCA_MOCK:-}
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    pids_limit: 2048
+    mem_limit: ${WORCA_MEM:-6g}
+    cpus: ${WORCA_CPUS:-4}
+    tmpfs:
+      - /tmp:size=2g
+    restart: unless-stopped
+
+volumes:
+  worca-home:
+  claude-config:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worca/app",
-  "version": "1.4.0",
+  "version": "1.5.0-rc.2",
   "description": "Worca — deterministic multi-agent pipeline that drives Claude Code (headless) through Plan -> Refine -> Implement -> Review, with a CLI, an installable /worca skill, and a web UI.",
   "license": "MIT",
   "author": "Sinisha Djukic",
@@ -38,6 +38,8 @@
     "skills/",
     "scripts/",
     "tools/install.mjs",
+    "docker/compose*.yml",
+    "docker/.env.example",
     "README.md"
   ],
   "scripts": {
@@ -49,6 +51,7 @@
     "smoke:workspace": "WORCA_MOCK=1 WORCA_HOME=.worca-cc-smoke node --disable-warning=ExperimentalWarning tools/smoke-workspace.mjs",
     "smoke:plugin": "WORCA_MOCK=1 WORCA_HOME=.worca-cc-smoke node --disable-warning=ExperimentalWarning tools/smoke-plugin.mjs",
     "docker:build": "node tools/docker-build.mjs",
+    "docker:smoke": "node tools/docker-smoke.mjs",
     "ask:fixtures": "node --disable-warning=ExperimentalWarning tools/ask-capture-fixtures.mjs",
     "verify:composer": "node --disable-warning=ExperimentalWarning tools/verify-composer-cdp.mjs",
     "verify:run-monitor": "node --disable-warning=ExperimentalWarning tools/verify-run-monitor-cdp.mjs",

package/src/cli/container.mjs

@@ -0,0 +1,227 @@
+// src/cli/container.mjs
+// `worca container` — run Worca in a container from the npm install
+// (docs/docker.md; plans/container-isolation-design.md §12.3). A thin wrapper:
+// it writes the package's compose files into <worcaHome>/container/, seeds a
+// .env once, and shells out to `docker compose` (or `podman compose`). Nothing
+// here talks to the engine; the box runs its own Worca with its own home.
+//
+// Every verb takes { out, c, fail } from the CLI and an injectable `exec` so
+// tests never spawn a runtime.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, copyFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+
+import { worcaHome, listProjects } from '../core/projects.mjs';
+
+/** The compose files shipped in the package (package.json `files`). */
+export const COMPOSE_SRC_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'docker');
+export const OVERLAYS = Object.freeze(['egress', 'ssh', 'teams', 'clonein']);
+const STATE_FILE = '.worca-container.json';
+
+export const CONTAINER_HELP = `worca container — run Worca in a container (docs/docker.md)
+
+  worca container init [--projects <dir>]        Write the compose files and a .env into the container dir
+  worca container up [--with <overlays>] [--tag <t>]
+                                                 Start the box in the background and print the URL.
+                                                 --with: comma-separated egress,ssh,teams,clonein (remembered)
+  worca container down                           Stop and remove the containers (volumes are kept)
+  worca container status                         Which containers are up
+  worca container logs [--follow]                Server logs
+  worca container pull                           Pull the newest image for the tag in .env
+  worca container login                          Log Claude Code in, once, into the box's own volume
+  worca container shell                          A bash shell inside the box
+  worca container run -- <worca args>            Run the Worca CLI inside the box
+                                                 e.g. worca container run -- --project /path/to/repo --prompt "…"
+  worca container where                          Print the container dir (compose files, .env)
+  worca container help
+
+Options:
+  --dir <d>        Container dir (default: <worcaHome>/container)
+  --runtime <r>    docker | podman (default: autodetect; env WORCA_CONTAINER_RUNTIME)
+
+The box has its own Worca home and its own Claude Code login: nothing from
+~/.worca-cc or ~/.claude is mounted. Your repositories are mounted at the same
+path as on the host (WORCA_PROJECTS in .env), so run worktrees stay valid here.
+`;
+
+/** Default exec: run and inherit the terminal. Returns { status }. */
+function defaultExec(cmd, args, { cwd, capture = false, env } = {}) {
+  const r = spawnSync(cmd, args, { cwd, env, stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit', encoding: 'utf8' });
+  return { status: r.error ? 127 : (r.status ?? 1), stdout: r.stdout || '', stderr: r.stderr || '' };
+}
+
+/** `docker compose` or `podman compose`, by flag, env, then autodetect. */
+export function detectRuntime(exec, want) {
+  const pick = want || process.env.WORCA_CONTAINER_RUNTIME || '';
+  const candidates = pick ? [pick] : ['docker', 'podman'];
+  for (const bin of candidates) {
+    if (!['docker', 'podman'].includes(bin)) return { error: `--runtime must be docker or podman, got ${bin}` };
+    if (exec(bin, ['compose', 'version'], { capture: true }).status === 0) return { bin };
+  }
+  return { error: pick ? `${pick} compose is not available` : 'no container runtime found: install Docker Desktop, Docker Engine or Podman (with podman compose)' };
+}
+
+function parse(argv) {
+  const o = { verb: argv[0] || 'help', dir: null, runtime: null, projects: null, with: null, tag: null, follow: false, passthrough: [], _: [] };
+  const rest = argv.slice(1);
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === '--') { o.passthrough = rest.slice(i + 1); break; }
+    else if (a === '--dir') o.dir = rest[++i];
+    else if (a === '--runtime') o.runtime = rest[++i];
+    else if (a === '--projects') o.projects = rest[++i];
+    else if (a === '--with') o.with = rest[++i];
+    else if (a === '--tag') o.tag = rest[++i];
+    else if (a === '--follow' || a === '-f') o.follow = true;
+    else o._.push(a);
+  }
+  return o;
+}
+
+/** Longest common ancestor directory of the registered projects, or null. */
+export function commonParent(paths) {
+  const parts = paths.filter(Boolean).map((p) => resolve(p).split(/[\\/]+/));
+  if (!parts.length) return null;
+  let prefix = parts[0].slice(0, -1);             // a project's parent, never the project itself
+  for (const p of parts.slice(1)) {
+    let n = 0;
+    while (n < prefix.length && n < p.length - 1 && prefix[n] === p[n]) n++;
+    prefix = prefix.slice(0, n);
+  }
+  if (prefix.length <= 1) return null;            // "/" or a drive root is too wide to mount
+  return prefix.join('/') || '/';
+}
+
+/** The .env body for a fresh container dir: the example with the known values filled in. */
+export function seedEnv(example, { projects, tz, gitName, gitEmail }) {
+  const set = (body, key, value) => {
+    if (!value) return body;
+    const re = new RegExp(`^#?${key}=.*$`, 'm');
+    return re.test(body) ? body.replace(re, `${key}=${value}`) : `${body}\n${key}=${value}\n`;
+  };
+  let body = example;
+  body = set(body, 'WORCA_PROJECTS', projects);
+  body = set(body, 'TZ', tz);
+  body = set(body, 'GIT_AUTHOR_NAME', gitName);
+  body = set(body, 'GIT_AUTHOR_EMAIL', gitEmail);
+  return body;
+}
+
+function readState(dir) {
+  try { return JSON.parse(readFileSync(join(dir, STATE_FILE), 'utf8')); } catch { return {}; }
+}
+function writeState(dir, state) {
+  writeFileSync(join(dir, STATE_FILE), JSON.stringify(state, null, 2) + '\n');
+}
+
+/** `-f compose.yml -f compose.<overlay>.yml …` for the remembered or requested overlays. */
+export function composeFileArgs(overlays) {
+  const args = ['-f', 'compose.yml'];
+  for (const o of overlays) args.push('-f', `compose.${o}.yml`);
+  return args;
+}
+
+function parseWith(s) {
+  if (!s) return [];
+  const list = s.split(',').map((x) => x.trim()).filter(Boolean);
+  const bad = list.filter((x) => !OVERLAYS.includes(x));
+  if (bad.length) return { error: `--with: unknown overlay ${bad.join(', ')} (known: ${OVERLAYS.join(', ')})` };
+  return [...new Set(list)];
+}
+
+/** Copy the package's compose files into `dir` (always, they are versioned with the package)
+ *  and seed .env once. Returns { dir, envCreated }. */
+export async function initDir(dir, { projects, exec, srcDir = COMPOSE_SRC_DIR, env = process.env } = {}) {
+  mkdirSync(dir, { recursive: true });
+  for (const f of readdirSync(srcDir)) {
+    if (/^compose(\.[a-z]+)?\.yml$/.test(f)) copyFileSync(join(srcDir, f), join(dir, f));
+  }
+  const envPath = join(dir, '.env');
+  let envCreated = false;
+  if (!existsSync(envPath)) {
+    let root = projects;
+    if (!root) {
+      try { root = commonParent((await listProjects()).map((p) => p.path)); } catch { root = null; }
+    }
+    if (!root) root = join(env.HOME || env.USERPROFILE || homedir(), 'dev');
+    const git = (k) => { const r = exec('git', ['config', '--get', k], { capture: true }); return r.status === 0 ? r.stdout.trim() : ''; };
+    const body = seedEnv(readFileSync(join(srcDir, '.env.example'), 'utf8'), {
+      projects: root,
+      tz: Intl.DateTimeFormat().resolvedOptions().timeZone,
+      gitName: git('user.name'),
+      gitEmail: git('user.email'),
+    });
+    writeFileSync(envPath, body, { mode: 0o600 });
+    envCreated = true;
+  }
+  return { dir, envCreated };
+}
+
+function readEnvValue(dir, key) {
+  try {
+    const m = new RegExp(`^${key}=(.*)$`, 'm').exec(readFileSync(join(dir, '.env'), 'utf8'));
+    return m ? m[1].trim() : '';
+  } catch { return ''; }
+}
+
+/**
+ * `worca container <verb> …`. Returns the process exit code.
+ * @param {string[]} argv          tokens after `container`
+ * @param {object} io              { out, c, fail } from the CLI; `exec` and `dir` are injectable for tests
+ */
+export async function cmdContainer(argv, { out, c, fail, exec = defaultExec, dir: dirOverride = null } = {}) {
+  const a = parse(argv);
+  if (a.verb === 'help' || a.verb === '--help' || a.verb === '-h') { out(CONTAINER_HELP.trimEnd()); return 0; }
+  const dir = resolve(a.dir || dirOverride || join(worcaHome(), 'container'));
+  if (a.verb === 'where') { out(dir); return 0; }
+
+  const rt = detectRuntime(exec, a.runtime);
+  if (rt.error) { fail(rt.error); return 1; }
+  const state = readState(dir);
+  let overlays = Array.isArray(state.with) ? state.with : [];
+  const compose = (args, opts = {}) => exec(rt.bin, ['compose', ...composeFileArgs(overlays), ...args], { cwd: dir, ...opts }).status;
+
+  if (a.verb === 'init' || a.verb === 'up') {
+    const r = await initDir(dir, { projects: a.projects, exec });
+    out(`${c('bold', 'container dir')}  ${dir}${r.envCreated ? `   (${c('green', '.env created')} — edit it: WORCA_PROJECTS, tokens)` : ''}`);
+    if (a.verb === 'init') return 0;
+  }
+  if (!existsSync(join(dir, 'compose.yml'))) { fail(`no compose files in ${dir}; run: worca container init`); return 1; }
+
+  switch (a.verb) {
+    case 'up': {
+      if (a.with !== null) {
+        const parsed = parseWith(a.with);
+        if (parsed.error) { fail(parsed.error); return 1; }
+        overlays = parsed;
+        writeState(dir, { ...state, with: overlays });
+      }
+      const env = a.tag ? { ...process.env, WORCA_TAG: a.tag } : undefined;
+      const port = readEnvValue(dir, 'WORCA_PORT') || '4317';
+      const code = exec(rt.bin, ['compose', ...composeFileArgs(overlays), 'up', '-d'], { cwd: dir, env }).status;
+      if (code !== 0) return code;
+      out(`${c('bold', 'Worca')}  http://localhost:${port}${overlays.length ? `   overlays: ${overlays.join(', ')}` : ''}`);
+      out(`  Log in once:  ${c('bold', 'worca container login')}`);
+      out(`  Stop:         ${c('bold', 'worca container down')}`);
+      return 0;
+    }
+    case 'down': return compose(['down']);
+    case 'status': return compose(['ps']);
+    case 'logs': return compose(['logs', ...(a.follow ? ['-f'] : []), 'worca']);
+    case 'pull': return compose(['pull', 'worca']);
+    case 'login': return compose(['run', '--rm', 'worca', 'claude']);
+    case 'shell': return compose(['run', '--rm', 'worca', 'bash']);
+    case 'run': {
+      const args = a.passthrough.length ? a.passthrough : a._;
+      if (!args.length) { fail('Usage: worca container run -- <worca args>'); return 1; }
+      return compose(['run', '--rm', 'worca', 'worca', ...args]);
+    }
+    default:
+      fail(`unknown container verb: ${a.verb}\n\n${CONTAINER_HELP}`);
+      return 1;
+  }
+}

package/src/cli/models.mjs

@@ -13,6 +13,7 @@ import {
   endpointModelsForImport, importEndpointModels,
 } from '../core/bridge/provider-ops.mjs';
 import { listModels } from '../core/config.mjs';
+import { isTranslatedApi } from '../core/model-env.mjs';
 
 export const MODELS_HELP = `worca models — the model catalog and its providers
 
@@ -76,7 +77,7 @@ export function formatModelLine(m) {
   else if (m.custom === 'policy') bits.push('policy');
   else if (m.custom === 'global') bits.push('yours');
   else if (!m.custom) bits.push('built-in');
-  if (m.bridged) bits.push(`bridged: ${m.bridged}${m.upstreamModel ? ` → ${m.upstreamModel}` : ''}${m.upstreamApi === 'openai-chat' ? ' (translated)' : ''}`);
+  if (m.bridged) bits.push(`bridged: ${m.bridged}${m.upstreamModel ? ` → ${m.upstreamModel}` : ''}${isTranslatedApi(m.upstreamApi) ? ' (translated)' : ''}`);
   else if (m.routed) bits.push('endpoint-routed');
   if (m.needsSignIn) bits.push(`NEEDS ${m.signInReason === 'no_key' ? 'API KEY' : m.signInReason === 'terms' ? 'ACKNOWLEDGEMENT' : 'SIGN-IN'}`);
   if (m.hidden) bits.push('hidden');
@@ -208,14 +209,14 @@ export async function cmdModels(argv, { out, c, fail, sleep: wait = sleep }) {
     else if (args.all) ids = importable.map((m) => m.id);
     else {
       out('Copilot models (pass --all, or --pick id,id,…):');
-      for (const m of list) out(`  ${m.id.padEnd(28)} ${m.vendor.padEnd(10)} ${(m.contextWindow ? `${Math.round(m.contextWindow / 1000)}k` : '-').padStart(5)}  ${m.toolCalls ? 'tools' : '     '} ${m.vision ? 'vision' : '      '} ${m.reasoning ? 'reasoning' : '         '}${m.inCatalog ? '  (in catalog)' : ''}${m.policyState && m.policyState !== 'enabled' ? '  (disabled in Copilot settings)' : ''}`);
+      for (const m of list) out(`  ${m.id.padEnd(28)} ${m.vendor.padEnd(10)} ${(m.contextWindow ? `${Math.round(m.contextWindow / 1000)}k` : '-').padStart(5)}  ${m.toolCalls ? 'tools' : '     '} ${m.vision ? 'vision' : '      '} ${m.reasoning ? 'reasoning' : '         '}  ${String(m.api || '').padEnd(16)}${m.inCatalog ? '  (in catalog)' : ''}${m.policyState && m.policyState !== 'enabled' ? '  (disabled in Copilot settings)' : ''}`);
       return 0;
     }
-    out('These run through your Copilot subscription. Claude models keep extended thinking; other vendors run through a translation layer (no thinking blocks, no web tools).');
+    out('These run through your Copilot subscription. Claude models keep extended thinking; other vendors run through a translation layer (no web tools; reasoning arrives as summaries on the Responses API).');
     if (!(await confirm(`Import ${ids.length} model${ids.length === 1 ? '' : 's'} into the catalog?`, args.yes, { c }))) return fail('cancelled');
     const r = await importCopilotModels(ids);
     for (const id of r.created) out(`  + ${id}`);
-    for (const id of r.updated) out(`  ~ ${id} (capabilities refreshed)`);
+    for (const id of r.updated) out(`  ~ ${id} (API and capabilities refreshed)`);
     for (const id of r.skipped) out(`  - ${id} (skipped: not offered, or not a copilot entry)`);
     return 0;
   }