kas signal

Inspect and process agent lifecycle signals. Signals are the primary mechanism by which agents notify kasmos that a lifecycle phase is complete.

kas signal <subcommand> [flags]

Alias: kas sig

signal types

signal type	payload	description
planner_finished	optional JSON or text	planner agent finished writing the plan
implement_finished	optional JSON or text	all coder agents finished implementation
review_approved	optional JSON or text	reviewer approved the implementation; triggers reviewing → verifying when auto_readiness_review = true, otherwise reviewing → done
review_changes_requested	optional JSON or text	reviewer requested changes
verify_approved	optional JSON or text	master agent approved during verifying (→ done). Only valid while task is in verifying status. The daemon never writes a verify_approved signal row itself — see verify_failed below for loop-cap handling.
verify_failed	optional JSON or text	master agent requested changes during verifying (→ implementing). Only valid while task is in verifying status. When readiness_max_verify_cycles is reached, the processor consumes this signal row but applies the verifying → done transition directly instead of verifying → implementing; no new verify_approved signal row is created, and the verify_failed row is still marked processed.
implement_task_finished	{"wave_number": N, "task_number": N}	a single coder task in a wave finished
implement_wave	{"wave_number": N}	a full wave finished
elaborator_finished	(none)	architect agent finished enriching the plan
architect_finished	(none)	CLI alias accepted for elaborator_finished (stored as elaborator_finished in the gateway)

Deprecated aliases: readiness_approved → verify_approved (aliases: readiness-approved, master_approved); readiness_changes_requested → verify_failed (aliases: readiness-changes, readiness-changes-requested). These are accepted and canonicalized at ingress — use verify_approved / verify_failed in new automation.

payload rules

• FSM signals (planner_finished, implement_finished, review_approved, review_changes_requested, verify_approved, verify_failed): payload is optional. If provided and valid JSON, it is stored verbatim. Plain text is wrapped as {"body": "..."}.
• implement_task_finished: payload is required and must be JSON containing integer fields wave_number and task_number.
• implement_wave: payload is required and must be JSON containing an integer wave_number.
• elaborator_finished / architect_finished: payload must be empty.

subcommands

emit

Emit a signal into the gateway database. This is the primary entrypoint for agents to signal completion of a lifecycle phase.

kas signal emit <signal-type> <plan-file> [--payload <json>]

# signal that planning finished
kas signal emit planner_finished my-feature

# signal that a single task in a wave finished
kas signal emit implement_task_finished my-feature \
  --payload '{"wave_number": 2, "task_number": 3}'

# signal that an entire wave finished
kas signal emit implement_wave my-feature \
  --payload '{"wave_number": 2}'

# signal implementation complete
kas signal emit implement_finished my-feature

# signal that the architect/elaborator finished (both names accepted)
kas signal emit elaborator_finished my-feature
kas signal emit architect_finished my-feature

flag	description
--payload	optional JSON payload (required for implement_task_finished and implement_wave)

The signal is inserted as a pending row in the SQLite gateway database (signals table). The daemon picks it up and applies the corresponding FSM transition. kas signal process is only for the filesystem compatibility path under .kasmos/signals/.

---

list

List all pending signals in the .kasmos/signals/ directory.

kas signal list

kas signal list
# planner_finished              my-feature
# implement_wave                my-feature  (wave 2)

Scans three signal categories:

• FSM event signals (e.g. implement-finished-my-feature)
• Wave signals (e.g. implement-wave-2-my-feature)
• Elaboration signals (e.g. elaborator-finished-my-feature)

Prints no pending signals when the directory is empty or missing.

---

process

Process pending signals and apply FSM transitions.

kas signal process [--once]

# continuous polling loop (every 5 seconds, ctrl-c to stop)
kas signal process

# process one batch and exit
kas signal process --once

flag	description
--once	process a single batch of signals and exit instead of running the polling loop

Processing behavior:

• Each signal is moved to a processing/ subdirectory atomically before the FSM transition is applied (prevents double-processing after crashes).
• If the plan file is not found in the task store, the signal is dead-lettered into failed/ with a .reason file.
• If the FSM transition fails (e.g. wrong state), the signal is also dead-lettered.
• Wave and elaboration signals are consumed atomically without FSM transitions (they are handled by the TUI orchestrator and daemon).
• In-flight signals from a previous crashed run are recovered automatically from processing/ on startup.

---

filesystem signal files

The .kasmos/signals/ directory exists as runtime plumbing and a compatibility layer — not as the normal user workflow. kas signal list and kas signal process scan this directory, and kas task implement writes wave signal files here so the TUI orchestrator can pick them up. The daemon bridges any filesystem sentinels it finds into the DB gateway automatically.

Agents and users should use kas signal emit for day-to-day signaling. The filesystem signals directory is an implementation detail and should not be used directly.

File naming conventions (for reference):

• FSM signals: <event>-<plan-file> (hyphens replace underscores in event names)
• Wave signals: implement-wave-<N>-<plan-file>
• Elaboration signals: elaborator-finished-<plan-file>