@sayknow-cli/coding-agent 0.2.4 → 0.2.5

package/src/defaults/skc/skills/ralplan/SKILL.md

@@ -23,7 +23,7 @@ Ralplan is the consensus planning workflow. It triggers iterative planning with
 - `--deliberate`: Forces deliberate mode for high-risk work. Adds pre-mortem (3 scenarios) and expanded test planning (unit/integration/e2e/observability). Without this flag, deliberate mode can still auto-enable when the request explicitly signals high risk (auth/security, migrations, destructive changes, production incidents, compliance/PII, public API breakage).
 - `--architect openai-code`: Use OpenAI code for the Architect pass when OpenAI code CLI is available. Otherwise, briefly note the fallback and keep the default SKC Architect review.
 - `--critic openai-code`: Use OpenAI code for the Critic pass when OpenAI code CLI is available. Otherwise, briefly note the fallback and keep the default SKC Critic review.
-- `--write --stage <type> --stage_n <N> --artifact <markdown file path or markdown string>`: Native artifact write path persisting Planner, Architect, Critic, revision, ADR, and final pending-approval plan markdown under `.skc/plans/ralplan/<run-id>/`. Use this instead of editing `.skc/` files directly.
+- `--write --stage <type> --stage_n <N> --artifact <markdown file path or markdown string>`: Native artifact write path persisting Planner, Architect, Critic, revision, ADR, and final pending-approval plan markdown under `.skc/_session-{sessionid}/plans/ralplan/<run-id>/`. Use this instead of editing `.skc/` files directly.
 
 ## Usage with interactive mode
 
@@ -31,6 +31,10 @@ Ralplan is the consensus planning workflow. It triggers iterative planning with
 /skill:ralplan --interactive "task description"
 ```
 
+## Corrupt current-session state recovery
+
+When ralplan detects its own current-session state is corrupt, tampered, unreadable, or stale on resume, run `skc state clear --force --mode ralplan` before reseeding or restarting. Scope the clear to the current session via `--session-id`, the command payload, or `SKC_SESSION_ID`; it clears only ralplan state for that session and never clears other skills or sessions.
+
 ## Behavior
 
 ## Planning/Execution Boundary
@@ -43,7 +47,9 @@ Planning artifacts and stage handoffs MUST be persisted through the ralplan CLI
 skc ralplan --write --stage <type> --stage_n <N> --artifact "markdown file path or markdown string"
 ```
 
-Use stage values that match the producer or artifact kind, such as `planner`, `architect`, `critic`, `revision`, `adr`, or `final`. Increment `--stage_n` for each consensus-loop pass. The `--artifact` value may be either a markdown file path prepared outside `.skc/` for ingestion or the markdown content string itself. The native `--write` handler persists markdown under `.skc/plans/ralplan/<run-id>/stage-<NN>-<stage>.md`, maintains an `index.jsonl` audit log, and for `final` stages additionally writes a `pending-approval.md` copy. Direct `write`, `edit`, or `ast_edit` calls against `.skc/specs`, `.skc/plans`, `.skc/state`, or any other `.skc/` path are forbidden unless an explicit force override is active.
+Use stage values that match the producer or artifact kind, such as `planner`, `architect`, `critic`, `revision`, `adr`, or `final`. Increment `--stage_n` for each consensus-loop pass. The `--artifact` value may be either a markdown file path prepared outside `.skc/` for ingestion or the markdown content string itself. The native `--write` handler persists markdown under `.skc/_session-{sessionid}/plans/ralplan/<run-id>/stage-<NN>-<stage>.md`, maintains an `index.jsonl` audit log, and for `final` stages additionally writes a `pending-approval.md` copy. Direct `write`, `edit`, or `ast_edit` calls against `.skc/_session-{sessionid}/specs`, `.skc/_session-{sessionid}/plans`, `.skc/_session-{sessionid}/state`, or any other `.skc/` path are forbidden unless an explicit force override is active.
+
+While ralplan is active it is a pre-approval planning phase: product-code mutation tools (`write`/`edit`/`ast_edit`) and product-mutating `bash` (e.g. `tee src/...`, redirects into the project tree) are blocked, exactly like deep-interview. Prefer passing the `--artifact` markdown **inline** (the content string) so no scratch file is needed; this is mandatory for restricted role agents (see below). Only the leader, and only when an artifact is too large to pass inline, may stage it as a file in a system temp directory (`os.tmpdir()`/`$TMPDIR`, `/tmp`, `/var/tmp`) outside the project tree and pass that path — never write scratch files into the repo or `.skc/`. Product code is mutated only after the plan is approved and execution begins.
 
 Restricted read-only role agents (`planner`, `architect`, and `critic`) must pass markdown content directly in `--artifact`; their restricted bash environment intentionally disables artifact file-path ingestion so a verdict command cannot persist arbitrary file contents.
 
@@ -74,7 +80,7 @@ The consensus workflow:
    d. Return to Critic evaluation
    e. Repeat this loop until Critic returns `APPROVE` or 5 iterations are reached
    f. If 5 iterations are reached without `APPROVE`, present the best version to the user
-6. On Critic approval, mark the plan `pending approval` unless explicit execution approval has already been captured, persist the ADR/final plan via `skc ralplan --write --stage final --stage_n <N> --artifact "..."`, and do not directly edit `.skc/plans`. *(--interactive only)* If `--interactive` is set, use the `ask` tool to present the plan with approval options (Approve execution via ultragoal (Recommended) / Approve execution via team (only when tmux-based interactive worker parallelization is required) / Compact then return for execution approval / Request changes / Reject). Final plan must include ADR (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups). Otherwise, output the final plan and stop before any mutation or delegation.
+6. On Critic approval, mark the plan `pending approval` unless explicit execution approval has already been captured, persist the ADR/final plan via `skc ralplan --write --stage final --stage_n <N> --artifact "..."`, and do not directly edit `.skc/_session-{sessionid}/plans`. *(--interactive only)* If `--interactive` is set, use the `ask` tool to present the plan with approval options (Approve execution via ultragoal (Recommended) / Approve execution via team (only when tmux-based interactive worker parallelization is required) / Compact then return for execution approval / Request changes / Reject). Final plan must include ADR (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups). Otherwise, output the final plan and stop before any mutation or delegation.
 7. *(--interactive only)* User chooses: Approve ultragoal execution (recommended), Approve team execution (tmux parallelization only), Request changes, or Reject
 8. *(--interactive only)* On approval: invoke `/skill:ultragoal` for execution by default; invoke `/skill:team` only when the user explicitly needs tmux-based interactive worker parallelization -- never implement directly
 
@@ -84,7 +90,7 @@ The consensus workflow:
    skc state ralplan write --input '{"current_phase":"handoff"}' --json
    ```
 
-   The skill tool then dispatches the execution skill same-turn and runs `skc state ralplan handoff --to <team|ultragoal> --json` in-process to atomically demote ralplan, promote the callee, and sync both `skill-active-state.json` files. You do not need to run the handoff verb yourself.
+   The skill tool then dispatches the execution skill same-turn and runs `skc state ralplan handoff --to <team|ultragoal> --json` in-process to atomically demote ralplan, promote the callee, and sync `.skc/_session-{sessionid}/state/skill-active-state.json`. You do not need to run the handoff verb yourself.
 
 > **Important:** Steps 3 and 4 MUST run sequentially. Do NOT issue both agent Task calls in the same parallel batch. Always await the Architect result before issuing the Critic Task.
 

package/src/defaults/skc/skills/team/SKILL.md

@@ -7,10 +7,14 @@ source: "forked from upstream team skill and rebranded for SKC"
 
 # Team Skill
 
-`$team` is the tmux-based multi-worker execution mode for SKC. It starts real SKC worker CLI sessions by splitting the current tmux leader window and coordinates them through `.skc/state/team/...` files plus CLI team interop (`skc team api ...`) and state files.
+`$team` is the tmux-based multi-worker execution mode for SKC. It starts real SKC worker CLI sessions by splitting the current tmux leader window and coordinates them through `.skc/_session-{sessionid}/state/team/...` files plus CLI team interop (`skc team api ...`) and state files.
 
 This skill is operationally sensitive. Treat it as an operator workflow, not a generic prompt pattern. In SKC App or plain outside-tmux sessions, do not present `$team` / `skc team` as directly available; launch SKC CLI from shell first, or stay on the nearest app-safe surface until the user explicitly wants the tmux runtime.
 
+## Corrupt current-session state recovery
+
+When team detects its own current-session state is corrupt, tampered, unreadable, or stale on resume, run `skc state clear --force --mode team` before reseeding or restarting. Scope the clear to the current session via `--session-id`, the command payload, or `SKC_SESSION_ID`; it clears only team state for that session and never clears other skills or sessions.
+
 ## Team vs Native Subagents
 
 - Use **SKC native subagents** for bounded, in-session parallelism where one leader thread can fan out a few independent subtasks and wait for them directly.
@@ -62,9 +66,9 @@ requiring a separate linked execution loop up front. SKC team supports current-w
 
 ### Team + Ultragoal bridge
 
-Use `$ultragoal` for durable leader-owned goal/ledger tracking and `$team` for parallel visible tmux execution lanes. When Team is launched with an active `.skc/ultragoal/goals.json`, worker task/status context may include leader-owned Ultragoal context: `.skc/ultragoal/goals.json`, `.skc/ultragoal/ledger.jsonl`, the active goal id, SKC goal mode, and the `fresh_leader_goal_get_required` checkpoint policy.
+Use `$ultragoal` for durable leader-owned goal/ledger tracking and `$team` for parallel visible tmux execution lanes. When Team is launched with an active `.skc/_session-{sessionid}/ultragoal/goals.json`, worker task/status context may include leader-owned Ultragoal context: `.skc/_session-{sessionid}/ultragoal/goals.json`, `.skc/_session-{sessionid}/ultragoal/ledger.jsonl`, the active goal id, SKC goal mode, and the `fresh_leader_goal_get_required` checkpoint policy.
 
-Workers provide task status and verification evidence only. They do not own Ultragoal goal state, create worker ledgers, mutate `.skc/ultragoal`, auto-launch Team from Ultragoal, or perform hidden SKC goal mutation. Workers must not run `skc ultragoal checkpoint`; checkpoint authority stays with the leader after worker tasks are terminal. Ultragoal does not auto-launch Team and performs no hidden goal mutation. The leader uses terminal Team evidence plus a fresh `goal({"op":"get"})` snapshot and strict quality gate to run `skc ultragoal checkpoint --goal-id <id> --status complete --evidence "<team evidence mentioning .skc/ultragoal and <id>>" --skc-goal-json <fresh-goal-get-json-or-path> --quality-gate-json <quality-gate-json-or-path>`.
+Workers provide task status and verification evidence only. They do not own Ultragoal goal state, create worker ledgers, mutate `.skc/_session-{sessionid}/ultragoal`, auto-launch Team from Ultragoal, or perform hidden SKC goal mutation. Workers must not run `skc ultragoal checkpoint`; checkpoint authority stays with the leader after worker tasks are terminal. Ultragoal does not auto-launch Team and performs no hidden goal mutation. The leader uses terminal Team evidence plus a fresh `goal({"op":"get"})` snapshot and strict quality gate to run `skc ultragoal checkpoint --goal-id <id> --status complete --evidence "<team evidence mentioning .skc/_session-{sessionid}/ultragoal and <id>>" --skc-goal-json <fresh-goal-get-json-or-path> --quality-gate-json <quality-gate-json-or-path>`.
 
 ### Worker command override
 
@@ -107,12 +111,12 @@ Before launching `skc team`, require a grounded context snapshot:
    - constraints
    - unknowns/open questions
    - likely codebase touchpoints
-4. If ambiguity remains high, run `explore` first for brownfield facts, then run `$deep-interview --quick <task>` before team launch.
+4. If ambiguity remains high, gather brownfield facts with focused repo inspection or a canonical read-only role agent first, then run `$deep-interview --quick <task>` before team launch.
 5. If current correctness depends on official docs, version-aware framework guidance, best practices, or external dependency behavior, auto-delegate `researcher` as an evidence lane before or alongside worker launch instead of relying on repo-local recall alone.
 
 Do not start the worker pane until this gate is satisfied; if forced to proceed quickly, state explicit scope/risk limitations in the launch report.
 
-For simple read-only brownfield lookups during intake, follow active session guidance: when `USE_SKC_EXPLORE_CMD` is enabled, prefer `skc explore` with narrow, concrete prompts; otherwise use the richer normal explore path and fall back normally if `skc explore` is unavailable.
+For simple read-only brownfield lookups during intake, use narrow repo inspection first; for broader mapping, delegate to `planner` or `architect` with a concrete fact-finding assignment.
 
 ## Follow-up Staffing Contract
 
@@ -141,19 +145,19 @@ When `$team` is used as a follow-up mode from ralplan, carry forward the approve
 1. Parse args (`N`, `agent-type`, task), default to 3 workers, and cap workers at 20.
 2. Non-dry-run: detect the current tmux leader context with `display-message -p "#S:#I #{pane_id}"` before creating state or worktrees.
 3. Initialize team state:
-   - `.skc/state/team/<team>/config.json`
-   - `.skc/state/team/<team>/manifest.v2.json`
-   - `.skc/state/team/<team>/tasks/task-*.json` (one per explicit lane section, otherwise one worker-owned compatibility task per worker)
-   - `.skc/state/team/<team>/mailbox/worker-1.json`
-   - `.skc/state/team/<team>/workers/<worker>/status.json`
-   - `.skc/state/team/<team>/workers/<worker>/lifecycle.json`
-   - `.skc/state/team/<team>/workers/<worker>/heartbeat.json`
+   - `.skc/_session-{sessionid}/state/team/<team>/config.json`
+   - `.skc/_session-{sessionid}/state/team/<team>/manifest.v2.json`
+   - `.skc/_session-{sessionid}/state/team/<team>/tasks/task-*.json` (one per explicit lane section, otherwise one worker-owned compatibility task per worker)
+   - `.skc/_session-{sessionid}/state/team/<team>/mailbox/worker-1.json`
+   - `.skc/_session-{sessionid}/state/team/<team>/workers/<worker>/status.json`
+   - `.skc/_session-{sessionid}/state/team/<team>/workers/<worker>/lifecycle.json`
+   - `.skc/_session-{sessionid}/state/team/<team>/workers/<worker>/heartbeat.json`
 4. Resolve the worker command from `SKC_TEAM_WORKER_COMMAND` or the active `skc` entrypoint.
 5. Split the current tmux window like SKC team: worker 1 is split horizontally to the right of the leader, workers 2..N are vertically stacked in the right column, then `select-layout main-vertical` and `main-pane-width` keep leader-left/worker-right at roughly 50/50.
 6. Launch the worker with:
    - `SKC_TEAM_NAME=<team>`
    - `SKC_TEAM_WORKER_ID=worker-1`
-   - `SKC_TEAM_STATE_ROOT=<leader-cwd>/.skc/state/team`
+   - `SKC_TEAM_STATE_ROOT=<leader-cwd>/.skc/_session-{sessionid}/state/team`
    - optional `SKC_TEAM_WORKTREE_PATH=<path>` when worktree mode is active
 7. Automatically integrate worker worktree commits during leader monitoring:
    - dirty worker worktrees are auto-checkpointed before integration
@@ -216,7 +220,7 @@ Semantics:
 - `list`: pure read path; lists known teams without integrating worker commits.
 - API/read-only snapshot operations are pure unless explicitly documented as a monitor path.
 - `claim-task`: mutating task path; before granting a new claim, it recovers expired claims and rejects claims from workers already classified as not live.
-- `shutdown`: writes per-worker graceful `shutdown-request.json`, moves lifecycle through `draining` to `stopped`, kills the recorded worker pane when it still belongs to the stored tmux target, removes clean created worktrees, marks worker runtime status stopped, and sets phase from task, lifecycle, and integration state: `complete` only when all tasks have verified `completion_evidence`, every worker has matching graceful shutdown lifecycle evidence, and no integration request/conflict is pending; `awaiting_integration` when tasks and lifecycle are complete but leader integration still requires action; `failed` when tasks failed/blocked or completed tasks lack valid evidence; and `cancelled` when work remains pending or in progress. It preserves `.skc/state/team/<team>` as evidence.
+- `shutdown`: writes per-worker graceful `shutdown-request.json`, moves lifecycle through `draining` to `stopped`, kills the recorded worker pane when it still belongs to the stored tmux target, removes clean created worktrees, marks worker runtime status stopped, and sets phase from task, lifecycle, and integration state: `complete` only when all tasks have verified `completion_evidence`, every worker has matching graceful shutdown lifecycle evidence, and no integration request/conflict is pending; `awaiting_integration` when tasks and lifecycle are complete but leader integration still requires action; `failed` when tasks failed/blocked or completed tasks lack valid evidence; and `cancelled` when work remains pending or in progress. It preserves `.skc/_session-{sessionid}/state/team/<team>` as evidence.
 
 ## Data Plane and Control Plane
 
@@ -228,26 +232,26 @@ Semantics:
 
 ### Data Plane
 
-- `.skc/state/team/<team>/config.json`
-- `.skc/state/team/<team>/manifest.v2.json`
-- `.skc/state/team/<team>/phase.json`
-- `.skc/state/team/<team>/events.jsonl`
-- `.skc/state/team/<team>/trace.jsonl`
-- `.skc/state/team/<team>/trace-errors.jsonl`
-- `.skc/state/team/<team>/telemetry.jsonl`
-- `.skc/state/team/<team>/monitor-snapshot.json`
-- `.skc/state/team/<team>/integration-report.md`
-- `.skc/state/team/<team>/tasks/task-1.json` (includes structured `completion_evidence` after completed transitions)
-- `.skc/state/team/<team>/mailbox/worker-1/<message-id>.json`
-- `.skc/state/team/<team>/mailbox/worker-1.json` (legacy compatibility view)
-- `.skc/state/team/<team>/notifications/<notification-id>.json`
-- `.skc/state/team/<team>/workers/<worker>/startup-ack.json`
-- `.skc/state/team/<team>/workers/<worker>/status.json`
-- `.skc/state/team/<team>/workers/<worker>/lifecycle.json`
-- `.skc/state/team/<team>/workers/<worker>/heartbeat.json`
-- `.skc/state/team/<team>/workers/<worker>/shutdown-request.json`
-- `.skc/state/team/<team>/workers/<worker>/nudges/<fingerprint>.json`
-- `.skc/reports/team-commit-hygiene/<team>.ledger.json`
+- `.skc/_session-{sessionid}/state/team/<team>/config.json`
+- `.skc/_session-{sessionid}/state/team/<team>/manifest.v2.json`
+- `.skc/_session-{sessionid}/state/team/<team>/phase.json`
+- `.skc/_session-{sessionid}/state/team/<team>/events.jsonl`
+- `.skc/_session-{sessionid}/state/team/<team>/trace.jsonl`
+- `.skc/_session-{sessionid}/state/team/<team>/trace-errors.jsonl`
+- `.skc/_session-{sessionid}/state/team/<team>/telemetry.jsonl`
+- `.skc/_session-{sessionid}/state/team/<team>/monitor-snapshot.json`
+- `.skc/_session-{sessionid}/state/team/<team>/integration-report.md`
+- `.skc/_session-{sessionid}/state/team/<team>/tasks/task-1.json` (includes structured `completion_evidence` after completed transitions)
+- `.skc/_session-{sessionid}/state/team/<team>/mailbox/worker-1/<message-id>.json`
+- `.skc/_session-{sessionid}/state/team/<team>/mailbox/worker-1.json` (legacy compatibility view)
+- `.skc/_session-{sessionid}/state/team/<team>/notifications/<notification-id>.json`
+- `.skc/_session-{sessionid}/state/team/<team>/workers/<worker>/startup-ack.json`
+- `.skc/_session-{sessionid}/state/team/<team>/workers/<worker>/status.json`
+- `.skc/_session-{sessionid}/state/team/<team>/workers/<worker>/lifecycle.json`
+- `.skc/_session-{sessionid}/state/team/<team>/workers/<worker>/heartbeat.json`
+- `.skc/_session-{sessionid}/state/team/<team>/workers/<worker>/shutdown-request.json`
+- `.skc/_session-{sessionid}/state/team/<team>/workers/<worker>/nudges/<fingerprint>.json`
+- `.skc/_session-{sessionid}/reports/team-commit-hygiene/<team>.ledger.json`
 
 ## Team Mutation Interop (CLI-first)
 
@@ -285,10 +289,10 @@ SKC ports team-mode concepts from `../../oh-my-codex`, not code or OMX/Codex-spe
 
 | Concept | SKC-native equivalent |
 |---------|-----------------------|
-| Worker identity/inbox/mailbox paths | `.skc/state/team/<team>/workers/<worker>/identity.json`, `inbox.md`, and per-message mailbox records under `.skc/state/team/<team>/mailbox/<worker>/`. |
+| Worker identity/inbox/mailbox paths | `.skc/_session-{sessionid}/state/team/<team>/workers/<worker>/identity.json`, `inbox.md`, and per-message mailbox records under `.skc/_session-{sessionid}/state/team/<team>/mailbox/<worker>/`. |
 | Startup ACK | `skc team api worker-startup-ack`, persisted as `workers/<worker>/startup-ack.json`. |
 | Claim-safe lifecycle APIs | `claim-task`, `transition-task-status`, and `release-task-claim` with worker ownership and claim-token guards. |
-| Delivery states and deferred pane attempts | Native notification records under `.skc/state/team/<team>/notifications/` with `pending`, `sent`, `queued`, `deferred`, `failed`, `delivered`, and `acknowledged` states. |
+| Delivery states and deferred pane attempts | Native notification records under `.skc/_session-{sessionid}/state/team/<team>/notifications/` with `pending`, `sent`, `queued`, `deferred`, `failed`, `delivered`, and `acknowledged` states. |
 | Non-destructive leader nudges | Lifecycle nudge records under `workers/<worker>/nudges/`; SKC suggests inspection/relaunch but never auto-kills or auto-relaunches workers. |
 
 Forbidden assumptions: do not copy OMX paths, Codex notify payload formats, OMX process names, or source code directly. Keep tmux as the current runtime; native split-worker TUI remains roadmap-only.
@@ -300,7 +304,7 @@ Worker protocol:
 - Claim pending work with `claim-task`.
 - Transition the task to `completed`, `failed`, or `blocked` with `transition-task-status`, including claim token and evidence for completion.
 - Commit or leave worktree changes in the worker worktree; the leader `monitor`/`resume` path will auto-checkpoint dirty worktrees and integrate committed history where possible.
-- Record implementation/verification evidence in normal task output and state files; leader integration/conflict notifications are delivered through `.skc/state/team/<team>/mailbox/leader-fixed.json`.
+- Record implementation/verification evidence in normal task output and state files; leader integration/conflict notifications are delivered through `.skc/_session-{sessionid}/state/team/<team>/mailbox/leader-fixed.json`.
 
 ## Environment Knobs
 
@@ -312,7 +316,7 @@ Useful runtime env vars:
 - `SKC_TEAM_WORKER_COMMAND`
   - worker command override (default resolves to active SKC entrypoint or `skc`)
 - `SKC_TEAM_STATE_ROOT`
-  - team state root override (default `<cwd>/.skc/state/team`)
+  - team state root override (default `<cwd>/.skc/_session-{sessionid}/state/team`)
 
 ## Failure Modes and Diagnosis
 
@@ -325,18 +329,18 @@ Operator note (important for SKC panes):
 
 - **Outside tmux:** non-dry-run launch fails before team state or worktrees are created. Start `skc team` from an attached tmux leader pane.
 - **Split failure:** startup records a failed phase if state was already initialized, rolls back created worktrees, and never kills the leader tmux session.
-- **Worker API ENOENT:** team state is missing or `SKC_TEAM_STATE_ROOT` points somewhere else. Check `.skc/state/team/<team>/` before assuming worker failure.
+- **Worker API ENOENT:** team state is missing or `SKC_TEAM_STATE_ROOT` points somewhere else. Check `.skc/_session-{sessionid}/state/team/<team>/` before assuming worker failure.
 - **Stale pane on shutdown:** shutdown only kills a recorded worker pane when it still belongs to the stored `tmux_target` and is not the leader pane. Stale panes outside that target require manual inspection.
-- **Integration conflict:** `skc team monitor <team>` / `resume` aborts the failing merge, cherry-pick, or worker rebase; `skc team status <team>` is read-only inspection. Inspect `.skc/state/team/<team>/integration-report.md`, `.skc/state/team/<team>/events.jsonl`, `.skc/state/team/<team>/mailbox/leader-fixed.json`, and `.skc/reports/team-commit-hygiene/<team>.ledger.json`.
+- **Integration conflict:** `skc team monitor <team>` / `resume` aborts the failing merge, cherry-pick, or worker rebase; `skc team status <team>` is read-only inspection. Inspect `.skc/_session-{sessionid}/state/team/<team>/integration-report.md`, `.skc/_session-{sessionid}/state/team/<team>/events.jsonl`, `.skc/_session-{sessionid}/state/team/<team>/mailbox/leader-fixed.json`, and `.skc/_session-{sessionid}/reports/team-commit-hygiene/<team>.ledger.json`.
 
 ### Safe Manual Intervention (last resort)
 
 Use only after checking `skc team status <team>` and state evidence:
 
 1. Inspect team files:
-   - `.skc/state/team/<team>/config.json`
-   - `.skc/state/team/<team>/tasks/task-1.json`
-   - `.skc/state/team/<team>/mailbox/worker-1.json`
+   - `.skc/_session-{sessionid}/state/team/<team>/config.json`
+   - `.skc/_session-{sessionid}/state/team/<team>/tasks/task-1.json`
+   - `.skc/_session-{sessionid}/state/team/<team>/mailbox/worker-1.json`
 2. Capture pane tail to confirm current worker state:
    - `tmux capture-pane -t %<worker-pane> -p -S -120`
    - If a larger-tail read or bounded summary would help, prefer explicit opt-in inspection via `skc sparkshell --tmux-pane %<worker-pane> --tail-lines 400` before improvising extra tmux commands.
@@ -385,7 +389,7 @@ When operating this skill, provide concrete progress evidence:
 
 1. Team started line (`Team started: <name>`)
 2. tmux target and worker pane id
-3. task state from read-only `skc team status <team>`, mutating `skc team monitor <team>`, or `.skc/state/team/<team>/tasks/task-1.json`
+3. task state from read-only `skc team status <team>`, mutating `skc team monitor <team>`, or `.skc/_session-{sessionid}/state/team/<team>/tasks/task-1.json`
 4. shutdown outcome (`phase=complete`, worker status `stopped`) when the run is terminal; incomplete shutdowns must report `phase=cancelled`/`failed`, and integration-blocked shutdowns must report `phase=awaiting_integration`
 
 Do not claim success without file/pane evidence.
@@ -399,13 +403,13 @@ Use the `skc team ...` CLI as the supported team-launch surface. For automation,
 ### Supported current surfaces
 
 - **`skc team ...` CLI** — Primary method for interactive or automated team orchestration. Use this when you want direct tmux-pane visibility or a scriptable launch path.
-- **Team state files** — Inspect `.skc/state/team/<team>/` when you need status, task, or mailbox evidence after launch.
+- **Team state files** — Inspect `.skc/_session-{sessionid}/state/team/<team>/` when you need status, task, or mailbox evidence after launch.
 
 ### Cleanup distinction
 
 Two cleanup paths exist and must not be confused:
 
-- `team_cleanup` (**state-server**): Deletes team state **files** on disk (`.skc/state/team/<team>/`). Use after a team run is fully complete.
+- `team_cleanup` (**state-server**): Deletes team state **files** on disk (`.skc/_session-{sessionid}/state/team/<team>/`). Use after a team run is fully complete.
 - tmux/session cleanup: Use the documented `skc team` shutdown / cleanup flow when you need to stop the worker pane or clean up an interrupted run.
 
 ### Automation example
@@ -439,4 +443,4 @@ When the team task-set completes OR the user requests return to planning/persist
 skc state team write --input '{"current_phase":"handoff"}' --json
 ```
 
-The skill tool then dispatches `/skill:ralplan`, `/skill:deep-interview`, or `/skill:ultragoal` same-turn and runs `skc state team handoff --to <ralplan|deep-interview|ultragoal> --json` in-process to atomically demote team, promote the callee, and sync both `skill-active-state.json` files. You do not need to run the handoff verb yourself.
+The skill tool then dispatches `/skill:ralplan`, `/skill:deep-interview`, or `/skill:ultragoal` same-turn and runs `skc state team handoff --to <ralplan|deep-interview|ultragoal> --json` in-process to atomically demote team, promote the callee, and sync both `.skc/_session-{sessionid}/state/skill-active-state.json` files. You do not need to run the handoff verb yourself.

package/src/defaults/skc/skills/ultragoal/SKILL.md

@@ -11,14 +11,18 @@ Use when the user asks for `ultragoal`, `create-goals`, `complete-goals`, durabl
 
 ## Purpose
 
-`ultragoal` turns a brief into repo-native artifacts and then drives a SKC goal safely through the unified `goal` tool. New plans default to a stable pointer-style aggregate SKC goal for the whole durable plan in `.skc/ultragoal/goals.json`, including later accepted/appended stories under the original brief constraints, while SKC tracks G001/G002 story progress in the ledger. Ultragoal does not require any `/goal` slash-command between runs. For back-to-back ultragoal runs in one session/thread, call `goal({"op":"drop"})` only when `goal({"op":"get"})` still reports an active aggregate; then call `goal({"op":"create"})`. The goal tool stays armed across drop so the next create works in-session, and no slash-command cleanup exists or is required.
+`ultragoal` turns a brief into repo-native artifacts and then drives a SKC goal safely through the unified `goal` tool. New plans default to a stable pointer-style aggregate SKC goal for the whole durable plan in `.skc/_session-{sessionid}/ultragoal/goals.json`, including later accepted/appended stories under the original brief constraints, while SKC tracks G001/G002 story progress in the ledger. Ultragoal does not require any `/goal` slash-command between runs. For back-to-back ultragoal runs in one session/thread, call `goal({"op":"drop"})` only when `goal({"op":"get"})` still reports an active aggregate; then call `goal({"op":"create"})`. The goal tool stays armed across drop so the next create works in-session, and no slash-command cleanup exists or is required.
 
-- `.skc/ultragoal/brief.md`
-- `.skc/ultragoal/goals.json`
-- `.skc/ultragoal/ledger.jsonl` (checkpoint and structured steering audit events)
+- `.skc/_session-{sessionid}/ultragoal/brief.md`
+- `.skc/_session-{sessionid}/ultragoal/goals.json`
+- `.skc/_session-{sessionid}/ultragoal/ledger.jsonl` (checkpoint and structured steering audit events)
 
 Existing aggregate plans with the legacy enumerated objective are migrated to the stable pointer objective on read, persisted to `goals.json`, retained in `skcObjectiveAliases` for already-active hidden goal reconciliation, and audited with an `aggregate_objective_migrated` ledger entry.
 
+## Corrupt current-session state recovery
+
+When ultragoal detects its own current-session state is corrupt, tampered, unreadable, or stale on resume, run `skc state clear --force --mode ultragoal` before reseeding or restarting. Scope the clear to the current session via `--session-id`, the command payload, or `SKC_SESSION_ID`; it clears only ultragoal state for that session and never clears other skills or sessions.
+
 ## Always-used command examples
 
 Use these exact `skc ultragoal` commands before spending tool calls rediscovering syntax:
@@ -81,7 +85,7 @@ Use `goal({"op":"get"})` snapshots inside Ultragoal for ledger reconciliation. T
    - `skc ultragoal create-goals --brief-file <path>`
    - `cat <brief> | skc ultragoal create-goals --from-stdin`
    - `skc ultragoal create-goals --skc-goal-mode per-story --brief "<brief>"` only when one SKC goal context per story is explicitly preferred
-3. Inspect `.skc/ultragoal/goals.json` and refine if needed.
+3. Inspect `.skc/_session-{sessionid}/ultragoal/goals.json` and refine if needed.
 
 ## Complete goals
 
@@ -131,9 +135,9 @@ skc ultragoal steer --kind mark_blocked_superseded --goal-id G004 --evidence "Th
 
 Steering invariants:
 
-- Do not edit the aggregate goal objective, original brief constraints, quality gates, or completion status. The aggregate objective is a stable pointer to `.skc/ultragoal/goals.json` and `.skc/ultragoal/ledger.jsonl`, not an enumeration of initial goal ids.
-- Do not hard-delete goals, auto-complete work, weaken verification, or silently mutate `.skc/ultragoal`.
-- Accepted and rejected attempts append structured audit entries to `.skc/ultragoal/ledger.jsonl`.
+- Do not edit the aggregate goal objective, original brief constraints, quality gates, or completion status. The aggregate objective is a stable pointer to `.skc/_session-{sessionid}/ultragoal/goals.json` and `.skc/_session-{sessionid}/ultragoal/ledger.jsonl`, not an enumeration of initial goal ids.
+- Do not hard-delete goals, auto-complete work, weaken verification, or silently mutate `.skc/_session-{sessionid}/ultragoal`.
+- Accepted and rejected attempts append structured audit entries to `.skc/_session-{sessionid}/ultragoal/ledger.jsonl`.
 - Superseded goals remain in `goals.json` with steering metadata and are skipped for scheduling.
 - Blocked goals without replacements are skipped for scheduling but still block final completion until later explicit steering replaces or supersedes them.
 
@@ -152,18 +156,18 @@ When delegating with native subagents, an await timeout only limits the leader's
 
 If an Ultragoal request has no approved plan or consensus artifact, run `ralplan` first and preserve its PRD, test spec, role roster, and verification guidance in the Ultragoal ledger. Do not silently substitute ad-hoc execution for missing planning.
 
-The Ultragoal leader owns `.skc/ultragoal/goals.json` and `.skc/ultragoal/ledger.jsonl`. Role agents return implementation/review evidence; they do not checkpoint Ultragoal or mutate goal state.
+The Ultragoal leader owns `.skc/_session-{sessionid}/ultragoal/goals.json` and `.skc/_session-{sessionid}/ultragoal/ledger.jsonl`. Role agents return implementation/review evidence; they do not checkpoint Ultragoal or mutate goal state.
 
-For large subgoals with independent slices, the Ultragoal leader must spawn parallel `executor` subagents instead of doing serial solo work. Split only cleanly separable files/surfaces, give each executor bounded targets and acceptance criteria, and keep checkpoint ownership in the leader. Use `architect` / `critic` review lanes after integration; do not let worker agents mutate `.skc/ultragoal` or call goal tools.
+For large subgoals with independent slices, the Ultragoal leader must spawn parallel `executor` subagents instead of doing serial solo work. Split only cleanly separable files/surfaces, give each executor bounded targets and acceptance criteria, and keep checkpoint ownership in the leader. Use `architect` / `critic` review lanes after integration; do not let worker agents mutate `.skc/_session-{sessionid}/ultragoal` or call goal tools.
 
 ## Use Ultragoal and Team together
 
-Use ultragoal and team together for a durable Ultragoal story that benefits from one visible tmux worker session. Ultragoal remains leader-owned: `.skc/ultragoal/goals.json` stores the story plan and `.skc/ultragoal/ledger.jsonl` stores checkpoints. Team is the single-worker tmux execution engine and returns task/evidence status to the leader.
+Use ultragoal and team together for a durable Ultragoal story that benefits from one visible tmux worker session. Ultragoal remains leader-owned: `.skc/_session-{sessionid}/ultragoal/goals.json` stores the story plan and `.skc/_session-{sessionid}/ultragoal/ledger.jsonl` stores checkpoints. Team is the single-worker tmux execution engine and returns task/evidence status to the leader.
 
 The leader checkpoints Ultragoal from Team evidence with a fresh `goal({"op":"get"})` snapshot:
 
 ```sh
-skc ultragoal checkpoint --goal-id <id> --status complete --evidence "<team evidence mentioning .skc/ultragoal and <id>>" --skc-goal-json <fresh-goal-get-json-or-path> --quality-gate-json <quality-gate-json-or-path>
+skc ultragoal checkpoint --goal-id <id> --status complete --evidence "<team evidence mentioning .skc/_session-{sessionid}/ultragoal and <id>>" --skc-goal-json <fresh-goal-get-json-or-path> --quality-gate-json <quality-gate-json-or-path>
 ```
 
 Workers do not own ultragoal goal state, do not create worker ultragoal ledgers, and do not checkpoint Ultragoal. Workers must not run `skc ultragoal checkpoint`; checkpoint authority stays with the leader after worker tasks are terminal. Team launch remains explicit; Ultragoal does not auto-launch Team and performs no hidden goal mutation.
@@ -335,7 +339,7 @@ When the aggregate ultragoal is complete OR the user requests return to planning
 skc state ultragoal write --input '{"current_phase":"handoff"}' --json
 ```
 
-The skill tool then dispatches `/skill:ralplan` or `/skill:deep-interview` same-turn and runs `skc state ultragoal handoff --to <ralplan|deep-interview> --json` in-process to atomically demote ultragoal, promote the callee, and sync both `skill-active-state.json` files. You do not need to run the handoff verb yourself.
+The skill tool then dispatches `/skill:ralplan` or `/skill:deep-interview` same-turn and runs `skc state ultragoal handoff --to <ralplan|deep-interview> --json` in-process to atomically demote ultragoal, promote the callee, and sync both `.skc/_session-{sessionid}/state/skill-active-state.json` files. You do not need to run the handoff verb yourself.
 
 ## Constraints
 

package/src/exec/bash-executor.ts

@@ -66,7 +66,9 @@ export interface BashResult {
 const shellSessions = new Map<string, Shell>();
 const brokenShellSessions = new Set<string>();
 const retiringShellSessions = new Set<Shell>();
-const CANCEL_CLEANUP_WAIT_MS = 250;
+// Cover pi-shell's normal cancellation kill waves without turning a stalled
+// native cleanup into a multi-second JavaScript tool stall.
+const CANCEL_CLEANUP_WAIT_MS = 400;
 
 /** Number of persistent shell sessions currently retained (owner gauge). */
 export function getShellSessionCount(): number {

package/src/extensibility/custom-commands/loader.ts

@@ -12,7 +12,6 @@ import { getConfigDirs } from "../../config";
 import { execCommand } from "../../exec/exec";
 import * as typebox from "../typebox";
 import { GreenCommand } from "./bundled/ci-green";
-import { ReviewCommand } from "./bundled/review";
 import type {
 	CustomCommand,
 	CustomCommandAPI,
@@ -155,12 +154,6 @@ function loadBundledCommands(sharedApi: CustomCommandAPI): LoadedCustomCommand[]
 		command: new GreenCommand(sharedApi),
 		source: "bundled",
 	});
-	bundled.push({
-		path: "bundled:review",
-		resolvedPath: "bundled:review",
-		command: new ReviewCommand(sharedApi),
-		source: "bundled",
-	});
 
 	return bundled;
 }

package/src/extensibility/skc-plugins/injection.ts

@@ -1,3 +1,16 @@
+import { resolveSkcSessionForRead, SessionResolutionError } from "../../skc-runtime/session-resolution";
+
+async function resolveBoundarySessionId(cwd: string, sessionId?: string): Promise<string | undefined> {
+	const normalizedSessionId = sessionId?.trim();
+	if (normalizedSessionId) return normalizedSessionId;
+	try {
+		return (await resolveSkcSessionForRead(cwd, { envSessionId: process.env.SKC_SESSION_ID })).skcSessionId;
+	} catch (error) {
+		if (error instanceof SessionResolutionError && error.code === "no_session") return undefined;
+		throw error;
+	}
+}
+
 import { readVisibleSkillActiveState } from "../../skill-state/active-state";
 import { initialPhaseForSkill } from "../../skill-state/initial-phase";
 import { readActiveSubskillsForParent } from "./state";
@@ -35,7 +48,8 @@ export async function resolveCurrentPhaseForParent(input: {
 	const explicitPhase = input.explicitPhase?.trim();
 	if (explicitPhase) return explicitPhase;
 
-	const state = await readVisibleSkillActiveState(input.cwd, input.sessionId);
+	const resolvedSessionId = await resolveBoundarySessionId(input.cwd, input.sessionId);
+	const state = resolvedSessionId ? await readVisibleSkillActiveState(input.cwd, resolvedSessionId) : null;
 	const persistedPhase = state?.active_skills?.find(entry => entry.skill === input.parent)?.phase?.trim();
 	if (persistedPhase) return persistedPhase;
 
@@ -54,9 +68,10 @@ export async function buildSubskillInjection(input: {
 	activation?: LoadedSubskillActivation;
 	currentPhase?: string;
 }): Promise<{ block: string; details?: LoadedSubskillActivation } | null> {
+	const resolvedSessionId = await resolveBoundarySessionId(input.cwd, input.sessionId);
 	const resolvedPhase = await resolveCurrentPhaseForParent({
 		cwd: input.cwd,
-		sessionId: input.sessionId,
+		sessionId: resolvedSessionId,
 		parent: input.skillName,
 		explicitPhase: input.currentPhase,
 	});
@@ -67,9 +82,11 @@ export async function buildSubskillInjection(input: {
 		return { block: wrapSubskillBlock(directActivation, body), details: directActivation };
 	}
 
+	if (!resolvedSessionId) return null;
+
 	const [entry] = await readActiveSubskillsForParent({
 		cwd: input.cwd,
-		sessionId: input.sessionId,
+		sessionId: resolvedSessionId,
 		parent: input.skillName,
 		phase: resolvedPhase,
 	});
@@ -96,9 +113,11 @@ export async function buildAgentSubskillInjection(input: {
 }): Promise<string> {
 	if (!(SKC_SUBSKILL_PARENT_AGENTS as readonly string[]).includes(input.agentName)) return "";
 
+	const resolvedSessionId = await resolveBoundarySessionId(input.cwd, input.sessionId);
+	if (!resolvedSessionId) return "";
 	const entries = await readActiveSubskillsForParent({
 		cwd: input.cwd,
-		sessionId: input.sessionId,
+		sessionId: resolvedSessionId,
 		parent: input.agentName,
 		phase: "prompt",
 	});

package/src/extensibility/skc-plugins/state.ts

@@ -1,3 +1,16 @@
+import { resolveSkcSessionForRead, SessionResolutionError } from "../../skc-runtime/session-resolution";
+
+async function resolveBoundarySessionId(cwd: string, sessionId?: string): Promise<string | undefined> {
+	const normalizedSessionId = sessionId?.trim();
+	if (normalizedSessionId) return normalizedSessionId;
+	try {
+		return (await resolveSkcSessionForRead(cwd, { envSessionId: process.env.SKC_SESSION_ID })).skcSessionId;
+	} catch (error) {
+		if (error instanceof SessionResolutionError && error.code === "no_session") return undefined;
+		throw error;
+	}
+}
+
 import type { ActiveSubskillEntry } from "../../skill-state/active-state";
 import { readVisibleSkillActiveState } from "../../skill-state/active-state";
 import type { LoadedSubskillActivation } from "./types";
@@ -21,7 +34,9 @@ export async function readActiveSubskillsForParent(input: {
 	parent: string;
 	phase: string;
 }): Promise<ActiveSubskillEntry[]> {
-	const state = await readVisibleSkillActiveState(input.cwd, input.sessionId);
+	const resolvedSessionId = await resolveBoundarySessionId(input.cwd, input.sessionId);
+	if (!resolvedSessionId) return [];
+	const state = await readVisibleSkillActiveState(input.cwd, resolvedSessionId);
 	const parent = input.parent.trim();
 	const phase = input.phase.trim();
 	if (!state || !parent || !phase) return [];

package/src/harness-control-plane/storage.ts

@@ -1,7 +1,7 @@
 /**
  * Session-scoped storage for the harness control plane.
  *
- * Layout (under the harness state root, default `<cwd>/.skc/state/harness`):
+ * Layout (under the harness state root, default `<cwd>/.skc/_session-{sessionid}/state/harness`):
  *   sessions/<encoded-id>/state.json        lifecycle + handle (atomic)
  *   sessions/<encoded-id>/lease.json         owner lease (M3)
  *   sessions/<encoded-id>/events.jsonl       owner-only severity envelopes
@@ -18,6 +18,7 @@ import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
+import { harnessStateRoot } from "../skc-runtime/session-layout";
 import { appendReceiptToConfiguredSpool } from "./receipt-spool";
 import type { ReceiptEnvelope } from "./receipts";
 import type { EventEnvelope, ReceiptFamily, SessionState } from "./types";
@@ -232,13 +233,22 @@ export class StorageError extends Error {
 	}
 }
 
-/** Resolve the harness state root from explicit value, env, or cwd default. */
-export function resolveHarnessRoot(opts?: { root?: string; cwd?: string; env?: NodeJS.ProcessEnv }): string {
+/** Resolve the harness state root from explicit value, env, or cwd/session default. */
+export function resolveHarnessRoot(opts?: {
+	root?: string;
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+	skcSessionId?: string;
+}): string {
 	const env = opts?.env ?? process.env;
 	if (opts?.root) return path.resolve(opts.root);
 	const fromEnv = env.SKC_HARNESS_STATE_ROOT;
 	if (fromEnv?.trim()) return path.resolve(fromEnv.trim());
-	return path.join(opts?.cwd ?? process.cwd(), ".skc", "state", "harness");
+	const skcSessionId = opts?.skcSessionId ?? env.SKC_SESSION_ID?.trim();
+	if (!skcSessionId) {
+		throw new StorageError("SKC session id is required for default harness state root", "missing_skc_session_id");
+	}
+	return harnessStateRoot(opts?.cwd ?? process.cwd(), skcSessionId);
 }
 
 export function assertSafeSessionId(id: string): void {

package/src/hooks/native-skill-hook.ts

@@ -4,10 +4,13 @@ import * as path from "node:path";
 import { YAML } from "bun";
 import type { SkillDiscoverySettings } from "../config/skill-settings-defaults";
 import { DEFAULT_DISABLED_EXTENSIONS, DEFAULT_SKILL_DISCOVERY_SETTINGS } from "../config/skill-settings-defaults";
+import { sessionLogsDir } from "../skc-runtime/session-layout";
 import {
 	buildActiveUltragoalPromptContext,
 	buildSkillActivationAdditionalContext,
 	buildSkillStopOutput,
+	buildStateRecoveryDiagnosticsContext,
+	collectUserPromptStateRecoveryDiagnostics,
 	type EffectiveSkillConfigInput,
 	recordSkillActivation,
 } from "./skill-state";
@@ -169,6 +172,15 @@ export async function dispatchSkcNativeSkillHook(
 	const hookEventName = readHookEventName(payload);
 	const cwd = (options.cwd ?? safeString(payload.cwd).trim()) || process.cwd();
 	if (hookEventName === "UserPromptSubmit") {
+		const recoveryDiagnostics = await collectUserPromptStateRecoveryDiagnostics({
+			cwd,
+			sessionId: readSessionId(payload),
+			threadId: readThreadId(payload),
+			stateDir: options.stateDir,
+			prompt: readPromptText(payload),
+			sessionFile: readSessionFile(payload),
+		});
+		const recoveryContext = buildStateRecoveryDiagnosticsContext(recoveryDiagnostics);
 		const prompt = readPromptText(payload);
 		const skillState = prompt
 			? await recordSkillActivation({
@@ -206,19 +218,22 @@ export async function dispatchSkcNativeSkillHook(
 				},
 			};
 		}
+		const additionalContext = [
+			skillState ? buildSkillActivationAdditionalContext(skillState, effectiveSkillConfig) : activeUltragoalContext,
+			recoveryContext,
+		]
+			.filter((value): value is string => Boolean(value))
+			.join(" ");
 		return {
 			hookEventName,
-			outputJson:
-				skillState || activeUltragoalContext
-					? {
-							hookSpecificOutput: {
-								hookEventName,
-								additionalContext: skillState
-									? buildSkillActivationAdditionalContext(skillState, effectiveSkillConfig)
-									: activeUltragoalContext,
-							},
-						}
-					: null,
+			outputJson: additionalContext
+				? {
+						hookSpecificOutput: {
+							hookEventName,
+							additionalContext,
+						},
+					}
+				: null,
 		};
 	}
 
@@ -253,7 +268,18 @@ async function readStdinJson(): Promise<{ payload: HookPayload; parseError: Erro
 }
 
 async function logHookError(cwd: string, type: string, error: unknown): Promise<void> {
-	const logsDir = path.join(cwd, ".skc", "logs");
+	const skcSessionId = process.env.SKC_SESSION_ID?.trim();
+	if (!skcSessionId) {
+		console.error(
+			JSON.stringify({
+				timestamp: new Date().toISOString(),
+				type,
+				error: error instanceof Error ? error.message : String(error),
+			}),
+		);
+		return;
+	}
+	const logsDir = sessionLogsDir(cwd, skcSessionId);
 	await mkdir(logsDir, { recursive: true }).catch(() => {});
 	await appendFile(
 		path.join(logsDir, `native-hook-${new Date().toISOString().split("T")[0]}.jsonl`),