Cm Terminal

Terminal Process Monitoring

Overview

Running commands without checking output is flying blind. Users MUST see what's happening at every step.

Core principle: Every command gets announced, monitored, and verified. No exceptions.

Violating the letter of this rule is violating the spirit of this rule.

The Iron Law

NO COMMAND RUNS WITHOUT READING ITS OUTPUT.
NO ERROR GOES UNREPORTED.
NO NEXT STEP WITHOUT PREVIOUS STEP CONFIRMED.

When to Use

ALWAYS when running terminal commands via run_command. This includes:

• Build commands (npm run build, npm run dev)
• Test commands (npx vitest run)
• Install commands (npm install)
• Deploy commands (npx wrangler pages deploy)
• Git commands (git push, git commit)
• Any script or CLI tool

The Protocol

Step 1: Announce Before Running

BEFORE calling run_command:

Update task_boundary TaskStatus to describe what you're about to run and why.

TaskStatus: "Running npm build to compile production bundle"
TaskStatus: "Installing dependencies with npm install"
TaskStatus: "Deploying to Cloudflare Pages"

Step 2: Set Appropriate Wait Time

Choose WaitMsBeforeAsync based on expected command duration:

Step 3: Read Output Immediately

After run_command returns:

1. If command completed synchronously → read output in the response
2. If command sent to background → call command_status immediately with WaitDurationSeconds: 10
3. NEVER proceed to next step without reading output

Step 4: Check for Errors

Scan output for error indicators:

ERROR PATTERNS TO DETECT:
- Exit code ≠ 0
- "error", "Error", "ERROR"
- "fail", "FAIL", "failed", "FAILED"
- "ENOENT", "EACCES", "EPERM"
- "not found", "No such file"
- "Cannot find module"
- "SyntaxError", "TypeError", "ReferenceError"
- "Build failed"
- "Command failed"
- "Permission denied"
- "FATAL"
- Stack traces (lines with "at " prefix)
- npm ERR!
- Warning patterns that indicate real problems

Step 4b: Compress Before Quoting

Before pasting stdout into TaskSummary or model context:

Helper: src/utils/output-compress.ts — compressGitStatus, compressNpmTest, summarizeBuildLog, collapseRepeatedLines, compressFor(command, stdout).

Anti-pattern: Pasting full stdout (> 50 lines) into TaskSummary when only the failing portion matters. Compress first, then quote.

Step 5: Stop on Error

If ANY error is detected:

1. STOP — Do not run any more commands
2. IDENTIFY — Extract the exact error message and context
3. REPORT — Call notify_user with error if critical
4. FIX — Use cm-debugging if proceeding to fix

Step 6: Poll Long-Running Commands

For background commands (returned a CommandId):

1. Poll command_status every 10-15 seconds
2. After EACH poll, update task_boundary TaskStatus with latest output summary
3. Continue until command completes (status: "done")
4. Read final output and check for errors

Step 7: Confirm Success

Only after reading output AND confirming no errors:

Update task_boundary TaskSummary with the result:

TaskSummary: "Build completed successfully (0 errors, 0 warnings)"
TaskSummary: "All 519 tests passed"
TaskSummary: "Deployed to https://prms-4pv.pages.dev successfully"

Red Flags — STOP and Follow Protocol

If you catch yourself doing ANY of these:

• Running a command without updating TaskStatus first
• Calling run_command while previous command is still running
• Skipping command_status for a background command
• Proceeding to next step without reading output
• Ignoring warnings or errors in output
• Assuming a command succeeded without checking exit code
• Running 3+ commands in parallel without monitoring each

ALL of these mean: STOP. Follow the protocol.

Anti-Patterns

Special Cases

Interactive Commands (dev servers, watch mode)

1. Start with WaitMsBeforeAsync: 3000-5000
2. Check initial output for startup success/failure
3. Look for "ready" / "listening on" / "compiled successfully" signals
4. Report the URL/port to user
5. Note the CommandId for future reference

Parallel Commands

If running multiple commands at once:

1. Track ALL CommandIds
2. Poll each one separately
3. If ANY fails → report which one failed

Piped/Chained Commands (&&, |)

1. The exit code reflects the LAST command in the chain
2. Read full output — errors from earlier commands may appear but the chain continues
3. Be extra careful with cd dir && npm run build — if cd fails, build won't run

Severity Levels

The Bottom Line

Every command tells a story through its output. READ the story. SHARE it with the user. STOP if the story is bad.