@theford/runly 0.0.0-stage → 0.20.0

package/dist/core/manifest.js

@@ -0,0 +1,179 @@
+import { readFileSync, existsSync, realpathSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { basename, dirname, join, resolve } from 'node:path';
+import { parse } from 'yaml';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { BrokerError, safeJoin } from './util.js';
+/** The build line and its `when:` globs, whichever form the manifest used. */
+export function buildOf(spec) {
+    if (spec.build === undefined)
+        return undefined;
+    if (typeof spec.build === 'string')
+        return { run: spec.build };
+    return { run: spec.build.run, when: spec.build.when, serial: spec.build.serial };
+}
+/** The output globs and how they are compared, whichever form the manifest used. */
+export function outputsOf(spec) {
+    const o = spec.outputs;
+    if (o === undefined)
+        return { paths: [], compare: 'stat' };
+    if (typeof o === 'string')
+        return { paths: [o], compare: 'stat' };
+    if (Array.isArray(o))
+        return { paths: o, compare: 'stat' };
+    return { paths: o.paths, compare: o.compare ?? 'stat' };
+}
+/** A rule's declared `outputs:` as a list (empty when it declares none). */
+export const upkeepOutputs = (rule) => rule.outputs === undefined ? [] : Array.isArray(rule.outputs) ? rule.outputs : [rule.outputs];
+/**
+ * One shape for consumers regardless of which form the manifest used: `[]` when no
+ * login is declared, otherwise every declared login in order. A single-object
+ * manifest yields exactly one entry, so callers never branch on the manifest form.
+ */
+export function normalizeLogins(spec) {
+    if (!spec)
+        return [];
+    return Array.isArray(spec) ? spec : [spec];
+}
+/**
+ * One-line warnings for manifest sections runly accepts but no longer acts on.
+ * The CLI prints them to stderr; the manifest still loads.
+ */
+export function manifestDeprecations(manifest, file = 'runly.yml') {
+    const out = [];
+    if (manifest.checks !== undefined) {
+        out.push(`${file} declares 'checks:', which is ignored since 'runly run' was removed (decision 0032) — run your checks yourself, with 'runly ctx --env' for the environment`);
+    }
+    return out;
+}
+/** The manifest's file name for a message: the one actually loaded. */
+export const manifestFileOf = (stack) => stack?.file ?? 'runly.yml';
+const schemaPath = () => join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'schema', 'runly.schema.json');
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let validator;
+function validate(data) {
+    if (!validator) {
+        // Loaded on first use: ajv and the schema compile cost ~100 ms, which a
+        // CLI verb paid on every invocation although the daemon validates the
+        // manifest it acts on anyway. ajv is CJS; the constructor lands on
+        // .default under real ESM interop.
+        const Ajv2020 = createRequire(import.meta.url)('ajv/dist/2020.js');
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const AjvCtor = Ajv2020.default ?? Ajv2020;
+        const ajv = new AjvCtor({ allErrors: true });
+        validator = ajv.compile(JSON.parse(readFileSync(schemaPath(), 'utf8')));
+    }
+    if (!validator(data)) {
+        throw new BrokerError('work-error', `the runly manifest is invalid: ${JSON.stringify(validator.errors)}`, 'manifest');
+    }
+}
+/** Walk upward from cwd to the nearest manifest. */
+/** runly.yml is canonical; backlot.yml and stack.yaml stay accepted so
+ * existing consumers survive the upgrade. When several exist, runly.yml wins —
+ * a rename, not a coin toss. */
+export const MANIFEST_NAMES = ['runly.yml', 'backlot.yml', 'stack.yaml'];
+function manifestIn(dir) {
+    for (const name of MANIFEST_NAMES) {
+        if (existsSync(join(dir, name)))
+            return join(dir, name);
+    }
+    return null;
+}
+export function canonicalDirectory(from) {
+    try {
+        return realpathSync(resolve(from));
+    }
+    catch {
+        throw new BrokerError('work-error', `cannot resolve project directory '${from}'`, 'manifest');
+    }
+}
+const IDENTITY_HASH_LENGTH = 8;
+export function stackIdentity(name, root) {
+    return `${name}-${createHash('sha256').update(root).digest('base64url').slice(0, IDENTITY_HASH_LENGTH)}`;
+}
+export function findStackRoot(from) {
+    let dir = canonicalDirectory(from);
+    for (;;) {
+        if (manifestIn(dir))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new BrokerError('work-error', `no runly.yml (or backlot.yml / stack.yaml) found from ${from} upward`, 'manifest');
+        }
+        dir = parent;
+    }
+}
+/**
+ * Find, read and validate the manifest from `from` upward. `validate: false`
+ * skips the schema check — only for a CLI-side read whose result the daemon
+ * re-reads and validates before acting on it (the deprecation warnings).
+ */
+export function loadStack(from, opts = {}) {
+    const root = findStackRoot(from);
+    const file = manifestIn(root);
+    if (!file)
+        throw new BrokerError('work-error', `no runly.yml (or backlot.yml / stack.yaml) in ${root}`, 'manifest');
+    const manifest = parse(readFileSync(file, 'utf8'));
+    if (opts.validate !== false)
+        validate(manifest);
+    // A path that escapes the worktree is refused at load, whether or not an
+    // upkeep rule ever makes runly read it: it is never a legitimate source file.
+    for (const inc of manifest.sync?.include ?? [])
+        safeJoin(root, inc, 'sync.include');
+    checkCopiesOnly(manifest, basename(file));
+    // Identity = absolute root + declared name; filesystem-safe. Hash the WHOLE
+    // path: slicing base64url(root) kept only the last ~6 bytes, so sibling
+    // worktrees like agent-1/myapp and agent-2/myapp collided into one pool.
+    const id = stackIdentity(manifest.name, root);
+    return { manifest, root, id, file: basename(file) };
+}
+/** Every string in `value`, with the manifest path it sits at (`services.web.ready.cmd`). */
+function* stringsIn(value, path) {
+    if (typeof value === 'string')
+        yield [path, value];
+    else if (Array.isArray(value))
+        for (const [i, v] of value.entries())
+            yield* stringsIn(v, `${path}[${i}]`);
+    else if (value && typeof value === 'object')
+        for (const [k, v] of Object.entries(value))
+            yield* stringsIn(v, path ? `${path}.${k}` : k);
+}
+/**
+ * A `copies_only` datastore (decision 0039) has no environment namespace, so
+ * nothing templated against an environment can name one: any field outside
+ * `datastores:` that templates it — a service's run, build, env or ready:,
+ * `auth.token`, a preview setting — is refused at load, naming the field and
+ * the alternative.
+ */
+function checkCopiesOnly(manifest, file) {
+    const only = Object.entries(manifest.datastores ?? {}).filter(([, spec]) => spec.copies_only === true).map(([ds]) => ds);
+    if (only.length === 0)
+        return;
+    const rest = Object.fromEntries(Object.entries(manifest).filter(([k]) => k !== 'datastores'));
+    for (const ds of only) {
+        const escaped = ds.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const ref = new RegExp(`\\{\\{\\s*datastores\\.${escaped}\\.`);
+        for (const [where, text] of stringsIn(rest, '')) {
+            if (!ref.test(text))
+                continue;
+            const svc = /^services\.([^.[]+)\./.exec(where)?.[1];
+            throw new BrokerError('work-error', `${svc !== undefined ? `service '${svc}'` : where} templates datastore '${ds}', which is copies_only in ${file}${svc !== undefined ? ` (at ${where})` : ''} — an environment never has one; take a copy with 'runly db new ${ds}' (or 'runly db with ${ds} -- <cmd>'), or drop copies_only`, 'manifest');
+        }
+    }
+}
+/** The datastores an environment provisions: every declared one except `copies_only` (decision 0039). */
+export function envDatastoreNames(manifest) {
+    return Object.entries(manifest.datastores ?? {}).filter(([, spec]) => spec.copies_only !== true).map(([name]) => name);
+}
+/** The declared default preset, if any — one value, whichever form the manifest used. */
+export function declaredDefaultPreset(ds) {
+    const d = ds.default_preset;
+    if (d === undefined)
+        return undefined;
+    return typeof d === 'string' ? d : (d.session ?? d.run);
+}
+export function defaultPreset(ds) {
+    return declaredDefaultPreset(ds) ?? ds.presets?.[0] ?? 'default';
+}
+//# sourceMappingURL=manifest.js.map

package/dist/core/manifest.js.map

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

package/dist/core/namespaces.d.ts

@@ -0,0 +1,7 @@
+/** Postgres's identifier limit; every truncated namespace is exactly this long. */
+export declare const NS_LIMIT = 63;
+export declare function recordedNamespaces(): Map<string, string>;
+/** Remember that `ns` (a truncated name) belongs to `stack`. A short name needs no record: its prefix says it. */
+export declare function recordNamespace(ns: string, stack: string): void;
+/** Forget `ns` once it is dropped. */
+export declare function forgetNamespace(ns: string): void;

package/dist/core/namespaces.js

@@ -0,0 +1,59 @@
+/**
+ * Server-side namespaces whose names do not carry their stack (decision 0037).
+ *
+ * A datastore namespace is `backlot_<env or stack>_<name>`, cut to Postgres's
+ * 63 bytes with a hash at the end. For a long stack id the cut lands inside
+ * the stack id, so `pool doctor` could not tell the namespace was this state
+ * root's from its name, called it foreign and never dropped it. Every
+ * namespace that is cut is therefore recorded here, with its stack, before it
+ * is created; doctor reads the record next to the name prefixes.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stateRoot } from './paths.js';
+/** Postgres's identifier limit; every truncated namespace is exactly this long. */
+export const NS_LIMIT = 63;
+const file = () => join(stateRoot(), 'namespaces.json');
+export function recordedNamespaces() {
+    try {
+        const raw = JSON.parse(readFileSync(file(), 'utf8'));
+        return new Map(Object.entries(raw).filter(([, v]) => typeof v === 'string'));
+    }
+    catch {
+        return new Map();
+    }
+}
+function save(all) {
+    mkdirSync(stateRoot(), { recursive: true });
+    const tmp = `${file()}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(Object.fromEntries(all)));
+    renameSync(tmp, file());
+}
+/** Remember that `ns` (a truncated name) belongs to `stack`. A short name needs no record: its prefix says it. */
+export function recordNamespace(ns, stack) {
+    if (ns.length < NS_LIMIT)
+        return;
+    const all = recordedNamespaces();
+    if (all.get(ns) === stack)
+        return;
+    all.set(ns, stack);
+    try {
+        save(all);
+    }
+    catch {
+        /* best effort: doctor then reports it as foreign, as before */
+    }
+}
+/** Forget `ns` once it is dropped. */
+export function forgetNamespace(ns) {
+    const all = recordedNamespaces();
+    if (!all.delete(ns))
+        return;
+    try {
+        save(all);
+    }
+    catch {
+        /* best effort */
+    }
+}
+//# sourceMappingURL=namespaces.js.map

package/dist/core/namespaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespaces.js","sourceRoot":"","sources":["../../src/core/namespaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,mFAAmF;AACnF,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,CAAC;AAE3B,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,iBAAiB,CAAC,CAAC;AAExD,MAAM,UAAU,kBAAkB;IAChC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,CAA2B,CAAC;QAC/E,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,GAAG,EAAE,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,IAAI,CAAC,GAAwB;IACpC,SAAS,CAAC,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAG,GAAG,IAAI,EAAE,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;IAC3C,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC5D,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;AAC1B,CAAC;AAED,kHAAkH;AAClH,MAAM,UAAU,eAAe,CAAC,EAAU,EAAE,KAAa;IACvD,IAAI,EAAE,CAAC,MAAM,GAAG,QAAQ;QAAE,OAAO;IACjC,MAAM,GAAG,GAAG,kBAAkB,EAAE,CAAC;IACjC,IAAI,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,KAAK;QAAE,OAAO;IAClC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACnB,IAAI,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;IACjE,CAAC;AACH,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,eAAe,CAAC,EAAU;IACxC,MAAM,GAAG,GAAG,kBAAkB,EAAE,CAAC;IACjC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAAE,OAAO;IAC5B,IAAI,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,iBAAiB;IACnB,CAAC;AACH,CAAC"}

package/dist/core/paths.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Per-machine state root (decision 0009). BACKLOT_STATE_DIR overrides — the
+ * isolation knob every integration test uses.
+ *
+ * Created 0700 and chmod-enforced every call: the daemon socket lives here and
+ * has NO application-level auth (README "Security model" — filesystem
+ * permissions ARE the auth), so no other local user may traverse in. We chmod
+ * even when the dir already exists, to repair a too-open pre-existing dir
+ * (e.g. one made before this hardening, or via a loose umask).
+ */
+export declare function stateRoot(): string;
+export declare const socketPath: () => string;
+export declare const pidPath: () => string;
+/**
+ * The singleton-election lock. Separate from daemon.pid, which stays a bare
+ * number for anything that reads it; this one carries the identity needed to
+ * tell a live holder from a crashed one.
+ */
+export declare const lockPath: () => string;
+export declare const journalPath: () => string;
+export declare const envsRoot: () => string;
+export declare const templatesRoot: () => string;
+/** Private directories of `runly db` copies whose namespace is a file (sqlite), one per copy (decision 0034). */
+export declare const dbCopiesRoot: () => string;
+/**
+ * Per-worktree state (decision 0032): the trigger-file hash cache and the
+ * worktree's upkeep ledger. It describes the caller's worktree, which
+ * every environment of that stack runs in, so it is keyed by stack id rather
+ * than by environment — and lives here, never inside the worktree.
+ */
+export declare const worktreesRoot: () => string;

package/dist/core/paths.js

@@ -0,0 +1,65 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, chmodSync } from 'node:fs';
+/**
+ * Per-machine state root (decision 0009). BACKLOT_STATE_DIR overrides — the
+ * isolation knob every integration test uses.
+ *
+ * Created 0700 and chmod-enforced every call: the daemon socket lives here and
+ * has NO application-level auth (README "Security model" — filesystem
+ * permissions ARE the auth), so no other local user may traverse in. We chmod
+ * even when the dir already exists, to repair a too-open pre-existing dir
+ * (e.g. one made before this hardening, or via a loose umask).
+ */
+export function stateRoot() {
+    const root = process.env.BACKLOT_STATE_DIR ??
+        join(process.env.XDG_STATE_HOME ?? join(homedir(), '.local', 'state'), 'backlot');
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(root, 0o700);
+    }
+    catch {
+        /* not the owner — leave it; the socket chmod below is the real gate */
+    }
+    return root;
+}
+/**
+ * AF_UNIX `sun_path` is 104 bytes on macOS and 108 on Linux (including the
+ * NUL); we enforce the tighter leg. Over the limit the OS does NOT error — it
+ * silently truncates (verified on macOS), and because client and daemon
+ * truncate identically everything appears to work while actually binding a
+ * socket that collides with any other state dir sharing the 103-byte prefix.
+ */
+const SUN_PATH_MAX = 103;
+export const socketPath = () => {
+    const sock = join(stateRoot(), 'daemon.sock');
+    const bytes = Buffer.byteLength(sock);
+    if (bytes > SUN_PATH_MAX) {
+        // "socket" in the message keeps classifyClientError reading this as
+        // infra-error — a bad state dir is never fixed by recycling an environment.
+        throw new Error(`unix socket path '${sock}' is ${bytes} bytes — over the ${SUN_PATH_MAX}-byte AF_UNIX sun_path limit ` +
+            `(104 on macOS incl. NUL), where the OS silently truncates and state dirs collide. ` +
+            `Point BACKLOT_STATE_DIR at a shorter path.`);
+    }
+    return sock;
+};
+export const pidPath = () => join(stateRoot(), 'daemon.pid');
+/**
+ * The singleton-election lock. Separate from daemon.pid, which stays a bare
+ * number for anything that reads it; this one carries the identity needed to
+ * tell a live holder from a crashed one.
+ */
+export const lockPath = () => join(stateRoot(), 'daemon.lock');
+export const journalPath = () => join(stateRoot(), 'journal.db');
+export const envsRoot = () => join(stateRoot(), 'envs');
+export const templatesRoot = () => join(stateRoot(), 'templates');
+/** Private directories of `runly db` copies whose namespace is a file (sqlite), one per copy (decision 0034). */
+export const dbCopiesRoot = () => join(stateRoot(), 'dbs');
+/**
+ * Per-worktree state (decision 0032): the trigger-file hash cache and the
+ * worktree's upkeep ledger. It describes the caller's worktree, which
+ * every environment of that stack runs in, so it is keyed by stack id rather
+ * than by environment — and lives here, never inside the worktree.
+ */
+export const worktreesRoot = () => join(stateRoot(), 'worktrees');
+//# sourceMappingURL=paths.js.map

package/dist/core/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,IAAI,GACR,OAAO,CAAC,GAAG,CAAC,iBAAiB;QAC7B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,CAAC;IACpF,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAClD,IAAI,CAAC;QACH,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;IACzE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,YAAY,GAAG,GAAG,CAAC;AAEzB,MAAM,CAAC,MAAM,UAAU,GAAG,GAAW,EAAE;IACrC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,EAAE,aAAa,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,KAAK,GAAG,YAAY,EAAE,CAAC;QACzB,oEAAoE;QACpE,4EAA4E;QAC5E,MAAM,IAAI,KAAK,CACb,qBAAqB,IAAI,QAAQ,KAAK,qBAAqB,YAAY,+BAA+B;YACpG,oFAAoF;YACpF,4CAA4C,CAC/C,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AACF,MAAM,CAAC,MAAM,OAAO,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,YAAY,CAAC,CAAC;AACrE;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,aAAa,CAAC,CAAC;AACvE,MAAM,CAAC,MAAM,WAAW,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,YAAY,CAAC,CAAC;AACzE,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,MAAM,CAAC,CAAC;AAChE,MAAM,CAAC,MAAM,aAAa,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,WAAW,CAAC,CAAC;AAC1E,iHAAiH;AACjH,MAAM,CAAC,MAAM,YAAY,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,KAAK,CAAC,CAAC;AACnE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,WAAW,CAAC,CAAC"}

package/dist/core/policy.d.ts

@@ -0,0 +1,94 @@
+export interface Policy {
+    /** Machine-wide ceiling across ALL stacks (the memory heuristic is per host). */
+    poolMaxTotal: number;
+    sessionTtlMs: number;
+    idleTtlMs: number;
+    waitMs: number;
+    /** Retention knobs (task: disk sweep). */
+    logCapBytes: number;
+    /** Templates kept per stack/datastore/preset beyond the referenced ones (decision 0037). */
+    templatesKeep: number;
+    /** How long an unreferenced, superseded template survives before it is dropped (decision 0037). */
+    templateGraceMs: number;
+    /** A service with no client bytes and no runly verb for this long is stopped (decision 0035). */
+    serviceIdleMs: number;
+    /** A dead tether is believed only after this long (decision 0035). */
+    tetherGraceMs: number;
+    /**
+     * An environment nobody leases is torn down (services, data, ports) after
+     * this long without activity (0.19, BACKLOT_UNLEASED_TTL, default 24h,
+     * `off` never). Templates and the worktree's records stay, so the next
+     * `up` there restores rather than bakes and skips fresh upkeep.
+     */
+    unleasedTtlMs: number;
+    /** The server-wide load budget (decision 0036). */
+    budget: Budget;
+}
+/**
+ * The load budget (decision 0036): what runly may commit on this box across
+ * every stack. `enabled: false` (BACKLOT_BUDGET=off) admits everything.
+ */
+export interface Budget {
+    enabled: boolean;
+    /** Declared memory runly may have committed at once (running services + builds in flight). */
+    memoryBytes: number;
+    /** Declared cores runly may have committed at once. */
+    cpu: number;
+    /** Linux: MemAvailable must stay above this after a start (headroom for non-runly work). */
+    reserveBytes: number;
+    /**
+     * Linux with PSI: a start waits while runnable work stalled on the CPU at
+     * least this percent of the time over both the last 10 s and the last 60 s
+     * (`/proc/pressure/cpu` "some"). 100 or more switches the gate off.
+     */
+    cpuPressure: number;
+    /** Without PSI (macOS, old kernels): a start waits while the 1-minute load average exceeds this many times the core count. */
+    loadPerCore: number;
+    /** How long an `up` waits in the queue before it fails. */
+    waitMs: number;
+    /** How many requests may wait at once; the next one is refused. */
+    maxQueue: number;
+    /** What an undeclared service costs while running, and while building. */
+    defaultRun: {
+        memoryBytes: number;
+        cpu: number;
+    };
+    defaultBuild: {
+        memoryBytes: number;
+        cpu: number;
+    };
+}
+interface ConfigFile {
+    serviceIdleMs?: number;
+    tetherGraceMs?: number;
+    /** A duration (`24h`, `90m`, seconds as a number) or `off`. */
+    unleasedTtl?: string | number;
+    templateGraceMs?: number;
+    budget?: Partial<Budget> & {
+        memory?: string | number;
+        reserve?: string | number;
+    };
+    poolMaxTotal?: number;
+    sessionTtlMs?: number;
+    idleTtlMs?: number;
+    waitMs?: number;
+    logCapBytes?: number;
+    templatesKeep?: number;
+}
+/**
+ * The machine-wide cap on environment ROWS (BACKLOT_POOL_MAX_TOTAL).
+ *
+ * Since 0.16 (decision 0036) the load budget bounds what RUNS, so this cap
+ * only bounds what is HELD — ports, data directories, database namespaces —
+ * by environments that may be idle-stopped and cost nothing running:
+ * 2 x cores, clamped to [4, 64] (32 on a 16-core box). With the budget
+ * switched off (BACKLOT_BUDGET=off) nothing else bounds concurrent load, and
+ * the pre-0.16 heuristic applies: min(cores/2, memGB/4) clamped to [2, 8].
+ */
+export declare function poolMaxHeuristic(budgetEnabled?: boolean): number;
+/** The pre-0.16 load-bounding heuristic, used when the budget is off. */
+export declare function legacyPoolMaxHeuristic(): number;
+/** The defaults leave headroom for work that is not runly's (decision 0036). */
+export declare function budgetPolicy(f?: ConfigFile): Budget;
+export declare function policy(): Policy;
+export {};

package/dist/core/policy.js

@@ -0,0 +1,122 @@
+/**
+ * Engine policy — NEVER repo knowledge (the manifest carries none of this).
+ * Precedence per knob: env var > $STATE_DIR/config.json > heuristic/default.
+ */
+import { readFileSync } from 'node:fs';
+import { cpus, totalmem } from 'node:os';
+import { join } from 'node:path';
+import { stateRoot } from './paths.js';
+import { parseDuration, parseSize } from './units.js';
+function configFile() {
+    try {
+        return JSON.parse(readFileSync(join(stateRoot(), 'config.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The machine-wide cap on environment ROWS (BACKLOT_POOL_MAX_TOTAL).
+ *
+ * Since 0.16 (decision 0036) the load budget bounds what RUNS, so this cap
+ * only bounds what is HELD — ports, data directories, database namespaces —
+ * by environments that may be idle-stopped and cost nothing running:
+ * 2 x cores, clamped to [4, 64] (32 on a 16-core box). With the budget
+ * switched off (BACKLOT_BUDGET=off) nothing else bounds concurrent load, and
+ * the pre-0.16 heuristic applies: min(cores/2, memGB/4) clamped to [2, 8].
+ */
+export function poolMaxHeuristic(budgetEnabled = budgetOn()) {
+    if (budgetEnabled)
+        return Math.max(4, Math.min(64, (cpus().length || 1) * 2));
+    return legacyPoolMaxHeuristic();
+}
+/** The pre-0.16 load-bounding heuristic, used when the budget is off. */
+export function legacyPoolMaxHeuristic() {
+    const byCores = Math.floor(cpus().length / 2);
+    const byMem = Math.floor(totalmem() / (4 * 1024 ** 3));
+    return Math.max(2, Math.min(8, Math.min(byCores || 1, byMem || 1)));
+}
+function budgetOn() {
+    const v = (process.env.BACKLOT_BUDGET ?? '').trim().toLowerCase();
+    if (v === 'off' || v === '0' || v === 'false')
+        return false;
+    return configFile().budget?.enabled !== false;
+}
+const num = (envVar, fileVal, fallback) => {
+    const e = process.env[envVar];
+    if (e !== undefined && e !== '')
+        return Number(e);
+    if (fileVal !== undefined)
+        return fileVal;
+    return fallback;
+};
+/** A duration knob: env var or config value as `24h`/`90m`/seconds, or `off` (Infinity). */
+const duration = (envVar, fileVal, fallback) => {
+    const e = process.env[envVar];
+    const fromEnv = e !== undefined && e !== '' ? parseDuration(e) : undefined;
+    if (fromEnv !== undefined)
+        return fromEnv;
+    const fromFile = fileVal !== undefined ? parseDuration(fileVal) : undefined;
+    return fromFile ?? fallback;
+};
+/** A size knob: env var or config value as bytes or `2G`. */
+const size = (envVar, fileVal, fallback) => {
+    const e = process.env[envVar];
+    if (e !== undefined && e !== '')
+        return parseSize(e) ?? fallback;
+    if (fileVal !== undefined)
+        return parseSize(fileVal) ?? fallback;
+    return fallback;
+};
+/** The defaults leave headroom for work that is not runly's (decision 0036). */
+export function budgetPolicy(f = configFile()) {
+    const b = f.budget ?? {};
+    const total = totalmem();
+    const cores = cpus().length || 1;
+    const off = (process.env.BACKLOT_BUDGET ?? '').toLowerCase();
+    return {
+        enabled: !(off === 'off' || off === '0' || off === 'false') && b.enabled !== false,
+        memoryBytes: size('BACKLOT_BUDGET_MEMORY', b.memory ?? b.memoryBytes, Math.floor(total * 0.7)),
+        cpu: num('BACKLOT_BUDGET_CPU', b.cpu, cores * 1.5),
+        reserveBytes: size('BACKLOT_BUDGET_RESERVE', b.reserve ?? b.reserveBytes, Math.max(2 * 1024 ** 3, Math.floor(total * 0.1))),
+        // Calibrated on a 16-core box shared by ~10 agents: a load of 25-43 (the
+        // old 2 x cores gate) held no-op ups for minutes while PSI "some" sat at
+        // 20-40%, i.e. the CPUs still had room. 70% over 10 s AND 60 s is a box
+        // that is genuinely saturated now and has been for a minute.
+        cpuPressure: num('BACKLOT_BUDGET_CPU_PRESSURE', b.cpuPressure, 70),
+        loadPerCore: num('BACKLOT_BUDGET_LOAD_PER_CORE', b.loadPerCore, 4),
+        waitMs: num('BACKLOT_BUDGET_WAIT_MS', b.waitMs, 10 * 60_000),
+        maxQueue: num('BACKLOT_BUDGET_MAX_QUEUE', b.maxQueue, 64),
+        defaultRun: { memoryBytes: 512 * 1024 ** 2, cpu: 0.5 },
+        defaultBuild: { memoryBytes: 1024 ** 3, cpu: 1 },
+    };
+}
+export function policy() {
+    const f = configFile();
+    const idleTtlMs = num('BACKLOT_IDLE_TTL_MS', f.idleTtlMs, 30 * 60_000);
+    return {
+        // The machine-wide ceiling: the heuristic is derived from this host's cores
+        // and memory, so it is a budget for the host, not per project. (There is no
+        // per-stack ceiling: a worktree has exactly one environment, decision 0032.)
+        // Raise it deliberately if the host can take it.
+        poolMaxTotal: num('BACKLOT_POOL_MAX_TOTAL', f.poolMaxTotal, poolMaxHeuristic()),
+        // There is no data-only ceiling any more (decision 0034): a database
+        // without an application is a `runly db` copy, which is not an
+        // environment and answers to no pool cap. BACKLOT_POOL_MAX_DATA_ONLY and
+        // `poolMaxDataOnly` are ignored.
+        sessionTtlMs: num('BACKLOT_LEASE_TTL_MS', f.sessionTtlMs, 30 * 60_000),
+        idleTtlMs,
+        waitMs: num('BACKLOT_WAIT_MS', f.waitMs, 60_000),
+        // One rotation per file (decision 0038): a service keeps up to twice this.
+        logCapBytes: num('BACKLOT_LOG_CAP_BYTES', f.logCapBytes, 20 * 1024 * 1024),
+        // Per stack/datastore/preset now (decision 0037), not per stack: the
+        // newest template of each, plus every one an environment or copy uses.
+        templatesKeep: num('BACKLOT_TEMPLATES_KEEP', f.templatesKeep, 1),
+        templateGraceMs: num('BACKLOT_TEMPLATE_GRACE_MS', f.templateGraceMs, 60 * 60_000),
+        serviceIdleMs: num('BACKLOT_SERVICE_IDLE_MS', f.serviceIdleMs, 10 * 60_000),
+        tetherGraceMs: num('BACKLOT_TETHER_GRACE_MS', f.tetherGraceMs, 60_000),
+        unleasedTtlMs: duration('BACKLOT_UNLEASED_TTL', f.unleasedTtl, 24 * 3_600_000),
+        budget: budgetPolicy(f),
+    };
+}
+//# sourceMappingURL=policy.js.map

package/dist/core/policy.js.map

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

package/dist/core/ports.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Is `port` genuinely free?
+ *
+ * Binding only 127.0.0.1 misses a foreign process listening on the WILDCARD
+ * address: on Linux that bind collides and reports busy, but on macOS it
+ * succeeds, so the "port occupied by a foreign process" guard never fired
+ * there and the service started into a port someone else already held.
+ * Probing the wildcard as well is what makes the two platforms agree.
+ */
+export declare function probeFree(port: number): Promise<boolean>;
+/**
+ * Port blocks (decision 0033). Three disjoint blocks, all below every common
+ * OS ephemeral range (Linux 32768–60999, macOS/BSD 49152–65535), so an
+ * outbound connection's source port can never sit on a port runly is about to
+ * hand out:
+ *
+ * - PUBLIC  20000–29999: what users, child services, `ctx` and tunnels see. The
+ *   daemon's proxy holds each one for the environment's lifetime.
+ * - INTERNAL 30000–31999: where a service actually listens, chosen fresh at
+ *   every start. Only the proxy and runly's own readiness probes connect here.
+ * - TUNNEL  32000–32767: tailnet HTTPS ports a preview publisher derives.
+ *
+ * Each is overridable (`BACKLOT_PORT_RANGE`, `BACKLOT_INTERNAL_PORT_RANGE`,
+ * `BACKLOT_TUNNEL_PORT_RANGE`, form `LO-HI`) for a box whose own layout
+ * collides; the daemon logs a warning when a block overlaps the ephemeral range
+ * it reads from /proc.
+ */
+export interface PortBlock {
+    lo: number;
+    hi: number;
+}
+export declare const DEFAULT_PUBLIC_BLOCK: PortBlock;
+export declare const DEFAULT_INTERNAL_BLOCK: PortBlock;
+export declare const DEFAULT_TUNNEL_BLOCK: PortBlock;
+export declare const publicBlock: () => PortBlock;
+export declare const internalBlock: () => PortBlock;
+export declare const tunnelBlock: () => PortBlock;
+export declare const inBlock: (port: number, block: PortBlock) => boolean;
+/**
+ * The OS ephemeral (outbound source-port) range. Linux publishes it; other
+ * platforms get the IANA range their kernels use by default.
+ */
+export declare function ephemeralRange(): PortBlock;
+/** Human-readable overlaps of the configured blocks with each other and the ephemeral range. */
+export declare function blockConflicts(): string[];
+/**
+ * The first port of `block` that is not in `taken`, not ephemeral, and probes
+ * free, scanning from a random offset so concurrent daemons (and a daemon
+ * restarted with an empty memory) do not all start at the bottom. Returns
+ * undefined when the block has nothing left — the caller names the block.
+ */
+export declare function allocateInBlock(block: PortBlock, taken: Set<number>, probe?: (port: number) => Promise<boolean>): Promise<number | undefined>;