open-multi-agent-kit 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Changelog
 
-## [Unreleased]
+## [1.2.0] - 2026-09-20
+
+### Added
+
+- Parallel-session coordination kernel (`coordination/`): an admission broker that keeps a possibly-live effect's resource claims held until a trusted supervisor confirms termination — expiry, cancellation and authority restart are authorization events, not termination proofs — plus prefix-based claim conflict algebra, a publisher that admits a candidate only when its read versions, parent revision and receipt binding all still match, generation-tagged session lifecycle that discards a late init from a superseded generation and retains the handle when close fails, an operation lifecycle whose dispatch consumes a recorded observation rather than a re-interpreted instruction and re-evaluates the permit at the dispatch boundary, and conservative change-invalidation and frontier admission helpers.
+- Metacognition evidence primitives: finite-sample Clopper–Pearson risk bounds for automation gating (a point estimate never widens scope; zero trials is absent evidence, not zero risk), probability calibration with temperature scaling, Brier/log-loss/ECE reported with bin occupancy, a selective-execution gate that reports coverage beside risk and leaves risk undefined when nothing was admitted, observation validity that separates time decay from the change indicator and lets explicit age and generation bounds override the decay score, state packing that returns `incomplete-state` instead of silently dropping required evidence, cost- and latency-aware route selection with safety as a hard filter outside the utility, and three-valued verification where `unknown` is never negated into `true` and evidence level is labelled by the strongest witness actually held.
 
 ## [1.0.0] - 2026-09-18
 

package/README.md

@@ -47,7 +47,7 @@ OMK stores user configuration under `~/.omk/agent/` and project configuration un
 Install `omk-book-to-skill` to compile documents into reusable skills without adding Python extractors to OMK core:
 
 ```bash
-omk install npm:omk-book-to-skill@1.0.0
+omk install npm:omk-book-to-skill@1.2.0
 ```
 
 It provides compile, update, and verification commands plus a local SHA-256 provenance manifest. See [Book to Skill](https://github.com/dmae97/omk/blob/main/packages/coding-agent/docs/book-to-skill.md).
@@ -258,7 +258,7 @@ npm test
 
 See [Development](https://github.com/dmae97/omk/blob/main/packages/coding-agent/docs/development.md) and [CONTRIBUTING.md](https://github.com/dmae97/omk/blob/main/CONTRIBUTING.md).
 
-Release notes: [v1.0.0](https://github.com/dmae97/omk/blob/main/.github/RELEASE_NOTES_v1.0.0.md).
+Release notes: [v1.2.0](https://github.com/dmae97/omk/blob/main/.github/RELEASE_NOTES_v1.2.0.md).
 
 ## License
 

package/dist/cli/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,wBAAgB,SAAS,CAAC,cAAc,CAAC,EAAE,aAAa,EAAE,GAAG,IAAI,CAkMhE","sourcesContent":["import chalk from \"chalk\";\nimport { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR, ENV_SESSION_DIR } from \"../config.ts\";\nimport type { ExtensionFlag } from \"../core/extensions/types.ts\";\n\nexport function printHelp(extensionFlags?: ExtensionFlag[]): void {\n\tlet extensionFlagsText = \"\";\n\tif (extensionFlags && extensionFlags.length > 0) {\n\t\textensionFlagsText = `\\n${chalk.bold(\"Extension CLI Flags:\")}\\n${extensionFlags\n\t\t\t.map((flag) => {\n\t\t\t\tconst value = flag.type === \"string\" ? \" <value>\" : \"\";\n\t\t\t\tconst description = flag.description ?? `Registered by ${flag.extensionPath}`;\n\t\t\t\treturn `  --${flag.name}${value}`.padEnd(30) + description;\n\t\t\t})\n\t\t\t.join(\"\\n\")}\\n`;\n\t}\n\t// CLI help is intentional stdout, not application debug logging.\n\t// pi-lens-ignore: no-console-except-error\n\tconsole.log(`${chalk.bold(APP_NAME)} - AI coding assistant with read, bash, edit, write tools\n\n${chalk.bold(\"Usage:\")}\n  ${APP_NAME} [options] [@files...] [messages...]\n\n${chalk.bold(\"Commands:\")}\n  ${APP_NAME} init --global [--dry-run] Create missing user context documents without overwriting settings\n  ${APP_NAME} install <source> [-l]     Install extension source and add to settings\n  ${APP_NAME} remove <source> [-l]      Remove extension source from settings\n  ${APP_NAME} uninstall <source> [-l]   Alias for remove\n  ${APP_NAME} update [source|self|omk]  Update OMK and installed extensions\n  ${APP_NAME} list                      List installed extensions from settings\n  ${APP_NAME} package doctor <source>   Diagnose omk/pi manifest and runtime compatibility as JSON\n  ${APP_NAME} config                    Open TUI to enable/disable package resources\n  ${APP_NAME} quota                     Manage CodexBar quota connector and summaries\n  ${APP_NAME} provider doctor <id>      Diagnose a provider as sanitized JSON (--probe-model adds an\n                                 opt-in Level-2 generative probe that may incur provider costs)\n  ${APP_NAME} session doctor            Inspect or safely repair one session (--session, --repair, --dry-run)\n  ${APP_NAME} doctor resources [--json] [--report] Inspect current pressure or aggregate local observations\n  ${APP_NAME} doctor adaptorch [--json]  Verify ADAPTORCH_API_KEY reaches the AdaptOrch API (0 ok, 1 unset, 2 failed)\n  ${APP_NAME} router-feedback compile-bias  Compile this repository's bounded router bias snapshot\n  ${APP_NAME} <command> --help          Show help for install/remove/uninstall/update/list\n\n${chalk.bold(\"Options:\")}\n  --provider <name>              Provider name (default: google)\n  --model <pattern>              Model pattern or ID (supports \"provider/id\" and optional \":<thinking>\")\n  --model-contract <file>        Pin an optional JSON model/effort/output dispatch policy\n  --api-key <key>                API key (defaults to env vars)\n  --system-prompt <text>         System prompt (default: coding assistant prompt)\n  --append-system-prompt <text>  Append text or file contents to the system prompt (can be used multiple times)\n  --mode <mode>                  Output mode: text (default), json, rpc, or acp (conversation-only)\n  --print, -p                    Non-interactive mode: process prompt and exit\n  --continue, -c                 Continue previous session\n  --resume, -r                   Select a session to resume\n  --session <path|id>            Use specific session file or partial UUID\n  --session-id <id>              Use exact project session ID, creating it if missing\n  --fork <path|id>               Fork specific session file or partial UUID into a new session\n  --session-dir <dir>            Directory for session storage and lookup\n  --no-session                   Don't save session (ephemeral)\n  --name, -n <name>              Set session display name\n  --models <patterns>            Comma-separated model patterns for Ctrl+P cycling\n                                 Supports globs (anthropic/*, *sonnet*) and fuzzy matching\n  --no-tools, -nt                Disable all tools by default (built-in and extension)\n  --no-builtin-tools, -nbt       Disable built-in tools by default but keep extension/custom tools enabled\n  --tools, -t <tools>            Comma-separated allowlist of tool names to enable\n                                 Applies to built-in, extension, and custom tools\n  --exclude-tools, -xt <tools>   Comma-separated denylist of tool names to disable\n                                 Applies to built-in, extension, and custom tools\n  --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh, max, ultra\n  --extension, -e <path>         Load an extension file (can be used multiple times)\n  --no-extensions, -ne           Disable extension discovery (explicit -e paths still work)\n  --skill <path>                 Load a skill file or directory (can be used multiple times)\n  --no-skills, -ns               Disable skills discovery and loading\n  --prompt-template <path>       Load a prompt template file or directory (can be used multiple times)\n  --no-prompt-templates, -np     Disable prompt template discovery and loading\n  --theme <path>                 Load a theme file or directory (can be used multiple times)\n  --no-themes                    Disable theme discovery and loading\n  --no-context-files, -nc        Disable AGENTS.md and CLAUDE.md discovery and loading\n  --export <file>                Export session file to HTML and exit\n  --list-models [search]         List available models (with optional fuzzy search)\n  --verbose                      Force verbose startup (overrides quietStartup setting)\n  --offline                      Disable startup network operations (same as OMK_OFFLINE=1)\n  --help, -h                     Show this help\n  --version, -v                  Show version number\n\nExtensions can register additional flags (e.g., --plan from plan-mode extension).${extensionFlagsText}\n\n${chalk.bold(\"Examples:\")}\n  # Interactive mode\n  ${APP_NAME}\n\n  # Interactive mode with initial prompt\n  ${APP_NAME} \"List all .ts files in src/\"\n\n  # Include files in initial message\n  ${APP_NAME} @prompt.md @image.png \"What color is the sky?\"\n\n  # Non-interactive mode (process and exit)\n  ${APP_NAME} -p \"List all .ts files in src/\"\n\n  # Multiple messages (interactive)\n  ${APP_NAME} \"Read package.json\" \"What dependencies do we have?\"\n\n  # Continue previous session\n  ${APP_NAME} --continue \"What did we discuss?\"\n\n  # Start a named session\n  ${APP_NAME} --name \"Refactor auth module\"\n\n  # Use different model\n  ${APP_NAME} --provider openai --model gpt-4o-mini \"Help me refactor this code\"\n\n  # Use model with provider prefix (no --provider needed)\n  ${APP_NAME} --model openai/gpt-4o \"Help me refactor this code\"\n\n  # Use model with thinking level shorthand\n  ${APP_NAME} --model sonnet:high \"Solve this complex problem\"\n\n  # Limit model cycling to specific models\n  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o\n\n  # Limit to a specific provider with glob pattern\n  ${APP_NAME} --models \"github-copilot/*\"\n\n  # Cycle models with fixed thinking levels\n  ${APP_NAME} --models sonnet:high,haiku:low\n\n  # Start with a specific thinking level\n  ${APP_NAME} --thinking high \"Solve this complex problem\"\n\n  # Read-only mode (no file modifications possible)\n  ${APP_NAME} --tools read,grep,find,ls -p \"Review the code in src/\"\n\n  # Disable one tool while keeping the rest available\n  ${APP_NAME} --exclude-tools ask_question\n\n  # Export a session file to HTML\n  ${APP_NAME} --export ~/${CONFIG_DIR_NAME}/agent/sessions/--path--/session.jsonl\n  ${APP_NAME} --export session.jsonl output.html\n\n${chalk.bold(\"Environment Variables:\")}\n  ANTHROPIC_API_KEY                - Anthropic Claude API key\n  ANTHROPIC_OAUTH_TOKEN            - Anthropic OAuth token (alternative to API key)\n  ANT_LING_API_KEY                 - Ant Ling API key\n  OPENAI_API_KEY                   - OpenAI GPT API key\n  AZURE_OPENAI_API_KEY             - Azure OpenAI API key\n  AZURE_OPENAI_BASE_URL            - Azure OpenAI/Cognitive Services base URL (e.g. https://{resource}.openai.azure.com)\n  AZURE_OPENAI_RESOURCE_NAME       - Azure OpenAI resource name (alternative to base URL)\n  AZURE_OPENAI_API_VERSION         - Azure OpenAI API version (default: v1)\n  AZURE_OPENAI_DEPLOYMENT_NAME_MAP - Azure OpenAI model=deployment map (comma-separated)\n  DEEPSEEK_API_KEY                 - DeepSeek API key\n  DEVIN_API_KEY                    - Devin CLI subscription session token (or /login devin)\n  NVIDIA_API_KEY                   - NVIDIA NIM API key\n  GEMINI_API_KEY                   - Google Gemini API key\n  GROQ_API_KEY                     - Groq API key\n  CEREBRAS_API_KEY                 - Cerebras API key\n  XAI_API_KEY                      - xAI Grok API key\n  FIREWORKS_API_KEY                - Fireworks API key\n  TOGETHER_API_KEY                 - Together AI API key\n  OPENROUTER_API_KEY               - OpenRouter API key\n  AI_GATEWAY_API_KEY               - Vercel AI Gateway API key\n  ZAI_API_KEY                      - ZAI API key\n  ZAI_CODING_CN_API_KEY            - ZAI Coding Plan API key (China)\n  MISTRAL_API_KEY                  - Mistral API key\n  MINIMAX_API_KEY                  - MiniMax API key\n  MOONSHOT_API_KEY                 - Moonshot AI API key\n  META_API_KEY                     - Meta Model API key (Muse Spark); META_MODEL_API_KEY/MODEL_API_KEY also read\n  OPENCODE_API_KEY                 - OpenCode Zen/OpenCode Go API key\n  KIMI_API_KEY                     - Kimi For Coding API key\n  CLOUDFLARE_API_KEY               - Cloudflare API token (Workers AI and AI Gateway)\n  CLOUDFLARE_ACCOUNT_ID            - Cloudflare account id (required for both)\n  CLOUDFLARE_GATEWAY_ID            - Cloudflare AI Gateway slug (required for AI Gateway)\n  XIAOMI_API_KEY                   - Xiaomi MiMo API key (api.xiaomimimo.com billing)\n  XIAOMI_TOKEN_PLAN_CN_API_KEY     - Xiaomi MiMo Token Plan API key (China region)\n  XIAOMI_TOKEN_PLAN_AMS_API_KEY    - Xiaomi MiMo Token Plan API key (Amsterdam region)\n  XIAOMI_TOKEN_PLAN_SGP_API_KEY    - Xiaomi MiMo Token Plan API key (Singapore region)\n  ZYLOO_API_KEY                    - Zyloo API key\n  AWS_PROFILE                      - AWS profile for Amazon Bedrock\n  AWS_ACCESS_KEY_ID                - AWS access key for Amazon Bedrock\n  AWS_SECRET_ACCESS_KEY            - AWS secret key for Amazon Bedrock\n  AWS_BEARER_TOKEN_BEDROCK         - Bedrock API key (bearer token)\n  AWS_REGION                       - AWS region for Amazon Bedrock (e.g., us-east-1)\n  ${ENV_AGENT_DIR.padEnd(32)} - Config directory (default: ~/${CONFIG_DIR_NAME}/agent)\n  ${ENV_SESSION_DIR.padEnd(32)} - Session storage directory (overridden by --session-dir)\n  OMK_PACKAGE_DIR                  - Override package directory (for Nix/Guix store paths)\n  OMK_TOOL_SCHEDULER               - Tool scheduler override: dag-v2 or waves-v1 rollback\n  OMK_OFFLINE                      - Disable startup network operations when set to 1/true/yes\n  OMK_TELEMETRY                    - Override install telemetry when set to 1/true/yes or 0/false/no\n  OMK_SHARE_VIEWER_URL             - Base URL for /share command (default: https://omk.dev/session/)\n  ADAPTORCH_API_KEY                - AdaptOrch API key (optional; enables the doctor adaptorch check)\n  ADAPTORCH_API_URL                - AdaptOrch API base URL (default: https://api.adaptorch.com)\n\n${chalk.bold(\"Built-in Tool Names:\")}\n  read   - Read file contents\n  bash   - Execute bash commands\n  edit   - Edit files with find/replace\n  write  - Write files (creates/overwrites)\n  grep   - Search file contents (read-only, off by default)\n  find   - Find files by glob pattern (read-only, off by default)\n  ls     - List directory contents (read-only, off by default)\n`);\n}\n"]}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,wBAAgB,SAAS,CAAC,cAAc,CAAC,EAAE,aAAa,EAAE,GAAG,IAAI,CAmMhE","sourcesContent":["import chalk from \"chalk\";\nimport { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR, ENV_SESSION_DIR } from \"../config.ts\";\nimport type { ExtensionFlag } from \"../core/extensions/types.ts\";\n\nexport function printHelp(extensionFlags?: ExtensionFlag[]): void {\n\tlet extensionFlagsText = \"\";\n\tif (extensionFlags && extensionFlags.length > 0) {\n\t\textensionFlagsText = `\\n${chalk.bold(\"Extension CLI Flags:\")}\\n${extensionFlags\n\t\t\t.map((flag) => {\n\t\t\t\tconst value = flag.type === \"string\" ? \" <value>\" : \"\";\n\t\t\t\tconst description = flag.description ?? `Registered by ${flag.extensionPath}`;\n\t\t\t\treturn `  --${flag.name}${value}`.padEnd(30) + description;\n\t\t\t})\n\t\t\t.join(\"\\n\")}\\n`;\n\t}\n\t// CLI help is intentional stdout, not application debug logging.\n\t// pi-lens-ignore: no-console-except-error\n\tconsole.log(`${chalk.bold(APP_NAME)} - AI coding assistant with read, bash, edit, write tools\n\n${chalk.bold(\"Usage:\")}\n  ${APP_NAME} [options] [@files...] [messages...]\n\n${chalk.bold(\"Commands:\")}\n  ${APP_NAME} init --global [--dry-run] Create missing user context documents without overwriting settings\n  ${APP_NAME} install <source> [-l]     Install extension source and add to settings\n  ${APP_NAME} remove <source> [-l]      Remove extension source from settings\n  ${APP_NAME} uninstall <source> [-l]   Alias for remove\n  ${APP_NAME} update [source|self|omk]  Update OMK and installed extensions\n  ${APP_NAME} list                      List installed extensions from settings\n  ${APP_NAME} package doctor <source>   Diagnose omk/pi manifest and runtime compatibility as JSON\n  ${APP_NAME} config                    Open TUI to enable/disable package resources\n  ${APP_NAME} quota                     Manage CodexBar quota connector and summaries\n  ${APP_NAME} provider doctor <id>      Diagnose a provider as sanitized JSON (--probe-model adds an\n                                 opt-in Level-2 generative probe that may incur provider costs)\n  ${APP_NAME} session doctor            Inspect or safely repair one session (--session, --repair, --dry-run)\n  ${APP_NAME} doctor resources [--json] [--report] Inspect current pressure or aggregate local observations\n  ${APP_NAME} doctor adaptorch [--json]  Verify ADAPTORCH_API_KEY reaches the AdaptOrch API (0 ok, 1 unset, 2 failed)\n  ${APP_NAME} router-feedback compile-bias  Compile this repository's bounded router bias snapshot\n  ${APP_NAME} <command> --help          Show help for install/remove/uninstall/update/list\n\n${chalk.bold(\"Options:\")}\n  --provider <name>              Provider name (default: google)\n  --model <pattern>              Model pattern or ID (supports \"provider/id\" and optional \":<thinking>\")\n  --model-contract <file>        Pin an optional JSON model/effort/output dispatch policy\n  --api-key <key>                API key (defaults to env vars)\n  --system-prompt <text>         System prompt (default: coding assistant prompt)\n  --append-system-prompt <text>  Append text or file contents to the system prompt (can be used multiple times)\n  --mode <mode>                  Output mode: text (default), json, rpc, or acp (conversation-only)\n  --print, -p                    Non-interactive mode: process prompt and exit\n  --continue, -c                 Continue previous session\n  --resume, -r                   Select a session to resume\n  --session <path|id>            Use specific session file or partial UUID\n  --session-id <id>              Use exact project session ID, creating it if missing\n  --fork <path|id>               Fork specific session file or partial UUID into a new session\n  --session-dir <dir>            Directory for session storage and lookup\n  --no-session                   Don't save session (ephemeral)\n  --name, -n <name>              Set session display name\n  --models <patterns>            Comma-separated model patterns for Ctrl+P cycling\n                                 Supports globs (anthropic/*, *sonnet*) and fuzzy matching\n  --no-tools, -nt                Disable all tools by default (built-in and extension)\n  --no-builtin-tools, -nbt       Disable built-in tools by default but keep extension/custom tools enabled\n  --tools, -t <tools>            Comma-separated allowlist of tool names to enable\n                                 Applies to built-in, extension, and custom tools\n  --exclude-tools, -xt <tools>   Comma-separated denylist of tool names to disable\n                                 Applies to built-in, extension, and custom tools\n  --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh, max, ultra\n  --extension, -e <path>         Load an extension file (can be used multiple times)\n  --no-extensions, -ne           Disable extension discovery (explicit -e paths still work)\n  --skill <path>                 Load a skill file or directory (can be used multiple times)\n  --no-skills, -ns               Disable skills discovery and loading\n  --prompt-template <path>       Load a prompt template file or directory (can be used multiple times)\n  --no-prompt-templates, -np     Disable prompt template discovery and loading\n  --theme <path>                 Load a theme file or directory (can be used multiple times)\n  --no-themes                    Disable theme discovery and loading\n  --no-context-files, -nc        Disable AGENTS.md and CLAUDE.md discovery and loading\n  --export <file>                Export session file to HTML and exit\n  --list-models [search]         List available models (with optional fuzzy search)\n  --verbose                      Force verbose startup (overrides quietStartup setting)\n  --offline                      Disable startup network operations (same as OMK_OFFLINE=1)\n  --help, -h                     Show this help\n  --version, -v                  Show version number\n\nExtensions can register additional flags (e.g., --plan from plan-mode extension).${extensionFlagsText}\n\n${chalk.bold(\"Examples:\")}\n  # Interactive mode\n  ${APP_NAME}\n\n  # Interactive mode with initial prompt\n  ${APP_NAME} \"List all .ts files in src/\"\n\n  # Include files in initial message\n  ${APP_NAME} @prompt.md @image.png \"What color is the sky?\"\n\n  # Non-interactive mode (process and exit)\n  ${APP_NAME} -p \"List all .ts files in src/\"\n\n  # Multiple messages (interactive)\n  ${APP_NAME} \"Read package.json\" \"What dependencies do we have?\"\n\n  # Continue previous session\n  ${APP_NAME} --continue \"What did we discuss?\"\n\n  # Start a named session\n  ${APP_NAME} --name \"Refactor auth module\"\n\n  # Use different model\n  ${APP_NAME} --provider openai --model gpt-4o-mini \"Help me refactor this code\"\n\n  # Use model with provider prefix (no --provider needed)\n  ${APP_NAME} --model openai/gpt-4o \"Help me refactor this code\"\n\n  # Use model with thinking level shorthand\n  ${APP_NAME} --model sonnet:high \"Solve this complex problem\"\n\n  # Limit model cycling to specific models\n  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o\n\n  # Limit to a specific provider with glob pattern\n  ${APP_NAME} --models \"github-copilot/*\"\n\n  # Cycle models with fixed thinking levels\n  ${APP_NAME} --models sonnet:high,haiku:low\n\n  # Start with a specific thinking level\n  ${APP_NAME} --thinking high \"Solve this complex problem\"\n\n  # Read-only mode (no file modifications possible)\n  ${APP_NAME} --tools read,grep,find,ls -p \"Review the code in src/\"\n\n  # Disable one tool while keeping the rest available\n  ${APP_NAME} --exclude-tools ask_question\n\n  # Export a session file to HTML\n  ${APP_NAME} --export ~/${CONFIG_DIR_NAME}/agent/sessions/--path--/session.jsonl\n  ${APP_NAME} --export session.jsonl output.html\n\n${chalk.bold(\"Environment Variables:\")}\n  ANTHROPIC_API_KEY                - Anthropic Claude API key\n  ANTHROPIC_OAUTH_TOKEN            - Anthropic OAuth token (alternative to API key)\n  ANT_LING_API_KEY                 - Ant Ling API key\n  OPENAI_API_KEY                   - OpenAI GPT API key\n  AZURE_OPENAI_API_KEY             - Azure OpenAI API key\n  AZURE_OPENAI_BASE_URL            - Azure OpenAI/Cognitive Services base URL (e.g. https://{resource}.openai.azure.com)\n  AZURE_OPENAI_RESOURCE_NAME       - Azure OpenAI resource name (alternative to base URL)\n  AZURE_OPENAI_API_VERSION         - Azure OpenAI API version (default: v1)\n  AZURE_OPENAI_DEPLOYMENT_NAME_MAP - Azure OpenAI model=deployment map (comma-separated)\n  DEEPSEEK_API_KEY                 - DeepSeek API key\n  DEVIN_API_KEY                    - Devin CLI subscription session token (or /login devin)\n  NVIDIA_API_KEY                   - NVIDIA NIM API key\n  GEMINI_API_KEY                   - Google Gemini API key\n  GROQ_API_KEY                     - Groq API key\n  CEREBRAS_API_KEY                 - Cerebras API key\n  XAI_API_KEY                      - xAI Grok API key\n  FIREWORKS_API_KEY                - Fireworks API key\n  TOGETHER_API_KEY                 - Together AI API key\n  OPENROUTER_API_KEY               - OpenRouter API key\n  AI_GATEWAY_API_KEY               - Vercel AI Gateway API key\n  ZAI_API_KEY                      - ZAI API key\n  ZAI_CODING_CN_API_KEY            - ZAI Coding Plan API key (China)\n  MISTRAL_API_KEY                  - Mistral API key\n  MINIMAX_API_KEY                  - MiniMax API key\n  MOONSHOT_API_KEY                 - Moonshot AI API key\n  META_API_KEY                     - Meta Model API key (Muse Spark); META_MODEL_API_KEY/MODEL_API_KEY also read\n  OPENCODE_API_KEY                 - OpenCode Zen/OpenCode Go API key\n  KIMI_API_KEY                     - Kimi For Coding API key\n  WORKBUDDY_API_KEY                - WorkBuddy (Tencent CodeBuddy) plan key\n  CLOUDFLARE_API_KEY               - Cloudflare API token (Workers AI and AI Gateway)\n  CLOUDFLARE_ACCOUNT_ID            - Cloudflare account id (required for both)\n  CLOUDFLARE_GATEWAY_ID            - Cloudflare AI Gateway slug (required for AI Gateway)\n  XIAOMI_API_KEY                   - Xiaomi MiMo API key (api.xiaomimimo.com billing)\n  XIAOMI_TOKEN_PLAN_CN_API_KEY     - Xiaomi MiMo Token Plan API key (China region)\n  XIAOMI_TOKEN_PLAN_AMS_API_KEY    - Xiaomi MiMo Token Plan API key (Amsterdam region)\n  XIAOMI_TOKEN_PLAN_SGP_API_KEY    - Xiaomi MiMo Token Plan API key (Singapore region)\n  ZYLOO_API_KEY                    - Zyloo API key\n  AWS_PROFILE                      - AWS profile for Amazon Bedrock\n  AWS_ACCESS_KEY_ID                - AWS access key for Amazon Bedrock\n  AWS_SECRET_ACCESS_KEY            - AWS secret key for Amazon Bedrock\n  AWS_BEARER_TOKEN_BEDROCK         - Bedrock API key (bearer token)\n  AWS_REGION                       - AWS region for Amazon Bedrock (e.g., us-east-1)\n  ${ENV_AGENT_DIR.padEnd(32)} - Config directory (default: ~/${CONFIG_DIR_NAME}/agent)\n  ${ENV_SESSION_DIR.padEnd(32)} - Session storage directory (overridden by --session-dir)\n  OMK_PACKAGE_DIR                  - Override package directory (for Nix/Guix store paths)\n  OMK_TOOL_SCHEDULER               - Tool scheduler override: dag-v2 or waves-v1 rollback\n  OMK_OFFLINE                      - Disable startup network operations when set to 1/true/yes\n  OMK_TELEMETRY                    - Override install telemetry when set to 1/true/yes or 0/false/no\n  OMK_SHARE_VIEWER_URL             - Base URL for /share command (default: https://omk.dev/session/)\n  ADAPTORCH_API_KEY                - AdaptOrch API key (optional; enables the doctor adaptorch check)\n  ADAPTORCH_API_URL                - AdaptOrch API base URL (default: https://api.adaptorch.com)\n\n${chalk.bold(\"Built-in Tool Names:\")}\n  read   - Read file contents\n  bash   - Execute bash commands\n  edit   - Edit files with find/replace\n  write  - Write files (creates/overwrites)\n  grep   - Search file contents (read-only, off by default)\n  find   - Find files by glob pattern (read-only, off by default)\n  ls     - List directory contents (read-only, off by default)\n`);\n}\n"]}

package/dist/cli/help.js

@@ -162,6 +162,7 @@ ${chalk.bold("Environment Variables:")}
   META_API_KEY                     - Meta Model API key (Muse Spark); META_MODEL_API_KEY/MODEL_API_KEY also read
   OPENCODE_API_KEY                 - OpenCode Zen/OpenCode Go API key
   KIMI_API_KEY                     - Kimi For Coding API key
+  WORKBUDDY_API_KEY                - WorkBuddy (Tencent CodeBuddy) plan key
   CLOUDFLARE_API_KEY               - Cloudflare API token (Workers AI and AI Gateway)
   CLOUDFLARE_ACCOUNT_ID            - Cloudflare account id (required for both)
   CLOUDFLARE_GATEWAY_ID            - Cloudflare AI Gateway slug (required for AI Gateway)

package/dist/cli/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGzF,MAAM,UAAU,SAAS,CAAC,cAAgC,EAAQ;IACjE,IAAI,kBAAkB,GAAG,EAAE,CAAC;IAC5B,IAAI,cAAc,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjD,kBAAkB,GAAG,KAAK,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,KAAK,cAAc;aAC7E,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACd,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,iBAAiB,IAAI,CAAC,aAAa,EAAE,CAAC;YAC9E,OAAO,OAAO,IAAI,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC;QAAA,CAC3D,CAAC;aACD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IAClB,CAAC;IACD,iEAAiE;IACjE,0CAA0C;IAC1C,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;;EAElC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;IAClB,QAAQ;;EAEV,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC;IACrB,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;;IAER,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;;EAEV,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mFA0C2D,kBAAkB;;EAEnG,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC;;IAErB,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ,eAAe,eAAe;IACtC,QAAQ;;EAEV,KAAK,CAAC,IAAI,CAAC,wBAAwB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA0ClC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC,mCAAmC,eAAe;IAC1E,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;;;;;;;;;EAS5B,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC;;;;;;;;CAQnC,CAAC,CAAC;AAAA,CACF","sourcesContent":["import chalk from \"chalk\";\nimport { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR, ENV_SESSION_DIR } from \"../config.ts\";\nimport type { ExtensionFlag } from \"../core/extensions/types.ts\";\n\nexport function printHelp(extensionFlags?: ExtensionFlag[]): void {\n\tlet extensionFlagsText = \"\";\n\tif (extensionFlags && extensionFlags.length > 0) {\n\t\textensionFlagsText = `\\n${chalk.bold(\"Extension CLI Flags:\")}\\n${extensionFlags\n\t\t\t.map((flag) => {\n\t\t\t\tconst value = flag.type === \"string\" ? \" <value>\" : \"\";\n\t\t\t\tconst description = flag.description ?? `Registered by ${flag.extensionPath}`;\n\t\t\t\treturn `  --${flag.name}${value}`.padEnd(30) + description;\n\t\t\t})\n\t\t\t.join(\"\\n\")}\\n`;\n\t}\n\t// CLI help is intentional stdout, not application debug logging.\n\t// pi-lens-ignore: no-console-except-error\n\tconsole.log(`${chalk.bold(APP_NAME)} - AI coding assistant with read, bash, edit, write tools\n\n${chalk.bold(\"Usage:\")}\n  ${APP_NAME} [options] [@files...] [messages...]\n\n${chalk.bold(\"Commands:\")}\n  ${APP_NAME} init --global [--dry-run] Create missing user context documents without overwriting settings\n  ${APP_NAME} install <source> [-l]     Install extension source and add to settings\n  ${APP_NAME} remove <source> [-l]      Remove extension source from settings\n  ${APP_NAME} uninstall <source> [-l]   Alias for remove\n  ${APP_NAME} update [source|self|omk]  Update OMK and installed extensions\n  ${APP_NAME} list                      List installed extensions from settings\n  ${APP_NAME} package doctor <source>   Diagnose omk/pi manifest and runtime compatibility as JSON\n  ${APP_NAME} config                    Open TUI to enable/disable package resources\n  ${APP_NAME} quota                     Manage CodexBar quota connector and summaries\n  ${APP_NAME} provider doctor <id>      Diagnose a provider as sanitized JSON (--probe-model adds an\n                                 opt-in Level-2 generative probe that may incur provider costs)\n  ${APP_NAME} session doctor            Inspect or safely repair one session (--session, --repair, --dry-run)\n  ${APP_NAME} doctor resources [--json] [--report] Inspect current pressure or aggregate local observations\n  ${APP_NAME} doctor adaptorch [--json]  Verify ADAPTORCH_API_KEY reaches the AdaptOrch API (0 ok, 1 unset, 2 failed)\n  ${APP_NAME} router-feedback compile-bias  Compile this repository's bounded router bias snapshot\n  ${APP_NAME} <command> --help          Show help for install/remove/uninstall/update/list\n\n${chalk.bold(\"Options:\")}\n  --provider <name>              Provider name (default: google)\n  --model <pattern>              Model pattern or ID (supports \"provider/id\" and optional \":<thinking>\")\n  --model-contract <file>        Pin an optional JSON model/effort/output dispatch policy\n  --api-key <key>                API key (defaults to env vars)\n  --system-prompt <text>         System prompt (default: coding assistant prompt)\n  --append-system-prompt <text>  Append text or file contents to the system prompt (can be used multiple times)\n  --mode <mode>                  Output mode: text (default), json, rpc, or acp (conversation-only)\n  --print, -p                    Non-interactive mode: process prompt and exit\n  --continue, -c                 Continue previous session\n  --resume, -r                   Select a session to resume\n  --session <path|id>            Use specific session file or partial UUID\n  --session-id <id>              Use exact project session ID, creating it if missing\n  --fork <path|id>               Fork specific session file or partial UUID into a new session\n  --session-dir <dir>            Directory for session storage and lookup\n  --no-session                   Don't save session (ephemeral)\n  --name, -n <name>              Set session display name\n  --models <patterns>            Comma-separated model patterns for Ctrl+P cycling\n                                 Supports globs (anthropic/*, *sonnet*) and fuzzy matching\n  --no-tools, -nt                Disable all tools by default (built-in and extension)\n  --no-builtin-tools, -nbt       Disable built-in tools by default but keep extension/custom tools enabled\n  --tools, -t <tools>            Comma-separated allowlist of tool names to enable\n                                 Applies to built-in, extension, and custom tools\n  --exclude-tools, -xt <tools>   Comma-separated denylist of tool names to disable\n                                 Applies to built-in, extension, and custom tools\n  --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh, max, ultra\n  --extension, -e <path>         Load an extension file (can be used multiple times)\n  --no-extensions, -ne           Disable extension discovery (explicit -e paths still work)\n  --skill <path>                 Load a skill file or directory (can be used multiple times)\n  --no-skills, -ns               Disable skills discovery and loading\n  --prompt-template <path>       Load a prompt template file or directory (can be used multiple times)\n  --no-prompt-templates, -np     Disable prompt template discovery and loading\n  --theme <path>                 Load a theme file or directory (can be used multiple times)\n  --no-themes                    Disable theme discovery and loading\n  --no-context-files, -nc        Disable AGENTS.md and CLAUDE.md discovery and loading\n  --export <file>                Export session file to HTML and exit\n  --list-models [search]         List available models (with optional fuzzy search)\n  --verbose                      Force verbose startup (overrides quietStartup setting)\n  --offline                      Disable startup network operations (same as OMK_OFFLINE=1)\n  --help, -h                     Show this help\n  --version, -v                  Show version number\n\nExtensions can register additional flags (e.g., --plan from plan-mode extension).${extensionFlagsText}\n\n${chalk.bold(\"Examples:\")}\n  # Interactive mode\n  ${APP_NAME}\n\n  # Interactive mode with initial prompt\n  ${APP_NAME} \"List all .ts files in src/\"\n\n  # Include files in initial message\n  ${APP_NAME} @prompt.md @image.png \"What color is the sky?\"\n\n  # Non-interactive mode (process and exit)\n  ${APP_NAME} -p \"List all .ts files in src/\"\n\n  # Multiple messages (interactive)\n  ${APP_NAME} \"Read package.json\" \"What dependencies do we have?\"\n\n  # Continue previous session\n  ${APP_NAME} --continue \"What did we discuss?\"\n\n  # Start a named session\n  ${APP_NAME} --name \"Refactor auth module\"\n\n  # Use different model\n  ${APP_NAME} --provider openai --model gpt-4o-mini \"Help me refactor this code\"\n\n  # Use model with provider prefix (no --provider needed)\n  ${APP_NAME} --model openai/gpt-4o \"Help me refactor this code\"\n\n  # Use model with thinking level shorthand\n  ${APP_NAME} --model sonnet:high \"Solve this complex problem\"\n\n  # Limit model cycling to specific models\n  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o\n\n  # Limit to a specific provider with glob pattern\n  ${APP_NAME} --models \"github-copilot/*\"\n\n  # Cycle models with fixed thinking levels\n  ${APP_NAME} --models sonnet:high,haiku:low\n\n  # Start with a specific thinking level\n  ${APP_NAME} --thinking high \"Solve this complex problem\"\n\n  # Read-only mode (no file modifications possible)\n  ${APP_NAME} --tools read,grep,find,ls -p \"Review the code in src/\"\n\n  # Disable one tool while keeping the rest available\n  ${APP_NAME} --exclude-tools ask_question\n\n  # Export a session file to HTML\n  ${APP_NAME} --export ~/${CONFIG_DIR_NAME}/agent/sessions/--path--/session.jsonl\n  ${APP_NAME} --export session.jsonl output.html\n\n${chalk.bold(\"Environment Variables:\")}\n  ANTHROPIC_API_KEY                - Anthropic Claude API key\n  ANTHROPIC_OAUTH_TOKEN            - Anthropic OAuth token (alternative to API key)\n  ANT_LING_API_KEY                 - Ant Ling API key\n  OPENAI_API_KEY                   - OpenAI GPT API key\n  AZURE_OPENAI_API_KEY             - Azure OpenAI API key\n  AZURE_OPENAI_BASE_URL            - Azure OpenAI/Cognitive Services base URL (e.g. https://{resource}.openai.azure.com)\n  AZURE_OPENAI_RESOURCE_NAME       - Azure OpenAI resource name (alternative to base URL)\n  AZURE_OPENAI_API_VERSION         - Azure OpenAI API version (default: v1)\n  AZURE_OPENAI_DEPLOYMENT_NAME_MAP - Azure OpenAI model=deployment map (comma-separated)\n  DEEPSEEK_API_KEY                 - DeepSeek API key\n  DEVIN_API_KEY                    - Devin CLI subscription session token (or /login devin)\n  NVIDIA_API_KEY                   - NVIDIA NIM API key\n  GEMINI_API_KEY                   - Google Gemini API key\n  GROQ_API_KEY                     - Groq API key\n  CEREBRAS_API_KEY                 - Cerebras API key\n  XAI_API_KEY                      - xAI Grok API key\n  FIREWORKS_API_KEY                - Fireworks API key\n  TOGETHER_API_KEY                 - Together AI API key\n  OPENROUTER_API_KEY               - OpenRouter API key\n  AI_GATEWAY_API_KEY               - Vercel AI Gateway API key\n  ZAI_API_KEY                      - ZAI API key\n  ZAI_CODING_CN_API_KEY            - ZAI Coding Plan API key (China)\n  MISTRAL_API_KEY                  - Mistral API key\n  MINIMAX_API_KEY                  - MiniMax API key\n  MOONSHOT_API_KEY                 - Moonshot AI API key\n  META_API_KEY                     - Meta Model API key (Muse Spark); META_MODEL_API_KEY/MODEL_API_KEY also read\n  OPENCODE_API_KEY                 - OpenCode Zen/OpenCode Go API key\n  KIMI_API_KEY                     - Kimi For Coding API key\n  CLOUDFLARE_API_KEY               - Cloudflare API token (Workers AI and AI Gateway)\n  CLOUDFLARE_ACCOUNT_ID            - Cloudflare account id (required for both)\n  CLOUDFLARE_GATEWAY_ID            - Cloudflare AI Gateway slug (required for AI Gateway)\n  XIAOMI_API_KEY                   - Xiaomi MiMo API key (api.xiaomimimo.com billing)\n  XIAOMI_TOKEN_PLAN_CN_API_KEY     - Xiaomi MiMo Token Plan API key (China region)\n  XIAOMI_TOKEN_PLAN_AMS_API_KEY    - Xiaomi MiMo Token Plan API key (Amsterdam region)\n  XIAOMI_TOKEN_PLAN_SGP_API_KEY    - Xiaomi MiMo Token Plan API key (Singapore region)\n  ZYLOO_API_KEY                    - Zyloo API key\n  AWS_PROFILE                      - AWS profile for Amazon Bedrock\n  AWS_ACCESS_KEY_ID                - AWS access key for Amazon Bedrock\n  AWS_SECRET_ACCESS_KEY            - AWS secret key for Amazon Bedrock\n  AWS_BEARER_TOKEN_BEDROCK         - Bedrock API key (bearer token)\n  AWS_REGION                       - AWS region for Amazon Bedrock (e.g., us-east-1)\n  ${ENV_AGENT_DIR.padEnd(32)} - Config directory (default: ~/${CONFIG_DIR_NAME}/agent)\n  ${ENV_SESSION_DIR.padEnd(32)} - Session storage directory (overridden by --session-dir)\n  OMK_PACKAGE_DIR                  - Override package directory (for Nix/Guix store paths)\n  OMK_TOOL_SCHEDULER               - Tool scheduler override: dag-v2 or waves-v1 rollback\n  OMK_OFFLINE                      - Disable startup network operations when set to 1/true/yes\n  OMK_TELEMETRY                    - Override install telemetry when set to 1/true/yes or 0/false/no\n  OMK_SHARE_VIEWER_URL             - Base URL for /share command (default: https://omk.dev/session/)\n  ADAPTORCH_API_KEY                - AdaptOrch API key (optional; enables the doctor adaptorch check)\n  ADAPTORCH_API_URL                - AdaptOrch API base URL (default: https://api.adaptorch.com)\n\n${chalk.bold(\"Built-in Tool Names:\")}\n  read   - Read file contents\n  bash   - Execute bash commands\n  edit   - Edit files with find/replace\n  write  - Write files (creates/overwrites)\n  grep   - Search file contents (read-only, off by default)\n  find   - Find files by glob pattern (read-only, off by default)\n  ls     - List directory contents (read-only, off by default)\n`);\n}\n"]}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGzF,MAAM,UAAU,SAAS,CAAC,cAAgC,EAAQ;IACjE,IAAI,kBAAkB,GAAG,EAAE,CAAC;IAC5B,IAAI,cAAc,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjD,kBAAkB,GAAG,KAAK,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,KAAK,cAAc;aAC7E,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACd,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,iBAAiB,IAAI,CAAC,aAAa,EAAE,CAAC;YAC9E,OAAO,OAAO,IAAI,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC;QAAA,CAC3D,CAAC;aACD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IAClB,CAAC;IACD,iEAAiE;IACjE,0CAA0C;IAC1C,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;;EAElC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;IAClB,QAAQ;;EAEV,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC;IACrB,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;;IAER,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;;EAEV,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mFA0C2D,kBAAkB;;EAEnG,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC;;IAErB,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ;;;IAGR,QAAQ,eAAe,eAAe;IACtC,QAAQ;;EAEV,KAAK,CAAC,IAAI,CAAC,wBAAwB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA2ClC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC,mCAAmC,eAAe;IAC1E,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;;;;;;;;;EAS5B,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC;;;;;;;;CAQnC,CAAC,CAAC;AAAA,CACF","sourcesContent":["import chalk from \"chalk\";\nimport { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR, ENV_SESSION_DIR } from \"../config.ts\";\nimport type { ExtensionFlag } from \"../core/extensions/types.ts\";\n\nexport function printHelp(extensionFlags?: ExtensionFlag[]): void {\n\tlet extensionFlagsText = \"\";\n\tif (extensionFlags && extensionFlags.length > 0) {\n\t\textensionFlagsText = `\\n${chalk.bold(\"Extension CLI Flags:\")}\\n${extensionFlags\n\t\t\t.map((flag) => {\n\t\t\t\tconst value = flag.type === \"string\" ? \" <value>\" : \"\";\n\t\t\t\tconst description = flag.description ?? `Registered by ${flag.extensionPath}`;\n\t\t\t\treturn `  --${flag.name}${value}`.padEnd(30) + description;\n\t\t\t})\n\t\t\t.join(\"\\n\")}\\n`;\n\t}\n\t// CLI help is intentional stdout, not application debug logging.\n\t// pi-lens-ignore: no-console-except-error\n\tconsole.log(`${chalk.bold(APP_NAME)} - AI coding assistant with read, bash, edit, write tools\n\n${chalk.bold(\"Usage:\")}\n  ${APP_NAME} [options] [@files...] [messages...]\n\n${chalk.bold(\"Commands:\")}\n  ${APP_NAME} init --global [--dry-run] Create missing user context documents without overwriting settings\n  ${APP_NAME} install <source> [-l]     Install extension source and add to settings\n  ${APP_NAME} remove <source> [-l]      Remove extension source from settings\n  ${APP_NAME} uninstall <source> [-l]   Alias for remove\n  ${APP_NAME} update [source|self|omk]  Update OMK and installed extensions\n  ${APP_NAME} list                      List installed extensions from settings\n  ${APP_NAME} package doctor <source>   Diagnose omk/pi manifest and runtime compatibility as JSON\n  ${APP_NAME} config                    Open TUI to enable/disable package resources\n  ${APP_NAME} quota                     Manage CodexBar quota connector and summaries\n  ${APP_NAME} provider doctor <id>      Diagnose a provider as sanitized JSON (--probe-model adds an\n                                 opt-in Level-2 generative probe that may incur provider costs)\n  ${APP_NAME} session doctor            Inspect or safely repair one session (--session, --repair, --dry-run)\n  ${APP_NAME} doctor resources [--json] [--report] Inspect current pressure or aggregate local observations\n  ${APP_NAME} doctor adaptorch [--json]  Verify ADAPTORCH_API_KEY reaches the AdaptOrch API (0 ok, 1 unset, 2 failed)\n  ${APP_NAME} router-feedback compile-bias  Compile this repository's bounded router bias snapshot\n  ${APP_NAME} <command> --help          Show help for install/remove/uninstall/update/list\n\n${chalk.bold(\"Options:\")}\n  --provider <name>              Provider name (default: google)\n  --model <pattern>              Model pattern or ID (supports \"provider/id\" and optional \":<thinking>\")\n  --model-contract <file>        Pin an optional JSON model/effort/output dispatch policy\n  --api-key <key>                API key (defaults to env vars)\n  --system-prompt <text>         System prompt (default: coding assistant prompt)\n  --append-system-prompt <text>  Append text or file contents to the system prompt (can be used multiple times)\n  --mode <mode>                  Output mode: text (default), json, rpc, or acp (conversation-only)\n  --print, -p                    Non-interactive mode: process prompt and exit\n  --continue, -c                 Continue previous session\n  --resume, -r                   Select a session to resume\n  --session <path|id>            Use specific session file or partial UUID\n  --session-id <id>              Use exact project session ID, creating it if missing\n  --fork <path|id>               Fork specific session file or partial UUID into a new session\n  --session-dir <dir>            Directory for session storage and lookup\n  --no-session                   Don't save session (ephemeral)\n  --name, -n <name>              Set session display name\n  --models <patterns>            Comma-separated model patterns for Ctrl+P cycling\n                                 Supports globs (anthropic/*, *sonnet*) and fuzzy matching\n  --no-tools, -nt                Disable all tools by default (built-in and extension)\n  --no-builtin-tools, -nbt       Disable built-in tools by default but keep extension/custom tools enabled\n  --tools, -t <tools>            Comma-separated allowlist of tool names to enable\n                                 Applies to built-in, extension, and custom tools\n  --exclude-tools, -xt <tools>   Comma-separated denylist of tool names to disable\n                                 Applies to built-in, extension, and custom tools\n  --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh, max, ultra\n  --extension, -e <path>         Load an extension file (can be used multiple times)\n  --no-extensions, -ne           Disable extension discovery (explicit -e paths still work)\n  --skill <path>                 Load a skill file or directory (can be used multiple times)\n  --no-skills, -ns               Disable skills discovery and loading\n  --prompt-template <path>       Load a prompt template file or directory (can be used multiple times)\n  --no-prompt-templates, -np     Disable prompt template discovery and loading\n  --theme <path>                 Load a theme file or directory (can be used multiple times)\n  --no-themes                    Disable theme discovery and loading\n  --no-context-files, -nc        Disable AGENTS.md and CLAUDE.md discovery and loading\n  --export <file>                Export session file to HTML and exit\n  --list-models [search]         List available models (with optional fuzzy search)\n  --verbose                      Force verbose startup (overrides quietStartup setting)\n  --offline                      Disable startup network operations (same as OMK_OFFLINE=1)\n  --help, -h                     Show this help\n  --version, -v                  Show version number\n\nExtensions can register additional flags (e.g., --plan from plan-mode extension).${extensionFlagsText}\n\n${chalk.bold(\"Examples:\")}\n  # Interactive mode\n  ${APP_NAME}\n\n  # Interactive mode with initial prompt\n  ${APP_NAME} \"List all .ts files in src/\"\n\n  # Include files in initial message\n  ${APP_NAME} @prompt.md @image.png \"What color is the sky?\"\n\n  # Non-interactive mode (process and exit)\n  ${APP_NAME} -p \"List all .ts files in src/\"\n\n  # Multiple messages (interactive)\n  ${APP_NAME} \"Read package.json\" \"What dependencies do we have?\"\n\n  # Continue previous session\n  ${APP_NAME} --continue \"What did we discuss?\"\n\n  # Start a named session\n  ${APP_NAME} --name \"Refactor auth module\"\n\n  # Use different model\n  ${APP_NAME} --provider openai --model gpt-4o-mini \"Help me refactor this code\"\n\n  # Use model with provider prefix (no --provider needed)\n  ${APP_NAME} --model openai/gpt-4o \"Help me refactor this code\"\n\n  # Use model with thinking level shorthand\n  ${APP_NAME} --model sonnet:high \"Solve this complex problem\"\n\n  # Limit model cycling to specific models\n  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o\n\n  # Limit to a specific provider with glob pattern\n  ${APP_NAME} --models \"github-copilot/*\"\n\n  # Cycle models with fixed thinking levels\n  ${APP_NAME} --models sonnet:high,haiku:low\n\n  # Start with a specific thinking level\n  ${APP_NAME} --thinking high \"Solve this complex problem\"\n\n  # Read-only mode (no file modifications possible)\n  ${APP_NAME} --tools read,grep,find,ls -p \"Review the code in src/\"\n\n  # Disable one tool while keeping the rest available\n  ${APP_NAME} --exclude-tools ask_question\n\n  # Export a session file to HTML\n  ${APP_NAME} --export ~/${CONFIG_DIR_NAME}/agent/sessions/--path--/session.jsonl\n  ${APP_NAME} --export session.jsonl output.html\n\n${chalk.bold(\"Environment Variables:\")}\n  ANTHROPIC_API_KEY                - Anthropic Claude API key\n  ANTHROPIC_OAUTH_TOKEN            - Anthropic OAuth token (alternative to API key)\n  ANT_LING_API_KEY                 - Ant Ling API key\n  OPENAI_API_KEY                   - OpenAI GPT API key\n  AZURE_OPENAI_API_KEY             - Azure OpenAI API key\n  AZURE_OPENAI_BASE_URL            - Azure OpenAI/Cognitive Services base URL (e.g. https://{resource}.openai.azure.com)\n  AZURE_OPENAI_RESOURCE_NAME       - Azure OpenAI resource name (alternative to base URL)\n  AZURE_OPENAI_API_VERSION         - Azure OpenAI API version (default: v1)\n  AZURE_OPENAI_DEPLOYMENT_NAME_MAP - Azure OpenAI model=deployment map (comma-separated)\n  DEEPSEEK_API_KEY                 - DeepSeek API key\n  DEVIN_API_KEY                    - Devin CLI subscription session token (or /login devin)\n  NVIDIA_API_KEY                   - NVIDIA NIM API key\n  GEMINI_API_KEY                   - Google Gemini API key\n  GROQ_API_KEY                     - Groq API key\n  CEREBRAS_API_KEY                 - Cerebras API key\n  XAI_API_KEY                      - xAI Grok API key\n  FIREWORKS_API_KEY                - Fireworks API key\n  TOGETHER_API_KEY                 - Together AI API key\n  OPENROUTER_API_KEY               - OpenRouter API key\n  AI_GATEWAY_API_KEY               - Vercel AI Gateway API key\n  ZAI_API_KEY                      - ZAI API key\n  ZAI_CODING_CN_API_KEY            - ZAI Coding Plan API key (China)\n  MISTRAL_API_KEY                  - Mistral API key\n  MINIMAX_API_KEY                  - MiniMax API key\n  MOONSHOT_API_KEY                 - Moonshot AI API key\n  META_API_KEY                     - Meta Model API key (Muse Spark); META_MODEL_API_KEY/MODEL_API_KEY also read\n  OPENCODE_API_KEY                 - OpenCode Zen/OpenCode Go API key\n  KIMI_API_KEY                     - Kimi For Coding API key\n  WORKBUDDY_API_KEY                - WorkBuddy (Tencent CodeBuddy) plan key\n  CLOUDFLARE_API_KEY               - Cloudflare API token (Workers AI and AI Gateway)\n  CLOUDFLARE_ACCOUNT_ID            - Cloudflare account id (required for both)\n  CLOUDFLARE_GATEWAY_ID            - Cloudflare AI Gateway slug (required for AI Gateway)\n  XIAOMI_API_KEY                   - Xiaomi MiMo API key (api.xiaomimimo.com billing)\n  XIAOMI_TOKEN_PLAN_CN_API_KEY     - Xiaomi MiMo Token Plan API key (China region)\n  XIAOMI_TOKEN_PLAN_AMS_API_KEY    - Xiaomi MiMo Token Plan API key (Amsterdam region)\n  XIAOMI_TOKEN_PLAN_SGP_API_KEY    - Xiaomi MiMo Token Plan API key (Singapore region)\n  ZYLOO_API_KEY                    - Zyloo API key\n  AWS_PROFILE                      - AWS profile for Amazon Bedrock\n  AWS_ACCESS_KEY_ID                - AWS access key for Amazon Bedrock\n  AWS_SECRET_ACCESS_KEY            - AWS secret key for Amazon Bedrock\n  AWS_BEARER_TOKEN_BEDROCK         - Bedrock API key (bearer token)\n  AWS_REGION                       - AWS region for Amazon Bedrock (e.g., us-east-1)\n  ${ENV_AGENT_DIR.padEnd(32)} - Config directory (default: ~/${CONFIG_DIR_NAME}/agent)\n  ${ENV_SESSION_DIR.padEnd(32)} - Session storage directory (overridden by --session-dir)\n  OMK_PACKAGE_DIR                  - Override package directory (for Nix/Guix store paths)\n  OMK_TOOL_SCHEDULER               - Tool scheduler override: dag-v2 or waves-v1 rollback\n  OMK_OFFLINE                      - Disable startup network operations when set to 1/true/yes\n  OMK_TELEMETRY                    - Override install telemetry when set to 1/true/yes or 0/false/no\n  OMK_SHARE_VIEWER_URL             - Base URL for /share command (default: https://omk.dev/session/)\n  ADAPTORCH_API_KEY                - AdaptOrch API key (optional; enables the doctor adaptorch check)\n  ADAPTORCH_API_URL                - AdaptOrch API base URL (default: https://api.adaptorch.com)\n\n${chalk.bold(\"Built-in Tool Names:\")}\n  read   - Read file contents\n  bash   - Execute bash commands\n  edit   - Edit files with find/replace\n  write  - Write files (creates/overwrites)\n  grep   - Search file contents (read-only, off by default)\n  find   - Find files by glob pattern (read-only, off by default)\n  ls     - List directory contents (read-only, off by default)\n`);\n}\n"]}

package/dist/coordination/awareness.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Change awareness: what a change invalidates, and who may proceed next.
+ *
+ * Both functions are deliberately conservative. Invalidation treats an
+ * unmapped dependent as affected, because "we have no edge for it" is not
+ * evidence that it is unaffected. Frontier admission lets an unrelated
+ * follower pass a blocked leader, but never lets a later request that
+ * conflicts with an older waiting one jump ahead of it.
+ */
+import type { ResourceClaim } from "./types.ts";
+export interface WaitingRequest {
+    readonly requestId: string;
+    readonly claims: readonly ResourceClaim[];
+}
+/**
+ * Transitive closure over reverse dependencies.
+ *
+ * `unknownDependents` are nodes whose dependencies could not be resolved; they
+ * join the affected set rather than being assumed safe. Reaching a fixpoint
+ * terminates on cycles because the set only grows and is bounded by the graph.
+ */
+export declare function invalidate(dependencies: Readonly<Record<string, readonly string[]>>, changed: readonly string[], unknownDependents?: readonly string[]): Set<string>;
+/**
+ * Requests admissible right now, in queue order.
+ *
+ * A request is admitted only when it conflicts neither with the active claims
+ * nor with any earlier waiting request. Accumulating earlier claims — whether
+ * or not they were admitted — is what stops a stream of later readers from
+ * starving an older writer. Capacity fairness is not modelled here.
+ */
+export declare function admissibleFrontier(waiting: readonly WaitingRequest[], active: readonly ResourceClaim[]): string[];
+//# sourceMappingURL=awareness.d.ts.map

package/dist/coordination/awareness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"awareness.d.ts","sourceRoot":"","sources":["../../src/coordination/awareness.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACzB,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,EACzD,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,iBAAiB,GAAE,SAAS,MAAM,EAAO,GACvC,GAAG,CAAC,MAAM,CAAC,CAab;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,EAAE,MAAM,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,EAAE,CAYjH","sourcesContent":["/**\n * Change awareness: what a change invalidates, and who may proceed next.\n *\n * Both functions are deliberately conservative. Invalidation treats an\n * unmapped dependent as affected, because \"we have no edge for it\" is not\n * evidence that it is unaffected. Frontier admission lets an unrelated\n * follower pass a blocked leader, but never lets a later request that\n * conflicts with an older waiting one jump ahead of it.\n */\n\nimport { claimSetsConflict } from \"./resource.ts\";\nimport type { ResourceClaim } from \"./types.ts\";\n\nexport interface WaitingRequest {\n\treadonly requestId: string;\n\treadonly claims: readonly ResourceClaim[];\n}\n\n/**\n * Transitive closure over reverse dependencies.\n *\n * `unknownDependents` are nodes whose dependencies could not be resolved; they\n * join the affected set rather than being assumed safe. Reaching a fixpoint\n * terminates on cycles because the set only grows and is bounded by the graph.\n */\nexport function invalidate(\n\tdependencies: Readonly<Record<string, readonly string[]>>,\n\tchanged: readonly string[],\n\tunknownDependents: readonly string[] = [],\n): Set<string> {\n\tconst affected = new Set<string>([...changed, ...unknownDependents]);\n\tfor (;;) {\n\t\tlet grew = false;\n\t\tfor (const [node, deps] of Object.entries(dependencies)) {\n\t\t\tif (affected.has(node)) continue;\n\t\t\tif (deps.some((dep) => affected.has(dep))) {\n\t\t\t\taffected.add(node);\n\t\t\t\tgrew = true;\n\t\t\t}\n\t\t}\n\t\tif (!grew) return affected;\n\t}\n}\n\n/**\n * Requests admissible right now, in queue order.\n *\n * A request is admitted only when it conflicts neither with the active claims\n * nor with any earlier waiting request. Accumulating earlier claims — whether\n * or not they were admitted — is what stops a stream of later readers from\n * starving an older writer. Capacity fairness is not modelled here.\n */\nexport function admissibleFrontier(waiting: readonly WaitingRequest[], active: readonly ResourceClaim[]): string[] {\n\tconst chosen: string[] = [];\n\tconst reserved: ResourceClaim[] = [...active];\n\tconst earlier: ResourceClaim[] = [];\n\tfor (const request of waiting) {\n\t\tif (!claimSetsConflict(request.claims, reserved) && !claimSetsConflict(request.claims, earlier)) {\n\t\t\tchosen.push(request.requestId);\n\t\t\treserved.push(...request.claims);\n\t\t}\n\t\tearlier.push(...request.claims);\n\t}\n\treturn chosen;\n}\n"]}

package/dist/coordination/awareness.js

@@ -0,0 +1,55 @@
+/**
+ * Change awareness: what a change invalidates, and who may proceed next.
+ *
+ * Both functions are deliberately conservative. Invalidation treats an
+ * unmapped dependent as affected, because "we have no edge for it" is not
+ * evidence that it is unaffected. Frontier admission lets an unrelated
+ * follower pass a blocked leader, but never lets a later request that
+ * conflicts with an older waiting one jump ahead of it.
+ */
+import { claimSetsConflict } from "./resource.js";
+/**
+ * Transitive closure over reverse dependencies.
+ *
+ * `unknownDependents` are nodes whose dependencies could not be resolved; they
+ * join the affected set rather than being assumed safe. Reaching a fixpoint
+ * terminates on cycles because the set only grows and is bounded by the graph.
+ */
+export function invalidate(dependencies, changed, unknownDependents = []) {
+    const affected = new Set([...changed, ...unknownDependents]);
+    for (;;) {
+        let grew = false;
+        for (const [node, deps] of Object.entries(dependencies)) {
+            if (affected.has(node))
+                continue;
+            if (deps.some((dep) => affected.has(dep))) {
+                affected.add(node);
+                grew = true;
+            }
+        }
+        if (!grew)
+            return affected;
+    }
+}
+/**
+ * Requests admissible right now, in queue order.
+ *
+ * A request is admitted only when it conflicts neither with the active claims
+ * nor with any earlier waiting request. Accumulating earlier claims — whether
+ * or not they were admitted — is what stops a stream of later readers from
+ * starving an older writer. Capacity fairness is not modelled here.
+ */
+export function admissibleFrontier(waiting, active) {
+    const chosen = [];
+    const reserved = [...active];
+    const earlier = [];
+    for (const request of waiting) {
+        if (!claimSetsConflict(request.claims, reserved) && !claimSetsConflict(request.claims, earlier)) {
+            chosen.push(request.requestId);
+            reserved.push(...request.claims);
+        }
+        earlier.push(...request.claims);
+    }
+    return chosen;
+}
+//# sourceMappingURL=awareness.js.map

package/dist/coordination/awareness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"awareness.js","sourceRoot":"","sources":["../../src/coordination/awareness.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAQlD;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACzB,YAAyD,EACzD,OAA0B,EAC1B,iBAAiB,GAAsB,EAAE,EAC3B;IACd,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,CAAC,GAAG,OAAO,EAAE,GAAG,iBAAiB,CAAC,CAAC,CAAC;IACrE,SAAS,CAAC;QACT,IAAI,IAAI,GAAG,KAAK,CAAC;QACjB,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;YACzD,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YACjC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBAC3C,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACnB,IAAI,GAAG,IAAI,CAAC;YACb,CAAC;QACF,CAAC;QACD,IAAI,CAAC,IAAI;YAAE,OAAO,QAAQ,CAAC;IAC5B,CAAC;AAAA,CACD;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAkC,EAAE,MAAgC,EAAY;IAClH,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAoB,CAAC,GAAG,MAAM,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;QAC/B,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;YACjG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,MAAM,CAAC;AAAA,CACd","sourcesContent":["/**\n * Change awareness: what a change invalidates, and who may proceed next.\n *\n * Both functions are deliberately conservative. Invalidation treats an\n * unmapped dependent as affected, because \"we have no edge for it\" is not\n * evidence that it is unaffected. Frontier admission lets an unrelated\n * follower pass a blocked leader, but never lets a later request that\n * conflicts with an older waiting one jump ahead of it.\n */\n\nimport { claimSetsConflict } from \"./resource.ts\";\nimport type { ResourceClaim } from \"./types.ts\";\n\nexport interface WaitingRequest {\n\treadonly requestId: string;\n\treadonly claims: readonly ResourceClaim[];\n}\n\n/**\n * Transitive closure over reverse dependencies.\n *\n * `unknownDependents` are nodes whose dependencies could not be resolved; they\n * join the affected set rather than being assumed safe. Reaching a fixpoint\n * terminates on cycles because the set only grows and is bounded by the graph.\n */\nexport function invalidate(\n\tdependencies: Readonly<Record<string, readonly string[]>>,\n\tchanged: readonly string[],\n\tunknownDependents: readonly string[] = [],\n): Set<string> {\n\tconst affected = new Set<string>([...changed, ...unknownDependents]);\n\tfor (;;) {\n\t\tlet grew = false;\n\t\tfor (const [node, deps] of Object.entries(dependencies)) {\n\t\t\tif (affected.has(node)) continue;\n\t\t\tif (deps.some((dep) => affected.has(dep))) {\n\t\t\t\taffected.add(node);\n\t\t\t\tgrew = true;\n\t\t\t}\n\t\t}\n\t\tif (!grew) return affected;\n\t}\n}\n\n/**\n * Requests admissible right now, in queue order.\n *\n * A request is admitted only when it conflicts neither with the active claims\n * nor with any earlier waiting request. Accumulating earlier claims — whether\n * or not they were admitted — is what stops a stream of later readers from\n * starving an older writer. Capacity fairness is not modelled here.\n */\nexport function admissibleFrontier(waiting: readonly WaitingRequest[], active: readonly ResourceClaim[]): string[] {\n\tconst chosen: string[] = [];\n\tconst reserved: ResourceClaim[] = [...active];\n\tconst earlier: ResourceClaim[] = [];\n\tfor (const request of waiting) {\n\t\tif (!claimSetsConflict(request.claims, reserved) && !claimSetsConflict(request.claims, earlier)) {\n\t\t\tchosen.push(request.requestId);\n\t\t\treserved.push(...request.claims);\n\t\t}\n\t\tearlier.push(...request.claims);\n\t}\n\treturn chosen;\n}\n"]}

package/dist/coordination/broker.d.ts

@@ -0,0 +1,79 @@
+/**
+ * In-process admission broker for parallel sessions.
+ *
+ * Safety property: a grant that may still own a live external effect keeps
+ * holding its claims. Expiry, cancellation and authority restart are
+ * authorization events; only a trusted supervisor reporting termination frees
+ * the claims. Treating a lapsed deadline as "the effect stopped" is exactly how
+ * two sessions end up writing the same path.
+ *
+ * Bounded reference semantics: a single trusted state machine, canonical claim
+ * keys, and every shared effect crossing this broker. No IPC, no OS fencing,
+ * no persistence — those belong to the supervisor this broker reports to.
+ */
+import type { EffectState, GrantToken, ResourceClaim, Sequence } from "./types.ts";
+export interface AdmissionBrokerOptions {
+    /** Total admissible weight of concurrently active grants. */
+    readonly capacity: number;
+}
+export interface AcquireInput {
+    readonly sessionId: string;
+    readonly incarnation: Sequence | string;
+    readonly claims: readonly ResourceClaim[];
+    readonly now: number;
+    readonly ttl: number;
+    readonly weight?: number;
+}
+export interface StartInput {
+    readonly token: GrantToken;
+    readonly now: number;
+    /** Claims the operation actually resolved to after approval hooks. */
+    readonly actualClaims: readonly ResourceClaim[];
+}
+export declare class AdmissionBroker {
+    private readonly capacity;
+    private authorityEpoch;
+    private grantCounter;
+    private readonly incarnations;
+    private readonly grants;
+    constructor(options: AdmissionBrokerOptions);
+    /**
+     * Announce a session incarnation. Re-registering does not free the previous
+     * incarnation's grants: a restarted session cannot assume its predecessor's
+     * effects stopped.
+     */
+    register(sessionId: string): Sequence;
+    /** Grants still holding their claims, including quarantined ones. */
+    private activeGrants;
+    acquire(input: AcquireInput): GrantToken | null;
+    /** Resolve a token that is still authoritative for new action. */
+    private authoritative;
+    /** Resolve a token for settlement only; accepts superseded epochs. */
+    private settleable;
+    /**
+     * Bind an effect to its reservation. The actual claims must equal the
+     * reserved set exactly — an approval hook that widened scope has to be
+     * re-admitted, not silently allowed to run under the old grant.
+     */
+    start(input: StartInput): boolean;
+    /**
+     * Apply lapsed authorization deadlines. A reservation that never started is
+     * released; a running effect is quarantined and keeps its claims.
+     */
+    expire(now: number): void;
+    /** Withdraw authorization. Requested cancellation is not observed termination. */
+    cancel(token: GrantToken): boolean;
+    /**
+     * Trusted supervisor event: this exact effect is gone. Accepted for
+     * superseded epochs so a restarted authority can still settle what the
+     * previous one started, never to authorize new work.
+     */
+    confirmTerminated(token: GrantToken): boolean;
+    /** Fence the authority. Live effects stay quarantined until confirmed. */
+    restart(): void;
+    stateOf(token: GrantToken): EffectState | undefined;
+    claimsOf(token: GrantToken): readonly ResourceClaim[];
+    /** Invariant: active grants fit capacity and never pairwise conflict. */
+    isSafe(): boolean;
+}
+//# sourceMappingURL=broker.d.ts.map

package/dist/coordination/broker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker.d.ts","sourceRoot":"","sources":["../../src/coordination/broker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAYnF,MAAM,WAAW,sBAAsB;IACtC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,QAAQ,GAAG,MAAM,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,SAAS,aAAa,EAAE,CAAC;CAChD;AAQD,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,cAAc,CAA2B;IACjD,OAAO,CAAC,YAAY,CAA2B;IAC/C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA+B;IAC5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IAEnD,YAAY,OAAO,EAAE,sBAAsB,EAG1C;IAED;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAOpC;IAED,qEAAqE;IACrE,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,GAAG,IAAI,CAuC9C;IAED,kEAAkE;IAClE,OAAO,CAAC,aAAa;IASrB,sEAAsE;IACtE,OAAO,CAAC,UAAU;IAMlB;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAShC;IAED;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAOxB;IAED,kFAAkF;IAClF,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAKjC;IAED;;;;OAIG;IACH,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAM5C;IAED,0EAA0E;IAC1E,OAAO,IAAI,IAAI,CAKd;IAED,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,SAAS,CAGlD;IAED,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,aAAa,EAAE,CAGpD;IAED,yEAAyE;IACzE,MAAM,IAAI,OAAO,CAShB;CACD","sourcesContent":["/**\n * In-process admission broker for parallel sessions.\n *\n * Safety property: a grant that may still own a live external effect keeps\n * holding its claims. Expiry, cancellation and authority restart are\n * authorization events; only a trusted supervisor reporting termination frees\n * the claims. Treating a lapsed deadline as \"the effect stopped\" is exactly how\n * two sessions end up writing the same path.\n *\n * Bounded reference semantics: a single trusted state machine, canonical claim\n * keys, and every shared effect crossing this broker. No IPC, no OS fencing,\n * no persistence — those belong to the supervisor this broker reports to.\n */\n\nimport { claimSetsConflict, sameClaimSet } from \"./resource.ts\";\nimport type { EffectState, GrantToken, ResourceClaim, Sequence } from \"./types.ts\";\nimport { nextSequence, SETTLED_EFFECT_STATES, sequence } from \"./types.ts\";\n\ninterface Grant {\n\treadonly token: GrantToken;\n\treadonly claims: readonly ResourceClaim[];\n\treadonly weight: number;\n\tstate: EffectState;\n\t/** True once an external effect may exist. Never inferred from the clock. */\n\teffectLive: boolean;\n}\n\nexport interface AdmissionBrokerOptions {\n\t/** Total admissible weight of concurrently active grants. */\n\treadonly capacity: number;\n}\n\nexport interface AcquireInput {\n\treadonly sessionId: string;\n\treadonly incarnation: Sequence | string;\n\treadonly claims: readonly ResourceClaim[];\n\treadonly now: number;\n\treadonly ttl: number;\n\treadonly weight?: number;\n}\n\nexport interface StartInput {\n\treadonly token: GrantToken;\n\treadonly now: number;\n\t/** Claims the operation actually resolved to after approval hooks. */\n\treadonly actualClaims: readonly ResourceClaim[];\n}\n\nfunction assertNonNegativeInteger(value: number, label: string): void {\n\tif (typeof value !== \"number\" || !Number.isSafeInteger(value) || value < 0) {\n\t\tthrow new TypeError(`${label} must be a nonnegative safe integer`);\n\t}\n}\n\nexport class AdmissionBroker {\n\tprivate readonly capacity: number;\n\tprivate authorityEpoch: Sequence = sequence(\"1\");\n\tprivate grantCounter: Sequence = sequence(\"0\");\n\tprivate readonly incarnations = new Map<string, Sequence>();\n\tprivate readonly grants = new Map<string, Grant>();\n\n\tconstructor(options: AdmissionBrokerOptions) {\n\t\tassertNonNegativeInteger(options.capacity, \"capacity\");\n\t\tthis.capacity = options.capacity;\n\t}\n\n\t/**\n\t * Announce a session incarnation. Re-registering does not free the previous\n\t * incarnation's grants: a restarted session cannot assume its predecessor's\n\t * effects stopped.\n\t */\n\tregister(sessionId: string): Sequence {\n\t\tif (typeof sessionId !== \"string\" || sessionId.length === 0) {\n\t\t\tthrow new TypeError(\"sessionId must be a non-empty string\");\n\t\t}\n\t\tconst next = nextSequence(this.incarnations.get(sessionId) ?? sequence(\"0\"));\n\t\tthis.incarnations.set(sessionId, next);\n\t\treturn next;\n\t}\n\n\t/** Grants still holding their claims, including quarantined ones. */\n\tprivate activeGrants(): Grant[] {\n\t\treturn [...this.grants.values()].filter((g) => !SETTLED_EFFECT_STATES.has(g.state));\n\t}\n\n\tacquire(input: AcquireInput): GrantToken | null {\n\t\tassertNonNegativeInteger(input.now, \"now\");\n\t\tconst weight = input.weight ?? 1;\n\t\tassertNonNegativeInteger(weight, \"weight\");\n\t\tif (!Number.isSafeInteger(input.ttl) || input.ttl <= 0) {\n\t\t\tthrow new TypeError(\"ttl must be a positive safe integer\");\n\t\t}\n\t\tconst incarnation = sequence(input.incarnation);\n\t\tif (this.incarnations.get(input.sessionId) !== incarnation) {\n\t\t\tthrow new TypeError(\"stale session incarnation\");\n\t\t}\n\t\tif (input.claims.length === 0) {\n\t\t\tthrow new TypeError(\"an unknown scope must not be admitted as an empty scope\");\n\t\t}\n\n\t\t// Settle lapsed authorizations first; this never evicts a live effect.\n\t\tthis.expire(input.now);\n\t\tconst active = this.activeGrants();\n\t\tconst used = active.reduce((sum, g) => sum + g.weight, 0);\n\t\tif (weight + used > this.capacity) return null;\n\t\tconst claims = [...input.claims];\n\t\tif (active.some((g) => claimSetsConflict(claims, g.claims))) return null;\n\n\t\tthis.grantCounter = nextSequence(this.grantCounter);\n\t\tconst token: GrantToken = Object.freeze({\n\t\t\tauthorityEpoch: this.authorityEpoch,\n\t\t\tgrantSequence: this.grantCounter,\n\t\t\tsessionId: input.sessionId,\n\t\t\tsessionIncarnation: incarnation,\n\t\t\tauthorizationDeadline: input.now + input.ttl,\n\t\t});\n\t\tthis.grants.set(token.grantSequence, {\n\t\t\ttoken,\n\t\t\tclaims: Object.freeze(claims),\n\t\t\tweight,\n\t\t\tstate: \"reserved\",\n\t\t\teffectLive: false,\n\t\t});\n\t\treturn token;\n\t}\n\n\t/** Resolve a token that is still authoritative for new action. */\n\tprivate authoritative(token: GrantToken): Grant | undefined {\n\t\tconst grant = this.grants.get(token.grantSequence);\n\t\tif (grant === undefined || !sameToken(grant.token, token)) return undefined;\n\t\tif (token.authorityEpoch !== this.authorityEpoch) return undefined;\n\t\tif (this.incarnations.get(token.sessionId) !== token.sessionIncarnation) return undefined;\n\t\tif (SETTLED_EFFECT_STATES.has(grant.state)) return undefined;\n\t\treturn grant;\n\t}\n\n\t/** Resolve a token for settlement only; accepts superseded epochs. */\n\tprivate settleable(token: GrantToken): Grant | undefined {\n\t\tconst grant = this.grants.get(token.grantSequence);\n\t\tif (grant === undefined || !sameToken(grant.token, token)) return undefined;\n\t\treturn SETTLED_EFFECT_STATES.has(grant.state) ? undefined : grant;\n\t}\n\n\t/**\n\t * Bind an effect to its reservation. The actual claims must equal the\n\t * reserved set exactly — an approval hook that widened scope has to be\n\t * re-admitted, not silently allowed to run under the old grant.\n\t */\n\tstart(input: StartInput): boolean {\n\t\tassertNonNegativeInteger(input.now, \"now\");\n\t\tconst grant = this.authoritative(input.token);\n\t\tif (grant === undefined || grant.state !== \"reserved\") return false;\n\t\tif (input.now >= grant.token.authorizationDeadline) return false;\n\t\tif (!sameClaimSet(input.actualClaims, grant.claims)) return false;\n\t\tgrant.state = \"running\";\n\t\tgrant.effectLive = true;\n\t\treturn true;\n\t}\n\n\t/**\n\t * Apply lapsed authorization deadlines. A reservation that never started is\n\t * released; a running effect is quarantined and keeps its claims.\n\t */\n\texpire(now: number): void {\n\t\tassertNonNegativeInteger(now, \"now\");\n\t\tfor (const grant of this.activeGrants()) {\n\t\t\tif (now >= grant.token.authorizationDeadline) {\n\t\t\t\tgrant.state = grant.effectLive ? \"quarantined\" : \"cancelled\";\n\t\t\t}\n\t\t}\n\t}\n\n\t/** Withdraw authorization. Requested cancellation is not observed termination. */\n\tcancel(token: GrantToken): boolean {\n\t\tconst grant = this.settleable(token);\n\t\tif (grant === undefined) return false;\n\t\tgrant.state = grant.effectLive ? \"quarantined\" : \"cancelled\";\n\t\treturn true;\n\t}\n\n\t/**\n\t * Trusted supervisor event: this exact effect is gone. Accepted for\n\t * superseded epochs so a restarted authority can still settle what the\n\t * previous one started, never to authorize new work.\n\t */\n\tconfirmTerminated(token: GrantToken): boolean {\n\t\tconst grant = this.settleable(token);\n\t\tif (grant === undefined) return false;\n\t\tgrant.effectLive = false;\n\t\tgrant.state = \"terminated\";\n\t\treturn true;\n\t}\n\n\t/** Fence the authority. Live effects stay quarantined until confirmed. */\n\trestart(): void {\n\t\tthis.authorityEpoch = nextSequence(this.authorityEpoch);\n\t\tfor (const grant of this.activeGrants()) {\n\t\t\tgrant.state = grant.effectLive ? \"quarantined\" : \"cancelled\";\n\t\t}\n\t}\n\n\tstateOf(token: GrantToken): EffectState | undefined {\n\t\tconst grant = this.grants.get(token.grantSequence);\n\t\treturn grant !== undefined && sameToken(grant.token, token) ? grant.state : undefined;\n\t}\n\n\tclaimsOf(token: GrantToken): readonly ResourceClaim[] {\n\t\tconst grant = this.grants.get(token.grantSequence);\n\t\treturn grant !== undefined && sameToken(grant.token, token) ? grant.claims : [];\n\t}\n\n\t/** Invariant: active grants fit capacity and never pairwise conflict. */\n\tisSafe(): boolean {\n\t\tconst active = this.activeGrants();\n\t\tif (active.reduce((sum, g) => sum + g.weight, 0) > this.capacity) return false;\n\t\tfor (const [index, grant] of active.entries()) {\n\t\t\tfor (const other of active.slice(index + 1)) {\n\t\t\t\tif (claimSetsConflict(grant.claims, other.claims)) return false;\n\t\t\t}\n\t\t}\n\t\treturn true;\n\t}\n}\n\nfunction sameToken(a: GrantToken, b: GrantToken): boolean {\n\treturn (\n\t\ta.authorityEpoch === b.authorityEpoch &&\n\t\ta.grantSequence === b.grantSequence &&\n\t\ta.sessionId === b.sessionId &&\n\t\ta.sessionIncarnation === b.sessionIncarnation &&\n\t\ta.authorizationDeadline === b.authorizationDeadline\n\t);\n}\n"]}

package/dist/coordination/broker.js

@@ -0,0 +1,195 @@
+/**
+ * In-process admission broker for parallel sessions.
+ *
+ * Safety property: a grant that may still own a live external effect keeps
+ * holding its claims. Expiry, cancellation and authority restart are
+ * authorization events; only a trusted supervisor reporting termination frees
+ * the claims. Treating a lapsed deadline as "the effect stopped" is exactly how
+ * two sessions end up writing the same path.
+ *
+ * Bounded reference semantics: a single trusted state machine, canonical claim
+ * keys, and every shared effect crossing this broker. No IPC, no OS fencing,
+ * no persistence — those belong to the supervisor this broker reports to.
+ */
+import { claimSetsConflict, sameClaimSet } from "./resource.js";
+import { nextSequence, SETTLED_EFFECT_STATES, sequence } from "./types.js";
+function assertNonNegativeInteger(value, label) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`${label} must be a nonnegative safe integer`);
+    }
+}
+export class AdmissionBroker {
+    capacity;
+    authorityEpoch = sequence("1");
+    grantCounter = sequence("0");
+    incarnations = new Map();
+    grants = new Map();
+    constructor(options) {
+        assertNonNegativeInteger(options.capacity, "capacity");
+        this.capacity = options.capacity;
+    }
+    /**
+     * Announce a session incarnation. Re-registering does not free the previous
+     * incarnation's grants: a restarted session cannot assume its predecessor's
+     * effects stopped.
+     */
+    register(sessionId) {
+        if (typeof sessionId !== "string" || sessionId.length === 0) {
+            throw new TypeError("sessionId must be a non-empty string");
+        }
+        const next = nextSequence(this.incarnations.get(sessionId) ?? sequence("0"));
+        this.incarnations.set(sessionId, next);
+        return next;
+    }
+    /** Grants still holding their claims, including quarantined ones. */
+    activeGrants() {
+        return [...this.grants.values()].filter((g) => !SETTLED_EFFECT_STATES.has(g.state));
+    }
+    acquire(input) {
+        assertNonNegativeInteger(input.now, "now");
+        const weight = input.weight ?? 1;
+        assertNonNegativeInteger(weight, "weight");
+        if (!Number.isSafeInteger(input.ttl) || input.ttl <= 0) {
+            throw new TypeError("ttl must be a positive safe integer");
+        }
+        const incarnation = sequence(input.incarnation);
+        if (this.incarnations.get(input.sessionId) !== incarnation) {
+            throw new TypeError("stale session incarnation");
+        }
+        if (input.claims.length === 0) {
+            throw new TypeError("an unknown scope must not be admitted as an empty scope");
+        }
+        // Settle lapsed authorizations first; this never evicts a live effect.
+        this.expire(input.now);
+        const active = this.activeGrants();
+        const used = active.reduce((sum, g) => sum + g.weight, 0);
+        if (weight + used > this.capacity)
+            return null;
+        const claims = [...input.claims];
+        if (active.some((g) => claimSetsConflict(claims, g.claims)))
+            return null;
+        this.grantCounter = nextSequence(this.grantCounter);
+        const token = Object.freeze({
+            authorityEpoch: this.authorityEpoch,
+            grantSequence: this.grantCounter,
+            sessionId: input.sessionId,
+            sessionIncarnation: incarnation,
+            authorizationDeadline: input.now + input.ttl,
+        });
+        this.grants.set(token.grantSequence, {
+            token,
+            claims: Object.freeze(claims),
+            weight,
+            state: "reserved",
+            effectLive: false,
+        });
+        return token;
+    }
+    /** Resolve a token that is still authoritative for new action. */
+    authoritative(token) {
+        const grant = this.grants.get(token.grantSequence);
+        if (grant === undefined || !sameToken(grant.token, token))
+            return undefined;
+        if (token.authorityEpoch !== this.authorityEpoch)
+            return undefined;
+        if (this.incarnations.get(token.sessionId) !== token.sessionIncarnation)
+            return undefined;
+        if (SETTLED_EFFECT_STATES.has(grant.state))
+            return undefined;
+        return grant;
+    }
+    /** Resolve a token for settlement only; accepts superseded epochs. */
+    settleable(token) {
+        const grant = this.grants.get(token.grantSequence);
+        if (grant === undefined || !sameToken(grant.token, token))
+            return undefined;
+        return SETTLED_EFFECT_STATES.has(grant.state) ? undefined : grant;
+    }
+    /**
+     * Bind an effect to its reservation. The actual claims must equal the
+     * reserved set exactly — an approval hook that widened scope has to be
+     * re-admitted, not silently allowed to run under the old grant.
+     */
+    start(input) {
+        assertNonNegativeInteger(input.now, "now");
+        const grant = this.authoritative(input.token);
+        if (grant === undefined || grant.state !== "reserved")
+            return false;
+        if (input.now >= grant.token.authorizationDeadline)
+            return false;
+        if (!sameClaimSet(input.actualClaims, grant.claims))
+            return false;
+        grant.state = "running";
+        grant.effectLive = true;
+        return true;
+    }
+    /**
+     * Apply lapsed authorization deadlines. A reservation that never started is
+     * released; a running effect is quarantined and keeps its claims.
+     */
+    expire(now) {
+        assertNonNegativeInteger(now, "now");
+        for (const grant of this.activeGrants()) {
+            if (now >= grant.token.authorizationDeadline) {
+                grant.state = grant.effectLive ? "quarantined" : "cancelled";
+            }
+        }
+    }
+    /** Withdraw authorization. Requested cancellation is not observed termination. */
+    cancel(token) {
+        const grant = this.settleable(token);
+        if (grant === undefined)
+            return false;
+        grant.state = grant.effectLive ? "quarantined" : "cancelled";
+        return true;
+    }
+    /**
+     * Trusted supervisor event: this exact effect is gone. Accepted for
+     * superseded epochs so a restarted authority can still settle what the
+     * previous one started, never to authorize new work.
+     */
+    confirmTerminated(token) {
+        const grant = this.settleable(token);
+        if (grant === undefined)
+            return false;
+        grant.effectLive = false;
+        grant.state = "terminated";
+        return true;
+    }
+    /** Fence the authority. Live effects stay quarantined until confirmed. */
+    restart() {
+        this.authorityEpoch = nextSequence(this.authorityEpoch);
+        for (const grant of this.activeGrants()) {
+            grant.state = grant.effectLive ? "quarantined" : "cancelled";
+        }
+    }
+    stateOf(token) {
+        const grant = this.grants.get(token.grantSequence);
+        return grant !== undefined && sameToken(grant.token, token) ? grant.state : undefined;
+    }
+    claimsOf(token) {
+        const grant = this.grants.get(token.grantSequence);
+        return grant !== undefined && sameToken(grant.token, token) ? grant.claims : [];
+    }
+    /** Invariant: active grants fit capacity and never pairwise conflict. */
+    isSafe() {
+        const active = this.activeGrants();
+        if (active.reduce((sum, g) => sum + g.weight, 0) > this.capacity)
+            return false;
+        for (const [index, grant] of active.entries()) {
+            for (const other of active.slice(index + 1)) {
+                if (claimSetsConflict(grant.claims, other.claims))
+                    return false;
+            }
+        }
+        return true;
+    }
+}
+function sameToken(a, b) {
+    return (a.authorityEpoch === b.authorityEpoch &&
+        a.grantSequence === b.grantSequence &&
+        a.sessionId === b.sessionId &&
+        a.sessionIncarnation === b.sessionIncarnation &&
+        a.authorizationDeadline === b.authorizationDeadline);
+}
+//# sourceMappingURL=broker.js.map

package/dist/coordination/broker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker.js","sourceRoot":"","sources":["../../src/coordination/broker.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * In-process admission broker for parallel sessions.\n *\n * Safety property: a grant that may still own a live external effect keeps\n * holding its claims. Expiry, cancellation and authority restart are\n * authorization events; only a trusted supervisor reporting termination frees\n * the claims. Treating a lapsed deadline as \"the effect stopped\" is exactly how\n * two sessions end up writing the same path.\n *\n * Bounded reference semantics: a single trusted state machine, canonical claim\n * keys, and every shared effect crossing this broker. No IPC, no OS fencing,\n * no persistence — those belong to the supervisor this broker reports to.\n */\n\nimport { claimSetsConflict, sameClaimSet } from \"./resource.ts\";\nimport type { EffectState, GrantToken, ResourceClaim, Sequence } from \"./types.ts\";\nimport { nextSequence, SETTLED_EFFECT_STATES, sequence } from \"./types.ts\";\n\ninterface Grant {\n\treadonly token: GrantToken;\n\treadonly claims: readonly ResourceClaim[];\n\treadonly weight: number;\n\tstate: EffectState;\n\t/** True once an external effect may exist. Never inferred from the clock. */\n\teffectLive: boolean;\n}\n\nexport interface AdmissionBrokerOptions {\n\t/** Total admissible weight of concurrently active grants. */\n\treadonly capacity: number;\n}\n\nexport interface AcquireInput {\n\treadonly sessionId: string;\n\treadonly incarnation: Sequence | string;\n\treadonly claims: readonly ResourceClaim[];\n\treadonly now: number;\n\treadonly ttl: number;\n\treadonly weight?: number;\n}\n\nexport interface StartInput {\n\treadonly token: GrantToken;\n\treadonly now: number;\n\t/** Claims the operation actually resolved to after approval hooks. */\n\treadonly actualClaims: readonly ResourceClaim[];\n}\n\nfunction assertNonNegativeInteger(value: number, label: string): void {\n\tif (typeof value !== \"number\" || !Number.isSafeInteger(value) || value < 0) {\n\t\tthrow new TypeError(`${label} must be a nonnegative safe integer`);\n\t}\n}\n\nexport class AdmissionBroker {\n\tprivate readonly capacity: number;\n\tprivate authorityEpoch: Sequence = sequence(\"1\");\n\tprivate grantCounter: Sequence = sequence(\"0\");\n\tprivate readonly incarnations = new Map<string, Sequence>();\n\tprivate readonly grants = new Map<string, Grant>();\n\n\tconstructor(options: AdmissionBrokerOptions) {\n\t\tassertNonNegativeInteger(options.capacity, \"capacity\");\n\t\tthis.capacity = options.capacity;\n\t}\n\n\t/**\n\t * Announce a session incarnation. Re-registering does not free the previous\n\t * incarnation's grants: a restarted session cannot assume its predecessor's\n\t * effects stopped.\n\t */\n\tregister(sessionId: string): Sequence {\n\t\tif (typeof sessionId !== \"string\" || sessionId.length === 0) {\n\t\t\tthrow new TypeError(\"sessionId must be a non-empty string\");\n\t\t}\n\t\tconst next = nextSequence(this.incarnations.get(sessionId) ?? sequence(\"0\"));\n\t\tthis.incarnations.set(sessionId, next);\n\t\treturn next;\n\t}\n\n\t/** Grants still holding their claims, including quarantined ones. */\n\tprivate activeGrants(): Grant[] {\n\t\treturn [...this.grants.values()].filter((g) => !SETTLED_EFFECT_STATES.has(g.state));\n\t}\n\n\tacquire(input: AcquireInput): GrantToken | null {\n\t\tassertNonNegativeInteger(input.now, \"now\");\n\t\tconst weight = input.weight ?? 1;\n\t\tassertNonNegativeInteger(weight, \"weight\");\n\t\tif (!Number.isSafeInteger(input.ttl) || input.ttl <= 0) {\n\t\t\tthrow new TypeError(\"ttl must be a positive safe integer\");\n\t\t}\n\t\tconst incarnation = sequence(input.incarnation);\n\t\tif (this.incarnations.get(input.sessionId) !== incarnation) {\n\t\t\tthrow new TypeError(\"stale session incarnation\");\n\t\t}\n\t\tif (input.claims.length === 0) {\n\t\t\tthrow new TypeError(\"an unknown scope must not be admitted as an empty scope\");\n\t\t}\n\n\t\t// Settle lapsed authorizations first; this never evicts a live effect.\n\t\tthis.expire(input.now);\n\t\tconst active = this.activeGrants();\n\t\tconst used = active.reduce((sum, g) => sum + g.weight, 0);\n\t\tif (weight + used > this.capacity) return null;\n\t\tconst claims = [...input.claims];\n\t\tif (active.some((g) => claimSetsConflict(claims, g.claims))) return null;\n\n\t\tthis.grantCounter = nextSequence(this.grantCounter);\n\t\tconst token: GrantToken = Object.freeze({\n\t\t\tauthorityEpoch: this.authorityEpoch,\n\t\t\tgrantSequence: this.grantCounter,\n\t\t\tsessionId: input.sessionId,\n\t\t\tsessionIncarnation: incarnation,\n\t\t\tauthorizationDeadline: input.now + input.ttl,\n\t\t});\n\t\tthis.grants.set(token.grantSequence, {\n\t\t\ttoken,\n\t\t\tclaims: Object.freeze(claims),\n\t\t\tweight,\n\t\t\tstate: \"reserved\",\n\t\t\teffectLive: false,\n\t\t});\n\t\treturn token;\n\t}\n\n\t/** Resolve a token that is still authoritative for new action. */\n\tprivate authoritative(token: GrantToken): Grant | undefined {\n\t\tconst grant = this.grants.get(token.grantSequence);\n\t\tif (grant === undefined || !sameToken(grant.token, token)) return undefined;\n\t\tif (token.authorityEpoch !== this.authorityEpoch) return undefined;\n\t\tif (this.incarnations.get(token.sessionId) !== token.sessionIncarnation) return undefined;\n\t\tif (SETTLED_EFFECT_STATES.has(grant.state)) return undefined;\n\t\treturn grant;\n\t}\n\n\t/** Resolve a token for settlement only; accepts superseded epochs. */\n\tprivate settleable(token: GrantToken): Grant | undefined {\n\t\tconst grant = this.grants.get(token.grantSequence);\n\t\tif (grant === undefined || !sameToken(grant.token, token)) return undefined;\n\t\treturn SETTLED_EFFECT_STATES.has(grant.state) ? undefined : grant;\n\t}\n\n\t/**\n\t * Bind an effect to its reservation. The actual claims must equal the\n\t * reserved set exactly — an approval hook that widened scope has to be\n\t * re-admitted, not silently allowed to run under the old grant.\n\t */\n\tstart(input: StartInput): boolean {\n\t\tassertNonNegativeInteger(input.now, \"now\");\n\t\tconst grant = this.authoritative(input.token);\n\t\tif (grant === undefined || grant.state !== \"reserved\") return false;\n\t\tif (input.now >= grant.token.authorizationDeadline) return false;\n\t\tif (!sameClaimSet(input.actualClaims, grant.claims)) return false;\n\t\tgrant.state = \"running\";\n\t\tgrant.effectLive = true;\n\t\treturn true;\n\t}\n\n\t/**\n\t * Apply lapsed authorization deadlines. A reservation that never started is\n\t * released; a running effect is quarantined and keeps its claims.\n\t */\n\texpire(now: number): void {\n\t\tassertNonNegativeInteger(now, \"now\");\n\t\tfor (const grant of this.activeGrants()) {\n\t\t\tif (now >= grant.token.authorizationDeadline) {\n\t\t\t\tgrant.state = grant.effectLive ? \"quarantined\" : \"cancelled\";\n\t\t\t}\n\t\t}\n\t}\n\n\t/** Withdraw authorization. Requested cancellation is not observed termination. */\n\tcancel(token: GrantToken): boolean {\n\t\tconst grant = this.settleable(token);\n\t\tif (grant === undefined) return false;\n\t\tgrant.state = grant.effectLive ? \"quarantined\" : \"cancelled\";\n\t\treturn true;\n\t}\n\n\t/**\n\t * Trusted supervisor event: this exact effect is gone. Accepted for\n\t * superseded epochs so a restarted authority can still settle what the\n\t * previous one started, never to authorize new work.\n\t */\n\tconfirmTerminated(token: GrantToken): boolean {\n\t\tconst grant = this.settleable(token);\n\t\tif (grant === undefined) return false;\n\t\tgrant.effectLive = false;\n\t\tgrant.state = \"terminated\";\n\t\treturn true;\n\t}\n\n\t/** Fence the authority. Live effects stay quarantined until confirmed. */\n\trestart(): void {\n\t\tthis.authorityEpoch = nextSequence(this.authorityEpoch);\n\t\tfor (const grant of this.activeGrants()) {\n\t\t\tgrant.state = grant.effectLive ? \"quarantined\" : \"cancelled\";\n\t\t}\n\t}\n\n\tstateOf(token: GrantToken): EffectState | undefined {\n\t\tconst grant = this.grants.get(token.grantSequence);\n\t\treturn grant !== undefined && sameToken(grant.token, token) ? grant.state : undefined;\n\t}\n\n\tclaimsOf(token: GrantToken): readonly ResourceClaim[] {\n\t\tconst grant = this.grants.get(token.grantSequence);\n\t\treturn grant !== undefined && sameToken(grant.token, token) ? grant.claims : [];\n\t}\n\n\t/** Invariant: active grants fit capacity and never pairwise conflict. */\n\tisSafe(): boolean {\n\t\tconst active = this.activeGrants();\n\t\tif (active.reduce((sum, g) => sum + g.weight, 0) > this.capacity) return false;\n\t\tfor (const [index, grant] of active.entries()) {\n\t\t\tfor (const other of active.slice(index + 1)) {\n\t\t\t\tif (claimSetsConflict(grant.claims, other.claims)) return false;\n\t\t\t}\n\t\t}\n\t\treturn true;\n\t}\n}\n\nfunction sameToken(a: GrantToken, b: GrantToken): boolean {\n\treturn (\n\t\ta.authorityEpoch === b.authorityEpoch &&\n\t\ta.grantSequence === b.grantSequence &&\n\t\ta.sessionId === b.sessionId &&\n\t\ta.sessionIncarnation === b.sessionIncarnation &&\n\t\ta.authorizationDeadline === b.authorizationDeadline\n\t);\n}\n"]}