@sakanano-moe/agenthelm 6.11.0 → 6.12.0-rc.1

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 (31) hide show
  1. package/package.json +1 -1
  2. package/runtime/index.json +6 -6
  3. package/runtime/plugins/agent-pack/.codex-plugin/plugin.json +1 -1
  4. package/runtime/plugins/agent-pack/plugin.json +1 -1
  5. package/runtime/plugins/agent-pack/references/capability-config.md +11 -1
  6. package/runtime/plugins/agent-pack/runtime/agent_pack_codex_mcp.py +161 -0
  7. package/runtime/plugins/agent-pack/runtime/agent_pack_config.py +232 -53
  8. package/runtime/plugins/agent-pack/runtime/agenthelm.py +171 -23
  9. package/runtime/plugins/agent-pack/runtime/agenthelm_runtime.py +1 -1
  10. package/runtime/plugins/agent-pack/runtime/locale/en.json +13 -1
  11. package/runtime/plugins/agent-pack/runtime/mcp_server.py +5 -1
  12. package/runtime/plugins/agents-init/.codex-plugin/plugin.json +1 -1
  13. package/runtime/plugins/agents-init/content.json +2 -2
  14. package/runtime/plugins/agents-init/plugin.json +1 -1
  15. package/runtime/plugins/agents-init/skills/agents-init/AGENT.template.md +169 -0
  16. package/runtime/plugins/agents-init/skills/agents-init/scripts/adopt.py +9 -1
  17. package/runtime/plugins/agents-init/skills/agents-init/scripts/init_project.py +74 -20
  18. package/runtime/plugins/agents-init/skills/agents-init/scripts/locale/en.json +7 -2
  19. package/runtime/plugins/agents-init/skills/agents-init/scripts/scaffold.py +5 -2
  20. package/runtime/plugins/agents-init/skills/agents-init/skill.json +1 -1
  21. package/runtime/plugins/opinion-manager/.codex-plugin/plugin.json +1 -1
  22. package/runtime/plugins/opinion-manager/plugin.json +1 -1
  23. package/runtime/plugins/opinion-manager/runtime/constants.py +3 -0
  24. package/runtime/plugins/project-orchestrator/.codex-plugin/plugin.json +1 -1
  25. package/runtime/plugins/project-orchestrator/plugin.json +1 -1
  26. package/runtime/plugins/project-orchestrator/references/case-workspaces.md +4 -0
  27. package/runtime/plugins/project-orchestrator/runtime/case.py +20 -2
  28. package/runtime/plugins/project-orchestrator/runtime/locale/en.json +5 -1
  29. package/runtime/plugins/project-orchestrator/runtime/memory.py +25 -8
  30. package/runtime/plugins/project-orchestrator/runtime/project_cli.py +4 -2
  31. package/runtime/plugins/project-orchestrator/runtime/project_maintain.py +6 -1
@@ -18,6 +18,7 @@ import stat
18
18
  import sys
19
19
  import tempfile
20
20
  import tomllib
21
+ from urllib.parse import parse_qsl, urlsplit
21
22
  from datetime import UTC, datetime
22
23
  from dataclasses import asdict, dataclass, field
23
24
  from pathlib import Path
@@ -40,6 +41,29 @@ SECRET_VALUE_RE = re.compile(
40
41
  re.IGNORECASE,
41
42
  )
42
43
  ENV_REFERENCE_RE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
44
+ # Known credential prefixes; only a long identifier counts, so SK_KEY or GH_TOKEN remain valid variable names.
45
+ TOKEN_PREFIX_RE = re.compile(r"^(?:gh[pousr]_|github_pat_|sk[-_]|pk[-_]|rk[-_]|xox[abprs]|glpat|AKIA|eyJ|ya29)", re.IGNORECASE)
46
+
47
+
48
+ def looks_like_token(name: str) -> bool:
49
+ """True when something spelled as an environment variable *name* is more likely a pasted credential value.
50
+
51
+ Real variable names are short and conventional (``EXAMPLE_MCP_TOKEN``). A well-known credential prefix on a long
52
+ identifier, a long mixed-case alphanumeric run, or an implausibly long name is treated as a credential.
53
+ """
54
+ if len(name) > 64:
55
+ return True
56
+ if len(name) >= 20 and TOKEN_PREFIX_RE.match(name):
57
+ return True
58
+ return (len(name) >= 24 and any(c.islower() for c in name) and any(c.isupper() for c in name)
59
+ and any(c.isdigit() for c in name))
60
+
61
+
62
+ def _safe_env_reference(text: str) -> bool:
63
+ """A value made of ``${NAME}`` references with nothing credential-like in the names or around them."""
64
+ references = ENV_REFERENCE_RE.findall(text)
65
+ return (bool(references) and not any(looks_like_token(name) for name in references)
66
+ and not SECRET_VALUE_RE.search(ENV_REFERENCE_RE.sub("", text)))
43
67
  # Placeholders the client resolves at launch time (immutable package root and
44
68
  # client-managed writable state). They are never credentials and must not
45
69
  # trigger the credential-env-file requirement or env-launcher wrapping.
@@ -293,8 +317,50 @@ def validate_plugin_manifest(plugin_root: Path) -> tuple[dict[str, Any], list[st
293
317
  def _portable_mcp(name: str, raw: Any) -> McpRecord:
294
318
  if not isinstance(raw, dict):
295
319
  return McpRecord(name, {}, "", False, ("MCP entry must be an object",))
296
- item = dict(raw)
320
+ item = json.loads(json.dumps(raw))
321
+ # Cursor spells process environment interpolation as ${env:NAME}.
322
+ if isinstance(item.get("headers"), dict):
323
+ item["headers"] = {key: re.sub(r"\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}", r"${\1}", value)
324
+ if isinstance(value, str) else value for key, value in item["headers"].items()}
297
325
  issues: list[str] = []
326
+ # Canonical portable form uses headers with literal environment references.
327
+ # Codex's native fields describe names, never values; normalize on import.
328
+ for source_field in ("http_headers", "env_http_headers"):
329
+ value = item.pop(source_field, None)
330
+ if value is None:
331
+ continue
332
+ if not isinstance(value, dict) or not all(isinstance(k, str) and isinstance(v, str)
333
+ for k, v in value.items()):
334
+ issues.append(f"{source_field} must be a string map")
335
+ continue
336
+ headers = dict(item.get("headers", {})) if isinstance(item.get("headers", {}), dict) else {}
337
+ for key, value in value.items():
338
+ if source_field == "env_http_headers":
339
+ if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", value):
340
+ issues.append(f"invalid environment variable name in {source_field}.{key}")
341
+ continue
342
+ if looks_like_token(value):
343
+ issues.append(f"{source_field}.{key} looks like a credential, not a variable name")
344
+ continue
345
+ value = "${" + value + "}"
346
+ if key in headers and headers[key] != value:
347
+ issues.append(f"conflicting header: {key}")
348
+ headers[key] = value
349
+ item["headers"] = headers
350
+ bearer = item.pop("bearer_token_env_var", None)
351
+ if bearer is not None:
352
+ if not isinstance(bearer, str) or not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", bearer):
353
+ issues.append("bearer_token_env_var must be an environment variable name")
354
+ elif looks_like_token(bearer):
355
+ issues.append("bearer_token_env_var looks like a credential, not a variable name")
356
+ else:
357
+ headers = dict(item.get("headers", {})) if isinstance(item.get("headers", {}), dict) else {}
358
+ auth = next((key for key in headers if key.lower() == "authorization"), "Authorization")
359
+ value = "Bearer ${" + bearer + "}"
360
+ if auth in headers and headers[auth] != value:
361
+ issues.append("conflicting Authorization header")
362
+ headers[auth] = value
363
+ item["headers"] = headers
298
364
  mcp_type = item.get("type")
299
365
  if mcp_type == "http":
300
366
  item["type"] = "streamable-http"
@@ -317,21 +383,23 @@ def _portable_mcp(name: str, raw: Any) -> McpRecord:
317
383
  issues.append(f"{container_name} must be an object")
318
384
  continue
319
385
  for key, value in container.items():
320
- references = ENV_REFERENCE_RE.findall(str(value))
321
- safe_reference = bool(references) and not SECRET_VALUE_RE.search(
322
- ENV_REFERENCE_RE.sub("", str(value))
323
- )
386
+ if not isinstance(key, str) or not isinstance(value, str):
387
+ issues.append(f"{container_name} must be a string map")
388
+ continue
389
+ safe_reference = _safe_env_reference(str(value))
324
390
  if (SECRET_NAME_RE.search(str(key)) or SECRET_VALUE_RE.search(str(value))) and not safe_reference:
325
391
  issues.append(f"possible secret in {container_name}.{key}")
392
+ elif any(looks_like_token(name) for name in ENV_REFERENCE_RE.findall(str(value))):
393
+ issues.append(f"possible secret in {container_name}.{key}")
326
394
  args = item.get("args", [])
327
395
  if isinstance(args, list):
328
396
  for index, value in enumerate(args):
329
397
  rendered = str(value)
330
- safe_reference = bool(ENV_REFERENCE_RE.search(rendered)) and not SECRET_VALUE_RE.search(
331
- ENV_REFERENCE_RE.sub("", rendered)
332
- )
398
+ safe_reference = _safe_env_reference(rendered)
333
399
  if (SECRET_NAME_RE.search(rendered) or SECRET_VALUE_RE.search(rendered)) and not safe_reference:
334
400
  issues.append(f"possible secret reference in args[{index}]")
401
+ elif any(looks_like_token(name) for name in ENV_REFERENCE_RE.findall(rendered)):
402
+ issues.append(f"possible secret reference in args[{index}]")
335
403
  if mcp_type == "stdio":
336
404
  allowed = {"type", "command", "args", "env", "cwd"}
337
405
  if not isinstance(item.get("command"), str) or not item["command"]:
@@ -340,6 +408,16 @@ def _portable_mcp(name: str, raw: Any) -> McpRecord:
340
408
  allowed = {"type", "url", "headers"}
341
409
  if not isinstance(item.get("url"), str) or not item["url"]:
342
410
  issues.append("remote URL is required")
411
+ else:
412
+ try:
413
+ url = urlsplit(item["url"])
414
+ if url.username or url.password or any(SECRET_NAME_RE.search(key) and value
415
+ for key, value in parse_qsl(url.query)):
416
+ issues.append("possible secret in URL")
417
+ except ValueError:
418
+ issues.append("invalid remote URL")
419
+ if ENV_REFERENCE_RE.search(item["url"]):
420
+ issues.append("remote environment references must be declared in headers")
343
421
  unknown = sorted(set(item) - allowed)
344
422
  if unknown:
345
423
  issues.append("unsupported fields: " + ", ".join(unknown))
@@ -675,51 +753,106 @@ def transfer_to_project(
675
753
  mcp_names: Iterable[str],
676
754
  *,
677
755
  apply: bool = False,
756
+ update: bool = False,
757
+ recovery_root: Path | None = None,
678
758
  ) -> dict[str, Any]:
759
+ """Import selected capabilities; replacement requires both --update and --apply.
760
+
761
+ Previews contain changed paths and hashes, never MCP values or file contents.
762
+ Stage everything before moving originals; roll back the whole selection on failure.
763
+ """
679
764
  layout = load_project_layout(destination_project)
680
- requested_skills = set(skill_names)
681
- requested_mcps = set(mcp_names)
765
+ requested_skills, requested_mcps = set(skill_names), set(mcp_names)
682
766
  selected_skills = [item for item in source.skills if item.name in requested_skills]
683
767
  selected_mcps = [item for item in source.mcps if item.name in requested_mcps]
684
- missing_skills = requested_skills - {item.name for item in selected_skills}
685
- missing_mcps = requested_mcps - {item.name for item in selected_mcps}
686
- if missing_skills or missing_mcps:
687
- raise AgentPackError(
688
- "requested items missing: "
689
- + ", ".join(sorted(missing_skills | missing_mcps))
690
- )
691
- blocked = [
692
- f"skill:{item.name}" for item in selected_skills if not item.portable
693
- ] + [
694
- f"mcp:{item.name}" for item in selected_mcps if not item.portable
695
- ]
768
+ missing = (requested_skills - {item.name for item in selected_skills}) | (requested_mcps - {item.name for item in selected_mcps})
769
+ if missing:
770
+ raise AgentPackError("requested items missing: " + ", ".join(sorted(missing)))
771
+ blocked = [f"skill:{item.name}" for item in selected_skills if not item.portable]
772
+ blocked += [f"mcp:{item.name}" for item in selected_mcps if not item.portable]
696
773
  if blocked:
697
774
  raise AgentPackError("non-portable or secret-bearing items blocked: " + ", ".join(blocked))
698
-
699
- operations: list[dict[str, str]] = []
775
+ # A same-name source from two installed packages is ambiguous.
776
+ if len(selected_skills) != len(requested_skills) or len(selected_mcps) != len(requested_mcps):
777
+ raise AgentPackError("duplicate selected capability; choose a plugin source instead")
778
+ operations: list[dict[str, Any]] = []
779
+ skills_to_copy = []
700
780
  for item in selected_skills:
701
781
  destination = layout.destination_skill_root / item.name
702
- if destination.exists() or destination.is_symlink():
703
- raise AgentPackError(f"destination already exists: {destination}")
704
- operations.append({"action": "copy-skill", "name": item.name, "to": str(destination)})
705
-
782
+ exists = destination.exists() or destination.is_symlink()
783
+ if exists and not update:
784
+ raise AgentPackError(f"destination already exists: {destination}; use --update to preview replacement")
785
+ if exists and destination.is_symlink():
786
+ raise AgentPackError(f"refusing symlinked destination: {destination}")
787
+ before = _tree_fingerprint(destination) if exists else None
788
+ after = _tree_fingerprint(Path(item.path))
789
+ if before == after:
790
+ continue
791
+ skills_to_copy.append(item)
792
+ operations.append({"action": "update-skill" if exists else "copy-skill", "name": item.name,
793
+ "to": str(destination), "before": before, "after": after})
706
794
  mcp_payload = _load_destination_mcp(layout.destination_mcp)
795
+ original_mcp = json.loads(json.dumps(mcp_payload))
707
796
  servers = mcp_payload.setdefault("mcpServers", {})
708
797
  for item in selected_mcps:
709
- if item.name in servers:
710
- raise AgentPackError(f"MCP destination already exists: {item.name}")
711
- operations.append({"action": "merge-mcp", "name": item.name, "to": str(layout.destination_mcp)})
712
-
713
- if apply:
714
- for item in selected_skills:
715
- _copy_skill(Path(item.path), layout.destination_skill_root / item.name)
716
- for item in selected_mcps:
717
- servers[item.name] = item.config
718
- if selected_mcps:
719
- if layout.destination_mcp.suffix == ".jsonc":
720
- raise AgentPackError("writing legacy JSONC destinations is intentionally unsupported")
721
- _write_json_atomic(layout.destination_mcp, mcp_payload)
722
- return {"ok": True, "applied": apply, "operations": operations}
798
+ exists = item.name in servers
799
+ if exists and not update:
800
+ raise AgentPackError(f"MCP destination already exists: {item.name}; use --update to preview replacement")
801
+ before = servers.get(item.name, {})
802
+ if before == item.config:
803
+ continue
804
+ operations.append({"action": "update-mcp" if exists else "merge-mcp", "name": item.name,
805
+ "to": str(layout.destination_mcp),
806
+ "changed_keys": sorted(key for key in set(before) | set(item.config)
807
+ if before.get(key) != item.config.get(key))})
808
+ servers[item.name] = item.config
809
+ result: dict[str, Any] = {"ok": True, "applied": apply, "operations": operations}
810
+ if not apply or not operations:
811
+ return result
812
+ if selected_mcps and layout.destination_mcp.suffix == ".jsonc":
813
+ raise AgentPackError("writing legacy JSONC destinations is intentionally unsupported")
814
+ recovery_base = (recovery_root or Path.home() / ".agent-pack" / "recovery").expanduser().resolve()
815
+ stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%S.%fZ")
816
+ transaction = recovery_base / f"{stamp}-transfer-{_package_name(layout.root)}"
817
+ transaction.mkdir(parents=True, mode=0o700)
818
+ moved, created = [], []
819
+ mcp_written = False
820
+ mcp_existed = layout.destination_mcp.exists()
821
+ try:
822
+ # Fully validate / copy Skill trees before changing any destination.
823
+ with tempfile.TemporaryDirectory(prefix="agent-pack-transfer-") as temporary:
824
+ staged = Path(temporary)
825
+ for item in skills_to_copy:
826
+ _copy_skill(Path(item.path), staged / item.name)
827
+ for item in skills_to_copy:
828
+ destination = layout.destination_skill_root / item.name
829
+ destination.parent.mkdir(parents=True, exist_ok=True)
830
+ if destination.exists():
831
+ archived = transaction / "skills" / item.name
832
+ archived.parent.mkdir(parents=True, exist_ok=True)
833
+ os.replace(destination, archived)
834
+ moved.append((archived, destination))
835
+ _copy_skill(staged / item.name, destination)
836
+ created.append(destination)
837
+ if mcp_payload != original_mcp:
838
+ if mcp_existed:
839
+ shutil.copy2(layout.destination_mcp, transaction / "mcp.json")
840
+ (transaction / "mcp.json").chmod(0o600)
841
+ _write_json_atomic(layout.destination_mcp, mcp_payload)
842
+ mcp_written = True
843
+ except Exception:
844
+ for destination in reversed(created):
845
+ shutil.rmtree(destination)
846
+ for archived, destination in reversed(moved):
847
+ os.replace(archived, destination)
848
+ if mcp_written:
849
+ if mcp_existed:
850
+ shutil.copy2(transaction / "mcp.json", layout.destination_mcp)
851
+ else:
852
+ layout.destination_mcp.unlink()
853
+ raise
854
+ result["recovery"] = str(transaction)
855
+ return result
723
856
 
724
857
 
725
858
  def _mcp_allowed(layout: ProjectLayout, name: str, client: str) -> bool:
@@ -828,7 +961,8 @@ def _portable_package_from_inventory(
828
961
  ]
829
962
  required_env: set[str] = set()
830
963
  for item in selected_mcps:
831
- required_env.update(_env_references(item.config))
964
+ if item.config.get("type") == "stdio":
965
+ required_env.update(_env_references(item.config))
832
966
  if required_env:
833
967
  if layout is None or layout.credential_env_file is None:
834
968
  raise AgentPackError(
@@ -844,11 +978,12 @@ def _portable_package_from_inventory(
844
978
  for item in selected_mcps:
845
979
  config = project_mcp_config(item)
846
980
  references = _env_references(config)
847
- if not references:
981
+ if not references or config.get("type") != "stdio":
982
+ if client == "cursor" and config.get("type") != "stdio" and isinstance(config.get("headers"), dict):
983
+ config["headers"] = {key: ENV_REFERENCE_RE.sub(r"${env:\1}", value)
984
+ for key, value in config["headers"].items()}
848
985
  rendered_mcps[item.name] = config
849
986
  continue
850
- if config.get("type") != "stdio":
851
- raise AgentPackError(f"environment-referenced remote MCP is unsupported: {item.name}")
852
987
  runtime_root = destination / "runtime"
853
988
  if not launcher_copied:
854
989
  runtime_root.mkdir(exist_ok=True)
@@ -879,7 +1014,7 @@ def _portable_package_from_inventory(
879
1014
  _write_json_atomic(destination / "plugin.json", manifest)
880
1015
 
881
1016
 
882
- def _codex_adapter(package_root: Path) -> None:
1017
+ def _codex_adapter(package_root: Path, *, native_remote: bool = False) -> None:
883
1018
  manifest = _read_json(package_root / "plugin.json")
884
1019
  codex_dir = package_root / ".codex-plugin"
885
1020
  codex_dir.mkdir(exist_ok=True)
@@ -905,6 +1040,13 @@ def _codex_adapter(package_root: Path) -> None:
905
1040
  codex_manifest.setdefault("mcpServers", "./.mcp.json")
906
1041
  _write_json_atomic(codex_manifest_path, codex_manifest)
907
1042
  mcp = _read_json(mcp_path)
1043
+ # Remote MCPs are synchronized through config.toml's native env-name fields;
1044
+ # do not load a second copy from the plugin with ambiguous header expansion.
1045
+ remote = {name: config for name, config in mcp.get("mcpServers", {}).items() if native_remote and config.get("type") != "stdio"}
1046
+ if remote:
1047
+ _write_json_atomic(package_root / "codex-remote-mcp.json", {"mcpServers": remote})
1048
+ mcp["mcpServers"] = {name: config for name, config in mcp["mcpServers"].items() if name not in remote}
1049
+ _write_json_atomic(mcp_path, mcp)
908
1050
  codex_mcps: dict[str, Any] = {}
909
1051
  for name, config in mcp.get("mcpServers", {}).items():
910
1052
  # Codex reads the portable mcp.json (${PLUGIN_ROOT}); this projection is
@@ -1007,7 +1149,7 @@ def _build_package(inventory: Inventory, package_name: str, parent: Path, client
1007
1149
  package = parent / package_name
1008
1150
  _portable_package_from_inventory(inventory, package_name, package, client=client)
1009
1151
  if client == "codex":
1010
- _codex_adapter(package)
1152
+ _codex_adapter(package, native_remote=True)
1011
1153
  return package
1012
1154
 
1013
1155
 
@@ -1383,6 +1525,10 @@ def reconcile_project(
1383
1525
  else:
1384
1526
  package_action = "replace-plugin"
1385
1527
 
1528
+ native_plan = None
1529
+ if client == "codex" and not retire_only:
1530
+ import agent_pack_codex_mcp
1531
+ native_plan = agent_pack_codex_mcp.plan(project, home, replace=replace)
1386
1532
  operations: list[dict[str, str]] = [] if retire_only else [
1387
1533
  {"action": package_action, "client": client, "name": package_name, "to": str(destination)}
1388
1534
  ]
@@ -1390,6 +1536,8 @@ def reconcile_project(
1390
1536
  {"action": "archive-" + kind, "name": name, "from": str(path)}
1391
1537
  for kind, name, path in retirement_targets
1392
1538
  )
1539
+ if native_plan is not None:
1540
+ operations.extend(native_plan["operations"])
1393
1541
  if not apply:
1394
1542
  return {"ok": True, "applied": False, "states": states, "operations": operations}
1395
1543
 
@@ -1400,6 +1548,7 @@ def reconcile_project(
1400
1548
  transaction.mkdir(mode=0o700)
1401
1549
  moved: list[tuple[Path, Path]] = []
1402
1550
  installed = False
1551
+ native_applied = False
1403
1552
  try:
1404
1553
  if needs_package:
1405
1554
  destination.parent.mkdir(parents=True, exist_ok=True)
@@ -1423,9 +1572,14 @@ def reconcile_project(
1423
1572
  archived.parent.mkdir(parents=True, exist_ok=True)
1424
1573
  os.replace(path, archived)
1425
1574
  moved.append((archived, path))
1575
+ if native_plan is not None:
1576
+ agent_pack_codex_mcp.apply(native_plan, transaction)
1577
+ native_applied = True
1426
1578
  if client == "codex" and needs_package:
1427
1579
  _update_personal_marketplace(home, package_name)
1428
1580
  except Exception as exc:
1581
+ if native_applied:
1582
+ agent_pack_codex_mcp.rollback(native_plan)
1429
1583
  if installed and destination.exists():
1430
1584
  shutil.rmtree(destination)
1431
1585
  for archived, original in reversed(moved):
@@ -1497,6 +1651,12 @@ def _package_mcps(package: Path) -> dict[str, Any]:
1497
1651
  return servers if isinstance(servers, dict) else {}
1498
1652
 
1499
1653
 
1654
+ def remote_missing_env(inventory: Inventory, layout: ProjectLayout, client: str) -> list[str]:
1655
+ return [f"MCP {item.name}: {name}" for item in inventory.mcps
1656
+ if item.portable and item.config.get("type") != "stdio" and _mcp_allowed(layout, item.name, client)
1657
+ for name in sorted(_env_references(item.config)) if not os.environ.get(name)]
1658
+
1659
+
1500
1660
  def client_drift(project: Path, client: str, home: Path | None = None) -> dict[str, Any]:
1501
1661
  """Compare what a client has installed for this project with the project's authority.
1502
1662
 
@@ -1508,7 +1668,11 @@ def client_drift(project: Path, client: str, home: Path | None = None) -> dict[s
1508
1668
  if client == "claude":
1509
1669
  import agent_pack_claude # noqa: PLC0415 - shipped next to this file
1510
1670
 
1511
- return agent_pack_claude.drift(project, home)
1671
+ report = agent_pack_claude.drift(project, home)
1672
+ layout = load_project_layout(project)
1673
+ report["missing_env"] = remote_missing_env(inventory_project(layout.root), layout, client)
1674
+ report["in_sync"] = report["in_sync"] and not report["missing_env"]
1675
+ return report
1512
1676
  home = (home or Path.home()).expanduser().resolve()
1513
1677
  layout = load_project_layout(project)
1514
1678
  authority = inventory_project(layout.root)
@@ -1541,7 +1705,16 @@ def client_drift(project: Path, client: str, home: Path | None = None) -> dict[s
1541
1705
  report["different"].append(f"package {name}: other files differ")
1542
1706
  native = _codex_mcps(home) if client == "codex" else _json_client_mcps(home / ".cursor" / "mcp.json")
1543
1707
  report["native"] = sorted(native)
1544
- report["in_sync"] = not (report["missing"] or report["different"] or report["stale"] or report["dangling"])
1708
+ if client == "codex":
1709
+ import agent_pack_codex_mcp
1710
+ for item in authority.mcps:
1711
+ if item.portable and item.config.get("type") != "stdio" and _mcp_allowed(layout, item.name, client):
1712
+ if item.name not in native:
1713
+ report["missing"].append(f"mcp {item.name}")
1714
+ elif native[item.name] != agent_pack_codex_mcp.native_entry(item.config):
1715
+ report["different"].append(f"mcp {item.name}")
1716
+ report["missing_env"] = remote_missing_env(authority, layout, client)
1717
+ report["in_sync"] = not (report["missing"] or report["different"] or report["stale"] or report["dangling"] or report["missing_env"])
1545
1718
  return report
1546
1719
 
1547
1720
 
@@ -1575,8 +1748,11 @@ def doctor(project: Path, clients: Iterable[str] = (), home: Path | None = None)
1575
1748
  )
1576
1749
  required_env: set[str] = set()
1577
1750
  for item in inventory.mcps:
1578
- if item.portable:
1751
+ if item.portable and item.config.get("type") == "stdio":
1579
1752
  required_env.update(_env_references(item.config))
1753
+ elif item.portable:
1754
+ issues.extend(f"MCP {item.name}: missing environment variable: {name}"
1755
+ for name in sorted(_env_references(item.config)) if not os.environ.get(name))
1580
1756
  if required_env:
1581
1757
  if layout.credential_env_file is None:
1582
1758
  issues.append("MCP environment references require capabilities.credential_env_file")
@@ -1590,7 +1766,7 @@ def doctor(project: Path, clients: Iterable[str] = (), home: Path | None = None)
1590
1766
  for client in dict.fromkeys(clients):
1591
1767
  report = client_drift(layout.root, client, home)
1592
1768
  reports[client] = report
1593
- for kind in ("missing", "different", "stale", "dangling"):
1769
+ for kind in ("missing", "different", "stale", "dangling", "missing_env"):
1594
1770
  issues.extend(f"{client}: {kind} {item}" for item in report[kind])
1595
1771
  if report["coupled"]:
1596
1772
  issues.append(f"{client}: install record points into another package directory: {report['coupled']}")
@@ -1653,6 +1829,8 @@ def build_parser() -> argparse.ArgumentParser:
1653
1829
  transfer_parser.add_argument("--mcp", action="append", default=[])
1654
1830
  transfer_parser.add_argument("--home", type=Path)
1655
1831
  transfer_parser.add_argument("--apply", action="store_true")
1832
+ transfer_parser.add_argument("--update", action="store_true", help="preview replacement of same-name project entries")
1833
+ transfer_parser.add_argument("--recovery-root", type=Path)
1656
1834
 
1657
1835
  sync_parser = sub.add_parser("sync")
1658
1836
  sync_parser.add_argument("--project", type=Path, default=Path.cwd())
@@ -1713,7 +1891,8 @@ def main(argv: list[str] | None = None) -> int:
1713
1891
  args.to_project,
1714
1892
  args.skill,
1715
1893
  args.mcp,
1716
- apply=args.apply,
1894
+ apply=args.apply, update=args.update,
1895
+ recovery_root=args.recovery_root or (args.home / ".agent-pack" / "recovery" if args.home else None),
1717
1896
  )
1718
1897
  elif args.command == "sync":
1719
1898
  result = sync_project(