dw-kit 1.7.0-rc.1 → 1.8.0-rc.1

package/.claude/hooks/pre-commit-gate.sh

@@ -96,27 +96,25 @@ fi
 # v1.6 (ADR-0009 R2-2): Agent OS post-hoc check.
 # When ≥1 active claim exists, verify staged files fall within an active claim's write_scope.
 # Cooperative protocol — warn only (cannot prevent non-compliant agents).
-if [ -f "$DW_BIN" ] && command -v node >/dev/null 2>&1 && [ -n "$STAGED_FILES" ]; then
+#
+# Issue #13 Bug 3 fix: previous version inlined `node -e` importing
+# `$CLAUDE_PROJECT_DIR/src/lib/agent-claim.mjs` — that path is cwd-relative and
+# only exists in dw-kit's own repo, NOT in consumer projects. The block was
+# silently no-op everywhere else. Replaced by `dw agent check-staged --stdin`
+# which uses the installed binary. Prefer global `dw` on PATH; fall back to
+# `node $DW_BIN` for in-repo local development (where DW_BIN points at the
+# source bin script).
+if [ -n "$STAGED_FILES" ]; then
   CLAIMS_DIR="$CLAUDE_PROJECT_DIR/.dw/cache/agents/claims"
   if [ -d "$CLAIMS_DIR" ] && ls "$CLAIMS_DIR"/*.json >/dev/null 2>&1; then
-    OUT_OF_SCOPE=$(STAGED="$STAGED_FILES" node -e "
-      const fs = require('fs');
-      const path = require('path');
-      (async () => {
-        const { listClaims } = await import('$CLAUDE_PROJECT_DIR/src/lib/agent-claim.mjs');
-        const { pathMatchesScope } = await import('$CLAUDE_PROJECT_DIR/src/lib/agent-conflict.mjs');
-        const claims = listClaims(process.env.CLAUDE_PROJECT_DIR || '$CLAUDE_PROJECT_DIR').filter(c => c._live_status === 'created' || c._live_status === 'active');
-        if (claims.length === 0) return;
-        const allScopes = claims.flatMap(c => c.write_scope);
-        const staged = (process.env.STAGED || '').split(/\r?\n/).filter(Boolean);
-        const outside = staged.filter(f => !pathMatchesScope(f, allScopes));
-        if (outside.length > 0) {
-          console.log('Files NOT in any active claim write_scope:');
-          for (const f of outside.slice(0, 10)) console.log('  ' + f);
-          if (outside.length > 10) console.log('  ... +' + (outside.length - 10) + ' more');
-        }
-      })().catch(e => { /* fail-graceful */ });
-    " 2>/dev/null || true)
+    if command -v dw >/dev/null 2>&1; then
+      OUT_OF_SCOPE=$(echo "$STAGED_FILES" | dw agent check-staged --stdin 2>/dev/null || true)
+    elif [ -f "$DW_BIN" ] && command -v node >/dev/null 2>&1; then
+      # Local dev fallback: in-repo dw-kit work where global `dw` not on PATH
+      OUT_OF_SCOPE=$(echo "$STAGED_FILES" | node "$DW_BIN" agent check-staged --stdin 2>/dev/null || true)
+    else
+      OUT_OF_SCOPE=""
+    fi
     if [ -n "$OUT_OF_SCOPE" ]; then
       echo "⚠️  Agent OS (ADR-0009 R2-2): post-hoc claim check" >&2
       echo "$OUT_OF_SCOPE" >&2

package/.claude/templates/agent-report.md

@@ -1,35 +1,35 @@
----
-date: [ISO timestamp — e.g. 2026-04-02T14:30:00]
-from: [agent-role — researcher | planner | developer | reviewer | debugger]
-to: [agent-role — planner | developer | user]
-task: [task-name]
-status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
----
-
-## Summary
-
-[1-3 câu tóm tắt kết quả / findings]
-
-## Details
-
-[Chi tiết findings, decisions, hoặc implementation notes]
-
-## Concerns (nếu DONE_WITH_CONCERNS)
-
-- [Concern 1]
-- [Concern 2]
-
-## Blockers (nếu BLOCKED)
-
-- **Blocker**: [Mô tả vấn đề]
-- **Owner**: [Ai cần resolve]
-- **Unblock by**: [Action cần làm]
-
-## Needs (nếu NEEDS_CONTEXT)
-
-- [ ] [Thông tin cần thêm]
-- [ ] [Quyết định cần từ user/TL]
-
-## Next Steps
-
-- [Bước tiếp theo đề xuất]
+---
+date: [ISO timestamp — e.g. 2026-04-02T14:30:00]
+from: [agent-role — researcher | planner | developer | reviewer | debugger]
+to: [agent-role — planner | developer | user]
+task: [task-name]
+status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+---
+
+## Summary
+
+[1-3 câu tóm tắt kết quả / findings]
+
+## Details
+
+[Chi tiết findings, decisions, hoặc implementation notes]
+
+## Concerns (nếu DONE_WITH_CONCERNS)
+
+- [Concern 1]
+- [Concern 2]
+
+## Blockers (nếu BLOCKED)
+
+- **Blocker**: [Mô tả vấn đề]
+- **Owner**: [Ai cần resolve]
+- **Unblock by**: [Action cần làm]
+
+## Needs (nếu NEEDS_CONTEXT)
+
+- [ ] [Thông tin cần thêm]
+- [ ] [Quyết định cần từ user/TL]
+
+## Next Steps
+
+- [Bước tiếp theo đề xuất]

package/.dw/config/agents.yml

@@ -0,0 +1,54 @@
+# ============================================================================
+# dw-kit Agent Runtime Config — v1
+# Reference: docs/dw_remote_agent_first_context_strategy.md §8 Priority 3
+# ============================================================================
+# Used by `dw session start --agent <name>`. Each agent is a thin descriptor
+# of an EXTERNAL CLI coding agent dw-kit orchestrates (Claude Code, Codex,
+# Gemini, etc.). dw-kit does NOT bundle these agents — they must be installed
+# separately. Per research §14: "Do not replace ... Orchestrate them."
+# ----------------------------------------------------------------------------
+
+schema_version: agents@v1
+
+agents:
+  # Anthropic Claude Code — non-interactive print mode.
+  # Install: https://docs.claude.com/en/docs/claude-code
+  # F-18 (Win32): goal_mode=stdin so the prompt goes via the child's stdin
+  # instead of an arg. Win32 PATHEXT resolution requires shell:true for
+  # .cmd shims (claude.cmd), and shell:true + args[] (Node DEP0190) is unsafe
+  # for multi-line / quoted prompts — stdin keeps user content out of the
+  # shell command line entirely.
+  claude:
+    command: claude
+    args: ["--print"]
+    goal_mode: stdin
+    env: {}
+    description: "Claude Code (Anthropic) — non-interactive print mode"
+
+  # OpenAI Codex CLI — non-interactive exec mode.
+  # Install: npm install -g @openai/codex
+  codex:
+    command: codex
+    args: ["exec"]
+    goal_mode: stdin
+    env: {}
+    description: "Codex CLI (OpenAI) — non-interactive exec mode"
+
+  # Google Gemini CLI — placeholder shape; adjust args once installed.
+  # Install: see Gemini CLI docs (subject to change).
+  gemini:
+    command: gemini
+    args: ["chat", "--once"]
+    goal_mode: stdin
+    env: {}
+    description: "Gemini CLI (Google) — single-prompt mode [placeholder]"
+
+  # Hermetic test agent used by smoke-test. Echoes the goal then exits 0.
+  # NOT for real use — kept here so tests can `dw session start --agent _smoke_echo`
+  # without depending on any external binary.
+  _smoke_echo:
+    command: node
+    args: ["-e", "process.stdout.write(`SMOKE_ECHO_GOAL: ${process.argv[1] || ''}\\n`); setTimeout(() => process.exit(0), 50);"]
+    goal_mode: trailing-arg
+    env: {}
+    description: "Internal smoke-test echo agent (do not use for real work)"

package/.dw/config/connectors.local.yml

@@ -0,0 +1,8 @@
+# .dw/config/connectors.local.yml — GITIGNORED. Secrets live here.
+# Created/updated by `dw connector telegram setup`.
+# Token + allow-list overrides the template in .dw/config/connectors.yml.
+telegram:
+  enabled: true
+  bot_token: 8693679403:AAG9FrgUd5Ig9eDTAWnA9RqhbMnShRi3Si0
+  allowed_user_ids:
+    - 6603235862

package/.dw/config/connectors.yml

@@ -0,0 +1,64 @@
+# ============================================================================
+# dw-kit Connectors Config — v1
+# Reference: docs/connector-telegram.md
+# Goal: G-rgoal-realtime-orch phase 2 (chat platform adapters)
+# ============================================================================
+# Connectors bridge external chat platforms (Telegram, Zalo, Slack later) to
+# the local dw session runtime. The chat side speaks "/status", "/sessions",
+# "/start <agent> <goal>", "/logs <id>" etc.; the connector translates and
+# calls the same session-store API as `dw session *`.
+#
+# SECRETS (bot tokens) should NEVER be committed. Prefer environment vars:
+#   DW_TG_BOT_TOKEN=...        for Telegram
+# This file holds policy (enabled, allow-list) and non-secret defaults.
+# ----------------------------------------------------------------------------
+
+schema_version: connectors@v1
+
+telegram:
+  enabled: false                  # Safe default. Enable in connectors.local.yml (gitignored).
+  bot_token: ""                   # leave empty; pass via DW_TG_BOT_TOKEN env
+  allowed_user_ids: []            # numeric Telegram user IDs. Empty = bot rejects all. Maintainer keeps their own id in a local-only override (NOT committed — `.dw/config/` ships to npm).
+  default_workspace: ""           # empty = use cwd at start time
+  default_agent: claude           # used by /start when agent name omitted
+  long_poll_timeout_sec: 25       # Telegram supports up to 50; lower if network is flaky
+
+# Voice channel (Phase 4 substrate of G-rgoal-realtime-orch).
+# `dw voice` boots a localhost HTTP server with a browser page using Web
+# Speech API for ASR + TTS. Optional orchestrator hybrid: when the regex
+# parser misses, hand the transcript to the configured agent (Claude Code /
+# Codex / Gemini) with a voice-aware system prompt.
+voice:
+  # Default UI language for SpeechRecognition + TTS. User can override on the
+  # page via dropdown. Common values: en-US · vi-VN · ja-JP · ko-KR · zh-CN.
+  # Browser support varies — Chrome / Edge / Safari are best.
+  lang: en-US
+  # Extra languages to surface in the dropdown (beyond `lang` + en-US default).
+  extra_langs: [vi-VN]
+  # Server-side TTS fallback when no native browser/OS voice matches the
+  # selected language. F-23 (G-dogfood-v1.7): a fresh Windows install has
+  # no Vietnamese SAPI voice; we proxy MP3 from Google Translate's public
+  # TTS endpoint. Modes:
+  #   auto    — only when no native voice matches (default; balanced)
+  #   always  — always use server-side (best for cross-machine consistency)
+  #   none    — never use server-side (privacy: spoken text stays local)
+  # Privacy note: in `auto`/`always`, the spoken text leaves the machine to
+  # translate.google.com. Disable with `none` if that is unacceptable.
+  fallback_tts: auto
+  orchestrator:
+    enabled: false          # opt-in. To enable WITHOUT committing it, add the
+                             # same `voice:` section to `.dw/config/connectors.local.yml`
+                             # (gitignored) — the local file overrides this template
+                             # via deep-merge (same pattern as bot_token + allow-list).
+    agent: claude            # must exist in .dw/config/agents.yml; CLI must be on PATH
+    timeout_ms: 30000        # max wait per turn (Claude is typically 2-8s)
+
+# Future connectors land here:
+#
+# zalo:
+#   enabled: false
+#   ...
+#
+# slack:
+#   enabled: false
+#   ...

package/.dw/core/AGENTS.md

@@ -1,53 +1,53 @@
-# Agent Communication Protocol — dw-kit v1.2
-
-## Mục Đích
-
-Khi một task lớn cần nhiều "vai" khác nhau (researcher → planner → developer), việc ghi lại kết quả từng bước giúp:
-- Team members (người hoặc agent) biết chính xác task đang ở đâu
-- Audit trail rõ ràng: ai quyết định gì, lúc nào
-- Session tiếp theo có thể tiếp tục mà không cần hỏi lại
-
-## Convention: Reports Directory
-
-```
-.dw/tasks/[task-name]/
-├── [name]-context.md      # Research findings
-├── [name]-plan.md         # Implementation plan
-├── [name]-progress.md     # Progress tracking
-└── reports/               # Agent communication (v1.2+)
-    ├── 260402-1430-from-researcher-to-planner-analysis.md
-    ├── 260402-1500-from-planner-to-developer-subtask-1.md
-    └── 260402-1600-from-developer-to-reviewer-pr-ready.md
-```
-
-**Filename format**: `[YYMMDD-HHMM]-from-[role]-to-[role]-[description].md`
-
-## Status Codes
-
-| Status | Nghĩa |
-|--------|-------|
-| `DONE` | Hoàn thành, output sẵn sàng để dùng |
-| `DONE_WITH_CONCERNS` | Xong nhưng có điểm đáng chú ý / cần review |
-| `BLOCKED` | Bị chặn, cần action từ bên ngoài để tiếp tục |
-| `NEEDS_CONTEXT` | Thiếu thông tin, cần human confirm |
-
-## Khi Nào Tạo Report
-
-- Sau khi `dw-research` hoàn thành → report `from-researcher-to-planner`
-- Sau khi `dw-plan` approved → report `from-planner-to-developer`
-- Khi phát hiện blocker trong execute → report `from-developer-to-user` với `BLOCKED`
-- Sau khi review xong → report `from-reviewer-to-developer`
-
-## Khi Nào KHÔNG Cần Report
-
-- Tasks `quick` depth (≤2 files, hotfix) → không cần overhead này
-- Solo dev, single session → progress.md đã đủ
-- Thông tin đã có trong context.md / plan.md → không duplicate
-
-## Template
-
-Dùng `.claude/templates/agent-report.md`
-
-## Lưu Ý Quan Trọng
-
-Reports là **cho con người đọc**, không phải protocol cho AI. Claude Code đã communicate qua conversation context. Reports giúp team members theo dõi task cross-session, không phải AI-to-AI messaging.
+# Agent Communication Protocol — dw-kit v1.2
+
+## Mục Đích
+
+Khi một task lớn cần nhiều "vai" khác nhau (researcher → planner → developer), việc ghi lại kết quả từng bước giúp:
+- Team members (người hoặc agent) biết chính xác task đang ở đâu
+- Audit trail rõ ràng: ai quyết định gì, lúc nào
+- Session tiếp theo có thể tiếp tục mà không cần hỏi lại
+
+## Convention: Reports Directory
+
+```
+.dw/tasks/[task-name]/
+├── [name]-context.md      # Research findings
+├── [name]-plan.md         # Implementation plan
+├── [name]-progress.md     # Progress tracking
+└── reports/               # Agent communication (v1.2+)
+    ├── 260402-1430-from-researcher-to-planner-analysis.md
+    ├── 260402-1500-from-planner-to-developer-subtask-1.md
+    └── 260402-1600-from-developer-to-reviewer-pr-ready.md
+```
+
+**Filename format**: `[YYMMDD-HHMM]-from-[role]-to-[role]-[description].md`
+
+## Status Codes
+
+| Status | Nghĩa |
+|--------|-------|
+| `DONE` | Hoàn thành, output sẵn sàng để dùng |
+| `DONE_WITH_CONCERNS` | Xong nhưng có điểm đáng chú ý / cần review |
+| `BLOCKED` | Bị chặn, cần action từ bên ngoài để tiếp tục |
+| `NEEDS_CONTEXT` | Thiếu thông tin, cần human confirm |
+
+## Khi Nào Tạo Report
+
+- Sau khi `dw-research` hoàn thành → report `from-researcher-to-planner`
+- Sau khi `dw-plan` approved → report `from-planner-to-developer`
+- Khi phát hiện blocker trong execute → report `from-developer-to-user` với `BLOCKED`
+- Sau khi review xong → report `from-reviewer-to-developer`
+
+## Khi Nào KHÔNG Cần Report
+
+- Tasks `quick` depth (≤2 files, hotfix) → không cần overhead này
+- Solo dev, single session → progress.md đã đủ
+- Thông tin đã có trong context.md / plan.md → không duplicate
+
+## Template
+
+Dùng `.claude/templates/agent-report.md`
+
+## Lưu Ý Quan Trọng
+
+Reports là **cho con người đọc**, không phải protocol cho AI. Claude Code đã communicate qua conversation context. Reports giúp team members theo dõi task cross-session, không phải AI-to-AI messaging.

package/.dw/core/schemas/agent-claim.schema.json

@@ -114,7 +114,27 @@
     },
     "worktree_path": {
       "type": "string",
-      "description": "If agent operates in a git worktree per R2-3, the worktree path. .dw/cache/worktrees/{agent-id}/"
+      "description": "Absolute path to the git worktree this agent operates in (issue #15). dw does NOT create or delete this directory — the caller harness owns lifecycle (`git worktree add` / `git worktree remove`). When two claims declare distinct worktree_path values, dw conflict detection skips write_scope comparison between them (physical isolation). One or both null → conservative; assume overlap."
+    },
+    "original_lease_expires": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "description": "Issue #15: lease_expires at claim creation time (immutable). Renewals do NOT change this — caps total lease window via max_renewals."
+    },
+    "renewed_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "description": "Issue #15: timestamp of last `dw agent renew` call. Stamped on each renewal; previous value overwritten."
+    },
+    "renewal_count": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Issue #15: number of times this claim has been renewed. Bounded by MAX_RENEWALS (default 3) to prevent unbounded lease compounding."
+    },
+    "previous_lease_expires": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "description": "Issue #15: lease_expires value immediately before the most recent renewal. Provides self-describing renewal history without depending on events.jsonl."
     }
   },
   "allOf": [

package/CLAUDE.md

@@ -3,7 +3,7 @@
 Workflow toolkit codebase. Rules live in `.claude/rules/` (auto-loaded).
 
 **v2.0 direction:** Context-First SDLC Governance Layer (5 pillars — see `.dw/core/PILLARS.md`)
-**Current:** v1.6.0-rc.1 on npm `rc` tag (2026-05-20) + **v1.7.0-rc.1 candidate** on `feat/goals-okr-v1.7` shipping ADR-0010 Goals Management Layer (Accepted Round 2 — all 4 Critical + 7 Warnings + 4 Suggestions resolved; `bcurts/agentchattr` summary primitive + bigokr icon/cycle/progress/constellation visualization borrowed; 150/150 smoke tests). Active ADRs: ADR-0001 (Pragmatic Lean), ADR-0005/0006 (Supply-Chain Guard; sunset review 2026-08-12), ADR-0008 (Task Docs v3, v1.5), ADR-0009 (Agent OS, v1.6), ADR-0010 (Goals Layer, v1.7). v1.4 cuts pending telemetry.
+**Current:** **v1.8.0-rc.1** (2026-05-25) — 4/5 phase substrate for [G-rgoal-realtime-orch](.dw/goals/G-rgoal-realtime-orch/goal.md) voice-meeting Root Goal: persistent CLI-agent session runtime (`dw session *`), Telegram chat bridge (`dw connector telegram setup`) with 1-command interactive wizard, multi-workspace registry (`dw workspace *`), and browser voice MVP (`dw voice`) with hybrid orchestrator fallback (Claude/Codex/Gemini), full bilingual UX (en + vi), voice-not-installed fallback via Google Translate TTS proxy. **v1.7.0 stable** on `main` (2026-05-24). 284/284 smoke tests. Active ADRs: ADR-0001 (Pragmatic Lean), ADR-0005/0006 (Supply-Chain Guard; sunset review 2026-08-12), ADR-0008 (Task Docs v3, v1.5), ADR-0009 (Agent OS, v1.6), ADR-0010 (Goals Layer, v1.7). ADR-0011 (Session Runtime + Voice Orchestrator, v1.8) pending codification.
 
 ---
 

package/bin/dw.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const [major] = process.versions.node.split('.').map(Number);
 if (major < 18) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-kit",
-  "version": "1.7.0-rc.1",
+  "version": "1.8.0-rc.1",
   "description": "AI development workflow toolkit — structured, quality-assured, team-ready. From requirements to dashboard.",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -180,6 +180,7 @@ export function run(argv) {
     .description('Watch task.md for changes and live-reload the HTML preview in browser (local server, debounced)')
     .option('-p, --port <port>', 'Local server port (auto-finds next available if busy)', parseInt)
     .option('--rotate-token', 'Regenerate .dw/cache/watch.token at startup (invalidates old browser sessions; C-3)')
+    .option('--no-open', 'Skip auto-opening browser tab (also implied by DW_NO_OPEN=1, CI=true, or non-TTY stdout — fixes #23)')
     .action(async (taskName, opts) => {
       const { taskWatchCommand } = await import('./commands/task-watch.mjs');
       await taskWatchCommand(taskName, opts);
@@ -196,7 +197,7 @@ export function run(argv) {
 
   const agentCmd = program
     .command('agent')
-    .description('Agent OS multi-agent orchestration (ADR-0009): claim · release · claims · reports · conflicts');
+    .description('Agent OS multi-agent orchestration (ADR-0009): claim · release · renew · expire · claims · reports · conflicts · check-staged · verify');
 
   agentCmd
     .command('claim <task-id>')
@@ -224,6 +225,15 @@ export function run(argv) {
       await agentReleaseCommand(claimId, opts);
     });
 
+  agentCmd
+    .command('renew <claim-id>')
+    .description('Extend lease on an active claim WITHOUT changing claim_id (preserves audit continuity vs expire+reclaim). Capped at 3 renewals (issue #15)')
+    .option('-l, --lease <duration>', 'New lease window (e.g. 30m, 1h, 4h)', '1h')
+    .action(async (claimId, opts) => {
+      const { agentRenewCommand } = await import('./commands/agent-claim.mjs');
+      await agentRenewCommand(claimId, opts);
+    });
+
   agentCmd
     .command('expire <claim-id>')
     .description('Mark a claim as expired or invalidated (orchestrator action)')
@@ -265,6 +275,192 @@ export function run(argv) {
       await agentConflictsCommand(opts);
     });
 
+  agentCmd
+    .command('check-staged [files...]')
+    .description('Check staged files against active claim write_scopes (R2-2 cooperative; used by pre-commit-gate hook). Always exits 0; warning on stdout.')
+    .option('--stdin', 'Read file list from stdin (one path per line) instead of positional args')
+    .action(async (files, opts) => {
+      const { agentCheckStagedCommand } = await import('./commands/agent-check-staged.mjs');
+      await agentCheckStagedCommand(files, opts);
+    });
+
+  agentCmd
+    .command('verify <task-id>')
+    .description('Check events.jsonl well-formedness for a task (detects malformed JSON lines; exits 1 if any). Note: not full tamper-evidence — use git log for that.')
+    .option('-v, --verbose', 'Show raw line content for malformed entries')
+    .option('--no-strict', 'Report malformed lines but always exit 0')
+    .action(async (taskId, opts) => {
+      const { agentVerifyCommand } = await import('./commands/agent-verify.mjs');
+      await agentVerifyCommand(taskId, opts);
+    });
+
+  // ─ session: persistent CLI-agent session runtime (G-rgoal-realtime-orch phase 1) ─
+  const sessionCmd = program
+    .command('session')
+    .description('Persistent CLI-agent session runtime (orchestrates Claude Code / Codex / Gemini): start · list · show · logs · stop. Sessions survive SSH disconnect.');
+
+  sessionCmd
+    .command('start')
+    .description('Start a CLI coding agent as a detached session (survives SSH disconnect)')
+    .requiredOption('-a, --agent <name>', 'Agent name from .dw/config/agents.yml (e.g. claude, codex, gemini)')
+    .requiredOption('-g, --goal <text>', 'Goal/prompt to pass to the agent')
+    .option('-w, --workspace <path>', 'Working directory for the agent (default: cwd)')
+    .action(async (opts) => {
+      const { sessionStartCommand } = await import('./commands/session.mjs');
+      await sessionStartCommand(opts);
+    });
+
+  sessionCmd
+    .command('list')
+    .description('List active and recent sessions (this workspace, or --all-workspaces)')
+    .option('-s, --status <name>', 'Filter by status (running|completed|failed|stopped|exited|all)', 'all')
+    .option('-n, --limit <n>', 'Cap rows', parseInt)
+    .option('--all-workspaces', 'Aggregate sessions across every registered workspace (phase 3)')
+    .action(async (opts) => {
+      const { sessionListCommand } = await import('./commands/session.mjs');
+      await sessionListCommand(opts);
+    });
+
+  sessionCmd
+    .command('show <session-id>')
+    .description('Show full snapshot of a session (state + last 10 output lines)')
+    .action(async (sessionId) => {
+      const { sessionShowCommand } = await import('./commands/session.mjs');
+      await sessionShowCommand(sessionId);
+    });
+
+  sessionCmd
+    .command('logs <session-id>')
+    .description('Print session output log (default: full output.log; --events for JSON events)')
+    .option('-n, --tail <n>', 'Tail last N lines/events', parseInt)
+    .option('--events', 'Read events.jsonl instead of raw output.log')
+    .option('--bytes <n>', 'Cap output at N tail bytes', parseInt)
+    .action(async (sessionId, opts) => {
+      const { sessionLogsCommand } = await import('./commands/session.mjs');
+      await sessionLogsCommand(sessionId, opts);
+    });
+
+  sessionCmd
+    .command('stop <session-id>')
+    .description('Send SIGTERM (or --signal) to a session\'s process')
+    .option('--signal <name>', 'Signal to send (default SIGTERM)', 'SIGTERM')
+    .action(async (sessionId, opts) => {
+      const { sessionStopCommand } = await import('./commands/session.mjs');
+      await sessionStopCommand(sessionId, opts);
+    });
+
+  // ─ voice: browser-based voice MVP (G-rgoal phase 4 — KR-A destination) ─
+  program
+    .command('voice')
+    .description('Browser-based voice MVP — speak dw commands, hear results. Local server + Web Speech API. Spike scope: localhost only.')
+    .option('-p, --port <port>', 'Local server port (default 4500; auto-finds next free)', parseInt)
+    .option('--default-agent <name>', 'Default agent for "start ..." without explicit agent name')
+    .option('--no-open', 'Skip auto-opening browser tab (also implied by DW_NO_OPEN=1, CI=true, or non-TTY stdout)')
+    .action(async (opts) => {
+      const { voiceCommand } = await import('./commands/voice.mjs');
+      await voiceCommand(opts);
+    });
+
+  // ─ workspace: cross-project orchestration registry (G-rgoal phase 3) ─
+  const workspaceCmd = program
+    .command('workspace')
+    .description('Multi-workspace registry: register · list · remove · resolve. Lets one orchestrator drive sessions across multiple .dw/ projects on this host.');
+
+  workspaceCmd
+    .command('register')
+    .description('Register the current directory (or --path) as a named workspace')
+    .requiredOption('-n, --name <alias>', 'Short alias (a-z A-Z 0-9 . _ -, ≤64 chars)')
+    .option('-p, --path <abs>', 'Absolute path to workspace root (default: cwd)')
+    .action(async (opts) => {
+      const { workspaceRegisterCommand } = await import('./commands/workspace.mjs');
+      await workspaceRegisterCommand(opts);
+    });
+
+  workspaceCmd
+    .command('list')
+    .description('List registered workspaces (with session tally per workspace)')
+    .action(async (opts) => {
+      const { workspaceListCommand } = await import('./commands/workspace.mjs');
+      await workspaceListCommand(opts);
+    });
+
+  workspaceCmd
+    .command('remove')
+    .description('Remove a workspace from the registry')
+    .requiredOption('-n, --name <alias>', 'Workspace alias')
+    .action(async (opts) => {
+      const { workspaceRemoveCommand } = await import('./commands/workspace.mjs');
+      await workspaceRemoveCommand(opts);
+    });
+
+  workspaceCmd
+    .command('resolve')
+    .description('Print the absolute path of a registered workspace (scriptable)')
+    .requiredOption('-n, --name <alias>', 'Workspace alias')
+    .action(async (opts) => {
+      const { workspaceResolveCommand } = await import('./commands/workspace.mjs');
+      await workspaceResolveCommand(opts);
+    });
+
+  // ─ connector: chat platform adapters (G-rgoal phase 2) ─
+  const connectorCmd = program
+    .command('connector')
+    .description('Chat platform connectors (Telegram first; Zalo/Slack later). list · telegram start/check.');
+
+  connectorCmd
+    .command('list')
+    .description('Show configured connectors and their enabled/disabled status')
+    .action(async () => {
+      const { connectorListCommand } = await import('./commands/connector.mjs');
+      await connectorListCommand();
+    });
+
+  const telegramCmd = connectorCmd
+    .command('telegram')
+    .description('Telegram bot connector: bridges chat messages to dw session commands');
+
+  telegramCmd
+    .command('start')
+    .description('Start the long-poll loop (foreground). Ctrl+C / SIGTERM to stop.')
+    .option('--token <tok>', 'Override bot token (else DW_TG_BOT_TOKEN env or connectors.yml)')
+    .option('--base-url <url>', 'Override Telegram API base URL (test/mock only)')
+    .option('--once', 'Single getUpdates poll then exit (for diagnostics + tests)')
+    .action(async (opts) => {
+      const { connectorTelegramStartCommand } = await import('./commands/connector.mjs');
+      await connectorTelegramStartCommand(opts);
+    });
+
+  telegramCmd
+    .command('setup')
+    .description('Interactive wizard: prompts token, validates, auto-discovers your user_id, writes connectors.local.yml (gitignored)')
+    .option('--token <tok>', 'Pre-provide token (skips the password prompt)')
+    .option('--base-url <url>', 'Override Telegram API base URL (test/mock only)')
+    .action(async (opts) => {
+      const { connectorTelegramSetupCommand } = await import('./commands/connector.mjs');
+      await connectorTelegramSetupCommand(opts);
+    });
+
+  telegramCmd
+    .command('check')
+    .description('Sanity-check config + reach Telegram API (calls getMe)')
+    .option('--token <tok>', 'Override bot token')
+    .option('--base-url <url>', 'Override Telegram API base URL')
+    .action(async (opts) => {
+      const { connectorTelegramCheckCommand } = await import('./commands/connector.mjs');
+      await connectorTelegramCheckCommand(opts);
+    });
+
+  sessionCmd
+    .command('prune')
+    .description('Remove old terminated sessions (default: >=7d ended; never prunes running)')
+    .option('--older-than <dur>', 'Age cutoff like 7d / 24h / 90m / 30s', '7d')
+    .option('--status <list>', 'Comma-separated terminal statuses to consider (default: completed,failed,stopped,exited)', '')
+    .option('--dry-run', 'Show what would be removed without deleting')
+    .action(async (opts) => {
+      const { sessionPruneCommand } = await import('./commands/session.mjs');
+      await sessionPruneCommand(opts);
+    });
+
   const goalCmd = program
     .command('goal')
     .description('Goals Management Layer (ADR-0010): strategic layer above tasks. new · show · link · summary · portfolio · lint · bump · delete · view');