session-coordinator

Ensures the main process never blocks by spawning async subagents for long, uncertain, or remote tasks, keeping dialog always responsive.

Session Coordinator Skill v3.0.1 — Main Process Never Blocks

Core Principle

Main process = dialog + dispatch. Never block.

The main goal is responsiveness — the main process must never be blocked, stalled, or made unresponsive. This is not "never execute." It is "never block."

A blocked main process shows as: typing indicator disappears, user cannot get a response, session appears frozen.

Decision Framework

Spawn when (blocks or uncertain):

• Remote operations (SSH, remote API calls)
• git push/pull/clone operations
• Any operation involving network I/O
• Operations with unknown duration
• Operations that need isolation (fail without affecting main session)
• State-modifying operations: file write, git commit, package publish, deploy, or any operation that changes persistent state on disk or remote
• Anything requiring waiting for external result
• Spawn must always include a label parameter (see Spawn Label Convention below)

Execute directly when (fast, non-blocking AND same topic):

• Local scripts that run in <1 second
• Reading files, writing docs, writing code
• Dialog, judgment, approval, reasoning
• Quick system calls (RAM, disk, process status)
• Must NOT involve network I/O (SSH, HTTP, remote calls)
• Must be same topic as current conversation

Self-check signal:

"If my typing indicator disappeared, am I being blocked right now?"

If a question or request is on a DIFFERENT topic, spawn it — do not handle it directly even if it seems fast. Different topic = different subagent.

---

Spawn Mode v3 — Default: session thread

Default spawn mode is mode="session" with thread=true.

• Use mode="session", thread=true for most tasks (interactive, multi-step, or uncertain duration)
• Use mode="one-shot" only when explicitly instructed or when the task is trivial and guaranteed single-turn
• Never assume mode="run" (run = detached, no result push = unreliable)

python

# ✅ Default: session thread (most tasks)
spawn(task="task-description", mode="session", thread=true, label="task-label")

# ✅ Explicit one-shot: only when scope is trivially bounded
spawn(task="task-description", mode="one-shot", label="task-label")

# ❌ Don't use run unless you explicitly need detached/no-result
spawn(task="task-description", mode="run")

---

Timeout Guidelines

Use these as a guide to set runtime when spawning:

Tier	Duration	Examples
fast	~5 min	file ops, single API call, config check, quick test
medium	~15 min	git operations, moderate build, moderate data processing
long	60 min+	large clones, heavy builds, multi-step deployments, data migration

python

# Fast task — 5 min timeout
spawn(task="check service status", runtime="fast", label="service-status-check")

# Medium task — 15 min timeout
spawn(task="clone repository and run tests", runtime="medium", label="repo-test")

# Long task — 60 min timeout
spawn(task="full deployment pipeline", runtime="long", label="deploy-pipeline")

---

Spawn Label Convention

When spawning a subagent, always include a descriptive label parameter:

• Use dashes, not spaces (e.g., project-config-sync not project config sync)
• Use generic, descriptive names only — never specific project names, IPs, hostnames, or user names
• Label should reflect the actual task category or action

Generic placeholder examples:

• project-name → repo-name or project-alfa
• 192.168.x.x → remote-host or node-alpha
• user@host → admin-user or service-account

python

# ✅ Good: generic, dashes, descriptive
spawn(task="sync config to remote node", label="config-sync")
spawn(task="run test suite for module", label="test-suite")
spawn(task="deploy service to environment", label="service-deploy")

# ❌ Bad: spaces, specific names, cryptic
spawn(task="...", label="proj1")           # too short, no dashes
spawn(task="...", label="192-168-1-1")     # specific IP — not allowed
spawn(task="...", label="johns-task")      # specific user name — not allowed
spawn(task="...", label="foo-bar-v2")      # specific project codename — not allowed

When the user says "stop that thing", look at subagents list and match the label to find the right subagent to stop.

---

Lifecycle Management

Auto-Timeout

• Subagents run with a defined runtime timeout (fast/medium/long)
• If the subagent exceeds its timeout without a result, it is considered stalled
• Do NOT manually extend timeouts unless user explicitly asks

Done Signals

A subagent can be safely let timeout (or can terminate early) when:

1. user says "done" — user has indicated the task is complete or no longer needed
2. Context switches — user has moved to a different topic or task; the previous subagent is no longer relevant
3. Explicit cancel — user says "stop", "cancel", "forget it"

What to do when done signal fires:

• Do NOT try to salvage a timed-out subagent
• Do NOT restart the same task unless user explicitly asks
• Acknowledge the signal and move on

---

Result Writing

Important results → MEMORY.md

After a subagent completes, if the result is significant (decision made, lesson learned, important output, state change), write it to MEMORY.md in the main session.

markdown

## [Date] Task Result
- Task: task-description
- Outcome: what happened
- Key decision/learning: ...

Daily logs → memory/YYYY-MM-DD.md

Routine subagent work should be logged in the daily memory file:

bash

# Create/update daily log
memory/2026-04-06.md

Include: task label, what was done, key result. Keep it concise.

---

Spawn Is Transparent

Do not announce to user when you are spawning a subagent.

• Do NOT say "I'm spawning a subagent to handle this..."
• Do NOT say "Let me dispatch this to a background agent..."
• Just spawn it and continue the dialog naturally

user does not need to know the execution architecture. The subagent handles the work; you handle the conversation.

---

Role Definition

Responsibility	Main Process	Subagent
User dialog	✅	❌
Task dispatch	✅	❌
Result production	❌	✅
Result delivery to user	✅	❌
Decision making	✅	❌
Status coordination	✅	❌
Fast local operations	✅	❌
Blocking operations	❌	✅

---

Execution Model

Blocked = Wrong

If the main process blocks, the pattern has failed — regardless of whether the task eventually completes.

Spawn and Continue

python

# ❌ Wrong — blocks main process, typing disappears
exec("ssh remote-host ...")
subprocess.run(...)

# ✅ Correct — non-blocking, typing stays active
spawn(task="remote operation description", runtime="medium", mode="session", thread=true, label="remote-task")

After spawning: continue dialog with user. Do NOT wait. Results arrive via push event.

Fire-and-Forget

• Spawn with full task description and runtime estimate
• Do NOT estimate how long it takes
• Do NOT poll for status
• Continue dialog
• Report result when delivered

---

Multi-Node Coordination

Each node runs its own subagents. Nodes do not delegate to each other's subagents. Coordination between nodes goes through whatever inter-node protocol is configured for that setup.

---

Anti-Patterns

Anti-Pattern	Why Wrong	Correct
"Let me check..." + exec in main	Blocks typing	Spawn subagent
Waiting for subagent result before responding	Blocks dialog	Continue, report later
Direct remote operations in main process	Blocks	Spawn
Spawning to avoid doing work (not to avoid blocking)	Misuse of pattern	Execute directly if fast
All work spawn, nothing direct	Over-interpretation	Fast ops = direct
Announcing the spawn to user	Noise, breaks flow	Spawn silently, continue
Using specific IPs/hostnames in labels	Privacy leak	Use generic names

---

Workflow Summary

1. User request arrives
2. Assess: will this block? (slow / uncertain / remote = spawn; fast / local / dialog = direct)
3. If spawn → spawn with session thread + appropriate runtime + generic label
4. If direct → execute and respond now
5. Result arrives via push → report to user
6. If result is significant → write to MEMORY.md or daily log
7. Self-check: is typing indicator still showing?

---

Key Insight

"Never block" is the rule. "Never execute" is a misreading of the rule — fast operations should be direct because they do not block. The typing indicator is the visible signal: if it disappears, something is blocking.

---

Privacy Notes

All examples in this skill use generic placeholders only. No specific project names, IPs, hostnames, user names, service names, or AI names appear in any example. This protects both operational security and privacy.