@appforge-ci/core 0.2.3 → 0.3.1

package/dist/agent-readiness.d.ts

@@ -98,6 +98,183 @@ export declare function agentFitsPlatform(readiness: AgentReadiness, platform: P
  * getting bound somewhere it can't actually run.
  */
 export declare function agentCanBuildPlatform(agent: Parameters<typeof computeAgentReadiness>[0], platform: Platform, now?: Date): boolean;
+/**
+ * Build-isolation level an agent reports (`Agent.enforcementLevel`,
+ * migrations/0043). Ordered: a higher level satisfies a lower requirement.
+ *  - `none`         no kernel-enforced isolation of build processes (today).
+ *  - `sandbox`      builds run under a kernel sandbox profile (Seatbelt).
+ *  - `sandbox_uid`  ... and as a dedicated unprivileged user.
+ * Anything unrecognised ranks as `none`: an unknown level never satisfies a
+ * requirement (fail closed).
+ */
+export declare const ENFORCEMENT_LEVELS: readonly ["none", "sandbox", "sandbox_uid"];
+export type EnforcementLevel = (typeof ENFORCEMENT_LEVELS)[number];
+export declare function parseEnforcementLevel(raw: unknown): EnforcementLevel;
+/** 0 (`none`) .. 2 (`sandbox_uid`); unknown input is 0. */
+export declare function enforcementLevelRank(level: unknown): number;
+/** What a feature id may look like (`Agent.vpnFeatures` entries, tunnel
+ *  `requires` entries): lowercase, short, no whitespace or separators that
+ *  could be abused in a log line or SQL JSON. Ids carry their own version
+ *  suffix (`ssh-v1`) so a breaking change is a NEW id, never a redefinition. */
+export declare const VPN_FEATURE_ID_PATTERN: RegExp;
+/** An agent reports at most this many features; the rest are dropped. */
+export declare const MAX_VPN_FEATURES = 32;
+/**
+ * Feature ids the regulated-VPN program will introduce. Informational: the
+ * scheduler's superset check works on whatever ids a tunnel requires and an
+ * agent reports, so a new id needs no change here. Only `egress-policy-v1` is
+ * required (by a strict-egress tunnel) and reported (by an agent with a new
+ * enough verified helper) so far; the others land in later PRs.
+ */
+export declare const KNOWN_VPN_FEATURES: readonly ["egress-policy-v1", "ssh-v1", "sandbox-v1", "evidence-v1"];
+/** Prefix of a requirement token that asks for a minimum enforcement level
+ *  (`enforcement:sandbox`) rather than a feature id. */
+export declare const ENFORCEMENT_REQUIREMENT_PREFIX = "enforcement:";
+/**
+ * The canonical form of a reported feature list: only well-formed ids,
+ * de-duplicated, sorted, capped at `MAX_VPN_FEATURES`. Anything else is
+ * dropped, never repaired. This is the ONLY form stored in
+ * `Agent.vpnFeatures`, so the scheduler's SQL superset check can compare
+ * strings exactly.
+ */
+export declare function canonicalVpnFeatures(input: readonly unknown[] | null | undefined): string[];
+/** Parses the `Agent.vpnFeatures` JSON column. Malformed, non-array or null
+ *  input is `[]` (no features), never an exception. */
+export declare function parseVpnFeatures(raw: string | null | undefined): string[];
+/** What a tunnel needs from the Mac that serves its builds. */
+export interface VpnRequirements {
+    /** Feature ids the agent must report (a superset check). */
+    features: readonly string[];
+    /** Minimum `enforcementLevel`. */
+    minEnforcementLevel: EnforcementLevel;
+}
+export declare const NO_VPN_REQUIREMENTS: VpnRequirements;
+/** The feature id of the strict egress policy: the helper enforces a job's
+ *  `egress` allow-list and echoes its hash, and the agent verifies the echo. A
+ *  tunnel with `strictEgress` requires it (see `vpnTunnelRequirements`). */
+export declare const EGRESS_POLICY_FEATURE = "egress-policy-v1";
+/**
+ * The slice of a tunnel `vpnTunnelRequirements` reads: the status, plus the two
+ * settings that make a tunnel demand something of the Mac (migrations/0045).
+ * The columns are required (not optional) so a caller that builds this from a
+ * query cannot forget them: a forgotten setting would silently mean "nothing
+ * required".
+ */
+export interface VpnTunnelRequirementSource {
+    status: "pending" | "ready" | "degraded" | "disabled" | null;
+    /** `VpnTunnel.strictEgress` (0/1). */
+    strictEgress: number | boolean | null;
+    /** `VpnTunnel.complianceMode` ('standard' | 'regulated'). */
+    complianceMode: string | null;
+    /** The build's app uses an ssh git remote (`isSshGitRemote(App.repoUrl)`, vpn-ssh.ts, migrations/0048).
+     *  Required, like the two settings above, so a caller cannot forget it: the clone would then run on a Mac
+     *  that cannot do ssh. Only an exact `true` means "ssh"; the callers compute it from the app row. */
+    sshRepo: boolean;
+}
+/**
+ * What the given tunnel requires of an agent. This is the single place a tunnel
+ * setting makes a requirement; the scheduler, the guarded claim SQL, the lease
+ * response (`job.requires`) and the agent's abort check all consume this one
+ * answer.
+ *
+ *  - `strictEgress`: the Mac must report `egress-policy-v1`, because an agent or
+ *    helper that predates the policy ignores the `egress` block and would run
+ *    the build with no allow-list. Only an exact `0`/`false` means "not strict":
+ *    a missing, null or unrecognised value requires it (fail closed).
+ *  - `complianceMode` other than exactly `standard` (regulated, or a value this
+ *    code does not know): strict egress as above, and at least `sandbox`
+ *    enforcement. No Mac reports a sandbox yet, so a regulated tunnel's builds
+ *    wait for one rather than run unconfined.
+ *
+ *  - `sshRepo` (the app's repository is an ssh remote, PR-G): the Mac must report
+ *    `ssh-v1`, because an agent or helper that predates it cannot clone through
+ *    the tunnel's pinned-host-key ssh path and would ignore the ssh fields.
+ *
+ * A standard-mode tunnel with strict egress off and an https repository requires
+ * nothing, exactly as before, so the server can ship ahead of any agent.
+ */
+export declare function vpnTunnelRequirements(tunnel: VpnTunnelRequirementSource): VpnRequirements;
+/** The wire form of requirements, carried in the lease response as
+ *  `job.requires`: feature ids plus `enforcement:<level>` for a level above
+ *  `none`. An agent aborts a job with any token it cannot satisfy. */
+export declare function vpnRequirementTokens(req: VpnRequirements): string[];
+/**
+ * Which of `tokens` the capabilities do NOT satisfy. A token is satisfied only
+ * if it is a feature id the capabilities list, or `enforcement:<level>` with a
+ * KNOWN level the capabilities reach. An unknown token, an unknown level, or a
+ * non-string entry is unmet: this is what makes the check fail closed against a
+ * requirement introduced by a newer control plane than the agent. A non-array
+ * `tokens` is itself unmet (reported as one entry).
+ *
+ * Used by both the scheduler (`agentSatisfiesVpnRequirements`) and the agent
+ * (before it starts a leased VPN job), so they cannot disagree.
+ */
+export declare function unmetRequirements(tokens: unknown, capabilities: {
+    features: readonly string[];
+    enforcementLevel: unknown;
+}): string[];
+/**
+ * Operator taint (`Agent.dedicatedOrgId`): a Mac dedicated to an org takes only
+ * that org's builds, VPN or not. `null` = shared. An empty string is NOT shared:
+ * only an explicit null is (a mangled value must not widen who may build here).
+ */
+export declare function agentAllowsOrg(dedicatedOrgId: string | null, buildOrgId: string): boolean;
+/**
+ * Where a tunnel's builds may run (`VpnTunnel.hostPolicy`, migrations/0047).
+ *  - `shared`     any approved, VPN-capable Mac, under the exclusive-host lock
+ *                 (today's behaviour, and the default).
+ *  - `pinned`     only Macs the operator pinned to the tunnel (node affinity).
+ *  - `dedicated`  pinned, AND the Mac is dedicated to this org
+ *                 (`Agent.dedicatedOrgId`, so no other org's work is leased to
+ *                 it), AND it reports no co-hosted GitHub Actions runner.
+ * Set only by a platform admin; org admins can read it, never write it.
+ */
+export declare const VPN_HOST_POLICIES: readonly ["shared", "pinned", "dedicated"];
+export type VpnHostPolicy = (typeof VPN_HOST_POLICIES)[number];
+/**
+ * What a customer sees for their tunnel's host policy (read-only; the operator
+ * sets it). Deliberately plain about the limits: "dedicated" is a scheduling
+ * guarantee about which machines AppForge runs this org's VPN builds on, not a
+ * claim of hardware isolation or of any compliance certification.
+ */
+export declare function describeVpnHostPolicy(policy: VpnHostPolicy | string, pinnedHostCount?: number): string;
+/** How long a queued VPN build of a `pinned`/`dedicated` tunnel waits for a ready
+ *  pinned Mac before the control plane's sweep fails it as an infra failure with a
+ *  refund. The wait is measured as CONTINUOUS host unavailability, not build age:
+ *  the sweep records when the tunnel's pinned Macs stopped being ready
+ *  (`VpnTunnelHostWait`) and fails a build only once they have all been unready
+ *  for this long AND the build itself has been queued this long. Any tick that
+ *  finds a ready Mac (busy counts as ready) restarts the clock, so a Mac that is
+ *  briefly away (a reboot or self-update cycle, a short drain) does not fail a
+ *  build that has merely been waiting in line. Longer than the 120 s
+ *  lock-reservation window. The sweep runs every 5 minutes, so the effective
+ *  wait is this plus up to one cron interval. */
+export declare const VPN_HOST_WAIT_SECONDS = 600;
+/** If the sweep's last observation of a tunnel's pinned hosts is older than this
+ *  (three cron ticks), it knows nothing about the gap, so the next "unready"
+ *  observation starts a fresh unavailability stretch instead of extending an old one. */
+export declare const VPN_HOST_OBSERVATION_GAP_SECONDS = 900;
+/**
+ * Parses a stored policy. An UNKNOWN value is `dedicated`, the strictest, not
+ * `shared`: a mangled policy must tighten placement, never loosen it (the
+ * column's CHECK makes this unreachable today; it is here so a future value
+ * read by an older Worker fails closed).
+ */
+export declare function parseVpnHostPolicy(raw: unknown): VpnHostPolicy;
+/**
+ * Whether an agent may serve a VPN build under the tunnel's host policy.
+ *  - `hostPinned` is "this Mac is in the tunnel's pin set".
+ *  - `dedicatedOrgId` is the Mac's operator taint.
+ *  - `coHostedRunner` is what its last (fresh) heartbeat reported: only an
+ *    exact 0 means "no GitHub Actions runner on the machine". 1, null
+ *    (unreported) and anything else all refuse for `dedicated`.
+ * `shared` always passes (and is the only case that needs no pin).
+ */
+export declare function agentSatisfiesHostPolicy(policy: VpnHostPolicy | string, orgId: string, agent: {
+    hostPinned: boolean;
+    dedicatedOrgId: string | null;
+    coHostedRunner: number | null;
+}): boolean;
 /**
  * The VPN-related slice of an agent row the scheduler needs — kept as its
  * own structural type (not added to `AgentInfo`) because it comes straight
@@ -112,6 +289,21 @@ export interface VpnSchedulingAgent {
     vpnApproved: number;
     /** The org this Mac is exclusively locked to, or null when unlocked. */
     vpnLockOrgId: string | null;
+    /** Features the agent proved it can enforce — the caller passes `[]` unless
+     *  the heartbeat that reported them is fresh (see `agentProvesVpnEnforcement`). */
+    vpnFeatures: readonly string[];
+    /** Same provenance and freshness rule as `vpnFeatures`. */
+    enforcementLevel: EnforcementLevel;
+    /** Operator-set taint (migrations/0043): the one org this Mac may serve, or
+     *  null for a shared Mac. Required (not optional) so a caller can never
+     *  forget it: forgetting it would silently un-taint a dedicated Mac. */
+    dedicatedOrgId: string | null;
+    /** What the last heartbeat reported about a co-hosted GitHub Actions runner
+     *  (migrations/0047): 1 present, 0 absent, null unknown. As with
+     *  `vpnFeatures`, the caller passes null unless that heartbeat is fresh.
+     *  Required so a caller cannot forget it (forgetting would let a dedicated
+     *  policy pass on a stale value). */
+    coHostedRunner: number | null;
 }
 /** The slice of a queued-build candidate (`@appforge/db`'s
  *  `QueuedBuildCandidate`) the VPN predicate reads. */
@@ -120,17 +312,34 @@ export interface VpnSchedulingBuild {
     useVpn: boolean;
     /** The build's org's tunnel status, or null when it has no tunnel. */
     vpnTunnelStatus: "pending" | "ready" | "degraded" | "disabled" | null;
+    /** What the build's tunnel requires of the Mac (`vpnTunnelRequirements`).
+     *  Ignored for a build that doesn't use the VPN. */
+    requirements: VpnRequirements;
+    /** The build's tunnel's host policy (`VpnTunnel.hostPolicy`, migrations/0047).
+     *  Ignored for a build that doesn't use the VPN. */
+    hostPolicy: VpnHostPolicy;
+    /** Whether the asking agent is pinned to the build's tunnel
+     *  (`VpnTunnelHostPin`). Required: forgetting it must read as "not pinned". */
+    agentPinned: boolean;
 }
 /**
  * Scheduler predicate for the site-to-site VPN's exclusive-host lock —
  * the "taint/toleration" check, ANDed alongside `agentCanBuildPlatform` in
  * `/agents/lease-job` before any `claimBuildById` attempt:
  *
+ * - A Mac dedicated to an org (`dedicatedOrgId`) refuses every other org's
+ *   builds, VPN or not.
  * - A build that doesn't use the VPN is never offered to a Mac that is
  *   locked to an org (the lock means "only that org's VPN builds here").
  * - A VPN build needs a VPN-capable AND admin-approved Mac (issue #643), a tunnel that exists and isn't
  *   `disabled`, and a Mac that is either unlocked or already locked to
  *   this same org (same-org VPN builds share the lock).
+ * - A VPN build also needs a Mac that satisfies the tunnel's requirements:
+ *   it reports every required feature and a high enough enforcement level
+ *   (capability negotiation, migrations/0043). Nothing is required today.
+ * - A VPN build whose tunnel is `pinned` or `dedicated` (migrations/0047) only
+ *   goes to a Mac pinned to that tunnel, and `dedicated` additionally needs the
+ *   Mac dedicated to the org with no co-hosted GitHub Actions runner.
  *
  * This is an optimization, not the safety net: it filters on the agent
  * row loaded at the start of the request, which can be stale by the time
@@ -141,6 +350,36 @@ export interface VpnSchedulingBuild {
  * proves it works.
  */
 export declare function agentSatisfiesVpnRequirements(agent: VpnSchedulingAgent, build: VpnSchedulingBuild): boolean;
+/** The first agent release that can enforce a VPN job (it ships the signed
+ *  WireGuard helper and honours `job.vpn`). Anything older IGNORES `job.vpn`
+ *  and would run the build with no tunnel, so it must never be leased one,
+ *  whatever its (possibly stale) `Agent.vpnCapable` row says. */
+export declare const MIN_VPN_AGENT_VERSION = "0.2.0";
+/** How recent `Agent.lastSeenAt` must be for `vpnCapable` to count: the flag
+ *  is only as good as the heartbeat that last set it. Three missed 15s beats
+ *  plus slack — and well under the 60s-ish scheduler cadence's tolerance. */
+export declare const VPN_CAPABILITY_MAX_AGE_SECONDS = 120;
+/**
+ * Numeric `major.minor.patch` comparison (a `-prerelease`/`+build` suffix is
+ * ignored). Returns <0, 0, >0, or `null` when either side isn't a plain
+ * semver — callers treat `null` as "unknown", never as "new enough".
+ */
+export declare function compareSemver(a: string, b: string): number | null;
+/** True only for a known version >= `MIN_VPN_AGENT_VERSION`. A missing or
+ *  unparseable version is NOT capable (fail closed). */
+export declare function agentVersionSupportsVpn(agentVersion: string | null | undefined): boolean;
+/**
+ * Server-side proof that the leasing agent can actually enforce a VPN job,
+ * independent of the sticky-ish `vpnCapable` bit: the agent's reported
+ * version must be >= `MIN_VPN_AGENT_VERSION` and its last heartbeat (which is
+ * what (re-)asserts `vpnCapable`) must be recent. ANDed with
+ * `agentSatisfiesVpnRequirements` in `/agents/lease-job`; the guarded SQL in
+ * `claimBuildById`/`acquireVpnLock` re-checks freshness and pins the version.
+ */
+export declare function agentProvesVpnEnforcement(agent: {
+    agentVersion: string | null;
+    lastSeenAt: string;
+}, now?: Date): boolean;
 /**
  * The currently published packages/agent build — bump this in lockstep
  * with packages/agent/package.json's own "version" field (and
@@ -154,7 +393,7 @@ export declare function agentSatisfiesVpnRequirements(agent: VpnSchedulingAgent,
  * version against this same constant to decide whether to auto-issue an
  * `UPDATE_AGENT` command (Phase 2's remote command, reused unchanged).
  */
-export declare const CURRENT_AGENT_VERSION = "0.2.3";
+export declare const CURRENT_AGENT_VERSION = "0.3.1";
 /**
  * Whether a fleet member is running the latest known agent build.
  * `null` — deliberately not "outdated" — for a row with no reported

package/dist/agent-readiness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-readiness.d.ts","sourceRoot":"","sources":["../src/agent-readiness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB;;;sBAGkB;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB;;;oCAGgC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAEhF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,GAAG,YAAY,CAAC,EAC/C,GAAG,GAAE,IAAiB,GACrB,SAAS,CAAC,QAAQ,CAAC,CAErB;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,IAAI,CACT,SAAS,EACT,cAAc,GAAG,aAAa,GAAG,mBAAmB,GAAG,kBAAkB,GAAG,gBAAgB,GAAG,QAAQ,GAAG,YAAY,CACvH,EACD,GAAG,GAAE,IAAiB,GACrB,cAAc,CAUhB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAYxF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC,CAAC,CAAC,EAClD,QAAQ,EAAE,QAAQ,EAClB,GAAG,GAAE,IAAiB,GACrB,OAAO,CAET;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB;+EAC2E;IAC3E,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;uDACuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,sEAAsE;IACtE,eAAe,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,IAAI,CAAC;CACvE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAK3G;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAE7C;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI,CAGjF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CAAC,qBAAqB,EAAE,MAAM,GAAG,IAAI,EAAE,sBAAsB,EAAE,OAAO,GAAG,OAAO,CAEpH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAOzD"}
+{"version":3,"file":"agent-readiness.d.ts","sourceRoot":"","sources":["../src/agent-readiness.ts"],"names":[],"mappings":"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"}

package/dist/agent-readiness.js

@@ -1,3 +1,4 @@
+import { SSH_FEATURE } from "./vpn-ssh.js";
 /**
  * A mini's `status` column is only ever written as a side effect of an
  * inbound heartbeat (see updateAgentHeartbeat in packages/db/src/agents.ts)
@@ -100,16 +101,256 @@ export function agentFitsPlatform(readiness, platform) {
 export function agentCanBuildPlatform(agent, platform, now = new Date()) {
     return agentFitsPlatform(computeAgentReadiness(agent, now), platform);
 }
+/**
+ * Build-isolation level an agent reports (`Agent.enforcementLevel`,
+ * migrations/0043). Ordered: a higher level satisfies a lower requirement.
+ *  - `none`         no kernel-enforced isolation of build processes (today).
+ *  - `sandbox`      builds run under a kernel sandbox profile (Seatbelt).
+ *  - `sandbox_uid`  ... and as a dedicated unprivileged user.
+ * Anything unrecognised ranks as `none`: an unknown level never satisfies a
+ * requirement (fail closed).
+ */
+export const ENFORCEMENT_LEVELS = ["none", "sandbox", "sandbox_uid"];
+export function parseEnforcementLevel(raw) {
+    return typeof raw === "string" && ENFORCEMENT_LEVELS.includes(raw) ? raw : "none";
+}
+/** 0 (`none`) .. 2 (`sandbox_uid`); unknown input is 0. */
+export function enforcementLevelRank(level) {
+    return ENFORCEMENT_LEVELS.indexOf(parseEnforcementLevel(level));
+}
+/** What a feature id may look like (`Agent.vpnFeatures` entries, tunnel
+ *  `requires` entries): lowercase, short, no whitespace or separators that
+ *  could be abused in a log line or SQL JSON. Ids carry their own version
+ *  suffix (`ssh-v1`) so a breaking change is a NEW id, never a redefinition. */
+export const VPN_FEATURE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/** An agent reports at most this many features; the rest are dropped. */
+export const MAX_VPN_FEATURES = 32;
+/**
+ * Feature ids the regulated-VPN program will introduce. Informational: the
+ * scheduler's superset check works on whatever ids a tunnel requires and an
+ * agent reports, so a new id needs no change here. Only `egress-policy-v1` is
+ * required (by a strict-egress tunnel) and reported (by an agent with a new
+ * enough verified helper) so far; the others land in later PRs.
+ */
+export const KNOWN_VPN_FEATURES = ["egress-policy-v1", "ssh-v1", "sandbox-v1", "evidence-v1"];
+/** Prefix of a requirement token that asks for a minimum enforcement level
+ *  (`enforcement:sandbox`) rather than a feature id. */
+export const ENFORCEMENT_REQUIREMENT_PREFIX = "enforcement:";
+/**
+ * The canonical form of a reported feature list: only well-formed ids,
+ * de-duplicated, sorted, capped at `MAX_VPN_FEATURES`. Anything else is
+ * dropped, never repaired. This is the ONLY form stored in
+ * `Agent.vpnFeatures`, so the scheduler's SQL superset check can compare
+ * strings exactly.
+ */
+export function canonicalVpnFeatures(input) {
+    if (!Array.isArray(input))
+        return [];
+    const ok = new Set();
+    for (const v of input)
+        if (typeof v === "string" && VPN_FEATURE_ID_PATTERN.test(v))
+            ok.add(v);
+    return [...ok].sort().slice(0, MAX_VPN_FEATURES);
+}
+/** Parses the `Agent.vpnFeatures` JSON column. Malformed, non-array or null
+ *  input is `[]` (no features), never an exception. */
+export function parseVpnFeatures(raw) {
+    if (!raw)
+        return [];
+    try {
+        return canonicalVpnFeatures(JSON.parse(raw));
+    }
+    catch {
+        return [];
+    }
+}
+export const NO_VPN_REQUIREMENTS = { features: [], minEnforcementLevel: "none" };
+/** The feature id of the strict egress policy: the helper enforces a job's
+ *  `egress` allow-list and echoes its hash, and the agent verifies the echo. A
+ *  tunnel with `strictEgress` requires it (see `vpnTunnelRequirements`). */
+export const EGRESS_POLICY_FEATURE = "egress-policy-v1";
+/**
+ * What the given tunnel requires of an agent. This is the single place a tunnel
+ * setting makes a requirement; the scheduler, the guarded claim SQL, the lease
+ * response (`job.requires`) and the agent's abort check all consume this one
+ * answer.
+ *
+ *  - `strictEgress`: the Mac must report `egress-policy-v1`, because an agent or
+ *    helper that predates the policy ignores the `egress` block and would run
+ *    the build with no allow-list. Only an exact `0`/`false` means "not strict":
+ *    a missing, null or unrecognised value requires it (fail closed).
+ *  - `complianceMode` other than exactly `standard` (regulated, or a value this
+ *    code does not know): strict egress as above, and at least `sandbox`
+ *    enforcement. No Mac reports a sandbox yet, so a regulated tunnel's builds
+ *    wait for one rather than run unconfined.
+ *
+ *  - `sshRepo` (the app's repository is an ssh remote, PR-G): the Mac must report
+ *    `ssh-v1`, because an agent or helper that predates it cannot clone through
+ *    the tunnel's pinned-host-key ssh path and would ignore the ssh fields.
+ *
+ * A standard-mode tunnel with strict egress off and an https repository requires
+ * nothing, exactly as before, so the server can ship ahead of any agent.
+ */
+export function vpnTunnelRequirements(tunnel) {
+    const regulated = tunnel.complianceMode !== "standard";
+    const strict = regulated || (tunnel.strictEgress !== 0 && tunnel.strictEgress !== false);
+    const features = [];
+    if (strict)
+        features.push(EGRESS_POLICY_FEATURE);
+    if (tunnel.sshRepo === true)
+        features.push(SSH_FEATURE);
+    if (features.length === 0)
+        return NO_VPN_REQUIREMENTS;
+    return { features, minEnforcementLevel: regulated ? "sandbox" : "none" };
+}
+/** The wire form of requirements, carried in the lease response as
+ *  `job.requires`: feature ids plus `enforcement:<level>` for a level above
+ *  `none`. An agent aborts a job with any token it cannot satisfy. */
+export function vpnRequirementTokens(req) {
+    // Verbatim, deliberately NOT `canonicalVpnFeatures`: that drops malformed ids
+    // and truncates at MAX_VPN_FEATURES, which is right for untrusted agent-reported
+    // input but would silently remove a REQUIRED feature here (fail open). A
+    // malformed or surplus required id must survive so `unmetRequirements` flags it
+    // as unmet — matching the guarded SQL, which binds the raw list.
+    const tokens = [...new Set(req.features)].sort();
+    if (enforcementLevelRank(req.minEnforcementLevel) > 0)
+        tokens.push(`${ENFORCEMENT_REQUIREMENT_PREFIX}${req.minEnforcementLevel}`);
+    return tokens;
+}
+/** Printable, bounded rendering of an untrusted token for logs and errors. */
+function describeToken(token) {
+    if (typeof token !== "string")
+        return "<non-string>";
+    return token.replace(/[^\x21-\x7e]/g, "?").slice(0, 80);
+}
+/**
+ * Which of `tokens` the capabilities do NOT satisfy. A token is satisfied only
+ * if it is a feature id the capabilities list, or `enforcement:<level>` with a
+ * KNOWN level the capabilities reach. An unknown token, an unknown level, or a
+ * non-string entry is unmet: this is what makes the check fail closed against a
+ * requirement introduced by a newer control plane than the agent. A non-array
+ * `tokens` is itself unmet (reported as one entry).
+ *
+ * Used by both the scheduler (`agentSatisfiesVpnRequirements`) and the agent
+ * (before it starts a leased VPN job), so they cannot disagree.
+ */
+export function unmetRequirements(tokens, capabilities) {
+    if (!Array.isArray(tokens))
+        return ["<malformed requires>"];
+    const have = new Set(capabilities.features);
+    const haveRank = enforcementLevelRank(capabilities.enforcementLevel);
+    const unmet = [];
+    for (const token of tokens) {
+        if (typeof token === "string" && token.startsWith(ENFORCEMENT_REQUIREMENT_PREFIX)) {
+            const level = token.slice(ENFORCEMENT_REQUIREMENT_PREFIX.length);
+            const known = ENFORCEMENT_LEVELS.includes(level);
+            if (!known || haveRank < enforcementLevelRank(level))
+                unmet.push(describeToken(token));
+        }
+        else if (typeof token !== "string" || !VPN_FEATURE_ID_PATTERN.test(token) || !have.has(token)) {
+            unmet.push(describeToken(token));
+        }
+    }
+    return unmet;
+}
+/**
+ * Operator taint (`Agent.dedicatedOrgId`): a Mac dedicated to an org takes only
+ * that org's builds, VPN or not. `null` = shared. An empty string is NOT shared:
+ * only an explicit null is (a mangled value must not widen who may build here).
+ */
+export function agentAllowsOrg(dedicatedOrgId, buildOrgId) {
+    return dedicatedOrgId === null || dedicatedOrgId === buildOrgId;
+}
+/**
+ * Where a tunnel's builds may run (`VpnTunnel.hostPolicy`, migrations/0047).
+ *  - `shared`     any approved, VPN-capable Mac, under the exclusive-host lock
+ *                 (today's behaviour, and the default).
+ *  - `pinned`     only Macs the operator pinned to the tunnel (node affinity).
+ *  - `dedicated`  pinned, AND the Mac is dedicated to this org
+ *                 (`Agent.dedicatedOrgId`, so no other org's work is leased to
+ *                 it), AND it reports no co-hosted GitHub Actions runner.
+ * Set only by a platform admin; org admins can read it, never write it.
+ */
+export const VPN_HOST_POLICIES = ["shared", "pinned", "dedicated"];
+/**
+ * What a customer sees for their tunnel's host policy (read-only; the operator
+ * sets it). Deliberately plain about the limits: "dedicated" is a scheduling
+ * guarantee about which machines AppForge runs this org's VPN builds on, not a
+ * claim of hardware isolation or of any compliance certification.
+ */
+export function describeVpnHostPolicy(policy, pinnedHostCount = 0) {
+    const n = `${pinnedHostCount} build machine${pinnedHostCount === 1 ? "" : "s"}`;
+    switch (parseVpnHostPolicy(policy)) {
+        case "shared":
+            return "shared: builds may run on any approved AppForge build machine, one organization's VPN tunnel at a time";
+        case "pinned":
+            return `pinned: VPN builds run only on the ${n} AppForge assigned to your tunnel`;
+        case "dedicated":
+            return `dedicated: VPN builds run only on the ${n} AppForge assigned to your tunnel, which take no other organization's builds. This is a scheduling arrangement, not a compliance certification`;
+    }
+}
+/** How long a queued VPN build of a `pinned`/`dedicated` tunnel waits for a ready
+ *  pinned Mac before the control plane's sweep fails it as an infra failure with a
+ *  refund. The wait is measured as CONTINUOUS host unavailability, not build age:
+ *  the sweep records when the tunnel's pinned Macs stopped being ready
+ *  (`VpnTunnelHostWait`) and fails a build only once they have all been unready
+ *  for this long AND the build itself has been queued this long. Any tick that
+ *  finds a ready Mac (busy counts as ready) restarts the clock, so a Mac that is
+ *  briefly away (a reboot or self-update cycle, a short drain) does not fail a
+ *  build that has merely been waiting in line. Longer than the 120 s
+ *  lock-reservation window. The sweep runs every 5 minutes, so the effective
+ *  wait is this plus up to one cron interval. */
+export const VPN_HOST_WAIT_SECONDS = 600;
+/** If the sweep's last observation of a tunnel's pinned hosts is older than this
+ *  (three cron ticks), it knows nothing about the gap, so the next "unready"
+ *  observation starts a fresh unavailability stretch instead of extending an old one. */
+export const VPN_HOST_OBSERVATION_GAP_SECONDS = 900;
+/**
+ * Parses a stored policy. An UNKNOWN value is `dedicated`, the strictest, not
+ * `shared`: a mangled policy must tighten placement, never loosen it (the
+ * column's CHECK makes this unreachable today; it is here so a future value
+ * read by an older Worker fails closed).
+ */
+export function parseVpnHostPolicy(raw) {
+    return typeof raw === "string" && VPN_HOST_POLICIES.includes(raw) ? raw : "dedicated";
+}
+/**
+ * Whether an agent may serve a VPN build under the tunnel's host policy.
+ *  - `hostPinned` is "this Mac is in the tunnel's pin set".
+ *  - `dedicatedOrgId` is the Mac's operator taint.
+ *  - `coHostedRunner` is what its last (fresh) heartbeat reported: only an
+ *    exact 0 means "no GitHub Actions runner on the machine". 1, null
+ *    (unreported) and anything else all refuse for `dedicated`.
+ * `shared` always passes (and is the only case that needs no pin).
+ */
+export function agentSatisfiesHostPolicy(policy, orgId, agent) {
+    const p = parseVpnHostPolicy(policy);
+    if (p === "shared")
+        return true;
+    if (!agent.hostPinned)
+        return false;
+    if (p === "pinned")
+        return true;
+    return agent.dedicatedOrgId === orgId && agent.coHostedRunner === 0;
+}
 /**
  * Scheduler predicate for the site-to-site VPN's exclusive-host lock —
  * the "taint/toleration" check, ANDed alongside `agentCanBuildPlatform` in
  * `/agents/lease-job` before any `claimBuildById` attempt:
  *
+ * - A Mac dedicated to an org (`dedicatedOrgId`) refuses every other org's
+ *   builds, VPN or not.
  * - A build that doesn't use the VPN is never offered to a Mac that is
  *   locked to an org (the lock means "only that org's VPN builds here").
  * - A VPN build needs a VPN-capable AND admin-approved Mac (issue #643), a tunnel that exists and isn't
  *   `disabled`, and a Mac that is either unlocked or already locked to
  *   this same org (same-org VPN builds share the lock).
+ * - A VPN build also needs a Mac that satisfies the tunnel's requirements:
+ *   it reports every required feature and a high enough enforcement level
+ *   (capability negotiation, migrations/0043). Nothing is required today.
+ * - A VPN build whose tunnel is `pinned` or `dedicated` (migrations/0047) only
+ *   goes to a Mac pinned to that tunnel, and `dedicated` additionally needs the
+ *   Mac dedicated to the org with no co-hosted GitHub Actions runner.
  *
  * This is an optimization, not the safety net: it filters on the agent
  * row loaded at the start of the request, which can be stale by the time
@@ -120,14 +361,76 @@ export function agentCanBuildPlatform(agent, platform, now = new Date()) {
  * proves it works.
  */
 export function agentSatisfiesVpnRequirements(agent, build) {
+    if (!agentAllowsOrg(agent.dedicatedOrgId, build.orgId))
+        return false;
     if (!build.useVpn)
         return agent.vpnLockOrgId === null;
     if (agent.vpnCapable !== 1 || agent.vpnApproved !== 1)
         return false;
     if (build.vpnTunnelStatus === null || build.vpnTunnelStatus === "disabled")
         return false;
+    if (unmetRequirements(vpnRequirementTokens(build.requirements), { features: agent.vpnFeatures, enforcementLevel: agent.enforcementLevel }).length > 0)
+        return false;
+    if (!agentSatisfiesHostPolicy(build.hostPolicy, build.orgId, {
+        hostPinned: build.agentPinned,
+        dedicatedOrgId: agent.dedicatedOrgId,
+        coHostedRunner: agent.coHostedRunner,
+    })) {
+        return false;
+    }
     return agent.vpnLockOrgId === null || agent.vpnLockOrgId === build.orgId;
 }
+/** The first agent release that can enforce a VPN job (it ships the signed
+ *  WireGuard helper and honours `job.vpn`). Anything older IGNORES `job.vpn`
+ *  and would run the build with no tunnel, so it must never be leased one,
+ *  whatever its (possibly stale) `Agent.vpnCapable` row says. */
+export const MIN_VPN_AGENT_VERSION = "0.2.0";
+/** How recent `Agent.lastSeenAt` must be for `vpnCapable` to count: the flag
+ *  is only as good as the heartbeat that last set it. Three missed 15s beats
+ *  plus slack — and well under the 60s-ish scheduler cadence's tolerance. */
+export const VPN_CAPABILITY_MAX_AGE_SECONDS = 120;
+/**
+ * Numeric `major.minor.patch` comparison (a `-prerelease`/`+build` suffix is
+ * ignored). Returns <0, 0, >0, or `null` when either side isn't a plain
+ * semver — callers treat `null` as "unknown", never as "new enough".
+ */
+export function compareSemver(a, b) {
+    const parse = (v) => {
+        const m = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(v.trim());
+        return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    if (!pa || !pb)
+        return null;
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] !== pb[i])
+            return pa[i] - pb[i];
+    }
+    return 0;
+}
+/** True only for a known version >= `MIN_VPN_AGENT_VERSION`. A missing or
+ *  unparseable version is NOT capable (fail closed). */
+export function agentVersionSupportsVpn(agentVersion) {
+    if (!agentVersion)
+        return false;
+    const cmp = compareSemver(agentVersion, MIN_VPN_AGENT_VERSION);
+    return cmp !== null && cmp >= 0;
+}
+/**
+ * Server-side proof that the leasing agent can actually enforce a VPN job,
+ * independent of the sticky-ish `vpnCapable` bit: the agent's reported
+ * version must be >= `MIN_VPN_AGENT_VERSION` and its last heartbeat (which is
+ * what (re-)asserts `vpnCapable`) must be recent. ANDed with
+ * `agentSatisfiesVpnRequirements` in `/agents/lease-job`; the guarded SQL in
+ * `claimBuildById`/`acquireVpnLock` re-checks freshness and pins the version.
+ */
+export function agentProvesVpnEnforcement(agent, now = new Date()) {
+    if (!agentVersionSupportsVpn(agent.agentVersion))
+        return false;
+    const ageMs = now.getTime() - parseUtc(agent.lastSeenAt).getTime();
+    return Number.isFinite(ageMs) && ageMs <= VPN_CAPABILITY_MAX_AGE_SECONDS * 1000;
+}
 /**
  * The currently published packages/agent build — bump this in lockstep
  * with packages/agent/package.json's own "version" field (and
@@ -141,7 +444,7 @@ export function agentSatisfiesVpnRequirements(agent, build) {
  * version against this same constant to decide whether to auto-issue an
  * `UPDATE_AGENT` command (Phase 2's remote command, reused unchanged).
  */
-export const CURRENT_AGENT_VERSION = "0.2.3";
+export const CURRENT_AGENT_VERSION = "0.3.1";
 /**
  * Whether a fleet member is running the latest known agent build.
  * `null` — deliberately not "outdated" — for a row with no reported