okstra 0.168.0 → 0.169.0

package/runtime/python/okstra_ctl/doctor.py

@@ -11,6 +11,7 @@ from typing import Iterable
 from okstra_project import ResolverError, project_json_path, resolve_project_root
 
 from . import improvement_lenses, worktree_registry
+from .models import provider_wrappers
 from .workers import resolve_profile_workers
 from .worktree import is_git_work_tree, main_worktree_path
 
@@ -40,6 +41,7 @@ def phase_diagnostics(
     cwd: str | Path,
     workspace_root: str | Path,
     home: str | Path,
+    host_runtime: str,
 ) -> dict[str, object]:
     """Return JSON-serialisable readiness checks for one lifecycle phase."""
     if phase not in SUPPORTED_PHASES:
@@ -57,7 +59,11 @@ def phase_diagnostics(
     checks.append(_profile_check(workspace, phase))
 
     if project_root is not None:
-        checks.extend(_phase_checks(phase, project_root, workspace, home_path))
+        checks.extend(
+            _phase_checks(
+                phase, project_root, workspace, home_path, host_runtime
+            )
+        )
 
     return {
         "ok": all(check.ok for check in checks),
@@ -164,15 +170,18 @@ def _phase_checks(
     project_root: Path,
     workspace: Path,
     home: Path,
+    host_runtime: str,
 ) -> list[DoctorCheck]:
     if phase == "implementation":
-        return _implementation_checks(project_root, workspace, home)
+        return _implementation_checks(
+            project_root, workspace, home, host_runtime
+        )
     if phase == "final-verification":
         return _final_verification_checks(workspace)
     if phase == "release-handoff":
         return _release_handoff_checks(project_root)
     if phase == "improvement-discovery":
-        return _improvement_discovery_checks(workspace, home)
+        return _improvement_discovery_checks(workspace, home, host_runtime)
     return []
 
 
@@ -180,12 +189,13 @@ def _implementation_checks(
     project_root: Path,
     workspace: Path,
     home: Path,
+    host_runtime: str,
 ) -> list[DoctorCheck]:
     return [
         _git_work_tree_check(project_root),
         _git_worktree_support_check(project_root),
         _approved_plan_validator_check(),
-        _worker_agents_check(home, workspace, "implementation"),
+        *_worker_dispatch_checks(home, workspace, "implementation", host_runtime),
     ]
 
 
@@ -213,10 +223,15 @@ def _release_handoff_checks(project_root: Path) -> list[DoctorCheck]:
     ]
 
 
-def _improvement_discovery_checks(workspace: Path, home: Path) -> list[DoctorCheck]:
+def _improvement_discovery_checks(
+    workspace: Path,
+    home: Path,
+    host_runtime: str,
+) -> list[DoctorCheck]:
     return [
-        _worker_agents_check(home, workspace, "improvement-discovery"),
-        _file_check("antigravity worker agent", _agent_path(home, "antigravity")),
+        *_worker_dispatch_checks(
+            home, workspace, "improvement-discovery", host_runtime
+        ),
         _lens_whitelist_check(),
     ]
 
@@ -242,18 +257,77 @@ def _approved_plan_validator_check() -> DoctorCheck:
     return _ok("approved-plan validator", "okstra plan-validate is available")
 
 
-def _worker_agents_check(home: Path, workspace: Path, phase: str) -> DoctorCheck:
+def _worker_dispatch_checks(
+    home: Path,
+    workspace: Path,
+    phase: str,
+    host_runtime: str,
+) -> list[DoctorCheck]:
     workers = resolve_profile_workers(_profile_path(workspace, phase))
     if not workers:
-        return _ok("worker agents", "no worker agents required")
-    missing = [worker for worker in workers if not _agent_path(home, worker).is_file()]
-    roster = ",".join(workers)
-    if missing:
-        return _fail(
-            "worker agents",
-            f"missing {','.join(missing)}; profile requires {roster}",
+        return [_ok("worker dispatch", "no workers required")]
+    if not host_runtime:
+        return [_fail("worker dispatch", "resolved host runtime is required")]
+
+    native_provider = {
+        "claude-code": "claude",
+        "codex": "codex",
+        "antigravity": "antigravity",
+        "grok": "grok",
+        "kimi": "kimi",
+    }.get(host_runtime)
+    providers = ["claude" if worker == "report-writer" else worker for worker in workers]
+    checks: list[DoctorCheck] = []
+
+    if host_runtime == "claude-code":
+        native_agents = []
+        if "claude" in workers:
+            native_agents.append("claude")
+        if "report-writer" in workers:
+            native_agents.append("report-writer")
+        for agent in native_agents:
+            checks.append(
+                _file_check(
+                    f"host-native agent: {agent}", _agent_path(home, agent)
+                )
+            )
+
+    cli_providers = sorted({
+        provider for provider in providers if provider != native_provider
+    })
+    if cli_providers:
+        dispatch_module = _first_file(
+            workspace / "scripts" / "okstra_ctl" / "worker_dispatch.py",
+            workspace / "python" / "okstra_ctl" / "worker_dispatch.py",
+        )
+        checks.append(
+            _file_check("worker-dispatch entrypoint", dispatch_module)
         )
-    return _ok("worker agents", f"installed: {roster}")
+        wrappers = provider_wrappers("analyser")
+        for provider in cli_providers:
+            wrapper = wrappers.get(provider, "")
+            if not wrapper:
+                checks.append(
+                    _fail(
+                        f"CLI provider strategy: {provider}",
+                        "provider registry has no analyser wrapper",
+                    )
+                )
+                continue
+            path = _first_file(
+                workspace / "scripts" / wrapper,
+                workspace / "bin" / wrapper,
+            )
+            checks.append(_file_check(f"CLI provider strategy: {provider}", path))
+    if not checks:
+        checks.append(
+            _ok("worker dispatch", f"native host owns roster on {host_runtime}")
+        )
+    return checks
+
+
+def _first_file(*paths: Path) -> Path:
+    return next((path for path in paths if path.is_file()), paths[0])
 
 
 def _worktree_registry_check() -> DoctorCheck:

package/runtime/python/okstra_ctl/entrypoints/hosts.py

@@ -9,6 +9,14 @@ from contextlib import contextmanager
 from dataclasses import asdict
 from pathlib import Path
 
+from ..agent_invocation import (
+    AgentInvocationError,
+    AgentModelAssignment,
+    agent_model_assignment_from_payload,
+    verify_agent_invocation,
+)
+from ..dispatch_state import DispatchError, record_verified_agent_dispatch
+
 from ..application.start_run import start_run
 from ..application.resume_run import resume_run
 from ..domain.host import (
@@ -24,6 +32,7 @@ from ..domain.host import (
     ProviderUnavailable,
 )
 from ..registry.host_registry import HostAdapterRegistry, default_host_registry
+from ..models import lead_launch_argv, lead_launch_spec
 
 
 _ENTRYPOINT_ERRORS = (
@@ -33,6 +42,7 @@ _ENTRYPOINT_ERRORS = (
     HostUnavailable,
     ProviderNotRegistered,
     ProviderUnavailable,
+    DispatchError,
     ValueError,
 )
 
@@ -252,9 +262,24 @@ def _launch_plan_payload(
         available_functions=frozenset(),
         interaction_surface="terminal",
     )
-    project_root, request_argv = _launch_request(args, adapter.descriptor.id)
+    project_root, request_argv, dispatch_authority = _launch_request(
+        args, adapter.descriptor.id
+    )
     request = LeadStartRequest(project_root, "", request_argv)
     plan = start_run(request, context, adapter)
+    if dispatch_authority is not None:
+        run_manifest_path, metadata_path, _assignment = dispatch_authority
+        record_verified_agent_dispatch(
+            project_root=project_root,
+            run_manifest_path=run_manifest_path,
+            metadata_path=metadata_path,
+            enforcement_mode=(
+                "core-pre-dispatch"
+                if plan.mode == "spawn-process"
+                else "host-native-spec-link-gate"
+            ),
+            allow_native_core=plan.mode == "spawn-process",
+        )
     return {"ok": True, "_project_root": str(project_root), **asdict(plan)}
 
 
@@ -283,9 +308,13 @@ def _resume_plan_payload(
 def _launch_request(
     args: argparse.Namespace,
     canonical_host_id: str,
-) -> tuple[Path, tuple[str, ...]]:
+) -> tuple[
+    Path,
+    tuple[str, ...],
+    tuple[Path, Path, AgentModelAssignment] | None,
+]:
     if not args.prepared_launch_json:
-        return Path(args.project_root), ()
+        return Path(args.project_root), (), None
     try:
         prepared = json.loads(args.prepared_launch_json)
     except json.JSONDecodeError as exc:
@@ -295,14 +324,63 @@ def _launch_request(
     if prepared.get("leadRuntime") != canonical_host_id:
         raise ValueError("prepared launch runtime does not match selected host")
     project_root = prepared.get("projectRoot")
-    request_argv = prepared.get("launchRequestArgv")
     if not isinstance(project_root, str) or not project_root:
         raise ValueError("prepared launch is missing projectRoot")
-    if not isinstance(request_argv, list) or not all(
-        isinstance(arg, str) for arg in request_argv
-    ):
-        raise ValueError("prepared launch is missing launchRequestArgv")
-    return Path(project_root), tuple(request_argv)
+    root = Path(project_root)
+    run_manifest_value = prepared.get("runManifestPath")
+    metadata_value = prepared.get("leadPromptMetadataPath")
+    if not isinstance(run_manifest_value, str) or not run_manifest_value:
+        raise ValueError("prepared launch is missing runManifestPath")
+    if not isinstance(metadata_value, str) or not metadata_value:
+        raise ValueError("prepared launch is missing leadPromptMetadataPath")
+    run_manifest_path = Path(run_manifest_value)
+    metadata_path = Path(metadata_value)
+    try:
+        manifest = json.loads(run_manifest_path.read_text(encoding="utf-8"))
+        resources = manifest["resources"]
+        assignment = agent_model_assignment_from_payload(
+            manifest["invocationAssignments"]["lead"]
+        )
+        prompt_path = root / resources["leadExecutionPromptPath"]
+        canonical_metadata = root / resources["leadPromptMetadataPath"]
+        metadata = json.loads(canonical_metadata.read_text(encoding="utf-8"))
+        if metadata["prompt"]["path"] != resources["leadExecutionPromptPath"]:
+            raise KeyError("lead prompt resource does not match metadata")
+    except (OSError, json.JSONDecodeError, KeyError, TypeError, AgentInvocationError) as exc:
+        raise ValueError("lead invocation authority is incomplete") from exc
+    if metadata_path.resolve(strict=False) != canonical_metadata.resolve(strict=False):
+        raise ValueError("prepared lead metadata does not match run manifest")
+    if prepared.get("leadProvider") != assignment.provider:
+        raise ValueError("prepared lead provider does not match run manifest")
+    if prepared.get("leadModelExecutionValue") != assignment.model_execution_value:
+        raise ValueError("prepared lead model does not match run manifest")
+    errors = verify_agent_invocation(
+        metadata_path,
+        project_root=root,
+        expected_run_manifest_path=run_manifest_path,
+        expected_assignment=assignment,
+        expected_worker_id="lead",
+        expected_assignment_ref="lead",
+        expected_audience="lead",
+    )
+    if errors:
+        raise ValueError("lead invocation verification failed: " + "; ".join(errors))
+    session_id = prepared.get("leadSessionId")
+    if not isinstance(session_id, str):
+        raise ValueError("prepared launch is missing leadSessionId")
+    argv = lead_launch_argv(
+        assignment.provider,
+        model=assignment.model_execution_value,
+        session_id=session_id,
+        prompt=prompt_path.read_text(encoding="utf-8"),
+    )
+    launch = lead_launch_spec(assignment.provider)
+    prefix_size = 1 + len(launch.sandbox_waiver)
+    return (
+        root,
+        tuple(argv[prefix_size:]),
+        (run_manifest_path, canonical_metadata, assignment),
+    )
 
 
 def _write_null_launch_plan(payload: dict[str, object]) -> None:

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -11,6 +11,16 @@ from pathlib import Path
 from typing import Any, Callable, Literal, Mapping, Sequence
 
 from .final_report_paths import final_report_data_path
+from .agent_invocation import (
+    AgentInstruction,
+    AgentInstructionSource,
+    AgentInvocationError,
+    AgentInvocationRequest,
+    agent_model_assignment_from_payload,
+    compose_agent_prompt,
+    prepare_agent_invocation,
+    verify_agent_invocation,
+)
 from .path_hints import hydrate_active_run_context
 from .report_language import resolve_report_language
 from .worker_prompt_body import (
@@ -101,6 +111,30 @@ _CLARIFICATION_AUTHORITY_INTRO = (
 _CLARIFICATION_SOURCE_PREFIX = "Source:"
 _REQUIRED_PROMPT_RESOURCES_HEADING = "## Required prompt resources"
 _HTML_COMMENTS = re.compile(r"<!--.*?-->\n?", re.DOTALL)
+_AGENT_CONTRACT_KEYS = {
+    "schemaVersion",
+    "dutyRootPath",
+    "catalogDigest",
+    "invocationReservationRootPath",
+    "allowedAudiences",
+    "authorizedPaths",
+}
+_MODEL_ASSIGNMENT_KEYS = {
+    "provider",
+    "model",
+    "modelExecutionValue",
+    "runner",
+    "hostRuntime",
+    "hostModelValue",
+}
+_RUN_INVOCATION_PATH_KEYS = {
+    "runManifestPath",
+    "workerPromptsDirectoryPath",
+    "leadInstructionsPath",
+    "leadExecutionPromptPath",
+    "leadPromptMetadataPath",
+    "invocationReservationRootPath",
+}
 
 
 @dataclass(frozen=True)
@@ -198,6 +232,7 @@ def _load_materialization_context(
         )
     manifest_path = _resolve_input_path(project_root, request.run_manifest_path)
     manifest = _load_json_object(manifest_path, "run manifest")
+    _validate_invocation_manifest_authority(manifest)
     team_state = _load_referenced_json(project_root, manifest, "teamStatePath")
     active_context = hydrate_active_run_context(
         _load_referenced_json(
@@ -215,6 +250,39 @@ def _load_materialization_context(
     )
 
 
+def _validate_invocation_manifest_authority(
+    manifest: Mapping[str, Any],
+) -> None:
+    has_contract = "agentContract" in manifest
+    has_assignments = "invocationAssignments" in manifest
+    if not has_contract and not has_assignments:
+        return
+    contract = manifest.get("agentContract")
+    assignments = manifest.get("invocationAssignments")
+    complete = (
+        isinstance(contract, Mapping)
+        and set(contract) == _AGENT_CONTRACT_KEYS
+        and contract.get("schemaVersion") == 1
+        and isinstance(assignments, Mapping)
+        and bool(assignments)
+        and all(
+            isinstance(item, Mapping)
+            and set(item) == _MODEL_ASSIGNMENT_KEYS
+            for item in assignments.values()
+        )
+        and all(
+            isinstance(manifest.get(key), str)
+            and bool(manifest.get(key))
+            for key in _RUN_INVOCATION_PATH_KEYS
+        )
+    )
+    if not complete:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            "new invocation manifest is incomplete",
+        )
+
+
 def _resolve_prompt_item(
     context: _MaterializationContext,
     worker: InitialPromptWorkerRequest,
@@ -312,12 +380,23 @@ def _render_prompt(
     context: _MaterializationContext,
     item: _PromptItem,
 ) -> str:
+    request = _agent_invocation_request(context, item)
+    if request is not None:
+        return compose_agent_prompt(request)
+    anchors, body = _render_prompt_parts(context, item)
+    return "\n".join([*anchors, *body]).rstrip() + "\n"
+
+
+def _render_prompt_parts(
+    context: _MaterializationContext,
+    item: _PromptItem,
+) -> tuple[list[str], list[str]]:
     worker = item.worker
     state = _worker_state(context.team_state, worker.worker_id)
     prompt_rel = _project_relative(context.project_root, item.final_path)
     result_rel, audit_source_rel = _result_paths(context, state, worker.worker_id)
     try:
-        lines = worker_prompt_headers(
+        anchors = worker_prompt_headers(
             project_root=context.project_root,
             prompt_rel=prompt_rel,
             result_rel=result_rel,
@@ -327,12 +406,12 @@ def _render_prompt(
             manifest=context.manifest,
             active_context=context.active_context,
         )
-        lines.append(
+        anchors.append(
             f"**Prompt Delivery Mode:** {context.request.delivery_mode.value}"
         )
-        lines.extend(_implementation_anchor_lines(context, item.plan))
-        lines.extend(_prompt_body(context, state, worker, item.plan))
-        lines.extend(_resource_lines(context, item))
+        anchors.extend(_implementation_anchor_lines(context, item.plan))
+        body = _prompt_body(context, state, worker, item.plan)
+        body.extend(_resource_lines(context, item))
     except InitialPromptMaterializationError:
         raise
     except Exception as exc:
@@ -340,7 +419,62 @@ def _render_prompt(
             "render_failed",
             f"cannot compose initial prompt for {worker.worker_id}: {exc}",
         ) from exc
-    return "\n".join(lines).rstrip() + "\n"
+    return anchors, body
+
+
+def _agent_invocation_request(
+    context: _MaterializationContext,
+    item: _PromptItem,
+) -> AgentInvocationRequest | None:
+    contract = context.manifest.get("agentContract")
+    if not isinstance(contract, Mapping):
+        return None
+    assignment_ref = f"initial/{item.worker.worker_id}"
+    assignments = context.manifest.get("invocationAssignments")
+    payload = assignments.get(assignment_ref) if isinstance(assignments, Mapping) else None
+    try:
+        assignment = agent_model_assignment_from_payload(payload)
+    except AgentInvocationError as exc:
+        raise InitialPromptMaterializationError(
+            "required_input_missing", str(exc)
+        ) from exc
+    if assignment.model_execution_value != item.worker.model:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            f"requested model does not match {assignment_ref}",
+        )
+    anchors, body = _render_prompt_parts(context, item)
+    source_paths = (
+        AgentInstructionSource(
+            "project",
+            _project_relative(context.project_root, context.request.run_manifest_path),
+        ),
+        AgentInstructionSource(
+            "project", _required_string(context.manifest, "activeRunContextPath")
+        ),
+        AgentInstructionSource(
+            "project", _required_string(context.manifest, "teamStatePath")
+        ),
+    )
+    return AgentInvocationRequest(
+        invocation_id=f"initial-{item.worker.worker_id}",
+        worker_id=item.worker.worker_id,
+        audience=item.plan.duty_audience,
+        assignment_ref=assignment_ref,
+        purpose=None,
+        assignment=assignment,
+        instruction=AgentInstruction(
+            anchor_lines=tuple(anchors),
+            body="\n".join(body).rstrip() + "\n",
+            source_paths=source_paths,
+        ),
+        project_root=context.project_root,
+        run_manifest_path=context.request.run_manifest_path,
+        duty_root=context.project_root / _required_string(contract, "dutyRootPath"),
+        prompt_path=item.final_path,
+        metadata_path=item.final_path.with_name(item.final_path.name + ".meta.json"),
+        dispatch_kind="initial",
+    )
 
 
 def _prompt_body(
@@ -366,7 +500,6 @@ def _prompt_body(
         context.active_context,
         worker.worker_id,
         worker.model,
-        _worker_role(plan),
         plan,
     )
 
@@ -607,15 +740,30 @@ def _publish_or_reuse(
 ) -> _PublishedPrompt:
     if item.existed:
         return _published_prompt(item, existed=True)
-    temp_path = _required_temp_path(item)
+    invocation = _agent_invocation_request(context, item)
+    if invocation is None:
+        temp_path = _required_temp_path(item)
+        try:
+            os.link(temp_path, item.final_path)
+        except FileExistsError:
+            _validate_existing_prompt(context, item)
+            return _published_prompt(item, existed=True)
+        except OSError as exc:
+            raise InitialPromptMaterializationError(
+                "publication_failed",
+                f"cannot publish initial prompt {item.final_path}: {exc}",
+            ) from exc
+        return _published_prompt(item, existed=False)
     try:
-        os.link(temp_path, item.final_path)
-    except FileExistsError:
-        _validate_existing_prompt(context, item)
-        return _published_prompt(item, existed=True)
-    except OSError as exc:
+        prepare_agent_invocation(invocation)
+    except AgentInvocationError as exc:
+        reason: MaterializationReason = (
+            "existing_prompt_conflict"
+            if exc.reason == "existing_invocation_conflict"
+            else "publication_failed"
+        )
         raise InitialPromptMaterializationError(
-            "publication_failed",
+            reason,
             f"cannot publish initial prompt {item.final_path}: {exc}",
         ) from exc
     return _published_prompt(item, existed=False)
@@ -625,6 +773,7 @@ def _validate_existing_prompt(
     context: _MaterializationContext,
     item: _PromptItem,
 ) -> None:
+    expects_invocation = isinstance(context.manifest.get("agentContract"), Mapping)
     text = _require_readable_prompt(
         item.final_path,
         item.worker.worker_id,
@@ -636,6 +785,10 @@ def _validate_existing_prompt(
         item.worker.worker_id,
         "initial",
         item.final_path,
+        metadata_path=_metadata_path(item.final_path) if expects_invocation else None,
+        expected_duty_audience=(
+            item.plan.duty_audience if expects_invocation else None
+        ),
     )
     basic_errors = validate_initial_prompt_records(
         manifest=context.manifest,
@@ -653,6 +806,10 @@ def _validate_existing_prompt(
         item.final_path,
         expected_model=item.worker.model,
         expected_delivery_mode=context.request.delivery_mode.value,
+        metadata_path=_metadata_path(item.final_path) if expects_invocation else None,
+        expected_duty_audience=(
+            item.plan.duty_audience if expects_invocation else None
+        ),
     )
     expected_errors = validate_initial_prompt_records(
         manifest=context.manifest,
@@ -665,6 +822,23 @@ def _validate_existing_prompt(
             reason,
             "existing initial prompt metadata: " + "; ".join(expected_errors),
         )
+    invocation = _agent_invocation_request(context, item)
+    if invocation is not None:
+        errors = verify_agent_invocation(
+            invocation.metadata_path,
+            project_root=context.project_root,
+            expected_run_manifest_path=context.request.run_manifest_path,
+            expected_assignment=invocation.assignment,
+            expected_invocation_id=invocation.invocation_id,
+            expected_worker_id=invocation.worker_id,
+            expected_assignment_ref=invocation.assignment_ref,
+            expected_audience=invocation.audience,
+        )
+        if errors:
+            raise InitialPromptMaterializationError(
+                "existing_prompt_invalid",
+                "existing initial prompt invocation: " + "; ".join(errors),
+            )
 
 
 def _validate_existing_clarification_metadata(
@@ -854,12 +1028,20 @@ def _item_record(
     item: _PromptItem,
 ) -> PromptRecord:
     path = item.final_path if item.existed else _required_temp_path(item)
+    expects_invocation = (
+        item.existed
+        and isinstance(context.manifest.get("agentContract"), Mapping)
+    )
     return PromptRecord(
         item.worker.worker_id,
         "initial",
         path,
         expected_model=item.worker.model,
         expected_delivery_mode=context.request.delivery_mode.value,
+        metadata_path=_metadata_path(item.final_path) if expects_invocation else None,
+        expected_duty_audience=(
+            item.plan.duty_audience if expects_invocation else None
+        ),
     )
 
 
@@ -867,15 +1049,24 @@ def _published_record(
     context: _MaterializationContext,
     prompt: _PublishedPrompt,
 ) -> PromptRecord:
+    expects_invocation = isinstance(context.manifest.get("agentContract"), Mapping)
     return PromptRecord(
         prompt.worker.worker_id,
         "initial",
         prompt.path,
         expected_model=prompt.worker.model,
         expected_delivery_mode=context.request.delivery_mode.value,
+        metadata_path=_metadata_path(prompt.path) if expects_invocation else None,
+        expected_duty_audience=(
+            prompt.plan.duty_audience if expects_invocation else None
+        ),
     )
 
 
+def _metadata_path(prompt_path: Path) -> Path:
+    return prompt_path.with_name(prompt_path.name + ".meta.json")
+
+
 def _worker_prompt_path(
     context: _MaterializationContext,
     worker_id: str,
@@ -1094,14 +1285,6 @@ def _validate_worker_request(worker: InitialPromptWorkerRequest) -> None:
     )
 
 
-def _worker_role(plan: PromptPlan) -> str:
-    if plan.audience == "implementation-executor":
-        return "executor"
-    if plan.audience == "implementation-verifier":
-        return "verifier"
-    return "worker"
-
-
 def _existing_metadata_reason(
     errors: Sequence[str],
 ) -> MaterializationReason:
@@ -1164,7 +1347,15 @@ def _required_temp_path(item: _PromptItem) -> Path:
 
 
 def _project_relative(project_root: Path, path: Path) -> str:
-    return path.relative_to(project_root).as_posix()
+    # macOS commonly exposes the same temporary directory as both `/var/...`
+    # and `/private/var/...`; project-root resolution already canonicalizes the
+    # former. Resolve the candidate too so provenance does not reject an alias
+    # for the same directory. `strict=False` is required for a prompt that has
+    # not been published yet, while still resolving every existing parent and
+    # therefore preserving the symlink-escape check in `relative_to`.
+    return path.resolve(strict=False).relative_to(
+        project_root.resolve(strict=True)
+    ).as_posix()
 
 
 def _resolve_input_path(project_root: Path, path: Path) -> Path: