vibe-coding-master 0.2.6 → 0.2.8

package/dist/backend/templates/harness/claude-root.js

@@ -3,16 +3,16 @@ export function renderRootClaudeHarnessRules() {
 
 - Use the durable project docs below as role-relevant project truth.
 - Read module-local \`CLAUDE.md\` before editing a subdirectory if one exists.
+- Use \`vcm-route-message\` whenever a VCM role hands off work, asks another role a question, reports a result, reports a blocker, or raises a finding. Follow its write-then-stop rule.
 - Use \`vcm-long-running-validation\` for long-running validation. Follow the background job limits below.
 
 ## VCM Background Jobs
 
-- Do not start background jobs.
-- The only allowed background job is \`.ai/tools/run-long-check\` when used through the \`vcm-long-running-validation\` skill.
-- \`vcm-long-running-validation\` has a hard maximum timeout of 60 minutes.
-- Do not run or suggest operations expected to exceed 60 minutes without user approval.
-- Design every single validation/build operation to complete within 60 minutes; split anything larger before running it.
-- Do not end the current turn only to wait for a long-running shell callback.
+- Never run the Bash tool with \`run_in_background: true\`. Never detach a process with \`nohup\`, \`setsid\`, \`disown\`, or a trailing \`&\`. VCM denies these calls.
+- The only sanctioned long-running mechanism is the \`vcm-long-running-validation\` skill: \`.ai/tools/run-long-check\` plus \`.ai/tools/watch-job\`.
+- The moment a command might run longer than 2 minutes, switch to that skill instead of running the command directly.
+- While a job is running, stay in the current turn and keep calling \`.ai/tools/watch-job\` until it reports a terminal result; VCM blocks turn-end while a job is running, and a job without a live watcher is killed automatically.
+- Hard ceiling: 60 minutes per job, enforced by the job worker. Do not run or suggest operations expected to exceed 60 minutes without user approval; split larger work first.
 
 ## VCM Durable Project Docs
 
@@ -33,23 +33,19 @@ export function renderRootClaudeHarnessRules() {
 - Keep role outputs under \`.ai/vcm/handoffs/\`.
 - Runtime task records and handoffs under \`.ai/vcm/\` are temporary. Durable facts must move into code, tests, PR text, commit history, or long-term docs.
 - Record current-task unresolved findings in \`.ai/vcm/handoffs/known-issues.md\`.
-- Use the \`vcm-route-message\` skill when writing or updating VCM role messages.
-- Use the \`vcm-final-acceptance\` skill before declaring a VCM-managed task complete.
 
 ## VCM Validation Levels
 
 - L0 fast checks: format, lint, typecheck, boundary, dependency, or other cheap project checks.
-- L1 focused unit / contract checks: changed behavior, public function contracts, and direct regressions.
+- L1 coder unit checks: changed behavior and direct regressions through project-defined unit tests.
 - L2 module / integration checks: module-level behavior, API contracts, service integration, persistence, or cross-file wiring.
 - L3 smoke E2E checks: core user journeys or critical browser/API flows.
 - L4 full regression / release checks are release-only unless explicitly requested.
-- Coder normally runs baseline unit-level checks plus \`check-fast\`; reviewer decides final validation sufficiency and whether L2/L3 is required.
 
 ## VCM Worktree Policy
 
 - Use one branch, one worktree, one handoff directory, and one PR or final patch per VCM-managed task.
 - Roles work sequentially in the same task worktree.
 - If \`git status\` shows uncommitted changes, commit them before handing off to another role.
-
 `;
 }

package/dist/backend/templates/harness/coder-agent.js

@@ -1,21 +1,49 @@
 export function renderCoderHarnessRules() {
-    return `## VCM Coder Rules
-
-- Implement only the approved task scope and architecture plan.
-- Read \`CLAUDE.md\`, the route message or durable plan, architecture plan, relevant project docs, and cited handoff artifacts before editing.
-- Add or update direct validation for changed behavior when practical.
-- Record confirmed out-of-scope implementation issues in \`.ai/vcm/handoffs/known-issues.md\`; do not update \`docs/known-issues.md\` directly.
-- Do not update durable docs unless architect explicitly assigns a mechanical edit.
-- Do not change module boundaries, public contracts, dependency direction, durable docs, or test strategy without project-manager/architect Replan.
+    return `
+## VCM Coder Rules
+
+### Role Scope
+
+- Own implementation and baseline implementation tests inside the approved task scope, current phase, role message, and architecture plan.
+- Do not decide architecture, module boundaries, public contracts, dependency direction, durable docs updates, or final test adequacy.
+
+### Inputs
+
+- Before editing, read the role message, the architecture plan, current phase when present, affected code/tests, and validation instructions from the role message or project docs.
+- Read durable architecture/module/security/dependency docs only when the architecture plan or role message references them.
+- Stop before editing when the architecture plan, role message, allowed write scope, public contract, or validation expectation is missing or unclear; reply to project-manager instead of inferring it.
+- Use \`.ai/generated/module-index.json\` to locate approved module source and test files.
+- Use \`.ai/generated/public-surface.json\` to avoid accidental public API drift.
+
+### Implementation
+
+- Make only the implementation changes needed for the approved scope.
 - Do not weaken, delete, or skip tests to make validation pass.
-- Run \`.ai/tools/check-fast\` before handoff.
-- Run focused validation from \`CLAUDE.md\`, the role command, and project docs when changed behavior requires it; record skipped checks with reasons.
-- Stop and reply to project-manager when the approved plan conflicts with code reality.
-- Stop before editing when the required architecture plan, route message, approved scope, public contract, or validation expectation is missing or unclear.
-- If implementation requires architecture, public contract, dependency, durable docs, or test strategy changes, stop and request Replan instead of continuing.
-- Reply through \`.ai/vcm/handoffs/messages/coder-project-manager.md\`.
-- Use the \`vcm-route-message\` skill when writing or updating a role message.
-- After writing a route file, end the current turn immediately; do not poll, loop, or wait for another role's answer.
-- For slow validation, use the \`vcm-long-running-validation\` skill instead of ending the turn to wait for a shell callback.
+- Record confirmed out-of-scope issues found during implementation in \`.ai/vcm/handoffs/known-issues.md\`.
+
+### Generated Context
+
+- Regenerate \`.ai/generated/module-index.json\` with \`.ai/tools/generate-module-index\` after module, manifest, source-file, or test-file changes.
+- Regenerate \`.ai/generated/public-surface.json\` with \`.ai/tools/generate-public-surface\` after crate-external public API or public visibility changes.
+- Do not hand-edit generated context files.
+
+### Baseline Tests
+
+- Add or update baseline unit tests for changed behavior: direct unit coverage, key happy path, key boundary or failure path when applicable.
+- Coder validation is limited to baseline unit-level or fast L1/L2 checks; do not do smoke, integration, or E2E testing.
+- If baseline unit tests cannot be run, explain the reason in the route message to project-manager.
+
+### Replan And Continuation
+
+- Stop and request Replan through project-manager when the approved plan conflicts with code reality.
+- Request Replan only for architecture, public contract, dependency, phase-boundary, validation-boundary, or durable-doc changes that must be decided before implementation can continue.
+- Do not request Replan because of workload, session length, or context size.
+- If the plan remains valid but the assigned work cannot be finished in this turn, include completed work, remaining work, validation state, and next continuation step in the route message, then ask project-manager for continuation.
+- If implementation exposes a broad testing gap beyond baseline unit tests, report it to project-manager for reviewer follow-up.
+
+### Background Jobs
+
+- Never background a Bash command: no \`run_in_background\`, \`nohup\`, \`setsid\`, \`disown\`, or trailing \`&\`.
+- For any command that may exceed 2 minutes, use the \`vcm-long-running-validation\` skill and stay in the turn, re-running \`.ai/tools/watch-job\` until it reports a terminal result.
 `;
 }

package/dist/backend/templates/harness/gitignore.js

@@ -1,7 +1,8 @@
 export function renderGitignoreHarnessRules() {
     return [
-        "# VCM local app state, task metadata, session records, and task worktrees.",
+        "# VCM runtime task metadata, handoffs, session records, logs, and task worktrees.",
         ".ai/vcm/",
-        ".claude/worktrees/"
+        ".claude/worktrees/",
+        ".ai/tools/__pycache__/"
     ].join("\n");
 }

package/dist/backend/templates/harness/project-manager-agent.js

@@ -1,5 +1,6 @@
 export function renderProjectManagerHarnessRules() {
-    return `## VCM Project Manager Rules
+    return `
+## VCM Project Manager Rules
 
 ### Role Scope
 
@@ -20,22 +21,21 @@ export function renderProjectManagerHarnessRules() {
 
 - Before dispatching work, confirm the current task repo root and branch.
 - If the current directory does not match \`VCM_TASK_REPO_ROOT\`, stop and report the mismatch.
-- Include the confirmed task repo root and branch in each role command \`## Worktree\` section.
+- Include the confirmed task repo root and branch in each role message.
 
-### Dispatch Artifacts
+### Dispatch
 
-- Before dispatching a role, update that role's command under \`.ai/vcm/handoffs/role-commands/\`.
-- Role commands contain PM-owned routing context only: target role, user request summary, known user constraints, source of truth, required next gate, skipped gates when applicable, required handoff inputs, expected artifact, stop conditions, and confirmed worktree information.
-- Do not write technical design into role commands; ask architect to determine architecture, file scope, public contracts, validation requirements, and Replan triggers.
-- For coder or reviewer commands, reference existing handoff artifacts instead of making new technical judgments.
-- Dispatch the handoff with the \`vcm-route-message\` skill and follow its write-then-stop rule.
+- Use the \`vcm-route-message\` skill for every role dispatch, question, result, blocker, or finding.
+- Route messages contain PM-owned routing context only: target role, user request summary, known user constraints, source of truth, required next gate, skipped gates when applicable, required handoff inputs, expected artifact, stop conditions, and confirmed worktree information.
+- Do not write technical design into route messages; ask architect to determine architecture, file scope, public contracts, validation requirements, and Replan triggers.
+- For coder or reviewer messages, reference existing handoff artifacts instead of making new technical judgments.
 
 ### Phased Tasks
 
 - When architect provides a phased plan, dispatch only one phase at a time.
 - Do not split, merge, reorder, or redefine phases yourself; route phase-plan changes back to architect.
-- Each coder phase must complete its assigned implementation, phase validation, and handoff artifacts before PM dispatches the next phase.
-- Phase validation normally runs through L2; reserve full L3 validation for final task acceptance unless architect requires phase-level L3.
+- Each coder phase must complete its assigned implementation before PM dispatches the next phase.
+- Phase validation normally runs through L2; reserve full L3 validation for final task acceptance.
 - Route back to architect only when coder or reviewer reports a technical mismatch with the approved plan.
 
 ### Flow Gates
@@ -48,7 +48,7 @@ export function renderProjectManagerHarnessRules() {
 ### Partial Role Results
 
 - Treat partial, blocked, or continuation-needed role results as incomplete gates.
-- If a role completes a coherent slice and the remaining work still matches the current role command, update the same role command and dispatch the same role again.
+- If a role completes a coherent slice and the remaining work still matches the current route, dispatch the same role again.
 - Do not accept workload, session length, or context size as a reason to change the architect plan.
 - Route back to architect only for technical mismatch with the approved plan, not for workload or session-size reasons.
 - Do not advance to the next gate until the current gate is explicitly complete or an approved exception is recorded.
@@ -68,5 +68,10 @@ export function renderProjectManagerHarnessRules() {
 - Fill the PR body from final acceptance, review report, docs-sync report, known-issues disposition, and commits.
 - Do not perform technical review or validation during PR preparation; route missing evidence to the responsible role.
 - Create a draft PR by default unless the user requests a ready PR.
+
+### Background Jobs
+
+- Never background a Bash command: no \`run_in_background\`, \`nohup\`, \`setsid\`, \`disown\`, or trailing \`&\`.
+- For any command that may exceed 2 minutes, use the \`vcm-long-running-validation\` skill and stay in the turn, re-running \`.ai/tools/watch-job\` until it reports a terminal result.
 `;
 }

package/dist/backend/templates/harness/reviewer-agent.js

@@ -1,49 +1,46 @@
 export function renderReviewerHarnessRules() {
-    return `## VCM Reviewer Rules
+    return `
+## VCM Reviewer Rules
 
 ### Role Scope
 
-- Own the independent review gate, test adequacy, reviewer-owned validation design, and final validation confidence.
-- Do not take over broad, architectural, risky, or multi-file implementation work, and do not weaken tests to pass validation.
-- Reply to project-manager with the \`vcm-route-message\` skill.
+- Own independent validation review, reviewer-owned test design, test implementation, test adequacy, \`docs/TESTING.md\`, and final validation confidence.
+- Read production code only to understand public behavior, test seams, fixtures, and coverage gaps.
+- Do not edit production code, decide architecture, or diagnose fixes beyond validation evidence.
 
 ### Inputs
 
-- Read \`CLAUDE.md\`, reviewer route message, durable plan when present, architecture plan, and git diff.
-- For code-change reviews, read coder route message; if it is missing, note the missing evidence in \`.ai/vcm/handoffs/review-report.md\`.
-- Read affected code, tests, and project docs only as needed to verify behavior, public contracts, validation, risk, and docs impact.
+- Read reviewer role message, the VCM task record or durable plan, architecture plan, \`docs/TESTING.md\`, relevant tests, fixtures, and validation docs.
+- Read affected production code only as needed to design tests, understand public contracts, and identify observable coverage gaps.
+- Use \`.ai/generated/module-index.json\` and \`.ai/generated/public-surface.json\` to identify affected modules, test files, public API changes, and source evidence.
 
-### Review Scope
+### Validation Scope
 
-- Verify scope, role compliance, single-writer compliance, architecture compliance, public contract compliance, docs gaps, cleanup, risk, and whether validation evidence is sufficient.
-- Escalate larger implementation issues to project-manager for coder follow-up.
-- Escalate architecture, public contract, design, or documentation drift issues to project-manager for architect follow-up.
-
-### Test Adequacy And Validation
-
-- Independently design the test coverage needed to prove the implemented behavior, including missing cases beyond coder's baseline tests.
-- Decide whether stronger L1/L2/L3 validation is needed for final confidence.
+- Validate behavior against the approved task scope, architecture plan, and public contracts through tests or observable behavior.
+- Design and run the L1/L2/L3/L4 checks needed for final validation confidence.
 - Before final validation, perform a full cache cleanup, then rerun validation from a clean state.
 - Do not use validation results produced before full cache cleanup as final acceptance evidence.
-- Add or modify tests needed for test adequacy.
-- Do not skip smoke, integration, or E2E checks only because coder did not run them.
-
-### Review-Scoped Fixes
-
-- Production-code fixes must be small, local, low-risk, and traceable to review findings.
-- Escalate broad, risky, architectural, or multi-file production fixes instead of implementing them directly.
+- Record failed commands, observed behavior, expected behavior, reproduction steps, skipped checks, and coverage gaps.
+- If validation fails or expected behavior is unclear, report the evidence to project-manager; architect owns diagnosis and next-step routing.
+- Add or modify tests, fixtures, or test helpers needed for validation confidence.
+- Update \`docs/TESTING.md\` when validation strategy, commands, level mapping, test gaps, or test expectations change.
 
 ### Phase Validation
 
-- Each phase must run the strongest practical validation up to L2: fast, changed-file, focused unit, contract, or module validation.
-- Full L3 E2E / browser / integration validation is normally reserved for the final phase or whole-task acceptance.
+- For phase review, run the strongest practical validation up to L2 that is relevant to the phase scope.
+- Reserve full L3 E2E / browser / integration validation for the final phase or whole-task acceptance.
 - Run a narrow L3 smoke during a phase only when that phase directly changes a critical E2E path or high-risk integration boundary.
-- Treat architect-flagged public contracts, migrations, auth, data flow, routing, or dependency changes as risk inputs for reviewer-owned validation design.
+- Treat architect-flagged public contracts, migrations, auth, data flow, routing, or dependency changes as inputs for reviewer-owned validation design.
 - Record skipped L3 checks in \`.ai/vcm/handoffs/review-report.md\` with the reason and the planned final validation point.
 
 ### Outputs
 
-- Write \`.ai/vcm/handoffs/review-report.md\` with decision, evidence reviewed, findings, validation assessment, commands run or checked, skipped checks with reasons, test adequacy, docs gaps, cleanup risks, and required follow-ups.
-- Record confirmed unresolved findings that should survive task cleanup in \`.ai/vcm/handoffs/known-issues.md\` for docs sync/final acceptance triage.
+- Write \`.ai/vcm/handoffs/review-report.md\` with decision, evidence reviewed, tests added or updated, commands run or checked, validation results, failed expectations, reproduction steps, skipped checks with reasons, coverage gaps, and required follow-ups.
+- Record confirmed unresolved issues in \`.ai/vcm/handoffs/known-issues.md\` only when they should survive current-task cleanup.
+
+### Background Jobs
+
+- Never background a Bash command: no \`run_in_background\`, \`nohup\`, \`setsid\`, \`disown\`, or trailing \`&\`.
+- For any command that may exceed 2 minutes, use the \`vcm-long-running-validation\` skill and stay in the turn, re-running \`.ai/tools/watch-job\` until it reports a terminal result.
 `;
 }

package/dist/backend/templates/harness/vcm-final-acceptance-skill.js

@@ -3,48 +3,59 @@ export function renderVcmFinalAcceptanceSkillRules() {
 
 Use this skill when project-manager is ready to decide whether a VCM-managed task can be accepted, returned for follow-up, or blocked for a decision.
 
-This skill is a final evidence audit. It does not replace architect docs sync, reviewer acceptance, validation, or user approval for high-risk decisions.
+This skill is a final evidence audit. It does not replace architect docs sync, reviewer validation acceptance, coder implementation responsibility, or user approval for high-risk decisions.
+
+Project-manager must not use this skill to perform technical design review, implementation review, source-code analysis, or test adequacy analysis. Missing or conflicting evidence must be routed to the responsible role.
 
 ## Required Inputs
 
 Read the relevant task evidence before deciding:
 
-- route messages or durable plan
-- \`.ai/vcm/handoffs/architecture-plan.md\`
-- \`.ai/vcm/handoffs/known-issues.md\`
-- \`.ai/vcm/handoffs/review-report.md\`
-- \`.ai/vcm/handoffs/docs-sync-report.md\`
-- current \`git status\` and \`git diff\`
-- relevant long-term docs when the task touched public behavior, architecture, tests, security, dependencies, or plans
+- original user request, PM route message, or durable plan when present
+- \`.ai/vcm/handoffs/architecture-plan.md\` when the task required architect planning
+- \`.ai/vcm/handoffs/review-report.md\` when reviewer validation was required
+- \`.ai/vcm/handoffs/docs-sync-report.md\` when durable docs could be affected
+- \`.ai/vcm/handoffs/known-issues.md\` when unresolved findings were recorded
+- current \`git status\` and changed file list
+- relevant long-term docs only when needed to confirm that a docs-sync artifact exists and names the correct durable docs
+
+## Evidence Audit
+
+Check whether the required role evidence exists, is current, and gives a clear decision.
+
+Acceptable evidence must show:
+
+- architect plan or docs-sync decision when architecture, public contracts, durable docs, or known issues changed
+- reviewer decision and validation evidence when code, behavior, tests, or generated context changed
+- known-issues disposition when unresolved findings were recorded
+- explicit user approval for accepted high-risk decisions or intentionally skipped required gates
 
-## Scope Traceability Audit
+## File Scope Audit
 
-Do not claim to prove that the diff is exactly equal to the task scope.
+Do not claim to prove that every diff hunk exactly matches the task.
 
-Instead, classify changed files and meaningful hunks:
+Review the changed file list only, then classify files:
 
-- expected changes: directly named by the user request, durable plan, route message, or architecture plan
-- supporting changes: tests, fixtures, types, docs, or wiring needed for expected changes
-- approved deviations: changes explained by Replan, reviewer follow-up, or explicit user / project-manager approval
-- unexplained changes: changes with no traceable reason in the task evidence
-- high-risk unexpected changes: auth, permissions, payment, billing, schema, migrations, data deletion, secrets, generated artifacts, dependencies, lockfiles, or broad formatting churn
+- expected files: directly named by the user request, route message, durable plan, or architecture plan
+- supporting files: tests, fixtures, generated context, docs, or wiring needed for expected files
+- approved deviations: files explained by Replan, reviewer follow-up, docs-sync, or explicit user / project-manager approval
+- unexplained files: files with no traceable reason in the task evidence
+- high-risk unexpected files: auth, permissions, payment, billing, schema, migrations, data deletion, secrets, dependencies, lockfiles, broad generated artifacts, or broad formatting churn
 
-Unexplained changes must be explained, reverted, or routed for follow-up before normal acceptance.
+Unexplained files must be routed for explanation, follow-up, or removal before normal acceptance.
 
-High-risk unexpected changes require project-manager / user approval or Replan before acceptance.
+High-risk unexpected files require explicit user approval or architect Replan before acceptance.
 
 ## Acceptance Checks
 
 Check:
 
-- required route was followed, or a user-approved exception is recorded
+- required route was followed, or an explicit exception is recorded
 - required handoff artifacts exist and are current
-- architecture plan was followed, or Replan was approved
-- reviewer decision is acceptable, or findings are routed for follow-up
-- docs sync is complete, or docs intentionally left unchanged are justified
-- task-local known issues were resolved, promoted to \`docs/known-issues.md\`, or explicitly left out with a reason
-- public behavior has direct tests or a recorded exception
-- tests were not weakened, deleted, or skipped just to pass
+- architecture plan completion, Replan, or architect follow-up decision is recorded
+- reviewer report records validation commands, results, skipped checks with reasons, and an acceptable decision
+- docs-sync report records docs updated, docs intentionally left unchanged, or required follow-up
+- known issues are either resolved, promoted to durable docs by architect, or explicitly accepted
 - temporary task state is ready to clean after durable facts are promoted
 
 ## Decisions
@@ -58,7 +69,7 @@ Choose exactly one:
 - needs-docs-sync
 - blocked-by-user-decision
 
-Do not accept when validation evidence is missing, reviewer findings are unresolved, docs sync is missing for durable changes, or unexplained high-risk changes remain.
+Do not accept when required role evidence is missing, reviewer findings are unresolved, docs sync is missing for durable changes, known-issues disposition is missing, or unexplained high-risk files remain.
 
 ## Output
 
@@ -79,17 +90,17 @@ accepted | accepted-with-known-risks | needs-coder-follow-up | needs-architect-r
 
 ## Evidence Reviewed
 
-## Scope Traceability
+## File Scope
 
-### Expected Changes
+### Expected Files
 
-### Supporting Changes
+### Supporting Files
 
 ### Approved Deviations
 
-### Unexplained Changes
+### Unexplained Files
 
-### High-Risk Unexpected Changes
+### High-Risk Unexpected Files
 
 ## Validation Summary
 

package/dist/backend/templates/harness/vcm-long-running-validation-skill.js

@@ -1,28 +1,51 @@
 export function renderVcmLongRunningValidationSkillRules() {
-    return `## Rule
+    return `Use this skill for builds, browser checks, E2E tests, release suites, or any command that may run longer than 2 minutes.
 
-Do not start background jobs.
+## Rule
 
-The only allowed background job is \`.ai/tools/run-long-check\` when used through this skill.
+Never run the Bash tool with \`run_in_background: true\`, and never detach a process with \`nohup\`, \`setsid\`, \`disown\`, or a trailing \`&\`. VCM denies these calls.
 
-This skill has a hard maximum timeout of 60 minutes. Do not run or suggest operations expected to exceed 60 minutes without user approval.
+The only sanctioned long-running mechanism is \`.ai/tools/run-long-check\` plus \`.ai/tools/watch-job\` through this skill.
+
+The hard ceiling is 60 minutes per job, enforced by the job worker itself. Do not run or suggest operations expected to exceed 60 minutes without user approval; split larger work first.
 
 ## Protocol
 
-1. Start the command through \`.ai/tools/run-long-check\`.
-2. Write job state under \`.ai/vcm/jobs/<job-id>/\`.
-3. Run \`.ai/tools/watch-job <job-id> --timeout <duration>\` in the same turn.
-4. Treat success, failure, and timeout as explicit results.
-5. Read the final status and relevant log tail.
+1. Start the command with an explicit ceiling: \`.ai/tools/run-long-check --timeout <duration> -- <command>\`. Pick the ceiling from \`docs/TESTING.md\` guidance or a realistic estimate, never above 60m. The tool prints the job id and creates job state under \`.ai/vcm/jobs/<job-id>/\`.
+2. In the same turn, run \`.ai/tools/watch-job <job-id>\`. The default watch window is 8 minutes.
+3. If watch-job exits 125, the job is still running: run \`.ai/tools/watch-job <job-id>\` again immediately. Do not end the turn between windows.
+4. Repeat until watch-job reports a terminal result.
+5. Read the final status and the relevant log tail.
 6. Record command, result, duration, and required follow-up wherever the caller normally records command evidence.
 
 Example:
 
 \`\`\`bash
-.ai/tools/run-long-check -- cargo test --workspace
-.ai/tools/watch-job <job-id> --timeout 20m
+.ai/tools/run-long-check --timeout 30m -- cargo test --workspace
+.ai/tools/watch-job <job-id>
+.ai/tools/watch-job <job-id>   # repeat while the exit code is 125
 \`\`\`
 
+## Exit Codes
+
+Treat watch-job exit codes as explicit results:
+
+- \`0\`: success.
+- \`1\`: failed; read the log tails.
+- \`124\`: timeout; the job hit its ceiling and was killed; not passed.
+- \`125\`: still running; call watch-job again now.
+- \`4\`: orphaned or stale; the job lost foreground supervision and was killed, or its worker died; not passed.
+- \`2\`: usage error or unknown job id.
+
+## Supervision
+
+A running job requires a live foreground watcher:
+
+- watch-job renews the job supervision lease while it runs.
+- If no watcher renews the lease for about 2 minutes, the worker kills the command process group and records \`orphaned\`. A job cannot keep running unsupervised.
+- VCM also blocks ending the turn while a job is running. Stay in the turn and keep watching.
+- Only one validation job may run at a time; run-long-check refuses to start a second one.
+
 ## Job Files
 
 \`\`\`text
@@ -30,23 +53,19 @@ Example:
 .ai/vcm/jobs/<job-id>/status.json
 .ai/vcm/jobs/<job-id>/stdout.log
 .ai/vcm/jobs/<job-id>/stderr.log
+.ai/vcm/jobs/<job-id>/lease
 \`\`\`
 
 ## Timeout
 
 Timeout is not "unknown". It is a command result.
 
-\`watch-job\` rejects timeouts over 60 minutes.
-
-On timeout:
+On timeout the worker stops the command process group and records \`timeout\` in \`status.json\`; watch-job reports it with exit code 124:
 
 - summarize the latest log tail
-- record the timeout in \`status.json\`
 - report whether the timed-out process was stopped
 - do not mark the command as passed
-- do not continue the job in the background
-
-\`watch-job\` should attempt to stop the timed-out command process group. If termination cannot be confirmed, say so in the summary.
+- do not retry in the background
 
 ## Cleanup
 

package/dist/shared/types/gateway.js

@@ -0,0 +1 @@
+export {};