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

Signals describe lifecycle progress only. Permission and resource-control behavior for any agent spawned as a result of a signal is resolved later by the daemon or tui from repo config. [agents.<role>].permission_default becomes SkipPermissions, and [resources] becomes the ResourceControls policy passed to the session runtime.

signal types

signal type	payload	description
planner_finished	optional JSON or text	legacy/manual planner completion; in multi-planner mode the processor applies this transition internally after all drafts finish
planner_draft_finished	{"planner_id": "profile"}	gateway-only signal emitted by each draft-mode planner listed in [orchestration].planners
implement_start	optional JSON or text	starts architect or wave execution after a planned task enters implementing; task-transition handlers emit it with {"fsm_applied":true}
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	{"reviewed_sha":"<full-head-sha>","reviewed_base_sha":"<default-branch-sha>"}	approve during verifying (→ done). Both SHAs must still match the reviewed branch and default-branch snapshots. Manual recovery resolves and submits the same proof.
verify_failed	optional JSON or text	master agent requested changes during verifying (→ implementing). Only valid while task is in verifying status. A failed verdict is never promoted to approval.
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
retry_wave	(none)	recovery signal that replaces stale agents for the active wave and re-runs only unresolved tasks; completed tasks remain complete
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.

After terminal approval, the processor may dispatch automatic PR creation as a separate idempotent action. That action does not create another signal row; its persisted latest outcome, attempt count, and PR URL live on the task entry. Successful created and adopted outcomes are retained for observability rather than cleared.

Planner drafts: planner_draft_finished is not an FSM event and has no filesystem sentinel form. It is a gateway-only coordination signal for multi-planner mode. The processor aggregates one signal per configured planner profile and internally advances planning when all expected drafts are done. Keep planner_finished for legacy single-planner runs and manual recovery.

payload rules

• FSM signals (planner_finished, implement_start, 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": "..."}.
• planner_draft_finished: payload is required and must be JSON containing a non-empty string field planner_id that matches the configured planner profile name.
• 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.
• retry_wave: payload is optional and ignored; the daemon reconstructs the wave number and completed-task set from persisted task state.
• elaborator_finished / architect_finished: payload must be empty.
• verify_approved: gateway callers must provide non-empty reviewed_sha and reviewed_base_sha values from the master prompt. kas task recover <plan> verify-approved resolves the current branch and default-branch SHAs and emits the same bound payload. Gateway-supplied origin and fsm_applied fields never establish trusted provenance. The internal auto path does not come from gateway payloads.

If a PR or merge gate later detects that either bound SHA is stale, Kasmos clears the approval and applies verification_stale, reopening a done task in verifying for a fresh master pass.

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 draft-mode planner finished
kas signal emit planner_draft_finished my-feature \
  --payload '{"planner_id": "planner_gpt"}'

# 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 planner_draft_finished, 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>