@pennixrv/trellis 0.7.1 → 0.7.2-beta.0

package/dist/templates/trellis/scripts/common/active_task.py

@@ -201,54 +201,10 @@ def normalize_task_ref(task_ref: str) -> str:
 
 
 def resolve_task_ref(task_ref: str, repo_root: Path) -> Path | None:
-    """Resolve a task ref to an absolute task directory inside the repo.
+    """Use the canonical status-layout resolver shared by all task readers."""
+    from .paths import resolve_task_ref as resolve
 
-    Mirrors `paths.resolve_task_ref` (same containment check). Duplicated
-    rather than imported because this module is loaded standalone — hooks add
-    it to `sys.path` directly — so it stays zero-relative-import on purpose.
-    """
-    normalized = normalize_task_ref(task_ref)
-    if not normalized:
-        return None
-
-    try:
-        root = repo_root.resolve()
-    except OSError:
-        return None
-
-    path_obj = Path(normalized)
-    if path_obj.is_absolute():
-        candidate = path_obj
-    elif normalized.startswith(f"{DIR_WORKFLOW}/"):
-        candidate = root / path_obj
-    else:
-        candidate = root / DIR_WORKFLOW / DIR_TASKS / path_obj
-
-    # Both sides are resolved because repo_root itself may sit behind a
-    # symlink (/tmp on macOS does), and resolve() is what collapses `..`
-    # instead of leaving it for a lexical relative_to() to wave through.
-    try:
-        resolved = candidate.resolve()
-        workflow_real = (root / DIR_WORKFLOW).resolve()
-    except OSError:
-        return None
-
-    try:
-        resolved.relative_to(root)
-        return resolved
-    except ValueError:
-        pass
-
-    # `.trellis` may itself be a symlink into a store outside the repo (#567).
-    # The workflow dir's own real location is then a second legitimate
-    # containment base; a ref that escapes BOTH bases is still refused. Map
-    # back to the in-repo (lexical) form so callers store a repo-relative ref.
-    try:
-        rel = resolved.relative_to(workflow_real)
-    except ValueError:
-        return None
-
-    return root / DIR_WORKFLOW / rel
+    return resolve(task_ref, repo_root)
 
 
 def _runtime_sessions_dir(repo_root: Path) -> Path:

package/dist/templates/trellis/scripts/common/paths.py

@@ -344,35 +344,19 @@ def resolve_task_ref(task_ref: str, repo_root: Path | None = None) -> Path | Non
     else:
         candidate = root / DIR_WORKFLOW / DIR_TASKS / path_obj
 
-    # resolve() collapses `..` and follows symlinks, so a task directory that
-    # links outside the repo is refused too. Both sides are resolved because
-    # repo_root itself may sit behind a symlink (/tmp on macOS does).
-    try:
-        resolved = candidate.resolve()
-        workflow_real = (root / DIR_WORKFLOW).resolve()
-    except OSError:
-        return None
+    from .task_layout import task_status_dir
+    from .task_move import require_settled_layout
 
     try:
-        resolved.relative_to(root)
-        return resolved
-    except ValueError:
-        pass
-
-    # `.trellis` may itself be a symlink into a store outside the repo (#567).
-    # The workflow dir's own real location is then a second legitimate
-    # containment base: a ref through that link never left the workflow tree.
-    # A ref that escapes BOTH bases (traversal, absolute path elsewhere, a
-    # task dir symlinked out of the tree) is still refused.
-    try:
-        rel = resolved.relative_to(workflow_real)
-    except ValueError:
+        require_settled_layout(root)
+        tasks = root / DIR_WORKFLOW / DIR_TASKS
+        if task_status_dir(candidate, tasks) is None:
+            return None
+        relative = candidate.resolve().relative_to(tasks.resolve())
+        return tasks / relative
+    except (ValueError, OSError, RuntimeError):
         return None
 
-    # Map back to the in-repo (lexical) form so callers store the same
-    # repo-relative ref as in the non-symlinked layout.
-    return root / DIR_WORKFLOW / rel
-
 
 def get_current_task(
     repo_root: Path | None = None,

package/dist/templates/trellis/scripts/common/safe_commit.py

@@ -70,7 +70,7 @@ def safe_trellis_paths_to_add(
     Included:
       - .trellis/workspace/<developer>/journal-*.md
       - .trellis/workspace/<developer>/index.md
-      - .trellis/tasks/<task_name>/   (ONLY the current task dir when
+      - .trellis/tasks/<task-dir>/   (ONLY the current task dir when
         ``task_name`` is passed)
 
     Excluded (intentionally — these must not be staged):
@@ -112,16 +112,16 @@ def safe_trellis_paths_to_add(
         # Narrow scope — ONLY the current task directory.
         # Never iterdir() all tasks: parallel-window dirty task dirs must not
         # leak into the session auto-commit.
-        active_task = tasks_dir / task_name
-        if active_task.is_dir():
-            paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{task_name}")
+        from .task_utils import find_task_by_name
+        active_task = find_task_by_name(task_name, tasks_dir)
+        if active_task is not None and active_task.is_dir():
+            paths.append(active_task.relative_to(repo_root).as_posix())
         return paths
 
     # Wide scope (no task_name): each direct task directory.
-    for child in sorted(tasks_dir.iterdir()):
-        if not child.is_dir():
-            continue
-        paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{child.name}")
+    from .task_layout import iter_task_dirs
+    for child in iter_task_dirs(tasks_dir):
+        paths.append(child.relative_to(repo_root).as_posix())
 
     return paths
 

package/dist/templates/trellis/scripts/common/task_context.py

@@ -29,7 +29,7 @@ from .config import get_context_injection_limits
 from .git import branch_exists_locally
 from .io import read_json
 from .log import Colors, colored
-from .paths import DIR_TASKS, DIR_WORKFLOW, FILE_TASK_JSON, get_repo_root
+from .paths import FILE_TASK_JSON, get_repo_root
 from .task_utils import resolve_task_dir
 
 # Extensions that look like code rather than spec/research docs. Entries with
@@ -195,54 +195,6 @@ def _is_exempt_from_code_file_warning(file_path: str, task_rel: str) -> bool:
     return False
 
 
-def _resolve_context_entry_path(
-    file_path: str, repo_root: Path, task_dir: Path | None
-) -> Path | None:
-    """Bind historical self-references to their archive copy without fallback."""
-    repo_path = repo_root / file_path
-    if task_dir is None:
-        return repo_path
-
-    try:
-        task_parts = task_dir.resolve().relative_to(repo_root.resolve()).parts
-    except ValueError:
-        return repo_path
-
-    archive_prefix = (DIR_WORKFLOW, DIR_TASKS, "archive")
-    if len(task_parts) != 5 or task_parts[:3] != archive_prefix:
-        return repo_path
-
-    year_month = task_parts[3]
-    if (
-        len(year_month) != 7
-        or year_month[4] != "-"
-        or not year_month[:4].isdigit()
-        or not year_month[5:].isdigit()
-    ):
-        return repo_path
-
-    historical_root = f"{DIR_WORKFLOW}/{DIR_TASKS}/{task_dir.name}"
-    posix_path = file_path.replace("\\", "/")
-    if posix_path == historical_root:
-        relative_parts: tuple[str, ...] = ()
-    elif posix_path.startswith(f"{historical_root}/"):
-        relative_path = posix_path[len(historical_root) + 1 :]
-        if relative_path.endswith("/"):
-            relative_path = relative_path[:-1]
-        relative_parts = tuple(relative_path.split("/")) if relative_path else ()
-        if any(part in ("", ".", "..") for part in relative_parts):
-            return None
-    else:
-        return repo_path
-
-    try:
-        archive_root = task_dir.resolve()
-        resolved_path = task_dir.joinpath(*relative_parts).resolve()
-        resolved_path.relative_to(archive_root)
-    except (OSError, RuntimeError, ValueError):
-        return None
-    return resolved_path
-
 
 def _validate_jsonl(jsonl_file: Path, repo_root: Path, task_dir: Path | None = None) -> int:
     """Validate a single JSONL file.
@@ -268,7 +220,7 @@ def _validate_jsonl(jsonl_file: Path, repo_root: Path, task_dir: Path | None = N
     task_rel = ""
     if task_dir is not None:
         try:
-            task_rel = task_dir.resolve().relative_to(repo_root.resolve()).as_posix()
+            task_rel = task_dir.absolute().relative_to(repo_root.absolute()).as_posix()
         except ValueError:
             task_rel = ""
 
@@ -323,7 +275,15 @@ def _validate_jsonl(jsonl_file: Path, repo_root: Path, task_dir: Path | None = N
             continue
 
         real_entries += 1
-        full_path = _resolve_context_entry_path(file_path, repo_root, task_dir)
+        full_path = repo_root / file_path
+        normalized = file_path.replace("\\", "/")
+        if task_dir is not None and task_rel and (normalized == task_rel or normalized.startswith(task_rel + "/")):
+            try:
+                if ".." in Path(normalized).parts:
+                    raise ValueError("Traversal in task reference")
+                full_path.resolve().relative_to(task_dir.resolve())
+            except (ValueError, OSError, RuntimeError):
+                full_path = None
         if entry_type == "directory":
             if full_path is None or not full_path.is_dir():
                 print(f"  {colored(f'{file_name}:{line_num}: Directory not found: {file_path}', Colors.RED)}")

package/dist/templates/trellis/scripts/common/task_continuity.py

@@ -298,8 +298,10 @@ def _load_owner(path: Path) -> dict | None:
     if record is None:
         return None
     required = {"schema_version", "task_id", "task_path", "package_id", "package_digest", "generation", "status", "source_session_id", "target_session_id", "continuity_digest", "route"}
-    if set(record) != required or record.get("schema_version") != 1 or not isinstance(record.get("generation"), int):
+    if not required.issubset(record) or set(record) - required - {"target_continuity_digest", "recovery_history"} or record.get("schema_version") != 1 or not isinstance(record.get("generation"), int):
         raise ContinuityError("TASK_TRANSFER_WITHHELD", "ownership record has an invalid shape")
+    if "target_continuity_digest" in record and (not isinstance(record["target_continuity_digest"], str) or not PACKAGE_DIGEST_RE.fullmatch(record["target_continuity_digest"])):
+        raise ContinuityError("TASK_TRANSFER_WITHHELD", "target continuity digest is invalid")
     return record
 
 
@@ -311,6 +313,10 @@ def transfer_task_ownership(args: argparse.Namespace) -> int:
     root = get_repo_root()
     operation = args.transfer_action
     try:
+        package_bound = args.package_id is not None or args.package_digest is not None
+        if operation != "status" or package_bound:
+            if not isinstance(args.package_id, str) or not PACKAGE_ID_RE.fullmatch(args.package_id) or not isinstance(args.package_digest, str) or not PACKAGE_DIGEST_RE.fullmatch(args.package_digest):
+                raise ContinuityError("TASK_TRANSFER_INVALID_INPUT", "session package identity and SHA-256 digest are required")
         task_dir = resolve_task_dir(args.task_path, root)
         if task_dir is None or not is_within_tasks_dir(task_dir, root):
             raise ContinuityError("TASK_TRANSFER_WITHHELD", "task path is unavailable or unsafe")
@@ -326,10 +332,15 @@ def transfer_task_ownership(args: argparse.Namespace) -> int:
         path = _ownership_path(root, task_path)
         with _record_lock(path):
             record = _load_owner(path)
+            if record and (record["task_id"] != task_id or record["task_path"] != task_path):
+                raise ContinuityError("TASK_TRANSFER_WITHHELD", "ownership record does not match the requested task")
             if operation == "status":
-                if record and (record["package_id"] != args.package_id or record["package_digest"] != args.package_digest):
+                if record and package_bound and (record["package_id"] != args.package_id or record["package_digest"] != args.package_digest):
                     raise ContinuityError("TASK_TRANSFER_STALE_PACKAGE", "session package identity or digest changed")
                 result = record or {"status": "absent", "generation": 0, "task_id": task_id}
+                if args.include_current:
+                    current = _projection(root, task_dir, data, task_id)
+                    result = {**result, "current_continuity_digest": _digest(current), "current_projection": current}
                 print(json.dumps(result, ensure_ascii=False, sort_keys=True))
                 return 0
             if not args.explicit_user_request:
@@ -337,8 +348,6 @@ def transfer_task_ownership(args: argparse.Namespace) -> int:
             if args.expected_generation is None or args.expected_generation < 0:
                 raise ContinuityError("TASK_TRANSFER_INVALID_INPUT", "a non-negative expected generation is required")
             if operation == "quiesce":
-                if not PACKAGE_ID_RE.fullmatch(args.package_id) or not PACKAGE_DIGEST_RE.fullmatch(args.package_digest):
-                    raise ContinuityError("TASK_TRANSFER_INVALID_INPUT", "session package identity or SHA-256 digest is invalid")
                 context_key, current_path = _direct_pointer(root, task_path)
                 if current_path is None:
                     raise ContinuityError("TASK_TRANSFER_WITHHELD", "source session has no current task")
@@ -355,13 +364,18 @@ def transfer_task_ownership(args: argparse.Namespace) -> int:
                         result = record
                         print(json.dumps(result, ensure_ascii=False, sort_keys=True))
                         return 0
-                    raise ContinuityError("TASK_TRANSFER_STALE_GENERATION", "task already has an ownership record")
-                if args.expected_generation != 0:
+                    if record["status"] != "consumed" or record["generation"] != args.expected_generation:
+                        raise ContinuityError("TASK_TRANSFER_STALE_GENERATION", "task already has an ownership record at a different state or generation")
+                    if record["target_session_id"] != context_key:
+                        raise ContinuityError("TASK_TRANSFER_WITHHELD", "only the consumed target can start another handoff")
+                    if record["package_id"] == args.package_id:
+                        raise ContinuityError("TASK_TRANSFER_STALE_PACKAGE", "another handoff requires a new session package")
+                elif args.expected_generation != 0:
                     raise ContinuityError("TASK_TRANSFER_STALE_GENERATION", "initial ownership generation must be 0")
                 record = {
                     "schema_version": 1, "task_id": task_id, "task_path": task_path,
                     "package_id": args.package_id, "package_digest": args.package_digest,
-                    "generation": 1, "status": "quiescing", "source_session_id": context_key,
+                    "generation": args.expected_generation + 1, "status": "quiescing", "source_session_id": context_key,
                     "target_session_id": None, "continuity_digest": continuity_digest,
                     "route": _route_snapshot(data),
                 }
@@ -372,11 +386,50 @@ def transfer_task_ownership(args: argparse.Namespace) -> int:
                     raise ContinuityError("TASK_TRANSFER_STALE_PACKAGE", "session package identity or digest changed")
                 if args.expected_generation != record["generation"]:
                     raise ContinuityError("TASK_TRANSFER_STALE_GENERATION", f"expected generation {args.expected_generation}, current generation is {record['generation']}")
-                if operation != "release" and _current_projection_digest(root, task_dir, data, task_id) != record["continuity_digest"]:
+                current_digest = (
+                    _current_projection_digest(root, task_dir, data, task_id)
+                    if operation != "release" else record["continuity_digest"]
+                )
+                if args.expected_continuity_digest is not None:
+                    if not PACKAGE_DIGEST_RE.fullmatch(args.expected_continuity_digest):
+                        raise ContinuityError("TASK_TRANSFER_INVALID_INPUT", "expected continuity digest must be a SHA-256 digest")
+                    if args.expected_continuity_digest != current_digest:
+                        raise ContinuityError("TASK_TRANSFER_STALE_CONTINUITY", "current task projection differs from the explicitly checked snapshot")
+                # Recovery acknowledges a live target snapshot without rebasing the source package.
+                recovered_claim = (
+                    operation == "claim" and record["status"] == "sealed"
+                    and args.expected_continuity_digest == current_digest
+                )
+                if operation not in {"release", "recover"} and current_digest != record.get("target_continuity_digest", record["continuity_digest"]) and not recovered_claim:
                     raise ContinuityError("TASK_TRANSFER_STALE_CONTINUITY", "task continuity changed during ownership transfer")
                 if operation != "release" and _route_snapshot(data) != record["route"]:
                     raise ContinuityError("TASK_TRANSFER_STALE_ROUTE", "task phase, route, input, or implementation authorization changed")
                 context_key, current_path = _direct_pointer(root)
+                if operation == "recover":
+                    if record["status"] not in {"claiming", "claimed", "recovery_required"} or not isinstance(args.reason, str) or not args.reason.strip() or args.expected_continuity_digest != current_digest:
+                        raise ContinuityError("TASK_TRANSFER_INVALID_TRANSITION", "explicit recovery requires a pending target, a reason, and the current projection digest")
+                    if current_path not in {None, record["task_path"]}:
+                        raise ContinuityError("TASK_TRANSFER_WITHHELD", "recovery session already has another active task")
+                    from .task_workflow import _assert_delegated_resources_closed
+                    try:
+                        _assert_delegated_resources_closed(task_dir, data)
+                    except TaskWorkflowError as error:
+                        raise ContinuityError("TASK_TRANSFER_RECOVERY_REQUIRED", str(error)) from error
+                    teammates_dir = task_dir / "teammates"
+                    if any(teammates_dir.rglob("queue.json")) or any(teammates_dir.rglob("claim.json")):
+                        raise ContinuityError("TASK_TRANSFER_RECOVERY_REQUIRED", "managed teamwork runtime artifacts remain; reconcile the original batch first")
+                    record.setdefault("recovery_history", []).append({"generation": record["generation"], "status": record["status"], "target_session_id": record["target_session_id"], "requested_by": context_key, "reason": args.reason})
+                    record.update({"status": "recovery_required", "generation": record["generation"] + 1, "target_continuity_digest": current_digest})
+                    if not write_json(path, record):
+                        raise ContinuityError("TASK_TRANSFER_WRITE_FAILED", "could not fence the previous generation before recovery")
+                    for session in {record["source_session_id"], record["target_session_id"]} - {None}:
+                        if not clear_active_task_if_matches(root, session, record["task_path"]):
+                            raise ContinuityError("TASK_TRANSFER_RECOVERY_REQUIRED", "a prior session pointer changed; preserve the current generation")
+                    record.update({"status": "ready", "target_session_id": None})
+                    if not write_json(path, record):
+                        raise ContinuityError("TASK_TRANSFER_WRITE_FAILED", "could not persist explicit recovery")
+                    print(json.dumps(record, ensure_ascii=False, sort_keys=True))
+                    return 0
                 if operation in {"seal", "retire"}:
                     if context_key != record["source_session_id"] or current_path not in {record["task_path"], None}:
                         raise ContinuityError("TASK_TRANSFER_WITHHELD", "source session no longer owns the current task")
@@ -412,13 +465,15 @@ def transfer_task_ownership(args: argparse.Namespace) -> int:
                         write_json(path, record)
                         raise ContinuityError("TASK_TRANSFER_RECOVERY_REQUIRED", "source pointer remains after retirement")
                     record["status"] = "ready"
-                elif operation == "claim" and record["status"] in {"ready", "claiming", "recovery_required", "claimed"}:
-                    if record["status"] == "recovery_required" and record["target_session_id"] != context_key:
+                elif operation == "claim" and (record["status"] in {"ready", "claiming", "recovery_required", "claimed"} or recovered_claim):
+                    if record["status"] in {"claiming", "recovery_required"} and record["target_session_id"] != context_key:
                         raise ContinuityError("TASK_TRANSFER_WITHHELD", "only the recorded target session can recover a claim")
                     if current_path not in {None, record["task_path"]}:
                         raise ContinuityError("TASK_TRANSFER_WITHHELD", "target session already has a current task")
-                    if record["status"] == "ready":
+                    if record["status"] in {"ready", "sealed"}:
                         record.update({"status": "claiming", "generation": record["generation"] + 1, "target_session_id": context_key})
+                        if recovered_claim:
+                            record["target_continuity_digest"] = current_digest
                         if not write_json(path, record):
                             raise ContinuityError("TASK_TRANSFER_WRITE_FAILED", "could not record target claim")
                     elif record["status"] == "claimed":
@@ -430,6 +485,10 @@ def transfer_task_ownership(args: argparse.Namespace) -> int:
                         record.update({"status": "claiming", "generation": record["generation"] + 1, "target_session_id": context_key})
                         if not write_json(path, record):
                             raise ContinuityError("TASK_TRANSFER_WRITE_FAILED", "could not record target takeover")
+                    if not clear_active_task_if_matches(root, record["source_session_id"], record["task_path"]):
+                        record["status"] = "recovery_required"
+                        write_json(path, record)
+                        raise ContinuityError("TASK_TRANSFER_RECOVERY_REQUIRED", "source pointer could not be retired during claim")
                     if current_path is None and not compare_and_set_active_task(root, context_key, None, record["task_path"]):
                         record["status"] = "recovery_required"
                         write_json(path, record)
@@ -463,13 +522,15 @@ def add_continuity_commands(subparsers) -> None:
     capture.add_argument("--expected-source-digest", required=True, help="Current captured digest, or absent")
 
     transfer = subparsers.add_parser("transfer", help="Transfer task ownership between direct sessions")
-    transfer.add_argument("transfer_action", choices=("status", "quiesce", "seal", "retire", "claim", "consume", "release"))
+    transfer.add_argument("transfer_action", choices=("status", "quiesce", "seal", "retire", "claim", "consume", "release", "recover"))
+    transfer.add_argument("--reason", help="Explicit recovery reason")
     transfer.add_argument("--task-id", required=True)
     transfer.add_argument("--task-path", required=True)
-    transfer.add_argument("--package-id", required=True)
-    transfer.add_argument("--package-digest", required=True)
-    transfer.add_argument("--expected-continuity-digest")
+    transfer.add_argument("--package-id", help="Required with --package-digest for mutations or package-bound status")
+    transfer.add_argument("--package-digest", help="Required with --package-id for mutations or package-bound status")
+    transfer.add_argument("--expected-continuity-digest", help="Expected live projection for sealed-source claim recovery")
     transfer.add_argument("--expected-generation", type=int)
+    transfer.add_argument("--include-current", action="store_true", help="Include the live task projection and its digest in transfer status")
     transfer.add_argument("--explicit-user-request", action="store_true")
 
 
@@ -489,35 +550,39 @@ def clear_task_runtime_records(repo_root: Path, task_path: str) -> bool:
 @contextlib.contextmanager
 def active_task_change_guard(repo_root: Path, context_key: str, task_path: str, *, clearing: bool):
     """Serialize pointer writes with ownership changes for the same task."""
-    directory = resolve_task_dir(task_path, repo_root)
-    if directory is None:
-        yield False
-        return
-    task_path = directory.relative_to(repo_root).as_posix()
-    path = _ownership_path(repo_root, task_path)
-    with _record_lock(path):
-        try:
-            record = _load_owner(path)
-        except ContinuityError:
-            yield False
-            return
-        if record is None:
-            yield True
-            return
-        data, _ = read_json_checked(directory / FILE_TASK_JSON)
-        task_id = (data.get("id") or data.get("name")) if isinstance(data, dict) else None
-        if task_id != record["task_id"] or record["task_path"] != task_path:
+    from .task_move import layout_lock, require_settled_layout
+
+    with layout_lock(repo_root):
+        require_settled_layout(repo_root)
+        directory = resolve_task_dir(task_path, repo_root)
+        if directory is None:
             yield False
             return
-        if clearing:
-            allowed = record["status"] == "consumed" and record["target_session_id"] == context_key
-        elif record["status"] == "ready":
-            allowed = context_key != record["source_session_id"] and task_path == record["task_path"]
-        elif record["status"] == "consumed":
-            allowed = context_key == record["target_session_id"] and task_path == record["task_path"]
-        else:
-            allowed = record["status"] in {"claiming", "claimed"} and context_key == record["target_session_id"] and task_path == record["task_path"]
-        yield allowed
+        task_path = directory.relative_to(repo_root).as_posix()
+        path = _ownership_path(repo_root, task_path)
+        with _record_lock(path):
+            try:
+                record = _load_owner(path)
+            except ContinuityError:
+                yield False
+                return
+            if record is None:
+                yield True
+                return
+            data, _ = read_json_checked(directory / FILE_TASK_JSON)
+            task_id = (data.get("id") or data.get("name")) if isinstance(data, dict) else None
+            if task_id != record["task_id"] or record["task_path"] != task_path:
+                yield False
+                return
+            if clearing:
+                allowed = record["status"] == "consumed" and record["target_session_id"] == context_key
+            elif record["status"] == "ready":
+                allowed = context_key != record["source_session_id"] and task_path == record["task_path"]
+            elif record["status"] == "consumed":
+                allowed = context_key == record["target_session_id"] and task_path == record["task_path"]
+            else:
+                allowed = record["status"] in {"claiming", "claimed"} and context_key == record["target_session_id"] and task_path == record["task_path"]
+            yield allowed
 
 
 def assert_task_mutation_allowed(repo_root: Path, task_dir: Path, data: dict) -> None:
@@ -543,21 +608,25 @@ def assert_task_identity_change_allowed(repo_root: Path, task_dir: Path, data: d
 @contextlib.contextmanager
 def task_mutation_guard(repo_root: Path, task_dir: Path, data: dict):
     """Hold the ownership lock across a single task mutation."""
-    task_path = task_dir.relative_to(repo_root).as_posix()
-    path = _ownership_path(repo_root, task_path)
-    with _record_lock(path):
-        try:
-            record = _load_owner(path)
-        except ContinuityError:
-            yield False
-            return
-        if record is None:
-            yield True
-            return
-        task_id = (data.get("id") or data.get("name")) if isinstance(data, dict) else None
-        if task_id != record["task_id"] or record["task_path"] != task_path:
-            yield False
-            return
-        active = resolve_active_task(repo_root)
-        allowed = record["status"] == "consumed" and active.context_key == record["target_session_id"] and active.task_path == task_path
-        yield allowed
+    from .task_move import layout_lock, require_settled_layout
+
+    with layout_lock(repo_root):
+        require_settled_layout(repo_root)
+        task_path = task_dir.relative_to(repo_root).as_posix()
+        path = _ownership_path(repo_root, task_path)
+        with _record_lock(path):
+            try:
+                record = _load_owner(path)
+            except ContinuityError:
+                yield False
+                return
+            if record is None:
+                yield True
+                return
+            task_id = (data.get("id") or data.get("name")) if isinstance(data, dict) else None
+            if task_id != record["task_id"] or record["task_path"] != task_path:
+                yield False
+                return
+            active = resolve_active_task(repo_root)
+            allowed = record["status"] == "consumed" and active.context_key == record["target_session_id"] and active.task_path == task_path
+            yield allowed

package/dist/templates/trellis/scripts/common/task_layout.py

@@ -0,0 +1,80 @@
+"""Task status directories and bounded discovery (never recurse into task content)."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from datetime import date
+from pathlib import Path
+
+STATUSES = ("planning", "in_progress", "completed", "cancelled")
+MONTH_RE = re.compile(r"^\d{4}-(?:0[1-9]|1[0-2])$")
+
+
+def task_location(tasks_dir: Path, name: str, status: str, month: str | None = None) -> Path:
+    if not name or name in {".", "..", "archive", *STATUSES} or "/" in name or "\\" in name:
+        raise ValueError(f"Invalid task directory name: {name}")
+    if status not in STATUSES:
+        raise ValueError(f"Invalid task status: {status}")
+    if status == "completed":
+        month = month or date.today().strftime("%Y-%m")
+        if not MONTH_RE.fullmatch(month):
+            raise ValueError(f"Invalid completion month: {month}")
+        return tasks_dir / status / month / name
+    return tasks_dir / status / name
+
+
+def task_status_dir(task_dir: Path, tasks_dir: Path) -> str | None:
+    """Validate exact depth, containment and nested symlinks; allow a shared tasks root."""
+    try:
+        relative = task_dir.absolute().relative_to(tasks_dir.absolute())
+        parts = relative.parts
+        valid = (len(parts) == 2 and parts[0] in {"planning", "in_progress", "cancelled"}) or (
+            len(parts) == 3 and parts[0] == "completed" and MONTH_RE.fullmatch(parts[1])
+        )
+        if not valid:
+            return None
+        current = tasks_dir
+        for part in parts:
+            current /= part
+            if current.is_symlink():
+                return None
+        task_dir.resolve().relative_to(tasks_dir.resolve())
+        return parts[0]
+    except (ValueError, OSError, RuntimeError):
+        return None
+
+
+def iter_task_dirs(tasks_dir: Path, *, legacy: bool = False) -> Iterator[Path]:
+    """Enumerate only the prescribed levels; old layout is migration input only."""
+    if not tasks_dir.is_dir():
+        return
+    candidates: list[Path] = []
+    for entry in sorted(tasks_dir.iterdir()):
+        if entry.is_symlink():
+            raise ValueError(f"Symlink in task layout: {entry}")
+        if not entry.is_dir():
+            continue
+        if entry.name in STATUSES:
+            if entry.name == "completed":
+                for month in sorted(entry.iterdir()):
+                    if month.is_symlink() or not month.is_dir() or not MONTH_RE.fullmatch(month.name):
+                        raise ValueError(f"Invalid completion month directory: {month}")
+                    candidates.extend(month.iterdir())
+            else:
+                candidates.extend(entry.iterdir())
+        elif legacy and entry.name == "archive":
+            for month in sorted(entry.iterdir()):
+                if month.is_symlink() or not month.is_dir() or not MONTH_RE.fullmatch(month.name):
+                    raise ValueError(f"Invalid archive month directory: {month}")
+                candidates.extend(month.iterdir())
+        elif legacy:
+            candidates.append(entry)
+        else:
+            raise ValueError(f"Old task layout at {entry}; run task.py migrate-layout")
+    for candidate in sorted(candidates, key=lambda p: (p.name, str(p))):
+        if candidate.is_symlink():
+            raise ValueError(f"Symlink in task layout: {candidate}")
+        if not candidate.is_dir():
+            raise ValueError(f"Invalid task directory: {candidate}")
+        yield candidate