@farmslot/protocol 0.21.0 → 0.26.0

package/dist/contracts/runtime-capabilities.d.ts

@@ -1,14 +1,48 @@
+import type { ProjectResourcePostureConfig, ResourcePostureRetention, ResourcePostureRetentionBoundary } from './resource-posture.js';
 /** Runtime resources acquired after core prepare from a declared proof plan. */
 export type RuntimeCapabilityCostClass = 'low' | 'medium' | 'high';
 export type RuntimeCapabilitySharePolicy = 'exclusive' | 'shared';
 export type RuntimeCapabilityLeaseState = 'queued' | 'acquiring' | 'acquired' | 'releasing' | 'released' | 'error';
 export type RuntimeCapabilityHealthState = 'unknown' | 'healthy' | 'unhealthy';
-export type RuntimeCapabilityProofMode = 'state' | 'visual' | 'mixed';
+/** Proof modes a requirement may ask for. Exported as a value so clients can
+ * build option lists and validators from the protocol instead of retyping it. */
+export declare const RUNTIME_CAPABILITY_PROOF_MODES: readonly ["state", "visual", "mixed"];
+export type RuntimeCapabilityProofMode = (typeof RUNTIME_CAPABILITY_PROOF_MODES)[number];
+export declare function isRuntimeCapabilityProofMode(value: unknown): value is RuntimeCapabilityProofMode;
+/**
+ * How far a resource claim's exclusivity reaches.
+ *
+ * `slot` is the historical behaviour and stays the default: the claim only
+ * arbitrates against other leases on the same slot. `machine` reaches every
+ * slot on the same host, and `fleet` reaches every slot the Gateway knows
+ * about, which is how one physical device shared by several slots is expressed.
+ */
+export declare const RUNTIME_CAPABILITY_CLAIM_SCOPES: readonly ["slot", "machine", "fleet"];
+export type RuntimeCapabilityClaimScope = (typeof RUNTIME_CAPABILITY_CLAIM_SCOPES)[number];
+export declare function isRuntimeCapabilityClaimScope(value: unknown): value is RuntimeCapabilityClaimScope;
 export interface RuntimeCapabilityResourceClaim {
     id: string;
     access: RuntimeCapabilitySharePolicy;
     kind?: 'port' | 'device' | 'process' | 'service' | 'other';
+    /**
+     * Absent means `slot`. Normalization fills it in, so a catalog entry always
+     * carries an explicit scope; the field stays optional because leases and
+     * fixtures written before scopes existed have none, and those are slot-scoped
+     * by definition.
+     */
+    scope?: RuntimeCapabilityClaimScope;
 }
+/** A claim's effective scope. The one place the `slot` default is applied. */
+export declare function runtimeCapabilityClaimScope(claim: Pick<RuntimeCapabilityResourceClaim, 'scope'>): RuntimeCapabilityClaimScope;
+/**
+ * The widest of two scopes.
+ *
+ * Arbitration is symmetric: if either side declares a claim `fleet`, the two
+ * are contending for one physical thing whatever the other side declared. Two
+ * projects can describe the same claim id differently, so the wider declaration
+ * wins rather than whichever acquire happened to come second.
+ */
+export declare function widerRuntimeCapabilityClaimScope(left: RuntimeCapabilityClaimScope, right: RuntimeCapabilityClaimScope): RuntimeCapabilityClaimScope;
 export interface RuntimeCapabilityCost {
     class: RuntimeCapabilityCostClass;
     resources: RuntimeCapabilityResourceClaim[];
@@ -26,6 +60,30 @@ export interface RuntimeCapabilityProviderActions {
     health: RuntimeCapabilityProviderActionRef;
     release: RuntimeCapabilityProviderActionRef;
 }
+/**
+ * Who owns the lifecycle of a slot resource a provider touches.
+ * - `capability`: the lease is the resource's owner, so a running resource with
+ *   no lease is an unowned leak and machine parking refuses to stop it.
+ * - `slot-lifecycle`: prepare (or the operator) owns the resource and the
+ *   capability only rides on it, so no lease is required for it to be running.
+ */
+export declare const RUNTIME_CAPABILITY_AFFECTED_OWNERSHIPS: readonly ["capability", "slot-lifecycle"];
+export type RuntimeCapabilityAffectedOwnership = (typeof RUNTIME_CAPABILITY_AFFECTED_OWNERSHIPS)[number];
+/**
+ * What releasing the provider factually does to the resource. This is a claim
+ * about mechanics, not a policy knob: `retain` means the provider's release
+ * action leaves the resource running, so parking must not stop it either and
+ * restore must find it still running rather than boot it.
+ */
+export declare const RUNTIME_CAPABILITY_AFFECTED_RELEASE_EFFECTS: readonly ["stop", "retain"];
+export type RuntimeCapabilityAffectedReleaseEffect = (typeof RUNTIME_CAPABILITY_AFFECTED_RELEASE_EFFECTS)[number];
+/** One slot resource a provider touches, declared by the project catalog. */
+export interface RuntimeCapabilityAffectedResource {
+    /** Names a key of the project's `resources` map. */
+    resourceId: string;
+    ownership: RuntimeCapabilityAffectedOwnership;
+    releaseEffect: RuntimeCapabilityAffectedReleaseEffect;
+}
 export interface RuntimeCapabilityProviderConfig {
     label: string;
     description?: string;
@@ -36,12 +94,53 @@ export interface RuntimeCapabilityProviderConfig {
     /** JSON Schema object for acquire parameters. */
     parameters?: Record<string, unknown>;
     actions: RuntimeCapabilityProviderActions;
+    /**
+     * Slot resources this provider touches. Absent means "derive from the
+     * resource-kind action refs" (every referenced resource, owned by the
+     * capability, stopped on release) — the behaviour every catalog had before
+     * this field existed. An empty array is a deliberate declaration that the
+     * provider touches no watched slot resource, which is distinct from absent.
+     */
+    affectedResources?: RuntimeCapabilityAffectedResource[];
     releaseEffects: string[];
     /** Explicit project policy; zero/absent means release immediately. */
     keepWarmMs?: number;
+    /**
+     * Per-posture retention (ADR-054). Overrides the project posture defaults for
+     * this provider. `retain` is not accepted at `terminal`.
+     */
+    retention?: Partial<Record<ResourcePostureRetentionBoundary, ResourcePostureRetention>>;
 }
 export interface ProjectRuntimeCapabilitiesConfig {
     providers: Record<string, RuntimeCapabilityProviderConfig>;
+    /** Project-wide posture defaults (ADR-054); provider `retention` wins over these. */
+    posture?: ProjectResourcePostureConfig;
+    /** Opt-in host-pressure admission for this project's capability acquires. */
+    hostPressureAdmission?: ProjectHostPressureAdmissionConfig;
+}
+/**
+ * How this project's medium/high-cost capability acquires react to critical
+ * host pressure.
+ *
+ * `off` (the DEFAULT when the block is absent) never refuses: pressure is still
+ * evaluated and carried on the granted lease as an advisory. `refuse` blocks the
+ * acquire. `queue` blocks it and parks the caller in the pressure queue whether
+ * or not the caller passed `queueOnPressure`.
+ */
+export type HostPressureAdmissionMode = 'off' | 'refuse' | 'queue';
+export declare const HOST_PRESSURE_ADMISSION_MODES: readonly HostPressureAdmissionMode[];
+/**
+ * Project overrides for the critical thresholds that decide the pressure
+ * severity an enforcing mode acts on. Every field is optional and falls back to
+ * the gateway defaults (1.5x cores, 90% CPU, 90% memory, 95% disk); the warn
+ * band and thermal pressure are not project-tunable.
+ */
+export interface ProjectHostPressureAdmissionConfig {
+    mode: HostPressureAdmissionMode;
+    load1CriticalMultiplier?: number;
+    cpuCriticalPercent?: number;
+    memoryCriticalPercent?: number;
+    diskCriticalPercent?: number;
 }
 export interface RuntimeCapabilityProviderProvenance {
     project: string;
@@ -99,7 +198,70 @@ export interface RuntimeCapabilityLease {
     keepWarmUntil?: string;
     cleanupFailure?: string;
     /** Admission pressure retained while this lease is queued. */
-    pressure?: RuntimeCapabilityPressureConflict;
+    pressure?: RuntimeCapabilityLeasePressure;
+    /**
+     * The machine the slot ran on when the lease was taken.
+     *
+     * Persisted rather than resolved on read: judging a foreign lease's claim
+     * needs its machine, and reading another slot's config to get it would make
+     * arbitration depend on a file that can be mid-write. A lease without it
+     * (written before scopes existed, or by a Gateway with no fleet) can only
+     * arbitrate at `slot` and `fleet` scope.
+     */
+    machine?: string;
+    /**
+     * The resource claims this lease holds, resolved from the catalog entry at
+     * acquire time.
+     *
+     * Persisted for the same reason as `machine`: a conflict check across slots
+     * would otherwise need every foreign slot's catalog, possibly from another
+     * project. A lease with no `claims` predates scoped arbitration and is
+     * treated as slot-scoped, which is exactly how it behaved when it was taken.
+     */
+    claims?: RuntimeCapabilityLeaseClaim[];
+    /** Why this lease is queued behind a scoped claim, while it is queued. */
+    wait?: RuntimeCapabilityScopedClaimWait;
+}
+/** One resource claim a lease holds, with the scope it was resolved at. */
+export interface RuntimeCapabilityLeaseClaim {
+    id: string;
+    access: RuntimeCapabilitySharePolicy;
+    scope: RuntimeCapabilityClaimScope;
+}
+/**
+ * A queued lease's place in a scoped claim's wait queue.
+ *
+ * `blockingOwner` is carried rather than looked up because
+ * `runtime.capability.status` is slot-filtered: the run holding the claim is
+ * usually on another slot, so without this a client could only report that
+ * something, somewhere, holds it.
+ */
+export interface RuntimeCapabilityScopedClaimWait {
+    kind: 'scoped-claim';
+    claimId: string;
+    scope: RuntimeCapabilityClaimScope;
+    blockingOwner: RuntimeCapabilityLeaseOwner;
+    blockingLeaseId: string;
+    enqueuedAt: string;
+}
+/**
+ * One waiter in a scoped claim's queue, derived on read.
+ *
+ * Position is never stored. Order comes from `enqueuedAt` then lease id, so a
+ * Gateway restart preserves it for free and nothing has to renumber a queue.
+ */
+export interface RuntimeCapabilityClaimWaiter {
+    claimId: string;
+    scope: RuntimeCapabilityClaimScope;
+    /** 1-based place in the queue for this claim, across every slot in scope. */
+    position: number;
+    leaseId: string;
+    slotId: string;
+    capabilityId: string;
+    owner: RuntimeCapabilityLeaseOwner;
+    enqueuedAt: string;
+    blockingOwner: RuntimeCapabilityLeaseOwner;
+    blockingLeaseId: string;
 }
 export interface RuntimeCapabilityLeaseConflict {
     kind: 'lease-conflict';
@@ -108,6 +270,16 @@ export interface RuntimeCapabilityLeaseConflict {
     leaseId: string;
     reason: string;
 }
+/**
+ * The acquire was REFUSED because the host is under critical pressure and the
+ * project opted in to enforcement.
+ *
+ * This type only ever describes a refusal. Pressure that was observed but NOT
+ * enforced is a `RuntimeCapabilityPressureAdvisory`, which is deliberately a
+ * different `kind` and is not a member of `RuntimeCapabilityAcquireConflict`:
+ * a client matching `kind === 'host-pressure'` must never be able to paint an
+ * admitted acquire as a block, and an absent boolean was too easy to miss.
+ */
 export interface RuntimeCapabilityPressureConflict {
     kind: 'host-pressure';
     reason: string;
@@ -116,7 +288,53 @@ export interface RuntimeCapabilityPressureConflict {
     queued: boolean;
     retryAfterMs?: number;
 }
-export type RuntimeCapabilityAcquireConflict = RuntimeCapabilityLeaseConflict | RuntimeCapabilityPressureConflict | {
+/**
+ * Pressure that was observed and NOT enforced: the project (or the gateway env
+ * override) has `host_pressure_admission.mode: 'off'`, which is the default.
+ * The acquire PROCEEDED. This rides along on the granted lease so operators can
+ * still see the machine was loaded, and it is never a refusal.
+ *
+ * It is a reading taken AT ACQUIRE TIME and never refreshed — hence the
+ * required `observedAt`. A live view of the machine is
+ * `resource.pressure.snapshot`.
+ */
+export interface RuntimeCapabilityPressureAdvisory {
+    kind: 'host-pressure-advisory';
+    reason: string;
+    severity: 'warn' | 'critical';
+    machine?: string;
+    observedAt: string;
+}
+/**
+ * What a lease's `pressure` field may hold: why a QUEUED lease is waiting
+ * (a conflict), or the unenforced reading an ACQUIRED lease was taken under
+ * (an advisory). The `kind` tells them apart; nothing else has to.
+ */
+export type RuntimeCapabilityLeasePressure = RuntimeCapabilityPressureConflict | RuntimeCapabilityPressureAdvisory;
+/**
+ * The acquire was refused AND enqueued: a scoped claim is held elsewhere and
+ * the caller asked to queue on that conflict.
+ *
+ * Distinct from `lease-conflict`, which is a flat refusal with nothing to wait
+ * for. A client that sees this has a durable place in line — `queuedLeaseId` —
+ * and the run is in a resource wait until the holder releases.
+ */
+export interface RuntimeCapabilityScopedWaitConflict {
+    kind: 'scoped-wait';
+    capabilityId: string;
+    claimId: string;
+    scope: RuntimeCapabilityClaimScope;
+    /** The run holding the claim, which may be on another slot. */
+    owner: RuntimeCapabilityLeaseOwner;
+    /** The holder's lease. */
+    leaseId: string;
+    /** The queued lease this acquire now owns. */
+    queuedLeaseId: string;
+    /** 1-based place in line at the moment of the refusal. */
+    position: number;
+    reason: string;
+}
+export type RuntimeCapabilityAcquireConflict = RuntimeCapabilityLeaseConflict | RuntimeCapabilityPressureConflict | RuntimeCapabilityScopedWaitConflict | {
     kind: 'unavailable' | 'invalid-request';
     capabilityId: string;
     reason: string;
@@ -131,4 +349,38 @@ export interface RuntimeCapabilityLifecycleEvent {
     owner?: RuntimeCapabilityLeaseOwner;
     detail?: string;
 }
+/**
+ * Device-identity parameters a capability provider may accept so a validation
+ * or recipe rerun can name a target device instead of re-dispatching the run to
+ * another slot (ADR-054 item 3).
+ *
+ * These are the ONLY acquire parameters the Gateway turns into hook template
+ * variables. Everything else in a provider's parameter schema stays data the
+ * provider's own actions read; it never reaches a shell template.
+ */
+export declare const RUNTIME_CAPABILITY_TARGET_KEYS: readonly ["platform", "udid", "simulator", "avd", "adb_serial"];
+export type RuntimeCapabilityTargetKey = (typeof RUNTIME_CAPABILITY_TARGET_KEYS)[number];
+export type RuntimeCapabilityTarget = Partial<Record<RuntimeCapabilityTargetKey, string>>;
+/**
+ * The charset a device identity may use. Deliberately narrow: these values are
+ * substituted into project hook command templates, so anything that could carry
+ * shell meaning is refused before it reaches a template rather than escaped
+ * afterwards.
+ *
+ * A LEADING dash is refused too. `-x` is shell-safe but it is still an argument
+ * to whatever the hook runs — `simctl boot -x`, `adb -s -x` — so an identity
+ * must start with an identity character.
+ */
+export declare const RUNTIME_CAPABILITY_TARGET_VALUE_PATTERN: RegExp;
+export declare function isRuntimeCapabilityTargetKey(value: unknown): value is RuntimeCapabilityTargetKey;
+export declare function isRuntimeCapabilityTargetValue(value: unknown): value is string;
+/**
+ * The device-identity subset of a lease's stored acquire parameters, for
+ * clients that show which device a lease actually resolved to. Values that are
+ * not well-formed identities are dropped rather than rendered: a lease can only
+ * have been acquired with valid ones, so anything else is not a target.
+ */
+export declare function runtimeCapabilityTargetFromParameters(parameters: Record<string, unknown> | undefined): RuntimeCapabilityTarget | undefined;
+/** `simulator=A, udid=B` in the order the keys are declared. For labels only. */
+export declare function formatRuntimeCapabilityTarget(target: RuntimeCapabilityTarget): string;
 //# sourceMappingURL=runtime-capabilities.d.ts.map

package/dist/contracts/runtime-capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-capabilities.d.ts","sourceRoot":"","sources":["../../src/contracts/runtime-capabilities.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime-capabilities.d.ts","sourceRoot":"","sources":["../../src/contracts/runtime-capabilities.ts"],"names":[],"mappings":"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"}

package/dist/contracts/runtime-capabilities.js

@@ -1,2 +1,114 @@
-export {};
+/** Proof modes a requirement may ask for. Exported as a value so clients can
+ * build option lists and validators from the protocol instead of retyping it. */
+export const RUNTIME_CAPABILITY_PROOF_MODES = ['state', 'visual', 'mixed'];
+export function isRuntimeCapabilityProofMode(value) {
+    return RUNTIME_CAPABILITY_PROOF_MODES.includes(value);
+}
+/**
+ * How far a resource claim's exclusivity reaches.
+ *
+ * `slot` is the historical behaviour and stays the default: the claim only
+ * arbitrates against other leases on the same slot. `machine` reaches every
+ * slot on the same host, and `fleet` reaches every slot the Gateway knows
+ * about, which is how one physical device shared by several slots is expressed.
+ */
+export const RUNTIME_CAPABILITY_CLAIM_SCOPES = ['slot', 'machine', 'fleet'];
+export function isRuntimeCapabilityClaimScope(value) {
+    return RUNTIME_CAPABILITY_CLAIM_SCOPES.includes(value);
+}
+/** A claim's effective scope. The one place the `slot` default is applied. */
+export function runtimeCapabilityClaimScope(claim) {
+    return claim.scope ?? 'slot';
+}
+/**
+ * The widest of two scopes.
+ *
+ * Arbitration is symmetric: if either side declares a claim `fleet`, the two
+ * are contending for one physical thing whatever the other side declared. Two
+ * projects can describe the same claim id differently, so the wider declaration
+ * wins rather than whichever acquire happened to come second.
+ */
+export function widerRuntimeCapabilityClaimScope(left, right) {
+    if (left === 'fleet' || right === 'fleet')
+        return 'fleet';
+    if (left === 'machine' || right === 'machine')
+        return 'machine';
+    return 'slot';
+}
+/**
+ * Who owns the lifecycle of a slot resource a provider touches.
+ * - `capability`: the lease is the resource's owner, so a running resource with
+ *   no lease is an unowned leak and machine parking refuses to stop it.
+ * - `slot-lifecycle`: prepare (or the operator) owns the resource and the
+ *   capability only rides on it, so no lease is required for it to be running.
+ */
+export const RUNTIME_CAPABILITY_AFFECTED_OWNERSHIPS = ['capability', 'slot-lifecycle'];
+/**
+ * What releasing the provider factually does to the resource. This is a claim
+ * about mechanics, not a policy knob: `retain` means the provider's release
+ * action leaves the resource running, so parking must not stop it either and
+ * restore must find it still running rather than boot it.
+ */
+export const RUNTIME_CAPABILITY_AFFECTED_RELEASE_EFFECTS = ['stop', 'retain'];
+export const HOST_PRESSURE_ADMISSION_MODES = [
+    'off',
+    'refuse',
+    'queue',
+];
+/**
+ * Device-identity parameters a capability provider may accept so a validation
+ * or recipe rerun can name a target device instead of re-dispatching the run to
+ * another slot (ADR-054 item 3).
+ *
+ * These are the ONLY acquire parameters the Gateway turns into hook template
+ * variables. Everything else in a provider's parameter schema stays data the
+ * provider's own actions read; it never reaches a shell template.
+ */
+export const RUNTIME_CAPABILITY_TARGET_KEYS = [
+    'platform',
+    'udid',
+    'simulator',
+    'avd',
+    'adb_serial',
+];
+/**
+ * The charset a device identity may use. Deliberately narrow: these values are
+ * substituted into project hook command templates, so anything that could carry
+ * shell meaning is refused before it reaches a template rather than escaped
+ * afterwards.
+ *
+ * A LEADING dash is refused too. `-x` is shell-safe but it is still an argument
+ * to whatever the hook runs — `simctl boot -x`, `adb -s -x` — so an identity
+ * must start with an identity character.
+ */
+export const RUNTIME_CAPABILITY_TARGET_VALUE_PATTERN = /^[A-Za-z0-9._:][A-Za-z0-9._:-]*$/;
+export function isRuntimeCapabilityTargetKey(value) {
+    return RUNTIME_CAPABILITY_TARGET_KEYS.includes(value);
+}
+export function isRuntimeCapabilityTargetValue(value) {
+    return typeof value === 'string' && RUNTIME_CAPABILITY_TARGET_VALUE_PATTERN.test(value);
+}
+/**
+ * The device-identity subset of a lease's stored acquire parameters, for
+ * clients that show which device a lease actually resolved to. Values that are
+ * not well-formed identities are dropped rather than rendered: a lease can only
+ * have been acquired with valid ones, so anything else is not a target.
+ */
+export function runtimeCapabilityTargetFromParameters(parameters) {
+    if (!parameters)
+        return undefined;
+    const target = {};
+    for (const key of RUNTIME_CAPABILITY_TARGET_KEYS) {
+        const value = parameters[key];
+        if (isRuntimeCapabilityTargetValue(value))
+            target[key] = value;
+    }
+    return Object.keys(target).length > 0 ? target : undefined;
+}
+/** `simulator=A, udid=B` in the order the keys are declared. For labels only. */
+export function formatRuntimeCapabilityTarget(target) {
+    return RUNTIME_CAPABILITY_TARGET_KEYS.filter((key) => target[key] !== undefined)
+        .map((key) => `${key}=${target[key]}`)
+        .join(', ');
+}
 //# sourceMappingURL=runtime-capabilities.js.map

package/dist/contracts/runtime-capabilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-capabilities.js","sourceRoot":"","sources":["../../src/contracts/runtime-capabilities.ts"],"names":[],"mappings":""}
+{"version":3,"file":"runtime-capabilities.js","sourceRoot":"","sources":["../../src/contracts/runtime-capabilities.ts"],"names":[],"mappings":"AAiBA;iFACiF;AACjF,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAC;AAGpF,MAAM,UAAU,4BAA4B,CAAC,KAAc;IACzD,OAAO,8BAA8B,CAAC,QAAQ,CAAC,KAAmC,CAAC,CAAC;AACtF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAU,CAAC;AAGrF,MAAM,UAAU,6BAA6B,CAC3C,KAAc;IAEd,OAAO,+BAA+B,CAAC,QAAQ,CAAC,KAAoC,CAAC,CAAC;AACxF,CAAC;AAeD,8EAA8E;AAC9E,MAAM,UAAU,2BAA2B,CACzC,KAAoD;IAEpD,OAAO,KAAK,CAAC,KAAK,IAAI,MAAM,CAAC;AAC/B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gCAAgC,CAC9C,IAAiC,EACjC,KAAkC;IAElC,IAAI,IAAI,KAAK,OAAO,IAAI,KAAK,KAAK,OAAO;QAAE,OAAO,OAAO,CAAC;IAC1D,IAAI,IAAI,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAChE,OAAO,MAAM,CAAC;AAChB,CAAC;AAwBD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sCAAsC,GAAG,CAAC,YAAY,EAAE,gBAAgB,CAAU,CAAC;AAIhG;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2CAA2C,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAU,CAAC;AA2DvF,MAAM,CAAC,MAAM,6BAA6B,GAAyC;IACjF,KAAK;IACL,QAAQ;IACR,OAAO;CACR,CAAC;AAkQF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,UAAU;IACV,MAAM;IACN,WAAW;IACX,KAAK;IACL,YAAY;CACJ,CAAC;AAIX;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,uCAAuC,GAAG,kCAAkC,CAAC;AAE1F,MAAM,UAAU,4BAA4B,CAAC,KAAc;IACzD,OAAO,8BAA8B,CAAC,QAAQ,CAAC,KAAmC,CAAC,CAAC;AACtF,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,KAAc;IAC3D,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,uCAAuC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qCAAqC,CACnD,UAA+C;IAE/C,IAAI,CAAC,UAAU;QAAE,OAAO,SAAS,CAAC;IAClC,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,8BAA8B,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,8BAA8B,CAAC,KAAK,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACjE,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7D,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,6BAA6B,CAAC,MAA+B;IAC3E,OAAO,8BAA8B,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;SAC7E,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;SACrC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

package/dist/contracts/slots.d.ts

@@ -1,6 +1,6 @@
 import type { RecipeRuntimeCapabilityDeclaration } from '../recipe/common.js';
 import type { AgentContextSummary, SlotAgent } from './agents.js';
-import type { ResourceRollup } from './resources.js';
+import type { ResourceRollup, ResourceWatchRuntimeStats } from './resources.js';
 import type { RunLane } from './runs.js';
 export type SlotLifecycle = 'ready' | 'busy' | 'held' | 'manual' | 'disabled';
 /**
@@ -43,6 +43,13 @@ export interface SlotStatus {
     project: string;
     health: SlotHealth;
     branch: string;
+    /**
+     * The commit HEAD points at, as the last fleet refresh saw it. Recorded
+     * alongside `branch` because a detached checkout reports `branch` as the
+     * literal `HEAD`, which identifies nothing on its own — dispatch needs the
+     * commit to tell one detached slot from another.
+     */
+    headSha?: string;
     /** Pool tmux/session id — used to resolve slot_tracking_branch templates. */
     session?: string;
     /** Slot checkout path from pool config. */
@@ -120,6 +127,44 @@ export type { ActiveResourcePointer, SlotActionDefinition, SlotActionMode, SlotA
 export type { SlotRunHistoryEntry } from './runs.js';
 export type ThermalPressure = 'nominal' | 'fair' | 'serious' | 'critical';
 export type Headroom = 'green' | 'yellow' | 'red';
+export interface NodePressureRatios {
+    cpu: number;
+    memory: number;
+    disk: number;
+    load1?: number;
+    load5?: number;
+}
+/** Ownership-safe process data: executable name/path only, never argv or environment. */
+export interface NodeProcessSample {
+    pid: number;
+    ppid: number;
+    cpuPercent: number;
+    rssBytes: number;
+    elapsedSeconds: number;
+    executable: string;
+}
+export interface NodeProcessSamplerHealth {
+    attempts: number;
+    executions: number;
+    failures: number;
+    skippedBusy: number;
+    skippedCadence: number;
+    lastDurationMs: number | null;
+    lastError?: string;
+}
+export interface NodeProcessInventory {
+    generation: string;
+    sampleId: number;
+    collectedAt: string;
+    processes: NodeProcessSample[];
+    totalProcesses: number;
+    maxEntries: number;
+    truncated: boolean;
+    ancestryTruncated?: boolean;
+    /** Health-only failed attempt; does not represent a process census. */
+    failed?: boolean;
+    health: NodeProcessSamplerHealth;
+}
 export interface NodeSystemMetrics {
     cpuPercent: number;
     memoryPercent: number;
@@ -128,9 +173,16 @@ export interface NodeSystemMetrics {
     diskPercent: number;
     loadAvg1: number;
     loadAvg5: number;
+    cpuCores?: number;
+    pressure?: NodePressureRatios;
     thermalPressure?: ThermalPressure;
+    resourceWatches?: ResourceWatchRuntimeStats;
     collectedAt: string;
 }
+/** Private node→gateway sample; process census is never part of MachineHealth.system. */
+export interface NodeMetricsSample extends NodeSystemMetrics {
+    processInventory?: NodeProcessInventory;
+}
 export interface MachineHealth {
     machine: string;
     online: boolean;

package/dist/contracts/slots.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../src/contracts/slots.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../src/contracts/slots.ts"],"names":[],"mappings":"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"}

package/dist/contracts/template-placeholders.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `{{NAME}}` placeholder guard shared by every template renderer (task writer,
+ * agent-runtime task init, prompt templates). Pure string functions: no slot or
+ * project coupling, so a harness can render the same template a control plane
+ * renders and fail on the same unknown token.
+ */
+/** Full {{...}} tokens present in the text, including malformed names. */
+export declare function collectPlaceholderTokens(text: string): Set<string>;
+export declare function assertNoUnknownPlaceholders(template: string, known: Iterable<string>, source: string): void;
+/**
+ * Substitute `{{KEY}}` with `vars[KEY]` after the guard. Values are inserted
+ * verbatim and never re-expanded; a value that itself contains `{{...}}` is the
+ * caller's responsibility (the slot-config renderer rejects such values).
+ */
+export declare function renderTemplatePlaceholders(template: string, vars: Record<string, string>, source?: string): string;
+//# sourceMappingURL=template-placeholders.d.ts.map

package/dist/contracts/template-placeholders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-placeholders.d.ts","sourceRoot":"","sources":["../../src/contracts/template-placeholders.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,0EAA0E;AAC1E,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAElE;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,EACvB,MAAM,EAAE,MAAM,GACb,IAAI,CAYN;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,MAAM,SAAa,GAClB,MAAM,CAOR"}

package/dist/contracts/template-placeholders.js

@@ -0,0 +1,39 @@
+/**
+ * `{{NAME}}` placeholder guard shared by every template renderer (task writer,
+ * agent-runtime task init, prompt templates). Pure string functions: no slot or
+ * project coupling, so a harness can render the same template a control plane
+ * renders and fail on the same unknown token.
+ */
+// Any double-brace token, valid identifier or not — a malformed name like
+// {{foo-bar}} can never be substituted, so it must fail the guard rather
+// than slip through an identifier-only scan.
+const PLACEHOLDER_TOKEN_RE = /\{\{[^{}\n]+\}\}/g;
+/** Full {{...}} tokens present in the text, including malformed names. */
+export function collectPlaceholderTokens(text) {
+    return new Set(Array.from(text.matchAll(PLACEHOLDER_TOKEN_RE), (match) => match[0]));
+}
+export function assertNoUnknownPlaceholders(template, known, source) {
+    const knownSet = known instanceof Set ? known : new Set(known);
+    const unknown = [...collectPlaceholderTokens(template)].filter((token) => {
+        const name = token.slice(2, -2);
+        return !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || !knownSet.has(name);
+    });
+    if (unknown.length > 0) {
+        throw new Error(`${source} references placeholder(s) with no expansion value: ${unknown.join(', ')} — ` +
+            `supply the variable or remove the placeholder from the template`);
+    }
+}
+/**
+ * Substitute `{{KEY}}` with `vars[KEY]` after the guard. Values are inserted
+ * verbatim and never re-expanded; a value that itself contains `{{...}}` is the
+ * caller's responsibility (the slot-config renderer rejects such values).
+ */
+export function renderTemplatePlaceholders(template, vars, source = 'template') {
+    assertNoUnknownPlaceholders(template, Object.keys(vars), source);
+    let content = template;
+    for (const [key, value] of Object.entries(vars)) {
+        content = content.replaceAll(`{{${key}}}`, value);
+    }
+    return content;
+}
+//# sourceMappingURL=template-placeholders.js.map

package/dist/contracts/template-placeholders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-placeholders.js","sourceRoot":"","sources":["../../src/contracts/template-placeholders.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,0EAA0E;AAC1E,yEAAyE;AACzE,6CAA6C;AAC7C,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AAEjD,0EAA0E;AAC1E,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACvF,CAAC;AAED,MAAM,UAAU,2BAA2B,CACzC,QAAgB,EAChB,KAAuB,EACvB,MAAc;IAEd,MAAM,QAAQ,GAAG,KAAK,YAAY,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC/D,MAAM,OAAO,GAAG,CAAC,GAAG,wBAAwB,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QACvE,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAChC,OAAO,CAAC,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,uDAAuD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;YACrF,iEAAiE,CACpE,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,QAAgB,EAChB,IAA4B,EAC5B,MAAM,GAAG,UAAU;IAEnB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;IACjE,IAAI,OAAO,GAAG,QAAQ,CAAC;IACvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}