firekeep-client 1.6.0__tar.gz → 1.7.0__tar.gz

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 (179) hide show
  1. {firekeep_client-1.6.0/firekeep_client.egg-info → firekeep_client-1.7.0}/PKG-INFO +1 -1
  2. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/__init__.py +1 -1
  3. firekeep_client-1.7.0/firekeep_client/childenv.py +192 -0
  4. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/cli.py +206 -5
  5. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/decision/server.py +41 -1
  6. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/dexes.py +42 -9
  7. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/gateway.py +26 -4
  8. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/hooks/stop.py +3 -1
  9. firekeep_client-1.7.0/firekeep_client/jobobject.py +192 -0
  10. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/shim.py +21 -5
  11. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/updater.py +49 -25
  12. {firekeep_client-1.6.0 → firekeep_client-1.7.0/firekeep_client.egg-info}/PKG-INFO +1 -1
  13. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client.egg-info/SOURCES.txt +6 -0
  14. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/pyproject.toml +1 -1
  15. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_bootstrap_ps1.py +4 -2
  16. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_bootstrap_sh.py +5 -3
  17. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli_dex.py +38 -0
  18. firekeep_client-1.7.0/tests/test_cli_hands.py +221 -0
  19. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli_update.py +117 -7
  20. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_decision_server.py +69 -0
  21. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_dexes.py +28 -0
  22. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_e2e_bootstrap.py +13 -0
  23. firekeep_client-1.7.0/tests/test_gateway_child_env.py +347 -0
  24. firekeep_client-1.7.0/tests/test_jobobject.py +347 -0
  25. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_make_release.py +47 -0
  26. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_package.py +1 -1
  27. firekeep_client-1.7.0/tests/test_shim_eof_exit.py +127 -0
  28. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_updater.py +63 -7
  29. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/LICENSE +0 -0
  30. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/NOTICE +0 -0
  31. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/README.md +0 -0
  32. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/adapters/__init__.py +0 -0
  33. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/adapters/base.py +0 -0
  34. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/adapters/claude.py +0 -0
  35. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/adapters/claude_desktop.py +0 -0
  36. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/adapters/codex.py +0 -0
  37. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/adapters/generic.py +0 -0
  38. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/adapters/kiro.py +0 -0
  39. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/adapters/opencode.py +0 -0
  40. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/adapters/pi.py +0 -0
  41. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/autoupdate.py +0 -0
  42. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/background.py +0 -0
  43. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/backups.py +0 -0
  44. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/config_write.py +0 -0
  45. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/connect.py +0 -0
  46. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/contract/__init__.py +0 -0
  47. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/contract/matrix.py +0 -0
  48. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/decision/__init__.py +0 -0
  49. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/decision/board.py +0 -0
  50. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/docdexsync.py +0 -0
  51. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/hooklog.py +0 -0
  52. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/hooks/__init__.py +0 -0
  53. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/hooks/__main__.py +0 -0
  54. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/hooks/_git.py +0 -0
  55. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/hooks/_mcp.py +0 -0
  56. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/hooks/destructive.py +0 -0
  57. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/hooks/post_tool.py +0 -0
  58. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/hooks/pre_tool.py +0 -0
  59. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/hooks/precompact.py +0 -0
  60. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/hooks/prompt.py +0 -0
  61. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/hooks/runbooks.py +0 -0
  62. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/hooks/session_end.py +0 -0
  63. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/hooks/session_start.py +0 -0
  64. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/join.py +0 -0
  65. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/joincode.py +0 -0
  66. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/maildexsync.py +0 -0
  67. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/migrate.py +0 -0
  68. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/nightshift.py +0 -0
  69. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/nightshiftdrain.py +0 -0
  70. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/pathenv.py +0 -0
  71. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/promptrecall.py +0 -0
  72. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/report.py +0 -0
  73. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/resolver.py +0 -0
  74. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/serverinit.py +0 -0
  75. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/serverupdate.py +0 -0
  76. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/sidecar.py +0 -0
  77. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/signing.py +0 -0
  78. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/state.py +0 -0
  79. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/stdio.py +0 -0
  80. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/symdexindex.py +0 -0
  81. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/transport.py +0 -0
  82. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/wizard.py +0 -0
  83. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client/worktree_snapshot.py +0 -0
  84. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client.egg-info/dependency_links.txt +0 -0
  85. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client.egg-info/entry_points.txt +0 -0
  86. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client.egg-info/requires.txt +0 -0
  87. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/firekeep_client.egg-info/top_level.txt +0 -0
  88. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/setup.cfg +0 -0
  89. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_attribution_headers.py +0 -0
  90. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_autoupdate.py +0 -0
  91. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_background.py +0 -0
  92. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_bash_layer_retired.py +0 -0
  93. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_bootstrap_consent_pty.py +0 -0
  94. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_bootstrap_docdex.py +0 -0
  95. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_bootstrap_maildex.py +0 -0
  96. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_bootstrap_reinstall.py +0 -0
  97. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_bootstrap_symdex.py +0 -0
  98. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_bootstrap_venv_provisioning.py +0 -0
  99. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_ci_publishes_symdex.py +0 -0
  100. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli.py +0 -0
  101. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli_backup.py +0 -0
  102. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli_docdex.py +0 -0
  103. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli_doctor.py +0 -0
  104. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli_doctor_generic.py +0 -0
  105. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli_doctor_report.py +0 -0
  106. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli_entry.py +0 -0
  107. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli_generic_install.py +0 -0
  108. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli_install.py +0 -0
  109. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli_maildex.py +0 -0
  110. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli_onboarding.py +0 -0
  111. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli_personal.py +0 -0
  112. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli_uninstall.py +0 -0
  113. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_cli_uninstall_generic.py +0 -0
  114. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_config_migration.py +0 -0
  115. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_connect.py +0 -0
  116. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_decision_board_html.py +0 -0
  117. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_decision_bypass.py +0 -0
  118. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_decision_poll_ceiling.py +0 -0
  119. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_decision_registration.py +0 -0
  120. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_docdexsync.py +0 -0
  121. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_docs_reference_client_kit.py +0 -0
  122. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_doctor_credential_expiry.py +0 -0
  123. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_doctor_embeddings.py +0 -0
  124. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_doctor_no_server.py +0 -0
  125. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_gateway.py +0 -0
  126. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_gateway_schema_slimming.py +0 -0
  127. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_gateway_toolset.py +0 -0
  128. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_generic_config.py +0 -0
  129. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_hooklog.py +0 -0
  130. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_import_boundary.py +0 -0
  131. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_init_self_enroll.py +0 -0
  132. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_init_stale_bundle.py +0 -0
  133. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_install_skill_contract.py +0 -0
  134. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_instruction_budget.py +0 -0
  135. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_join.py +0 -0
  136. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_join_config_write.py +0 -0
  137. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_joincode.py +0 -0
  138. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_kit_smoke.py +0 -0
  139. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_maildexsync.py +0 -0
  140. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_memory_instructions.py +0 -0
  141. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_migration_entrypoints.py +0 -0
  142. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_nightshift.py +0 -0
  143. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_nightshiftdrain.py +0 -0
  144. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_pathenv.py +0 -0
  145. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_promptrecall.py +0 -0
  146. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_report_bootstrap_enums.py +0 -0
  147. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_report_capture.py +0 -0
  148. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_report_consent.py +0 -0
  149. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_report_consent_surfaces.py +0 -0
  150. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_report_flush_points.py +0 -0
  151. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_report_integration.py +0 -0
  152. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_report_schema.py +0 -0
  153. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_report_spool.py +0 -0
  154. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_resolver.py +0 -0
  155. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_resolver_bypass.py +0 -0
  156. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_resolver_single_connection.py +0 -0
  157. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_runbook_match_parity.py +0 -0
  158. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_runbook_state.py +0 -0
  159. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_scratch_ttl.py +0 -0
  160. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_serverinit.py +0 -0
  161. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_serverupdate.py +0 -0
  162. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_shim_bridge.py +0 -0
  163. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_shim_bypass.py +0 -0
  164. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_shim_fail_loud.py +0 -0
  165. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_shim_identity.py +0 -0
  166. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_shim_recovery.py +0 -0
  167. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_shim_skeleton.py +0 -0
  168. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_sidecar.py +0 -0
  169. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_sidecar_robustness.py +0 -0
  170. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_signing.py +0 -0
  171. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_state.py +0 -0
  172. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_stdio_encoding.py +0 -0
  173. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_symdexindex.py +0 -0
  174. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_transport.py +0 -0
  175. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_transport_sse.py +0 -0
  176. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_twin_removed.py +0 -0
  177. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_wizard.py +0 -0
  178. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_wizard_generic.py +0 -0
  179. {firekeep_client-1.6.0 → firekeep_client-1.7.0}/tests/test_worktree_snapshot.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: firekeep-client
3
- Version: 1.6.0
3
+ Version: 1.7.0
4
4
  Summary: Client for Firekeep, the self-hosted operating layer for connected AI agents.
5
5
  License-Expression: LicenseRef-Firekeep-BUSL-1.1
6
6
  Project-URL: Homepage, https://firekeep.ai
@@ -9,4 +9,4 @@ versions without a verdict (`_check_versions`) and judges staleness against the
9
9
  release manifest instead (`_check_client_version`).
10
10
  """
11
11
 
12
- __version__ = "1.6.0"
12
+ __version__ = "1.7.0"
@@ -0,0 +1,192 @@
1
+ """The environment a gateway backend child is started with.
2
+
3
+ The gateway runs wherever an agent runtime runs: a developer shell, a CI
4
+ runner, the server-side ChatGPT tunnel (``deploy/chatgpt-tunnel/``). Any of
5
+ those can hold server service credentials — ``FIREKEEP_INTERNAL_KEY``,
6
+ ``RELAY_INTERNAL_API_KEY``, ``VAULT_KEY`` and the rest of a deployment's
7
+ ``.env``. Backend children (the four shims, the decision server, every
8
+ ``mcp-stdio`` dex or capability in the registry) used to inherit that
9
+ environment whole, and symdex's Cortex client read ``FIREKEEP_INTERNAL_KEY``
10
+ from it — so a dex child could act with the deployment's service key instead
11
+ of the member's enrolled key.
12
+
13
+ A child now gets an ALLOWLISTED environment: what a process needs to run (OS,
14
+ locale, proxy and TLS, the desktop session), the kit's own non-secret
15
+ ``FIREKEEP_*`` knobs, and — only for the child that owns it — a credential that
16
+ child is documented to read (symdex's LLM provider keys, the decision server's
17
+ notify token). Anything else is dropped. Symdex additionally receives the
18
+ member's enrolled Cortex connection, resolved from ``~/.firekeep/config`` and
19
+ passed explicitly (``FIREKEEP_CORTEX_URL`` / ``FIREKEEP_CLIENT_API_KEY`` /
20
+ ``FIREKEEP_CORTEX_CA``); the parent's copies of those names are never
21
+ forwarded, so the config, not ambient environment, decides who symdex is.
22
+
23
+ ``client/tests/test_gateway_child_env.py`` scans every child package for the
24
+ environment names it reads and fails on any name not classified here — the
25
+ allowlist cannot silently fall behind a new knob.
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ import os
31
+ from collections.abc import Callable, Mapping
32
+
33
+ # Names match case-insensitively (Windows environment names are; POSIX proxies
34
+ # are conventionally lower-case) and keep their original spelling in the child.
35
+
36
+ _OS_WINDOWS = frozenset({
37
+ "SYSTEMROOT", "SYSTEMDRIVE", "WINDIR", "COMSPEC", "PATHEXT", "TEMP", "TMP",
38
+ "USERPROFILE", "HOMEDRIVE", "HOMEPATH", "APPDATA", "LOCALAPPDATA",
39
+ "PROGRAMDATA", "ALLUSERSPROFILE", "PUBLIC", "PROGRAMFILES",
40
+ "PROGRAMFILES(X86)", "PROGRAMW6432", "COMMONPROGRAMFILES",
41
+ "COMMONPROGRAMFILES(X86)", "COMMONPROGRAMW6432", "USERNAME", "USERDOMAIN",
42
+ "COMPUTERNAME", "NUMBER_OF_PROCESSORS", "PROCESSOR_ARCHITECTURE", "OS",
43
+ })
44
+ _OS_POSIX = frozenset({
45
+ "PATH", "HOME", "USER", "LOGNAME", "SHELL", "TMPDIR", "LANG", "LANGUAGE",
46
+ "TZ", "TERM", "__CF_USER_TEXT_ENCODING",
47
+ # The desktop session: the decision server opens a browser and Hands drives
48
+ # the desktop, both from the child's environment.
49
+ "DISPLAY", "WAYLAND_DISPLAY", "XAUTHORITY", "DBUS_SESSION_BUS_ADDRESS",
50
+ })
51
+ _NETWORK = frozenset({
52
+ "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "ALL_PROXY",
53
+ "SSL_CERT_FILE", "SSL_CERT_DIR", "REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE",
54
+ })
55
+ _PYTHON = frozenset({"VIRTUAL_ENV"})
56
+
57
+ # The kit's own non-secret knobs, as the children (and the client code they
58
+ # import) read them. Identity labels such as NEXUS_AGENT_ID are labels, not
59
+ # credentials — the server derives identity from the key.
60
+ _KIT = frozenset({
61
+ # resolver / state / logging / reporting — every shim and Hands use these
62
+ "FIREKEEP_CONFIG", "FIREKEEP_CACHE_DIR", "FIREKEEP_LOG_DIR",
63
+ "FIREKEEP_AGENT_ID", "FIREKEEP_RUNTIME", "FIREKEEP_BYPASS",
64
+ "FIREKEEP_PERSONAL_TTL_HOURS", "FIREKEEP_SESSION_STASH_TTL_HOURS",
65
+ "FIREKEEP_SHIM_DEBUG", "FIREKEEP_NO_JOB_OBJECT",
66
+ "FIREKEEP_REPORT_CONSENT", "FIREKEEP_REPORT_DIR",
67
+ "FIREKEEP_FAILURE_REPORT", "FIREKEEP_NO_FAILURE_REPORT",
68
+ "FIREKEEP_SESSION_ID", "NEXUS_AGENT_ID",
69
+ # hook-side knobs the client modules a child imports may consult
70
+ "FIREKEEP_AGENT_GOAL", "FIREKEEP_BRIEFING", "FIREKEEP_NO_AUTO_UPDATE",
71
+ "FIREKEEP_NO_AUTO_SYNC", "FIREKEEP_NO_AUTO_INDEX", "FIREKEEP_NO_AUTO_NIGHTSHIFT",
72
+ "FIREKEEP_NO_RECALL_PUSH", "FIREKEEP_RECALL_PUSH_MIN_SCORE",
73
+ "FIREKEEP_RECALL_PUSH_TIMEOUT_SECONDS", "FIREKEEP_SIDECAR_INTERVAL",
74
+ "FIREKEEP_SNAPSHOT_DIR", "FIREKEEP_SNAPSHOT_KEEP", "FIREKEEP_SNAPSHOT_MAX_BYTES",
75
+ "FIREKEEP_NIGHTSHIFT_AGENT_ID", "FIREKEEP_NIGHTSHIFT_ALLOW_REMOTE",
76
+ "FIREKEEP_NIGHTSHIFT_LLM_BASE", "FIREKEEP_NIGHTSHIFT_LLM_MODEL",
77
+ "FIREKEEP_NIGHTSHIFT_DRAIN_INTERVAL_HOURS",
78
+ # decision server
79
+ "FIREKEEP_DECISION_HEADLESS", "FIREKEEP_DECISION_SURFACE",
80
+ "FIREKEEP_DECISION_NOTIFY_URL", "DECISION_INGEST_CLIENT_TIMEOUT_SECONDS",
81
+ # symdex
82
+ "CODE_INDEX_PATH", "SYMDEX_ANALYTICS_ENABLED", "FIREKEEP_SYMDEX_HOST",
83
+ "FIREKEEP_SYMDEX_PORT", "FIREKEEP_SYMDEX_MODE", "FIREKEEP_SYMDEX_MAX_FILES",
84
+ "FIREKEEP_SYMDEX_MAX_RESULT_TOKENS", "FIREKEEP_SYMDEX_SHARE_STATS",
85
+ # hands
86
+ "FIREKEEP_HANDS_OFFLINE", "FIREKEEP_HANDS_LOG", "FIREKEEP_HANDS_TRACE_KEYS",
87
+ # docdex / maildex (ingest clients: no gateway child today, classified so a
88
+ # future mcp-stdio entry inherits a working environment)
89
+ "FIREKEEP_DOCDEX_MAX_EXTRACT_KB", "FIREKEEP_DOCDEX_MAX_FILES",
90
+ "FIREKEEP_DOCDEX_MAX_FILE_MB", "FIREKEEP_DOCDEX_INGEST_TIMEOUT_SECONDS",
91
+ "FIREKEEP_DOCDEX_SYNC_INTERVAL_HOURS",
92
+ "FIREKEEP_MAILDEX_BACKFILL_DAYS", "FIREKEEP_MAILDEX_MAX_MESSAGE_KB",
93
+ "FIREKEEP_MAILDEX_INGEST_TIMEOUT_SECONDS", "FIREKEEP_MAILDEX_MAX_PER_SYNC",
94
+ "FIREKEEP_MAILDEX_SYNC_INTERVAL_HOURS",
95
+ })
96
+
97
+ ALLOWED_NAMES: frozenset[str] = _OS_WINDOWS | _OS_POSIX | _NETWORK | _PYTHON | _KIT
98
+ ALLOWED_PREFIXES: tuple[str, ...] = ("LC_", "XDG_", "PYTHON")
99
+
100
+ # A credential a child is documented to read reaches THAT child only.
101
+ CHILD_EXTRAS: dict[str, frozenset[str]] = {
102
+ # symdex's own features: AI symbol summaries / scaffolding and GitHub
103
+ # repository indexing (symdex/README.md).
104
+ "symdex": frozenset({
105
+ "ANTHROPIC_API_KEY", "GOOGLE_API_KEY", "OPENAI_API_KEY",
106
+ "OPENAI_API_BASE", "OPENAI_MODEL", "OPENAI_TIMEOUT", "GITHUB_TOKEN",
107
+ }),
108
+ # the bearer for the decision board's optional notify webhook
109
+ "decision": frozenset({"FIREKEEP_DECISION_NOTIFY_TOKEN"}),
110
+ }
111
+
112
+ # Classified and deliberately NOT forwarded to any child.
113
+ NOT_FORWARDED: frozenset[str] = frozenset({
114
+ # Server service credentials. The allowlist already drops them; they are
115
+ # named here so the intent is greppable and the tests can assert it.
116
+ "FIREKEEP_INTERNAL_KEY", "FIREKEEP_BRIDGE_KEY", "NS_FIREKEEP_INTERNAL_KEY",
117
+ "RELAY_INTERNAL_API_KEY", "DASHBOARD_API_KEY", "VAULT_KEY", "NEO4J_PASSWORD",
118
+ "FIREKEEP_SIGNING_KEY",
119
+ # An enrolment code is a credential; only `firekeep join` reads it.
120
+ "FIREKEEP_JOIN",
121
+ # Set by the gateway from ~/.firekeep/config for symdex alone; a parent's
122
+ # copy (stale shell export, another member's key) is never authoritative.
123
+ "FIREKEEP_CORTEX_URL", "FIREKEEP_CLIENT_API_KEY", "FIREKEEP_CORTEX_CA",
124
+ # The gateway's own surface: a child must not be able to re-read or widen it.
125
+ "FIREKEEP_TOOLSET", "FIREKEEP_TOOLS_ALLOW",
126
+ # Install/update trust path: no gateway child installs or updates the kit,
127
+ # and a trust-anchor override has no business reaching one.
128
+ "FIREKEEP_DIST_BASE", "FIREKEEP_SERVER_DIST_BASE", "FIREKEEP_SIGNING_PUB",
129
+ "FIREKEEP_SUMS_FILE", "FIREKEEP_VERSION", "FIREKEEP_INSTALL_TIMEOUT",
130
+ "FIREKEEP_SERVER_INSTALL_TIMEOUT", "FIREKEEP_NO_MODIFY_PATH", "FIREKEEP_PROFILE",
131
+ # Adapter render-time only.
132
+ "PI_CODING_AGENT_CONFIG_DIR",
133
+ })
134
+
135
+
136
+ def child_environment(
137
+ name: str, *, source: Mapping[str, str] | None = None
138
+ ) -> dict[str, str]:
139
+ """The allowlisted subset of ``source`` (default: this process's
140
+ environment) that backend ``name`` may see. Never mutates ``source``."""
141
+ environ = os.environ if source is None else source
142
+ extras = CHILD_EXTRAS.get(name, frozenset())
143
+ kept: dict[str, str] = {}
144
+ for key, value in environ.items():
145
+ upper = key.upper()
146
+ if upper in NOT_FORWARDED:
147
+ continue
148
+ if upper in ALLOWED_NAMES or upper in extras or upper.startswith(ALLOWED_PREFIXES):
149
+ kept[key] = value
150
+ return kept
151
+
152
+
153
+ def cortex_connection() -> dict[str, str]:
154
+ """The member's enrolled Cortex REST connection, for symdex.
155
+
156
+ Empty — symdex's Cortex tools then report "not configured", exactly as
157
+ before this connection was passed — when the machine is not enrolled, the
158
+ config is unreadable, or the kit is bypassed (personal mode /
159
+ ``FIREKEEP_BYPASS``) at spawn: the shims serve zero tools then, and symdex
160
+ must not keep a live member connection to the Keep either. Never raises: a
161
+ broken config must cost symdex its Cortex tools, not its mount."""
162
+ from firekeep_client import resolver
163
+
164
+ try:
165
+ if resolver.is_bypassed():
166
+ return {}
167
+ endpoint = resolver.resolve("cortex", resolver.load_config())
168
+ except Exception: # noqa: BLE001 - see docstring
169
+ return {}
170
+ connection = {"FIREKEEP_CORTEX_URL": endpoint.rest_base}
171
+ api_key = endpoint.headers.get("X-API-Key")
172
+ if api_key:
173
+ connection["FIREKEEP_CLIENT_API_KEY"] = api_key
174
+ if isinstance(endpoint.verify, str):
175
+ # A CA file path, or resolver.OS_TRUST ("os").
176
+ connection["FIREKEEP_CORTEX_CA"] = endpoint.verify
177
+ return connection
178
+
179
+
180
+ # Backends that receive something beyond the allowlist, computed at spawn.
181
+ _INJECTED: dict[str, Callable[[], dict[str, str]]] = {"symdex": cortex_connection}
182
+
183
+
184
+ def backend_environment(name: str) -> dict[str, str]:
185
+ """Everything backend ``name`` is started with. Computed when the child is
186
+ (re)started, not when the gateway is built, so an enrolment or a personal
187
+ toggle between restarts is honoured."""
188
+ environment = child_environment(name)
189
+ inject = _INJECTED.get(name)
190
+ if inject is not None:
191
+ environment.update(inject())
192
+ return environment
@@ -154,6 +154,16 @@ EMPTY_REGISTRY_HINT = (
154
154
  "then `firekeep dex add docdex`"
155
155
  )
156
156
 
157
+ # The PyPI spec `firekeep hands enable` installs by default. Hands is NOT
158
+ # bundled by the bootstrap (a capability that moves the mouse is opt-in, spec
159
+ # §3.1), so this is the one place in the kit that names the wheel's source.
160
+ HANDS_WHEEL_SPEC = "firekeep-hands>=0.1,<0.2"
161
+
162
+ # Flip to True in the release that first publishes firekeep-hands through the
163
+ # `pypi-hands` trusted publisher (Task 13). Until then a bare `pip install
164
+ # firekeep-hands` could resolve to whoever registers the name first.
165
+ HANDS_PYPI_PUBLISHED = False
166
+
157
167
 
158
168
  def _current_link(home: Path | None = None) -> Path:
159
169
  return (home if home is not None else _firekeep_home()) / CURRENT_LINK_NAME
@@ -1235,6 +1245,8 @@ def _check_dexes() -> list[tuple[str, str, str]]:
1235
1245
  rows.append(_check_docdex())
1236
1246
  if any(m.name == "maildex" for m in registered):
1237
1247
  rows.append(_check_maildex())
1248
+ if any(m.name == "hands" for m in registered):
1249
+ rows.append(_check_hands())
1238
1250
  return rows
1239
1251
 
1240
1252
 
@@ -1330,6 +1342,45 @@ def _check_maildex() -> tuple[str, str, str]:
1330
1342
  return ("maildex", "warn" if failures else "ok", detail)
1331
1343
 
1332
1344
 
1345
+ def _check_hands() -> tuple[str, str, str]:
1346
+ """Hands' own row: wheel present, broker answering, and what approves.
1347
+
1348
+ The broker is the safety boundary — with it down every protected step is
1349
+ refused (fail closed), so its absence is the one thing this row must say
1350
+ loudly. A running broker that nothing can APPROVE through is the same
1351
+ outcome reached quietly, and phone approvals being off by default is what
1352
+ makes it reachable: a machine whose chord listener could not install has no
1353
+ approval path at all, and every protected step fails closed with no
1354
+ diagnosis anywhere. That case warns too, and names the fix.
1355
+
1356
+ The remedy text carries BOTH platforms' fixes in one string on purpose.
1357
+ Doctor cannot tell why a listener failed — `/health` reports only that it is
1358
+ unavailable — and the machine reading this row is not necessarily the one
1359
+ the broker runs on. Permissions (accessibility, screen recording, input
1360
+ monitoring) are the wheel's to report; `firekeep hands status` shows them."""
1361
+ if not dexes.is_installed(dexes.KNOWN_DEXES["hands"]):
1362
+ return ("hands", "fail", "registered but the wheel is missing — `firekeep hands enable`")
1363
+ health = read_broker_health()
1364
+ if not health:
1365
+ return ("hands", "warn",
1366
+ "broker not running — protected steps are refused until it is "
1367
+ "(`firekeep-hands-broker run`, or re-run `firekeep hands enable`)")
1368
+ listeners = health.get("listeners") or {}
1369
+ chord, phone = listeners.get("chord", "?"), listeners.get("phone", "?")
1370
+ if chord == "unavailable" and phone != "active":
1371
+ return ("hands", "warn",
1372
+ "broker up but NOTHING can approve — the chord listener is unavailable "
1373
+ f"and phone approvals are {phone}, so every protected step is refused. "
1374
+ "macOS: grant Input Monitoring to this kit's python "
1375
+ "(System Settings → Privacy & Security → Input Monitoring) and restart "
1376
+ "the broker. Windows: re-run `firekeep hands enable` to restore the "
1377
+ "startup entry. Or opt in to phone approvals with `firekeep hands config "
1378
+ "set phone_approvals true` after reading what that trusts in "
1379
+ "docs/guides/hands.md")
1380
+ return ("hands", "ok",
1381
+ f"broker up · chord {health.get('chord', '?')} ({chord}) · phone {phone}")
1382
+
1383
+
1333
1384
  def _check_backup(cfg=None, *, reachable: bool = True) -> tuple[str, str, str]:
1334
1385
  """Is anything but one disk holding this Keep?
1335
1386
 
@@ -1984,8 +2035,9 @@ def cmd_dex(args) -> int:
1984
2035
  if action == "list":
1985
2036
  print("firekeep dexes — the domain indexes this Keep understands\n")
1986
2037
  for manifest in dexes.KNOWN_DEXES.values():
2038
+ verb = "operates" if manifest.role == "capability" else "indexes"
1987
2039
  print(f" {manifest.name} [{_dex_state(manifest, registry)}] "
1988
- f"indexes {manifest.indexes}")
2040
+ f"{verb} {manifest.indexes}")
1989
2041
  print(f" {manifest.description}")
1990
2042
  # Names in the file with no manifest here: a hand-edited entry, or a dex
1991
2043
  # from a newer client after a rollback. The gateway ignores them; a
@@ -2017,6 +2069,16 @@ def cmd_dex(args) -> int:
2017
2069
  if name in registry:
2018
2070
  print(f"firekeep: {name} is already registered — nothing to do.")
2019
2071
  return 0
2072
+ # A capability is registered by its own command, which also installs
2073
+ # the wheel, records where it came from and sets up its broker. The
2074
+ # generic `add` would stamp it `source: "bundled"` — a false statement
2075
+ # about a wheel the bootstrap never bundles — and skip the autostart.
2076
+ if manifest.role == "capability":
2077
+ print(f"firekeep: {name} is a capability — enable it with "
2078
+ f"`firekeep {name} enable` (that installs the wheel, records its "
2079
+ f"source and sets up its broker); `firekeep dex add` is for indexes.",
2080
+ file=sys.stderr)
2081
+ return 1
2020
2082
  # Prove the code is there BEFORE writing the entry. Registering a dex
2021
2083
  # whose wheel is absent trades a clear error now for a silent missing
2022
2084
  # tool next session, which is the harder failure to diagnose by far.
@@ -2102,6 +2164,118 @@ def cmd_docdex(args) -> int:
2102
2164
  return int(exc.code or 0)
2103
2165
 
2104
2166
 
2167
+ def _hands_dir() -> Path:
2168
+ return _config_path().parent / "hands"
2169
+
2170
+
2171
+ def read_broker_health(timeout: float = 1.0) -> dict | None:
2172
+ """The approval broker's /health, or None when it is not running.
2173
+
2174
+ Stdlib only and read from disk first: `broker.json` names the loopback
2175
+ port and bearer token the running broker chose. No file, or a refused
2176
+ connection, both mean "not running" — doctor must not hang on it."""
2177
+ import urllib.error
2178
+ import urllib.request
2179
+ path = _hands_dir() / "broker.json"
2180
+ try:
2181
+ info = json.loads(path.read_text(encoding="utf-8"))
2182
+ port, token = int(info["port"]), str(info["token"])
2183
+ except (OSError, ValueError, KeyError, TypeError):
2184
+ return None
2185
+ req = urllib.request.Request(
2186
+ f"http://127.0.0.1:{port}/health", headers={"Authorization": f"Bearer {token}"}
2187
+ )
2188
+ try:
2189
+ with urllib.request.urlopen(req, timeout=timeout) as resp: # noqa: S310 — loopback only
2190
+ data = json.loads(resp.read().decode("utf-8"))
2191
+ except (urllib.error.URLError, OSError, ValueError):
2192
+ return None
2193
+ return data if isinstance(data, dict) and data.get("ok") else None
2194
+
2195
+
2196
+ def _run_hands_broker(argv: list[str]) -> int:
2197
+ """Run the wheel's broker console script (install-autostart etc.) in-process."""
2198
+ try:
2199
+ from firekeep_hands.broker.__main__ import main as broker_main
2200
+ except ImportError:
2201
+ print("firekeep: firekeep-hands is not importable in this venv — run "
2202
+ "`firekeep hands enable`", file=sys.stderr)
2203
+ return 1
2204
+ return int(broker_main(argv) or 0)
2205
+
2206
+
2207
+ def cmd_hands(args) -> int:
2208
+ """`firekeep hands enable|disable|status|allow|chord|config|evidence`.
2209
+
2210
+ enable/disable are the kit's own (they touch the venv and the registry —
2211
+ spec §3.1: Hands is installed on demand, never bundled). Everything else
2212
+ is a translator onto `firekeep_hands.cli.main`, imported lazily so a kit
2213
+ without the wheel keeps every other command working.
2214
+
2215
+ PyPI squat guard (2026-09-05 ruling): `firekeep-hands` is not published
2216
+ yet, so a bare `enable` (no `--from`, no `--pypi`) refuses rather than
2217
+ `pip install`-ing a name a third party could still claim.
2218
+ """
2219
+ action = getattr(args, "action", None) or "status"
2220
+ manifest = dexes.KNOWN_DEXES["hands"]
2221
+
2222
+ if action == "enable":
2223
+ source = (getattr(args, "source", None) or "").strip()
2224
+ if not source:
2225
+ if getattr(args, "pypi", False) and HANDS_PYPI_PUBLISHED:
2226
+ source = HANDS_WHEEL_SPEC
2227
+ else:
2228
+ print("firekeep: firekeep-hands is not yet published to PyPI — install from a "
2229
+ "checkout: `firekeep hands enable --from <checkout>/hands`", file=sys.stderr)
2230
+ return 2
2231
+ print(f"firekeep: installing {source} into this kit's venv …")
2232
+ try:
2233
+ _pip_install(sys.executable, source)
2234
+ except Exception as exc: # noqa: BLE001 — pip's failure text is the diagnosis
2235
+ print(f"firekeep: install failed: {exc}", file=sys.stderr)
2236
+ return 1
2237
+ if not dexes.is_installed(manifest):
2238
+ print("firekeep: firekeep-hands installed but not importable "
2239
+ f"(no module '{manifest.import_probe}') — not registering it",
2240
+ file=sys.stderr)
2241
+ return 1
2242
+ # Provenance, recorded truthfully. Hands is the one wheel the bootstrap
2243
+ # never bundles, so stamping the registry's `"bundled"` default here
2244
+ # would put a false statement about where this machine's code came from
2245
+ # into the user's own file. `--from` installed a local directory or
2246
+ # wheel; anything else came off PyPI.
2247
+ dexes.add("hands", source="checkout" if getattr(args, "source", None) else "pypi")
2248
+ rc = 0
2249
+ if not getattr(args, "no_autostart", False):
2250
+ rc = _run_hands_broker(["install-autostart"])
2251
+ if rc:
2252
+ print("firekeep: broker autostart could not be installed — start it by "
2253
+ "hand with `firekeep-hands-broker run`", file=sys.stderr)
2254
+ print("firekeep: Hands is registered — your runtimes get the hands_* tools on "
2255
+ "the next agent session.\n"
2256
+ "firekeep: approve consequential steps with the chord "
2257
+ "(`firekeep hands chord` shows it) or from the dashboard on your phone.")
2258
+ return 0
2259
+
2260
+ if action == "disable":
2261
+ if "hands" in dexes.read_registry():
2262
+ dexes.remove("hands")
2263
+ _run_hands_broker(["uninstall-autostart"])
2264
+ if getattr(args, "purge", False):
2265
+ shutil.rmtree(_hands_dir(), ignore_errors=True)
2266
+ print("firekeep: Hands is off — the tools disappear on the next agent session"
2267
+ + (" and its local files are gone." if getattr(args, "purge", False)
2268
+ else "; `firekeep hands disable --purge` also removes its files."))
2269
+ return 0
2270
+
2271
+ try:
2272
+ from firekeep_hands import cli as hands_cli
2273
+ except ImportError:
2274
+ print("firekeep: Hands is not installed — run `firekeep hands enable`", file=sys.stderr)
2275
+ return 1
2276
+ return int(hands_cli.main([action, *list(getattr(args, "rest", []) or [])]) or 0)
2277
+
2278
+
2105
2279
  def _register_maildex() -> None:
2106
2280
  """Register maildex, if it is not already, on the way into `maildex add`.
2107
2281
 
@@ -2877,9 +3051,10 @@ def cmd_update(args) -> int:
2877
3051
  # the bootstrap will install, so `--to <older>` must verify THAT version's sums,
2878
3052
  # not latest's (security review, MEDIUM: verifying manifest.version while the
2879
3053
  # bootstrap pinned FIREKEEP_VERSION=target left every rollback unsigned, even
2880
- # under require_signed=true). verify-if-present — absence warns (until
2881
- # [dist] require_signed flips), an invalid signature is always fatal inside
2882
- # fetch_signed_sums itself.
3054
+ # under require_signed=true). Under [dist] require_signed (default true) an
3055
+ # unverifiable target is refused (UnverifiedReleaseError, persisted below);
3056
+ # under an explicit `false` absence only warns. An invalid signature is
3057
+ # always fatal inside fetch_signed_sums itself.
2883
3058
  req_signed = updater.require_signed(cfg)
2884
3059
  signed = updater.fetch_signed_sums(base, target, require_signed=req_signed)
2885
3060
  # The bootstrap SCRIPT we execute is always latest/'s, whose bytes are listed in
@@ -2906,7 +3081,7 @@ def cmd_update(args) -> int:
2906
3081
  # require_signed=false, and an invisible warning is no warning).
2907
3082
  state.note_unsigned_update(
2908
3083
  f"client update to {target} ran WITHOUT a verified release signature "
2909
- f"({warnings[0]}); [dist] require_signed=false tolerates this — "
3084
+ f"({warnings[0]}); your [dist] require_signed = false allows this — "
2910
3085
  f"see docs/RELEASE-SIGNING.md"
2911
3086
  )
2912
3087
  # The checksum is REQUIRED here: we are about to EXECUTE this script. Verifying uv
@@ -2936,6 +3111,16 @@ def cmd_update(args) -> int:
2936
3111
  except resolver.ConfigMigrationConflict as exc:
2937
3112
  print(f"firekeep: {exc}", file=sys.stderr)
2938
3113
  return 3
3114
+ except updater.UnverifiedReleaseError as exc:
3115
+ print(f"firekeep: {exc}", file=sys.stderr)
3116
+ # The mirror of the installed-unsigned notice above: the background
3117
+ # auto-update (how almost every install updates) runs with stderr on
3118
+ # DEVNULL, so a refusal printed only here would recur daily, unseen.
3119
+ # Persist it for the next session-start briefing. Only the overridable
3120
+ # refusals take this path — an INVALID signature is plain UpdateError and
3121
+ # must never be framed as something `require_signed = false` fixes.
3122
+ state.note_unsigned_update(f"client update to {target} was REFUSED: {exc}")
3123
+ return 1
2939
3124
  except (resolver.ConfigError, updater.UpdateError) as exc:
2940
3125
  print(f"firekeep: {exc}", file=sys.stderr)
2941
3126
  return 1
@@ -3028,6 +3213,22 @@ def _build_parser() -> argparse.ArgumentParser:
3028
3213
  maildex.add_argument("--account", metavar="ID", help="sync one account by id")
3029
3214
  maildex.set_defaults(func=cmd_maildex)
3030
3215
 
3216
+ p_hands = sub.add_parser(
3217
+ "hands", help="desktop operator — enable, disable, status, allow, chord, config, evidence")
3218
+ p_hands.add_argument("action", nargs="?", default="status",
3219
+ choices=["enable", "disable", "status", "allow", "chord", "config", "evidence"])
3220
+ # nargs="*", NOT argparse.REMAINDER: REMAINDER after a positional swallows
3221
+ # `--from X` into `rest` and leaves `source` None — the exact command the
3222
+ # live smoke depends on. With "*" the options still parse wherever they sit.
3223
+ p_hands.add_argument("rest", nargs="*")
3224
+ p_hands.add_argument("--from", dest="source", default=None,
3225
+ help="wheel source for enable: a local checkout dir or a pip spec")
3226
+ p_hands.add_argument("--pypi", action="store_true",
3227
+ help="enable: install the published wheel from PyPI (HANDS_WHEEL_SPEC)")
3228
+ p_hands.add_argument("--no-autostart", action="store_true")
3229
+ p_hands.add_argument("--purge", action="store_true", help="with disable: delete ~/.firekeep/hands")
3230
+ p_hands.set_defaults(func=cmd_hands)
3231
+
3031
3232
  backup = sub.add_parser(
3032
3233
  "backup",
3033
3234
  help="Keep snapshots on the server — status, list, link, pull, guided restore")
@@ -42,7 +42,7 @@ from typing import Any, Callable
42
42
 
43
43
  import anyio
44
44
 
45
- from firekeep_client import hooklog, resolver, transport
45
+ from firekeep_client import background, hooklog, jobobject, resolver, transport
46
46
  from firekeep_client.stdio import force_utf8_stdio, pin_import_paths
47
47
  from firekeep_client.decision.board import BOARD_CSP, BOARD_HTML, render_answers
48
48
 
@@ -559,6 +559,44 @@ def _bypass_notice() -> str:
559
559
  )
560
560
 
561
561
 
562
+ # Runs in a helper interpreter, not here: os.startfile is ShellExecute, which
563
+ # CreateProcess-es the browser as OUR child — and this server is a gateway
564
+ # backend inside the gateway's kill-on-close Job Object (jobobject.py).
565
+ _STARTFILE = "import os, sys; os.startfile(sys.argv[1])"
566
+
567
+
568
+ def _open_browser_outside_job(url: str) -> bool:
569
+ """Windows: start the browser from a helper launched with
570
+ CREATE_BREAKAWAY_FROM_JOB, so it outlives the agent session.
571
+
572
+ A browser cold-started inside the job would die with the gateway — taking
573
+ every window the human later opened in it. The helper is out of the job, so
574
+ the browser it starts is too. The URL rides as an argv element: board URLs
575
+ carry `&`, which `cmd /c start` would read as a command separator. Waits for
576
+ the helper's exit code so "True only when a launch was observed" holds.
577
+ False (hooklogged) sends the caller to plain webbrowser.open — a browser
578
+ inside the job beats no browser. Never raises.
579
+ """
580
+ proc = None
581
+ try:
582
+ # os_name pinned: only reached on win32, and a Linux test run of this
583
+ # branch must exercise the Windows recipe, not the POSIX one.
584
+ kwargs = background.popen_kwargs(os_name="nt") # hidden console, no inherited streams
585
+ proc = jobobject.popen_outside_job([sys.executable, "-c", _STARTFILE, url], **kwargs)
586
+ rc = proc.wait(timeout=10)
587
+ if rc == 0:
588
+ return True
589
+ hooklog.log_failure("decision", f"breakaway browser helper rc={rc} — trying webbrowser")
590
+ except Exception as e: # noqa: BLE001 — fall through to webbrowser
591
+ if proc is not None:
592
+ try:
593
+ proc.kill() # a hung helper must not launch a second browser late
594
+ except Exception: # noqa: BLE001
595
+ pass
596
+ hooklog.log_failure("decision", f"breakaway browser helper raised: {e!r} — trying webbrowser")
597
+ return False
598
+
599
+
562
600
  def _open_browser(url: str) -> bool:
563
601
  """Open the human's browser at ``url``; True only when a launch was observed.
564
602
 
@@ -588,6 +626,8 @@ def _open_browser(url: str) -> bool:
588
626
  hooklog.log_failure(
589
627
  "decision", f"open(1) raised: {e!r} — trying webbrowser",
590
628
  )
629
+ if sys.platform == "win32" and _open_browser_outside_job(url):
630
+ return True
591
631
  ok = bool(webbrowser.open(url))
592
632
  if not ok:
593
633
  hooklog.log_failure(
@@ -56,6 +56,11 @@ class DexManifest:
56
56
  console_script: str
57
57
  import_probe: str
58
58
  description: str
59
+ # "index" (symdex, docdex, maildex) or "capability" (hands). The gateway
60
+ # does not read it — `kind` decides mounting — but `dex list`, doctor and
61
+ # the docs do: a capability OPERATES its domain rather than indexing it,
62
+ # and is never part of the default seed (ensure_migrated).
63
+ role: str = "index"
59
64
 
60
65
 
61
66
  KNOWN_DEXES: dict[str, DexManifest] = {
@@ -98,6 +103,21 @@ KNOWN_DEXES: dict[str, DexManifest] = {
98
103
  "recall. Always private to you: never shared, and it cannot send."
99
104
  ),
100
105
  ),
106
+ "hands": DexManifest(
107
+ id="firekeep.hands",
108
+ name="hands",
109
+ title="Hands",
110
+ indexes="desktop",
111
+ kind="mcp-stdio",
112
+ console_script="firekeep-hands",
113
+ import_probe="firekeep_hands",
114
+ description=(
115
+ "Desktop operator — your runtime observes and operates this "
116
+ "computer's apps and a Hands-managed browser; consequential steps "
117
+ "wait for your chord or phone tap. Opt in with `firekeep hands enable`."
118
+ ),
119
+ role="capability",
120
+ ),
101
121
  }
102
122
 
103
123
 
@@ -191,26 +211,35 @@ def _manifest(name: str) -> DexManifest:
191
211
  return manifest
192
212
 
193
213
 
194
- def _stamp() -> dict:
214
+ def _stamp(source: str = "bundled") -> dict:
195
215
  return {
196
216
  "added_at": datetime.datetime.now(datetime.timezone.utc).strftime(
197
217
  "%Y-%m-%dT%H:%M:%SZ"
198
218
  ),
199
- # `source` is where the CODE came from, not who asked for it. Everything
200
- # milestone 1 registers is a bundled, checksum-verified wheel; the
201
- # dev-mode side-loading rung (ROADMAP §5, SDK ladder rung 3) is what
202
- # will write anything else here, and doctor will mark it loudly.
203
- "source": "bundled",
219
+ # `source` is where the CODE came from, not who asked for it. The three
220
+ # dexes are bundled, checksum-verified wheels and default to that;
221
+ # `hands` is the one entry that never can be — it is installed on
222
+ # demand by `firekeep hands enable`, from a checkout (`--from`) or from
223
+ # PyPI — so it passes its own value rather than inheriting a default
224
+ # that would state, in the user's own registry file, something untrue
225
+ # about where the code on their machine came from.
226
+ "source": str(source),
204
227
  }
205
228
 
206
229
 
207
- def add(name: str) -> DexManifest:
230
+ def add(name: str, *, source: str = "bundled") -> DexManifest:
208
231
  """Register a dex. Idempotent — re-adding keeps the original `added_at`
209
- rather than churning the stamp (and the file's mtime) on every re-run."""
232
+ rather than churning the stamp (and the file's mtime) on every re-run.
233
+
234
+ `source` defaults to `"bundled"`, which is right for every dex: their
235
+ wheels arrive with the release and are checksum-verified by the bootstrap.
236
+ A caller that installed the code itself passes what it actually did —
237
+ `"checkout"` or `"pypi"` — because this field is provenance, and a
238
+ provenance field that is a constant records nothing."""
210
239
  manifest = _manifest(name)
211
240
  entries = read_registry()
212
241
  if name not in entries:
213
- entries[name] = _stamp()
242
+ entries[name] = _stamp(source)
214
243
  write_registry(entries)
215
244
  return manifest
216
245
 
@@ -252,6 +281,10 @@ def ensure_migrated(*, installing: bool = False) -> None:
252
281
  indexes nothing, so registering it here would buy a doctor row and no mail;
253
282
  `firekeep maildex add` registers it at the moment it becomes real.
254
283
 
284
+ hands is likewise never seeded: a capability that can move the mouse is
285
+ opt-in by `firekeep hands enable`, which installs the wheel and registers
286
+ it in one step.
287
+
255
288
  Called from `cmd_install` (installing=True) and from gateway startup, which
256
289
  is what covers an update that never re-ran install. `installing` does not
257
290
  change the rule — it names the caller in the failure log, so a support log