@starci/hfs 4.7.26 → 4.7.28

package/runtime/knowledge/hfs/slots.yaml

@@ -538,6 +538,7 @@ slots:
     profiles: [app]
     exemplifiedBy:
       - packages/hfs/templates/app/ci-workflows-lite/github/workflows/db-deploy.yml
+      - {path: packages/hfs/src/hfs-release-provenance.spec.mjs, edition: full}
     editionWhy: "ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4): lite manages its Supabase database deploy workflow; full owns an optional provider-specific workflow."
     # The database deploy workflow: workflow_dispatch only (like app.ci-e2e); starci app sync renders it under the managed ci group.
     path: ".github/workflows/db-deploy.yml"
@@ -548,7 +549,6 @@ slots:
     liteManagedBy: ci-workflows-lite
     rules: [HFS_MANAGED_FILE_DRIFT]
     since: 2.1.0
-    exampleNa: "owner:no-runtime-specs (2026-10-17): the only example of this slot in an edition was a deleted runtime fixture; the scaffold e2e exercises the scaffolded slot"
   - id: app.ci-stack-deploy
     since: 3.3.0
     profiles: [app]
@@ -687,7 +687,8 @@ slots:
     tier: none
     tests: none
     rules: [HFS_PLAINTEXT_SECRET, HFS_SCRIPT_ONE_OFF, BE_SPEC_PLACEMENT, HFS_REPO_LOCAL_CHECK]
-    exampleNa: "owner:no-runtime-specs (2026-10-17): the only example of this slot in an edition was a deleted runtime fixture; the scaffold e2e exercises the scaffolded slot"
+    exemplifiedBy:
+      - {path: packages/hfs/src/hfs-slot-ownership.spec.mjs, edition: lite}
   - id: app.sides
     since: 3.1.0
     profiles: [app]
@@ -810,6 +811,7 @@ slots:
     profiles: [app]
     exemplifiedBy:
       - packages/hfs/templates/app/skeleton-lite/supabase/
+      - {path: packages/hfs/src/hfs-database-access.spec.mjs, edition: full}
     editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): Supabase is required in lite; full enables it only through a declared connection."
     # The one Supabase project directory, at the app root beside be/, fe/ and .starcistacks (never under a side).
     path: "supabase/"
@@ -820,11 +822,11 @@ slots:
     tier: none
     tests: none
     since: 2.1.0
-    exampleNa: "owner:no-runtime-specs (2026-10-17): the only example of this slot in an edition was a deleted runtime fixture; the scaffold e2e exercises the scaffolded slot"
   - id: app.supabase.config
     profiles: [app]
     exemplifiedBy:
       - packages/hfs/templates/app/skeleton-lite/supabase/config.toml
+      - {path: packages/hfs/src/db-config-policy.spec.mjs, edition: full}
     editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite requires Supabase configuration; full requires it only when Supabase is declared."
     # The project configuration: auth keys are env(NAME) references, never literals (L08 judges its policy keys).
     path: "supabase/config.toml"
@@ -835,11 +837,11 @@ slots:
     tier: none
     tests: none
     since: 2.1.0
-    exampleNa: "owner:no-runtime-specs (2026-10-17): the only example of this slot in an edition was a deleted runtime fixture; the scaffold e2e exercises the scaffolded slot"
   - id: app.supabase.migrations
     profiles: [app]
     exemplifiedBy:
       - packages/hfs/templates/app/skeleton-lite/supabase/migrations/__timestamp___baseline.sql
+      - {path: packages/hfs/src/db-migration-shape.spec.mjs, edition: full}
     editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite uses Supabase schema authority and requires a migration; full opts into that provider."
     # The schema authority of an app on Supabase: forward-only SQL migrations named <timestamp14>_<kebab-name>.sql,
     # one file per change, immutable once on origin/main (L02-L08 judge them).
@@ -852,7 +854,6 @@ slots:
     tier: none
     tests: none
     since: 2.1.0
-    exampleNa: "owner:no-runtime-specs (2026-10-17): the only example of this slot in an edition was a deleted runtime fixture; the scaffold e2e exercises the scaffolded slot"
   - id: app.supabase.migrations.archive
     profiles: [app]
     # The migrations an existing app retired at its cutover (owner ruling 2026-10-13, migration baseline policy): the live schema is
@@ -888,7 +889,8 @@ slots:
     tier: none
     tests: none
     since: 2.1.0
-    exampleNa: "owner:no-runtime-specs (2026-10-17): the only example of this slot in an edition was a deleted runtime fixture; the scaffold e2e exercises the scaffolded slot"
+    exemplifiedBy:
+      - {path: packages/hfs/src/db-types-returned-collector.spec.mjs, edition: full}
   - id: app.supabase.templates
     profiles: [app]
     path: "supabase/templates/*.html"
@@ -1025,7 +1027,8 @@ slots:
     tests: none
     coverage: none
     rules: [HFS_UNUSED_SYMBOL]
-    exampleNa: "owner:no-runtime-specs (2026-10-17): the only example of this slot in an edition was a deleted runtime fixture; the scaffold e2e exercises the scaffolded slot"
+    exemplifiedBy:
+      - {path: packages/hfs/src/hfs-unused-symbol-ledger.spec.mjs, editions: [lite, full]}
   - id: repo.packages
     since: 3.1.0
     profiles: [be, fe]
@@ -1183,8 +1186,9 @@ slots:
     tests: none
     coverage: none
     why: the MCP tool catalog an app's MCP server publishes at one contract major (`<server>@<major>`), the `tools/list` result its clients rely on, committed as a cross-repo interface; the canon emits no MCP catalog, so its shape is judged (R302 HFS_MCP_TOOLS_SNAPSHOT)
-    exampleNa: "owner:mcp-tools-snapshot-no-example (2026-10-21): no example app serves an MCP server; the package spec judges the shape"
     rules: [HFS_MCP_TOOLS_SNAPSHOT]
+    exemplifiedBy:
+      - {path: packages/hfs/src/mcp-tools-snapshot.spec.mjs, editions: [lite, full]}
 
   # ----- BE: apps (one slot per app kind; a new kind = a new slot, minor bump) ---------------------------
   # The files of every app (owner ruling 2026-10-14, R245 and R246, since 3.1.0), each with a line budget that
@@ -1449,7 +1453,8 @@ slots:
     coverage: none
     rules: [BE_KIND_ISOLATION, BE_FEATURE_IMPORTS_FEATURE, BE_FEATURE_NOT_COMPOSED]
     since: 1.0.0
-    exampleNa: "owner:no-runtime-specs (2026-10-17): the only example of this slot in an edition was a deleted runtime fixture; the scaffold e2e exercises the scaffolded slot"
+    exemplifiedBy:
+      - {path: packages/hfs/src/hfs-stacks-swarm.spec.mjs, edition: lite}
   - id: be.feature.realtime.graphql
     profiles: [be]
     editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite uses only the in-process socket.io gateway; the GraphQL subscription door remains full-only."
@@ -1653,7 +1658,8 @@ slots:
     coverage: required
     budget: {indexExports: 60}
     rules: [BE_TIER_DIRECTION, ARCH_OWNER_CYCLE, BE_MODULE_SHAPE, BE_INFRA_OWNER]
-    exampleNa: "owner:no-runtime-specs (2026-10-17): the only example of this slot in an edition was a deleted runtime fixture; the scaffold e2e exercises the scaffolded slot"
+    exemplifiedBy:
+      - {path: packages/eslint/be/webhook-handoff-inbox.spec.mjs, edition: lite}
   - id: be.platform.queue
     since: 3.1.0
     profiles: [be]
@@ -1792,7 +1798,8 @@ slots:
     tests: unit-beside            # a measured slot: <name>.projection.spec.ts beside its projection is legal (the file owes 100 per file; a spec of its own is optional)
     coverage: required
     rules: [BE_PROJECTION_WRITE_OWNER, BE_PROJECTION_SHAPE, BE_TIER_DIRECTION, BE_CONTEXT_COUPLING]
-    exampleNa: "owner:no-runtime-specs (2026-10-17): the only example of this slot in an edition was a deleted runtime fixture; the scaffold e2e exercises the scaffolded slot"
+    exemplifiedBy:
+      - {path: packages/eslint/be/jobs-projections-coverage.spec.mjs, edition: lite}
   - id: be.integrations
     since: 3.1.0
     profiles: [be]
@@ -1822,6 +1829,7 @@ slots:
     profiles: [be]
     exemplifiedBy:
       - packages/hfs/templates/be/skeleton-lite/src/modules/integrations/supabase/
+      - {path: packages/hfs/src/be-supabase-jwt-verified.spec.mjs, edition: full}
     editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite requires the Supabase Auth and Storage integration; full opts in through a connection."
     # The only be import of @supabase/* (L10): the Auth admin and Storage admin client, plus the JWKS-based verification of
     # the Supabase access token the guard chain reads (L16). The connection itself is ordinary Postgres (the shared
@@ -1839,7 +1847,6 @@ slots:
     rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT]
     coverage: required
     since: 2.1.0
-    exampleNa: "owner:no-runtime-specs (2026-10-17): the only example of this slot in an edition was a deleted runtime fixture; the scaffold e2e exercises the scaffolded slot"
 
   # ----- BE: tests (owner test layout 2026-09-30). Unit specs are <name>.service.spec.ts beside their service and nothing else; everything else
   # lives under src/tests/, one folder per kind, and the folder and the file suffix always agree (a file whose suffix does
@@ -1872,7 +1879,6 @@ slots:
       overridden in the DI container. It is the only test location that may import typeorm's DataSource or testcontainers,
       call migrate/runMigrations/synchronize, or write process.env.
     rules: [BE_TEST_TOPOLOGY, BE_TEST_CONSTRAINTS_ON]
-    exampleNa: "owner:no-runtime-specs (2026-10-17): the only example of this slot in an edition was a deleted runtime fixture; the scaffold e2e exercises the scaffolded slot"
 
   - id: be.tests.world.kit
     since: 3.1.0
@@ -2269,7 +2275,8 @@ slots:
     tests: none
     why: the canonical GraphQL client output of codegen is local and never committed; this specific slot overrides the tracked API parent
     rules: [FE_WIRE_GENERATED]
-    exampleNa: "owner:no-runtime-specs (2026-10-17): the only example of this slot in an edition was a deleted runtime fixture; the scaffold e2e exercises the scaffolded slot"
+    exemplifiedBy:
+      - {path: packages/eslint/fe/r52-wire-generated.spec.mjs, editions: [lite, full]}
   - id: fe.transport.client
     since: 3.1.0
     profiles: [fe]

package/runtime/modules/kernel/failure-codes.yaml

@@ -3044,6 +3044,16 @@ HFS_AUDIT_STEP_MISSING:
   owner: op-retry
   kind: check-finding
 
+HFS_BYPASS_MARKER:
+  title: "A product repository holds no bypass of a check"
+  title_vi: "Kho có đoạn bỏ qua một bước kiểm tra"
+  meaning_vi: "Kho có đoạn làm cho một bước kiểm tra qua mà không thỏa nó ở `<f>`: chú thích tắt luật (eslint, stylelint, prettier, biome), `ts-ignore`/`ts-expect-error`/`ts-nocheck`, `NOSONAR`, bỏ qua độ phủ istanbul/c8/v8, bài test bị bỏ qua hoặc chỉ chạy riêng, hoặc lỗi bị nuốt trong hook, script hay workflow (`|| true`, `continue-on-error`, `set +e`, `HUSKY=0`, `--no-verify`, `fail_ci_if_error: false`)."
+  causes_vi:
+    - "Vi phạm luật R303: một lần bỏ qua kiểm tra luôn là lỗi (phán quyết của chủ sở hữu loosening-always-red); kiểm tra được thỏa bằng cách sửa nguyên nhân, không phải bỏ qua. Giao diện (FE) không có test nhưng mã nguồn vẫn bị soát các chú thích tắt luật."
+  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra: xóa đoạn bỏ qua và sửa nguyên nhân thật (mã, kiểu dữ liệu, test, bước chạy)."
+  owner: op-retry
+  kind: check-finding
+
 HFS_CANON_COPY_DRIFT:
   title: "A hash-sensitive canon file differs from its template"
   title_vi: "Tệp canon nhạy hash lệch khỏi template"

package/runtime/packages/cli/src/catalog.generated.mjs

@@ -1,7 +1,7 @@
 // GENERATED by scripts/cli/gen-catalog.mjs — do not edit
 export const CATALOG = {
   "schema": "starci/cli-catalog@1",
-  "hash": "5bec1a5a568a8294dd40e3e09b7b97693660b8a7c273fcd35594aea87196257a",
+  "hash": "466ffd40fe4a003c976ac306bcb14639b1b57c947112e7899ef717a819e571f5",
   "global": [
     {
       "name": "json",
@@ -1248,7 +1248,7 @@ export const CATALOG = {
             "requireCi true: push --execute sends HEAD to refs/heads/release/candidate-<version> first and waits for its ci.yml run",
             "green moves the branch and the tag in one atomic push; red refuses RELEASE_CANDIDATE_CI_RED naming the failing jobs",
             "no run, or no end in time, refuses RELEASE_CANDIDATE_CI_TIMEOUT; unreadable GitHub refuses RELEASE_CI_UNKNOWN; nothing reaches the branch",
-            "only the owner's starci release ci-override --sha <sha> --reason <text> record lets a red candidate through; there is no --no-ci-check flag",
+            "a red candidate never passes: there is no override and no --no-ci-check flag",
             "gate refuses a dirty tree, HEAD other than --source, a moved HEAD and a tree dirtied by the gates; record and tag only when all gates are green",
             "a gate with summary jest is red on failed tests and on a coverage threshold miss even when the process exits 0",
             "push needs the annotated tag and L4 record of HEAD, runs git push --dry-run --atomic first and never uses --no-verify"
@@ -8466,56 +8466,6 @@ export const CATALOG = {
           },
           "runtimeSide": "tree"
         },
-        "ci-override": {
-          "summary": "the owner accepts a red candidate CI for one SHA (emergency path) and records who and why",
-          "owner": "runtime",
-          "flags": [
-            {
-              "name": "sha",
-              "type": "string",
-              "summary": "required full 40 lowercase hex SHA of the red CI run"
-            },
-            {
-              "name": "reason",
-              "type": "string",
-              "summary": "required nonempty owner reason, recorded verbatim after trimming"
-            },
-            {
-              "name": "repo",
-              "type": "string",
-              "summary": "repository receiving the override (default current directory)"
-            }
-          ],
-          "exit": {
-            "0": "the override record and runtime owner ruling were written",
-            "2": "RIGHTS_OWNER_ONLY (a bound role or non-TTY stdin), bad usage, confirmation mismatch, or write failure"
-          },
-          "json": "none",
-          "examples": [
-            "starci release ci-override --sha 0123456789abcdef0123456789abcdef01234567 --reason \"Owner accepts this CI failure for the release\"",
-            "starci release ci-override --repo ../my-app --sha 0123456789abcdef0123456789abcdef01234567 --reason \"Owner accepts the failed run\""
-          ],
-          "editions": [
-            "full"
-          ],
-          "impl": {
-            "script": "scripts/supervisor/release-ci-override-cli.mjs"
-          },
-          "conventions": [
-            "OWNER RULING candidate-ci (2026-10-18): a release reaches main only when the candidate CI of its own sha is green;",
-            "this verb is the one documented EMERGENCY path for a red candidate.",
-            "The override is owner-only, records who and why, and agents cannot run it (OWNER RULING alpha20-ci-override-owner-only).",
-            "Every bound role is refused by the command guard and by this script. The owner must use a terminal and type the first 12 SHA characters exactly.",
-            "Writes <git-common-dir>/starci-release/<sha>.ci-override.json, schema starci/ci-override@1,",
-            "with sha, reason, by (git user.name and OS user), at, and runUrl (empty if GitHub is unavailable).",
-            "release cut and app release push read that record for the exact candidate sha only; the release record logs its use.",
-            "For the runtime it also appends ci-override-<sha12> under rulings in modules/kernel/owner-rulings.yaml as the audit trail.",
-            "App repositories receive only the record.",
-            "An override applies only to its exact SHA. It never permits a release whose CI is unknown or timed out.",
-            "Existing ruling IDs with another reason refuse."
-          ],
-          "runtimeSide": "tree"
-        },
         "ci-status": {
           "summary": "the verdict of the GitHub ci workflow, Codecov and Sonar for a release; red is recorded for Debug",
           "owner": "runtime",
@@ -8662,8 +8612,7 @@ export const CATALOG = {
             "No run within the grace, or no end within the wait, refuses RELEASE_CANDIDATE_CI_TIMEOUT.",
             "A red candidate keeps its ref for diagnosis; after a cut the candidate ref is left on the remote, naming the released sha.",
             "Only on green is the annotated tag created and main plus the tag pushed atomically; the release record logs the candidate verdict.",
-            "Emergency path, owner-only: starci release ci-override --sha <HEAD> --reason <text> lets a red candidate through.",
-            "The release record logs its use."
+            "There is no override: a red candidate never passes."
           ],
           "runtimeSide": "tree"
         },
@@ -8986,6 +8935,133 @@ export const CATALOG = {
       "summary": "resolve runtime operations from structured routing inputs",
       "owner": "runtime",
       "verbs": {
+        "model": {
+          "summary": "resolve which tier members may take a workload from the declarative model-selection rules",
+          "owner": "runtime",
+          "flags": [
+            {
+              "name": "kind",
+              "type": "string",
+              "summary": "operation kind the workload runs"
+            },
+            {
+              "name": "role",
+              "type": "enum",
+              "enum": [
+                "implement",
+                "verify",
+                "decide",
+                "plan",
+                "write"
+              ],
+              "summary": "role of the workload (default is the role of the kind in kinds.yaml)"
+            },
+            {
+              "name": "domain",
+              "type": "string",
+              "summary": "domain of the workload"
+            },
+            {
+              "name": "risk",
+              "type": "enum",
+              "enum": [
+                "low",
+                "medium",
+                "high",
+                "critical"
+              ],
+              "summary": "risk of the workload"
+            },
+            {
+              "name": "floor",
+              "type": "enum",
+              "enum": [
+                "probation",
+                "standard",
+                "high",
+                "critical"
+              ],
+              "summary": "lowest qualification a pick may carry"
+            },
+            {
+              "name": "tools",
+              "type": "list",
+              "summary": "tool the workload needs; comma list or repeatable"
+            },
+            {
+              "name": "context-tokens",
+              "type": "string",
+              "summary": "context size in tokens the workload needs"
+            },
+            {
+              "name": "external",
+              "type": "boolean",
+              "summary": "the workload has external effects and probation is forbidden"
+            },
+            {
+              "name": "unapproved",
+              "type": "boolean",
+              "summary": "the workflow is not approved and probation is forbidden"
+            },
+            {
+              "name": "no-review",
+              "type": "boolean",
+              "summary": "no fresh independent review is planned"
+            },
+            {
+              "name": "no-checks",
+              "type": "boolean",
+              "summary": "the op declares no machine checks"
+            },
+            {
+              "name": "difficulty",
+              "type": "enum",
+              "enum": [
+                "easy",
+                "medium",
+                "hard",
+                "insane"
+              ],
+              "summary": "measured difficulty (default medium, required with --plan)"
+            },
+            {
+              "name": "plan",
+              "type": "boolean",
+              "summary": "what-if view that walks the tier chain and annotates missing or stale qualification evidence instead of refusing"
+            },
+            {
+              "name": "repo",
+              "type": "string",
+              "summary": "repository whose ledger provider-health circuit marks a model unavailable"
+            },
+            {
+              "name": "models-dir",
+              "type": "string",
+              "summary": "models directory (default is modules/models)"
+            },
+            {
+              "name": "verbose",
+              "type": "boolean",
+              "summary": "print the per-candidate rejection reasons"
+            }
+          ],
+          "exit": {
+            "0": "a member is picked",
+            "1": "no eligible model",
+            "2": "bad usage"
+          },
+          "json": "flag",
+          "examples": [
+            "starci route model --kind interface.draw --plan --json"
+          ],
+          "editions": [
+            "full"
+          ],
+          "impl": {
+            "script": "scripts/route/route-model.mjs"
+          },
+          "runtimeSide": "host"
+        },
         "op": {
           "summary": "resolve the operation that serves a structured routing request",
           "owner": "runtime",

package/runtime/scripts/api/git/check-ignore.mjs

@@ -0,0 +1,5 @@
+// check-ignore.mjs — `git check-ignore <args>`: whether paths are ignored (-q exits 0 for an ignored path).
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git check-ignore ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const checkIgnore = (args = [], options = {}) => runGit(['check-ignore', ...args], options);

package/runtime/scripts/gates/runtime-host.mjs

@@ -0,0 +1,83 @@
+// runtime-host.mjs - the repository that hosts this runtime and how a stack declaration's `repository` names resolve on
+// this machine. One home for scripts/gates/starcistacks.mjs (the services contract) and scripts/gates/sonar-local.mjs
+// (the Sonar helper), so both read a declaration's `{repository, path}` the same way.
+//
+// The runtime host is the repository whose checkout holds the runtime's MAIN checkout (`<host>/.claude`), found from git
+// identity, never from the folder this runtime tree happens to sit in: a lane worktree of the runtime
+// (<lanes root>/<lane>/<name>) resolves to the same host as the main checkout. STARCI_SOURCE_ROOT overrides it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { skillRoot, starciSourceRoot } from '../../engine/runtime-root.mjs';
+import { isDir } from '../lib/fs-kind.mjs';
+import { repositoryHome, repositoryName } from '../hfs/repo-identity.mjs';
+import { secretEnv } from '../../engine/secrets.mjs';
+import { revParseQuery } from '../api/git/rev-parse-query.mjs';
+import { gitOutputOf } from '../lib/git.mjs';
+
+/** The repository hosting this runtime: STARCI_SOURCE_ROOT, else the folder holding the runtime's main checkout. */
+export function runtimeHostRoot(env = process.env) {
+  if (env.STARCI_SOURCE_ROOT) return starciSourceRoot(env);
+  return path.dirname(repositoryHome(skillRoot));
+}
+
+/** The canonical runtime main root of a runtime checkout or lane (its secret.env lives there); throws when the root is not a verified Git top level. */
+export function verifiedRuntimeMain(runtimeRoot, env) {
+  if (typeof runtimeRoot !== 'string' || !path.isAbsolute(runtimeRoot))
+    throw new TypeError('runtimeSecretEnv requires an absolute runtime root');
+  const stat = fs.lstatSync(runtimeRoot);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('runtime root must be a regular directory');
+  const root = fs.realpathSync.native(runtimeRoot), marker = path.join(root, '.git');
+  let gitMarker;
+  try { gitMarker = fs.lstatSync(marker); } catch (error) {
+    if (error?.code === 'ENOENT') return root;
+    throw error;
+  }
+  if (gitMarker.isSymbolicLink() || (!gitMarker.isFile() && !gitMarker.isDirectory()))
+    throw new Error('runtime Git identity is unavailable');
+  const topLevel = cwd => fs.realpathSync.native(path.resolve(cwd,
+    gitOutputOf(revParseQuery(['--show-toplevel'], { cwd, env })).trim()));
+  if (!same(topLevel(root), root)) throw new Error('runtime must be its Git top level');
+  const main = fs.realpathSync.native(repositoryHome(root)), mainMarker = fs.lstatSync(path.join(main, '.git'));
+  if (!mainMarker.isDirectory() || mainMarker.isSymbolicLink() || !same(topLevel(main), main))
+    throw new Error('runtime main Git identity is unavailable');
+  return main;
+}
+
+/**
+ * Load host-local credentials from this runtime's verified main tree, or its installed physical tree.
+ * A lane never reads its own alternate file. The actual environment wins; no process state is mutated.
+ */
+export function runtimeSecretEnv(env = process.env, runtimeRoot = skillRoot) {
+  return secretEnv(verifiedRuntimeMain(runtimeRoot, env), env);
+}
+
+const same = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
+
+/**
+ * The checkout of the repository a declaration names: the declaring repository itself, the runtime host, or a sibling
+ * checkout of either (by repository identity, so a worktree and its main checkout are one repository). Null when the
+ * repository is not checked out on this machine.
+ */
+export function resolveDeclaredRepository(name, { fromRepo } = {}) {
+  const wanted = typeof name === 'string' && name.trim() ? name.trim() : null;
+  if (!wanted) return null;
+  const candidates = [...(fromRepo ? [path.resolve(fromRepo)] : []), runtimeHostRoot()];
+  for (const dir of candidates) if (same(repositoryName(dir), wanted) && isDir(dir)) return dir;
+  for (const dir of candidates) {
+    const sibling = path.join(path.dirname(repositoryHome(dir)), wanted);
+    if (isDir(sibling)) return sibling;
+  }
+  return null;
+}
+
+/**
+ * A custody path of a declared repository as a file on this machine. A path under `.claude/` of the runtime host is a member of
+ * the runtime tree in use (this checkout, a lane worktree included), the same rule a host-owned stack root `.claude/ext/<service>`
+ * follows; any other path is joined to the repository's checkout. A path with a `..` segment is refused (null).
+ */
+export function resolveCustodyFile(repo, rel) {
+  if (!repo || !rel || String(rel).split(/[\\/]/).includes('..')) return null;
+  const posix = String(rel).replaceAll('\\', '/');
+  if (posix.startsWith('.claude/') && same(path.resolve(repo), path.resolve(runtimeHostRoot()))) return path.join(skillRoot, posix.slice('.claude/'.length));
+  return path.join(repo, rel);
+}