@starci/hfs 4.13.0 → 4.13.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 4.13.2 - 2026-10-31
+
+- Added: R344 `BE_AI_VIRTUAL_KEY` in the bundled rule catalog and on the `be.integrations` slot: an app's ai-router gateway has one client key, `STARCI_AI_KEY`, read by `integrations/ai`, and no admin token; `@starci/eslint-canon-be` `ai-virtual-key-name` enforces it (ruling be-ai-one-virtual-key).
+- Changed: the bundled canon pins name hfs 4.13.2 and the lint cohort eslint-canon-be 3.10.0, eslint-canon-fe 9.6.5, eslint-grammar-core and eslint-grammar-offset-pop 0.16.5.
+
+## 4.13.1 - 2026-10-31
+
+The open items of the delivery pipeline (contexts/project/cicd.md, "As built").
+
+- Added: `starci-ssh-gate`, the forced command of the CI SSH key. The release store's remote operations are named scripts with arguments of a closed alphabet (`stack/ssh-gate.mts`); the gate admits `docker system dial-stdio` and `starci-op <name> <args>` and refuses anything else with exit 126, saying nothing about the request. `starci app stack ci-key --env <env>` prints the owner-run install steps, `--print-gate` the gate text and `--public-key <file> --print-authorized-keys` the line (`restrict,command="starci-ssh-gate",no-pty,no-port-forwarding,no-agent-forwarding,no-X11-forwarding,no-user-rc <key>`). A sealed `vps-ci` member that holds `VPS_GATE: "1"` makes `stack connect` export `STARCI_SSH_GATE=1`, and the deploy, rollback, accept and status verbs then send the operations through the gate; without it they run the same bodies under `sh -c`. Not admitted yet: the post-deploy tasks and the manager backup and test decrypt of a stack database.
+- Added: `deploy.notify` (`webhook: {member, key}`, optional `on`), off unless declared: one JSON webhook message (outcome, environment, stack, commit, tag, release, attempt, CI run URL, failure code) when an attempt ends; the URL is a key of a sealed member, https only, never printed; a failing webhook is a line of the result and never fails the deploy.
+- Added: the journal document of an attempt carries `contract`, the contract migrations it applied, and the release store reads the journal (`journals()`). `stack rollback` refuses `STACK_ROLLBACK_CONTRACT` (dry run too) for a release older than the previous release of an attempt that applied a contract migration, or that the journal never saw once any is recorded, unless `--data-acknowledged`.
+- Changed: the bundled canon pins name hfs 4.13.1 and the lint cohort eslint-canon-be 3.9.4, eslint-canon-fe 9.6.4, eslint-grammar-core and eslint-grammar-offset-pop 0.16.4 (their copies of the pins moved with them).
+- Changed: the release store's lock, pointer, list, read, store, accept and journal commands are the named operations above; a releases base may not contain `..` anywhere.
+
 ## 4.13.0 - 2026-10-31
 
 The delivery pipeline of an app (contexts/project/cicd.md, ruling app-cicd-auto-deploy; owner approval 2026-10-31: every green release tag deploys by itself, STARCI_DEPLOY_PAUSED is the brake, agents deploy, the CI deploy key is sealed, pull requests get CI, contract migrations run after the accept, Sonar judges every full run, images are cached in GitHub Actions and built for amd64 unless declared).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.13.0",
+  "version": "4.13.2",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,35 +31,35 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.16.3
+    version: 0.16.5
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.9.3
+    version: 3.10.0
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.6.3
+    version: 9.6.5
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.16.3
+    version: 0.16.5
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.16.3
+    version: 0.16.5
     group: starci
     install: registry
     side: fe
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 4.13.0
+    version: 4.13.2
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -6046,3 +6046,26 @@ rules:
         source: owner
         quote: "app check cache lại vào file dc không? sau chỉ check diff; chốt starcistacks lưu hết nhé và check diff và triển cho ci và local lun."
         ruling: "The app commits its check results in .starcistacks/cache/; CI trusts only the cache at the trusted base, a forged record blocks at any count, stale and missing only warn (ruling app-check-cache)."
+  - id: R344
+    code: "BE_AI_VIRTUAL_KEY"
+    law: "An app's ai-router gateway has one client key, STARCI_AI_KEY (sk-starci-<app>-<48 hex>, sealed in the ai member, used by the integrations/ai LangChain client and the agent runtime alike), and no admin token: integrations/ai reads exactly that secret name with env.secret, as a literal, and the custody owner integrations/ai-gateway passes the gateway no adminToken."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["BE_AI_VIRTUAL_KEY"]
+    enforcers:
+      - {kind: eslint-be, id: ai-virtual-key-name}
+    editions: [lite, full]
+    docs: [contexts/code/be/ai.md]
+    templateNa: "The skeleton scaffolds no model call; an app adds the ai and ai-gateway integrations and the ai member when it calls a model."
+    proves:
+      - {path: packages/eslint-canon-be/src/ai-gateway.spec.ts, editions: [lite, full], codes: [BE_AI_VIRTUAL_KEY]}
+    exemplifiedBy:
+      - {path: packages/eslint-canon-be/src/ai-gateway.spec.ts, editions: [lite, full], codes: [BE_AI_VIRTUAL_KEY]}
+    witness:
+      - {path: packages/eslint-canon-be/src/ai-gateway.spec.ts, editions: [lite, full], codes: [BE_AI_VIRTUAL_KEY]}
+    cases:
+      - id: case-1
+        date: "2026-10-31"
+        source: owner
+        quote: "Xóa ai api key và openclaw ai key chỉnh thành starci ai key là key ảo"
+        ruling: "Per app and environment the ai member holds the upstream provider keys and one random virtual key STARCI_AI_KEY that the gateway mounts and every client uses; the gateway has no admin API (ruling be-ai-one-virtual-key)."

package/runtime/knowledge/hfs/slots.yaml

@@ -1999,7 +1999,7 @@ slots:
     tests: unit-beside            # <name>.service.spec.ts beside each <name>.service.ts; plus src/tests/integration/<provider>/ (R112)
     coverage: required
     budget: {indexExports: 80}   # a provider's port surface includes clients, config, options, tokens and errors
-    rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INTEGRATION_SPEC_MISSING, BE_AI_KEY_CUSTODY, BE_AI_GATEWAY_CLIENT]
+    rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INTEGRATION_SPEC_MISSING, BE_AI_KEY_CUSTODY, BE_AI_GATEWAY_CLIENT, BE_AI_VIRTUAL_KEY]
   - id: be.integrations.model
     since: 3.1.0
     profiles: [be]

package/runtime/modules/schemas/application-stacks.schema.yaml

@@ -633,6 +633,7 @@ $defs:
         uniqueItems: true
         items: {type: string, pattern: '^[a-z][a-z0-9-]{0,40}$'}
       backup: {$ref: '#/$defs/deployBackup'}
+      notify: {$ref: '#/$defs/deployNotify'}
       registry: {$ref: '#/$defs/deployRegistry'}
       ingress:
         description: The shared host ingress (stack-ingress-config.mjs is the authority for the fields; starci app check R294 judges them).
@@ -850,6 +851,27 @@ $defs:
         type: array
         minItems: 1
         items: {$ref: '#/$defs/deployBackupVolume'}
+  deployNotify:
+    description: >-
+      One webhook message per deploy outcome (accepted, rolled-back, rollback-failed, failed; `refused` only when listed): the outcome, the environment, the commit, the tag, the
+      release and the attempt, as JSON with a `text` and a `content` line so a chat webhook shows it. Off unless declared. The URL is a sealed value of the environment
+      (https only), never written here; a failing webhook is a line of the result and never fails the deploy.
+    type: object
+    additionalProperties: false
+    required: [webhook]
+    properties:
+      webhook:
+        type: object
+        additionalProperties: false
+        required: [member, key]
+        properties:
+          member: {$ref: '#/$defs/deployName'}
+          key: {$ref: '#/$defs/deployKey'}
+      on:
+        type: array
+        uniqueItems: true
+        minItems: 1
+        items: {enum: [accepted, rolled-back, rollback-failed, failed, refused]}
   deployRegistry:
     description: >-
       The image registry and the visibility the app's packages are meant to have. The canon scaffold writes `public`; the value then belongs to the app.

package/runtime/scripts/hfs/stack-deploy-config.d.mts

@@ -99,6 +99,16 @@ export interface BackupConfig {
         volume: string;
     }>;
 }
+/** The outcomes of a deploy attempt a notification can be sent for. */
+export declare const NOTIFY_OUTCOMES: readonly ["accepted", "rolled-back", "rollback-failed", "failed", "refused"];
+/** `deploy.notify`: the sealed member and key that hold the webhook URL (https), and the outcomes that are announced. */
+export interface NotifyConfig {
+    webhook: {
+        member: string;
+        key: string;
+    };
+    on: string[];
+}
 export interface RegistryConfig {
     host: string;
     visibility: string;
@@ -124,6 +134,8 @@ export interface DeployConfig {
     tasks: Record<string, TaskConfig>;
     postDeploy: string[];
     backup: BackupConfig | null;
+    /** deploy.notify: one webhook message per deploy outcome; null (off) unless declared. */
+    notify: NotifyConfig | null;
     ingress: IngressConfig | null;
     registry: RegistryConfig;
 }

package/runtime/scripts/hfs/stack-deploy-config.mjs

@@ -5,6 +5,8 @@ import { isPlainObject as plain } from '../../engine/plain-object.mjs';
 import { closedFields, collector, patternField, treeFile } from './stack-config-kit.mjs';
 import { list } from '../lib/list.mjs';
 import { normalizeIngress } from './stack-ingress-config.mjs';
+/** The outcomes of a deploy attempt a notification can be sent for. */
+export const NOTIFY_OUTCOMES = ['accepted', 'rolled-back', 'rollback-failed', 'failed', 'refused'];
 export const DEPLOY_CONFIG_CODE = 'STACKS_DEPLOY_CONFIG_INVALID';
 export const NAME = /^[a-z][a-z0-9-]*$/u;
 export const KEY = /^[A-Z][A-Z0-9_]*$/u;
@@ -17,7 +19,7 @@ const PINNED_HELPER_IMAGE = /^[a-z0-9./_-]+(?::[A-Za-z0-9._-]+)?@sha256:(?!0{64}
 const ARGUMENT = /^[A-Za-z0-9_@%+=:,./-]+$/u;
 const UPPER_ENV = KEY;
 const FIELDS = {
-    deploy: ['stack', 'remote', 'images', 'volumes', 'secrets', 'environment', 'configs', 'passEnv', 'auto', 'approval', 'platforms', 'postDeploy', 'verify', 'jobs', 'tasks', 'backup', 'ingress', 'registry'],
+    deploy: ['stack', 'remote', 'images', 'volumes', 'secrets', 'environment', 'configs', 'passEnv', 'auto', 'approval', 'platforms', 'postDeploy', 'verify', 'jobs', 'tasks', 'backup', 'notify', 'ingress', 'registry'],
     remote: ['host', 'releasesBase', 'sealed', 'serverRecipient'],
     image: ['app', 'buildArgs'],
     buildArgs: ['values', 'sealed'],
@@ -36,6 +38,8 @@ const FIELDS = {
     backup: ['image', 'keepDays', 'dir', 'volumes'],
     backupVolume: ['name', 'volume'],
     registry: ['host', 'visibility'],
+    notify: ['webhook', 'on'],
+    webhook: ['member', 'key'],
 };
 const text = (value) => typeof value === 'string' && value.length > 0;
 const APPROVALS = ['none', 'reviewers'];
@@ -409,6 +413,22 @@ function backup(c, block) {
         c.problem('deploy.backup.volumes', 'must list at least one volume');
     return { image: block.image, keepDays: block.keepDays ?? 14, dir: block.dir ?? null, volumes };
 }
+/**
+ * `deploy.notify`: off unless declared. The webhook URL is a sealed value (never in the declaration, the log or the journal); the default announces every
+ * outcome that changed or tried to change the services (accepted, rolled-back, rollback-failed, failed), and `on` narrows or adds `refused`.
+ */
+function notify(c, block, members) {
+    if (block === undefined)
+        return null;
+    if (!closedFields(c, 'deploy.notify', block, FIELDS.notify))
+        return null;
+    if (!closedFields(c, 'deploy.notify.webhook', block.webhook, FIELDS.webhook))
+        return null;
+    memberRef(c, 'deploy.notify.webhook.member', block.webhook.member, members);
+    patternField(c, 'deploy.notify.webhook.key', block.webhook.key, KEY);
+    const on = block.on === undefined ? ['accepted', 'rolled-back', 'rollback-failed', 'failed'] : stringList(c, 'deploy.notify.on', block.on, new RegExp(`^(?:${NOTIFY_OUTCOMES.join('|')})$`, 'u'), { nonEmpty: true });
+    return { webhook: { member: block.webhook.member, key: block.webhook.key }, on };
+}
 function ingress(c, block, probe) {
     if (block === undefined)
         return null;
@@ -450,6 +470,7 @@ export function normalizeDeploy(block, { project, probe }) {
         tasks,
         postDeploy: postDeploy(c, block.postDeploy, tasks),
         backup: backup(c, block.backup),
+        notify: notify(c, block.notify, members),
         ingress: ingress(c, block.ingress, probe),
         registry: registry(c, block.registry),
     };

package/src/stack-records-double.d.mts

@@ -1,6 +1,6 @@
 import type { ReleaseStore, StoredRelease } from '../stack/release-store.mjs';
 /** The records half of a ReleaseStore, plus what it kept. */
-export interface RecordsDouble extends Pick<ReleaseStore, 'read' | 'tryLock' | 'refreshLock' | 'unlock' | 'journal'> {
+export interface RecordsDouble extends Pick<ReleaseStore, 'read' | 'tryLock' | 'refreshLock' | 'unlock' | 'journal' | 'journals'> {
     /** The latest document of each attempt, as the journal wrote it (a copy at each write). */
     documents: Map<string, Record<string, unknown>>;
     /** Every write of every document, in order: the phase boundaries a cancelled job would have left. */
@@ -25,6 +25,8 @@ export interface RecordsOptions {
         freeAfterTries?: number;
     } | undefined;
     failJournal?: boolean | undefined;
+    /** The attempt documents the journal already holds (what journals() answers): the evidence of the manual rollback guard. */
+    history?: Record<string, unknown>[] | undefined;
     /** The journal accepts this many document writes and fails every later one (a manager that drops mid-deploy). */
     failJournalAfter?: number | undefined;
 }

package/stack/ci-key.d.mts

@@ -0,0 +1,11 @@
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { ActionResult } from './remote.mjs';
+/** What the verb takes. */
+export interface CiKeyOptions {
+    publicKey?: string | null | undefined;
+    printAuthorizedKeys?: boolean | undefined;
+    printGate?: boolean | undefined;
+}
+/** Prints the gate, the authorized_keys line or the install steps (see the top of the file). */
+export declare function ciKey(_ctx: StackContext, config: DeployConfig, options?: CiKeyOptions): Promise<ActionResult>;

package/stack/ci-key.mjs

@@ -0,0 +1,44 @@
+// ci-key.mjs - `starci app stack ci-key`: the owner-run side of the forced-command gate of the CI SSH key (ssh-gate.mts).
+//   --print-gate              prints the text of starci-ssh-gate, to install executable as /usr/local/bin/starci-ssh-gate on the manager
+//   --print-authorized-keys   prints the authorized_keys line of the CI key from its PUBLIC key file (--public-key <file>)
+// Both print only their text, so they pipe straight into the owner's ssh. Nothing here reaches a server, reads a sealed member or touches a private
+// key: creating, installing and rotating the key stay owner-run steps. Without a flag the verb prints the install steps.
+import fs from 'node:fs';
+import { refusal } from './errors.mjs';
+import { GATE_PATH, authorizedKeysLine, gateScript } from './ssh-gate.mjs';
+const lineOf = (file) => {
+    if (!file)
+        throw refusal('STACK_USAGE', '--print-authorized-keys needs --public-key <the .pub file of the CI key>');
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        throw refusal('STACK_CI_KEY_PUBLIC', `cannot read the public key file ${file}`);
+    }
+    return authorizedKeysLine(text);
+};
+/** Prints the gate, the authorized_keys line or the install steps (see the top of the file). */
+export async function ciKey(_ctx, config, options = {}) {
+    if (options.printGate === true && options.printAuthorizedKeys === true)
+        throw refusal('STACK_USAGE', 'print the gate or the authorized_keys line, one at a time');
+    if (options.printGate === true)
+        return { ok: true, lines: [gateScript().trimEnd()], data: { gatePath: GATE_PATH } };
+    if (options.printAuthorizedKeys === true) {
+        const line = lineOf(options.publicKey);
+        return { ok: true, lines: [line], data: { authorizedKeys: line } };
+    }
+    const env = config.env;
+    return {
+        ok: true,
+        lines: [
+            'the CI key reaches Docker, which is root on the manager: its authorized_keys line forces starci-ssh-gate, which admits docker system dial-stdio and the release store\'s named operations only.',
+            'owner-run steps on the manager (as root; <ops> is your own ssh access):',
+            `  1. starci app stack ci-key --env ${env} --print-gate | ssh <ops> 'install -m 0755 -o root -g root /dev/stdin ${GATE_PATH}'`,
+            `  2. starci app stack ci-key --env ${env} --public-key <ci-key.pub> --print-authorized-keys | ssh <ops> 'cat >> ~<ci-account>/.ssh/authorized_keys'`,
+            '  3. seal VPS_GATE=1 in the vps-ci member of the environment, so `stack connect` tells the deploy to use the gate (STARCI_SSH_GATE=1); remove it to go back.',
+            'not yet admitted by the gate: the post-deploy tasks and the manager backup/decrypt of a stack database run free commands; keep those environments on an ungated key until they are named operations.',
+        ],
+        data: { gatePath: GATE_PATH },
+    };
+}

package/stack/cli.d.mts

@@ -15,6 +15,10 @@ export interface Flags {
     urgent?: boolean;
     'first-start'?: boolean;
     redeploy?: boolean;
+    'data-acknowledged'?: boolean;
+    'print-authorized-keys'?: boolean;
+    'print-gate'?: boolean;
+    'public-key'?: string;
     image?: string[];
     keep?: string[];
     'extra-compose'?: string[];
@@ -36,7 +40,7 @@ export interface Flags {
     remote?: string;
     'ci-run'?: string;
 }
-export declare const ACTIONS: readonly ["prepare", "connect", "disconnect", "build-args", "render", "deploy", "converge", "verify", "rollback", "prune", "backup", "jobs", "task", "ingress", "retire", "build", "accept", "status"];
+export declare const ACTIONS: readonly ["prepare", "connect", "disconnect", "build-args", "render", "deploy", "converge", "verify", "rollback", "prune", "backup", "jobs", "task", "ingress", "retire", "build", "accept", "status", "ci-key"];
 /** One action of `starci app stack`. */
 export type Action = (typeof ACTIONS)[number];
 /** True when `value` names one action of `starci app stack`. */

package/stack/cli.mjs

@@ -20,11 +20,11 @@ import { parseTargetBinding, bindStackTarget, nativeToolEnvironment } from './ta
 import { oneCommand, prepareUrgentRelease } from './urgent-release.mjs';
 /** The actions that drive the docker CLI of the operator machine (pointed at the manager by docker-transport.mjs when the key is sealed). */
 const DOCKER_ACTIONS = new Set(['deploy', 'accept', 'converge', 'verify', 'rollback', 'prune', 'status']);
-export const ACTIONS = Object.freeze(['prepare', 'connect', 'disconnect', 'build-args', 'render', 'deploy', 'converge', 'verify', 'rollback', 'prune', 'backup', 'jobs', 'task', 'ingress', 'retire', 'build', 'accept', 'status']);
+export const ACTIONS = Object.freeze(['prepare', 'connect', 'disconnect', 'build-args', 'render', 'deploy', 'converge', 'verify', 'rollback', 'prune', 'backup', 'jobs', 'task', 'ingress', 'retire', 'build', 'accept', 'status', 'ci-key']);
 /** True when `value` names one action of `starci app stack`. */
 export const isAction = (value) => ACTIONS.includes(value);
-export const BOOLEAN = new Set(['--execute', '--json', '--swarm-state', '--init-swarm', '--owner-approved', '--fix-live-restore', '--skip-public', '--skip-internal', '--allow-unpinned', '--push', '--urgent', '--first-start', '--redeploy']);
-export const VALUE = new Set(['--env', '--image', '--sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project', '--target-binding', '--db-url-env', '--backup-out', '--db-service', '--reason', '--remote', '--ci-run']);
+export const BOOLEAN = new Set(['--execute', '--json', '--swarm-state', '--init-swarm', '--owner-approved', '--fix-live-restore', '--skip-public', '--skip-internal', '--allow-unpinned', '--push', '--urgent', '--first-start', '--redeploy', '--data-acknowledged', '--print-authorized-keys', '--print-gate']);
+export const VALUE = new Set(['--env', '--image', '--sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project', '--target-binding', '--db-url-env', '--backup-out', '--db-service', '--reason', '--remote', '--ci-run', '--public-key']);
 export const REPEAT = new Set(['--image', '--keep', '--extra-compose', '--project']);
 /** `--ssh-cmd` replaces the configured alias for an action whose module (or the Docker transport) reaches the manager over SSH. */
 const SSH = ['--ssh-cmd'];
@@ -41,7 +41,7 @@ export const FLAGS = Object.freeze({
     deploy: ['--image', '--sha', '--execute', '--out', '--timeout', '--retry', '--skip-public', '--target-binding', '--urgent', '--reason', '--remote', '--db-url-env', '--backup-out', '--first-start', '--db-service', '--ci-run', '--redeploy', ...SSH],
     converge: ['--since', '--timeout', ...SSH],
     verify: ['--retry', '--skip-public', '--skip-internal', '--target-binding', ...SSH],
-    rollback: ['--release', '--execute', '--timeout', ...SSH],
+    rollback: ['--release', '--execute', '--timeout', '--data-acknowledged', ...SSH],
     prune: ['--keep', '--execute', ...SSH],
     backup: ['--swarm-state', '--execute', ...SSH],
     jobs: ['--execute', ...SSH],
@@ -51,11 +51,12 @@ export const FLAGS = Object.freeze({
     build: ['--push', '--execute'],
     accept: ['--release', '--execute', '--retry', '--db-url-env', ...SSH],
     status: [...SSH],
+    'ci-key': ['--public-key', '--print-authorized-keys', '--print-gate'],
 });
 /** The operands of the actions that take any, as the usage prints them. */
 export const OPERANDS = Object.freeze({ jobs: '<action> [<arg>...]', task: '<name> [<arg>...]', ingress: '<action> [<arg>...]' });
 /** The read-only actions, whose `--env` defaults to production. Every action with an effect names its environment, so none reaches production by omission. */
-export const READ_ONLY = Object.freeze(['build-args', 'render', 'verify', 'status']);
+export const READ_ONLY = Object.freeze(['build-args', 'render', 'verify', 'status', 'ci-key']);
 /** Splits argv into { flags, positional }; an unknown flag, a flag of another action or a flag without its value is a refusal. */
 function parseFlags(action, argv) {
     const own = new Set(['--env', '--json', ...FLAGS[action]]);
@@ -137,13 +138,14 @@ const OPTIONS = {
     }),
     converge: ({ flags }) => ({ since: flags.since, timeoutSeconds: number(flags, 'timeout') }),
     verify: ({ flags }) => ({ retrySeconds: number(flags, 'retry'), skipPublic: flags['skip-public'] === true, skipInternal: flags['skip-internal'] === true }),
-    rollback: ({ flags }) => ({ release: flags.release ?? null, execute: flags.execute === true, timeoutSeconds: number(flags, 'timeout') }),
+    rollback: ({ flags }) => ({ release: flags.release ?? null, execute: flags.execute === true, timeoutSeconds: number(flags, 'timeout'), dataAcknowledged: flags['data-acknowledged'] === true }),
     prune: ({ flags, cwd }) => ({ keepFiles: (flags.keep ?? []).map((file) => path.resolve(cwd, file)), execute: flags.execute === true }),
     backup: ({ flags }) => ({ swarmState: flags['swarm-state'] === true, execute: flags.execute === true }),
     ingress: ({ flags, positional }) => ({ action: positional[0], execute: flags.execute === true, args: positional.slice(1) }),
     build: ({ flags }) => ({ push: flags.push === true, execute: flags.execute === true }),
     accept: ({ flags }) => ({ release: flags.release ?? null, execute: flags.execute === true, retrySeconds: number(flags, 'retry'), dbUrlEnv: flags['db-url-env'] }),
     status: () => ({}),
+    'ci-key': ({ flags, cwd }) => ({ publicKey: flags['public-key'] ? path.resolve(cwd, flags['public-key']) : null, printAuthorizedKeys: flags['print-authorized-keys'] === true, printGate: flags['print-gate'] === true }),
     retire: ({ flags }) => ({ projects: flags.project ?? [], execute: flags.execute === true }),
     jobs: ({ flags, positional }) => ({ action: positional[0], args: positional.slice(1), execute: flags.execute === true }),
     task: ({ flags, positional }) => ({ name: positional[0], args: positional.slice(1), execute: flags.execute === true }),
@@ -160,6 +162,7 @@ const MODULES = {
     build: ['./build.mjs', 'buildImages'],
     accept: ['./deploy.mjs', 'acceptRelease'],
     status: ['./status.mjs', 'statusStack'],
+    'ci-key': ['./ci-key.mjs', 'ciKey'],
 };
 async function handlerOf(action, importer) {
     const [file, name] = MODULES[action];

package/stack/config.d.mts

@@ -84,6 +84,14 @@ export interface BackupBlock {
     dir: string | null;
     volumes: BackupVolume[];
 }
+/** The normalised `deploy.notify` block: the sealed webhook URL and the outcomes announced. */
+export interface NotifyBlock {
+    webhook: {
+        member: string;
+        key: string;
+    };
+    on: string[];
+}
 export interface RegistryBlock {
     host: string;
     visibility: string;
@@ -172,6 +180,7 @@ export interface DeployBlock {
     tasks: Record<string, TaskEntry>;
     postDeploy: string[];
     backup: BackupBlock | null;
+    notify: NotifyBlock | null;
     ingress: IngressConfig | null;
     registry: RegistryBlock;
 }

package/stack/deploy.d.mts

@@ -41,6 +41,7 @@ export interface RollbackOptions {
     timeoutSeconds?: number | undefined;
     sshCmd?: string | null | undefined;
     lockWaitSeconds?: number | undefined;
+    dataAcknowledged?: boolean | undefined;
 }
 /** What an accept takes. */
 export interface AcceptOptions {
@@ -70,7 +71,9 @@ export interface DeployDeps {
         keepFiles: string[];
         execute: boolean;
     }) => Promise<ActionResult>;
-    releaseStore: (config: DeployConfig, ssh: Runner) => ReleaseStore;
+    releaseStore: (config: DeployConfig, ssh: Runner, options?: {
+        gated?: boolean | undefined;
+    }) => ReleaseStore;
     observedServices: (ctx: StackContext, config: DeployConfig) => ObservedService[];
     ssh: (ctx: StackContext, config: DeployConfig, options: SshOptions) => Runner | Promise<Runner>;
     floor: Partial<FloorDeps>;

package/stack/deploy.mjs

@@ -42,6 +42,8 @@ import { pruneStack } from './prune.mjs';
 import { compareWithRelease, observedServices, stackImages } from './status.mjs';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { createReleaseStore } from './release-store.mjs';
+import { contractFinding, enforceContractGuard } from './rollback-guard.mjs';
+import { gateIsOn } from './ssh-gate.mjs';
 import { urgentDeploy } from './urgent-floor.mjs';
 import { verifyStack } from './verify.mjs';
 /** Loads `file` (relative to this module). Split out so a spec can load a real sibling module through `lazy`. */
@@ -163,7 +165,7 @@ async function openRunner(ctx, config, options, d, cleanups) {
     cleanups.push(() => run.cleanup?.());
     return run;
 }
-const openStore = async (ctx, config, options, d, cleanups) => d.releaseStore(config, await openRunner(ctx, config, options, d, cleanups));
+const openStore = async (ctx, config, options, d, cleanups) => d.releaseStore(config, await openRunner(ctx, config, options, d, cleanups), { gated: gateIsOn(ctx.env) });
 /** Redeploys a stored release after a failed deploy: fetch, stack deploy, converge. Returns the lines to print. */
 async function redeployStored(ctx, config, d, store, previous, out, steps, rec) {
     const dir = path.join(out, 'previous');
@@ -352,7 +354,7 @@ async function deployExecute(ctx, config, options, d, out, seams) {
         const contract = phase && !first ? await rec.phase('contract', () => contractPhase(phase), (done) => done.ok) : null;
         if (contract) {
             lines.push(...contract.lines);
-            rec.note({ migrations: [...(data.migrations?.applied ?? []), ...contract.applied] });
+            rec.note({ migrations: [...(data.migrations?.applied ?? []), ...contract.applied], contract: contract.applied });
             steps.push({ step: 'contract', ok: contract.ok });
             data.migrations = { ...data.migrations, contractApplied: contract.applied };
         }
@@ -413,7 +415,7 @@ export async function deployRelease(ctx, config, options = {}, deps = {}) {
         if (options.urgent !== true)
             await render();
         const run = await openRunner(ctx, config, options, d, cleanups);
-        const store = d.releaseStore(config, run);
+        const store = d.releaseStore(config, run, { gated: gateIsOn(ctx.env) });
         const meta = {
             kind: 'deploy', trigger: triggerOf(options), sourceSha: options.sourceSha, ciRun: options.ciRun,
             urgent: options.urgent === true ? { role: ctx.env.STARCI_ROLE ?? 'unknown', reason: options.reason ?? '' } : undefined,
@@ -457,8 +459,10 @@ export async function rollbackRelease(ctx, config, options = {}, deps = {}) {
         const target = release ?? await store.previous();
         if (!target)
             throw refusal('STACK_ROLLBACK_NO_TARGET', 'no previous accepted release is recorded; name one with --release');
+        // A manual rollback to a release older than an applied contract migration is refused unless the owner acknowledges the data effect.
+        const notice = enforceContractGuard(contractFinding(await store.journals(), target), options.dataAcknowledged === true);
         if (options.execute !== true)
-            return { ok: true, lines: [`dry run: would redeploy release ${target}`], data: { release: target, executed: false } };
+            return { ok: true, lines: [...notice, `dry run: would redeploy release ${target}`], data: { release: target, executed: false } };
         return await recordedAttempt(ctx, config, store, { kind: 'rollback', trigger: 'dispatch' }, { waitSeconds: options.lockWaitSeconds }, async (rec) => {
             const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-rollback-'));
             try {
@@ -475,6 +479,7 @@ export async function rollbackRelease(ctx, config, options = {}, deps = {}) {
                     ['verify', () => d.verifyStack(ctx, config, { retrySeconds: 180, stackFile })],
                     ['accept', async () => { await acceptObserved(ctx, config, d, store, rec, { out: scratch, releaseId: target }); return { ok: true, lines: [] }; }],
                 ], lines, steps, rec);
+                lines.unshift(...notice);
                 lines.push(failed ? `rollback to ${target} failed at ${failed}` : `rolled back to release ${target}; a rollback cannot undo data effects`);
                 return { ok: !failed, lines, data: { release: target, executed: true, steps } };
             }
@@ -525,7 +530,7 @@ export async function acceptRelease(ctx, config, options = {}, deps = {}) {
             const contract = database ? await rec.phase('contract', () => contractPhase({ ctx, config, database, f: { ...FLOOR_DEPS, ...d.floor }, run: null, dbUrlEnv: options.dbUrlEnv }), (done) => done.ok) : null;
             if (contract) {
                 lines.push(...contract.lines);
-                rec.note({ migrations: contract.applied });
+                rec.note({ migrations: contract.applied, contract: contract.applied });
             }
             if (contract && !contract.ok)
                 return { ok: false, lines: [...lines, `release ${release} is accepted and serving; its contract migration is red: the owner decides`], data: { release, accepted: true, executed: true, contractFailed: true } };

package/stack/journal.d.mts

@@ -47,6 +47,8 @@ export interface AttemptDocument {
     backup: Record<string, unknown> | null;
     /** Reserved for the migrate and contract phases: the names of the migrations that were applied. */
     migrations: string[];
+    /** The contract migrations this attempt applied (the marker the manual rollback guard reads); empty when it applied none. */
+    contract: string[];
     /** `docker service inspect` snapshots by moment: `converge`, `rollback`, `accept`. */
     observed: Record<string, ObservedService[]>;
     outcome: Outcome;
@@ -55,6 +57,20 @@ export interface AttemptDocument {
         message: string;
     } | null;
 }
+/** The facts of a finished attempt that a notification carries: names, digests and codes, never a message text or a value. */
+export interface AttemptSummary {
+    attempt: string;
+    kind: AttemptKind;
+    stack: string;
+    env: string;
+    outcome: Outcome;
+    trigger: Trigger;
+    sourceSha: string | null;
+    tag: string | null;
+    releaseId: string | null;
+    ciUrl: string | null;
+    errorCode: string | null;
+}
 /** What an attempt is told about itself when it opens. */
 export interface AttemptMeta {
     kind: AttemptKind;
@@ -74,6 +90,7 @@ export interface Note {
     previous?: string | null;
     backup?: Record<string, unknown> | null;
     migrations?: string[];
+    contract?: string[];
     urgent?: {
         role: string;
         reason: string;
@@ -95,6 +112,8 @@ export interface Recorder {
         code: string;
         message: string;
     } | null): Promise<void>;
+    /** The facts of the attempt as it stands (call after `finish` for a notification). */
+    summary(): AttemptSummary;
 }
 /** A new attempt id: the UTC time and 8 random hex characters. */
 export declare const newAttemptId: (ctx: Pick<StackContext, "now">) => string;

package/stack/journal.mjs

@@ -11,6 +11,7 @@
 import { randomBytes } from 'node:crypto';
 import { firstLine } from './context.mjs';
 import { StackError, refusal } from './errors.mjs';
+import { notifyOutcome } from './notify.mjs';
 const REASON_MAX = 500;
 const SAFE = /[^A-Za-z0-9._/:@ -]/gu;
 const isoOf = (ctx) => new Date(ctx.now()).toISOString();
@@ -39,7 +40,7 @@ export async function openAttempt(ctx, config, store, meta) {
         schema: 'starci/stack-deploy-attempt@1', attempt: id, kind: meta.kind, stack: config.stack, env: config.env, startedAt: isoOf(ctx), endedAt: null,
         trigger: meta.trigger, sourceSha: meta.sourceSha ?? null, tag: facts.tag, ci: facts.ci,
         urgent: meta.urgent ? { role: clean(meta.urgent.role, 40), reason: meta.urgent.reason.slice(0, REASON_MAX), tag: meta.urgent.tag ?? null } : null,
-        releaseId: null, previous: null, phases: [], backup: null, migrations: [], observed: {}, outcome: 'running', error: null,
+        releaseId: null, previous: null, phases: [], backup: null, migrations: [], contract: [], observed: {}, outcome: 'running', error: null,
     };
     const warnings = [];
     let beat = async () => { };
@@ -70,6 +71,8 @@ export async function openAttempt(ctx, config, store, meta) {
                 document.backup = found.backup;
             if (found.migrations !== undefined)
                 document.migrations = found.migrations;
+            if (found.contract !== undefined)
+                document.contract = found.contract;
             if (found.urgent)
                 document.urgent = { role: clean(found.urgent.role, 40), reason: found.urgent.reason.slice(0, REASON_MAX), tag: found.urgent.tag ?? null };
         },
@@ -93,6 +96,10 @@ export async function openAttempt(ctx, config, store, meta) {
             }
         },
         snapshot(moment, services) { document.observed[moment] = services; },
+        summary: () => ({
+            attempt: id, kind: document.kind, stack: document.stack, env: document.env, outcome: document.outcome, trigger: document.trigger,
+            sourceSha: document.sourceSha, tag: document.tag, releaseId: document.releaseId, ciUrl: document.ci?.url ?? null, errorCode: document.error?.code ?? null,
+        }),
         async finish(outcome, error = null) {
             document.outcome = outcome;
             document.endedAt = isoOf(ctx);
@@ -165,10 +172,12 @@ export async function recordedAttempt(ctx, config, store, meta, wait, body) {
         });
         const result = await body(recorder);
         await recorder.finish(outcomeOf(result, meta.kind), result.refused ? { code: result.refused.code, message: result.refused.message.slice(0, 300) } : null);
-        return { ...result, lines: [...result.lines, ...recorder.warnings], data: { ...result.data, attempt: recorder.id } };
+        const notice = await notifyOutcome(ctx, config, recorder.summary());
+        return { ...result, lines: [...result.lines, ...recorder.warnings, ...notice], data: { ...result.data, attempt: recorder.id } };
     }
     catch (error) {
         await recorder.finish('refused', errorOf(error));
+        await notifyOutcome(ctx, config, recorder.summary());
         throw error;
     }
     finally {

package/stack/notify.d.mts

@@ -0,0 +1,9 @@
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { AttemptSummary } from './journal.mjs';
+/** The one-line text a chat webhook shows. */
+export declare function notifyText(summary: AttemptSummary): string;
+/** The JSON body: `text` (Slack style) and `content` (Discord style) carry the line, the rest is the same facts as fields. */
+export declare function notifyBody(summary: AttemptSummary): Record<string, unknown>;
+/** Sends the message for a finished attempt when `deploy.notify` is declared and lists its outcome; returns the lines to print (empty when nothing was sent or it went well). */
+export declare function notifyOutcome(ctx: StackContext, config: Pick<DeployConfig, 'notify' | 'secretsDir'>, summary: AttemptSummary): Promise<string[]>;

package/stack/notify.mjs

@@ -0,0 +1,32 @@
+import { openMember } from './sealed.mjs';
+const TIMEOUT_MS = 10_000;
+const HTTPS_URL = /^https:\/\/[^\s]+$/u;
+/** The one-line text a chat webhook shows. */
+export function notifyText(summary) {
+    const commit = summary.sourceSha ? ` of ${summary.sourceSha.slice(0, 10)}` : '';
+    const tag = summary.tag ? ` (${summary.tag})` : '';
+    const release = summary.releaseId ? `, release ${summary.releaseId}` : '';
+    const failure = summary.errorCode ? `, ${summary.errorCode}` : '';
+    return `[${summary.stack}/${summary.env}] ${summary.kind} ${summary.outcome}${commit}${tag}${release}${failure}`;
+}
+/** The JSON body: `text` (Slack style) and `content` (Discord style) carry the line, the rest is the same facts as fields. */
+export function notifyBody(summary) {
+    const text = notifyText(summary);
+    return { text, content: text, ...summary };
+}
+/** Sends the message for a finished attempt when `deploy.notify` is declared and lists its outcome; returns the lines to print (empty when nothing was sent or it went well). */
+export async function notifyOutcome(ctx, config, summary) {
+    const declared = config.notify;
+    if (!declared || !declared.on.includes(summary.outcome))
+        return [];
+    try {
+        const url = openMember(ctx, config, declared.webhook.member)[declared.webhook.key];
+        if (typeof url !== 'string' || !HTTPS_URL.test(url))
+            return [`notify: the sealed ${declared.webhook.member} holds no https URL under ${declared.webhook.key}; nothing was sent`];
+        const response = await ctx.fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(notifyBody(summary)), redirect: 'error', signal: AbortSignal.timeout(TIMEOUT_MS) });
+        return response.ok ? [] : [`notify: the webhook answered HTTP ${response.status}; the deploy outcome stands`];
+    }
+    catch (error) {
+        return [`notify: the message was not sent (${error.name === 'TimeoutError' ? 'timed out' : 'the webhook could not be reached'}); the deploy outcome stands`];
+    }
+}

package/stack/release-store.d.mts

@@ -48,20 +48,22 @@ export interface ReleaseStore {
     unlock(token: string): Promise<boolean>;
     /** The journal of one attempt under /srv/<stack>/deploys. */
     journal(attempt: string): AttemptJournal;
+    /** The newest attempt documents (at most 500), oldest first; a document that is not a JSON object is left out. */
+    journals(): Promise<Record<string, unknown>[]>;
 }
 /** A lock nobody refreshed for this long (its holder died without releasing it) is taken over by the next try. Phases refresh it. */
 export declare const LOCK_TTL_SECONDS = 3600;
 /** An attempt id: UTC compact time and 8 random hex. */
 export declare const ATTEMPT_ID: RegExp;
 /**
- * The remote script of one try at the deploy lock: `mkdir` is the atomic claim, the owner file (token, trigger, epoch) is replaced by rename, a lock
- * unrefreshed for `ttl` seconds is moved aside (one rename wins) and claimed anew. Prints `acquired` or `busy <trigger> <age>`. Composed only from
- * a validated base, token and trigger.
+ * The remote command of one try at the deploy lock (ssh-gate.mts holds the body): `mkdir` is the atomic claim, the owner file (token, trigger, epoch) is
+ * replaced by rename, a lock unrefreshed for `ttl` seconds is moved aside (one rename wins) and claimed anew. Prints `acquired` or `busy <trigger> <age>`.
+ * Composed only from a validated base, token and trigger.
  */
 export declare const lockAcquireScript: (base: string, token: string, trigger: string, ttl?: number) => string;
-/** The remote script that marks the lock alive when `token` owns it: prints `held` or `lost`. */
+/** The remote command that marks the lock alive when `token` owns it: prints `held` or `lost`. */
 export declare const lockRefreshScript: (base: string, token: string) => string;
-/** The remote script that removes the lock when `token` owns it: prints `released` or `lost`. */
+/** The remote command that removes the lock when `token` owns it: prints `released` or `lost`. */
 export declare const lockReleaseScript: (base: string, token: string) => string;
 /** Removes every carriage return: a snippet from a Windows checkout must never reach a remote shell with CRLF. */
 export declare const lfOnly: (text: unknown) => string;
@@ -69,4 +71,6 @@ export declare const lfOnly: (text: unknown) => string;
  * The release store of one stack. `ssh` is the runner; the returned API is async:
  *   store(dir, id) accept(id) current() previous() fetch(id, targetDir) list()
  */
-export declare function createReleaseStore(config: Pick<DeployConfig, 'remote' | 'stack'>, ssh: StoreSsh): ReleaseStore;
+export declare function createReleaseStore(config: Pick<DeployConfig, 'remote' | 'stack'>, ssh: StoreSsh, options?: {
+    gated?: boolean | undefined;
+}): ReleaseStore;

package/stack/release-store.mjs

@@ -8,7 +8,7 @@ import path from 'node:path';
 import { firstLine, lines as splitLines } from './context.mjs';
 import { isReleaseId } from './digest.mjs';
 import { failure, refusal } from './errors.mjs';
-import { releaseListScript, releasePointerScript } from './remote.mjs';
+import { gatedCommand, inlineCommand } from './ssh-gate.mjs';
 /** A lock nobody refreshed for this long (its holder died without releasing it) is taken over by the next try. Phases refresh it. */
 export const LOCK_TTL_SECONDS = 3600;
 const TOKEN = /^[0-9a-f]{32}$/u;
@@ -30,27 +30,16 @@ const checkedAttempt = (attempt) => {
         throw refusal('STACK_ATTEMPT_ID', 'an attempt id is a UTC compact time and 8 lowercase hex characters');
     return attempt;
 };
-const OWNER_READ = (lock) => `if [ -r "${lock}/owner" ]; then read -r held_token held_trigger held_stamp < "${lock}/owner"; else held_token=none; held_trigger=unknown; held_stamp=$(stat -c %Y "${lock}" 2>/dev/null) || held_stamp=0; fi; case "$held_stamp" in ''|*[!0-9]*) held_stamp=0;; esac`;
 /**
- * The remote script of one try at the deploy lock: `mkdir` is the atomic claim, the owner file (token, trigger, epoch) is replaced by rename, a lock
- * unrefreshed for `ttl` seconds is moved aside (one rename wins) and claimed anew. Prints `acquired` or `busy <trigger> <age>`. Composed only from
- * a validated base, token and trigger.
+ * The remote command of one try at the deploy lock (ssh-gate.mts holds the body): `mkdir` is the atomic claim, the owner file (token, trigger, epoch) is
+ * replaced by rename, a lock unrefreshed for `ttl` seconds is moved aside (one rename wins) and claimed anew. Prints `acquired` or `busy <trigger> <age>`.
+ * Composed only from a validated base, token and trigger.
  */
-export const lockAcquireScript = (base, token, trigger, ttl = LOCK_TTL_SECONDS) => {
-    const lock = `${base}/deploy.lock`;
-    return [
-        `b="${base}"; l="${lock}"; now=$(date +%s); mkdir -p "$b" || exit 1`,
-        `claim() { printf '%s %s %s\\n' '${checkedToken(token)}' '${checkedTrigger(trigger)}' "$now" > "$l/owner.new" && mv -f "$l/owner.new" "$l/owner" && echo acquired && exit 0; exit 1; }`,
-        'if mkdir "$l" 2>/dev/null; then claim; fi',
-        OWNER_READ('$l'),
-        `age=$((now - held_stamp)); if [ "$age" -gt ${Math.trunc(ttl)} ]; then if mv "$l" "$l.stale.${token}" 2>/dev/null; then rm -rf "$l.stale.${token}"; if mkdir "$l" 2>/dev/null; then claim; fi; fi; fi`,
-        'case "$held_trigger" in ci|dispatch|urgent) ;; *) held_trigger=unknown;; esac; echo "busy $held_trigger $age"',
-    ].join('; ');
-};
-/** The remote script that marks the lock alive when `token` owns it: prints `held` or `lost`. */
-export const lockRefreshScript = (base, token) => `l="${base}/deploy.lock"; now=$(date +%s); if [ -r "$l/owner" ]; then read -r t g s < "$l/owner"; if [ "$t" = '${checkedToken(token)}' ]; then printf '%s %s %s\\n' "$t" "$g" "$now" > "$l/owner.new" && mv -f "$l/owner.new" "$l/owner" && echo held; else echo lost; fi; else echo lost; fi`;
-/** The remote script that removes the lock when `token` owns it: prints `released` or `lost`. */
-export const lockReleaseScript = (base, token) => `l="${base}/deploy.lock"; if [ -r "$l/owner" ]; then read -r t g s < "$l/owner"; if [ "$t" = '${checkedToken(token)}' ]; then rm -rf "$l" && echo released; else echo lost; fi; else echo lost; fi`;
+export const lockAcquireScript = (base, token, trigger, ttl = LOCK_TTL_SECONDS) => inlineCommand('lock-acquire', [base, checkedToken(token), checkedTrigger(trigger), String(Math.trunc(ttl))]);
+/** The remote command that marks the lock alive when `token` owns it: prints `held` or `lost`. */
+export const lockRefreshScript = (base, token) => inlineCommand('lock-refresh', [base, checkedToken(token)]);
+/** The remote command that removes the lock when `token` owns it: prints `released` or `lost`. */
+export const lockReleaseScript = (base, token) => inlineCommand('lock-release', [base, checkedToken(token)]);
 const BASE = /^\/[A-Za-z0-9._/-]+$/u;
 const FILES = ['stack.yaml', 'release.json'];
 /** Removes every carriage return: a snippet from a Windows checkout must never reach a remote shell with CRLF. */
@@ -62,7 +51,7 @@ const checkedId = (id) => {
 };
 const checkedBase = (config) => {
     const base = config.remote?.releasesBase ?? `/srv/${config.stack}`;
-    if (!BASE.test(base) || base.split('/').includes('..'))
+    if (!BASE.test(base) || base.includes('..'))
         throw refusal('STACK_RELEASE_BASE', `the releases base ${base} must be an absolute path without ..`);
     return base;
 };
@@ -70,10 +59,11 @@ const checkedBase = (config) => {
  * The release store of one stack. `ssh` is the runner; the returned API is async:
  *   store(dir, id) accept(id) current() previous() fetch(id, targetDir) list()
  */
-export function createReleaseStore(config, ssh) {
+export function createReleaseStore(config, ssh, options = {}) {
     const base = checkedBase(config);
-    const dirOf = (id) => `${base}/releases/${checkedId(id)}`;
-    async function run(command, input) {
+    /** Runs the named operation: through the forced-command gate (`starci-op <name> <args>`) when the key has one, else as the same body under `sh -c`. */
+    async function run(name, args, input) {
+        const command = options.gated === true ? gatedCommand(name, args) : inlineCommand(name, args);
         const answer = await ssh(lfOnly(command), { input });
         if (answer.status !== 0)
             throw failure('STACK_RELEASE_SSH', `remote command failed: ${firstLine(answer.stderr)}`);
@@ -88,14 +78,13 @@ export function createReleaseStore(config, ssh) {
         }
     }
     async function pointer(name) {
-        const out = await run(releasePointerScript(`"${base}"`, name));
+        const out = await run('pointer', [base, name]);
         const id = out.trim();
         return isReleaseId(id) ? id : '';
     }
     /** Both files of a stored release as [name, text] pairs, framed as base64 lines. */
     async function readFiles(id) {
-        const source = dirOf(id);
-        const out = await run(`set -e; for f in stack.yaml release.json; do test -r "${source}/$f"; base64 < "${source}/$f" | tr -d '\\n'; printf '\\n'; done`);
+        const out = await run('read', [base, checkedId(id)]);
         const frames = out.split('\n');
         if (frames.length !== 3 || frames[2] !== '' || frames.slice(0, 2).some((frame) => !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(frame)))
             throw failure('STACK_RELEASE_SSH', 'invalid release response framing');
@@ -104,15 +93,15 @@ export function createReleaseStore(config, ssh) {
     return {
         /** Uploads stack.yaml and release.json of a rendered release as text; read-only afterwards. */
         async store(dir, id) {
-            const target = dirOf(id);
+            checkedId(id);
             const contents = FILES.map((name) => [name, readLocal(dir, name)]);
             const input = contents.map(([, text]) => Buffer.from(text, 'utf8').toString('base64')).join('\n') + '\n';
-            await run(`set -e; d="${target}"; if [ -d "$d" ]; then chmod -R u+w "$d"; else mkdir -p "$d"; fi; IFS= read -r stack; IFS= read -r release; printf '%s' "$stack" | base64 -d > "$d/stack.yaml"; printf '%s' "$release" | base64 -d > "$d/release.json"; chmod 440 "$d/stack.yaml" "$d/release.json"; chmod 550 "$d"`, input);
+            await run('store', [base, checkedId(id)], input);
         },
         /** The release was verified: previous := current, current := id. */
         async accept(id) {
             checkedId(id);
-            await run(`set -e; cd "${base}"; test -d "releases/${id}"; if [ -L current ] && [ "$(basename "$(readlink current)")" != "${id}" ]; then ln -sfn "$(readlink current)" previous; fi; ln -sfn "releases/${id}" current.new; mv -Tf current.new current`);
+            await run('accept', [base, id]);
         },
         /** The accepted release id, '' when none. */
         current: () => pointer('current'),
@@ -139,7 +128,7 @@ export function createReleaseStore(config, ssh) {
             return { stackYaml: stack[1], release: record !== null && typeof record === 'object' && !Array.isArray(record) ? record : {} };
         },
         async tryLock(token, trigger) {
-            const answer = (await run(lockAcquireScript(base, token, trigger))).trim();
+            const answer = (await run('lock-acquire', [base, checkedToken(token), checkedTrigger(trigger), String(LOCK_TTL_SECONDS)])).trim();
             if (answer === 'acquired')
                 return { acquired: true };
             const busy = /^busy ([a-z]+) (-?[0-9]+)$/u.exec(answer);
@@ -147,25 +136,39 @@ export function createReleaseStore(config, ssh) {
                 throw failure('STACK_RELEASE_SSH', 'the deploy lock script answered something else than acquired or busy');
             return { acquired: false, holder: busy[1], ageSeconds: Number(busy[2]) };
         },
-        async refreshLock(token) { return (await run(lockRefreshScript(base, token))).trim() === 'held'; },
-        async unlock(token) { return (await run(lockReleaseScript(base, token))).trim() === 'released'; },
+        async refreshLock(token) { return (await run('lock-refresh', [base, checkedToken(token)])).trim() === 'held'; },
+        async unlock(token) { return (await run('lock-release', [base, checkedToken(token)])).trim() === 'released'; },
         journal(attempt) {
             const id = checkedAttempt(attempt);
-            const file = `${base}/deploys/${id}.json`;
             const encoded = (value) => `${Buffer.from(JSON.stringify(value), 'utf8').toString('base64')}
 `;
             return {
                 async write(document) {
-                    await run(`set -e; d="${base}/deploys"; mkdir -p "$d"; IFS= read -r doc; printf '%s' "$doc" | base64 -d > "$d/.${id}.tmp"; mv -f "$d/.${id}.tmp" "${file}"`, encoded(document));
+                    await run('journal-write', [base, id], encoded(document));
                 },
                 async index(entry) {
-                    await run(`set -e; mkdir -p "${base}/deploys"; IFS= read -r line; printf '%s\\n' "$(printf '%s' "$line" | base64 -d)" >> "${base}/deploys.jsonl"`, encoded(entry));
+                    await run('journal-index', [base], encoded(entry));
                 },
             };
         },
+        /** The attempt documents the journal keeps, oldest first. */
+        async journals() {
+            const documents = [];
+            for (const frame of (await run('journal-read', [base])).split('\n')) {
+                if (frame === '')
+                    continue;
+                try {
+                    const parsed = JSON.parse(Buffer.from(frame, 'base64').toString('utf8'));
+                    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed))
+                        documents.push(parsed);
+                }
+                catch { /* a document that cannot be read is no evidence either way */ }
+            }
+            return documents;
+        },
         /** The stored releases, newest first: [{ id, current, previous }]. */
         async list() {
-            const response = await run(`${releasePointerScript(`"${base}"`, 'current')}; ${releasePointerScript(`"${base}"`, 'previous')}; ${releaseListScript(`"${base}"`)}`);
+            const response = await run('list', [base]);
             const [current, previous, ...entries] = response.split('\n');
             const now = isReleaseId(current) ? current : '';
             const before = isReleaseId(previous) ? previous : '';

package/stack/remote.mjs

@@ -228,7 +228,7 @@ function ciValues(ctx, config) {
     if (!present)
         return { values: ctx.env, sealed: false };
     const map = openSealedMember(ctx, config, CI_MEMBER);
-    return { values: Object.fromEntries(CI_VARIABLES.map((name) => [name, typeof map[name] === 'string' ? map[name] : undefined])), sealed: true };
+    return { values: Object.fromEntries([...CI_VARIABLES, 'VPS_GATE'].map((name) => [name, typeof map[name] === 'string' ? map[name] : undefined])), sealed: true };
 }
 function ciInputs(ctx, values, sealed) {
     for (const name of CI_VARIABLES)
@@ -258,9 +258,10 @@ export async function connectCi(ctx, config, { execute = false } = {}) {
     const { values, sealed } = ciValues(ctx, config);
     const inputs = ciInputs(ctx, values, sealed);
     const alias = config.remote.host;
+    const gated = values.VPS_GATE === '1';
     const origin = sealed ? `the sealed member ${CI_MEMBER}` : 'VPS_SSH_KEY';
-    const plan = [`${dir}/deploy_key (0600) from ${origin}`, `${dir}/known_hosts (0644) from ${sealed ? CI_MEMBER : 'VPS_KNOWN_HOSTS'}`, `a Host ${alias} block in ${dir}/config`, `DOCKER_HOST=ssh://${alias} in GITHUB_ENV`];
-    const data = { host: alias, files: ['deploy_key', 'known_hosts', 'config'], sealed };
+    const plan = [...(gated ? ['STARCI_SSH_GATE=1 in GITHUB_ENV (the key is forced through starci-ssh-gate)'] : []), `${dir}/deploy_key (0600) from ${origin}`, `${dir}/known_hosts (0644) from ${sealed ? CI_MEMBER : 'VPS_KNOWN_HOSTS'}`, `a Host ${alias} block in ${dir}/config`, `DOCKER_HOST=ssh://${alias} in GITHUB_ENV`];
+    const data = { host: alias, files: ['deploy_key', 'known_hosts', 'config'], sealed, gated };
     if (!execute)
         return { ok: true, lines: plan.map((item) => `dry run: would write ${item}`), data };
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -268,7 +269,7 @@ export async function connectCi(ctx, config, { execute = false } = {}) {
     writeWithMode(path.join(dir, 'known_hosts'), inputs.known, 0o644);
     fs.appendFileSync(path.join(dir, 'config'), sshBlock(alias, inputs), { mode: 0o600 });
     fs.appendFileSync(ctx.env.GITHUB_ENV, `DOCKER_HOST=ssh://${alias}
-`);
+${gated ? 'STARCI_SSH_GATE=1' + String.fromCharCode(10) : ''}`);
     // The log of a public repository is public: mask the host, the account and the releases root before any later line can carry them.
     const masks = sealed ? [inputs.host, inputs.user, config.remote.releasesBase].filter((value) => typeof value === 'string' && value.length >= 4).map((value) => `::add-mask::${value}`) : [];
     return { ok: true, lines: [...masks, ...plan.map((item) => `wrote ${item}`)], data };

package/stack/rollback-guard.d.mts

@@ -0,0 +1,10 @@
+/** What the guard found. */
+export interface ContractFinding {
+    blocked: boolean;
+    migrations: string[];
+    reason: string;
+}
+/** Judges a rollback to `target` against the attempt documents of the journal (oldest first). */
+export declare function contractFinding(documents: readonly Record<string, unknown>[], target: string): ContractFinding;
+/** Refuses `STACK_ROLLBACK_CONTRACT` when the finding blocks and the owner did not acknowledge the data effect; returns the notice line when it did. */
+export declare function enforceContractGuard(finding: ContractFinding, acknowledged: boolean): string[];

package/stack/rollback-guard.mjs

@@ -0,0 +1,41 @@
+// rollback-guard.mjs - the guard of a manual rollback to an older release.
+// A rollback restores service specs, never data (PROJECT-STACKS-6). A contract migration destroys what the code of the releases before the previous
+// one still uses, so rolling back to such a release after a contract migration ran leaves it on a schema it cannot read. The journal knows both: each
+// attempt that accepted a release carries an `accept` phase, and each attempt that applied contract migrations carries them in `contract`.
+//   chain      the accepted releases in the order the journal accepted them (a rollback is one more entry)
+//   a contract migration applied by the attempt that accepted chain[i] is safe for chain[i] and chain[i-1] (the deploy only runs it once the previous
+//   release no longer uses what it drops), and unsafe for every release accepted for the last time before chain[i-1].
+// A target the journal cannot place is refused as soon as any contract migration is recorded; `--data-acknowledged` is the owner's yes to the loss window.
+import { refusal } from './errors.mjs';
+const accepted = (document) => Array.isArray(document.phases) && document.phases.some((phase) => phase !== null && typeof phase === 'object' && phase.phase === 'accept' && phase.verdict === 'ok');
+const contractOf = (document) => (Array.isArray(document.contract) ? document.contract.filter((name) => typeof name === 'string') : []);
+/** Judges a rollback to `target` against the attempt documents of the journal (oldest first). */
+export function contractFinding(documents, target) {
+    const chain = [];
+    const marks = [];
+    for (const document of documents) {
+        if (typeof document.releaseId !== 'string' || !accepted(document))
+            continue;
+        chain.push(document.releaseId);
+        const migrations = contractOf(document);
+        if (migrations.length > 0)
+            marks.push({ index: chain.length - 1, migrations });
+    }
+    if (marks.length === 0)
+        return { blocked: false, migrations: [], reason: '' };
+    const at = chain.lastIndexOf(target);
+    const unsafe = marks.filter((mark) => at === -1 || at < mark.index - 1);
+    if (unsafe.length === 0)
+        return { blocked: false, migrations: [], reason: '' };
+    const migrations = unsafe.flatMap((mark) => mark.migrations);
+    const where = at === -1 ? `the journal has no record of release ${target} being accepted, and` : `release ${target} was accepted before the release that ran them, and`;
+    return { blocked: true, migrations, reason: `${where} contract migration(s) ${migrations.join(', ')} ran since: the schema no longer fits that release` };
+}
+/** Refuses `STACK_ROLLBACK_CONTRACT` when the finding blocks and the owner did not acknowledge the data effect; returns the notice line when it did. */
+export function enforceContractGuard(finding, acknowledged) {
+    if (!finding.blocked)
+        return [];
+    if (!acknowledged)
+        throw refusal('STACK_ROLLBACK_CONTRACT', `${finding.reason}. A rollback restores services, never data: restore the backup first, or pass --data-acknowledged to roll back anyway; nothing was changed`);
+    return [`--data-acknowledged: rolling back past ${finding.migrations.join(', ')}; the schema may not fit this release`];
+}

package/stack/ssh-gate.d.mts

@@ -0,0 +1,35 @@
+/** What an argument is: each kind is a closed alphabet, checked by the client (TypeScript) and by the gate (POSIX sh) alike. */
+export type ArgKind = 'base' | 'release' | 'pointer' | 'token' | 'trigger' | 'attempt' | 'seconds';
+/** One named operation: its arguments by kind, whether it reads stdin, and the sh body that runs with the arguments as $1.... */
+export interface GateOp {
+    readonly name: string;
+    readonly args: readonly ArgKind[];
+    readonly stdin: boolean;
+    readonly body: string;
+}
+/** The closed alphabet of each argument kind. */
+export declare const ARG_TESTS: Readonly<Record<ArgKind, (value: string) => boolean>>;
+/**
+ * The named operations of the release store. `lock-acquire`: `mkdir` is the atomic claim, the owner file (token, trigger, epoch) is replaced by
+ * rename, a lock unrefreshed for $4 seconds is moved aside (one rename wins) and claimed anew; prints `acquired` or `busy <trigger> <age>`.
+ */
+export declare const GATE_OPS: readonly GateOp[];
+/** The operation called `name`; an unknown name is a defect of the caller. */
+export declare function gateOp(name: string): GateOp;
+/** The command the CI transport sends: `starci-op <name> <argument>...` (every argument is plain characters, so nothing needs quoting). */
+export declare function gatedCommand(name: string, args: readonly string[]): string;
+/** The same operation as one command for a key without the gate: the body under `sh -c` with the arguments as positional parameters. */
+export declare function inlineCommand(name: string, args: readonly string[]): string;
+/** The POSIX sh text of `starci-ssh-gate`, to install executable at /usr/local/bin/starci-ssh-gate on the manager. */
+export declare function gateScript(): string;
+/** True when the CI transport was set up for a key that has the gate (`connect` exports STARCI_SSH_GATE=1 for a sealed `vps-ci` member that says `VPS_GATE: "1"`). */
+export declare const gateIsOn: (env: NodeJS.ProcessEnv | undefined) => boolean;
+/** Where the gate is installed on the manager, and the forced-command word of the authorized_keys line. */
+export declare const GATE_PATH = "/usr/local/bin/starci-ssh-gate";
+/** The options of the CI key's line: `restrict` already denies everything optional; the explicit denials keep the line readable and survive a reader who forgets what `restrict` covers. */
+export declare const AUTHORIZED_OPTIONS: readonly string[];
+/**
+ * The authorized_keys line of the CI key from its PUBLIC key text. Only a one-line public key is accepted (a private key, a line that already carries options
+ * or a second line is refused); the key keeps the comment it was generated with, which names it for revocation.
+ */
+export declare function authorizedKeysLine(publicKey: string): string;

package/stack/ssh-gate.mjs

@@ -0,0 +1,145 @@
+// ssh-gate.mjs - the forced command of the CI SSH key on the manager (`starci-ssh-gate`) and the named operations it admits.
+// The CI key reaches the manager's Docker socket, which is root on that host; its line in authorized_keys is therefore
+//   restrict,command="starci-ssh-gate" ssh-ed25519 AAAA... <comment>
+// and the gate admits exactly two kinds of request:
+//   `docker system dial-stdio`                   the transport of DOCKER_HOST=ssh://<alias> (the docker CLI starts it itself)
+//   `starci-op <name> <argument>...`             one of the named operations below, each argument validated by its kind
+// Everything else - a shell, an unknown name, a wrong argument count, an argument outside its closed alphabet - is refused with exit 126 and no echo of
+// the request. The operations are the release store's remote protocol (release-store.mts): the same script bodies run for the owner's key (through
+// `sh -c`, without the gate) and for the CI key (through the gate), so the gate admits no script the store does not itself run.
+// A body reads its arguments as $1... ($0 is `starci-op`) and its stdin; it holds no free text.
+import { refusal } from './errors.mjs';
+import { shellQuote } from './remote.mjs';
+const RELEASE_ID = /^[0-9a-f]{16}$/u;
+const TOKEN = /^[0-9a-f]{32}$/u;
+const ATTEMPT = /^[0-9]{8}T[0-9]{6}Z-[0-9a-f]{8}$/u;
+const BASE = /^\/[A-Za-z0-9._/-]+$/u;
+/** The closed alphabet of each argument kind. */
+export const ARG_TESTS = Object.freeze({
+    base: (value) => BASE.test(value) && !value.includes('..'),
+    release: (value) => RELEASE_ID.test(value),
+    pointer: (value) => value === 'current' || value === 'previous',
+    token: (value) => TOKEN.test(value),
+    trigger: (value) => value === 'ci' || value === 'dispatch' || value === 'urgent',
+    attempt: (value) => ATTEMPT.test(value),
+    seconds: (value) => /^[0-9]{1,6}$/u.test(value),
+});
+const OWNER_READ = 'if [ -r "$l/owner" ]; then read -r held_token held_trigger held_stamp < "$l/owner"; else held_token=none; held_trigger=unknown; held_stamp=$(stat -c %Y "$l" 2>/dev/null) || held_stamp=0; fi; case "$held_stamp" in \'\'|*[!0-9]*) held_stamp=0;; esac';
+/** Prints the release the pointer `$2` under `$1` names, or an empty line for an absent link; a failing readlink fails the script. */
+const POINTER = 'if [ -L "$1/$2" ]; then basename "$(readlink "$1/$2")"; else printf \'\\n\'; fi';
+/**
+ * The named operations of the release store. `lock-acquire`: `mkdir` is the atomic claim, the owner file (token, trigger, epoch) is replaced by
+ * rename, a lock unrefreshed for $4 seconds is moved aside (one rename wins) and claimed anew; prints `acquired` or `busy <trigger> <age>`.
+ */
+export const GATE_OPS = Object.freeze([
+    { name: 'pointer', args: ['base', 'pointer'], stdin: false, body: POINTER },
+    { name: 'list', args: ['base'], stdin: false, body: `for n in current previous; do if [ -L "$1/$n" ]; then basename "$(readlink "$1/$n")"; else printf '\\n'; fi; done; if [ -d "$1/releases" ]; then ls -1t "$1/releases"; fi` },
+    { name: 'read', args: ['base', 'release'], stdin: false, body: `set -e; s="$1/releases/$2"; for f in stack.yaml release.json; do test -r "$s/$f"; base64 < "$s/$f" | tr -d '\\n'; printf '\\n'; done` },
+    { name: 'store', args: ['base', 'release'], stdin: true, body: 'set -e; d="$1/releases/$2"; if [ -d "$d" ]; then chmod -R u+w "$d"; else mkdir -p "$d"; fi; IFS= read -r stack; IFS= read -r release; printf \'%s\' "$stack" | base64 -d > "$d/stack.yaml"; printf \'%s\' "$release" | base64 -d > "$d/release.json"; chmod 440 "$d/stack.yaml" "$d/release.json"; chmod 550 "$d"' },
+    { name: 'accept', args: ['base', 'release'], stdin: false, body: 'set -e; cd "$1"; id="$2"; test -d "releases/$id"; if [ -L current ] && [ "$(basename "$(readlink current)")" != "$id" ]; then ln -sfn "$(readlink current)" previous; fi; ln -sfn "releases/$id" current.new; mv -Tf current.new current' },
+    {
+        name: 'lock-acquire', args: ['base', 'token', 'trigger', 'seconds'], stdin: false,
+        body: [
+            'b="$1"; tok="$2"; trg="$3"; ttl="$4"; l="$b/deploy.lock"; now=$(date +%s); mkdir -p "$b" || exit 1',
+            'claim() { printf \'%s %s %s\\n\' "$tok" "$trg" "$now" > "$l/owner.new" && mv -f "$l/owner.new" "$l/owner" && echo acquired && exit 0; exit 1; }',
+            'if mkdir "$l" 2>/dev/null; then claim; fi',
+            OWNER_READ,
+            'age=$((now - held_stamp)); if [ "$age" -gt "$ttl" ]; then if mv "$l" "$l.stale.$tok" 2>/dev/null; then rm -rf "$l.stale.$tok"; if mkdir "$l" 2>/dev/null; then claim; fi; fi; fi',
+            'case "$held_trigger" in ci|dispatch|urgent) ;; *) held_trigger=unknown;; esac; echo "busy $held_trigger $age"',
+        ].join('; '),
+    },
+    { name: 'lock-refresh', args: ['base', 'token'], stdin: false, body: 'l="$1/deploy.lock"; now=$(date +%s); if [ -r "$l/owner" ]; then read -r t g s < "$l/owner"; if [ "$t" = "$2" ]; then printf \'%s %s %s\\n\' "$t" "$g" "$now" > "$l/owner.new" && mv -f "$l/owner.new" "$l/owner" && echo held; else echo lost; fi; else echo lost; fi' },
+    { name: 'lock-release', args: ['base', 'token'], stdin: false, body: 'l="$1/deploy.lock"; if [ -r "$l/owner" ]; then read -r t g s < "$l/owner"; if [ "$t" = "$2" ]; then rm -rf "$l" && echo released; else echo lost; fi; else echo lost; fi' },
+    { name: 'journal-write', args: ['base', 'attempt'], stdin: true, body: 'set -e; d="$1/deploys"; mkdir -p "$d"; IFS= read -r doc; printf \'%s\' "$doc" | base64 -d > "$d/.$2.tmp"; mv -f "$d/.$2.tmp" "$d/$2.json"' },
+    { name: 'journal-index', args: ['base'], stdin: true, body: 'set -e; mkdir -p "$1/deploys"; IFS= read -r line; printf \'%s\\n\' "$(printf \'%s\' "$line" | base64 -d)" >> "$1/deploys.jsonl"' },
+    // The newest 500 attempt documents, one base64 line each, oldest first (attempt ids sort by their UTC time).
+    { name: 'journal-read', args: ['base'], stdin: false, body: 'd="$1/deploys"; [ -d "$d" ] || exit 0; names=$(ls -1 "$d") || exit 1; printf \'%s\\n\' "$names" | tail -n 500 | while IFS= read -r f; do case "$f" in ' + `${'[0-9]'.repeat(8)}T${'[0-9]'.repeat(6)}Z-${'[0-9a-f]'.repeat(8)}.json` + ') base64 < "$d/$f" | tr -d \'\\n\'; printf \'\\n\';; esac; done' },
+]);
+const BY_NAME = new Map(GATE_OPS.map((op) => [op.name, op]));
+/** The operation called `name`; an unknown name is a defect of the caller. */
+export function gateOp(name) {
+    const op = BY_NAME.get(name);
+    if (!op)
+        throw refusal('STACK_GATE_OP', `${name} is not an operation of the ssh gate`);
+    return op;
+}
+function checkedArguments(op, args) {
+    if (args.length !== op.args.length)
+        throw refusal('STACK_GATE_ARGUMENT', `${op.name} takes ${op.args.length} argument(s)`);
+    op.args.forEach((kind, index) => {
+        if (!ARG_TESTS[kind](args[index]))
+            throw refusal('STACK_GATE_ARGUMENT', `argument ${index + 1} of ${op.name} is not a plain ${kind}`);
+    });
+    return args;
+}
+/** The command the CI transport sends: `starci-op <name> <argument>...` (every argument is plain characters, so nothing needs quoting). */
+export function gatedCommand(name, args) {
+    const op = gateOp(name);
+    return ['starci-op', op.name, ...checkedArguments(op, args)].join(' ');
+}
+/** The same operation as one command for a key without the gate: the body under `sh -c` with the arguments as positional parameters. */
+export function inlineCommand(name, args) {
+    const op = gateOp(name);
+    return `sh -c ${shellQuote(op.body)} starci-op ${checkedArguments(op, args).map(shellQuote).join(' ')}`;
+}
+const VALIDATOR = Object.freeze({
+    base: 'v_base', release: 'v_release', pointer: 'v_pointer', token: 'v_token', trigger: 'v_trigger', attempt: 'v_attempt', seconds: 'v_seconds',
+});
+/** The sh variable that holds the body of an operation. */
+const bodyVariable = (name) => `OP_${name.replaceAll('-', '_')}`;
+/** The POSIX sh text of `starci-ssh-gate`, to install executable at /usr/local/bin/starci-ssh-gate on the manager. */
+export function gateScript() {
+    const digits = (count, set = '[0-9]') => set.repeat(count);
+    const bodies = GATE_OPS.map((op) => `${bodyVariable(op.name)}=${shellQuote(op.body)}`);
+    const cases = GATE_OPS.map((op) => {
+        const checks = op.args.map((kind, index) => `${VALIDATOR[kind]} "$${index + 1}"`).join(' && ');
+        return `  ${op.name}) [ $# -eq ${op.args.length} ]${checks ? ` && ${checks}` : ''} || refuse; exec sh -c "$${bodyVariable(op.name)}" starci-op "$@";;`;
+    });
+    return [
+        '#!/bin/sh',
+        '# starci-ssh-gate: the forced command of the CI key (generated by `starci app stack ci-key --print-gate`; do not edit, regenerate).',
+        '# Admits `docker system dial-stdio` and the named operations of the release store, nothing else. A refusal says nothing about the request.',
+        'PATH="$PATH:/usr/local/bin:/usr/bin:/bin"',
+        "refuse() { echo 'starci-ssh-gate: command refused' >&2; exit 126; }",
+        'v_base() { case "$1" in /*) ;; *) return 1;; esac; case "$1" in *[!A-Za-z0-9._/-]*|*..*) return 1;; esac; }',
+        'v_hex() { case "$2" in \'\'|*[!0-9a-f]*) return 1;; esac; [ "${#2}" -eq "$1" ]; }',
+        'v_release() { v_hex 16 "$1"; }',
+        'v_token() { v_hex 32 "$1"; }',
+        'v_pointer() { case "$1" in current|previous) ;; *) return 1;; esac; }',
+        'v_trigger() { case "$1" in ci|dispatch|urgent) ;; *) return 1;; esac; }',
+        `v_attempt() { case "$1" in ${digits(8)}T${digits(6)}Z-${digits(8, '[0-9a-f]')}) ;; *) return 1;; esac; v_hex 8 "\${1#*Z-}"; }`,
+        'v_seconds() { case "$1" in \'\'|*[!0-9]*) return 1;; esac; [ "${#1}" -le 6 ]; }',
+        ...bodies,
+        'cmd=${SSH_ORIGINAL_COMMAND-}',
+        '[ -n "$cmd" ] || refuse',
+        'if [ "$cmd" = \'docker system dial-stdio\' ]; then exec docker system dial-stdio; fi',
+        "IFS=' '; set -f",
+        'set -- $cmd',
+        '[ $# -ge 2 ] && [ "$1" = starci-op ] || refuse',
+        'op=$2; shift 2',
+        'case "$op" in',
+        ...cases,
+        '  *) refuse;;',
+        'esac',
+        '',
+    ].join('\n');
+}
+/** True when the CI transport was set up for a key that has the gate (`connect` exports STARCI_SSH_GATE=1 for a sealed `vps-ci` member that says `VPS_GATE: "1"`). */
+export const gateIsOn = (env) => env?.STARCI_SSH_GATE === '1';
+/** Where the gate is installed on the manager, and the forced-command word of the authorized_keys line. */
+export const GATE_PATH = '/usr/local/bin/starci-ssh-gate';
+/** The options of the CI key's line: `restrict` already denies everything optional; the explicit denials keep the line readable and survive a reader who forgets what `restrict` covers. */
+export const AUTHORIZED_OPTIONS = Object.freeze(['restrict', 'command="starci-ssh-gate"', 'no-pty', 'no-port-forwarding', 'no-agent-forwarding', 'no-X11-forwarding', 'no-user-rc']);
+const KEY_LINE = /^(ssh-ed25519|ecdsa-sha2-nistp(?:256|384|521)|ssh-rsa|sk-ssh-ed25519@openssh\.com) [A-Za-z0-9+/]+={0,3}(?: [A-Za-z0-9._@:+=-]+)?$/u;
+/**
+ * The authorized_keys line of the CI key from its PUBLIC key text. Only a one-line public key is accepted (a private key, a line that already carries options
+ * or a second line is refused); the key keeps the comment it was generated with, which names it for revocation.
+ */
+export function authorizedKeysLine(publicKey) {
+    const text = publicKey.trim();
+    if (text.includes('PRIVATE KEY'))
+        throw refusal('STACK_CI_KEY_PRIVATE', 'that is a private key: give the public half (.pub) of the CI key');
+    if (!KEY_LINE.test(text))
+        throw refusal('STACK_CI_KEY_PUBLIC', 'the CI public key must be one line: <type> <base64> [comment], with no options in front');
+    return `${AUTHORIZED_OPTIONS.join(',')} ${text}`;
+}

package/stack/status.d.mts

@@ -39,7 +39,9 @@ export declare function compareWithRelease(expected: ExpectedRelease, live: read
 /** The collaborators of a status (the specs inject stubs). */
 export interface StatusDeps {
     ssh: (ctx: StackContext, config: DeployConfig, options: SshOptions) => Runner | Promise<Runner>;
-    releaseStore: (config: DeployConfig, ssh: Runner) => ReleaseStore;
+    releaseStore: (config: DeployConfig, ssh: Runner, options?: {
+        gated?: boolean | undefined;
+    }) => ReleaseStore;
     observedServices: (ctx: StackContext, config: DeployConfig) => ObservedService[];
 }
 /**

package/stack/status.mjs

@@ -11,6 +11,7 @@ import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { canonical } from './converge.mjs';
 import { lines as splitLines, toolOutput } from './context.mjs';
 import { createReleaseStore } from './release-store.mjs';
+import { gateIsOn } from './ssh-gate.mjs';
 const DIGEST = /@(sha256:[0-9a-f]{64})$/u;
 const IMAGE_FIELD = /^[A-Za-z0-9][A-Za-z0-9./_:@-]*$/u;
 /** The `sha256:...` digest an image reference pins, or null. */
@@ -89,7 +90,7 @@ export async function statusStack(ctx, config, options = {}, deps = {}) {
     const d = { ...DEFAULT_DEPS, ...deps };
     const run = await d.ssh(ctx, config, { sshCmd: options.sshCmd ?? null });
     try {
-        const store = d.releaseStore(config, run);
+        const store = d.releaseStore(config, run, { gated: gateIsOn(ctx.env) });
         const current = await store.current();
         const live = d.observedServices(ctx, config);
         if (!current)