{"owner":"osaurus-ai","repo":"osaurus","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Codex Configuration - osaurus-staging\n\nSee `~/AGENTS.md` for the global Codex environment, wiki protocol, hard rules,\nmachine context, and useful commands.\n\n## Build & Test\n\nRunning tests and builds is encouraged — they're how we keep quality high. The\ncanonical lanes live in `Makefile`:\n\n- `make test` — `swift test --package-path Packages/OsaurusCore` (fast unit\n  loop).\n- `make ci-test` — mirrors the CI `test-core` xcodebuild job (`xcbeautify`\n  output, xcresult bundle at `build/Tests.xcresult`).\n- `make cli` / `make app` — build the CLI and the embedded app via\n  `xcodebuild` against `osaurus.xcworkspace`.\n- `make evals` / `make evals-all` — run OsaurusEvals suites under\n  `Packages/OsaurusEvals/Suites/*`.\n- Live-app smoke: `scripts/live-proof/launch-keychain-free-osaurus.sh`.\n\n### Keychain tip (optional)\n\nSome tests touch Osaurus Keychain wrappers. If a test doesn't need real\nKeychain access, prefer running it in keychain-disabled mode to avoid\nunrelated \"wants to use your confidential information\" prompts:\n\n```bash\nOSAURUS_DISABLE_KEYCHAIN_FOR_TESTS=1 \\\nOSAURUS_TEST_ROOT=/tmp/osaurus-test \\\nOSU_MODELS_DIR=/tmp/osaurus-test-models \\\nmake test\n```\n\nIn that mode, Keychain wrappers should return nil / no-op on reads, writes,\nand deletes rather than calling `SecItemCopyMatching` / `SecItemAdd` /\n`SecItemUpdate` / `SecItemDelete` against the login Keychain.\n\n`OSU_MODELS_DIR` (pointed at an empty dir) matters on machines with real\nmodels in `~/MLXModels`: dispatch-style tests start real `ChatSession.send`\nturns, and without the override they resolve the user's installed models and\ntry to load them inside the SwiftPM harness — which has no Metal kernels and\ndies with `MLX/MLXArray.swift precondition failed`. With the override those\nsends fail fast with `modelUnavailable`, matching CI behavior. Keychain-gated\nsuites (e.g. `PluginAgentScopingTests`) still fail by design under\n`OSAURUS_DISABLE_KEYCHAIN_FOR_TESTS=1`; run those without the flag when you\nneed real Keychain proof.\n\n## Osaurus Release Proof and PR Reporting\n\nFor every change that can affect a runtime, parser, tool call, agent loop,\nsubagent/delegation path, cache, model setting, or user-facing execution\nlifecycle, source inspection and focused unit tests are necessary but never\nsufficient:\n\n- Build a fresh isolated Release development app and exercise the real Chat and\n  Settings UI. Click every control touched by the change, save it, navigate\n  away and back, relaunch when persistence is part of the contract, and prove\n  the effective request/runtime state changed. Inspect the complete turn until\n  reasoning closes, every tool/subagent card settles, Stop disappears, input\n  unlocks, and a follow-up turn completes.\n- During a user-authorized live UI proof, when Osaurus shows its first-use\n  permission popup for a newly exercised tool kind, choose **Always Allow**\n  for that tool in the isolated test agent. Record the granted tool kind and\n  verify the choice survives the intended follow-up/relaunch. This does not\n  authorize unrelated macOS, browser, account, or external-service grants.\n- For batching/delegation specifically, live-test the allowed agent/local/cloud\n  target pool, add/remove/save/relaunch, target notes, permission modes, worker\n  tools, child budgets, per-agent maximum fan-out, Server Continuous Batching,\n  Concurrent Sessions, RAM-safety clamp/refusal, same-model batching,\n  different-model handoff/restore, mixed local/remote fan-out, ordering,\n  cancellation at each lifecycle phase, cache reuse, and parent continuation.\n  A visible control or source-wired value is not proof that it is effective.\n- Run the relevant focused regression suites and the applicable full\n  OsaurusEvals lanes, including AgentLoop and AgentLoopFrontier when agent-loop\n  behavior can change. Add efficient deterministic eval cases for new\n  delegation, batching, parser, completion, cancellation, or cache contracts.\n  If an external judge key is unavailable, preserve the raw artifacts and\n  grade the named rows manually rather than silently omitting them.\n- Every GitHub PR proof/status comment must include the exact tested source SHA,\n  app/vMLX pin, model bundle and generation defaults, suite/eval names, raw\n  scores and denominators, failed-case attribution, and paths or hashes for\n  local evidence. Never post images to the repository. Never report only the\n  favorable model rows or summarize a non-perfect score as passing.\n- Re-run the affected full matrix after rebase, merge-conflict resolution, or\n  any source/config change. If any required source trace, automated score, or\n  live UI row is missing, report `PARTIAL` or `BLOCKED` and do not describe the\n  PR as fixed, proven, release-ready, or regression-free.\n\n## Model Runtime Non-Negotiables\n\n- Never add forced thinking tags, parser repair, hidden sampler defaults,\n  repetition-penalty rescues, close-token bias, or prompt/template coercion to\n  make a model appear coherent.\n- Never add fake guards, placeholder gates, hardcoded model allowlists,\n  synthetic output filters, or \"same behavior\" enforcement to make a runtime\n  row look safe. If JANG, JANGTQ, MXFP, VL/audio/video, hybrid cache, SWA,\n  speed, coherency, leaking tool parser output, reasoning boundaries, or RAM\n  policy is wrong, trace the root cause and fix the real function/path. If the\n  root cause is not fixed yet, document the row as `PARTIAL` or `BLOCKED` with\n  exact evidence instead of forcing behavior in prompts, parsers, samplers, or\n  UI state.\n- Chat/API defaults must come from the active model bundle's\n  `generation_config.json` or equivalent runtime config unless a user\n  explicitly overrides them. Native-trained defaults such as top-k matter for\n  quality and speed; do not replace them with synthetic Osaurus defaults.\n- Reasoning, tool, and chat-template behavior must be auto-detected from the\n  bundle/tokenizer/template/runtime config. Do not fake thinking envelopes,\n  strip visible output to hide parser bugs, or coerce one model family into\n  another family's template.\n- Runtime proof must separate proven, partial, failed, and unproven rows. A\n  load-only result, single prompt, or source-only assertion is not enough to\n  call a model family working.\n- RAM proof means Activity Monitor physical footprint stays within the intended\n  low-RAM gate. A row that reaches full model size in physical footprint is a\n  failure even if generation is coherent.\n- Every generation row must record token/s. Missing token/s is a blocked or\n  failed row, not production proof.\n- Multi-turn coherency is required: visible answer, reasoning channel behavior,\n  no looping, no hidden reasoning-only output, no length-cap fake pass, and no\n  raw parser marker leak.\n- Reasoning fixes must preserve the model's real contract. Do not inject fake\n  closers/openers, hide leaked reasoning markers by stripping visible text, or\n  treat a parser cleanup as correctness unless the live output, structured\n  reasoning field, and user-visible answer all prove the boundary is correct.\n- Cache proof must match the model architecture:\n  - Full-attention models need real KV, prefix/paged, L2 disk, and TurboQuant\n    KV proof when enabled.\n  - Qwen-style hybrid SSM needs KV plus SSM companion rederive/hit proof; a KV\n    hit alone is not enough.\n  - ZAYA/CCA and HY3-style models need companion cache and pooling proof.\n  - DeepSeek-V4 CSA/HSA/SWA hybrid pool needs prefix/L2 plus pool restore/hit\n    proof and must not use TurboQuant KV as a substitute.\n- VL/video rows require real media payloads, media cache salts, and cache-hit\n  validation; text-path evidence does not prove media-path correctness.\n- Big-model load cancellation must be live-proven before promotion: if the user\n  stops generation, closes chat, or exits during first load, startup must\n  cancel and cleanup must prevent zombie loads and OOM growth.\n- Qwen/JANG/JANGTQ RAM regressions require end-to-end Osaurus proof with\n  physical footprint, stop status, cache telemetry, token/s, and visible\n  multi-turn output before being called fixed.\n- Memory limits must apply only through documented user/runtime settings and\n  the resolved runtime plan. Do not add hidden RAM percentage blocks or fake\n  load refusals. If a selected setting or true runtime limit prevents a load or\n  context request, fail before unsafe MLX/Metal allocation with a clear typed\n  API/app error that tells the user what setting or resource limit applied.\n- Server settings are part of runtime proof, not a source-only contract. For\n  every claimed model/runtime row, verify the relevant server setting wiring\n  through live Osaurus panel/API state: generation defaults and overrides,\n  reasoning mode, tool mode, memory enablement, prefix cache, paged KV, L2 disk\n  cache, TurboQuant KV when applicable, media/cache settings, concurrency, and\n  memory-safety settings. Toggle the setting, speak to the model, and confirm\n  the runtime behavior, telemetry, and user-visible state changed as intended.\n  If settings conflict or do not compose for a model family, question the\n  compatibility contract, fix the real wiring, or document the row as\n  `PARTIAL`/`BLOCKED` with the exact incompatible setting combination.\n- Treat every implementation change as a cross-function and cross-settings\n  compatibility change until proven otherwise. Trace every shared value from\n  persisted global and per-agent configuration through UI editing, save and\n  relaunch, request/schema composition, runtime admission, execution,\n  telemetry, cancellation, and finalization. Test precedence and composition\n  with adjacent controls (including model defaults, explicit request\n  overrides, reasoning, tools, cache, batching, concurrency, and RAM safety)\n  and remove duplicate, stale, or unwired consumers instead of adding a second\n  source of truth. A direct unit test of the changed function is not sufficient\n  when another consumer or setting can alter the effective behavior.\n- For every touched or behaviorally related user setting, use the real built\n  app to change or toggle it, save it, exercise the affected workflow, and\n  visually inspect the complete result. Relaunch when persistence or\n  next-load-only behavior is part of the contract. Reading a stored value,\n  source default, or test fixture is never a substitute for this live proof.\n- Tool, memory, and cache setting proof must exercise the live user flow after\n  the setting changes. Required tool proof includes exact tool args, tool-result\n  history grounding, a second tool call after history, and no parser/protocol\n  leakage. Memory proof, when the shipped flow exposes memory context or memory\n  toggles, must include multi-turn chat that depends on the memory state. Cache\n  proof must include baseline, changed setting, reload when next-load-only,\n  live chat, `/admin/cache-stats`, and typed incompatibility rather than silent\n  ignore for unsupported combinations.\n- For the active Gemma 4 QAT checkpoint, every OsaurusAI MXFP4 and JANG_4M\n  bundle must prove real Osaurus tool use before harness or benchmark results\n  are treated as meaningful. A row needs load, at least one executed tool with\n  exact name and parseable JSON arguments, tool-result continuation, clean\n  visible text, no protocol/reasoning/tool marker leakage, cache telemetry with\n  paged KV off and disk/L2 behavior recorded, and a scored AgentLoop harness\n  artifact with every failed case attributed. Decent non-perfect scores are\n  acceptable for teammate testing only when the failures are documented; source\n  or BF16 Gemma folders do not count for this QAT checkpoint.\n- Do not spawn recursive local \"agent\" workers, Python subagents, or delegated\n  helper agents for Gemma/Osaurus release work unless the user explicitly asks.\n  Do not use Python or shell wrappers as an orchestration layer to farm work out\n  to Codex, Claude, local LLMs, or other helper agents. Work directly in the\n  current session, keep status artifacts current, and use normal shell, test,\n  build, and proof commands for evidence. Python is allowed for deterministic\n  parsing or proof harnesses, but never to recursively run another agent.\n"},"files":{"AGENTS.md":"# Codex Configuration - osaurus-staging\n\nSee `~/AGENTS.md` for the global Codex environment, wiki protocol, hard rules,\nmachine context, and useful commands.\n\n## Build & Test\n\nRunning tests and builds is encouraged — they're how we keep quality high. The\ncanonical lanes live in `Makefile`:\n\n- `make test` — `swift test --package-path Packages/OsaurusCore` (fast unit\n  loop).\n- `make ci-test` — mirrors the CI `test-core` xcodebuild job (`xcbeautify`\n  output, xcresult bundle at `build/Tests.xcresult`).\n- `make cli` / `make app` — build the CLI and the embedded app via\n  `xcodebuild` against `osaurus.xcworkspace`.\n- `make evals` / `make evals-all` — run OsaurusEvals suites under\n  `Packages/OsaurusEvals/Suites/*`.\n- Live-app smoke: `scripts/live-proof/launch-keychain-free-osaurus.sh`.\n\n### Keychain tip (optional)\n\nSome tests touch Osaurus Keychain wrappers. If a test doesn't need real\nKeychain access, prefer running it in keychain-disabled mode to avoid\nunrelated \"wants to use your confidential information\" prompts:\n\n```bash\nOSAURUS_DISABLE_KEYCHAIN_FOR_TESTS=1 \\\nOSAURUS_TEST_ROOT=/tmp/osaurus-test \\\nOSU_MODELS_DIR=/tmp/osaurus-test-models \\\nmake test\n```\n\nIn that mode, Keychain wrappers should return nil / no-op on reads, writes,\nand deletes rather than calling `SecItemCopyMatching` / `SecItemAdd` /\n`SecItemUpdate` / `SecItemDelete` against the login Keychain.\n\n`OSU_MODELS_DIR` (pointed at an empty dir) matters on machines with real\nmodels in `~/MLXModels`: dispatch-style tests start real `ChatSession.send`\nturns, and without the override they resolve the user's installed models and\ntry to load them inside the SwiftPM harness — which has no Metal kernels and\ndies with `MLX/MLXArray.swift precondition failed`. With the override those\nsends fail fast with `modelUnavailable`, matching CI behavior. Keychain-gated\nsuites (e.g. `PluginAgentScopingTests`) still fail by design under\n`OSAURUS_DISABLE_KEYCHAIN_FOR_TESTS=1`; run those without the flag when you\nneed real Keychain proof.\n\n## Osaurus Release Proof and PR Reporting\n\nFor every change that can affect a runtime, parser, tool call, agent loop,\nsubagent/delegation path, cache, model setting, or user-facing execution\nlifecycle, source inspection and focused unit tests are necessary but never\nsufficient:\n\n- Build a fresh isolated Release development app and exercise the real Chat and\n  Settings UI. Click every control touched by the change, save it, navigate\n  away and back, relaunch when persistence is part of the contract, and prove\n  the effective request/runtime state changed. Inspect the complete turn until\n  reasoning closes, every tool/subagent card settles, Stop disappears, input\n  unlocks, and a follow-up turn completes.\n- During a user-authorized live UI proof, when Osaurus shows its first-use\n  permission popup for a newly exercised tool kind, choose **Always Allow**\n  for that tool in the isolated test agent. Record the granted tool kind and\n  verify the choice survives the intended follow-up/relaunch. This does not\n  authorize unrelated macOS, browser, account, or external-service grants.\n- For batching/delegation specifically, live-test the allowed agent/local/cloud\n  target pool, add/remove/save/relaunch, target notes, permission modes, worker\n  tools, child budgets, per-agent maximum fan-out, Server Continuous Batching,\n  Concurrent Sessions, RAM-safety clamp/refusal, same-model batching,\n  different-model handoff/restore, mixed local/remote fan-out, ordering,\n  cancellation at each lifecycle phase, cache reuse, and parent continuation.\n  A visible control or source-wired value is not proof that it is effective.\n- Run the relevant focused regression suites and the applicable full\n  OsaurusEvals lanes, including AgentLoop and AgentLoopFrontier when agent-loop\n  behavior can change. Add efficient deterministic eval cases for new\n  delegation, batching, parser, completion, cancellation, or cache contracts.\n  If an external judge key is unavailable, preserve the raw artifacts and\n  grade the named rows manually rather than silently omitting them.\n- Every GitHub PR proof/status comment must include the exact tested source SHA,\n  app/vMLX pin, model bundle and generation defaults, suite/eval names, raw\n  scores and denominators, failed-case attribution, and paths or hashes for\n  local evidence. Never post images to the repository. Never report only the\n  favorable model rows or summarize a non-perfect score as passing.\n- Re-run the affected full matrix after rebase, merge-conflict resolution, or\n  any source/config change. If any required source trace, automated score, or\n  live UI row is missing, report `PARTIAL` or `BLOCKED` and do not describe the\n  PR as fixed, proven, release-ready, or regression-free.\n\n## Model Runtime Non-Negotiables\n\n- Never add forced thinking tags, parser repair, hidden sampler defaults,\n  repetition-penalty rescues, close-token bias, or prompt/template coercion to\n  make a model appear coherent.\n- Never add fake guards, placeholder gates, hardcoded model allowlists,\n  synthetic output filters, or \"same behavior\" enforcement to make a runtime\n  row look safe. If JANG, JANGTQ, MXFP, VL/audio/video, hybrid cache, SWA,\n  speed, coherency, leaking tool parser output, reasoning boundaries, or RAM\n  policy is wrong, trace the root cause and fix the real function/path. If the\n  root cause is not fixed yet, document the row as `PARTIAL` or `BLOCKED` with\n  exact evidence instead of forcing behavior in prompts, parsers, samplers, or\n  UI state.\n- Chat/API defaults must come from the active model bundle's\n  `generation_config.json` or equivalent runtime config unless a user\n  explicitly overrides them. Native-trained defaults such as top-k matter for\n  quality and speed; do not replace them with synthetic Osaurus defaults.\n- Reasoning, tool, and chat-template behavior must be auto-detected from the\n  bundle/tokenizer/template/runtime config. Do not fake thinking envelopes,\n  strip visible output to hide parser bugs, or coerce one model family into\n  another family's template.\n- Runtime proof must separate proven, partial, failed, and unproven rows. A\n  load-only result, single prompt, or source-only assertion is not enough to\n  call a model family working.\n- RAM proof means Activity Monitor physical footprint stays within the intended\n  low-RAM gate. A row that reaches full model size in physical footprint is a\n  failure even if generation is coherent.\n- Every generation row must record token/s. Missing token/s is a blocked or\n  failed row, not production proof.\n- Multi-turn coherency is required: visible answer, reasoning channel behavior,\n  no looping, no hidden reasoning-only output, no length-cap fake pass, and no\n  raw parser marker leak.\n- Reasoning fixes must preserve the model's real contract. Do not inject fake\n  closers/openers, hide leaked reasoning markers by stripping visible text, or\n  treat a parser cleanup as correctness unless the live output, structured\n  reasoning field, and user-visible answer all prove the boundary is correct.\n- Cache proof must match the model architecture:\n  - Full-attention models need real KV, prefix/paged, L2 disk, and TurboQuant\n    KV proof when enabled.\n  - Qwen-style hybrid SSM needs KV plus SSM companion rederive/hit proof; a KV\n    hit alone is not enough.\n  - ZAYA/CCA and HY3-style models need companion cache and pooling proof.\n  - DeepSeek-V4 CSA/HSA/SWA hybrid pool needs prefix/L2 plus pool restore/hit\n    proof and must not use TurboQuant KV as a substitute.\n- VL/video rows require real media payloads, media cache salts, and cache-hit\n  validation; text-path evidence does not prove media-path correctness.\n- Big-model load cancellation must be live-proven before promotion: if the user\n  stops generation, closes chat, or exits during first load, startup must\n  cancel and cleanup must prevent zombie loads and OOM growth.\n- Qwen/JANG/JANGTQ RAM regressions require end-to-end Osaurus proof with\n  physical footprint, stop status, cache telemetry, token/s, and visible\n  multi-turn output before being called fixed.\n- Memory limits must apply only through documented user/runtime settings and\n  the resolved runtime plan. Do not add hidden RAM percentage blocks or fake\n  load refusals. If a selected setting or true runtime limit prevents a load or\n  context request, fail before unsafe MLX/Metal allocation with a clear typed\n  API/app error that tells the user what setting or resource limit applied.\n- Server settings are part of runtime proof, not a source-only contract. For\n  every claimed model/runtime row, verify the relevant server setting wiring\n  through live Osaurus panel/API state: generation defaults and overrides,\n  reasoning mode, tool mode, memory enablement, prefix cache, paged KV, L2 disk\n  cache, TurboQuant KV when applicable, media/cache settings, concurrency, and\n  memory-safety settings. Toggle the setting, speak to the model, and confirm\n  the runtime behavior, telemetry, and user-visible state changed as intended.\n  If settings conflict or do not compose for a model family, question the\n  compatibility contract, fix the real wiring, or document the row as\n  `PARTIAL`/`BLOCKED` with the exact incompatible setting combination.\n- Treat every implementation change as a cross-function and cross-settings\n  compatibility change until proven otherwise. Trace every shared value from\n  persisted global and per-agent configuration through UI editing, save and\n  relaunch, request/schema composition, runtime admission, execution,\n  telemetry, cancellation, and finalization. Test precedence and composition\n  with adjacent controls (including model defaults, explicit request\n  overrides, reasoning, tools, cache, batching, concurrency, and RAM safety)\n  and remove duplicate, stale, or unwired consumers instead of adding a second\n  source of truth. A direct unit test of the changed function is not sufficient\n  when another consumer or setting can alter the effective behavior.\n- For every touched or behaviorally related user setting, use the real built\n  app to change or toggle it, save it, exercise the affected workflow, and\n  visually inspect the complete result. Relaunch when persistence or\n  next-load-only behavior is part of the contract. Reading a stored value,\n  source default, or test fixture is never a substitute for this live proof.\n- Tool, memory, and cache setting proof must exercise the live user flow after\n  the setting changes. Required tool proof includes exact tool args, tool-result\n  history grounding, a second tool call after history, and no parser/protocol\n  leakage. Memory proof, when the shipped flow exposes memory context or memory\n  toggles, must include multi-turn chat that depends on the memory state. Cache\n  proof must include baseline, changed setting, reload when next-load-only,\n  live chat, `/admin/cache-stats`, and typed incompatibility rather than silent\n  ignore for unsupported combinations.\n- For the active Gemma 4 QAT checkpoint, every OsaurusAI MXFP4 and JANG_4M\n  bundle must prove real Osaurus tool use before harness or benchmark results\n  are treated as meaningful. A row needs load, at least one executed tool with\n  exact name and parseable JSON arguments, tool-result continuation, clean\n  visible text, no protocol/reasoning/tool marker leakage, cache telemetry with\n  paged KV off and disk/L2 behavior recorded, and a scored AgentLoop harness\n  artifact with every failed case attributed. Decent non-perfect scores are\n  acceptable for teammate testing only when the failures are documented; source\n  or BF16 Gemma folders do not count for this QAT checkpoint.\n- Do not spawn recursive local \"agent\" workers, Python subagents, or delegated\n  helper agents for Gemma/Osaurus release work unless the user explicitly asks.\n  Do not use Python or shell wrappers as an orchestration layer to farm work out\n  to Codex, Claude, local LLMs, or other helper agents. Work directly in the\n  current session, keep status artifacts current, and use normal shell, test,\n  build, and proof commands for evidence. Python is allowed for deterministic\n  parsing or proof harnesses, but never to recursively run another agent.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Codex Configuration - osaurus-staging\n\nSee `~/AGENTS.md` for the global Codex environment, wiki protocol, hard rules,\nmachine context, and useful commands.\n\n## Build & Test\n\nRunning tests and builds is encouraged — they're how we keep quality high. The\ncanonical lanes live in `Makefile`:\n\n- `make test` — `swift test --package-path Packages/OsaurusCore` (fast unit\n  loop).\n- `make ci-test` — mirrors the CI `test-core` xcodebuild job (`xcbeautify`\n  output, xcresult bundle at `build/Tests.xcresult`).\n- `make cli` / `make app` — build the CLI and the embedded app via\n  `xcodebuild` against `osaurus.xcworkspace`.\n- `make evals` / `make evals-all` — run OsaurusEvals suites under\n  `Packages/OsaurusEvals/Suites/*`.\n- Live-app smoke: `scripts/live-proof/launch-keychain-free-osaurus.sh`.\n\n### Keychain tip (optional)\n\nSome tests touch Osaurus Keychain wrappers. If a test doesn't need real\nKeychain access, prefer running it in keychain-disabled mode to avoid\nunrelated \"wants to use your confidential information\" prompts:\n\n```bash\nOSAURUS_DISABLE_KEYCHAIN_FOR_TESTS=1 \\\nOSAURUS_TEST_ROOT=/tmp/osaurus-test \\\nOSU_MODELS_DIR=/tmp/osaurus-test-models \\\nmake test\n```\n\nIn that mode, Keychain wrappers should return nil / no-op on reads, writes,\nand deletes rather than calling `SecItemCopyMatching` / `SecItemAdd` /\n`SecItemUpdate` / `SecItemDelete` against the login Keychain.\n\n`OSU_MODELS_DIR` (pointed at an empty dir) matters on machines with real\nmodels in `~/MLXModels`: dispatch-style tests start real `ChatSession.send`\nturns, and without the override they resolve the user's installed models and\ntry to load them inside the SwiftPM harness — which has no Metal kernels and\ndies with `MLX/MLXArray.swift precondition failed`. With the override those\nsends fail fast with `modelUnavailable`, matching CI behavior. Keychain-gated\nsuites (e.g. `PluginAgentScopingTests`) still fail by design under\n`OSAURUS_DISABLE_KEYCHAIN_FOR_TESTS=1`; run those without the flag when you\nneed real Keychain proof.\n\n## Osaurus Release Proof and PR Reporting\n\nFor every change that can affect a runtime, parser, tool call, agent loop,\nsubagent/delegation path, cache, model setting, or user-facing execution\nlifecycle, source inspection and focused unit tests are necessary but never\nsufficient:\n\n- Build a fresh isolated Release development app and exercise the real Chat and\n  Settings UI. Click every control touched by the change, save it, navigate\n  away and back, relaunch when persistence is part of the contract, and prove\n  the effective request/runtime state changed. Inspect the complete turn until\n  reasoning closes, every tool/subagent card settles, Stop disappears, input\n  unlocks, and a follow-up turn completes.\n- During a user-authorized live UI proof, when Osaurus shows its first-use\n  permission popup for a newly exercised tool kind, choose **Always Allow**\n  for that tool in the isolated test agent. Record the granted tool kind and\n  verify the choice survives the intended follow-up/relaunch. This does not\n  authorize unrelated macOS, browser, account, or external-service grants.\n- For batching/delegation specifically, live-test the allowed agent/local/cloud\n  target pool, add/remove/save/relaunch, target notes, permission modes, worker\n  tools, child budgets, per-agent maximum fan-out, Server Continuous Batching,\n  Concurrent Sessions, RAM-safety clamp/refusal, same-model batching,\n  different-model handoff/restore, mixed local/remote fan-out, ordering,\n  cancellation at each lifecycle phase, cache reuse, and parent continuation.\n  A visible control or source-wired value is not proof that it is effective.\n- Run the relevant focused regression suites and the applicable full\n  OsaurusEvals lanes, including AgentLoop and AgentLoopFrontier when agent-loop\n  behavior can change. Add efficient deterministic eval cases for new\n  delegation, batching, parser, completion, cancellation, or cache contracts.\n  If an external judge key is unavailable, preserve the raw artifacts and\n  grade the named rows manually rather than silently omitting them.\n- Every GitHub PR proof/status comment must include the exact tested source SHA,\n  app/vMLX pin, model bundle and generation defaults, suite/eval names, raw\n  scores and denominators, failed-case attribution, and paths or hashes for\n  local evidence. Never post images to the repository. Never report only the\n  favorable model rows or summarize a non-perfect score as passing.\n- Re-run the affected full matrix after rebase, merge-conflict resolution, or\n  any source/config change. If any required source trace, automated score, or\n  live UI row is missing, report `PARTIAL` or `BLOCKED` and do not describe the\n  PR as fixed, proven, release-ready, or regression-free.\n\n## Model Runtime Non-Negotiables\n\n- Never add forced thinking tags, parser repair, hidden sampler defaults,\n  repetition-penalty rescues, close-token bias, or prompt/template coercion to\n  make a model appear coherent.\n- Never add fake guards, placeholder gates, hardcoded model allowlists,\n  synthetic output filters, or \"same behavior\" enforcement to make a runtime\n  row look safe. If JANG, JANGTQ, MXFP, VL/audio/video, hybrid cache, SWA,\n  speed, coherency, leaking tool parser output, reasoning boundaries, or RAM\n  policy is wrong, trace the root cause and fix the real function/path. If the\n  root cause is not fixed yet, document the row as `PARTIAL` or `BLOCKED` with\n  exact evidence instead of forcing behavior in prompts, parsers, samplers, or\n  UI state.\n- Chat/API defaults must come from the active model bundle's\n  `generation_config.json` or equivalent runtime config unless a user\n  explicitly overrides them. Native-trained defaults such as top-k matter for\n  quality and speed; do not replace them with synthetic Osaurus defaults.\n- Reasoning, tool, and chat-template behavior must be auto-detected from the\n  bundle/tokenizer/template/runtime config. Do not fake thinking envelopes,\n  strip visible output to hide parser bugs, or coerce one model family into\n  another family's template.\n- Runtime proof must separate proven, partial, failed, and unproven rows. A\n  load-only result, single prompt, or source-only assertion is not enough to\n  call a model family working.\n- RAM proof means Activity Monitor physical footprint stays within the intended\n  low-RAM gate. A row that reaches full model size in physical footprint is a\n  failure even if generation is coherent.\n- Every generation row must record token/s. Missing token/s is a blocked or\n  failed row, not production proof.\n- Multi-turn coherency is required: visible answer, reasoning channel behavior,\n  no looping, no hidden reasoning-only output, no length-cap fake pass, and no\n  raw parser marker leak.\n- Reasoning fixes must preserve the model's real contract. Do not inject fake\n  closers/openers, hide leaked reasoning markers by stripping visible text, or\n  treat a parser cleanup as correctness unless the live output, structured\n  reasoning field, and user-visible answer all prove the boundary is correct.\n- Cache proof must match the model architecture:\n  - Full-attention models need real KV, prefix/paged, L2 disk, and TurboQuant\n    KV proof when enabled.\n  - Qwen-style hybrid SSM needs KV plus SSM companion rederive/hit proof; a KV\n    hit alone is not enough.\n  - ZAYA/CCA and HY3-style models need companion cache and pooling proof.\n  - DeepSeek-V4 CSA/HSA/SWA hybrid pool needs prefix/L2 plus pool restore/hit\n    proof and must not use TurboQuant KV as a substitute.\n- VL/video rows require real media payloads, media cache salts, and cache-hit\n  validation; text-path evidence does not prove media-path correctness.\n- Big-model load cancellation must be live-proven before promotion: if the user\n  stops generation, closes chat, or exits during first load, startup must\n  cancel and cleanup must prevent zombie loads and OOM growth.\n- Qwen/JANG/JANGTQ RAM regressions require end-to-end Osaurus proof with\n  physical footprint, stop status, cache telemetry, token/s, and visible\n  multi-turn output before being called fixed.\n- Memory limits must apply only through documented user/runtime settings and\n  the resolved runtime plan. Do not add hidden RAM percentage blocks or fake\n  load refusals. If a selected setting or true runtime limit prevents a load or\n  context request, fail before unsafe MLX/Metal allocation with a clear typed\n  API/app error that tells the user what setting or resource limit applied.\n- Server settings are part of runtime proof, not a source-only contract. For\n  every claimed model/runtime row, verify the relevant server setting wiring\n  through live Osaurus panel/API state: generation defaults and overrides,\n  reasoning mode, tool mode, memory enablement, prefix cache, paged KV, L2 disk\n  cache, TurboQuant KV when applicable, media/cache settings, concurrency, and\n  memory-safety settings. Toggle the setting, speak to the model, and confirm\n  the runtime behavior, telemetry, and user-visible state changed as intended.\n  If settings conflict or do not compose for a model family, question the\n  compatibility contract, fix the real wiring, or document the row as\n  `PARTIAL`/`BLOCKED` with the exact incompatible setting combination.\n- Treat every implementation change as a cross-function and cross-settings\n  compatibility change until proven otherwise. Trace every shared value from\n  persisted global and per-agent configuration through UI editing, save and\n  relaunch, request/schema composition, runtime admission, execution,\n  telemetry, cancellation, and finalization. Test precedence and composition\n  with adjacent controls (including model defaults, explicit request\n  overrides, reasoning, tools, cache, batching, concurrency, and RAM safety)\n  and remove duplicate, stale, or unwired consumers instead of adding a second\n  source of truth. A direct unit test of the changed function is not sufficient\n  when another consumer or setting can alter the effective behavior.\n- For every touched or behaviorally related user setting, use the real built\n  app to change or toggle it, save it, exercise the affected workflow, and\n  visually inspect the complete result. Relaunch when persistence or\n  next-load-only behavior is part of the contract. Reading a stored value,\n  source default, or test fixture is never a substitute for this live proof.\n- Tool, memory, and cache setting proof must exercise the live user flow after\n  the setting changes. Required tool proof includes exact tool args, tool-result\n  history grounding, a second tool call after history, and no parser/protocol\n  leakage. Memory proof, when the shipped flow exposes memory context or memory\n  toggles, must include multi-turn chat that depends on the memory state. Cache\n  proof must include baseline, changed setting, reload when next-load-only,\n  live chat, `/admin/cache-stats`, and typed incompatibility rather than silent\n  ignore for unsupported combinations.\n- For the active Gemma 4 QAT checkpoint, every OsaurusAI MXFP4 and JANG_4M\n  bundle must prove real Osaurus tool use before harness or benchmark results\n  are treated as meaningful. A row needs load, at least one executed tool with\n  exact name and parseable JSON arguments, tool-result continuation, clean\n  visible text, no protocol/reasoning/tool marker leakage, cache telemetry with\n  paged KV off and disk/L2 behavior recorded, and a scored AgentLoop harness\n  artifact with every failed case attributed. Decent non-perfect scores are\n  acceptable for teammate testing only when the failures are documented; source\n  or BF16 Gemma folders do not count for this QAT checkpoint.\n- Do not spawn recursive local \"agent\" workers, Python subagents, or delegated\n  helper agents for Gemma/Osaurus release work unless the user explicitly asks.\n  Do not use Python or shell wrappers as an orchestration layer to farm work out\n  to Codex, Claude, local LLMs, or other helper agents. Work directly in the\n  current session, keep status artifacts current, and use normal shell, test,\n  build, and proof commands for evidence. Python is allowed for deterministic\n  parsing or proof harnesses, but never to recursively run another agent.\n","category":"root","tokens":3044}]}