okstra 0.236.0 → 0.237.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -707,6 +707,7 @@ Storage authority:
707
707
  - `manager.json`: manager identity and schema version.
708
708
  - `projects.json`: the projectId / projectRoot / role / tags registered with the manager. `projectRoot` must be an existing directory, and setup-equivalent registration is performed only when project-local `.okstra/project.json` is absent.
709
709
  - `manifest.json`, `children.json`, `directives.jsonl`: manager-owned plan, child assignment, and shared/project directives.
710
+ - `children.json`의 하위 작업 행은 `task run --base-ref`로 받은 `baseRef`와, `task register-session`이 기록한 `session`(`address`, `name`, `registeredAt`)을 가집니다. `task run`은 옵션이 없으면 그 `baseRef`를 쓰고, 없으면 같은 프로젝트 형제 행들이 모두 같은 `baseRef`를 가질 때만 그 값을 씁니다. 세션 등록이 값을 바꾸면 작업 `events.jsonl`에 `child-session-registered` 행을 남깁니다.
710
711
  - `group.json`: the task group's original name and creation time, written by `new task-group` and `new task`. The directory name is a slug and cannot give the name back.
711
712
  - `split-plan.json`: the last tracker split plan `task split` applied. The briefs it produced live in each child project's `.okstra/briefs/`, and the children it registered carry `ticketId`, `briefPath`, `scope` and `recommendedPhase` in `children.json`.
712
713
  - `snapshots.json`: a read-side snapshot that `task sync` imports from the child project's `.okstra`. It is not the source of truth for project state.
@@ -154,7 +154,7 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
154
154
  - `prompts/lead/adapters/cmux.md` is selected by environment rather than by runtime: when the run manifest's `terminalBackend` is `cmux-pane`, every lead runtime resolves to it and dispatches through `okstra team`, because okstra owns the worker panes on that path instead of the host. It overrides only the adapter and the dispatch mode; the lead's agent, role, and session accounting still come from its own runtime.
155
155
  - Runtime metadata and role assignments are persisted separately, but the lead provider is derived from the host: Claude Code maps to Claude, Codex maps to Codex, and Antigravity CLI maps to Antigravity. New runs persist `hostRuntime`, `leadAssignment`, and `workerAssignments[]`; each assignment records its provider, model, execution value, and resolved `native-session` or `cli-wrapper` runner. `lead-execution-prompt.md` is canonical: one file per run at `runs/<task-type>/prompts/lead-execution-prompt-<task-type>-<seq>.md`. No Claude-named copy is written — `resources.claudeExecutionPromptPath` in the run manifest is a key alias that resolves to that same file for historical consumers.
156
156
  - Host and provider registries remain separate: the active registered host owns the native lead session, while non-native providers run through their registered CLI wrappers.
157
- - [`skills/okstra-setup/SKILL.md`](../skills/okstra-setup/SKILL.md) — **first-run bootstrap**. Runs `okstra install` and creates `project.json`.
157
+ - [`skills/okstra-setup/SKILL.md`](../skills/okstra-setup/SKILL.md) — **first-run bootstrap**. Runs `okstra install`, creates `project.json`, and offers to save worker defaults through the `okstra-run` worker settings mode.
158
158
  - [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) — host-aware in-session entry point that starts an okstra task in the current registered host session and calls `prepare_task_bundle` directly.
159
159
  - Twelve skills are user-invocable: `skills/okstra-setup/SKILL.md`, `skills/okstra-brief-gen/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-discussion/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-chat/SKILL.md`, `skills/okstra-schedule-gen/SKILL.md`, `skills/okstra-pr-gen/SKILL.md`, `skills/okstra-user-response/SKILL.md`, `skills/okstra-code-review/SKILL.md`, and `skills/okstra-explain-flow/SKILL.md`. Only these are copied into the agent skill home. They cover brief authoring, phase execution, multi-agent discussions that settle requirements before planning, cross-project manager task coordination, global Memory Book storage/search, global chat rooms, schedule support, PR description generation, clarification-response submission, and census-based code review of a stage or branch diff. `okstra-manager` uses `okstra manager` CLI JSON/launch packets as the source of truth, and stores manager-owned plans, assignments, directives, snapshots, and events under `~/.okstra/managers/<manager-id>/`.
160
160
  - Wrapper transcripts are written at `<run-dir>/prompts/<worker>-prompt-<phase>-<seq>.log`; for stage executions, the stage-qualified `run_dir` includes `stage-<N>/`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "okstra",
3
- "version": "0.236.0",
3
+ "version": "0.237.0",
4
4
  "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
5
5
  "license": "MIT",
6
6
  "author": "devonshin",
@@ -1,5 +1,5 @@
1
1
  {
2
- "package": "0.236.0",
3
- "builtAt": "2026-11-19T05:54:13.362Z",
2
+ "package": "0.237.0",
3
+ "builtAt": "2026-11-19T13:45:11.249Z",
4
4
  "repoRoot": "/home/runner/work/okstra/okstra"
5
5
  }
@@ -103,7 +103,7 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
103
103
  | `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id>` | Every `PROGRESS` checkpoint the command performing that step does not record itself; print the `progressLine` it returns. `--phase` accepts only the listed phase ids; use `--worker`, `--field NAME=VALUE`, and `--detail <text>` for the rest | this contract "Progress reporting" |
104
104
  | `okstra agent-activity append --project-root <dir> --run-manifest <path> --kind <kind> --agent <agent> --outcome <outcome> --summary <text>` | Before each activity boundary when the run manifest declares `activityContractVersion: 1`, except a `worker-dispatched` / `worker-completed` row the dispatching command already appended (see "Progress reporting") | launch prompt "Progress reporting" |
105
105
  | `okstra error-log append-observed --out <errors-path> --task-key <key> --phase <phase> --agent <provider-worker> --agent-role <role> --model <model> --error-type <type> --command-kind <kind> --command <command> --message <text>` | Record an observed failure. `--agent` takes the provider worker id (`codex-worker`); an execution label goes in `--execution-label` | this contract "Errors log path wiring"; `team-contract` "Worker error-log command" |
106
- | `okstra approval-decision open --ledger <path> --task-key <key> --task-type <type> --run-seq <seq> --clarification-id <C-NNN> --ticket-id <id> --statement <text> --expected-form <form> --classification <class> --origin <origin> --user-confirmation <text> --unblock-condition <text> --recommended-disposition <disposition> [--supersedes <C-NNN>] [--candidate-ref <IO-NNN>]` | Open an approval blocker after the user confirmed it; `--candidate-ref` names the implementation option a split-vote decision accepts | this contract "User confirmation before an approval blocker" |
106
+ | `okstra approval-decision open --ledger <path> --task-key <key> --task-type <type> --run-seq <seq> --clarification-id <C-NNN> --ticket-id <id> --statement <text> --expected-form <form> --classification <class> --origin <origin> --user-confirmation <text> --unblock-condition <text> --recommended-disposition <disposition> [--supersedes <C-NNN>] [--candidate-ref <IO-NNN>] [--blocks next-phase]` | Open an approval blocker after the user confirmed it; `--candidate-ref` names the implementation option a split-vote decision accepts; `--blocks next-phase` records a decision of a phase whose profile says `Blocks=next-phase` (the default is `approval`) | this contract "User confirmation before an approval blocker" |
107
107
  | `okstra approval-decision carry --ledger <path> --clarification-id <C-NNN> --from-responses <path>` | Carry a decision answered in an earlier run | `report-writer` "Role-owned inputs" |
108
108
  | `okstra approval-decision resolve --ledger <path> --clarification-id <C-NNN> --disposition <disposition> --user-text <text> --user-response-ref <ref>` | Record the user's disposition of an approval row; it touches no verdict | `plan-body-verification` "Round protocol" |
109
109
  | `okstra user-response show --report <path>` | Not a lead step: the `okstra-user-response` skill reads approval rows through it, so an `origin` outside the schema enum breaks every later read | `plan-body-verification` "Round protocol" |
@@ -1,4 +1,4 @@
1
- - every `Kind=decision` clarification row is recorded by the lead in the approval decision ledger — one `okstra approval-decision open --ledger <approvalDecisionsPath>` call per row, before report assembly runs. Assembly reads `clarificationItems[]` from that ledger and from nowhere else, so a decision that exists only as narrative prose reaches no reader and no answer channel: `okstra user-response` cannot offer a row the ledger never carried, and the HTML prints "No further decision is needed" over the top of it. Each option is an object with eight fields:
1
+ - every `Kind=decision` clarification row is recorded by the lead in the approval decision ledger — one `okstra approval-decision open --ledger <approvalDecisionsPath>` call per row, before report assembly runs. The row's `Blocks` value is the call's `--blocks`: `approval` by default, so pass `--blocks next-phase` for every row the phase profile or `_common-contract.md` assigns `Blocks=next-phase`. **Enforced:** `scripts/okstra_ctl/approval_decisions.py` `_decision_row` refuses any other value. Assembly reads `clarificationItems[]` from that ledger and from nowhere else, so a decision that exists only as narrative prose reaches no reader and no answer channel: `okstra user-response` cannot offer a row the ledger never carried, and the HTML prints "No further decision is needed" over the top of it. Each option is an object with eight fields:
2
2
  - `role` — `recommended` for the single best answer, `alternative` for the rest. Exactly one option per row is `recommended`.
3
3
  - `answer` — the choice itself, phrased so the user can pick it as-is. Keep it to a short phrase (roughly 120 characters); the reasoning and the consequences have their own fields below.
4
4
  - `rationale` — why this option is on the board, as long as the reason needs.
@@ -11,6 +11,7 @@ from dataclasses import dataclass
11
11
  from pathlib import Path
12
12
  from typing import Any, Mapping, Sequence
13
13
 
14
+ from .clarification_items.dispositions import USER_INPUT_BLOCKS
14
15
  from .clarification_items.sidecars import (
15
16
  sidecar_answers,
16
17
  attached_response_sections,
@@ -57,6 +58,10 @@ SCOPE_EFFECTS = frozenset({"new-schema", "deferrable"})
57
58
  CLASSIFICATIONS = frozenset(
58
59
  {"user-decision", "noncritical-dissent", "correctness-critical"}
59
60
  )
61
+ # A phase without an approval gate records its decisions as next-phase blockers
62
+ # (`_common-contract.md` reporter-confirmation precondition); both are the values
63
+ # the gates read as waiting on user input.
64
+ DECISION_BLOCKS = tuple(sorted(USER_INPUT_BLOCKS))
60
65
  _FORBIDDEN_BY_CLASSIFICATION = {
61
66
  "correctness-critical": frozenset({"select"}),
62
67
  "noncritical-dissent": frozenset({"select"}),
@@ -214,7 +219,12 @@ def _decision_row(
214
219
  expected_form: str, classification: str, origin: str,
215
220
  user_confirmation: str, unblock_condition: str,
216
221
  recommended_disposition: str, options: Sequence[DecisionOption],
222
+ blocks: str = "approval",
217
223
  ) -> dict[str, Any]:
224
+ if blocks not in DECISION_BLOCKS:
225
+ raise ApprovalDecisionError(
226
+ f"invalid blocks: {blocks!r}. Allowed values: " + ", ".join(DECISION_BLOCKS)
227
+ )
218
228
  if classification not in CLASSIFICATIONS:
219
229
  raise ApprovalDecisionError(f"invalid classification: {classification}")
220
230
  _reject_off_enum(origin, "origin", "ClarificationOrigin")
@@ -232,7 +242,7 @@ def _decision_row(
232
242
  "kind": "decision",
233
243
  "statement": _required(statement, "statement"),
234
244
  "expectedForm": _required(expected_form, "expected_form"),
235
- "blocks": "approval",
245
+ "blocks": blocks,
236
246
  "origin": _required(origin, "origin"),
237
247
  "userConfirmation": _required(user_confirmation, "user_confirmation"),
238
248
  "approval": {
@@ -250,7 +260,7 @@ def open_decision(
250
260
  classification: str, origin: str, user_confirmation: str,
251
261
  unblock_condition: str, recommended_disposition: str,
252
262
  options: Sequence[DecisionOption], supersedes: Sequence[str] = (),
253
- candidate_ref: str = "",
263
+ candidate_ref: str = "", blocks: str = "approval",
254
264
  ) -> None:
255
265
  row = _decision_row(
256
266
  clarification_id=clarification_id, ticket_id=ticket_id,
@@ -258,6 +268,7 @@ def open_decision(
258
268
  classification=classification, origin=origin,
259
269
  user_confirmation=user_confirmation, unblock_condition=unblock_condition,
260
270
  recommended_disposition=recommended_disposition, options=options,
271
+ blocks=blocks,
261
272
  )
262
273
  ledger = _ledger(ledger_path, task_key, task_type, run_seq)
263
274
  active = ledger.get("activeClarifications")
@@ -487,6 +498,15 @@ def _add_open_arguments(parser: argparse.ArgumentParser) -> None:
487
498
  "candidate's splitAcceptance may cite only a decision opened for it."
488
499
  ),
489
500
  )
501
+ parser.add_argument(
502
+ "--blocks",
503
+ choices=DECISION_BLOCKS,
504
+ default="approval",
505
+ help=(
506
+ "what the open row withholds: approval (the default) or next-phase, "
507
+ "for a phase without an approval gate"
508
+ ),
509
+ )
490
510
 
491
511
 
492
512
  _CLI_EPILOG = r"""Usage:
@@ -28,6 +28,7 @@ from .manager_store import (
28
28
  list_projects,
29
29
  list_task_groups,
30
30
  list_tasks,
31
+ register_child_session,
31
32
  remove_child,
32
33
  remove_task,
33
34
  remove_task_group,
@@ -58,7 +59,7 @@ _LIST_ROWS = {
58
59
  def render_manager_text(command: str, payload: dict | list[dict]) -> str:
59
60
  """manager 모델 표면에 승인된 식별자와 상태만 투영한다."""
60
61
  allowed = {"init", "discover-projects", "new-project", "new-task-group", "new-task",
61
- "task-assign", "task-note", "task-sync", "task-status", "task-run", "task-split",
62
+ "task-assign", "task-register-session", "task-note", "task-sync", "task-status", "task-run", "task-split",
62
63
  "list-managers", "list-projects", "list-task-groups", "list-tasks", "view",
63
64
  "task-update", "task-remove-child", "remove-project", "remove-task", "remove-task-group",
64
65
  "log", "journal-add", "resume"}
@@ -80,7 +81,9 @@ def render_manager_text(command: str, payload: dict | list[dict]) -> str:
80
81
  ("Backend", "backend"),
81
82
  ("Worker dispatch backend", "workerDispatchBackend"),
82
83
  ("Project root", "projectRoot"), ("Context path", "contextPath"),
83
- ("Shell command", "shellCommand"), ("View path", "viewPath"),
84
+ ("Shell command", "shellCommand"), ("Base ref", "baseRef"),
85
+ ("Base ref source", "baseRefSource"), ("Manager session", "managerSession"),
86
+ ("View path", "viewPath"),
84
87
  ("View URL", "viewUrl")):
85
88
  if key in payload:
86
89
  rows.append(line(label, payload.get(key)))
@@ -92,6 +95,7 @@ def render_manager_text(command: str, payload: dict | list[dict]) -> str:
92
95
  "new-project": (("Projects", "projects"),),
93
96
  "new-task": (("Manifest", "manifest"), ("Children", "children")),
94
97
  "task-assign": (("Children", "children"),),
98
+ "task-register-session": (("Children", "children"),),
95
99
  "task-sync": (("Children", "children"),),
96
100
  }
97
101
  for label, key in structures.get(command, ()):
@@ -245,11 +249,15 @@ def _render_manager_status(payload: dict) -> list[str]:
245
249
  ("current phase", "currentPhase"), ("work status", "workStatus"),
246
250
  ("summary", "summaryBucket"), ("project linked", "projectLinked"),
247
251
  ("ticket", "ticketId"), ("brief path", "briefPath"),
248
- ("report path", "latestReportRecordPath"),
252
+ ("report path", "latestReportRecordPath"), ("base ref", "baseRef"),
249
253
  ("changed since sync", "changedSinceSync"), ("error", "error")):
250
254
  if key in child:
251
255
  value = child.get(key)
252
256
  rows.append(line(f"Child {index} {label}", ("yes" if value else "no") if isinstance(value, bool) else value))
257
+ session = child.get("session") if isinstance(child.get("session"), dict) else {}
258
+ for label, key in (("session address", "address"), ("session name", "name")):
259
+ if session.get(key):
260
+ rows.append(line(f"Child {index} {label}", session[key]))
253
261
  if isinstance(child.get("discussion"), dict):
254
262
  rows.extend(_render_discussion(index, child["discussion"]))
255
263
  return rows
@@ -332,7 +340,8 @@ _CLI_EPILOG = r"""Usage:
332
340
  okstra manager task sync --manager-id <id> --task-group <task-group> --task-id <task-id>
333
341
  okstra manager task assign --manager-id <id> --task-group <task-group> --task-id <task-id> --project-id <project-id>
334
342
  okstra manager task note --manager-id <id> --task-group <task-group> --task-id <task-id> --scope <shared|project> --body <text>
335
- okstra manager task run --manager-id <id> --project-id <project-id> --task-group <task-group> --task-id <task-id>
343
+ okstra manager task register-session --manager-id <id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <id>] --session <address> [--session-name <name>]
344
+ okstra manager task run --manager-id <id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--base-ref <ref>] [--manager-session <address>]
336
345
  okstra manager task split --manager-id <id> --task-group <task-group> --task-id <task-id> --plan <split-plan.json> [--overwrite]
337
346
  okstra manager task update --manager-id <id> --task-group <task-group> --task-id <task-id> [--objective <text>] [--common-brief <path>] [--progress-mode <manual|auto>]
338
347
  okstra manager task remove-child --manager-id <id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <id>] [--confirm]
@@ -411,6 +420,15 @@ def _parser() -> argparse.ArgumentParser:
411
420
  assign.add_argument("--tag", action="append", default=[])
412
421
  assign.add_argument("--assignment", default="")
413
422
 
423
+ session = task_sub.add_parser("register-session")
424
+ session.add_argument("--manager-id", required=True)
425
+ session.add_argument("--task-group", required=True)
426
+ session.add_argument("--task-id", required=True)
427
+ session.add_argument("--project-id", required=True)
428
+ session.add_argument("--child-task-id", default=None)
429
+ session.add_argument("--session", required=True)
430
+ session.add_argument("--session-name", default="")
431
+
414
432
  note = task_sub.add_parser("note")
415
433
  note.add_argument("--manager-id", required=True)
416
434
  note.add_argument("--task-group", required=True)
@@ -426,6 +444,8 @@ def _parser() -> argparse.ArgumentParser:
426
444
  run.add_argument("--task-id", required=True)
427
445
  run.add_argument("--child-task-id", default=None)
428
446
  run.add_argument("--allow-completed", action="store_true")
447
+ run.add_argument("--base-ref", default="")
448
+ run.add_argument("--manager-session", default="")
429
449
 
430
450
  split = task_sub.add_parser("split")
431
451
  split.add_argument("--manager-id", required=True)
@@ -513,7 +533,7 @@ def _manager_state_changed(args: argparse.Namespace) -> bool:
513
533
  if args.command == "task":
514
534
  if args.task_command == "remove-child":
515
535
  return args.confirm
516
- return args.task_command in ("assign", "note", "sync", "run", "split", "update")
536
+ return args.task_command in ("assign", "register-session", "note", "sync", "run", "split", "update")
517
537
  return False
518
538
 
519
539
 
@@ -583,6 +603,21 @@ def main(argv: list[str] | None = None) -> int:
583
603
  ),
584
604
  args.json,
585
605
  )
606
+ elif args.command == "task" and args.task_command == "register-session":
607
+ _emit(
608
+ "task-register-session",
609
+ register_child_session(
610
+ home,
611
+ args.manager_id,
612
+ args.task_group,
613
+ args.task_id,
614
+ args.project_id,
615
+ address=args.session,
616
+ name=args.session_name,
617
+ child_task_id=args.child_task_id,
618
+ ),
619
+ args.json,
620
+ )
586
621
  elif args.command == "task" and args.task_command == "note":
587
622
  _emit(
588
623
  "task-note",
@@ -612,6 +647,8 @@ def main(argv: list[str] | None = None) -> int:
612
647
  args.project_id,
613
648
  child_task_id=args.child_task_id,
614
649
  allow_completed=args.allow_completed,
650
+ base_ref=args.base_ref,
651
+ manager_session=args.manager_session,
615
652
  ),
616
653
  args.json,
617
654
  )
@@ -19,7 +19,15 @@ from .manager_paths import (
19
19
  snapshots_json_path,
20
20
  task_manifest_path,
21
21
  )
22
- from .manager_store import ManagerError, _now_iso, _read_json, _read_json_default, _write_json, record_event
22
+ from .manager_store import (
23
+ ManagerError,
24
+ _now_iso,
25
+ _read_json,
26
+ _read_json_default,
27
+ _session_address,
28
+ _write_json,
29
+ record_event,
30
+ )
23
31
  from .manager_sync import _snapshot_child, summary_bucket
24
32
 
25
33
 
@@ -94,6 +102,32 @@ def _sibling_snapshots(snapshot: dict, target_task_key: str) -> list[dict]:
94
102
  ]
95
103
 
96
104
 
105
+ def _launch_base_ref(children: dict, child: dict, project_id: str, requested: str) -> tuple[str, str]:
106
+ """The base ref a child's first phase branches from, and where it came from.
107
+
108
+ A sibling's ref is reused only within the same project and only when every sibling that
109
+ recorded one agrees; refs of different repositories, or a split choice, are not guesses to make.
110
+ A child whose worktree is registered and checked out ignores the ref. One whose registry row is
111
+ stale and whose branch is gone is rebuilt from this ref instead of the recorded commit.
112
+ """
113
+ if requested.strip():
114
+ ref = requested.strip()
115
+ if ref.startswith("-") or any(c.isspace() for c in ref):
116
+ raise ManagerError(f"--base-ref must be a branch, tag or commit: {requested!r}")
117
+ return ref, "argument"
118
+ if str(child.get("baseRef") or ""):
119
+ return str(child["baseRef"]), "child"
120
+ sibling_refs = {
121
+ str(row.get("baseRef"))
122
+ for row in children.get("children", [])
123
+ if isinstance(row, dict) and row is not child
124
+ and row.get("projectId") == project_id and row.get("baseRef")
125
+ }
126
+ if len(sibling_refs) == 1:
127
+ return sibling_refs.pop(), "sibling"
128
+ return "", "none"
129
+
130
+
97
131
  def _discussion_follow_up_brief(snapshot: dict, target_task_key: str) -> Path | None:
98
132
  """`okstra discussion follow-up-brief` 가 이 하위 task 에 쓴 브리프.
99
133
 
@@ -120,6 +154,7 @@ def _render_context(
120
154
  directives: list[dict],
121
155
  siblings: list[dict],
122
156
  discussion_ref: dict | None,
157
+ manager_session: str,
123
158
  ) -> str:
124
159
  lines = [
125
160
  "# Okstra Manager Child Context",
@@ -153,6 +188,18 @@ def _render_context(
153
188
  f"- requirements: {', '.join(discussion_ref['requirementIds'])}",
154
189
  "- The brief pins this revision; a newer revision applies only when the user adopts it.",
155
190
  ""])
191
+ if manager_session:
192
+ lines.extend([
193
+ "## Manager Reporting",
194
+ "",
195
+ f"- manager session: {manager_session}",
196
+ "",
197
+ f"Send the manager session a message naming child task-key {child_task_key} and this session's own "
198
+ "address when this run starts, and one naming the task key when each phase ends; "
199
+ "then wait for the manager before starting the next phase.",
200
+ "Approval gates stay with this session's user.",
201
+ "",
202
+ ])
156
203
  lines.extend(["## Manager Directives", ""])
157
204
  for row in directives:
158
205
  lines.append(f"- [{row.get('scope')}] {row.get('body')}")
@@ -204,6 +251,8 @@ def _record_launch_prepared(
204
251
  }
205
252
  )
206
253
  child["launch"] = launch
254
+ if packet["baseRefSource"] == "argument":
255
+ child["baseRef"] = packet["baseRef"]
207
256
  _write_json(children_json_path(home, manager_id, task_group, task_id), children)
208
257
  record_event(
209
258
  events_jsonl_path(home, manager_id, task_group, task_id),
@@ -250,6 +299,8 @@ def build_launch_packet(
250
299
  *,
251
300
  child_task_id: str | None = None,
252
301
  allow_completed: bool = False,
302
+ base_ref: str = "",
303
+ manager_session: str = "",
253
304
  now: str | None = None,
254
305
  ) -> dict:
255
306
  manifest = _read_json(task_manifest_path(home, manager_id, task_group, task_id))
@@ -265,6 +316,8 @@ def build_launch_packet(
265
316
  _validate_child_task_key(child, target_task_key)
266
317
  project_root = _validated_project_root(project)
267
318
  current = _current_child_state(project_root, child, target_task_key, allow_completed=allow_completed)
319
+ resolved_base_ref, base_ref_source = _launch_base_ref(children, child, project_id, base_ref)
320
+ manager_session = _session_address(manager_session, "--manager-session") if manager_session.strip() else ""
268
321
  created_at = now or _now_iso()
269
322
  brief_path = (Path(str(child["briefPath"])) if child.get("briefPath")
270
323
  else _discussion_follow_up_brief(snapshot, target_task_key))
@@ -279,6 +332,7 @@ def build_launch_packet(
279
332
  directives=_directives_for_project(directives, project_id),
280
333
  siblings=_sibling_snapshots(snapshot, target_task_key),
281
334
  discussion_ref=discussion_ref,
335
+ manager_session=manager_session,
282
336
  ),
283
337
  encoding="utf-8",
284
338
  )
@@ -302,6 +356,8 @@ def build_launch_packet(
302
356
  run_args.extend(["--task-type", str(recommended)])
303
357
  if brief_path is not None:
304
358
  run_args.extend(["--task-brief", str(brief_path)])
359
+ if resolved_base_ref:
360
+ run_args.extend(["--base-ref", resolved_base_ref])
305
361
  run_args += [
306
362
  "--directive",
307
363
  f"{MANAGER_CONTEXT_DIRECTIVE_PREFIX}{context_path}",
@@ -319,6 +375,9 @@ def build_launch_packet(
319
375
  "command": command,
320
376
  "runArgs": run_args,
321
377
  "shellCommand": shlex.join([command, *run_args]),
378
+ "baseRef": resolved_base_ref,
379
+ "baseRefSource": base_ref_source,
380
+ "managerSession": manager_session,
322
381
  "createdAt": created_at,
323
382
  }
324
383
  if discussion_ref:
@@ -486,6 +486,51 @@ def assign_child(
486
486
  return payload
487
487
 
488
488
 
489
+ def _session_address(value: str, option: str) -> str:
490
+ text = value.strip()
491
+ if not text or text.startswith("-") or any(c in text for c in "\r\n"):
492
+ raise ManagerError(f"{option} must be a non-empty single-line session address")
493
+ return text
494
+
495
+
496
+ def register_child_session(
497
+ home: Path,
498
+ manager_id: str,
499
+ task_group: str,
500
+ task_id: str,
501
+ project_id: str,
502
+ *,
503
+ address: str,
504
+ name: str = "",
505
+ child_task_id: str | None = None,
506
+ now: str | None = None,
507
+ ) -> dict:
508
+ """Record which host session runs a child task.
509
+
510
+ The address is what the manager sends messages to; a host may rename the session on restart
511
+ while keeping the address, so the name is informational only.
512
+ """
513
+ _read_json(task_manifest_path(home, manager_id, task_group, task_id))
514
+ payload = _load_children(home, manager_id, task_group, task_id)
515
+ child = _select_child_for_assignment(payload["children"], project_id, task_group, child_task_id)
516
+ current = child.get("session") if isinstance(child.get("session"), dict) else {}
517
+ if any(c in name for c in "\r\n"):
518
+ raise ManagerError("--session-name must be a single line")
519
+ requested = {"address": _session_address(address, "--session"),
520
+ "name": name.strip() or str(current.get("name") or "")}
521
+ changes = _field_changes(current, requested)
522
+ if changes:
523
+ created_at = now or _now_iso()
524
+ child["session"] = {**requested, "registeredAt": created_at}
525
+ _write_json(children_json_path(home, manager_id, task_group, task_id), payload)
526
+ record_event(
527
+ events_jsonl_path(home, manager_id, task_group, task_id),
528
+ {"event": "child-session-registered", "createdAt": created_at,
529
+ "taskKey": str(child.get("taskKey") or ""), "changes": changes},
530
+ )
531
+ return payload
532
+
533
+
489
534
  def append_directive(
490
535
  home: Path,
491
536
  manager_id: str,
@@ -872,7 +872,7 @@ never recorded, and the round is scored on the items that remain.
872
872
  **Explanation**: <2-3 sentences>
873
873
  **Dependencies**: {"complete": false, "itemIds": [], "paths": []}
874
874
 
875
- Keep the detailed Note and Explanation. Declare all direct and transitive plan-item and whole-file evidence dependencies. Set `complete` to true only when that boundary is known. Include source files behind references. External or dynamic evidence, unlisted narrative dependencies and unresolved references keep `complete` false. This declaration controls reuse eligibility, not the verdict itself. Missing and malformed declarations are treated as unknown by `verdict_blocks._block` and `plan_item_evidence.review_fingerprint`.
875
+ Keep the detailed Note and Explanation. Declare all direct and transitive plan-item and whole-file evidence dependencies. Set `complete` to true only when that boundary is known. Include source files behind references. External or dynamic evidence, unlisted narrative dependencies and unresolved references keep `complete` false. This declaration controls reuse eligibility, not the verdict itself. The run manifest and the task manifest are rewritten on every dispatch; the runtime neither snapshots them nor counts them in the closure, and their review facts (worker assignments, contracts) enter the reuse fingerprint directly. Cite the plan items, project source files, plan narrative or analysis packet that the verdict rests on instead. Missing and malformed declarations are treated as unknown by `verdict_blocks._block` and `plan_item_evidence.review_fingerprint`.
876
876
 
877
877
  ### P-Opt-2
878
878
  ...
@@ -3,6 +3,7 @@ from __future__ import annotations
3
3
 
4
4
  import hashlib
5
5
  import json
6
+ import posixpath
6
7
  import re
7
8
  import stat
8
9
  from collections.abc import Mapping, Sequence
@@ -31,6 +32,7 @@ class ReviewInputs(TypedDict):
31
32
  complete: bool
32
33
  planContext: dict[str, Any]
33
34
  priorReviewHashes: dict[str, str]
35
+ runOwned: dict[str, Any]
34
36
 
35
37
 
36
38
  def _digest(value: object) -> str:
@@ -63,6 +65,22 @@ def _file_snapshot(root: Path, name: str) -> FileSnapshot | None:
63
65
  return None
64
66
 
65
67
 
68
+ def _run_owned(manifest: Mapping[str, Any]) -> dict[str, Any]:
69
+ """The run and task manifests, which every dispatch rewrites.
70
+
71
+ A reviewer may cite them, but a snapshot of one changes with every dispatch, and the review
72
+ facts they hold (assignments, contracts) already enter the `context` digest. Other files in the
73
+ run directory, such as the plan narrative, stay evidence.
74
+ """
75
+ names = (manifest.get("runManifestPath"), manifest.get("taskManifestPath"))
76
+ return {"files": sorted({posixpath.normpath(str(name)) for name in names if name})}
77
+
78
+
79
+ def _is_run_owned(name: str, owned: Mapping[str, Any]) -> bool:
80
+ path = posixpath.normpath(name)
81
+ return any(path == file or path.endswith("/" + file) for file in owned.get("files", []))
82
+
83
+
66
84
  def _payload_paths(value: object) -> set[str]:
67
85
  if isinstance(value, str):
68
86
  return {value} if value and not any(c in value for c in "\n`*") else set()
@@ -118,9 +136,12 @@ def capture_review_inputs(
118
136
  "plan_items.py", "plan_item_evidence.py", "plan_review_context.py", "phases/implementation_planning/authoring.py",
119
137
  "phases/implementation_planning/instructions/plan-body-verification.md",
120
138
  )})
139
+ run_owned = _run_owned(manifest)
140
+ paths = {name for name in paths if not _is_run_owned(name, run_owned)}
121
141
  files = {name: _file_snapshot(root, name) for name in sorted(paths)}
122
142
  return {
123
143
  "version": 1,
144
+ "runOwned": run_owned,
124
145
  "planContext": metadata,
125
146
  "priorReviewHashes": {str(row["id"]): str(row.get("verifiedReviewHash", "")) for row in previous_rows},
126
147
  "items": {str(item["id"]): dict(item) for item in items},
@@ -180,6 +201,8 @@ def _dependency_closure(row: Mapping[str, Any], inputs: Mapping[str, Any]) -> tu
180
201
  declared = _vote_dependencies(graph.get(key), inputs.get("workers", []))
181
202
  if declared is None:
182
203
  return None
204
+ owned = inputs.get("runOwned") or {}
205
+ declared = (declared[0], {name for name in declared[1] if not _is_run_owned(name, owned)})
183
206
  if any(not inputs.get("files", {}).get(name)
184
207
  or inputs["files"][name]["hash"] == "absent" for name in declared[1]):
185
208
  return None
@@ -198,7 +221,8 @@ def _dependency_closure(row: Mapping[str, Any], inputs: Mapping[str, Any]) -> tu
198
221
  )
199
222
  for field in ("files", "plannedPaths"):
200
223
  paths.update(_payload_paths(payload.get(field)))
201
- return item_ids, paths
224
+ owned = inputs.get("runOwned") or {}
225
+ return item_ids, {name for name in paths if not _is_run_owned(name, owned)}
202
226
 
203
227
 
204
228
  def review_fingerprint(row: Mapping[str, Any], inputs: Mapping[str, Any]) -> str | None:
@@ -9,7 +9,7 @@ from okstra_ctl.registry.host_registry import default_host_registry
9
9
 
10
10
  from .ids import REQUESTABLE_TASK_TYPES
11
11
  from .state import WizardError
12
- from .statefile import load_state_file, save_state_file
12
+ from .statefile import load_state_file, read_state_file, save_state_file
13
13
  from .confirmation import confirmation_block
14
14
  from .engine import (
15
15
  init_state,
@@ -113,7 +113,7 @@ def main(argv: list[str]) -> int:
113
113
  return 0
114
114
 
115
115
  if args.cmd == "step":
116
- state = load_state_file(state_path)
116
+ state, restarted = read_state_file(state_path)
117
117
  persisted_state = copy.deepcopy(state)
118
118
  if args.no_submit and args.answer is not None:
119
119
  print(json.dumps(
@@ -133,6 +133,18 @@ def main(argv: list[str]) -> int:
133
133
  ensure_ascii=False, indent=2,
134
134
  ))
135
135
  return 2
136
+ if restarted and not args.no_submit:
137
+ save_state_file(state_path, state)
138
+ print(json.dumps({
139
+ "ok": False,
140
+ "error": (
141
+ "the wizard state was saved by an older okstra version and has "
142
+ "restarted from the first step; the answer was not submitted. "
143
+ "Answer the current prompt instead."
144
+ ),
145
+ "current": prompt_payload(state, next_prompt(state)),
146
+ }, ensure_ascii=False, indent=2))
147
+ return 0
136
148
  try:
137
149
  if args.no_submit:
138
150
  result = {"echo": "", "next": prompt_payload(state, next_prompt(state))}
@@ -337,7 +337,10 @@ def _profile_path(workspace_root: Path, task_type: str) -> Path:
337
337
  raise WizardError(str(exc)) from exc
338
338
 
339
339
 
340
- WIZARD_STATE_VERSION = 2
340
+ # Bump on every change to the saved fields or step ids: a state of the old shape
341
+ # that still loads resumes on a recomputed step, and the answer meant for its
342
+ # saved step lands on another one.
343
+ WIZARD_STATE_VERSION = 3
341
344
 
342
345
 
343
346
  _V2_STATE_FIELDS = (
@@ -31,13 +31,18 @@ def _fresh_state_from_stale(payload: dict) -> WizardState:
31
31
  return WizardState(**kwargs)
32
32
 
33
33
 
34
- def load_state_file(path: Path) -> WizardState:
34
+ def read_state_file(path: Path) -> tuple[WizardState, bool]:
35
+ """The saved state, and whether it was an older format restarted from scratch."""
35
36
  data = load_owned_object(Path(path), artifact="wizard state")
36
37
  try:
37
- return WizardState.from_json(data)
38
+ return WizardState.from_json(data), False
38
39
  except StaleWizardStateError:
39
40
  # 이전 형식의 진행분은 옮기지 않는다 — 같은 프로젝트로 새 세션을 시작한다.
40
- return _fresh_state_from_stale(data)
41
+ return _fresh_state_from_stale(data), True
42
+
43
+
44
+ def load_state_file(path: Path) -> WizardState:
45
+ return read_state_file(path)[0]
41
46
 
42
47
 
43
48
  def save_state_file(path: Path, state: WizardState) -> None:
@@ -107,10 +107,16 @@ def _cited_file_paths(content: str) -> set[str]:
107
107
  # A file that a citation, an evidence note or an Opened list names:
108
108
  # `src/a_b.ts:4-9`, **src/a.ts**, [packet](.okstra/x/p.md:3), /abs/src/a.ts.
109
109
  # A name counts only with a directory or a line, so prose such as `e.g.` or a
110
- # version number is not a file.
110
+ # version number is not a file. Bracketed and parenthesised segments are route
111
+ # directories (Next.js `[slug]`, `[[...slug]]`, `(group)`); without them the
112
+ # path was cut at the bracket and a file the worker opened read as unopened.
113
+ _PATH_CHAR = r"(?:[\w.@-]|\[{1,2}[\w.@-]+\]{1,2}|\([\w.@-]+\))"
111
114
  _NAMED_FILE_RE = re.compile(
112
- r"(?<![\w./@-])(?P<path>[\w.@-]*(?:/[\w.@-]+)*\.[A-Za-z]\w*"
113
- r"|(?:[\w.@-]+/)+(?:Dockerfile|Justfile|Makefile|Procfile|Rakefile))"
115
+ # A match never starts inside a run of path characters — after a segment's
116
+ # closing bracket or at the inner `[` of `[[` either — so a failed scan ends
117
+ # at the run's end once instead of restarting at every bracket.
118
+ rf"(?<![\w./@\])-])(?!(?<=\[)\[)(?P<path>{_PATH_CHAR}*(?:/{_PATH_CHAR}+)*\.[A-Za-z]\w*"
119
+ rf"|(?:{_PATH_CHAR}+/)+(?:Dockerfile|Justfile|Makefile|Procfile|Rakefile))"
114
120
  r"(?P<line>:\d+(?:-\d+)?)?"
115
121
  )
116
122
 
@@ -33,7 +33,8 @@ okstra manager task status --manager-id <manager-id> --task-group <task-group> -
33
33
  okstra manager task sync --manager-id <manager-id> --task-group <task-group> --task-id <task-id>
34
34
  okstra manager task assign --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <child-task-id>] [--role <role>] [--tag <tag>] [--assignment <text>]
35
35
  okstra manager task note --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --scope <shared|project> [--project-id <project-id>] --body <text>
36
- okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>] [--allow-completed]
36
+ okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>] [--allow-completed] [--base-ref <ref>] [--manager-session <address>]
37
+ okstra manager task register-session --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <child-task-id>] --session <address> [--session-name <name>]
37
38
  okstra manager task split --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --plan <split-plan.json> [--overwrite]
38
39
  okstra manager list managers
39
40
  okstra manager list projects --manager-id <manager-id>
@@ -154,7 +155,12 @@ For launching child work:
154
155
 
155
156
  1. Run `okstra manager task sync ...` if the manager snapshot must be refreshed first.
156
157
  2. Run `okstra manager task run ...`. It re-reads the child's state from its project, not from the snapshot. When the child is already done there (terminal next phase, or work status `done`), it refuses with the last phase and report path; tell the user that and do not add `--allow-completed` unless the user asks to run the child again.
157
- 3. Read the returned fixed fields `Backend`, `Worker dispatch backend`, `Project root`, `Context path`, `Run command`, every numbered `Run arg N`, and `Shell command`.
158
+ - A child task's first phase branches from a base ref. Pass the one the user chose as `--base-ref <ref>`; the child keeps it for later launches. Without the option, `task run` uses the child's recorded ref, or the ref every sibling of the same project recorded, and `Base ref source` says which (`argument`, `child`, `sibling`). When it is `none` and the child task does not exist in its project yet, ask the user for the base ref and run `task run` again with `--base-ref`; do not pick a branch yourself.
159
+ - When this session can receive messages from other sessions, pass its own address as `--manager-session <address>`. The child context then tells the child lead to message that address with its child task key and its own session address when the run starts, to report again when each phase ends, and to wait for the manager before the next phase. Approval gates stay with the child session's user; the manager recommends, it does not answer them. Use the address the host keeps across restarts, not a display name.
160
+ - A recorded or sibling ref is also passed for a child that already exists. A child whose worktree is registered and checked out ignores it; one whose worktree was released starts its next worktree from it, and one whose registry row is stale with its branch gone is rebuilt from it instead of the recorded commit.
161
+ 3. Read the returned fixed fields `Backend`, `Worker dispatch backend`, `Project root`, `Context path`, `Run command`, every numbered `Run arg N`, `Shell command`, `Base ref`, `Base ref source`, and `Manager session`.
158
162
  4. Give the user the `Shell command` line verbatim and tell them to run it in a new terminal. It starts the installed launcher in the child project: the launcher fills the task type and brief from the child task manifest or asks for them, prepares the run with the manager context directive, and starts the child lead as a separate host process (`Backend` `spawn-process`).
159
163
 
164
+ 5. When a child lead's first message names its child task key and its session address, record that address with `okstra manager task register-session ... --session <address> [--session-name <name>]`. `task status` then shows each child's `session address` and `session name`; send later directives to that address. Registering the same address and name again records nothing; a new name on the same address replaces the old one, and leaving out `--session-name` keeps the recorded name.
165
+
160
166
  Do not run the `Shell command` through this session's Bash tool: it opens an interactive host session. Do not rebuild it from `Run arg N` or swap in `okstra run`, which drops the task inputs and the directive for a lead host.
@@ -182,6 +182,9 @@ matching section:
182
182
  standards every run reads; hand-added, checked by `okstra doctor --phase <phase>`.
183
183
  - **H. MCP servers** (`mcpServers`) — `okstra mcp add` declares a server,
184
184
  `okstra mcp check` shows which provider CLIs reach it.
185
+ - **I. worker defaults** (`workerDefaults`) — saved worker models and counts per
186
+ role, global or per-project. Setup offers this in Step 5; the same flow runs
187
+ whenever the user asks to review or change them later.
185
188
 
186
189
  ## Step 4: Verify
187
190
 
@@ -189,16 +192,42 @@ matching section:
189
192
  okstra doctor --runtime <host-runtime>
190
193
  ```
191
194
 
192
- If all checks return `OK`, the setup is complete. If any check fails, surface
193
- the output and let the user decide whether to re-run install or skip.
195
+ If all checks return `OK`, continue to Step 5. If any check fails, surface
196
+ the output and let the user decide whether to re-run install or skip. A skipped
197
+ failure also skips Step 5, because saving defaults checks each model's
198
+ availability; the hand-off then reports worker defaults as skipped.
194
199
 
195
- ## Step 5: Hand-off
200
+ ## Step 5: Worker defaults
201
+
202
+ Saved worker defaults let `/okstra-run` fill each configured role's models and
203
+ count without showing its selection screen; roles left unconfigured are still
204
+ asked on every run. Ask once with `prompt_user`:
205
+
206
+ - **Question**: `"Save default worker models and counts now, so okstra-run skips those selection screens?"`
207
+ - **Options**: `Configure now` (recommended) — open the worker settings editor;
208
+ `Skip` — keep choosing on each run; the settings can be opened later with
209
+ "okstra-run worker settings".
210
+
211
+ On `Configure now`, run the worker settings mode of the installed `okstra-run`
212
+ skill with the project root from Step 2 and the project id from Step 3. That
213
+ mode owns the scope choice, role editor, review, save and cancel; it shows any
214
+ values already saved and keeps them unless the user edits them. Do not edit
215
+ `~/.okstra/config.json` or `project.json` by hand, and do not start a task from
216
+ it. When the mode reports that it finished or was cancelled, continue to Step 6
217
+ and carry its final `next.label` text.
218
+
219
+ ## Step 6: Hand-off
196
220
 
197
221
  Inform the user with a short summary:
198
222
 
199
223
  > okstra is ready. Runtime: `~/.okstra` (version stamp). Project metadata:
200
- > `<PROJECT_ROOT>/.okstra/project.json` (`projectId`). Run
201
- > `/okstra-run` to start your first task.
224
+ > `<PROJECT_ROOT>/.okstra/project.json` (`projectId`). Worker defaults:
225
+ > `<outcome>`. Run `/okstra-run` to start your first task.
226
+
227
+ Fill `<outcome>` only from what Step 5 observed: the settings mode's final
228
+ `next.label` when it finished, `cancelled, nothing saved` when it was cancelled,
229
+ and `skipped` when the user chose `Skip` or Step 4 skipped Step 5. Do not claim
230
+ that values were saved, changed or absent beyond that text.
202
231
 
203
232
  ## Failure modes
204
233
 
@@ -335,3 +335,22 @@ existing entries.
335
335
  prepare repeats the check for the providers a run selects and prints a warning
336
336
  for each gap; it never refuses the run. It also warns when the task brief cites
337
337
  a Figma URL and no declared server name or alias contains `figma`.
338
+
339
+ ## I. Worker defaults (`workerDefaults`)
340
+
341
+ `workerDefaults` saves the worker models for each role, keyed by role name. The
342
+ array fixes both the models and the count; an empty array disables an optional
343
+ role. The project value in `project.json` replaces that role's global value in
344
+ `~/.okstra/config.json`. `/okstra-run` fills each valid configured role without
345
+ showing its selection screen and still asks for roles that are missing or whose
346
+ saved models are unavailable. `modelDefaults` only orders the candidate list and
347
+ never skips a screen.
348
+
349
+ Review, change or clear these values with the same flow as SKILL.md Step 5: run
350
+ the worker settings mode of the installed `okstra-run` skill. It shows the
351
+ current values for every role and saves nothing until the user chooses Save.
352
+ To only read the saved values of both scopes, run:
353
+
354
+ ```bash
355
+ okstra config show --scope all
356
+ ```