@pennixrv/trellis 0.7.0-beta.5 → 0.7.0-beta.50

package/dist/templates/trellis/scripts/subnode_artifact.py

@@ -9,6 +9,7 @@ dispatches workers, makes the acceptance judgment, or mutates task state.
 from __future__ import annotations
 
 import argparse
+import hashlib
 import json
 import re
 import sys
@@ -22,14 +23,19 @@ from common.task_utils import is_within_tasks_dir, resolve_task_dir
 from common.tasks import load_task
 
 
-SCHEMA_VERSION = 1
+SCHEMA_VERSION = 2
 MAX_DRAFT_BYTES = 64 * 1024
 MAX_REPORT_BYTES = 128 * 1024
+MAX_WORKLOG_BYTES = 128 * 1024
+MAX_QUEUE_BYTES = 128 * 1024
 ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
+CHECKPOINT_RE = re.compile(r"^<!-- trellis-checkpoint: (?P<payload>\{.*\}) -->$", re.MULTILINE)
 SECRET_PATTERNS = (
     re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----"),
     re.compile(r"\bsk-[A-Za-z0-9]{20,}\b"),
     re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b"),
+    re.compile(r"\bBearer\s+[A-Za-z0-9._~+/-]+=*", re.IGNORECASE),
+    re.compile(r'''["']?\b(?:password|secret|api[_-]?key|access[_-]?token|authorization)["']?\s*[:=]\s*(?:"[^"\r\n]+"|'[^'\r\n]+'|[^\s,;}]+)''', re.IGNORECASE),
 )
 TERMINAL_LIFECYCLES = {"done", "error", "killed", "crashed"}
 DISPOSITION_OUTCOMES = {"accepted", "rejected", "deferred"}
@@ -152,6 +158,98 @@ def _relative_to_repo(path: Path, repo_root: Path) -> str:
         _fail(f"path is outside repository: {path}")
 
 
+def _queue_paths(task_dir: Path, work_id: str) -> tuple[Path, Path]:
+    work_dir = task_dir / "subnodes" / work_id
+    _assert_no_subpath_symlinks(task_dir, work_dir)
+    if not work_dir.exists() or not work_dir.is_dir():
+        _fail(f"queue work directory does not exist: {work_dir}")
+    return work_dir / "queue.json", work_dir / "queue-abandoned.json"
+
+
+def _queue_context(args: argparse.Namespace) -> tuple[Path, str, Path, Path, Path]:
+    repo_root = get_repo_root()
+    task_dir = resolve_task_dir(args.task, repo_root)
+    if task_dir is None or not is_within_tasks_dir(task_dir, repo_root):
+        _fail("--task must identify a direct active task directory")
+    if task_dir.is_symlink():
+        _fail(f"refusing symlinked task directory: {task_dir}")
+    work_id = _require_id(args.work_id, "--work-id")
+    task_id = _task_id(task_dir)
+    queue_path, abandoned_path = _queue_paths(task_dir, work_id)
+    for path in (queue_path, abandoned_path):
+        if path.is_symlink():
+            _fail(f"refusing symlinked queue artifact: {path}")
+    return repo_root, task_id, task_dir, queue_path, abandoned_path
+
+
+def _write_json_exclusive(path: Path, value: dict[str, Any], label: str) -> None:
+    if path.is_symlink():
+        _fail(f"refusing symlinked {label}: {path}")
+    try:
+        with path.open("x", encoding="utf-8") as stream:
+            json.dump(value, stream, indent=2, ensure_ascii=False)
+            stream.write("\n")
+    except FileExistsError:
+        _fail(f"{label} already exists and cannot be replaced: {path}")
+    except OSError as exc:
+        _fail(f"could not write {label} {path}: {exc}")
+
+
+def _validate_queue_file(
+    queue_path: Path,
+    task_dir: Path,
+    task_id: str,
+    work_id: str,
+    repo_root: Path,
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    queue, _raw = _read_json_object(queue_path, MAX_QUEUE_BYTES, "queue")
+    if queue.get("schema_version") != 1:
+        _fail("queue.schema_version must be 1")
+    if queue.get("task_id") != task_id:
+        _fail("queue.task_id does not match the task")
+    if queue.get("work_id") != work_id:
+        _fail("queue.work_id does not match the requested work")
+    channel = queue.get("channel_ref")
+    if not isinstance(channel, dict):
+        _fail("queue.channel_ref must be an object")
+    channel_name = _require_text(channel.get("name"), "queue.channel_ref.name", max_len=128)
+    channel_scope = _require_text(channel.get("scope"), "queue.channel_ref.scope", max_len=32)
+    if channel_scope not in {"project", "global"}:
+        _fail("queue.channel_ref.scope must be project or global")
+    items = queue.get("items")
+    if not isinstance(items, list) or not items:
+        _fail("queue.items must be a non-empty list")
+    seen: set[str] = set()
+    validated: list[dict[str, Any]] = []
+    for index, item in enumerate(items):
+        if not isinstance(item, dict):
+            _fail(f"queue.items[{index}] must be an object")
+        subnode_id = _require_id(item.get("subnode_id"), f"queue.items[{index}].subnode_id")
+        if subnode_id in seen:
+            _fail("queue.items contains duplicate subnode_id values")
+        seen.add(subnode_id)
+        brief_path = _require_text(item.get("brief_path"), f"queue.items[{index}].brief_path")
+        brief, raw, brief_file, node_dir, brief_task_dir = _validate_brief_file(
+            brief_path, repo_root
+        )
+        if brief_task_dir != task_dir:
+            _fail(f"queue item {subnode_id} brief belongs to another task")
+        if brief.get("work_id") != work_id or brief.get("subnode_id") != subnode_id:
+            _fail(f"queue item {subnode_id} brief identity does not match")
+        expected_brief_path = _relative_to_repo(node_dir / "brief.json", repo_root)
+        if _relative_to_repo(brief_file, repo_root) != expected_brief_path:
+            _fail(f"queue item {subnode_id} brief_path is not canonical")
+        if brief.get("channel_ref", {}).get("name") != channel_name:
+            _fail(f"queue item {subnode_id} channel name does not match the queue")
+        if brief.get("channel_ref", {}).get("scope") != channel_scope:
+            _fail(f"queue item {subnode_id} channel scope does not match the queue")
+        digest = hashlib.sha256(raw).hexdigest()
+        if item.get("brief_digest") != digest:
+            _fail(f"queue item {subnode_id} brief digest does not match")
+        validated.append({"subnode_id": subnode_id, "brief_path": brief_path, "brief_digest": digest})
+    return queue, validated
+
+
 def _validate_snapshot(value: Any) -> None:
     if not isinstance(value, list) or not value:
         _fail("source_snapshot must be a non-empty list")
@@ -305,27 +403,121 @@ def _validate_brief_file(
     return brief, raw, brief_path, node_dir, task_dir
 
 
-def _validate_evidence(value: Any) -> set[tuple[str, str]]:
+def _validate_evidence(value: Any) -> set[str]:
     if not isinstance(value, list):
         _fail("report.evidence must be a list")
-    identities: set[tuple[str, str]] = set()
+    identities: set[str] = set()
     for index, item in enumerate(value):
         if not isinstance(item, dict):
             _fail(f"report.evidence[{index}] must be an object")
         evidence_id = _require_text(item.get("id"), f"report.evidence[{index}].id", max_len=128)
-        locator = _require_text(item.get("locator"), f"report.evidence[{index}].locator")
+        _require_text(item.get("locator"), f"report.evidence[{index}].locator")
         _require_text(item.get("summary"), f"report.evidence[{index}].summary")
-        identity = (evidence_id, locator)
-        if identity in identities:
+        if evidence_id in identities:
             _fail("report.evidence contains a duplicate evidence identity")
-        identities.add(identity)
+        identities.add(evidence_id)
     return identities
 
 
+def _validate_id_list(value: Any, field: str) -> list[str]:
+    if not isinstance(value, list):
+        _fail(f"{field} must be a list")
+    result = []
+    for index, item in enumerate(value):
+        result.append(_require_text(item, f"{field}[{index}]", max_len=128))
+    if len(result) != len(set(result)):
+        _fail(f"{field} must not contain duplicates")
+    return result
+
+
+def _validate_typed_notes(value: Any, field: str, evidence: set[str]) -> list[str]:
+    if not isinstance(value, list):
+        _fail(f"report.{field} must be a list")
+    concerns: list[str] = []
+    for index, item in enumerate(value):
+        if not isinstance(item, dict):
+            _fail(f"report.{field}[{index}] must be an object")
+        _require_id(item.get("id"), f"report.{field}[{index}].id")
+        _require_text(item.get("type"), f"report.{field}[{index}].type", max_len=64)
+        _require_text(item.get("detail"), f"report.{field}[{index}].detail")
+        references = _validate_id_list(item.get("evidence_ids", []), f"report.{field}[{index}].evidence_ids")
+        if any(reference not in evidence for reference in references):
+            concerns.append(f"{field}_evidence_unresolved")
+    return concerns
+
+
+def _validate_checkpoint(node_dir: Path, evidence_ids: set[str], scope: list[str]) -> list[str]:
+    worklog_path = node_dir / "worklog.md"
+    if worklog_path.is_symlink():
+        _fail(f"refusing symlinked worklog: {worklog_path}")
+    try:
+        raw = worklog_path.read_bytes()
+    except FileNotFoundError:
+        _fail(f"worklog does not exist: {worklog_path}")
+    except OSError as exc:
+        _fail(f"could not read worklog {worklog_path}: {exc}")
+    if len(raw) > MAX_WORKLOG_BYTES:
+        _fail(f"worklog exceeds the {MAX_WORKLOG_BYTES} byte limit: {worklog_path}")
+    _reject_obvious_secrets(raw, "worklog")
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        _fail(f"worklog is not UTF-8: {worklog_path}")
+    matches = list(CHECKPOINT_RE.finditer(text))
+    if not matches:
+        return ["missing_worklog_checkpoint"]
+    concerns: list[str] = []
+    checkpoint_ids: set[str] = set()
+    checkpoint_scope: set[str] = set()
+    for match in matches:
+        try:
+            checkpoint = json.loads(match.group("payload"))
+        except json.JSONDecodeError:
+            concerns.append("malformed_worklog_checkpoint")
+            continue
+        if not isinstance(checkpoint, dict):
+            concerns.append("malformed_worklog_checkpoint")
+            continue
+        try:
+            checkpoint_id = _require_id(checkpoint.get("id"), "worklog checkpoint.id")
+            if checkpoint_id in checkpoint_ids:
+                concerns.append("duplicate_worklog_checkpoint")
+            checkpoint_ids.add(checkpoint_id)
+            covered_scope = _require_text_list(
+                checkpoint.get("covered_scope"),
+                "worklog checkpoint.covered_scope",
+                allow_empty=True,
+            )
+            for item in covered_scope:
+                if item not in scope:
+                    concerns.append("checkpoint_scope_outside_brief")
+            checkpoint_evidence = _validate_id_list(
+                checkpoint.get("evidence_ids"), "worklog checkpoint.evidence_ids"
+            )
+            if any(item not in evidence_ids for item in checkpoint_evidence):
+                concerns.append("checkpoint_evidence_unresolved")
+            _require_text(
+                checkpoint.get("conclusion_or_blocker"),
+                "worklog checkpoint.conclusion_or_blocker",
+            )
+            _require_text_list(
+                checkpoint.get("unknowns"),
+                "worklog checkpoint.unknowns",
+                allow_empty=True,
+            )
+            _require_text(checkpoint.get("safe_resume_point"), "worklog checkpoint.safe_resume_point")
+            checkpoint_scope.update(covered_scope)
+        except ArtifactError:
+            concerns.append("malformed_worklog_checkpoint")
+    if not set(scope).issubset(checkpoint_scope):
+        concerns.append("checkpoint_scope_incomplete")
+    return sorted(set(concerns))
+
+
 def _validate_report_data(
     report: dict[str, Any],
     brief: dict[str, Any],
-) -> set[tuple[str, str]]:
+) -> tuple[set[str], list[str]]:
     if report.get("schema_version") != SCHEMA_VERSION:
         _fail(f"report.schema_version must be {SCHEMA_VERSION}")
     for field in ("task_id", "work_id", "subnode_id", "role_id"):
@@ -339,25 +531,71 @@ def _validate_report_data(
     if status not in {"complete", "blocked", "incomplete", "error"}:
         _fail("report.status must be complete, blocked, incomplete, or error")
     evidence = _validate_evidence(report.get("evidence"))
-    for field in ("findings", "uncertainties", "corrections"):
-        if not isinstance(report.get(field), list):
-            _fail(f"report.{field} must be a list")
+    assessment = report.get("scope_assessment")
+    if not isinstance(assessment, list) or len(assessment) != len(brief["scope"]):
+        _fail("report.scope_assessment must contain one item for every brief scope item")
+    concerns: list[str] = []
+    for index, item in enumerate(assessment):
+        if not isinstance(item, dict):
+            _fail(f"report.scope_assessment[{index}] must be an object")
+        if item.get("scope") != brief["scope"][index]:
+            _fail(f"report.scope_assessment[{index}].scope does not match brief.scope")
+        if item.get("status") not in {"covered", "inconclusive", "not-started"}:
+            _fail(f"report.scope_assessment[{index}].status is invalid")
+        _require_text(item.get("conclusion"), f"report.scope_assessment[{index}].conclusion")
+        assessment_evidence = _validate_id_list(
+            item.get("evidence_ids"), f"report.scope_assessment[{index}].evidence_ids"
+        )
+        if any(value not in evidence for value in assessment_evidence):
+            concerns.append("scope_assessment_evidence_unresolved")
+        if item["status"] != "covered":
+            concerns.append("incomplete_scope_coverage")
+        if item["status"] == "covered" and not assessment_evidence:
+            concerns.append("covered_scope_without_evidence")
+    findings = report.get("findings")
+    if not isinstance(findings, list):
+        _fail("report.findings must be a list")
+    finding_ids: set[str] = set()
+    for index, item in enumerate(findings):
+        if not isinstance(item, dict):
+            _fail(f"report.findings[{index}] must be an object")
+        finding_id = _require_id(item.get("id"), f"report.findings[{index}].id")
+        if finding_id in finding_ids:
+            _fail("report.findings contains duplicate ids")
+        finding_ids.add(finding_id)
+        _require_text(item.get("conclusion"), f"report.findings[{index}].conclusion")
+        finding_evidence = _validate_id_list(
+            item.get("evidence_ids"), f"report.findings[{index}].evidence_ids"
+        )
+        if not finding_evidence:
+            concerns.append("finding_without_evidence")
+        if any(value not in evidence for value in finding_evidence):
+            concerns.append("finding_evidence_unresolved")
+    concerns.extend(_validate_typed_notes(report.get("uncertainties"), "uncertainties", evidence))
+    concerns.extend(_validate_typed_notes(report.get("corrections"), "corrections", evidence))
     if status == "complete" and not evidence:
         _fail("a complete report requires at least one evidence item")
+    if status == "complete" and not findings:
+        _fail("a complete report requires at least one finding")
     if status != "complete":
-        _require_text_list(
+        completed = _require_text_list(
             report.get("completed_scope"),
             "report.completed_scope",
             allow_empty=True,
         )
+        if len(completed) != len(set(completed)) or any(item not in brief["scope"] for item in completed):
+            _fail("report.completed_scope must contain unique assigned scope items")
+        covered = {item["scope"] for item in assessment if item["status"] == "covered"}
+        if set(completed) != covered:
+            concerns.append("completed_scope_assessment_mismatch")
         _require_text(report.get("blocker"), "report.blocker")
-    return evidence
+    return evidence, sorted(set(concerns))
 
 
 def _validate_report_file(
     value: str,
     repo_root: Path,
-) -> tuple[dict[str, Any], set[tuple[str, str]], dict[str, Any], Path]:
+) -> tuple[dict[str, Any], set[str], dict[str, Any], Path, list[str]]:
     report_path, node_dir, _task_dir = _resolve_artifact_file(value, "report.json", repo_root)
     brief_path = node_dir / "brief.json"
     brief, _brief_raw, _brief_path, _brief_node, _brief_task = _validate_brief_file(
@@ -368,8 +606,9 @@ def _validate_report_file(
         _fail("brief.report_path does not point to the report being validated")
     report, raw = _read_json_object(report_path, MAX_REPORT_BYTES, "report")
     _reject_obvious_secrets(raw, "report")
-    evidence = _validate_report_data(report, brief)
-    return report, evidence, brief, node_dir
+    evidence, concerns = _validate_report_data(report, brief)
+    concerns.extend(_validate_checkpoint(node_dir, evidence, brief["scope"]))
+    return report, evidence, brief, node_dir, sorted(set(concerns))
 
 
 def _validate_disposition_data(
@@ -407,6 +646,29 @@ def _validate_disposition_data(
     _require_text(disposition.get("decided_at"), "disposition.decided_at", max_len=128)
 
 
+def _validate_unit_plan(brief: dict[str, Any], task_dir: Path, repo_root: Path) -> None:
+    """New dispatch admission only; historical report readers remain compatible."""
+    plan = brief.get("unit_plan")
+    if not isinstance(plan, dict):
+        _fail("new evidence unit requires unit_plan")
+    reference = _require_text(plan.get("plan_ref"), "unit_plan.plan_ref", max_len=1024)
+    locator = reference.partition("#")[0]
+    relative = Path(locator)
+    if relative.is_absolute() or ".." in relative.parts or "\\" in locator:
+        _fail("unit_plan.plan_ref must be a repository-relative task document")
+    document = repo_root / relative
+    lexical_task = _task_lexical_from_resolved(task_dir, repo_root)
+    _assert_no_subpath_symlinks(lexical_task, document)
+    if not document.is_file() or document.suffix != ".md":
+        _fail("unit_plan.plan_ref must identify a regular document in this task")
+    if document.stat().st_size > MAX_REPORT_BYTES:
+        _fail("unit_plan.plan_ref document exceeds the byte limit")
+    _require_text(document.read_text(encoding="utf-8"), "unit_plan.plan_ref document", max_len=MAX_REPORT_BYTES)
+    _require_text(plan.get("sizing_rationale"), "unit_plan.sizing_rationale")
+    if len(brief["scope"]) > 1:
+        _require_text(plan.get("grouping_rationale"), "unit_plan.grouping_rationale")
+
+
 def _init(args: argparse.Namespace) -> None:
     repo_root = get_repo_root()
     task_dir = resolve_task_dir(args.task, repo_root)
@@ -434,13 +696,14 @@ def _init(args: argparse.Namespace) -> None:
     brief["role_id"] = "subnode"
     brief["report_path"] = _relative_to_repo(node_dir / "report.json", repo_root)
     _validate_brief_data(brief, task_dir, node_dir, repo_root)
+    _validate_unit_plan(brief, task_dir, repo_root)
     for directory in (task_dir / "subnodes", task_dir / "subnodes" / work_id, node_dir):
         if directory.is_symlink():
             _fail(f"refusing symlinked artifact directory: {directory}")
         if directory.exists() and not directory.is_dir():
             _fail(f"artifact path component is not a directory: {directory}")
         try:
-            directory.mkdir(exist_ok=True)
+            directory.mkdir(exist_ok=directory != node_dir)
         except OSError as exc:
             _fail(f"could not create artifact directory {directory}: {exc}")
     brief_path = node_dir / "brief.json"
@@ -464,15 +727,171 @@ def _init(args: argparse.Namespace) -> None:
     }))
 
 
+def _queue_init(args: argparse.Namespace) -> None:
+    repo_root, task_id, task_dir, queue_path, abandoned_path = _queue_context(args)
+    if queue_path.exists() or abandoned_path.exists():
+        _fail("queue already exists or has been abandoned")
+    if not args.brief:
+        _fail("queue init requires at least one --brief")
+    work_id = _require_id(args.work_id, "--work-id")
+    channel_name = _require_text(args.channel_name, "--channel-name", max_len=128)
+    channel_scope = _require_text(args.channel_scope, "--channel-scope", max_len=32)
+    if channel_scope not in {"project", "global"}:
+        _fail("--channel-scope must be project or global")
+    items: list[dict[str, str]] = []
+    seen: set[str] = set()
+    for brief_arg in args.brief:
+        brief, raw, brief_path, node_dir, brief_task_dir = _validate_brief_file(
+            brief_arg, repo_root
+        )
+        subnode_id = _require_id(brief.get("subnode_id"), "brief.subnode_id")
+        if brief_task_dir != task_dir:
+            _fail(f"queue item {subnode_id} brief belongs to another task")
+        _validate_unit_plan(brief, task_dir, repo_root)
+        if brief.get("work_id") != work_id:
+            _fail(f"queue item {subnode_id} brief belongs to another work")
+        if subnode_id in seen:
+            _fail("queue init contains duplicate subnode_id values")
+        if brief.get("channel_ref", {}).get("name") != channel_name:
+            _fail(f"queue item {subnode_id} channel name does not match")
+        if brief.get("channel_ref", {}).get("scope") != channel_scope:
+            _fail(f"queue item {subnode_id} channel scope does not match")
+        expected_path = _relative_to_repo(node_dir / "brief.json", repo_root)
+        if _relative_to_repo(brief_path, repo_root) != expected_path:
+            _fail(f"queue item {subnode_id} brief path is not canonical")
+        seen.add(subnode_id)
+        items.append({
+            "subnode_id": subnode_id,
+            "brief_path": expected_path,
+            "brief_digest": hashlib.sha256(raw).hexdigest(),
+        })
+    queue = {
+        "schema_version": 1,
+        "task_id": task_id,
+        "work_id": work_id,
+        "channel_ref": {"name": channel_name, "scope": channel_scope},
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "items": items,
+    }
+    _write_json_exclusive(queue_path, queue, "queue")
+    print(json.dumps({"queue": _relative_to_repo(queue_path, repo_root), "items": items}))
+
+
+def _queue_validate(args: argparse.Namespace) -> None:
+    repo_root, task_id, task_dir, queue_path, abandoned_path = _queue_context(args)
+    _queue, items = _validate_queue_file(
+        queue_path, task_dir, task_id, args.work_id, repo_root
+    )
+    print(json.dumps({
+        "status": "abandoned" if abandoned_path.exists() else "valid",
+        "queue": _relative_to_repo(queue_path, repo_root),
+        "task_id": task_id,
+        "work_id": args.work_id,
+        "items": items,
+        "item_count": len(items),
+    }))
+
+
+def _queue_claim(args: argparse.Namespace) -> None:
+    repo_root, task_id, task_dir, queue_path, abandoned_path = _queue_context(args)
+    if abandoned_path.exists():
+        _fail("queue has been abandoned; no further dispatch claim is allowed")
+    _queue, items = _validate_queue_file(
+        queue_path, task_dir, task_id, args.work_id, repo_root
+    )
+    subnode_id = _require_id(args.subnode_id, "--subnode-id")
+    item = next((candidate for candidate in items if candidate["subnode_id"] == subnode_id), None)
+    if item is None:
+        _fail(f"subnode is not listed in the queue: {subnode_id}")
+    for previous in items:
+        if previous is item:
+            break
+        previous_claim = task_dir / "subnodes" / args.work_id / previous["subnode_id"] / "dispatch-claim.json"
+        _assert_no_subpath_symlinks(task_dir, previous_claim)
+        if not previous_claim.is_file():
+            _fail(f"FIFO requires claiming earlier unit first: {previous['subnode_id']}")
+    claim_path = task_dir / "subnodes" / args.work_id / subnode_id / "dispatch-claim.json"
+    _assert_no_subpath_symlinks(task_dir, claim_path)
+    claim = {
+        "schema_version": 1,
+        "task_id": task_id,
+        "work_id": args.work_id,
+        "subnode_id": subnode_id,
+        "brief_digest": item["brief_digest"],
+        "claimed_at": datetime.now(timezone.utc).isoformat(),
+    }
+    _write_json_exclusive(claim_path, claim, "dispatch claim")
+    print(json.dumps({
+        "claim": _relative_to_repo(claim_path, repo_root),
+        "subnode_id": subnode_id,
+        "brief_digest": item["brief_digest"],
+    }))
+
+
+def _queue_abandon(args: argparse.Namespace) -> None:
+    repo_root, task_id, task_dir, queue_path, abandoned_path = _queue_context(args)
+    _queue, items = _validate_queue_file(
+        queue_path, task_dir, task_id, args.work_id, repo_root
+    )
+    item_ids = {item["subnode_id"] for item in items}
+    claimed_ids: set[str] = set()
+    for item in items:
+        subnode_id = item["subnode_id"]
+        claim_path = task_dir / "subnodes" / args.work_id / subnode_id / "dispatch-claim.json"
+        _assert_no_subpath_symlinks(task_dir, claim_path)
+        if not claim_path.exists():
+            continue
+        claim, _raw = _read_json_object(claim_path, MAX_DRAFT_BYTES, "dispatch claim")
+        if (
+            claim.get("schema_version") != 1
+            or claim.get("task_id") != task_id
+            or claim.get("work_id") != args.work_id
+            or claim.get("subnode_id") != subnode_id
+            or claim.get("brief_digest") != item["brief_digest"]
+        ):
+            _fail(f"dispatch claim does not match queue item {subnode_id}")
+        claimed_ids.add(subnode_id)
+    dispatched = [_require_id(value, "--dispatched") for value in (args.dispatched or [])]
+    pending = [_require_id(value, "--pending") for value in (args.pending or [])]
+    if len(set(dispatched)) != len(dispatched) or len(set(pending)) != len(pending):
+        _fail("queue abandonment lists must not contain duplicates")
+    if not set(dispatched).issubset(item_ids) or not set(pending).issubset(item_ids):
+        _fail("queue abandonment lists must contain only queued subnode IDs")
+    if set(dispatched) & set(pending):
+        _fail("a subnode cannot be both dispatched and pending")
+    if set(dispatched) != claimed_ids or set(pending) != item_ids - claimed_ids:
+        _fail("queue abandonment lists must exactly match dispatch claims and remaining queued items")
+    abandoned = {
+        "schema_version": 1,
+        "task_id": task_id,
+        "work_id": args.work_id,
+        "reason": _require_text(args.reason, "--reason"),
+        "dispatched": dispatched,
+        "pending": pending,
+        "abandoned_at": datetime.now(timezone.utc).isoformat(),
+    }
+    _write_json_exclusive(abandoned_path, abandoned, "queue abandonment")
+    print(json.dumps({"status": "abandoned", "queue": _relative_to_repo(abandoned_path, repo_root)}))
+
+
 def _validate(args: argparse.Namespace) -> None:
     repo_root = get_repo_root()
-    report, _evidence, _brief, _node_dir_value = _validate_report_file(args.report, repo_root)
+    report, _evidence, _brief, _node_dir_value, concerns = _validate_report_file(args.report, repo_root)
+    if concerns:
+        print(json.dumps({
+            "status": "review_concern",
+            "subnode_id": report["subnode_id"],
+            "concerns": concerns,
+        }))
+        return
     print(f"Validated pending-review report: {report['subnode_id']}")
 
 
 def _disposition(args: argparse.Namespace) -> None:
     repo_root = get_repo_root()
-    report, _evidence, brief, node_dir = _validate_report_file(args.report, repo_root)
+    report, _evidence, brief, node_dir, concerns = _validate_report_file(args.report, repo_root)
+    if args.outcome == "accepted" and (report["status"] != "complete" or concerns):
+        _fail("cannot accept a non-complete report or unresolved validation concerns: " + ", ".join(concerns))
     disposition_path = node_dir / "disposition.json"
     if disposition_path.exists() or disposition_path.is_symlink():
         _fail(f"disposition already exists and cannot be replaced: {disposition_path}")
@@ -514,10 +933,10 @@ def _validate_counter(args: argparse.Namespace) -> None:
         primary_dir = repo_root / primary_dir
     if not counter_dir.is_absolute():
         counter_dir = repo_root / counter_dir
-    primary_report, primary_evidence, primary_brief, primary_node = _validate_report_file(
+    primary_report, primary_evidence, primary_brief, primary_node, _primary_concerns = _validate_report_file(
         str(primary_dir / "report.json"), repo_root
     )
-    counter_report, counter_evidence, counter_brief, counter_node = _validate_report_file(
+    counter_report, counter_evidence, counter_brief, counter_node, _counter_concerns = _validate_report_file(
         str(counter_dir / "report.json"), repo_root
     )
     if primary_node == counter_node:
@@ -580,6 +999,36 @@ def _parser() -> argparse.ArgumentParser:
     counter.add_argument("--primary", required=True, help="primary subnode artifact directory")
     counter.add_argument("--counter", required=True, help="counter subnode artifact directory")
     counter.set_defaults(handler=_validate_counter)
+
+    queue = subparsers.add_parser("queue", help="manage one write-once subnode queue")
+    queue_parsers = queue.add_subparsers(dest="queue_command", required=True)
+
+    queue_init = queue_parsers.add_parser("init", help="write one FIFO queue manifest")
+    queue_init.add_argument("--task", required=True)
+    queue_init.add_argument("--work-id", required=True)
+    queue_init.add_argument("--channel-name", required=True)
+    queue_init.add_argument("--channel-scope", required=True)
+    queue_init.add_argument("--brief", action="append", required=True)
+    queue_init.set_defaults(handler=_queue_init)
+
+    queue_validate = queue_parsers.add_parser("validate", help="validate a queue manifest")
+    queue_validate.add_argument("--task", required=True)
+    queue_validate.add_argument("--work-id", required=True)
+    queue_validate.set_defaults(handler=_queue_validate)
+
+    queue_claim = queue_parsers.add_parser("claim", help="write one dispatch intent")
+    queue_claim.add_argument("--task", required=True)
+    queue_claim.add_argument("--work-id", required=True)
+    queue_claim.add_argument("--subnode-id", required=True)
+    queue_claim.set_defaults(handler=_queue_claim)
+
+    queue_abandon = queue_parsers.add_parser("abandon", help="stop a queue permanently")
+    queue_abandon.add_argument("--task", required=True)
+    queue_abandon.add_argument("--work-id", required=True)
+    queue_abandon.add_argument("--reason", required=True)
+    queue_abandon.add_argument("--dispatched", action="append")
+    queue_abandon.add_argument("--pending", action="append")
+    queue_abandon.set_defaults(handler=_queue_abandon)
     return parser