@starci/hfs 5.2.0 → 5.4.0

package/runtime/scripts/lib/secret-records.d.mts

@@ -0,0 +1,13 @@
+/** The cache folder of the secrets family, relative to the cache directory. */
+export declare const SECRETS_FOLDER = "check/secrets";
+/** A file of the secrets folder in a tracked tree: `.starcistacks/cache/check/secrets/<area>.jsonl` (an area is a folder path, so the file may sit in subfolders), at the app root or below one. */
+export declare const SECRETS_CACHE_FILE: RegExp;
+/** The finding codes of the secrets family: plaintext secrets, sealed custody, untracked secret files. */
+export declare const SECRET_CODES: ReadonlySet<string>;
+/** The stored form of a finding message: the digest of the message. A message already in that form is kept. */
+export declare function messageDigest(message: string): string;
+/**
+ * The faults of the text of a file of the secrets folder: every line is a record that holds codes, paths, positions and digests, and nothing
+ * else. An empty list means the file carries no secret material by construction.
+ */
+export declare function secretRecordFaults(text: string): string[];

package/runtime/scripts/lib/secret-records.mjs

@@ -0,0 +1,83 @@
+// secret-records.mjs - the contract of the secrets family's records in the committed check cache (contexts/project/check-cache.md, "The secrets
+// records"). The cache is committed, so what the secrets family writes may never be secret material: a record holds codes, paths, positions
+// and hashes. The finding's rule is one of the family's codes, its message is the sha256 prefix of the message the run printed (the identity
+// the new / known / fixed comparison needs), and the record carries no `data`. The cache writer (hfs cache/secret-records.mjs) projects its
+// records to this form; the secret judgement of R06 (scripts/hfs/rules/secrets.mjs, shared by `starci app check` and the commit hook) judges a
+// staged or tracked file of the folder by `secretRecordFaults`, so the file is accepted by what it holds and never by where it sits.
+import { createHash } from 'node:crypto';
+/** The cache folder of the secrets family, relative to the cache directory. */
+export const SECRETS_FOLDER = 'check/secrets';
+/** A file of the secrets folder in a tracked tree: `.starcistacks/cache/check/secrets/<area>.jsonl` (an area is a folder path, so the file may sit in subfolders), at the app root or below one. */
+export const SECRETS_CACHE_FILE = /(?:^|\/)\.starcistacks\/cache\/check\/secrets\/.+\.jsonl$/;
+/** The finding codes of the secrets family: plaintext secrets, sealed custody, untracked secret files. */
+export const SECRET_CODES = new Set([
+    'HFS_PLAINTEXT_SECRET', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'HFS_LITE_SECRET_CUSTODY', 'HFS_IDENTITY_CUSTODY',
+    'HFS_AGE_KEY_CUSTODY', 'RT_SECRET_TRACKED', 'STACKS_SECRET_ENV_LITERAL', 'STACKS_SECRET_NOT_EXTERNAL', 'STACKS_SECRET_UNVERSIONED', 'SEALED_CUSTODY_LOCATION',
+    'APP_SECRET_IN_CI', 'CI_SECRET_SEALED', 'BE_LOG_SECRET', 'BE_SECRET_DEFAULT', 'HFS_DOCKER_SECRETS',
+]);
+/** The form a stored message takes: `sha256:` and the first 16 hex digits of the sha256 of the message. */
+const DIGEST = /^sha256:[0-9a-f]{16}$/;
+/** A path a record may name: a relative posix path without control characters, backslashes or colons, never absolute and never leaving the app. */
+const SAFE_PATH = /^(?!\/)(?!(?:.*\/)?\.\.(?:\/|$))[^\u0000-\u001f\\:]*$/u;
+/** The stored form of a finding message: the digest of the message. A message already in that form is kept. */
+export function messageDigest(message) {
+    return DIGEST.test(message) ? message : `sha256:${createHash('sha256').update(message).digest('hex').slice(0, 16)}`;
+}
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const isPath = (value) => typeof value === 'string' && SAFE_PATH.test(value);
+/** The faults of one parsed record of the secrets folder; an empty list is a record that carries no secret material. */
+function recordFaults(value, at) {
+    if (!isObject(value))
+        return [`${at} is not a record`];
+    const faults = [];
+    const extra = Object.keys(value).filter((key) => !['path', 'step', 'hash', 'findings'].includes(key));
+    if (extra.length > 0)
+        faults.push(`${at} carries ${extra.join(', ')}; a secrets record holds path, step, hash and findings only`);
+    if (!isPath(value['path']))
+        faults.push(`${at} path is not a relative posix path`);
+    if (value['step'] !== 'secrets')
+        faults.push(`${at} step is not "secrets"`);
+    if (typeof value['hash'] !== 'string' || !/^(?:[0-9a-f]{64}|absent)$/.test(value['hash']))
+        faults.push(`${at} hash is not a sha256`);
+    const findings = value['findings'];
+    if (!Array.isArray(findings))
+        return [...faults, `${at} findings is not a list`];
+    for (const finding of findings) {
+        if (!isObject(finding)) {
+            faults.push(`${at} holds a finding that is not an object`);
+            continue;
+        }
+        const keys = Object.keys(finding).sort().join(',');
+        if (keys !== 'column,line,message,path,rule')
+            faults.push(`${at} holds a finding with the keys ${keys}; a finding holds path, line, column, rule and message only`);
+        if (typeof finding['rule'] !== 'string' || !SECRET_CODES.has(finding['rule']))
+            faults.push(`${at} holds a finding whose rule is not a code of the secrets family`);
+        if (typeof finding['message'] !== 'string' || !DIGEST.test(finding['message']))
+            faults.push(`${at} holds a finding whose message is not a digest (sha256:<16 hex>)`);
+        if (!isPath(finding['path']))
+            faults.push(`${at} holds a finding whose path is not a relative posix path`);
+        if (!Number.isInteger(finding['line']) || !Number.isInteger(finding['column']))
+            faults.push(`${at} holds a finding whose position is not a pair of integers`);
+    }
+    return faults;
+}
+/**
+ * The faults of the text of a file of the secrets folder: every line is a record that holds codes, paths, positions and digests, and nothing
+ * else. An empty list means the file carries no secret material by construction.
+ */
+export function secretRecordFaults(text) {
+    const faults = [];
+    text.split('\n').forEach((raw, index) => {
+        const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+        if (line.trim() === '')
+            return;
+        const at = `line ${index + 1}`;
+        try {
+            faults.push(...recordFaults(JSON.parse(line), at));
+        }
+        catch {
+            faults.push(`${at} is not JSON`);
+        }
+    });
+    return faults;
+}

package/scaffold/add-inbox-lite.mjs

@@ -218,8 +218,8 @@ export function addLiteWebhookInbox({ root, repo, noun, provider, values, now =
     const hasHandoffStorage = migrations.some((file) => /create\s+function\s+public\.event_bus_send\b/i.test(fs.readFileSync(path.join(migrationsDir, file), "utf8")));
     if (!hasHandoffStorage)
         planned[0].text = `${template("platform/migration.sql.tpl", renderValues)}\n${template("platform/client-operation-outcomes.sql.tpl", renderValues)}\n${planned[0].text}`; // the migration is the first planned file
-    // The sql tag and the database-function call (with its spec) the inbox and the event bus use; the lite starter leaves them out.
-    for (const file of ["database.sql.ts", "database.client.ts", "database.client.spec.ts"]) {
+    // The sql tag the inbox and the event bus use; the lite starter leaves it out.
+    for (const file of ["database.sql.ts"]) {
         const relative = `be/src/modules/platform/database/${file}`;
         if (fs.existsSync(path.join(root, ...relative.split("/"))))
             continue;

package/scaffold/add-queue-lite.mjs

@@ -79,13 +79,11 @@ const template = (relative) => read(path.join(TEMPLATES_DIR, ...relative.split('
 const DATABASE_ERROR = 'be/src/modules/platform/database/errors/database.error.ts';
 /** Skeleton files the lite starter leaves out and the queue capabilities use, each from its skeleton template. */
 const SKELETON_FILES = Object.freeze([
-    ['be/src/modules/platform/database/database.client.ts', 'skeleton-lite/src/modules/platform/database/database.client.ts'],
-    ['be/src/modules/platform/database/database.client.spec.ts', 'skeleton-lite/src/modules/platform/database/database.client.spec.ts'],
     ['be/src/modules/platform/database/database.sql.ts', 'skeleton-lite/src/modules/platform/database/database.sql.ts'],
     ['be/src/modules/platform/primitives/sequence.policy.ts', 'skeleton/src/modules/platform/primitives/sequence.policy.ts'],
     ['be/src/modules/platform/primitives/sequence.policy.spec.ts', 'skeleton/src/modules/platform/primitives/sequence.policy.spec.ts'],
 ]);
-/** The database-function call and the sql tag of the outbox and claim statements (with its identifier error) and the in-order relay the queue adapters walk their rows with. */
+/** The sql tag of the outbox and claim statements (with its identifier error) and the in-order relay the queue adapters walk their rows with. */
 function skeletonFiles(repoRoot) {
     const created = SKELETON_FILES.filter(([relative]) => !fs.existsSync(path.join(repoRoot, ...relative.split('/'))))
         .map(([relative, source]) => ({ relative, text: render(template(`be/${source}`), {}) }));

package/scaffold/app.d.mts

@@ -160,8 +160,8 @@ export declare const PARTIAL_VARIABLES: any;
  * The be files a generator writes when it first needs them, never the starter, so a fresh app carries no file and no export that
  * nothing reads (R25). In both editions: the entity bases of platform/database (abstract.entity.ts, BE-PERSISTENCE-3), written by
  * the first table whose entity extends them, since no starter table has both timestamps. In lite also: the cli's runners, the in-order
- * relay, and the raw SQL helpers of platform/database (the sql tag, and the database-function call statement with its spec), which only
- * the table, queue, jobs and webhook capabilities call; a fresh app reads and writes through entities alone (R334).
+ * relay, and the sql tag of platform/database, which only the table, queue, jobs and webhook capabilities call; a fresh app reads and
+ * writes through entities and, for the account doors of its sign-in, the database-function call of database.client.ts (R334).
  */
 export declare const ENTITY_BASE_FILE = "src/modules/platform/database/abstract.entity.ts";
 /**

package/scaffold/app.mjs

@@ -139,7 +139,7 @@ const LITE_STARTER_SIDES = Object.freeze({
 const STARTER_DEPENDENCIES = Object.freeze({
     dependencies: {
         '@apollo/server': null, '@nestjs/apollo': null, '@nestjs/common': null, '@nestjs/core': null, '@nestjs/cqrs': null, '@nestjs/graphql': null,
-        '@nestjs/platform-express': null, '@nestjs/typeorm': null, 'nest-commander': null, pg: null, graphql: null,
+        '@nestjs/platform-express': null, '@nestjs/typeorm': null, '@starci/nest-kit': null, 'nest-commander': null, pg: null, graphql: null,
         'class-transformer': null, 'class-validator': null, 'reflect-metadata': null, rxjs: null, tslib: null, typeorm: null, undici: null, zod: null,
     },
     devDependencies: {
@@ -158,7 +158,7 @@ const STARTER_DEPENDENCIES = Object.freeze({
 const LITE_STARTER_DEPENDENCIES = Object.freeze({
     dependencies: {
         '@apollo/server': null, '@nestjs/apollo': null, '@nestjs/common': null, '@nestjs/core': null, '@nestjs/cqrs': null, '@nestjs/graphql': null,
-        '@nestjs/platform-express': null, '@nestjs/typeorm': null, '@starci/auth': null, '@starci/object-storage': null,
+        '@nestjs/platform-express': null, '@nestjs/typeorm': null, '@starci/auth': null, '@starci/mail': null, '@starci/nest-kit': null, '@starci/object-storage': null,
         'class-transformer': null, 'class-validator': null, graphql: null, pg: null,
         'reflect-metadata': null, rxjs: null, tslib: null, typeorm: null, undici: null, zod: null,
     },
@@ -182,22 +182,22 @@ const FE_APP_DEPENDENCIES = Object.freeze({
     '@heroui/react': null, '@heroui/styles': null, '@starci/grammar': null, '@xyflow/react': null, 'react-aria-components': null, next: null, 'next-intl': null, react: null, 'react-dom': null,
 });
 /**
- * The lite fe workspace: the same base without the shared packages, plus server-only for its own next-intl request config. It
- * holds no identity SDK: modules/auth talks only to the app's own back-end auth doors.
+ * The lite fe workspace: the same base without the shared packages (its next-intl stack is @starci/next-i18n's, a core package of the
+ * fe stack). It holds no identity SDK: modules/auth talks only to the app's own back-end auth doors.
  */
 const LITE_FE_APP_DEPENDENCIES = Object.freeze({
     '@heroicons/react': null, '@heroui/react': null, '@heroui/styles': null, '@starci/auth': null, '@starci/grammar': null, '@starci/heroicons': null, '@xyflow/react': null, 'react-aria-components': null,
-    next: null, 'next-intl': null, react: null, 'react-dom': null, 'server-only': null,
+    next: null, 'next-intl': null, react: null, 'react-dom': null,
 });
 /**
  * The shared fe workspace packages of the starter, fe/packages/<project>-<name> named @<project>/<name>: each one's exported
  * subpaths (built to dist) and the runtime dependencies its own source imports. ui holds the drawings both apps mount; i18n the
- * next-intl stack (the entry, a server module: createAppI18n; ./proxy, the locale negotiation the apps' proxy.ts re-exports;
- * ./routing, client-safe: the default locale a client boundary reads).
+ * product's description of its languages over @starci/next-i18n (the entry, a server module: createAppI18n; ./proxy, the locale
+ * negotiation the apps' proxy.ts re-exports; ./routing, client-safe: the description and the default locale a client boundary reads).
  */
 const FE_PACKAGES = Object.freeze({
     ui: { exports: ['.'], dependencies: { '@heroui/react': null, '@starci/grammar': null, '@starci/heroicons': null, '@xyflow/react': null, 'react-aria-components': null, 'next-intl': null, react: null, 'react-dom': null } },
-    i18n: { exports: ['.', './proxy', './routing'], dependencies: { next: null, 'next-intl': null, 'server-only': null } },
+    i18n: { exports: ['.', './proxy', './routing'], dependencies: { '@starci/next-i18n': null, next: null, 'server-only': null } },
 });
 /** The scripts of every fe package workspace: tsc builds it to dist and type-checks it. */
 const PACKAGE_WORKSPACE_SCRIPTS = Object.freeze({ build: 'tsc -p tsconfig.build.json', typecheck: 'tsc --noEmit -p tsconfig.json' });
@@ -333,15 +333,13 @@ const LITE_APP_REUSED = new Set(['.editorconfig', '.gitattributes', '.nvmrc']);
  * The be files a generator writes when it first needs them, never the starter, so a fresh app carries no file and no export that
  * nothing reads (R25). In both editions: the entity bases of platform/database (abstract.entity.ts, BE-PERSISTENCE-3), written by
  * the first table whose entity extends them, since no starter table has both timestamps. In lite also: the cli's runners, the in-order
- * relay, and the raw SQL helpers of platform/database (the sql tag, and the database-function call statement with its spec), which only
- * the table, queue, jobs and webhook capabilities call; a fresh app reads and writes through entities alone (R334).
+ * relay, and the sql tag of platform/database, which only the table, queue, jobs and webhook capabilities call; a fresh app reads and
+ * writes through entities and, for the account doors of its sign-in, the database-function call of database.client.ts (R334).
  */
 export const ENTITY_BASE_FILE = 'src/modules/platform/database/abstract.entity.ts';
 const DEFERRED_GENERATOR_FILES = new Set([ENTITY_BASE_FILE]);
 const LITE_DEFERRED_GENERATOR_FILES = new Set([
     ...DEFERRED_GENERATOR_FILES,
-    'src/modules/platform/database/database.client.ts',
-    'src/modules/platform/database/database.client.spec.ts',
     'src/modules/platform/database/database.sql.ts',
     'src/modules/platform/database/migration-runner.service.ts',
     'src/modules/platform/database/seed-runner.service.ts',

package/scaffold/lite-exports.mjs

@@ -59,20 +59,13 @@ const REGISTRATIONS = Object.freeze({
             names: ["sql"],
             beforeSource: "./errors/database.error",
         },
-        {
-            // The outbox write and the relay call the queue functions of their migration (R334).
-            file: "be/src/modules/platform/database/index.ts",
-            source: "./database.client",
-            names: ["callDbFunction"],
-            beforeSource: "./primary.decorators",
-        },
     ],
     // The jobs capability (add job, the fenced-job pattern): its tick takes a transaction-scoped lock before it claims the minute (R335).
     jobs: [
         {
             file: "be/src/modules/platform/database/index.ts",
             source: "./database.client",
-            names: ["advisoryXactLock", "callDbFunction"],
+            names: ["advisoryXactLock"],
             beforeSource: "./primary.decorators",
         },
     ],
@@ -83,13 +76,6 @@ const REGISTRATIONS = Object.freeze({
             names: ["BATCH_ROWS", "sql"],
             beforeSource: "./errors/database.error",
         },
-        {
-            // The inbox claim and the lite event bus call the functions of their migration (R334).
-            file: "be/src/modules/platform/database/index.ts",
-            source: "./database.client",
-            names: ["callDbFunction"],
-            beforeSource: "./primary.decorators",
-        },
         {
             // PRIMARY_ENTITY_MANAGER: the token the inbox service's unit spec provides its EntityManager double under.
             file: "be/src/modules/platform/database/index.ts",

package/scripts/sync-bundles.d.mts

@@ -29,3 +29,11 @@ export declare function syncBundles(options: {
     readonly check: boolean;
     readonly packages?: readonly string[];
 }): SyncResult;
+/** The harness runtime layers whose recipe hfs ships for `starci app stack up` (stack/runtime-layers.mts): the folder name under images/ of the harness repository. */
+export declare const layerRecipes: readonly ["openclaw-runtime"];
+/** Syncs (or judges) the shipped copy stack/images/<layer>/ of each recipe against the owner, `images/<layer>/` of the harness repository. */
+export declare function syncLayerRecipes(options: {
+    readonly imagesDir: string;
+    readonly shippedDir: string;
+    readonly check: boolean;
+}): SyncResult;

package/stack/images/openclaw-runtime/Dockerfile

@@ -0,0 +1,18 @@
+# StarCi OpenClaw runtime layer: the harness-pinned source-built fork (images/openclaw, sources.json) plus the generic gateway wrapper.
+# An app image does `FROM ghcr.io/starci183/openclaw-runtime@sha256:...` and only COPYs its own plugins into /opt/starci/plugins/<name>/;
+# it carries no wrapper code (images/README.md "The OpenClaw runtime layer"). The base below is the recorded `published.reference` of the
+# `openclaw` entry of sources.json; a new fork build raises it here in the same change.
+FROM ghcr.io/starci183/openclaw:2026.10.10-beta.5-starci.1@sha256:0770c1da11ec4a46607ec16957ac3cff68d05db4a287f59f0e1d0e76de980ff8
+
+USER root
+# The wrapper is root-owned and not writable by the runtime user; the plugin directory is root-owned and world-readable, so a plugin an
+# app copies in cannot be rewritten by the gateway it runs inside.
+COPY --chmod=0555 entrypoint.sh /opt/starci/entrypoint.sh
+COPY --chmod=0444 openclaw-init.mjs openclaw-relay.mjs /opt/starci/
+RUN mkdir -p /opt/starci/plugins \
+    && chown -R root:root /opt/starci \
+    && chmod 0755 /opt/starci /opt/starci/plugins
+
+USER node
+ENV STARCI_PLUGINS_DIR=/opt/starci/plugins
+ENTRYPOINT ["tini", "-s", "--", "sh", "/opt/starci/entrypoint.sh"]

package/stack/images/openclaw-runtime/entrypoint.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+# Entrypoint of the StarCi OpenClaw runtime layer (/opt/starci/entrypoint.sh).
+#
+# 1. The OpenClaw image has no `<NAME>_FILE` support, so every secret named in STARCI_SECRETS (space separated; OPENCLAW_GATEWAY_TOKEN is always
+#    read) is exported from /run/secrets/<NAME> into THIS process tree only: no env file on the host, no value in the service specification.
+# 2. openclaw-init.mjs merges the gateway settings into openclaw.json (idempotent; other keys, agents and plugins are kept) and enables the plugins
+#    found under STARCI_PLUGINS_DIR.
+# 3. openclaw-relay.mjs listens on the overlay address and forwards to the loopback-only gateway: the gateway honours the scopes a client
+#    declares only for a loopback peer using the shared secret, so clients connect to the relay (OPENCLAW_RELAY_PORT, default 18790).
+set -eu
+
+for name in OPENCLAW_GATEWAY_TOKEN ${STARCI_SECRETS:-}; do
+  file="/run/secrets/$name"
+  if [ -r "$file" ]; then
+    value="$(cat "$file")"
+    export "$name=$value"
+  fi
+done
+: "${OPENCLAW_GATEWAY_TOKEN:?the secret OPENCLAW_GATEWAY_TOKEN is not granted to this service}"
+
+OPENCLAW_GATEWAY_TOKEN_FILE=/run/secrets/OPENCLAW_GATEWAY_TOKEN node /opt/starci/openclaw-init.mjs
+node /opt/starci/openclaw-relay.mjs &
+exec node openclaw.mjs gateway

package/stack/images/openclaw-runtime/openclaw-init.mjs

@@ -0,0 +1,101 @@
+// Writes the gateway settings the StarCi runtime layer relies on into openclaw.json before the gateway starts (idempotent merge: other keys,
+// agents and plugins that OpenClaw or an operator added are kept). Loopback bind + token auth: the gateway is reached only through the relay.
+//
+// The contract an app image relies on (images/README.md "The OpenClaw runtime layer"):
+//   STARCI_PLUGINS_DIR   the plugin directory (default /opt/starci/plugins): every subfolder holding an openclaw.plugin.json is added to
+//                        plugins.load.paths and enabled as plugins.entries.<folder name>
+//   AI_BASE_URL + STARCI_AI_KEY  one OpenAI-compatible custom provider (name OPENCLAW_PROVIDER, default "starci-ai"; chat model AI_CHAT_MODEL,
+//                        default "work"); the key stays a reference openclaw resolves from the gateway process environment
+//   OPENCLAW_MODEL       the primary model of the agents; OPENCLAW_MODEL_REASONING=off switches the model's reasoning off
+import fs from "node:fs"
+import path from "node:path"
+
+const file = "/home/node/.openclaw/openclaw.json"
+let config = {}
+try {
+    config = JSON.parse(fs.readFileSync(file, "utf8"))
+} catch {
+    config = {}
+}
+// The app writes each agent workspace itself: no first-run ritual.
+config.agents = config.agents || {}
+config.agents.defaults = { ...(config.agents.defaults || {}), skipBootstrap: true }
+// The app owns every trigger and schedule: OpenClaw runs one turn when asked and nothing in the background. `cron.enabled: false` stops its cron
+// scheduler; a `defaults.heartbeat` block makes every agent resolve its heartbeat from it, and `every: "0m"` gives each no interval.
+config.cron = { ...(config.cron || {}), enabled: false }
+config.agents.defaults.heartbeat = { ...(config.agents.defaults.heartbeat || {}), every: "0m" }
+// Plugins: every folder of the plugin directory that holds an openclaw.plugin.json is loaded and enabled; other paths and entries are kept.
+const pluginsDir = process.env.STARCI_PLUGINS_DIR || "/opt/starci/plugins"
+const found = fs.existsSync(pluginsDir)
+    ? fs.readdirSync(pluginsDir, { withFileTypes: true })
+          .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(pluginsDir, entry.name, "openclaw.plugin.json")))
+          .map((entry) => entry.name)
+          .sort()
+    : []
+const plugins = config.plugins || {}
+const load = plugins.load || {}
+const paths = Array.isArray(load.paths) ? load.paths : []
+const entries = { ...(plugins.entries || {}) }
+for (const name of found) entries[name] = { ...(entries[name] || {}), enabled: true }
+config.plugins = {
+    ...plugins,
+    load: { ...load, paths: [...paths, ...found.map((name) => path.join(pluginsDir, name)).filter((folder) => !paths.includes(folder))] },
+    entries,
+}
+config.session = {
+    ...(config.session || {}),
+    maintenance: {
+        ...((config.session || {}).maintenance || {}),
+        mode: "enforce",
+        pruneAfter: "7d",
+        maxEntries: 400,
+        maxDiskBytes: "400mb",
+    },
+}
+config.gateway = {
+    ...(config.gateway || {}),
+    mode: "local",
+    bind: "loopback",
+    port: 18789,
+    auth: {
+        ...((config.gateway || {}).auth || {}),
+        mode: "token",
+        token: fs.readFileSync(process.env.OPENCLAW_GATEWAY_TOKEN_FILE, "utf8"),
+    },
+}
+// Language models come only from the AI gateway the app hosts: one OpenAI-compatible custom provider with the virtual key it shares with the app.
+if (process.env.AI_BASE_URL && process.env.STARCI_AI_KEY) {
+    const chat = process.env.AI_CHAT_MODEL || "work"
+    const provider = process.env.OPENCLAW_PROVIDER || "starci-ai"
+    config.models = {
+        ...(config.models || {}),
+        mode: "merge",
+        providers: {
+            ...((config.models || {}).providers || {}),
+            [provider]: {
+                baseUrl: process.env.AI_BASE_URL,
+                apiKey: "${STARCI_AI_KEY}",
+                api: "openai-completions",
+                models: [{ id: chat, name: chat, input: ["text", "image"] }],
+            },
+        },
+    }
+}
+const model = process.env.OPENCLAW_MODEL
+if (model) {
+    config.agents.defaults.model = { ...(config.agents.defaults.model || {}), primary: model }
+    if (process.env.OPENCLAW_MODEL_REASONING === "off") {
+        const models = (config.agents.defaults.models = config.agents.defaults.models || {})
+        const previous = models[model] || {}
+        models[model] = {
+            ...previous,
+            params: {
+                ...(previous.params || {}),
+                extra_body: { ...((previous.params || {}).extra_body || {}), reasoning: { enabled: false } },
+            },
+        }
+    }
+}
+fs.mkdirSync("/home/node/.openclaw", { recursive: true })
+fs.writeFileSync(file, JSON.stringify(config, null, 2), { mode: 0o600 })
+console.log("openclaw.json ready (gateway local/loopback/token, " + found.length + " plugin" + (found.length === 1 ? "" : "s") + (model ? ", model " + model : "") + ")")

package/stack/images/openclaw-runtime/openclaw-relay.mjs

@@ -0,0 +1,25 @@
+// A byte-for-byte TCP relay inside the OpenClaw task: it listens on the overlay address and forwards every connection to the loopback-only
+// gateway (127.0.0.1:18789), so the gateway sees a loopback peer and honours the scopes a client declares. It adds no header and reads no frame.
+import net from "node:net"
+
+const listenPort = Number(process.env.OPENCLAW_RELAY_PORT || 18790)
+const gatewayPort = 18789
+
+const server = net.createServer((client) => {
+    const gateway = net.connect({ host: "127.0.0.1", port: gatewayPort })
+    const close = () => {
+        client.destroy()
+        gateway.destroy()
+    }
+    client.on("error", close)
+    gateway.on("error", close)
+    client.on("close", close)
+    gateway.on("close", close)
+    client.pipe(gateway)
+    gateway.pipe(client)
+})
+server.on("error", (error) => {
+    console.error("openclaw relay failed: " + error.message)
+    process.exit(1)
+})
+server.listen(listenPort, "0.0.0.0", () => console.log("openclaw relay " + listenPort + " -> 127.0.0.1:" + gatewayPort))

package/stack/local-up.mjs

@@ -11,6 +11,7 @@ import { missingKeys, missingStep, openCustody } from './local-custody.mjs';
 import { hostRefusal, preflight, runSetup } from './local-prepare.mjs';
 import { DEFAULT_TIMEOUT_SECONDS, makeDataDirectories, commandDigest, compose, composeValues, databaseUrl, isAlive, probe, runCommand, runEnvironment, serviceReady, startProcess, stateOf, waitFor } from './local-run.mjs';
 import { readRecord, writeRecord } from './local-state.mjs';
+import { ensureRuntimeLayers, layerPlan } from './runtime-layers.mjs';
 const SAFE_PASSWORD = /^[A-Za-z0-9_-]{8,}$/u;
 /** The digest of the migration folder (names and contents): what a migrate receipt records. */
 export function migrationsDigest(repoRoot) {
@@ -122,6 +123,7 @@ function plan(local, missing) {
     return [
         `plan custody: ${missing.length ? `missing ${missing.join(', ')}: ${missingStep(local, missing)}` : 'open the sealed dev values into host-local files'}`,
         ...local.setup.map((run) => `plan setup ${run.name}: ${run.argv.join(' ')}`),
+        ...layerPlan(local),
         `plan services: ${local.services.map((service) => `${service.name} (wait ${service.wait})`).join(', ')}`,
         ...(local.database ? [`plan database: own role ${local.database.role}, database ${local.database.name}, then starci app db migrate`] : []),
         ...local.seed.map((run) => `plan seed ${run.name}: ${run.argv.join(' ')}`),
@@ -142,6 +144,7 @@ export async function upLocal(ctx, local, { execute = false, timeoutSeconds = DE
     lines.push(`custody: ${custody.values.size} key file(s) in the host-local directory`);
     lines.push(...await runSetup(ctx, local, custody));
     makeDataDirectories(ctx, local);
+    lines.push(...await ensureRuntimeLayers(ctx, local));
     const values = composeValues(local, custody);
     const started = await compose(ctx, local, ['up', '-d', ...local.services.map((service) => service.name)], { values, heavy: true, label: 'compose up' });
     if (started.status !== 0)

package/stack/runtime-layers.d.mts

@@ -0,0 +1,21 @@
+import type { StackContext } from './context.mjs';
+import type { LocalConfig } from './local-config.mjs';
+/** The registry path of the harness-owned layers: `<prefix><layer>`. */
+export declare const LAYER_PREFIX = "ghcr.io/starci183/";
+/** The layers whose recipe this package ships. */
+export declare const SHIPPED_LAYERS: readonly string[];
+/** The folder holding the recipe of a layer in this package. */
+export declare const recipeDirectory: (layer: string) => string;
+/** One layer an app image builds on: the layer, the reference as the Dockerfile writes it and the tag a local build gives it. */
+export interface LayerUse {
+    layer: string;
+    reference: string;
+    tag: string;
+    dockerfile: string;
+}
+/** The layers `.starcistacks/images/*` of the app builds on (each distinct reference once), from the `FROM` lines of its Dockerfiles. */
+export declare function layersUsed(repoRoot: string): LayerUse[];
+/** The lines of the plan a dry run prints for the layers the app builds on. */
+export declare const layerPlan: (local: LocalConfig) => string[];
+/** Builds every layer the app names that the host neither holds nor can pull; returns one line per layer. */
+export declare function ensureRuntimeLayers(ctx: StackContext, local: LocalConfig): Promise<string[]>;

package/stack/runtime-layers.mjs

@@ -0,0 +1,67 @@
+// runtime-layers.mjs - the harness runtime layers a dev stack builds on (images/README.md "The OpenClaw runtime layer"; R374 STACKS_IMAGE_BASE_NOT_FORK).
+// An app image folder `.starcistacks/images/<name>/Dockerfile` is `FROM ghcr.io/starci183/<layer>:<tag>[@sha256:<digest>]`. While the harness has not
+// published that layer (or the host cannot pull it), `starci app stack up` builds it from the recipe this package ships (stack/images/<layer>/,
+// byte-equal to the harness repository's images/<layer>/, which `npm run bundles` copies and a spec compares) and tags it with the reference the
+// app names minus its digest, so the compose build of the app image finds it in the local store. The build is a governed heavy command
+// (hard rule 8): an agent never runs docker by hand. A reference whose image the host already holds, or can pull, is left alone.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { failure } from './errors.mjs';
+/** The registry path of the harness-owned layers: `<prefix><layer>`. */
+export const LAYER_PREFIX = 'ghcr.io/starci183/';
+/** The layers whose recipe this package ships. */
+export const SHIPPED_LAYERS = Object.freeze(['openclaw-runtime']);
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+/** The folder holding the recipe of a layer in this package. */
+export const recipeDirectory = (layer) => path.join(HERE, 'images', layer);
+/** The layers `.starcistacks/images/*` of the app builds on (each distinct reference once), from the `FROM` lines of its Dockerfiles. */
+export function layersUsed(repoRoot) {
+    const folder = path.join(repoRoot, '.starcistacks', 'images');
+    if (!fs.existsSync(folder))
+        return [];
+    const found = new Map();
+    for (const entry of fs.readdirSync(folder, { withFileTypes: true }).filter((item) => item.isDirectory()).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+        const dockerfile = path.join(folder, entry.name, 'Dockerfile');
+        if (!fs.existsSync(dockerfile))
+            continue;
+        for (const line of fs.readFileSync(dockerfile, 'utf8').split(/\r?\n/u)) {
+            const from = /^\s*FROM\s+(?:--\S+\s+)*(\S+)/iu.exec(line)?.[1];
+            if (from?.startsWith(LAYER_PREFIX) !== true)
+                continue;
+            const reference = from;
+            const tag = reference.replace(/@sha256:[0-9a-f]+$/u, '');
+            const layer = tag.slice(LAYER_PREFIX.length).replace(/:.*$/u, '');
+            if (SHIPPED_LAYERS.includes(layer) && !found.has(reference))
+                found.set(reference, { layer, reference, tag: tag.includes(':') ? tag : `${tag}:latest`, dockerfile: path.relative(repoRoot, dockerfile).split(path.sep).join('/') });
+        }
+    }
+    return [...found.values()];
+}
+/** Whether the host holds `reference` or can pull it: the local store first, then the registry's manifest. */
+async function available(ctx, use) {
+    if ((await ctx.spawn('docker', ['image', 'inspect', use.tag])).status === 0)
+        return true;
+    return (await ctx.spawn('docker', ['manifest', 'inspect', use.reference])).status === 0;
+}
+/** The lines of the plan a dry run prints for the layers the app builds on. */
+export const layerPlan = (local) => layersUsed(local.repoRoot).map((use) => `plan runtime layer ${use.layer}: ${use.tag} is built from the shipped recipe when the host holds none and the registry has none`);
+/** Builds every layer the app names that the host neither holds nor can pull; returns one line per layer. */
+export async function ensureRuntimeLayers(ctx, local) {
+    const lines = [];
+    for (const use of layersUsed(local.repoRoot)) {
+        if (await available(ctx, use)) {
+            lines.push(`runtime layer ${use.layer}: ${use.tag} is available`);
+            continue;
+        }
+        const recipe = recipeDirectory(use.layer);
+        if (!fs.existsSync(path.join(recipe, 'Dockerfile')))
+            throw failure('STACK_LOCAL_RUNTIME_LAYER', `${use.dockerfile} builds on ${use.reference}, which is not published, and this package ships no recipe for ${use.layer}`);
+        const argv = ['docker', 'build', '-t', use.tag, recipe];
+        const built = ctx.heavy ? await ctx.heavy({ kind: 'build', label: `${local.project} runtime layer ${use.layer}`, cwd: local.repoRoot, argv, env: ctx.env }) : await ctx.spawn('docker', argv.slice(1), { cwd: local.repoRoot, env: ctx.env });
+        if (built.status !== 0)
+            throw failure('STACK_LOCAL_RUNTIME_LAYER', `docker build of the runtime layer ${use.layer} failed: ${(built.stderr.trim().split(/\r?\n/u)[0] ?? '').slice(0, 200)}`);
+        lines.push(`runtime layer ${use.layer}: ${use.reference} is not published; built ${use.tag} from the recipe this package ships`);
+    }
+    return lines;
+}

package/sync/compile-guard.d.mts

@@ -0,0 +1,36 @@
+/** The TypeScript compiler API of the app's own install, typed by the version this package develops against. */
+type Ts = typeof import('typescript');
+/** The refusal code of a held group. */
+export declare const GROUP_HELD = "HFS_SYNC_GROUP_HELD";
+/** The pseudo-group of the retired files a sync deletes. */
+export declare const RETIRED_GROUP = "retired";
+/** One write the guard judges: an app-relative path, its managed group, and its new text (null: the file is deleted). */
+export interface GuardedWrite {
+    path: string;
+    group: string;
+    text: string | null;
+}
+/** A group sync does not write, with its files and the errors its writes would add. */
+export interface HeldGroup {
+    group: string;
+    files: string[];
+    errors: string[];
+}
+/** What the guard answers: the held groups, and the sides it could not compile. */
+export interface GuardVerdict {
+    held: HeldGroup[];
+    unchecked: string[];
+}
+/** Whether `file` (app-relative) is TypeScript source a side compiles. */
+export declare const isGuardedSource: (file: string) => boolean;
+/** The tsconfig that compiles an app-relative source: `be/tsconfig.json`, or the front-end app's or package's own; null when there is none. */
+export declare function projectOf(root: string, file: string): string | null;
+/**
+ * The groups `starci app sync --execute` holds back at `root`: every write of a TypeScript source is compiled, per side, with the side's own
+ * TypeScript (`loadTs`, the app's install by default); a side with no tsconfig compiles nothing, a side whose TypeScript is not installed is
+ * named in `unchecked`.
+ */
+export declare function guardWrites(root: string, writes: readonly GuardedWrite[], loadTs?: (dir: string) => Ts | null): GuardVerdict;
+/** The lines sync prints for a held group: what is held and why, the first errors, and what to do. */
+export declare function heldLines(group: HeldGroup): string[];
+export {};