okstra 0.235.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.
Files changed (80) hide show
  1. package/dist/lib/host-registry-client.d.mts +9 -2
  2. package/dist/lib/host-registry-client.mjs +29 -3
  3. package/dist/lib/host-registry-client.mjs.map +1 -1
  4. package/dist/lib/runtime-payload.mjs +1 -0
  5. package/dist/lib/runtime-payload.mjs.map +1 -1
  6. package/docs/architecture/storage-model.md +1 -0
  7. package/docs/architecture.md +2 -2
  8. package/docs/cli.md +6 -0
  9. package/package.json +1 -1
  10. package/runtime/BUILD.json +2 -2
  11. package/runtime/bin/lib/okstra/usage.sh +8 -8
  12. package/runtime/bin/okstra-qwen-exec.sh +5 -0
  13. package/runtime/prompts/lead/convergence.md +4 -1
  14. package/runtime/prompts/lead/okstra-lead-contract.md +4 -4
  15. package/runtime/prompts/profiles/_clarification-recommendation.md +1 -1
  16. package/runtime/prompts/profiles/_common-contract.md +10 -1
  17. package/runtime/prompts/wizard/prompts.ko.json +16 -4
  18. package/runtime/python/okstra_ctl/adapters/providers/antigravity/adapter.py +10 -2
  19. package/runtime/python/okstra_ctl/adapters/providers/claude/adapter.py +16 -1
  20. package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py +20 -5
  21. package/runtime/python/okstra_ctl/adapters/providers/kimi/adapter.py +17 -9
  22. package/runtime/python/okstra_ctl/adapters/providers/qwen/adapter.py +88 -0
  23. package/runtime/python/okstra_ctl/adapters/providers/qwen/manifest.json +1 -0
  24. package/runtime/python/okstra_ctl/adapters/providers/qwen/settings.json +12 -0
  25. package/runtime/python/okstra_ctl/adapters/providers/zai/adapter.py +8 -2
  26. package/runtime/python/okstra_ctl/approval_decisions.py +22 -2
  27. package/runtime/python/okstra_ctl/business_flow/contracts.py +11 -0
  28. package/runtime/python/okstra_ctl/business_flow/engine.py +90 -32
  29. package/runtime/python/okstra_ctl/business_flow/hooks.py +4 -2
  30. package/runtime/python/okstra_ctl/business_flow/source.py +39 -7
  31. package/runtime/python/okstra_ctl/business_flow/store.py +94 -28
  32. package/runtime/python/okstra_ctl/convergence.py +95 -5
  33. package/runtime/python/okstra_ctl/convergence_critic_verify_prompt.py +11 -10
  34. package/runtime/python/okstra_ctl/convergence_engine.py +30 -15
  35. package/runtime/python/okstra_ctl/convergence_reverify_prompt.py +9 -2
  36. package/runtime/python/okstra_ctl/coverage_census.py +75 -12
  37. package/runtime/python/okstra_ctl/entrypoints/hosts.py +1 -1
  38. package/runtime/python/okstra_ctl/lead_progress.py +1 -1
  39. package/runtime/python/okstra_ctl/manager_cli.py +42 -5
  40. package/runtime/python/okstra_ctl/manager_launch.py +60 -1
  41. package/runtime/python/okstra_ctl/manager_store.py +45 -0
  42. package/runtime/python/okstra_ctl/model_discovery.py +1 -1
  43. package/runtime/python/okstra_ctl/models.py +2 -2
  44. package/runtime/python/okstra_ctl/phases/discussion/profile.md +2 -2
  45. package/runtime/python/okstra_ctl/phases/error_analysis/profile.md +1 -1
  46. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  47. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +2 -1
  48. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +2 -2
  49. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +3 -3
  50. package/runtime/python/okstra_ctl/phases/requirements_discovery/profile.md +5 -5
  51. package/runtime/python/okstra_ctl/plan_item_evidence.py +25 -1
  52. package/runtime/python/okstra_ctl/registry/provider_registry.py +1 -1
  53. package/runtime/python/okstra_ctl/render_final_report.py +1 -1
  54. package/runtime/python/okstra_ctl/run.py +1 -1
  55. package/runtime/python/okstra_ctl/run_context.py +18 -3
  56. package/runtime/python/okstra_ctl/schema_excerpt.py +14 -9
  57. package/runtime/python/okstra_ctl/verdict_blocks.py +7 -2
  58. package/runtime/python/okstra_ctl/wizard/cli.py +14 -2
  59. package/runtime/python/okstra_ctl/wizard/engine.py +28 -1
  60. package/runtime/python/okstra_ctl/wizard/ids.py +8 -0
  61. package/runtime/python/okstra_ctl/wizard/picker_navigation.py +64 -2
  62. package/runtime/python/okstra_ctl/wizard/roles.py +194 -45
  63. package/runtime/python/okstra_ctl/wizard/sources.py +10 -1
  64. package/runtime/python/okstra_ctl/wizard/state.py +71 -21
  65. package/runtime/python/okstra_ctl/wizard/statefile.py +8 -3
  66. package/runtime/python/okstra_ctl/wizard/steps_roles.py +6 -3
  67. package/runtime/python/okstra_ctl/wizard/worker_settings.py +129 -25
  68. package/runtime/python/okstra_ctl/worker_audit_ledger.py +50 -8
  69. package/runtime/python/okstra_ctl/worker_prompt_body.py +26 -2
  70. package/runtime/python/okstra_ctl/worker_prompt_headers.py +12 -9
  71. package/runtime/python/okstra_token_usage/claude.py +5 -1
  72. package/runtime/python/okstra_token_usage/collect.py +3 -3
  73. package/runtime/python/okstra_token_usage/pricing.py +1 -0
  74. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  75. package/runtime/skills/okstra-discussion/SKILL.md +1 -1
  76. package/runtime/skills/okstra-manager/SKILL.md +8 -2
  77. package/runtime/skills/okstra-run/SKILL.md +2 -2
  78. package/runtime/skills/okstra-setup/SKILL.md +34 -5
  79. package/runtime/skills/okstra-setup/references/project-config.md +19 -0
  80. package/runtime/templates/worker-prompt-preamble.md +12 -2
@@ -22,13 +22,18 @@ from .convergence_provenance import id_occurs_wordbounded
22
22
  from .json_boundary import JsonBoundaryError, load_owned_object
23
23
  from .phases.improvement_discovery.lenses import LENSES, validate_priority_lenses
24
24
  from .scope_provenance import brief_end_state_id_sequence
25
+ from .worker_audit_ledger import named_files, recorded_as_opened
25
26
 
26
27
 
27
28
  CENSUS_SCHEMA_VERSION = "1.0"
29
+ RECORDS_EVIDENCE = "records"
28
30
  CENSUS_ASPECTS_LINE = "- Census aspects:"
29
31
  SCOPES = ("requirement", "task", "file", "lens")
32
+ # `[records]` marks an aspect that okstra's own records (brief, plan, other task
33
+ # records) may settle, so a `clean` citing only them is accepted.
30
34
  _ASPECT_RE = re.compile(
31
- r"^ - (?P<scope>[a-z]+) (?P<slug>[a-z0-9]+(?:-[a-z0-9]+)*):\s*(?P<question>\S.*)$"
35
+ r"^ - (?P<scope>[a-z]+) (?P<slug>[a-z0-9]+(?:-[a-z0-9]+)*)(?P<records> \[records\])?:"
36
+ r"\s*(?P<question>\S.*)$"
32
37
  )
33
38
 
34
39
 
@@ -41,6 +46,7 @@ class Aspect:
41
46
  scope: str
42
47
  slug: str
43
48
  question: str
49
+ records: bool = False
44
50
 
45
51
 
46
52
  def parse_census_aspects(profile_text: str) -> tuple[Aspect, ...]:
@@ -72,7 +78,10 @@ def parse_census_aspects(profile_text: str) -> tuple[Aspect, ...]:
72
78
  raise CensusError(
73
79
  f"census aspect scope {scope!r} is not one of {', '.join(SCOPES)}"
74
80
  )
75
- aspects.append(Aspect(scope, match.group("slug"), match.group("question").strip()))
81
+ aspects.append(Aspect(
82
+ scope, match.group("slug"), match.group("question").strip(),
83
+ records=match.group("records") is not None,
84
+ ))
76
85
  keys = [(aspect.scope, aspect.slug) for aspect in aspects]
77
86
  if len(keys) != len(set(keys)):
78
87
  raise CensusError("census aspects repeat a scope and slug pair")
@@ -101,6 +110,7 @@ def build_census(
101
110
  "aspect": aspect.slug,
102
111
  "subject": subject,
103
112
  "question": aspect.question,
113
+ **({"evidence": RECORDS_EVIDENCE} if aspect.records else {}),
104
114
  })
105
115
 
106
116
  by_scope = {
@@ -200,9 +210,13 @@ def render_census_section(census: Mapping[str, Any], census_rel_path: str) -> st
200
210
  "|---|---|---|---|",
201
211
  ]
202
212
  for cell in cells:
213
+ settled_by_records = (
214
+ " The brief or okstra records may settle it."
215
+ if cell.get("evidence") == RECORDS_EVIDENCE else ""
216
+ )
203
217
  rows.append(
204
218
  f"| `{cell['id']}` | {cell['scope']} | `{_cell_text(str(cell['subject']))}` "
205
- f"| {_cell_text(str(cell['question']))} |"
219
+ f"| {_cell_text(str(cell['question']) + settled_by_records)} |"
206
220
  )
207
221
  return "\n".join(rows)
208
222
 
@@ -265,12 +279,41 @@ def split_coverage_verdict_section(text: str) -> tuple[list[str], str]:
265
279
  return lines[start + 1:end], "\n".join(lines[:start] + lines[end:])
266
280
 
267
281
 
268
- def _judge(kind: str, rest: str, body_texts: Sequence[str]) -> tuple[str, str] | str:
269
- """``(kind, detail)`` for a usable verdict, otherwise why it is unusable."""
282
+ # Stage worktrees live under `~/.okstra/worktrees/`, so source cited by its
283
+ # absolute worktree path is not an okstra input.
284
+ _OKSTRA_INPUT_RE = re.compile(r"(?:^|/)\.okstra/(?!worktrees/)")
285
+
286
+
287
+ def _okstra_input(path: str) -> bool:
288
+ """One of okstra's own inputs: they pose the cell's question, they cannot clear it."""
289
+ return _OKSTRA_INPUT_RE.search(path) is not None
290
+
291
+
292
+ def _judge(
293
+ kind: str, rest: str, body_texts: Sequence[str], opened: frozenset[str] | None = None,
294
+ accepts_records: bool = False,
295
+ ) -> tuple[str, str] | str:
296
+ """``(kind, detail)`` for a usable verdict, otherwise why it is unusable.
297
+
298
+ ``opened`` holds the worker's recorded Evidence read paths; ``None`` means
299
+ the worker kept no ledger, so a clean is not checked against one.
300
+ """
270
301
  detail = rest.strip().lstrip(_SEPARATORS).strip()
271
302
  if kind == "clean":
272
303
  if not _CITATION_RE.search(detail):
273
304
  return "clean without a path:line citation"
305
+ sources = [path for path in named_files(detail) if not _okstra_input(path)]
306
+ if not sources and not accepts_records:
307
+ return "clean cites only .okstra/ artifacts, not the source it judges"
308
+ unopened = [
309
+ path for path in sources
310
+ if opened is not None and not recorded_as_opened(path, opened)
311
+ ]
312
+ if unopened:
313
+ return (
314
+ f"clean rests on `{unopened[0]}`, which the audit sidecar does not "
315
+ "record as opened"
316
+ )
274
317
  return kind, detail
275
318
  if kind == "n/a":
276
319
  if not detail:
@@ -290,12 +333,16 @@ def parse_cell_verdicts(
290
333
  cell_ids: Sequence[str],
291
334
  *,
292
335
  reference_texts: Sequence[str] = (),
336
+ opened: frozenset[str] | None = None,
337
+ record_cells: frozenset[str] = frozenset(),
293
338
  ) -> CellVerdicts:
294
339
  """Read a result's `Coverage Verdicts` section against ``cell_ids``.
295
340
 
296
341
  ``reference_texts`` are other results a `finding` may point into: a
297
342
  gap-fill result can cite an item its worker's first result already raised.
298
- The first usable line for a cell wins.
343
+ ``opened`` is the worker's Evidence read ledger, which a `clean` citation
344
+ must appear in. ``record_cells`` are cells whose `clean` may cite okstra
345
+ records alone. The first usable line for a cell wins.
299
346
  """
300
347
  section, body = split_coverage_verdict_section(result_text)
301
348
  wanted = list(dict.fromkeys(cell_ids))
@@ -315,7 +362,8 @@ def parse_cell_verdicts(
315
362
  if cell in verdicts:
316
363
  continue
317
364
  judged = _judge(
318
- match.group("kind").lower(), match.group("rest"), (body, *reference_texts)
365
+ match.group("kind").lower(), match.group("rest"), (body, *reference_texts), opened,
366
+ cell in record_cells,
319
367
  )
320
368
  if isinstance(judged, tuple):
321
369
  verdicts[cell] = judged
@@ -342,21 +390,33 @@ def audit_census(
342
390
  census: Mapping[str, Any],
343
391
  results: Mapping[str, str | None],
344
392
  gapfills: Mapping[str, str | None] | None = None,
393
+ opened: Mapping[str, frozenset[str] | None] | None = None,
394
+ gapfill_opened: Mapping[str, frozenset[str] | None] | None = None,
345
395
  ) -> dict[str, Any]:
346
396
  """Per-worker coverage of ``census``, the cell x worker matrix, and the
347
397
  cells two workers judged in opposite directions.
348
398
 
349
399
  ``results`` maps each analysis worker to its result text (``None``: the
350
400
  file is missing). ``gapfills`` does the same for the one gap-fill dispatch;
351
- a worker absent from it was not sent one. Whatever stays unjudged after
352
- both is ``unverdicted`` — recorded, never raised.
401
+ a worker absent from it was not sent one. ``opened`` and ``gapfill_opened``
402
+ map a worker to the Evidence read ledger of that result (``None`` or absent:
403
+ no ledger, no check). Whatever stays unjudged after both is ``unverdicted``
404
+ — recorded, never raised.
353
405
  """
354
406
  gapfills = gapfills or {}
407
+ opened = opened or {}
408
+ gapfill_opened = gapfill_opened or {}
355
409
  cell_ids = [str(cell["id"]) for cell in census.get("cells") or []]
410
+ record_cells = frozenset(
411
+ str(cell["id"]) for cell in census.get("cells") or []
412
+ if cell.get("evidence") == RECORDS_EVIDENCE
413
+ )
356
414
  workers: list[dict[str, Any]] = []
357
415
  judged: dict[str, dict[str, tuple[str, str]]] = {}
358
416
  for worker, text in results.items():
359
- first = parse_cell_verdicts(text or "", cell_ids)
417
+ first = parse_cell_verdicts(
418
+ text or "", cell_ids, opened=opened.get(worker), record_cells=record_cells,
419
+ )
360
420
  verdicts = dict(first.verdicts)
361
421
  missing = dict(first.missing)
362
422
  if text is None:
@@ -367,7 +427,8 @@ def audit_census(
367
427
  gapfill_status = "missing" if gapfill_text is None else "read"
368
428
  if gapfill_text is not None and missing:
369
429
  second = parse_cell_verdicts(
370
- gapfill_text, list(missing), reference_texts=(text or "",)
430
+ gapfill_text, list(missing), reference_texts=(text or "",),
431
+ opened=gapfill_opened.get(worker), record_cells=record_cells,
371
432
  )
372
433
  verdicts.update(second.verdicts)
373
434
  missing = {
@@ -446,7 +507,9 @@ requires, and only these two sections:
446
507
  evidence. Write `- none` when there is none. A `finding` may also cite an
447
508
  item ID from your first result.
448
509
  - `## 6. Coverage Verdicts` — one line per cell listed below, in the
449
- preamble's form: `clean — <path:line>`, `finding <ID>`, or `n/a — <reason>`.
510
+ preamble's form: `clean — <path:line>` citing project source (the brief or
511
+ okstra records only where the cell says they may settle it), `finding <ID>`,
512
+ or `n/a — <reason>`.
450
513
 
451
514
  Do not judge cells that are not listed, and do not repeat your first result.
452
515
  """.strip()
@@ -233,7 +233,7 @@ def _probe_paths(project_root: str, home_dir: str):
233
233
 
234
234
  def _unclaimed_host_message(registry: HostAdapterRegistry, command: str) -> str:
235
235
  runtime_flag = "--runtime" if command in {
236
- "install", "ensure-installed", "doctor"
236
+ "install", "ensure-installed", "doctor", "preflight"
237
237
  } else "--lead-runtime"
238
238
  allowed = "|".join(registry.ids())
239
239
  return (
@@ -317,7 +317,7 @@ def _append(args: argparse.Namespace) -> int:
317
317
 
318
318
  _CLI_EPILOG = r"""Usage:
319
319
  okstra lead-progress append --project-root <dir> --run-manifest <path> --phase phase-1-intake
320
- okstra lead-progress append --project-root <dir> --run-manifest <path> --phase phase-4-dispatch --worker codex-worker --field model=gpt-6.1-sol
320
+ okstra lead-progress append --project-root <dir> --run-manifest <path> --phase phase-4-dispatch --worker codex-worker --field model=gpt-6.2-sol
321
321
  okstra lead-progress append --project-root <dir> --run-manifest <path> --phase phase-5-collect --worker codex-worker --field status=completed
322
322
 
323
323
  `progressLine` in the output is the line to emit to the user, verbatim.
@@ -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,
@@ -45,7 +45,7 @@ def agy_tier_suffixes() -> frozenset[str]:
45
45
  어휘다. 둘은 다르다: 정책이 지금 붙이는 것은 `high` 뿐이지만, 관측값에는
46
46
  다른 티어가 실려 올 수 있다.
47
47
  """
48
- return frozenset({"high", "medium", "low"})
48
+ return frozenset({"high", "medium", "low", "xhigh"})
49
49
 
50
50
 
51
51
  @lru_cache(maxsize=1)
@@ -35,8 +35,8 @@ IMPLEMENTATION_ROLES = frozenset({"executor", "verifier"})
35
35
  # Legacy role-keyed compatibility defaults. Canonical assignments resolve a
36
36
  # provider first and then use ProviderSpec.default_models for that role.
37
37
  ROLE_DEFAULTS = {
38
- "lead": "opus", "claude": "opus", "codex": "gpt-6.1-sol",
39
- "antigravity": "gemini-3.1-pro", "report-writer": "sonnet",
38
+ "lead": "opus", "claude": "opus", "codex": "gpt-6.2-sol",
39
+ "antigravity": "gemini-4-argon", "report-writer": "sonnet",
40
40
  }
41
41
 
42
42
 
@@ -35,10 +35,10 @@
35
35
  - keep factual claims (what the code or an external source does) apart from questions only the user can answer (intent, scope, priority, acceptable risk)
36
36
  - for each alternative direction, state what it requires, what it excludes and the risk it carries, without ranking it into a decision the user has not made
37
37
  - Census aspects:
38
- - task subject-framing: What exactly is the subject and the question to settle, and where does the request leave it ambiguous?
38
+ - task subject-framing [records]: What exactly is the subject and the question to settle, and where does the request leave it ambiguous?
39
39
  - task factual-claims: Which claims about the current code or external facts bear on the decision, and what evidence establishes or refutes each?
40
40
  - task alternative-directions: Which alternative directions exist, and what does each require, exclude and risk?
41
- - task user-decisions: Which questions can only the user answer, and what does each answer change?
41
+ - task user-decisions [records]: Which questions can only the user answer, and what does each answer change?
42
42
  - Cross-verification mode:
43
43
  - Phase 5.5 convergence runs in **adversarial mode** for factual claims. Verifiers try to refute each claim by re-inspecting the cited evidence. A convergence stop ends one verification cycle; it does not end the discussion.
44
44
  - A participant checking its own claim is not an independent refutation.
@@ -20,7 +20,7 @@
20
20
  - **Fix-design boundary:** do not design the implementation fix beyond what is necessary to validate the cause. Record whether the cause is credible and the next diagnostic. The common Phase Routing settles the next phase.
21
21
  - Census aspects:
22
22
  - requirement pass-observation: Which observation would show the symptom resolved for this requirement?
23
- - task symptom-lock: Which single observable failure condition does the reported symptom translate to?
23
+ - task symptom-lock [records]: Which single observable failure condition does the reported symptom translate to?
24
24
  - task reproduction: Was the symptom reproduced, not reproduced, or blocked before reproduction, and on what evidence?
25
25
  - task cause-falsification: For each cause candidate, which evidence that could falsify it was checked?
26
26
  - task next-diagnostic: Which diagnostic should run next, and which signal would confirm or reject the leading cause?
@@ -12,7 +12,7 @@
12
12
  - In `preselected-validation` mode, validate the one preselected direction: its evidence, counterevidence, criterion scores, and requirement mappings, and state the same feasibility verdict with its rationale and counterevidence. The worker must not generate new candidates.
13
13
  - Do not produce detailed file lists, stage maps, execution commands, or a plan approval request.
14
14
  - Census aspects:
15
- - requirement mapping: Which candidate or preselected direction satisfies this requirement, and how?
15
+ - requirement mapping [records]: Which candidate or preselected direction satisfies this requirement, and how?
16
16
  - requirement support: Which inspected evidence supports that mapping?
17
17
  - requirement counter-evidence: What is the strongest evidence against that mapping?
18
18
  - task feasibility: Is each candidate feasible, not feasible, or uncertain on inspected evidence?
@@ -1026,7 +1026,8 @@ def _render_prior_round(entry: object) -> str:
1026
1026
  return "".join(rows)
1027
1027
 
1028
1028
 
1029
- # 검증자의 읽기 범위(`**Read scope:**`)는 `## Inputs` 에 열거된 경로만 허용한다.
1029
+ # The verifier's read scope admits okstra artifacts only when the prompt
1030
+ # enumerates them, as `## Inputs` does here.
1030
1031
  # 이 절이 없으면 P-Req 의 originalRequirementId 를 패킷의 요구 문장으로 되짚을
1031
1032
  # 수 없어 범위를 지킨 검증자는 verification-error 를 낸다.
1032
1033
  _INPUT_FIELDS = (
@@ -695,7 +695,7 @@ applies unchanged: append it verbatim after the response format below.
695
695
  `okstra plan-items prompt` renders the `## Inputs` section itself: a
696
696
  `- Primary analysis packet:` line from the run manifest's `analysisPacketPath`
697
697
  and a `- Plan narrative:` line from its `reportNarrativePath`. The worker's
698
- `**Read scope:**` header admits only paths the prompt enumerates, so these lines
698
+ `**Read scope:**` header admits `.okstra/` artifacts only when the prompt enumerates them, so these lines
699
699
  are what let a verifier read the requirement a selected-direction `P-Req-*` row
700
700
  names by `originalRequirementId`. The lead does not add them by hand.
701
701
 
@@ -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
  ...
@@ -26,10 +26,10 @@ Plan for the actual worktree layout before approval. Shared documentation direct
26
26
  - identify requirement gaps and affected interfaces with file:line evidence, resolving codebase-answerable ambiguity before returning findings
27
27
  - surface migration, deployment, cross-project, and approval risks without drafting final-report headings or schema rows
28
28
  - Census aspects:
29
- - requirement plan-linkage: Which planned files and stages realize this requirement?
29
+ - requirement plan-linkage [records]: Which planned files and stages realize this requirement?
30
30
  - requirement interface-impact: Which interfaces does realizing this requirement change, and who calls them?
31
- - requirement validation: Which validation step proves this requirement once the plan is executed?
32
- - task migration-deploy-approval-risk: Which migration, deployment, cross-project, or approval risk does the plan carry?
31
+ - requirement validation [records]: Which validation step proves this requirement once the plan is executed?
32
+ - task migration-deploy-approval-risk [records]: Which migration, deployment, cross-project, or approval risk does the plan carry?
33
33
  - Legacy candidate-comparison-only responsibilities:
34
34
  - **Legacy candidate-comparison procedure** — only a legacy rerun without `selected-direction.json` compares feasible Option Candidates, preserves their trade-offs and Recommended Option, then produces stages, validation, rollback, and requirement coverage. This is the only branch that generates candidates, assigns candidate scores, recommends a direction, or awaits a user candidate choice.
35
35
  - **Spec-settled short-circuit** — when the brief already carries a decision-complete design the reporter has confirmed, do not re-litigate it. Preserve that design as the Recommended Option and its already-weighed alternatives as the remaining Option Candidates.
@@ -16,16 +16,16 @@
16
16
  - state the reporter's rejection criteria, missing routing inputs, and the evidence boundary behind each recommendation
17
17
  - Census aspects:
18
18
  - requirement interpretation: What does this requirement ask for, read against the brief and the code it touches?
19
- - requirement scope-boundary: Where does this requirement stop, and which nearby behaviour does it leave out?
19
+ - requirement scope-boundary [records]: Where does this requirement stop, and which nearby behaviour does it leave out?
20
20
  - requirement dependency: What must exist or happen first for this requirement, in code or in a related task?
21
21
  - requirement verification-method: How would a later phase observe that this requirement is met?
22
- - requirement human-decision: Does this requirement need a decision only a person can make? Name it, or cite the code that settles it.
22
+ - requirement human-decision [records]: Does this requirement need a decision only a person can make? Name it, or cite the code that settles it.
23
23
  - task classification: Which work category (bugfix, feature, improvement, refactor, ops) does the evidence support?
24
- - task rejection-criteria: Which delivered outcome would the reporter reject?
25
- - task missing-materials: Which missing material blocks reliable routing?
24
+ - task rejection-criteria [records]: Which delivered outcome would the reporter reject?
25
+ - task missing-materials [records]: Which missing material blocks reliable routing?
26
26
  - task terminology: Which fuzzy or overloaded terms need one canonical form, and what decides it?
27
27
  - task existing-reuse: Which existing code path, export, test seam or helper should this work reuse instead of adding a new one?
28
- - task related-work: Which related, follow-up or blocking task does this work overlap, and which units stay in or out of this split?
28
+ - task related-work [records]: Which related, follow-up or blocking task does this work overlap, and which units stay in or out of this split?
29
29
  - task input-consistency: Where do the brief, packet and recorded decisions contradict each other or the code?
30
30
  - task shared-impact: Which shared type, model, package or consumer outside the stated scope does this change reach?
31
31
  - Primary focus areas: