diff --git a/docs/pregate.md b/docs/pregate.md
index cfad85a34..58314a53d 100644
--- a/docs/pregate.md
+++ b/docs/pregate.md
@@ -65,7 +65,7 @@ the byte-pinned `/ship` renders in `test/fixtures/golden/`).
| `selection` | `workflow.yml/job` → a command printing the lane's file list, for matrices a planner computes (gstack: `scripts/test-free-shards.ts --list`) |
| `warn` | check ids downgraded to warn; `secrets` and required lanes never |
| `strays.allow` | intentional root files or new top-level directories |
-| `local` | `workflow.yml/job` lanes a local run satisfies: a platform-agnostic toolchain (an `ubuntu-latest` suite that runs the same on a Mac), or a repo whose CI is off. Their tests run here instead of becoming `requires-remote`, except that on a machine under 8 cores with a `remote_gate` or a remote `test_backend` the small-machine rule still records the test tier as a `requires-remote` obligation. `--explain` notes an id that matches no platform lane |
+| `local` | `workflow.yml/job` lanes a local run satisfies: a platform-agnostic toolchain (an `ubuntu-latest` suite that runs the same on a Mac), or a repo whose CI is off. Their tests run here instead of becoming `requires-remote`, except that on a machine under 8 cores with a `remote_gate` or a remote `test_backend` the small-machine rule still records the test tier as a `requires-remote` obligation. `--explain` notes an id that matches no workflow lane |
| `guards` | `[{ id, when: [globs], command, fix?, timeout_s? }]`: repo commands a lane must pass when a touched file matches `when` (manifest checks, subprocess goldens the import graph cannot see); see [guards](#guards) |
| `serial_patterns` | test-file globs the `lanes` check runs one process per file, apart from the unit files (default `**/*.serial.test.*`) |
| `sealed` | sealed or eval output that must never reach a public destination; read by the pre-push hook and `gstack-pregate sealed` (see [sealed output](#sealed)) |
@@ -77,8 +77,8 @@ Only the `origin/` copy or the user-owned file below is honoured, so a
downgrade is reviewed (or is the user's own) before it takes effect. A repo that
keeps `.gstack/` out of git (a shared repo where gstack is one contributor's
tool) can hold the same file at `/projects//pregate.json`. The
-state root is `GSTACK_STATE_ROOT`, else `GSTACK_HOME`, else `~/.gstack` (full
-chain in [docs/state-root.md](state-root.md)); `` is what
+state root is `GSTACK_STATE_ROOT`, else `GSTACK_HOME`, else `GSTACK_STATE_DIR`,
+else a gstack plugin's data directory, else `~/.gstack` ([docs/state-root.md](state-root.md)); `` is what
`~/.claude/skills/gstack/bin/gstack-slug` prints as `SLUG=` in the repository
(`GSTACK_PROJECT_SLUG` overrides it). It is read only when the base carries none
(never under `--policy-from head`), it lives outside the repository so a PR still
diff --git a/lib/pregate/config.ts b/lib/pregate/config.ts
index 0fc24b78c..e3348f252 100644
--- a/lib/pregate/config.ts
+++ b/lib/pregate/config.ts
@@ -277,6 +277,6 @@ export function explainConfig(): string {
'price_file: repo-relative path of the GSTACK_EVAL_CALLS v1 call-plan file `gstack-eval-plan price-gate` prices a paid gate from; never executed (docs/eval-calls.md)',
'stall_timeout_s: seconds without test output before the lanes check kills the runner\'s process group and records it incomplete (default 300; 0 disables; --stall-timeout overrides)',
'remote_gate: the repo\'s remote test gate command; under 8 cores the test tier becomes a requires-remote obligation naming it, and gstack-pregate --remote runs it (it must print PREGATE_REMOTE: tree= tests= failed=) (docs/pregate.md#remote-gate)',
- 'no .gstack/pregate.json on the base: /projects//pregate.json is read instead (state root: GSTACK_STATE_ROOT, else GSTACK_HOME, else ~/.gstack; outside the repo, so a PR cannot reach it; a path inside the checkout is ignored)',
+ 'no .gstack/pregate.json on the base: /projects//pregate.json is read instead (state root: GSTACK_STATE_ROOT, else GSTACK_HOME, else GSTACK_STATE_DIR, else a gstack plugin data dir, else ~/.gstack, per docs/state-root.md; run --explain prints the resolved path; outside the repo, so a PR cannot reach it; a path inside the checkout is ignored)',
].join('\n') + '\n';
}
diff --git a/lib/pregate/context.ts b/lib/pregate/context.ts
index db8d48e1a..480d00b8b 100644
--- a/lib/pregate/context.ts
+++ b/lib/pregate/context.ts
@@ -106,13 +106,13 @@ export function touchedFiles(repoRoot: string, mergeBase: string): TouchedFile[]
return [...out.values()].filter(t => t.path !== 'node_modules' && !t.path.startsWith('node_modules/')).sort((a, b) => a.path.localeCompare(b.path));
}
-/** The deepest existing ancestor realpathed, the rest re-joined: a symlinked state root inside the checkout still counts as inside. */
+/** The deepest existing ancestor realpathed (on-disk casing), the rest re-joined: a symlinked state root inside the checkout still counts as inside. */
function realish(p: string): string {
let head = path.resolve(p); const tail: string[] = [];
while (!fs.existsSync(head) && path.dirname(head) !== head) { tail.unshift(path.basename(head)); head = path.dirname(head); }
- try { return path.join(fs.realpathSync(head), ...tail); } catch { return path.resolve(p); }
+ try { return path.join(fs.realpathSync.native(head), ...tail); } catch { return path.resolve(p); }
}
-const within = (root: string, p: string) => { const rel = path.relative(root, p); return !rel.startsWith('..') && !path.isAbsolute(rel); };
+const within = (root: string, p: string) => { const rel = path.relative(root, p); return rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel); };
/** Why a user policy path must not be read, or null: a relative path (no HOME) or one a PR could commit is never trusted. */
export function userConfigRejection(repoRoot: string, file: string): string | null {
@@ -149,7 +149,7 @@ export function buildContext(o: BuildContextOptions): ContextLoad {
const config = configLoad.config as PregateConfig;
const lanes = discoverLanes(o.repoRoot, platform);
// A lane that exists but is not platform-tier on this host already runs here, so only an unknown id is worth a line.
- for (const id of config.local) if (!lanes.some(l => l.id === id)) explain.push(`local: ${id} matches no platform lane; ignored`);
+ for (const id of config.local) if (!lanes.some(l => l.id === id)) explain.push(`local: ${id} matches no workflow lane; ignored`);
return {
ctx: {
repoRoot: o.repoRoot, base, baseRef, baseSha: baseSha.out, mergeBase, head, wtree, touched: touchedFiles(o.repoRoot, mergeBase),
diff --git a/test/pregate-user-policy.test.ts b/test/pregate-user-policy.test.ts
index f969c2b0a..461cd88c4 100644
--- a/test/pregate-user-policy.test.ts
+++ b/test/pregate-user-policy.test.ts
@@ -8,10 +8,11 @@
*/
import { afterEach, describe, expect, test } from 'bun:test';
import * as fs from 'node:fs';
+import * as os from 'node:os';
import * as path from 'node:path';
import { EXIT } from '../lib/headless-artifacts';
import { loadConfigFromUser, validateConfig } from '../lib/pregate/config';
-import { buildContext, sha256 } from '../lib/pregate/context';
+import { buildContext, sha256, userConfigRejection } from '../lib/pregate/context';
import { runPregate } from '../lib/pregate/index';
import { BASE_PREGATE, cleanup, commit, makeFixtureRepo, runBin, type FixtureRepo } from './helpers/pregate-fixture';
@@ -216,7 +217,7 @@ describe('gstack-pregate with a user-owned policy', () => {
// Value: protects=a user path inside the checkout (GSTACK_HOME under the repo, or a relative state root when HOME is unset) is
// never read, so a PR cannot commit its own "user" policy; fails_when=userConfigRejection is dropped and the in-repo file
// becomes the policy; why_new=the trust check is new; seam=none (userConfigPath is an existing buildContext option);
- // no_claim=a symlinked state root (realish covers it, untested here)
+ // no_claim=a symlinked state root (the next test)
test('a user path inside the repository or relative is ignored, with an explain line', () => {
const { repo } = setup();
const inside = path.join(repo.work, '.gstack', 'projects', 'x', 'pregate.json');
@@ -230,15 +231,31 @@ describe('gstack-pregate with a user-owned policy', () => {
}
}, 60_000);
- // Value: protects=--explain says when the user file was looked for and absent, and names a `local` id that matches no platform lane;
+ // Value: protects=the containment check sees through a symlinked state root and does not mistake an in-repo `..name`
+ // directory for a parent; fails_when=the realpath half or the `..`-segment test regresses and a file a PR committed is read
+ // as the user policy; why_new=both edges are new; seam=none; no_claim=case-only path differences (realpathSync.native)
+ test('a state root symlinked into the checkout, or under an in-repo ..name directory, is inside', () => {
+ const { repo } = setup();
+ fs.mkdirSync(path.join(repo.work, '.st'));
+ const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'pregate-sr-'));
+ try {
+ const link = path.join(outside, 'root');
+ fs.symlinkSync(path.join(repo.work, '.st'), link);
+ expect(userConfigRejection(repo.work, path.join(link, 'projects', 'x', 'pregate.json'))).toContain('inside the repository');
+ expect(userConfigRejection(repo.work, path.join(repo.work, '..st', 'projects', 'x', 'pregate.json'))).toContain('inside the repository');
+ expect(userConfigRejection(repo.work, path.join(outside, 'projects', 'x', 'pregate.json'))).toBeNull();
+ } finally { fs.rmSync(outside, { recursive: true, force: true }); }
+ });
+
+ // Value: protects=--explain says when the user file was looked for and absent, and names a `local` id that matches no workflow lane;
// fails_when=either line is dropped and a typo'd slug or lane id silently does nothing; why_new=both lines are new; seam=none;
// no_claim=the line wording beyond its path and id
- test('--explain names an absent user file and a local id that matches no platform lane', () => {
+ test('--explain names an absent user file and a local id that matches no workflow lane', () => {
const { userPolicy, run } = setup();
expect(run(['--explain']).out).toContain(`user policy: ${userPolicy} (absent)`);
writePolicy(userPolicy, { local: [...LOCAL_ALL, 'ci.yml/nope'] });
const r = run(['--explain']);
- expect(r.out).toContain('local: ci.yml/nope matches no platform lane; ignored');
+ expect(r.out).toContain('local: ci.yml/nope matches no workflow lane; ignored');
expect(r.out).not.toContain('local: free-tests.yml/unit matches');
}, 60_000);