chamba 0.3.0 → 0.4.0

package/dist/lib/workspace-identity.js

@@ -0,0 +1,260 @@
+// =========================================================================================================================================
+// src/lib/workspace-identity.ts - Workspace identity, registration, and lookup
+// Uses workspace_id from chamba.yaml. Lock files in ~/.chamba/workspaces/<workspace_id>/
+// =========================================================================================================================================
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { readChambaYaml } from "./chamba-yaml.js";
+import { AGENTS_DIR, CHAMBA_DIR, CHAMBA_YAML, CONTAINER_NAME_PREFIX, DEFAULT_PROFILE, GIT_MODE, GIT_MODES, LOCK_FILE, LOCK_VERSION, SHADOWS_DIR, WORKSPACES_DIR, } from "./constants.js";
+/** Maps LockFile field names to their corresponding keys written in the .lock file. */
+export const LOCK_KEYS = {
+    workspaceRoot: "root",
+    activeProfile: "profile",
+    gitMode: "git_mode",
+    webPort: "web_port",
+    version: "version",
+};
+/** Reverse lookup: file key -> LockFile field name, used during parsing. */
+const FILE_KEY_TO_FIELD = Object.fromEntries(Object.entries(LOCK_KEYS).map(([field, key]) => [key, field]));
+/** Pre-computed entries for writing - avoids re-casting on every write. */
+const LOCK_ENTRIES = Object.entries(LOCK_KEYS);
+// --- Path helpers ------------------------------------------------------------------------------------------------------------------------
+/** Base directory for all workspace caches - ~/.chamba/workspaces/ */
+export function getWorkspacesBaseDir() {
+    return join(homedir(), CHAMBA_DIR, WORKSPACES_DIR);
+}
+/** Cache directory for a specific workspace - ~/.chamba/workspaces/<workspace_id>/ */
+export function getWorkspaceDir(workspaceId) {
+    return join(getWorkspacesBaseDir(), workspaceId);
+}
+/** Derive container and image name from workspace ID */
+export function deriveContainerName(workspaceId) {
+    return `${CONTAINER_NAME_PREFIX}${workspaceId}`;
+}
+// --- Lock file ---------------------------------------------------------------------------------------------------------------------------
+/** Parse a workspace .lock file into a LockFile object. Returns null if the file is missing or malformed. */
+function parseLockFile(workspaceId) {
+    const lockPath = join(getWorkspaceDir(workspaceId), LOCK_FILE);
+    try {
+        const lines = readFileSync(lockPath, "utf8")
+            .trimEnd()
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean);
+        const partial = {};
+        for (const line of lines) {
+            const eq = line.indexOf("=");
+            if (eq === -1)
+                continue;
+            const field = FILE_KEY_TO_FIELD[line.slice(0, eq)];
+            if (field)
+                partial[field] = line.slice(eq + 1);
+        }
+        if (!partial.workspaceRoot)
+            return null;
+        return {
+            workspaceRoot: partial.workspaceRoot,
+            activeProfile: partial.activeProfile ?? DEFAULT_PROFILE,
+            gitMode: partial.gitMode ?? GIT_MODE.local,
+            webPort: partial.webPort ?? "",
+            version: partial.version ?? "",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write a LockFile to disk, always writing all keys. Creates the workspace dir if needed.
+ *
+ * The shape version is stamped here rather than taken from the caller, so a lock this chamba writes
+ * always names the shape it was written in - and a key retired from LOCK_KEYS disappears from the file
+ * on the same write.
+ */
+function writeLockFileInternal(workspaceId, data) {
+    const dir = getWorkspaceDir(workspaceId);
+    mkdirSync(dir, { recursive: true });
+    const stamped = { ...data, version: LOCK_VERSION };
+    const content = `${LOCK_ENTRIES.map(([field, key]) => `${key}=${stamped[field]}`).join("\n")}\n`;
+    writeFileSync(join(dir, LOCK_FILE), content);
+}
+/** Read a workspace's lock file. Returns the absolute workspace root path, or null if missing. */
+export function readLockFile(workspaceId) {
+    return parseLockFile(workspaceId)?.workspaceRoot ?? null;
+}
+/** Write a workspace's lock file with the owning workspace root path. Preserves all other fields. */
+export function writeLockFile(workspaceId, workspaceRoot) {
+    const existing = parseLockFile(workspaceId);
+    writeLockFileInternal(workspaceId, {
+        workspaceRoot,
+        activeProfile: existing?.activeProfile ?? DEFAULT_PROFILE,
+        gitMode: existing?.gitMode ?? GIT_MODE.local,
+        webPort: existing?.webPort ?? "",
+        version: LOCK_VERSION,
+    });
+}
+/** Read the active profile name. Returns null if lock file is missing. */
+export function readActiveProfile(workspaceId) {
+    return parseLockFile(workspaceId)?.activeProfile ?? null;
+}
+/** Write the active profile name. Preserves workspace root path and git mode. */
+export function writeActiveProfile(workspaceId, profile) {
+    const existing = parseLockFile(workspaceId);
+    if (!existing)
+        return;
+    writeLockFileInternal(workspaceId, { ...existing, activeProfile: profile });
+}
+/** Read the active git mode. Returns null if lock file is missing. Coerces unknown values to local. */
+export function readGitMode(workspaceId) {
+    const parsed = parseLockFile(workspaceId);
+    if (!parsed)
+        return null;
+    const value = parsed.gitMode;
+    return GIT_MODES.includes(value) ? value : GIT_MODE.local;
+}
+/** Write the active git mode. Preserves workspace root path and active profile. */
+export function writeGitMode(workspaceId, gitMode) {
+    const existing = parseLockFile(workspaceId);
+    if (!existing)
+        return;
+    writeLockFileInternal(workspaceId, { ...existing, gitMode });
+}
+/** Read the sticky web interface host port. Returns null when the lock is missing, unset, or not a positive integer. */
+export function readWebPort(workspaceId) {
+    const value = parseLockFile(workspaceId)?.webPort;
+    if (!value)
+        return null;
+    const port = Number(value);
+    return Number.isInteger(port) && port > 0 ? port : null;
+}
+/**
+ * Write the sticky web interface host port, preserving all other fields. Returns false when the lock
+ * file is missing or unreadable, so the port was NOT persisted: callers must not hand out a port they
+ * failed to record, or the next workspace is handed the same one (it stays invisible to the
+ * assigned-port scan) and two workspaces end up on one URL.
+ */
+export function writeWebPort(workspaceId, port) {
+    const existing = parseLockFile(workspaceId);
+    if (!existing)
+        return false;
+    writeLockFileInternal(workspaceId, { ...existing, webPort: String(port) });
+    return true;
+}
+/** Read the workspace shape version stamped in the lock. Empty string for a lock written without one, null when there is no lock. */
+export function readLockVersion(workspaceId) {
+    return parseLockFile(workspaceId)?.version ?? null;
+}
+// --- Workspace directory initialization --------------------------------------------------------------------------------------------------
+/** Initialize ~/.chamba/workspaces/<workspace_id>/ with lock file and subdirs. */
+export function initWorkspaceDir(workspaceId, workspaceRoot, activeProfile = DEFAULT_PROFILE, gitMode = GIT_MODE.local) {
+    const dir = getWorkspaceDir(workspaceId);
+    mkdirSync(join(dir, AGENTS_DIR), { recursive: true });
+    mkdirSync(join(dir, SHADOWS_DIR), { recursive: true });
+    writeLockFileInternal(workspaceId, { workspaceRoot, activeProfile, gitMode, webPort: "", version: LOCK_VERSION });
+}
+// --- Listing -----------------------------------------------------------------------------------------------------------------------------
+/** List all registered workspace IDs (directories with a .lock file) */
+export function listWorkspaceIds() {
+    const base = getWorkspacesBaseDir();
+    if (!existsSync(base))
+        return [];
+    try {
+        return readdirSync(base).filter((name) => existsSync(join(base, name, LOCK_FILE)));
+    }
+    catch {
+        return [];
+    }
+}
+/** List all registered workspaces as WorkspaceContext objects. Skips entries whose lock target has no chamba.yaml. */
+export function listWorkspaces() {
+    return listWorkspaceIds()
+        .map((workspaceId) => {
+        const lockPath = readLockFile(workspaceId);
+        if (!lockPath)
+            return null;
+        try {
+            const yaml = readChambaYaml(lockPath);
+            if (!yaml || yaml.workspace_id !== workspaceId)
+                return null;
+            return {
+                workspaceId,
+                workspaceRoot: lockPath,
+                containerName: deriveContainerName(workspaceId),
+                workspaceDir: getWorkspaceDir(workspaceId),
+            };
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((w) => w !== null);
+}
+// --- Resolution --------------------------------------------------------------------------------------------------------------------------
+/**
+ * Walk up from the given path looking for chamba.yaml. If found, read workspace_id,
+ * verify lock file, and return WorkspaceContext. Returns null if no chamba.yaml found
+ * or if the workspace dir is not initialized.
+ */
+export function resolveWorkspace(fromPath) {
+    let current = fromPath;
+    while (true) {
+        const yaml = readChambaYaml(current);
+        if (yaml) {
+            const lockPath = readLockFile(yaml.workspace_id);
+            // Workspace dir exists and lock matches this path
+            if (lockPath === current) {
+                return {
+                    workspaceId: yaml.workspace_id,
+                    workspaceRoot: current,
+                    containerName: deriveContainerName(yaml.workspace_id),
+                    workspaceDir: getWorkspaceDir(yaml.workspace_id),
+                };
+            }
+            // chamba.yaml found but workspace not initialized or lock mismatch - return null
+            // (caller handles onboarding / collision)
+            return null;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Walk up from the given path looking for chamba.yaml. Returns the directory containing it, or null.
+ */
+export function findChambaYamlDir(fromPath) {
+    let current = fromPath;
+    while (true) {
+        if (existsSync(join(current, CHAMBA_YAML)))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+// --- Collision and orphan detection ------------------------------------------------------------------------------------------------------
+/** Check if a workspace_id's lock file points to a different path than expected. */
+export function checkCollision(workspaceId, currentPath) {
+    const lockPath = readLockFile(workspaceId);
+    if (lockPath === null)
+        return "ok"; // no lock = no collision
+    return lockPath === currentPath ? "ok" : "collision";
+}
+/**
+ * Scan all workspace dirs for a lock file pointing to the given path.
+ * Used when a workspace_id has changed and we need to find the orphaned dir.
+ * Returns the orphan's workspace_id, or null.
+ */
+export function findOrphanWorkspaceDir(currentPath) {
+    for (const id of listWorkspaceIds()) {
+        const lockPath = readLockFile(id);
+        if (lockPath === currentPath)
+            return id;
+    }
+    return null;
+}

package/package.json

@@ -1,26 +1,63 @@
 {
-  "name": "chamba",
-  "version": "0.3.0",
-  "description": "A browser workspace beside your terminal coding agent - a rich parallel interface to the terminal chat.",
-  "type": "module",
-  "bin": {
-    "chamba": "dist/cli.js"
-  },
-  "engines": {
-    "node": ">=22.12"
-  },
-  "files": [
-    "dist",
-    "web",
-    "inject",
-    "skill",
-    "README.md"
-  ],
-  "dependencies": {
-    "hono": "4.12.30",
-    "@hono/node-server": "1.19.14",
-    "@hono/node-ws": "1.3.1",
-    "ws": "8.21.1",
-    "zod": "4.4.3"
-  }
+    "name": "chamba",
+    "version": "0.4.0",
+    "description": "Run AI coding agents in a container, from your browser",
+    "type": "module",
+    "bin": {
+        "chamba": "./bin/chamba.js"
+    },
+    "dependencies": {
+        "@clack/prompts": "^1.1.0",
+        "ajv": "^8.18.0",
+        "fast-glob": "^3.3.3",
+        "js-yaml": "^4.1.1"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^2.4.10",
+        "@types/js-yaml": "^4.0.9",
+        "@types/node": "^25.4.0",
+        "tsx": "^4.21.0",
+        "typescript": "^5.9.3"
+    },
+    "scripts": {
+        "start": "node bin/chamba.js",
+        "build": "tsx scripts/build.ts",
+        "re:build": "rm -rf dist && pnpm build",
+        "prepare": "git config core.hooksPath .githooks",
+        "typecheck": "tsc --noEmit",
+        "lint": "biome check .",
+        "lint:fix": "biome check --write .",
+        "test": "node --import tsx/esm --test 'tests/*.test.ts'",
+        "test:docker": "node --import tsx/esm --test 'tests/docker/**/*.test.ts'",
+        "test:all": "pnpm test && pnpm test:docker",
+        "validate": "pnpm typecheck && pnpm lint && tsx scripts/check.ts && pnpm test",
+        "check": "pnpm validate && pnpm re:build",
+        "release": "tsx scripts/release.ts",
+        "prepublishOnly": "pnpm re:build"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "license": "MIT",
+    "author": "Asaf Ratzon",
+    "packageManager": "pnpm@11.9.0",
+    "keywords": [
+        "ai",
+        "ai-agent",
+        "claude",
+        "opencode",
+        "codex",
+        "docker",
+        "sandbox",
+        "devcontainer",
+        "cli",
+        "developer-tools"
+    ],
+    "files": [
+        "bin/",
+        "templates/",
+        "schema/",
+        "LICENSE",
+        "dist/"
+    ]
 }

package/schema/chamba.schema.json

@@ -0,0 +1,65 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "chamba.yaml",
+    "description": "Configuration file for chamba - secure AI dev containers",
+    "type": "object",
+    "required": ["workspace_id"],
+    "additionalProperties": false,
+    "properties": {
+        "workspace_id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$",
+            "minLength": 2,
+            "maxLength": 48,
+            "description": "Unique workspace identifier. Used for container naming and cache directory. Lowercase alphanumeric and hyphens only."
+        },
+        "env": {
+            "type": ["string", "array"],
+            "items": { "type": "string" },
+            "description": "Environment injected into the container at runtime. A scalar or a list; each entry is either an env-file path relative to chamba.yaml (e.g. '.env', loaded via --env-file; a missing file is skipped with a warning) or an inline 'KEY=VALUE' variable (contains '=', injected via -e). Inline vars override file-provided values. Changing env recreates the container on the next session."
+        },
+        "shadow_paths": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Gitignore-style patterns. Matching paths are hidden from the agent - the container gets an empty, isolated copy instead. Patterns without a '/' match at any depth (e.g. 'node_modules' matches all nested node_modules too). Patterns with a '/' match relative to the workspace root. Supports globs: * (any chars), ? (single char), {a,b} (alternatives)."
+        },
+        "profiles": {
+            "type": "object",
+            "description": "Named Dockerfile profiles. Each profile defines a dockerfile_hook with raw Dockerfile instructions appended to the base image.",
+            "additionalProperties": {
+                "type": "object",
+                "properties": {
+                    "description": {
+                        "type": "string",
+                        "description": "Human-readable description of this profile shown as a hint during profile selection."
+                    },
+                    "dockerfile_hook": {
+                        "type": "string",
+                        "description": "Raw Dockerfile instructions appended after the base image layers. Use for installing additional runtimes, tools, or dependencies."
+                    }
+                },
+                "additionalProperties": false
+            }
+        },
+        "ports": {
+            "type": "array",
+            "description": "Container ports published to the host, loopback-only (127.0.0.1). A host port already in use fails at startup. Give each workspace its own ports to avoid collisions between parallel workspaces.",
+            "items": {
+                "type": "object",
+                "required": ["port"],
+                "additionalProperties": false,
+                "properties": {
+                    "port": {
+                        "type": ["integer", "string"],
+                        "description": "A bare integer identity-maps the port (e.g. 4820 -> 127.0.0.1:4820:4820). A quoted \"HOST:CONTAINER\" string maps them explicitly, host first as in docker (e.g. \"8080:3000\"). Both sides must be 1024-65535 (the CLI runs unprivileged). Container port 3899 is reserved for the chamba web agent interface."
+                    },
+                    "env": {
+                        "type": "string",
+                        "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+                        "description": "Env var injected into the container carrying the host port number. Allowed only on identity entries (a bare port number)."
+                    }
+                }
+            }
+        }
+    }
+}

package/templates/.dockerignore

@@ -0,0 +1,3 @@
+# Never send a locally-installed webterm/node_modules to the build context - deps are
+# installed in-image by npm ci, and a host install may carry a wrong-arch node-pty build.
+webterm/node_modules

package/templates/Dockerfile

@@ -0,0 +1,173 @@
+# =============================================================================
+# chamba - Secure AI Dev Container (essentials base)
+# =============================================================================
+# Non-root user, git remote block, AI tools: opencode, claude, codex
+# Base runtime: Node.js LTS + python3 (for build scripts)
+#
+# Additional runtimes (Go, Rust, Java, Bun, etc.) are added via
+# dockerfile_hook in chamba.yaml profiles.
+# =============================================================================
+
+# ---------------------------------------------------------------------------
+# Version pinning policy
+# Infra tools whose major versions can change behavior are pinned exact so that
+# fresh and --no-cache builds stay reproducible; bumping a pin edits this file,
+# busts the build hash, and auto-prompts a rebuild. Deliberately left floating:
+# apt packages (pinned by the Debian trixie release), Node (major-pinned via
+# setup_24.x; minors carry security fixes), and the AI CLIs (always latest).
+# ---------------------------------------------------------------------------
+
+FROM debian:trixie-slim
+LABEL chamba.managed=true
+
+# Enable 24-bit color support for AI CLIs (suppresses color upgrade prompts)
+ENV COLORTERM=truecolor
+
+# ---------------------------------------------------------------------------
+# Layer 1 - System packages
+# ---------------------------------------------------------------------------
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    # Core utilities
+    git curl wget bash zsh make \
+    # Build essentials
+    build-essential pkg-config libssl-dev \
+    # Utilities
+    jq unzip zip tree htop procps lsb-release gnupg ca-certificates file bubblewrap \
+    # Modern search/navigation tools (fd-find installs the binary as 'fdfind'; symlinked to 'fd' below)
+    ripgrep fzf fd-find \
+    # Database clients
+    sqlite3 postgresql-client default-mysql-client redis-tools \
+    # Python (needed for build scripts and as a light default)
+    python3 python3-pip python3-venv pipx \
+    && rm -rf /var/lib/apt/lists/*
+
+# ---------------------------------------------------------------------------
+# Layer 2 - fd (from apt fd-find; Debian names the binary 'fdfind')
+# Symlink to 'fd' so the tool is callable by its upstream name.
+# ---------------------------------------------------------------------------
+RUN ln -sf "$(command -v fdfind)" /usr/local/bin/fd
+
+# ---------------------------------------------------------------------------
+# Layer 3 - yq (GitHub release, pinned)
+# ---------------------------------------------------------------------------
+RUN ARCH=$(dpkg --print-architecture) && \
+    curl -fsSL "https://github.com/mikefarah/yq/releases/download/v4.53.3/yq_linux_${ARCH}" \
+        -o /usr/local/bin/yq && chmod +x /usr/local/bin/yq
+
+# ---------------------------------------------------------------------------
+# Layer 4 - GitHub CLI
+# ---------------------------------------------------------------------------
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+        | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg && \
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] \
+        https://cli.github.com/packages stable main" \
+        > /etc/apt/sources.list.d/github-cli.list && \
+    apt-get update && apt-get install -y gh && rm -rf /var/lib/apt/lists/*
+
+# ---------------------------------------------------------------------------
+# Layer 5 - Node.js 24 LTS (via NodeSource)
+# Trixie's apt nodejs is 20.x; NodeSource is pinned to the current Active LTS (24.x).
+# ---------------------------------------------------------------------------
+RUN curl -fsSL https://deb.nodesource.com/setup_24.x | bash - && \
+    apt-get install -y nodejs && rm -rf /var/lib/apt/lists/*
+
+# ---------------------------------------------------------------------------
+# Layer 6 - Git remote block (security boundary)
+# ---------------------------------------------------------------------------
+RUN git config --system protocol.allow never && \
+    git config --system protocol.file.allow always
+
+# ---------------------------------------------------------------------------
+# Layer 7 - Global npm tools (pnpm pinned; AI CLIs always latest)
+# pnpm is pinned exact: pnpm 11 changed where global settings are read from
+# (~/.config/pnpm/config.yaml, no longer ~/.npmrc), so an unpinned major bump
+# can silently break the baked store-dir config.
+#
+# The date is stamped in this same RUN, not further down, because it is the
+# claim "the CLIs are this fresh" and startup.mjs skips its update for a day
+# on the strength of it. Docker caches this layer until a line above changes,
+# so an image rebuilt weeks later can carry CLIs weeks old; written here, the
+# stamp is cached along with them and stays true. Written to a neutral path
+# because /home/devuser does not exist yet - the next layer copies it in.
+# ---------------------------------------------------------------------------
+RUN npm install -g \
+    pnpm@11.6.0 \
+    opencode-ai \
+    @anthropic-ai/claude-code \
+    @openai/codex \
+    && npm cache clean --force \
+    && date -u +"%Y-%m-%dT%H:%M:%S.000Z" > /usr/local/share/ai-cli-installed
+
+# ---------------------------------------------------------------------------
+# Layer 8 - Non-root user
+# ---------------------------------------------------------------------------
+RUN groupadd --gid 1001 devuser && \
+    useradd --uid 1001 --gid devuser --shell /bin/bash --create-home devuser && \
+    mkdir -p /home/devuser/.local/state /home/devuser/.local/share /home/devuser/.local/share/pnpm /home/devuser/.local/bin /home/devuser/.config/pnpm && \
+    cp /usr/local/share/ai-cli-installed /home/devuser/.ai-cli-updated && \
+    chown -R devuser:devuser /home/devuser
+
+# ---------------------------------------------------------------------------
+# Layer 9 - Bake startup script + git mode helper + shared constants + pnpm config into image
+# pnpm 11+ reads settings from ~/.config/pnpm/config.yaml; ~/.npmrc covers anyone pinning pnpm <= 10.
+# ---------------------------------------------------------------------------
+COPY npmrc /home/devuser/.npmrc
+COPY pnpm-config.yaml /home/devuser/.config/pnpm/config.yaml
+COPY startup.mjs /home/devuser/startup.mjs
+COPY startup-git-mode.mjs /home/devuser/startup-git-mode.mjs
+COPY runtime-constants.mjs /home/devuser/runtime-constants.mjs
+RUN chown devuser:devuser /home/devuser/.npmrc /home/devuser/.config/pnpm/config.yaml /home/devuser/startup.mjs /home/devuser/startup-git-mode.mjs /home/devuser/runtime-constants.mjs
+
+# ---------------------------------------------------------------------------
+# Layer 10 - Bake git read-only wrapper into image
+# Symlinked to /usr/local/bin/git by startup.mjs when git_mode=strict.
+# ---------------------------------------------------------------------------
+RUN mkdir -p /usr/local/share/chamba
+COPY git-readonly-wrapper.mjs /usr/local/share/chamba/git-readonly
+RUN chmod +x /usr/local/share/chamba/git-readonly
+
+# ---------------------------------------------------------------------------
+# Layer 11 - Bake the Claude status line script
+# Referenced from ~/.claude/settings.json (statusLine.command) at session start.
+# It prints nothing: what it is for is the per-session snapshot it writes, which
+# the web interface's status strip and the context-usage helper read.
+# ---------------------------------------------------------------------------
+COPY claude-statusline.sh /usr/local/share/chamba/claude-statusline.sh
+RUN chmod +x /usr/local/share/chamba/claude-statusline.sh
+
+# ---------------------------------------------------------------------------
+# Layer 12 - Bake context-usage helper
+# Prints the context/quota snapshot written by the status line script, so
+# agents can inspect their own usage. On PATH via the symlink.
+# ---------------------------------------------------------------------------
+COPY context-usage.sh /usr/local/share/chamba/context-usage.sh
+RUN chmod +x /usr/local/share/chamba/context-usage.sh && \
+    ln -sf /usr/local/share/chamba/context-usage.sh /usr/local/bin/context-usage
+
+# ---------------------------------------------------------------------------
+# Layer 13 - Bake webterm (web agent interface) with deps preinstalled
+# npm ci builds node-pty against this image's toolchain (Layer 1). chamba
+# starts the server with the container; the launcher stays for switching
+# which agent new browser sessions start with.
+# ---------------------------------------------------------------------------
+COPY webterm/ /usr/local/share/chamba/webterm/
+RUN cd /usr/local/share/chamba/webterm && npm ci --omit=dev && npm cache clean --force
+COPY webterm.sh /usr/local/share/chamba/webterm.sh
+RUN chmod +x /usr/local/share/chamba/webterm.sh && \
+    ln -sf /usr/local/share/chamba/webterm.sh /usr/local/bin/webterm
+
+# ---------------------------------------------------------------------------
+# Layer 14 - Bake the web pane publish helper
+# Publishes an HTML file as a page in the calling session's pane. On PATH via
+# the symlink, so any process inside a session can use it.
+# ---------------------------------------------------------------------------
+COPY webpane.sh /usr/local/share/chamba/webpane.sh
+RUN chmod +x /usr/local/share/chamba/webpane.sh && \
+    ln -sf /usr/local/share/chamba/webpane.sh /usr/local/bin/webpane
+
+WORKDIR /workspace
+
+# ---------------------------------------------------------------------------
+# NOTE: USER devuser is appended by chamba at build time (after profile hook)
+# Do not add it here.
+# ---------------------------------------------------------------------------