@cyanautomation/kaseki-agent 1.4.1

package/CONTRIBUTING.md

@@ -0,0 +1,339 @@
+# Contributing to Kaseki Agent
+
+Thanks for helping improve Kaseki Agent. This repo is the host/container orchestration layer for running ephemeral coding-agent jobs, so changes here should stay bounded, reproducible, and operator-friendly.
+
+## 1) Proposing or updating `TASK_PROMPT` defaults and guardrails
+
+`TASK_PROMPT` defaults are currently defined in both runtime entrypoints:
+
+- Host launcher: `run-kaseki.sh`
+- Container runner: `kaseki-agent.sh`
+
+When changing default prompt behavior, update both files in the same PR so host metadata and in-container execution stay aligned.
+
+### What to include in prompt changes
+
+- **Task objective clarity:** what behavior the downstream agent should change.
+- **Scope boundaries:** which files/types of changes are allowed.
+- **Security guardrails:** explicit instruction to avoid printing/exposing secrets, credentials, or env vars.
+- **Test expectation in prompt:** call out the focused test file(s) to update when behavior changes.
+
+### PR expectations for prompt changes
+
+- Explain *why* the prompt default changed and what failure mode it addresses.
+- Include before/after prompt snippets (or a concise diff summary).
+- Confirm both scripts were updated together (unless intentionally diverged, which should be justified).
+
+## 2) Test expectations for upstream target repos
+
+Behavior changes in target repos must include corresponding tests. In particular:
+
+- Add or update **focused Vitest coverage** whenever behavior changes.
+- Prefer narrow, deterministic tests near the touched behavior (for example, parser-focused tests rather than broad end-to-end-only coverage).
+- Ensure `KASEKI_VALIDATION_COMMANDS` still reflects the expected upstream validation sequence.
+
+If a prompt requests behavior changes but no focused Vitest update is present, treat that as an incomplete contribution.
+
+### Validation fail-fast behavior
+
+Kaseki Agent validates changes using a **fail-fast pipeline** to minimize wasted CI time:
+
+- **Quality gates run first** — Diff size, allowlist, and secret scans run before validation commands. If any quality gate fails, validation is skipped entirely.
+- **Validation stops at first failure** — By default (`KASEKI_VALIDATION_FAIL_FAST=1`), validation stops at the first command failure instead of running all commands. This saves 10-60s per run when early commands fail.
+- **Missing npm scripts are skipped** — Validation commands like `npm run check` are skipped automatically if the script doesn't exist in `package.json`, with a warning logged.
+
+**Controlling fail-fast behavior:**
+
+| Variable | Default | Notes |
+|---|---|---|
+| `KASEKI_VALIDATION_FAIL_FAST` | 1 | Set to 0 to run all validation commands despite early failures (old behavior) |
+| `KASEKI_STRICT_SCRIPT_CHECK` | 0 | Set to 1 to fail validation if any npm script is missing (for strict repos) |
+
+**Example:** If `npm run check` (missing), `npm run test`, and `npm run build` are configured, with fail-fast enabled:
+
+1. `npm run check` is skipped (script missing) → warning logged
+2. `npm run test` runs and fails → validation stops
+3. `npm run build` is NOT run (fail-fast stopped the loop)
+
+**Metadata tracking:** Kaseki records fail-fast decisions in `metadata.json`:
+
+- `validation_fail_fast_mode`: whether fail-fast was enabled for this run
+- `validation_stopped_early`: whether validation stopped at first failure
+- `validation_commands_attempted`: how many validation commands actually ran
+
+Contributors should be aware of fail-fast behavior when designing validation commands; avoid side effects that depend on the full command sequence running.
+
+## 3) TypeScript Development Setup
+
+This repo is written in **TypeScript 5.7** and compiles to CommonJS in the `dist/` directory. Source files are in `src/` and must be compiled before use.
+
+### Building and Type-Checking
+
+```bash
+npm run build                  # Compile TypeScript to dist/
+npm run type-check             # Full-project type-check (informational while debt is tracked)
+npm run type-check:full        # Alias for full-project type-check
+npm run type-check:changed     # Changed-file gate used for PR blocking
+```
+
+### Key directories and files
+
+- **`src/`** — TypeScript source files (utilities, CLI, test files)
+- **`dist/`** — Compiled JavaScript output (generated by `npm run build`)
+- **`tsconfig.json`** — TypeScript compiler configuration with strict mode enabled
+- **`.eslintignore`** — ESLint excludes `dist/` (check compiled output separately if needed)
+
+### Development workflow
+
+1. Edit `.ts` files in `src/`
+2. Run `npm run type-check:changed` to verify changed-file type safety (PR gate)
+3. Optionally run `npm run type-check` (or `npm run type-check:full`) to view full-project debt status
+4. Run `npm run build` to compile (or let `npm test` do it as part of the pre-test check)
+5. Run focused unit tests while iterating (for example `npm run test:unit -- src/result-cache.test.ts` or `npm run test:unit -- -t "cache"`)
+6. Run `npm run test:ci` before submitting to execute full CI-style validation (build + type-check + Jest + bash integration tests)
+
+### Running a single test file
+
+When you only need to run one unit test file, prefer the unit-test script (or direct Jest invocation) instead of `npm test`.
+
+```bash
+npm run test:unit -- src/result-cache.test.ts
+npx jest src/result-cache.test.ts
+```
+
+Use `npm test` when you want the full validation pipeline (build + type-check + jest + integration scripts).
+
+```bash
+npm test
+```
+
+### Type Safety Standards
+
+- **Strict mode enabled** — All files compile with `"strict": true`
+- **No implicit any** — Function parameters and return types must be explicit
+- **ESM modules** — Source uses ES2024 syntax; CommonJS output for Node compatibility
+- **Declaration files** — TypeScript generates `.d.ts` for CLI library exports
+
+## 4) Code Quality: Linting and Style
+
+All TypeScript and shell scripts must pass linting before submission, and changed-file type-checking must pass before merge. Full-project type-checking remains informational while debt is burned down. This repo uses **ESLint** for TypeScript code and **ShellCheck** for shell scripts to enforce consistent code style and catch common errors.
+
+### Running linting locally
+
+Before pushing, ensure your code passes all linting checks:
+
+```bash
+npm install                    # Install dependencies (one-time)
+npm run type-check:changed     # Verify changed-file TypeScript types (PR gate)
+npm run type-check             # Optional: full-project debt snapshot (non-blocking)
+npm run lint                   # Check all TS and shell scripts
+npm run lint:fix               # Auto-fix formatting and common issues
+```
+
+Specific linting commands:
+
+- `npm run lint:ts` — Check only TypeScript files
+- `npm run lint:ts:fix` — Auto-fix TypeScript issues
+- `npm run lint:sh` — Check only shell scripts
+
+### What gets linted
+
+- **TypeScript files:** All `.ts` files in `src/`
+- **Shell scripts:** `run-kaseki.sh`, `kaseki-agent.sh`, `cleanup-kaseki.sh`
+- **Excluded:** `node_modules/`, `.git/`, `docker/`, `dist/` (compiled output), CI artifacts
+
+### Style expectations
+
+See [STYLE.md](STYLE.md) for detailed code style guidelines. In summary:
+
+- **Indentation:** 2 spaces (enforced)
+- **Line endings:** Unix (LF) only
+- **Quotes:** Single quotes, except where escaping is needed
+- **Semicolons:** Required at end of statements
+- **Console usage:** Allowed (not flagged as error; this is a CLI tool)
+- **No trailing whitespace**
+- **Types:** Always explicit in function signatures, no implicit `any`
+
+### PR checklist for code quality
+
+Before opening a pull request:
+
+- [ ] Run `npm run type-check:changed` locally and confirm 0 errors (PR gate).
+- [ ] Optionally run `npm run type-check` (or `npm run type-check:full`) to assess tracked full-project TypeScript debt (non-blocking).
+- [ ] Run `npm run lint` locally and confirm 0 errors.
+- [ ] If linting issues were found, run `npm run lint:fix` and review the changes.
+- [ ] Ensure no unintended auto-fixes were applied (review git diff).
+- [ ] Run `npm run build` to verify compilation succeeds.
+- [ ] If you disagree with a lint rule, discuss in the PR description.
+
+## 5) Running the local containerized flow
+
+Use either the published image or a local build, then run `./run-kaseki.sh` from this repo root.
+
+### Option A: pull published image
+
+```bash
+docker pull docker.io/cyanautomation/kaseki-agent:latest
+OPENROUTER_API_KEY=<your_openrouter_api_key> ./run-kaseki.sh
+```
+
+Use stable version tags such as `0.1.0` for reproducible runs. Reserve `latest`
+for smoke testing a freshly published image before a stable release tag is cut.
+
+### Option B: build locally, then run
+
+```bash
+docker build -t kaseki-template:latest .
+KASEKI_IMAGE=kaseki-template:latest OPENROUTER_API_KEY=<your_openrouter_api_key> ./run-kaseki.sh
+```
+
+Optional: pass a specific instance name (for example `kaseki-7`) as the first arg.
+
+## 6) Release Process and Conventional Commits
+
+Kaseki Agent releases are **automated via semantic-release**. Version bumps, changelog updates, and GitHub Releases are generated automatically from commit messages using the **conventional commits** format.
+
+### Conventional Commit Format
+
+All commits should follow the format:
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+**Types that trigger version bumps:**
+
+- `feat:` — New feature (bumps **minor** version: 0.1.0 → 0.2.0)
+- `fix:` — Bug fix (bumps **patch** version: 0.1.0 → 0.1.1)
+- `perf:` — Performance improvement (bumps **patch** version)
+- `revert:` — Revert a previous commit (bumps **patch** version)
+
+**Types that do NOT trigger version bumps** (included in CHANGELOG as documentation only):
+
+- `docs:` — Documentation changes
+- `style:` — Code style/formatting (no logic changes)
+- `refactor:` — Code refactoring (no behavior changes)
+- `test:` — Test additions/updates
+- `chore:` — Dependency updates, build config, etc.
+
+**Examples:**
+
+```
+feat(api): add retry logic to GitHub App token exchange
+
+Implements exponential backoff for transient network failures.
+
+Fixes #123
+```
+
+```
+fix(docker): resolve cache miss in npm ci layer
+
+The workspace cache key was missing lock hash; rebuilt as sha256($lock).
+```
+
+```
+chore(deps): upgrade semantic-release to v24
+```
+
+### Making a Release
+
+**Workflow Options:**
+
+You can create a release in two ways:
+
+**Option A: Via GitHub Actions (Recommended)**
+
+1. Go to the repository's [Actions](https://github.com/CyanAutomation/kaseki-agent/actions) tab
+2. Select the **Release** workflow from the left sidebar
+3. Click **Run workflow** and choose your options:
+   - **Dry-run (optional)**: Check to preview the release without creating tags/releases
+   - Click **Run workflow**
+4. The workflow will:
+   - Analyze commits since last release
+   - Automatically determine version (major/minor/patch)
+   - Update CHANGELOG.md, package.json, and create GitHub Release
+   - Automatically trigger Docker multi-arch build and publish images
+5. Monitor the workflow progress in the Actions tab
+6. Verify the release in the [Releases](https://github.com/CyanAutomation/kaseki-agent/releases) tab
+
+**Option B: Via Local Command (Advanced)**
+
+1. Ensure your local git is clean: `git status`
+2. **Test locally (recommended):**
+
+   ```bash
+   npm run release:dry
+   ```
+
+3. **Create release:**
+
+   ```bash
+   npm run release
+   ```
+
+4. This requires:
+   - Write access to the repository
+   - Valid `GITHUB_TOKEN` in environment (or git credentials)
+   - Ability to push tags to GitHub
+5. The command will automatically trigger the Docker build workflow on GitHub
+
+Both options use **semantic-release** to automate all versioning and changelog tasks. The GitHub Actions workflow is recommended for team releases to ensure consistency and visibility.
+
+### Commit Message Best Practices
+
+- **Be descriptive:** Include *why* the change was made, not just *what* changed
+- **Use body for details:** If the title is short, explain the impact in the commit body
+- **Reference issues:** Link to related issues with `Fixes #123` or `Relates to #456`
+- **One logical change per commit:** Avoid mixing features with refactoring in a single commit
+- **Squash before merge:** Use PR squash-and-rebase to clean up history if needed, then ensure the final squashed message follows conventional format
+
+### Non-Conventional Commits
+
+If a commit message doesn't follow the format, it will **not trigger a version bump** but will still be included in the CHANGELOG. This allows for organic adoption—your PR reviewers can suggest better commit messages without blocking merges.
+
+Once you're comfortable with the format, encourage your team to adopt it systematically (optional: use `commitlint` + `husky` hooks for enforcement in future phases).
+
+## 7) Validating changed-file allowlist and max diff limits
+
+The container runner enforces quality gates using:
+
+- `KASEKI_CHANGED_FILES_ALLOWLIST`
+- `KASEKI_MAX_DIFF_BYTES`
+
+Contributors must validate that any change to defaults or behavior preserves these constraints:
+
+- Changed files remain within the configured allowlist for the intended task.
+- `git.diff` size remains under the configured max diff bytes.
+- If you intentionally broaden scope, update defaults/documentation and clearly explain operator impact.
+
+A failed allowlist or diff-size check should be treated as a real regression unless intentionally changed and documented.
+
+## 8) Diagnosing failures with `/agents/kaseki-results/kaseki-N`
+
+When a run fails, inspect artifacts in this order:
+
+1. `kaseki-report /agents/kaseki-results/kaseki-N` for a compact status, failed command, exit-code, model, timing, changed-file, and next-diagnostic summary.
+2. `result-summary.md` for top-level status, failed command, and changed files.
+3. `metadata.json` for exit codes (`pi`, validation, quality, secret scan), model details, and timing.
+4. `stdout.log` / `stderr.log` for execution flow and shell-level failures.
+5. `pi-summary.json` and `pi-events.jsonl` for agent/model behavior.
+6. `validation.log` and `validation-timings.tsv` for command failures and duration outliers.
+7. `quality.log`, `changed-files.txt`, and `git.diff` for allowlist/diff-limit failures.
+8. `secret-scan.log` for credential-detection issues.
+9. `host-start.json`, `host_docker_exit_code`, and `resource.time` for host/container startup context.
+
+Tip: If quality or validation failures are ambiguous, compare `git.status` + `git.diff` with `TASK_PROMPT` constraints first.
+
+## PR checklist
+
+Before opening/merging, include:
+
+- [ ] Prompt rationale for any `TASK_PROMPT` default or guardrail change.
+- [ ] Test evidence (commands + output summary), including focused Vitest updates when behavior changed.
+- [ ] Confirmation that changed-file allowlist and max diff checks still pass (or documented rationale for updates).
+- [ ] Any operator-impacting env var, default, or runbook/documentation updates.

package/Dockerfile

@@ -0,0 +1,217 @@
+# Bump the pinned Node base image monthly with a security review.
+# Node v24 base image: Updated May 2026 for improved performance and security.
+# Using ARG for DRY principle - base image used in both stages
+ARG NODE_IMAGE=node:24-bookworm-slim
+
+FROM ${NODE_IMAGE} AS deps
+
+# Phase 1: System dependencies + user setup (consolidated)
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends bash ca-certificates git procps \
+    && rm -rf /var/lib/apt/lists/* \
+    && groupadd --system --gid 10001 kaseki \
+    && useradd --system --uid 10001 --gid kaseki --create-home --home-dir /home/kaseki --shell /usr/sbin/nologin kaseki \
+    && mkdir -p /workspace /results /tmp/kaseki-home /tmp/npm-cache /tmp/pi-agent \
+    && chown -R kaseki:kaseki /workspace /results /tmp/kaseki-home /tmp/npm-cache /tmp/pi-agent
+
+ENV HOME=/tmp/kaseki-home \
+    NPM_CONFIG_CACHE=/tmp/npm-cache \
+    npm_config_cache=/tmp/npm-cache \
+    PI_CODING_AGENT_DIR=/tmp/pi-agent \
+    PI_TELEMETRY=0 \
+    PI_SKIP_VERSION_CHECK=1 \
+    CI=true
+
+# Phase 2: Workspace cache seed for Layer 3 runtime fallback
+WORKDIR /opt/kaseki/workspace-cache-seed
+COPY docker/workspace-cache/package.json docker/workspace-cache/package-lock.json ./
+RUN npm ci --no-audit --prefer-offline --ignore-scripts \
+    && mkdir -p node_modules
+
+# Phase 3: Global Pi CLI installation (Layer 3 fallback for image seed cache)
+RUN npm install -g --no-audit @earendil-works/pi-coding-agent@0.74.0
+
+
+FROM ${NODE_IMAGE} AS runtime
+
+# System dependencies + user setup (consolidated)
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends bash ca-certificates curl docker.io git procps \
+    && rm -rf /var/lib/apt/lists/* \
+    && groupadd --system --gid 10001 kaseki \
+    && useradd --system --uid 10001 --gid kaseki --create-home --home-dir /home/kaseki --shell /usr/sbin/nologin kaseki \
+    && mkdir -p /workspace /results /tmp/kaseki-home /tmp/npm-cache /tmp/pi-agent /opt/kaseki/workspace-cache/default \
+    && chown -R kaseki:kaseki /workspace /results /tmp/kaseki-home /tmp/npm-cache /tmp/pi-agent /opt/kaseki
+
+ENV HOME=/tmp/kaseki-home \
+    NPM_CONFIG_CACHE=/tmp/npm-cache \
+    npm_config_cache=/tmp/npm-cache \
+    PI_CODING_AGENT_DIR=/tmp/pi-agent \
+    PI_TELEMETRY=0 \
+    PI_SKIP_VERSION_CHECK=1 \
+    CI=true
+
+# Copy Pi CLI and workspace cache seed from deps stage
+COPY --from=deps /usr/local/lib/node_modules /usr/local/lib/node_modules
+RUN ln -sf ../lib/node_modules/@earendil-works/pi-coding-agent/dist/cli.js /usr/local/bin/pi
+COPY --from=deps /opt/kaseki/workspace-cache-seed/node_modules /opt/kaseki/workspace-cache/default/node_modules
+
+# Build kaseki application (cache-optimal: dependencies first, then source code)
+WORKDIR /app
+COPY package.json package-lock.json tsconfig.json ./
+COPY src ./src
+RUN npm ci --no-audit --prefer-offline --ignore-scripts && npm run build
+RUN test -f /app/dist/kaseki-api-service.js
+
+# Copy all application files (after build, so layer invalidation is minimal)
+COPY Dockerfile .dockerignore README.md CLAUDE.md CONTRIBUTING.md STYLE.md ./
+COPY kaseki run-kaseki.sh kaseki-agent.sh ./
+COPY docs ./docs
+COPY ops ./ops
+COPY scripts ./scripts
+COPY docker ./docker
+COPY test ./test
+
+# Copy entrypoints to /usr/local/bin
+COPY kaseki-agent.sh /usr/local/bin/kaseki-agent
+COPY scripts/docker-entrypoint.sh /usr/local/bin/kaseki-entrypoint
+
+# Setup and install binaries (consolidated: container scripts, lib copies, permissions, and global installs)
+RUN chmod +x \
+      /app/scripts/kaseki-container-setup.sh \
+      /app/scripts/kaseki-container-setup-remote.sh \
+      /app/scripts/kaseki-container-entrypoint-wrapper.sh \
+      /app/kaseki /app/run-kaseki.sh /app/kaseki-agent.sh \
+    && mkdir -p /scripts \
+    && ln -sf /app/scripts/kaseki-container-setup.sh /scripts/kaseki-container-setup.sh \
+    && ln -sf /app/scripts/kaseki-container-setup-remote.sh /scripts/kaseki-container-setup-remote.sh \
+    && ln -sf /app/scripts/kaseki-container-entrypoint-wrapper.sh /scripts/kaseki-container-entrypoint-wrapper.sh \
+    && mkdir -p /app/lib \
+    && cp dist/pi-event-filter.js /app/lib/pi-event-filter.js \
+    && cp dist/event-aggregator.js /app/lib/event-aggregator.js \
+    && cp dist/timestamp-tracker.js /app/lib/timestamp-tracker.js \
+    && cp dist/pi-progress-stream.js /app/lib/pi-progress-stream.js \
+    && cp dist/progress-stream-utils.js /app/lib/progress-stream-utils.js \
+    && cp dist/kaseki-report.js /app/lib/kaseki-report.js \
+    && cp dist/instance-state-derivation.js /app/lib/instance-state-derivation.js \
+    && cp dist/instance-metadata-reader.js /app/lib/instance-metadata-reader.js \
+    && cp dist/kaseki-cli.js /app/kaseki-cli.js \
+    && cp dist/kaseki-cli-lib.js /app/kaseki-cli-lib.js \
+    && cp dist/github-app-token.js /app/lib/github-app-token.js \
+    && chmod 0755 /app/dist/*.js \
+    && install -m 0755 /app/lib/pi-event-filter.js /usr/local/bin/kaseki-pi-event-filter \
+    && install -m 0755 /app/lib/pi-progress-stream.js /usr/local/bin/kaseki-pi-progress-stream \
+    && install -m 0755 /app/lib/event-aggregator.js /usr/local/bin/event-aggregator.js \
+    && install -m 0755 /app/lib/timestamp-tracker.js /usr/local/bin/timestamp-tracker.js \
+    && install -m 0755 /app/lib/progress-stream-utils.js /usr/local/bin/progress-stream-utils.js \
+    && install -m 0755 /app/lib/instance-state-derivation.js /usr/local/bin/instance-state-derivation.js \
+    && install -m 0755 /app/lib/instance-metadata-reader.js /usr/local/bin/instance-metadata-reader.js \
+    && install -m 0755 /app/lib/kaseki-report.js /usr/local/bin/kaseki-report \
+    && install -m 0755 /app/lib/github-app-token.js /usr/local/bin/github-app-token \
+    && ln -sf github-app-token /usr/local/bin/github-app-token.js \
+    && chmod 0755 \
+      /usr/local/bin/kaseki-entrypoint \
+      /usr/local/bin/kaseki-pi-event-filter \
+      /usr/local/bin/kaseki-pi-progress-stream \
+      /usr/local/bin/kaseki-report \
+      /usr/local/bin/github-app-token \
+      /usr/local/bin/github-app-token.js \
+      /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/dist/cli.js \
+      /app/scripts/*.sh
+
+WORKDIR /workspace
+USER kaseki
+ENTRYPOINT ["/usr/local/bin/kaseki-entrypoint"]
+CMD ["agent"]
+
+# The runner initializes these logs before long-running work starts.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD test -f /results/stdout.log && test -f /results/stderr.log
+
+
+# ===== FINAL STAGE: Artifact-Stripped Production Image =====
+# This stage removes build-time artifacts (test/, docs/, src/) and devDependencies,
+# reducing image size by ~80-150 MB while preserving all runtime functionality.
+# Trade-off: Cannot rebuild code in container (not needed—build happens in CI before image creation).
+#
+# Impact:
+#   - Size: 15–25% reduction (80 MB prune + 50 MB docs/test/src)
+#   - Build time: negligible (final stage only copies needed files)
+#   - Runtime: unaffected (all runtime binaries, scripts, and dependencies included)
+#
+FROM ${NODE_IMAGE} AS final
+
+# Minimal setup: only runtime requirements (no build tools or package managers beyond npm for app startup check)
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends bash ca-certificates curl docker.io git procps \
+    && rm -rf /var/lib/apt/lists/* \
+    && groupadd --system --gid 10001 kaseki \
+    && useradd --system --uid 10001 --gid kaseki --create-home --home-dir /home/kaseki --shell /usr/sbin/nologin kaseki \
+    && mkdir -p /workspace /results /tmp/kaseki-home /tmp/npm-cache /tmp/pi-agent /opt/kaseki/workspace-cache/default \
+    && chown -R kaseki:kaseki /workspace /results /tmp/kaseki-home /tmp/npm-cache /tmp/pi-agent /opt/kaseki
+
+ENV HOME=/tmp/kaseki-home \
+    NPM_CONFIG_CACHE=/tmp/npm-cache \
+    npm_config_cache=/tmp/npm-cache \
+    PI_CODING_AGENT_DIR=/tmp/pi-agent \
+    PI_TELEMETRY=0 \
+    PI_SKIP_VERSION_CHECK=1 \
+    CI=true
+
+# Copy runtime essentials from runtime stage (skip test/, docs/, src/)
+COPY --from=runtime /usr/local/lib/node_modules /usr/local/lib/node_modules
+COPY --from=runtime /usr/local/bin/pi /usr/local/bin/pi
+COPY --from=runtime /opt/kaseki/workspace-cache/default/node_modules /opt/kaseki/workspace-cache/default/node_modules
+
+# Copy application files (excluding build artifacts)
+WORKDIR /app
+COPY --from=runtime /app/package.json /app/package-lock.json /app/
+COPY --from=runtime /app/Dockerfile /app/.dockerignore /app/README.md /app/CLAUDE.md /app/CONTRIBUTING.md /app/STYLE.md ./
+COPY --from=runtime /app/kaseki /app/run-kaseki.sh /app/kaseki-agent.sh ./
+COPY --from=runtime /app/ops ./ops
+COPY --from=runtime /app/scripts ./scripts
+COPY --from=runtime /app/docker ./docker
+COPY --from=runtime /app/dist ./dist
+COPY --from=runtime /app/lib ./lib
+COPY --from=runtime /app/node_modules ./node_modules
+
+# Copy only production dependencies (remove devDependencies)
+# Note: This only affects kaseki-agent's own dependencies; Pi CLI and workspace cache remain untouched.
+RUN npm prune --production
+
+# Install global binaries and set up scripts (from runtime stage)
+RUN mkdir -p /scripts \
+    && ln -sf /app/scripts/kaseki-container-setup.sh /scripts/kaseki-container-setup.sh \
+    && ln -sf /app/scripts/kaseki-container-setup-remote.sh /scripts/kaseki-container-setup-remote.sh \
+    && ln -sf /app/scripts/kaseki-container-entrypoint-wrapper.sh /scripts/kaseki-container-entrypoint-wrapper.sh \
+    && install -m 0755 /app/lib/pi-event-filter.js /usr/local/bin/kaseki-pi-event-filter \
+    && install -m 0755 /app/lib/pi-progress-stream.js /usr/local/bin/kaseki-pi-progress-stream \
+    && install -m 0755 /app/lib/event-aggregator.js /usr/local/bin/event-aggregator.js \
+    && install -m 0755 /app/lib/timestamp-tracker.js /usr/local/bin/timestamp-tracker.js \
+    && install -m 0755 /app/lib/progress-stream-utils.js /usr/local/bin/progress-stream-utils.js \
+    && install -m 0755 /app/lib/instance-state-derivation.js /usr/local/bin/instance-state-derivation.js \
+    && install -m 0755 /app/lib/instance-metadata-reader.js /usr/local/bin/instance-metadata-reader.js \
+    && install -m 0755 /app/lib/kaseki-report.js /usr/local/bin/kaseki-report \
+    && install -m 0755 /app/lib/github-app-token.js /usr/local/bin/github-app-token \
+    && ln -sf github-app-token /usr/local/bin/github-app-token.js \
+    && install -m 0755 /app/kaseki-agent.sh /usr/local/bin/kaseki-agent \
+    && install -m 0755 /app/scripts/docker-entrypoint.sh /usr/local/bin/kaseki-entrypoint \
+    && chmod 0755 \
+      /usr/local/bin/kaseki-entrypoint \
+      /usr/local/bin/kaseki-pi-event-filter \
+      /usr/local/bin/kaseki-pi-progress-stream \
+      /usr/local/bin/kaseki-report \
+      /usr/local/bin/github-app-token \
+      /usr/local/bin/github-app-token.js \
+      /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/dist/cli.js \
+      /app/kaseki /app/run-kaseki.sh /app/kaseki-agent.sh \
+      /app/scripts/*.sh
+
+WORKDIR /workspace
+USER kaseki
+ENTRYPOINT ["/usr/local/bin/kaseki-entrypoint"]
+CMD ["agent"]
+
+# The runner initializes these logs before long-running work starts.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD test -f /results/stdout.log && test -f /results/stderr.log