feat: add release gates and pty preflight

Author: MackDing

.env.example

@@ -1,4 +1,6 @@
 BOT_TOKEN=123456789:telegram-token-from-botfather
+TELEGRAM_EXPECTED_USERNAME=
+TELEGRAM_SMOKE_CHAT_ID=
 ALLOWED_USER_IDS=123456789,987654321
 PROACTIVE_USER_IDS=123456789
 STATE_FILE=.codex-telegram-claws-state.json

.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    env:
+      BOT_TOKEN: "ci-bot-token"
+      ALLOWED_USER_IDS: "1"
+      CODEX_COMMAND: "node"
+      CODEX_WORKDIR: "."
+      WORKSPACE_ROOT: "."
+      GITHUB_DEFAULT_WORKDIR: "."
+      STATE_FILE: ".codex-telegram-claws-state.json"
+      MCP_SERVERS: "[]"
+      SHELL_ENABLED: "false"
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - run: npm ci
+      - run: npm run check
+      - run: npm run lint
+      - run: npm run format:check
+      - run: npm test
+      - run: npm run healthcheck

.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      BOT_TOKEN: "ci-bot-token"
+      ALLOWED_USER_IDS: "1"
+      CODEX_COMMAND: "node"
+      CODEX_WORKDIR: "."
+      WORKSPACE_ROOT: "."
+      GITHUB_DEFAULT_WORKDIR: "."
+      STATE_FILE: ".codex-telegram-claws-state.json"
+      MCP_SERVERS: "[]"
+      SHELL_ENABLED: "false"
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+      - run: npm run ci
+
+      - name: Publish GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

.github/workflows/telegram-smoke.yml

@@ -0,0 +1,25 @@
+name: Telegram Smoke
+
+on:
+  workflow_dispatch:
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    if: ${{ secrets.TELEGRAM_BOT_TOKEN != '' }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      - name: Telegram getMe smoke check
+        env:
+          BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
+          TELEGRAM_EXPECTED_USERNAME: ${{ secrets.TELEGRAM_EXPECTED_USERNAME }}
+          TELEGRAM_SMOKE_CHAT_ID: ${{ secrets.TELEGRAM_SMOKE_CHAT_ID }}
+        run: npm run telegram:smoke

.prettierignore

@@ -0,0 +1,4 @@
+node_modules/
+.git/
+.env
+.codex-telegram-claws-state.json

.prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "none",
+  "arrowParens": "always"
+}

AGENTS.md

@@ -1,39 +1,54 @@
 # Repository Guidelines
 
-## Project Structure & Module Organization
-This repository is currently minimal and does not yet include application code, tests, or build tooling. Until a concrete stack is added, keep contributions organized with a predictable layout:
+## Repo Structure
 
-- `src/` for production code
-- `tests/` for automated tests
-- `assets/` for static files such as images or fixtures
-- `docs/` for design notes or operational guides
+- `src/index.js`: application entrypoint and subsystem wiring.
+- `src/bot/`: Telegram handlers, formatting, command parsing, i18n, middleware.
+- `src/orchestrator/`: routing, MCP client, skill registry, GitHub/MCP skills.
+- `src/runner/`: Codex PTY/exec management and restricted shell execution.
+- `src/cron/`: scheduled proactive jobs.
+- `tests/`: Node built-in test suite, one `*.test.js` file per module area.
 
-Keep modules small and grouped by feature. For example, place Telegram client code in `src/telegram/` and matching tests in `tests/telegram/`.
+## Start And Dev Commands
 
-## Build, Test, and Development Commands
-No project-specific commands are defined yet. When adding tooling, expose a minimal, documented set of commands such as:
+- `npm install`: install dependencies.
+- `npm run start`: start the Telegram bot with the current `.env`.
+- `npm run dev`: run the bot in watch mode for local development.
 
-- `npm install` or equivalent to install dependencies
-- `npm test` to run the full test suite
-- `npm run lint` to enforce style rules
-- `npm run dev` to start local development
+## Test Commands
 
-If you introduce a different stack, update this file in the same change so contributors have one reliable entry point.
+- `npm test`: run the full unit test suite with `node --test`.
+- `npm run check`: run a syntax check on the entrypoint and fail fast on invalid JS.
+- `npm run healthcheck`: run the local runtime health check.
 
-## Coding Style & Naming Conventions
-Use 4 spaces for indentation in Markdown, YAML, and Python-style formats; follow the formatter defaults for any language-specific toolchain you add. Prefer descriptive, lowercase directory names (`src/bot/`), `snake_case` for Python files, and `kebab-case` or framework-standard naming for frontend assets.
+## Lint And Format
 
-Add formatting and linting early and run them before opening a PR. Keep files ASCII unless the file already requires Unicode.
+- `npm run lint`: run ESLint over source, tests, scripts, and local JS/CJS config files.
+- `npm run lint:fix`: apply safe ESLint fixes.
+- `npm run format`: run Prettier across the repository.
+- `npm run format:check`: verify formatting without writing changes.
+- Do not submit formatting-only churn or rewrap unrelated files.
 
-## Testing Guidelines
-Place tests under `tests/` and mirror the source layout. Name test files after the unit under test, such as `tests/telegram/test_dispatcher.py` or `dispatcher.test.ts`. Cover new behavior and important edge cases; avoid merging untested logic.
+## Files And Paths You Must Not Change
 
-Document the exact test command in the project README and here once the framework is chosen.
+- Do not edit `.git/` or `node_modules/`.
+- Do not commit or rewrite `.env`, secrets, Telegram tokens, or local session artifacts.
+- Do not manually edit `.codex-telegram-claws-state.json`; it is runtime state.
+- Avoid changing files outside this repository root, even when `/repo` or shell features reference other workspaces.
 
-## Commit & Pull Request Guidelines
-There is no Git history in the current workspace, so no established commit pattern can be inferred. Use short, imperative commit messages and prefer Conventional Commit prefixes where helpful, such as `feat: add webhook handler` or `fix: guard empty update payload`.
+## Contribution Rules
 
-Pull requests should include a clear summary, testing notes, and linked issue references when applicable. Include screenshots or sample bot interactions for user-facing changes.
+- Use ES Modules and keep new files under the existing feature-oriented layout.
+- Keep user-facing bot copy in English by default. Localized strings must go through `src/bot/i18n.js`.
+- Prefer focused changes. Do not mix feature work with unrelated refactors.
+- Add or update tests for behavior changes in `tests/`.
 
-## Configuration & Secrets
-Do not commit API tokens, session files, or `.env` values. Keep local configuration in ignored files and document required environment variables in `README.md`.
+## Required Verification Before Commit
+
+- Run `npm run check`.
+- Run `npm run lint`.
+- Run `npm run format:check`.
+- Run `npm test`.
+- Run `npm run healthcheck`.
+- Review `git diff --stat` and `git status --short` for accidental edits.
+- If bot commands or behavior changed, update `README.md` and include a Telegram usage example in the PR or commit notes.

README.md

@@ -73,13 +73,30 @@ Development mode:
 npm run dev
 ```
 
-Sanity check:
+Validation:
 
 ```bash
 npm run check
+npm run lint
+npm run format:check
 npm test
+npm run healthcheck
 ```
 
+## Development Commands
+
+- `npm run start` - start the bot
+- `npm run dev` - watch mode for local development
+- `npm run check` - syntax validation
+- `npm run lint` - ESLint for source, tests, scripts, and local JS/CJS config files
+- `npm run lint:fix` - apply safe lint fixes
+- `npm run format` - format repository files with Prettier
+- `npm run format:check` - verify formatting
+- `npm test` - run the full test suite
+- `npm run healthcheck` - static runtime readiness check
+- `npm run healthcheck:strict` - stricter production-oriented health check
+- `npm run telegram:smoke` - live Telegram API smoke test when a real bot token is available
+
 ## Architecture
 
 ```text
@@ -114,6 +131,31 @@ This prevents:
 - extra latency/token/tool cost
 - context drift from two independent MCP execution surfaces
 
+## Subagents
+
+In this repository, "subagent" means a dedicated skill executor behind the router, not a second free-form Codex session.
+
+Current subagents:
+
+- `github` skill - local git actions, repo creation through GitHub API, and test job tracking
+- `mcp` skill - explicit MCP server inspection, enable/disable, tool listing, and tool calls
+
+How they are triggered:
+
+- Explicit commands always go straight to the matching subagent:
+  - `/gh ...` -> GitHub skill
+  - `/mcp ...` -> MCP skill
+- Plain text may also route to a subagent when the router sees a supported GitHub-style request such as `git push`, `commit`, or `run test`
+- Everything else falls back to Codex CLI
+
+Where this happens:
+
+- Router decision order: [router.js](/Users/ding/Documents/Code/Github/codex-telegram-claws/src/orchestrator/router.js)
+- Skill toggles per chat: [skillRegistry.js](/Users/ding/Documents/Code/Github/codex-telegram-claws/src/orchestrator/skillRegistry.js)
+- Telegram command entrypoints: [handlers.js](/Users/ding/Documents/Code/Github/codex-telegram-claws/src/bot/handlers.js)
+
+Operationally, subagents are the bot's control plane. Codex remains the coding execution plane.
+
 ## Commands
 
 General:
@@ -192,6 +234,7 @@ PTY output is streamed with throttled `editMessageText` updates.
   - quote block (if `REASONING_RENDER_MODE=quote`)
 - If `node-pty` cannot spawn on the current host, the runner falls back to `codex exec` for per-request execution
 - In `codex exec` fallback mode, Telegram output is cleaned to hide the Codex banner, raw tool trace, `mcp startup`, and duplicate `tokens used` footer
+- On macOS, startup now auto-repairs `node-pty` helper execute permissions before the first PTY session
 
 ## Project-Scoped Conversation State
 
@@ -262,6 +305,33 @@ GITHUB_DEFAULT_BRANCH=main
 E2E_TEST_COMMAND=npx playwright test --reporter=line
 ```
 
+## CI And Release Automation
+
+GitHub Actions now includes:
+
+- `CI` workflow on push and pull request
+- `Telegram Smoke` manual workflow for live bot-token validation when repository secrets are configured
+- `Release` workflow on `v*` tags, which reruns validation and publishes a GitHub Release
+
+Repository secrets for live smoke checks:
+
+- `TELEGRAM_BOT_TOKEN`
+- `TELEGRAM_EXPECTED_USERNAME` (optional)
+- `TELEGRAM_SMOKE_CHAT_ID` (optional)
+
+Recommended local release gate:
+
+```bash
+npm run ci
+node scripts/healthcheck.js --strict --telegram-live
+```
+
+Release references:
+
+- [operations.md](/Users/ding/Documents/Code/Github/codex-telegram-claws/docs/operations.md)
+- [release.md](/Users/ding/Documents/Code/Github/codex-telegram-claws/docs/release.md)
+- [ecosystem.config.cjs](/Users/ding/Documents/Code/Github/codex-telegram-claws/ecosystem.config.cjs)
+
 ## Security Baseline
 
 - Whitelist-only access (`ALLOWED_USER_IDS`) is mandatory
@@ -275,6 +345,21 @@ E2E_TEST_COMMAND=npx playwright test --reporter=line
 - If you allow write commands, mark high-risk prefixes in `SHELL_DANGEROUS_COMMANDS` and require `/sh --confirm ...`
 - Prefer least-privilege GitHub PAT
 
+## Operations
+
+The recommended production supervisor is PM2.
+
+Basic flow:
+
+```bash
+pm2 start ecosystem.config.cjs
+pm2 status codex-telegram-claws
+pm2 logs codex-telegram-claws
+pm2 restart codex-telegram-claws
+```
+
+Run exactly one polling process per bot token.
+
 ## Should You Enable `/sh`?
 
 Usually not for general users. Codex itself can run commands as part of a coding task, so `/sh` is not required for normal code-edit workflows.
@@ -305,7 +390,7 @@ Telegram can manage runtime usage of Bot-side MCP and skills, but not install ar
 - **MCP failures**: run `/mcp tools <server>` first to validate server availability
 - **GitHub API failures**: verify `GITHUB_TOKEN` scope (`repo`) and account permissions
 - **Duplicate MCP suspicion**: ensure coding tasks are routed directly to Codex, and bot MCP is used only for `/mcp`
-- **`posix_spawnp failed`**: this means PTY spawn is blocked on the host; the runner will fall back to `codex exec`
+- **`posix_spawnp failed`**: this usually means the `node-pty` helper lost execute permissions; startup now auto-repairs it, and `npm run healthcheck` reports the result
 
 ## Reference
 

docs/operations.md

@@ -0,0 +1,59 @@
+# Operations Guide
+
+## Process Supervision
+
+The recommended production supervisor is PM2. This bot uses Telegram long polling, so run exactly one instance per bot token.
+
+Start:
+
+```bash
+npm install
+cp .env.example .env
+pm2 start ecosystem.config.cjs
+```
+
+Common PM2 commands:
+
+```bash
+pm2 status codex-telegram-claws
+pm2 logs codex-telegram-claws
+pm2 restart codex-telegram-claws
+pm2 stop codex-telegram-claws
+pm2 save
+```
+
+## Health Checks
+
+Static health check:
+
+```bash
+npm run healthcheck
+```
+
+Strict health check:
+
+```bash
+npm run healthcheck:strict
+```
+
+Optional Telegram live check:
+
+```bash
+node scripts/healthcheck.js --strict --telegram-live
+```
+
+What the health check validates:
+
+- workspace and runner directories exist
+- the state file directory is writable
+- the configured Codex command can be resolved
+- `node-pty` helper permissions are valid
+- optional live Telegram API authentication
+
+## Deployment Notes
+
+- Keep exactly one polling process per bot token.
+- Run the bot under a restricted system user.
+- Keep `.env` outside version control.
+- Rotate Telegram and GitHub tokens if they are ever exposed.
+- If you reinstall dependencies on macOS, rerun `npm run healthcheck`; the bot now auto-repairs `node-pty` helper permissions on startup.