@starci/hfs 4.16.0 → 4.16.2

package/CHANGELOG.md

@@ -1,10 +1,23 @@
 # Changelog
 
+## 4.16.2 - 2026-10-31
+
+- Fixed: R248 `ENV_DUPLICATE` judges app env only. The operator's SSH member (`deploy.remote.sealed`) and the CI member `vps-ci` are separate identities by design (ruling ci-transport-one-home) and never reach an app container, so the SSH group keys (`SSH_GROUP`, now exported from `secret-standard`) held by exactly those two members of one environment are no duplicate; an app key in two members, or an SSH group key in any third member, stays red.
+- Changed: the CI transport lives in the sealed `vps-ci` alone and GitHub keeps only `SOPS_AGE_KEY`: `stack-key-restore.yml` (both editions) opens the sealed member with the same `stack connect` step as the deploy instead of `VPS_*` environment secrets, and the starters no longer declare `VPS_SSH_KEY`, `VPS_KNOWN_HOSTS`, `VPS_HOST` and `VPS_USER` under `ci:`.
+- Added: the ssh gate operation `identity-restore <recipient>` (stdin: the identity; writes only the fixed server identity path, once, for the matching recipient), so the restore workflow is admitted when the CI key is forced through `starci-ssh-gate`; `CI_MEMBER` moves to `sealed-member`.
+- Fixed: R259 `DB_MIGRATION_DESTRUCTIVE` leaves out `SET NOT NULL` and a type change on a column (or table) the same migration created earlier, which touches no existing data, and an entity references a table only by the name its `@Entity`/`@Table` decorator spells: a column property of the same word (`queue`) is no reference to a dropped table `queue`; an entity that spells no name keeps the identifier match.
+- Fixed: `HFS_SCHEDULE_UNDECLARED` judges unparsable SQL only when it calls `cron.schedule`, `cron.unschedule`, `cron.schedule_in_database` or `cron.alter_job`; a statement of another dialect (MySQL session setup) schedules nothing.
+- Changed: the bundled canon pins name hfs 4.16.2, @starci/grammar 0.19.1, eslint-canon-be 3.11.3, eslint-canon-fe 9.8.2 and eslint-grammar-core and eslint-grammar-offset-pop 0.19.1.
+
+## 4.16.1 - 2026-10-31
+
+- Changed: the bundled canon pins name @starci/grammar, eslint-grammar-core and eslint-grammar-offset-pop 0.19.0, eslint-canon-be 3.11.2, eslint-canon-fe 9.8.1, stylelint-canon 2.4.0 and hfs 4.16.1 (RELEASE_VERSION_NOT_BUMPED: 4.16.0 is on npm).
+
 ## 4.16.0 - 2026-10-31
 
 - Added: `starci app codemod spacing-roles [--execute] [--json] [--format json|markdown] [--out <file>]`: a dry run by default; plain flex column and row `div`s whose only spacing is one gap become `Stack` and `Cluster` bound from the file's Grammar import (gap-1 identity, gap-2 inline, gap-3 row, gap-4 section, gap-6 and gap-8 region, gap-8 marked for review); every other spacing utility is reported with its suggested role, and the report counts the utilities by family.
 - Changed: `starci app lint` reports an ESLint warning (a rule of the canon's counting cohort) with severity `warning`, counts them per rule (`counts.warning`, `counting`) and keeps them out of the verdict and the error threshold.
-- Changed: the canon pins name @starci/grammar, eslint-grammar-core and eslint-grammar-offset-pop 0.18.0, eslint-canon-fe 9.8.0, stylelint-canon 2.4.0 and hfs 4.16.0; R350 joins the bundled rule catalog.
+- Changed: the canon pins name @starci/grammar, eslint-grammar-core and eslint-grammar-offset-pop 0.19.0, eslint-canon-fe 9.8.0, stylelint-canon 2.4.0 and hfs 4.16.0; R350 joins the bundled rule catalog.
 
 ## 4.15.0 - 2026-10-31
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.16.0",
+  "version": "4.16.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.18.0
+    version: 0.19.1
     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.11.1
+    version: 3.11.3
     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.8.0
+    version: 9.8.2
     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.18.0
+    version: 0.19.1
     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.18.0
+    version: 0.19.1
     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.16.0
+    version: 4.16.2
     group: starci
     install: registry
     side: both

package/runtime/modules/kernel/failure-codes.yaml

@@ -1989,6 +1989,7 @@ ENV_DUPLICATE:
   causes_vi:
     - "Vi phạm luật R248: một khoá chỉ sống trong một member; hai bản sao lệch giá trị là lỗi vận hành chờ xảy ra."
     - "Khoá được di chuyển sang member mới nhưng quên gỡ khỏi member cũ."
+    - "Chỉ các khoá nhóm SSH (`VPS_HOST`, `VPS_USER`, `privateKey`, `knownHosts`) được phép nằm ở cả member `deploy.remote.sealed` lẫn `vps-ci` của cùng môi trường; mọi khoá app khác, hoặc khoá SSH ở member thứ ba, vẫn bị báo."
   nextStep_vi: "Giữ khoá ở đúng một member và gỡ nó khỏi member còn lại (`starci app secret set` rồi chỉnh lại member thừa)."
   owner: op-retry
   kind: check-finding

package/runtime/scripts/hfs/rules/database-migrations.mjs

@@ -369,7 +369,7 @@ function columnAlterObject(tokens, index, table, line) {
         && sqlWord(tokens[at + 2 + Number(sqlWord(tokens[at + 1], 'column'))], 'set') && sqlWord(tokens[at + 3 + Number(sqlWord(tokens[at + 1], 'column'))], 'default'));
     if (!type && !(notNull && !defaultSet))
         return null;
-    return { name: `${table.name}.${column.name}`, leaf: column.leaf, table: table.leaf, kind: 'column', line };
+    return { name: `${table.name}.${column.name}`, leaf: column.leaf, table: table.leaf, kind: 'column', alters: true, line };
 }
 function alteredColumn(table, column, line) {
     return { name: `${table.name}.${column.name}`, leaf: column.leaf, table: table.leaf, kind: 'column', line };
@@ -467,11 +467,32 @@ function globalConstraintNames(statement) {
     }
     return names;
 }
+const ENTITY_DECORATORS = new Set(['Entity', 'Table', 'ViewEntity']);
+/** Adds the table names a class decorator `@Entity(...)`, `@Table(...)` or `@ViewEntity(...)` spells to `tables`; true when such a decorator spells none. */
+function noteEntityTables(ts, decorator, tables) {
+    const call = decorator.expression;
+    const callee = ts.isCallExpression(call) ? call.expression : call;
+    if (!ts.isIdentifier(callee) || !ENTITY_DECORATORS.has(callee.text))
+        return false;
+    const before = tables.size;
+    const collect = (node) => {
+        if (ts.isStringLiteralLike(node))
+            for (const part of [node.text, node.text.split('.').at(-1)])
+                tables.add(part);
+        ts.forEachChild(node, collect);
+    };
+    if (ts.isCallExpression(call))
+        for (const argument of call.arguments)
+            collect(argument);
+    return tables.size === before;
+}
 function sourceNameScopes(ts, text, file) {
     const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
     const checker = lexicalChecker(ts, source);
     const scopes = [];
     const entityNames = /\.entity\.[cm]?tsx?$/.test(file) ? new Set() : null;
+    const entityTables = new Set();
+    let implicitTable = false;
     const addSql = (sql) => {
         for (const statement of databaseSqlStatements(databaseSqlTokens(sql))) {
             const names = new Set(statement.filter((token) => sqlName(token) !== null).map((token) => token.v));
@@ -490,10 +511,15 @@ function sourceNameScopes(ts, text, file) {
             addSql(sql);
         if (entityNames && ts.isIdentifier(node))
             entityNames.add(node.text);
+        if (entityNames && ts.isDecorator(node))
+            implicitTable = noteEntityTables(ts, node, entityTables) || implicitTable;
         ts.forEachChild(node, visit);
     };
     visit(source);
-    return entityNames ? [{ names: entityNames, constraints: entityNames, globalConstraints: new Set() }] : scopes;
+    // An entity names its table by the string of its @Entity/@Table decorator; a column property of the same word (`queue`) is no table reference.
+    // An entity that names none (or has no such decorator) keeps the conservative identifier match.
+    const tables = entityTables.size > 0 && !implicitTable ? entityTables : undefined;
+    return entityNames ? [{ names: entityNames, tables, constraints: entityNames, globalConstraints: new Set() }] : scopes;
 }
 /**
  * Whether a be/src source references a destroyed object. A column (`<schema>.<table>.<column>`) is referenced only by a source that
@@ -501,9 +527,10 @@ function sourceNameScopes(ts, text, file) {
  * SQL constraints require explicit constraint names, while entities retain their table/decorator association.
  * Other object kinds match their leaf name conservatively.
  */
-const referencesObject = (scopes, object) => scopes.some(({ names, constraints, globalConstraints }) => (object.kind === 'constraint' && globalConstraints.has(object.leaf))
-    || ((object.kind === 'constraint' ? constraints : names).has(object.leaf)
-        && (!['column', 'constraint'].includes(object.kind) || !object.table || names.has(object.table))));
+const referencesObject = (scopes, object) => scopes.some(({ names, tables, constraints, globalConstraints }) => (object.kind === 'constraint' && globalConstraints.has(object.leaf))
+    || (object.kind === 'table' && tables !== undefined ? tables.has(object.leaf)
+        : (object.kind === 'constraint' ? constraints : names).has(object.leaf)
+            && (!['column', 'constraint'].includes(object.kind) || !object.table || (tables ?? names).has(object.table))));
 function destructiveObjectFinding(file, object, contract, references) {
     const reference = references.find(({ scopes }) => referencesObject(scopes, object));
     if (contract && !reference)
@@ -512,10 +539,50 @@ function destructiveObjectFinding(file, object, contract, references) {
         : 'use a *_contract_* migration after the application stops using this object';
     return found(DB_MIGRATION_DESTRUCTIVE, file, `${file}:${object.line} destructively changes ${object.name}; ${reason}`, { line: object.line, object: object.name, ...(reference ? { reference: reference.file } : {}) });
 }
+/** The `<table leaf>.<column leaf>` keys an ALTER TABLE ... ADD COLUMN statement adds, and `<table leaf>.*` for a CREATE TABLE. */
+function addedColumns(statement) {
+    const added = [];
+    for (let index = 0; index < statement.length - 1; index += 1) {
+        if (sqlWord(statement[index], 'create')) {
+            const at = skipWords(statement, index + 1, ['temp', 'temporary', 'unlogged']);
+            const created = sqlWord(statement[at], 'table') ? nameAt(statement, skipWords(statement, at + 1, ['if', 'not', 'exists'])) : null;
+            if (created)
+                added.push(`${created.leaf}.*`);
+        }
+        if (!(sqlWord(statement[index], 'alter') && sqlWord(statement[index + 1], 'table')))
+            continue;
+        const table = nameAt(statement, skipWords(statement, index + 2, ['if', 'exists', 'only']));
+        if (!table)
+            continue;
+        const body = statement.slice(table.next);
+        body.forEach((token, at) => {
+            if (!sqlWord(token, 'add'))
+                return;
+            const start = skipWords(body, at + 1, ['column', 'if', 'not', 'exists']);
+            if (['constraint', 'primary', 'foreign', 'unique', 'check', 'exclude'].some((word) => sqlWord(body[start], word)))
+                return;
+            const column = nameAt(body, start);
+            if (column)
+                added.push(`${table.leaf}.${column.leaf}`);
+        });
+    }
+    return added;
+}
+/** An ALTER of a column (SET NOT NULL, TYPE) the same migration added earlier changes no existing data: it is not destructive. */
+const alterOfNewColumn = (object, added) => object.alters === true && (added.has(`${object.table}.${object.leaf}`) || added.has(`${object.table}.*`));
+/** The destructive objects of one migration's SQL, in order, leaving out the alters of columns and tables the migration created itself. */
+function migrationDestructiveObjects(text) {
+    const added = new Set();
+    return databaseSqlStatements(databaseExecutableTokens(text)).flatMap((statement) => {
+        for (const key of addedColumns(statement))
+            added.add(key);
+        return destructiveObjects(statement).filter((object) => !alterOfNewColumn(object, added));
+    });
+}
 function destructiveFileFindings(file, text, references) {
     const contract = /_contract_[a-z0-9]+(?:[-_][a-z0-9]+)*\.sql$/.test(file);
     const seen = new Set();
-    const objects = databaseSqlStatements(databaseExecutableTokens(text)).flatMap(destructiveObjects);
+    const objects = migrationDestructiveObjects(text);
     return objects.flatMap((object) => {
         const key = `${object.line}:${object.kind}:${object.name}`;
         if (seen.has(key))
@@ -564,7 +631,7 @@ export async function contractReleaseFindings({ repoRoot, migrations, git }) {
         const text = readText(repoRoot, file);
         if (text === null)
             return [];
-        return databaseSqlStatements(databaseExecutableTokens(text)).flatMap(destructiveObjects).flatMap((object) => {
+        return migrationDestructiveObjects(text).flatMap((object) => {
             const reference = references.find(({ scopes }) => referencesObject(scopes, object));
             return reference ? [found(DB_MIGRATION_DESTRUCTIVE, file, `${file}:${object.line} destroys ${object.name}, which the previous release ${release} still references in ${reference.file}; the contract migration runs right after the accept while that release is the rollback target: ship the code change in one release and this contract migration in the next`, { line: object.line, object: object.name, release, reference: reference.file })] : [];
         });

package/runtime/scripts/hfs/rules/env-parity.mjs

@@ -13,7 +13,8 @@
 //       `.starcistacks/<env>/runtime/env/KEYS.md`, and the `environment:`/`env:` entries, `runtimeSecrets`, `secrets`
 //       and `vars[].name` of every `.starcistacks` yaml. A `<KEY>_FILE` name declares `<KEY>`.
 // Findings: ENV_REQUIRED_UNSET a required read sits in neither S nor D; ENV_SEALED_UNREAD a sealed key sits in
-// neither R nor a declared consumer; ENV_DUPLICATE one key in two members of one environment; ENV_PUBLIC_SEALED a NEXT_PUBLIC_* key in
+// neither R nor a declared consumer; ENV_DUPLICATE one app key in two members of one environment (the transport members, the operator's `deploy.remote.sealed` member and
+// `vps-ci`, never reach an app container and may both hold the SSH_GROUP keys, nothing else); ENV_PUBLIC_SEALED a NEXT_PUBLIC_* key in
 // custody; ENV_EXAMPLE_DRIFT a `*.env.example` key nothing reads. The rule judges the app root (`isRoot`): the whole
 // tree `all` is its input, both editions.
 import path from 'node:path';
@@ -21,6 +22,8 @@ import { fileURLToPath } from 'node:url';
 import { loadTypescript } from '../../lib/package-at.mjs';
 import { parseYaml } from '../../../engine/yaml.mjs';
 import { envelopeOf } from '../secret-document.mjs';
+import { SSH_GROUP, sshTransportMembers } from '../secret-standard.mjs';
+import { memberOfName } from '../../lib/sealed-member.mjs';
 import { found, readText } from './read.mjs';
 export const ENV_REQUIRED_UNSET = 'ENV_REQUIRED_UNSET';
 export const ENV_SEALED_UNREAD = 'ENV_SEALED_UNREAD';
@@ -349,25 +352,39 @@ function sealedMemberFinding(key, member, reads, declared) {
     }
     return null;
 }
-function addSealedFindings(sealed, reads, declared, findings) {
+/** The transport members per environment: the `deploy.remote.sealed` member(s) of application-stacks.yaml and `vps-ci`. */
+function transportMembers(repoRoot) {
+    const text = readText(repoRoot, '.starcistacks/application-stacks.yaml');
+    let stacks = {};
+    try {
+        stacks = text === null ? {} : parseYaml(text) ?? {};
+    }
+    catch { /* a malformed stacks yaml is the shape rule's finding, not this one's */ }
+    return (environment) => sshTransportMembers(stacks.environments?.[environment]);
+}
+function addSealedFindings(sealed, reads, declared, transport, findings) {
     for (const [key, members] of sealed) {
         for (const member of members) {
             const finding = sealedMemberFinding(key, member, reads, declared);
             if (finding !== null)
                 findings.push(finding);
         }
-        addDuplicateFindings(key, members, findings);
+        addDuplicateFindings(key, members, transport, findings);
     }
 }
-function addDuplicateFindings(key, members, findings) {
+/** One key in two members of one environment, except an SSH_GROUP key held by the two transport members (a classification: those never reach an app). */
+function addDuplicateFindings(key, members, transport, findings) {
     const firstByEnvironment = new Map();
     for (const member of members) {
         const environment = member.split('/')[1];
+        const exempt = (file) => SSH_GROUP.includes(key) && transport(environment).has(memberOfName(file.split('/').pop()));
         const first = firstByEnvironment.get(environment);
         if (first === undefined) {
             firstByEnvironment.set(environment, member);
             continue;
         }
+        if (exempt(first) && exempt(member))
+            continue;
         findings.push(found(ENV_DUPLICATE, member, `${key} is sealed in ${first} and again in ${member}; one key lives in one member per environment`));
     }
 }
@@ -394,7 +411,7 @@ export function envParityFindings({ repoRoot, all = [], isRoot }) {
     const declared = declaredKeys(repoRoot, all);
     const findings = [];
     addRequiredFindings(reads, sealed, declared, findings);
-    addSealedFindings(sealed, reads, declared, findings);
+    addSealedFindings(sealed, reads, declared, transportMembers(repoRoot), findings);
     addExampleFindings(repoRoot, all, reads, findings);
     return findings;
 }

package/runtime/scripts/hfs/rules/stacks-release.mjs

@@ -245,6 +245,14 @@ function executableExpression(expression) {
     }
     return `SELECT ${query}`;
 }
+const PG_CRON_CALL = /\bcron\s*\.\s*(?:schedule|unschedule|schedule_in_database|alter_job)\b/i;
+/**
+ * SQL Postgres cannot parse is judged only when it names a pg_cron call: a statement of another dialect (MySQL session setup, say) schedules nothing, so
+ * it is no unknown job, while unparsable text that does call cron.schedule stays an undeclared job nobody can read.
+ */
+function unparsedSchedule(text, file) {
+    return PG_CRON_CALL.test(text) ? [{ id: null, cadence: null, at: file }] : [];
+}
 function doSqlObservations(statement, file) {
     const body = statement.args?.find((arg) => arg.DefElem?.defname === 'as')?.DefElem?.arg?.String?.sval;
     if (!present(body))
@@ -254,7 +262,7 @@ function doSqlObservations(statement, file) {
         tree = pg.parsePlPgSQLSync("DO '" + body.replaceAll("'", "''") + "';");
     }
     catch {
-        return [{ id: null, cadence: null, at: file }];
+        return unparsedSchedule(body, file);
     }
     const observations = [];
     walkSql(tree, (value) => {
@@ -267,7 +275,7 @@ function doSqlObservations(statement, file) {
 function sqlObservations(text, file) {
     const tree = parseSql(text);
     if (!tree)
-        return [{ id: null, cadence: null, at: file }];
+        return unparsedSchedule(text, file);
     const observations = [];
     walkSql(tree, (value) => {
         if (value.DoStmt)
@@ -338,7 +346,7 @@ function templateObservations(node, file) {
     const named = spell(DYNAMIC);
     const tree = parseSql(named);
     if (!tree)
-        return [{ id: null, cadence: null, at: file }];
+        return unparsedSchedule(named, file);
     let dynamicCall = false;
     walkSql(tree, (value) => {
         if (value.FuncCall && (value.FuncCall.funcname ?? []).some((part) => part.String?.sval === DYNAMIC))

package/runtime/scripts/hfs/secret-standard.d.mts

@@ -46,6 +46,13 @@ export interface MoveOptions {
 }
 /** The provider a key belongs to: its first word (`SEPAY_IPN_SECRET_KEY` is `sepay`, `OPENROUTER_API_KEY` is `openrouter`). */
 export declare const providerOf: (key: string) => string;
+/** The keys of the one sealed SSH member `deploy.remote.sealed` names (stack/remote.mjs): the deploy transport reads exactly these. */
+export declare const SSH_GROUP: readonly string[];
+/**
+ * The two transport members of an environment (ruling ci-transport-one-home): the operator's member(s) `deploy.remote.sealed` names and
+ * the CI member `vps-ci`, two identities by design, neither of which reaches an app container. Only the SSH_GROUP keys may appear in both.
+ */
+export declare function sshTransportMembers(spec: EnvironmentSpec | undefined): Set<string>;
 /**
  * Every deviation of the app at `repoRoot` (one environment, else each with a secrets folder): LEGACY_MEMBER, MIXED_PROVIDERS,
  * RECIPIENT_DRIFT, UNDECLARED_KEY (only where application-stacks.yaml declares the environment), UNTRACKED. Names only.

package/runtime/scripts/hfs/secret-standard.mjs

@@ -8,7 +8,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { parseYaml } from "../../engine/yaml.mjs";
 import { lsFiles } from "../api/git/ls-files.mjs";
-import { MEMBER_SUFFIX, isLegacyName, memberOfName } from "../lib/sealed-member.mjs";
+import { CI_MEMBER, MEMBER_SUFFIX, isLegacyName, memberOfName } from "../lib/sealed-member.mjs";
 import { configuredRecipients } from "./secret-init.mjs";
 import { envelopeOf, validateMap } from "./secret-document.mjs";
 import { deleteSealed, fileOf, sealedFiles, writeSecret } from "./secret-store.mjs";
@@ -27,7 +27,16 @@ function declaredKeys(spec, member, keys) {
     return entries.filter((entry) => entry?.key !== undefined && memberOfEntry(entry) === member).map((entry) => entry.key);
 }
 /** The keys of the one sealed SSH member `deploy.remote.sealed` names (stack/remote.mjs): the deploy transport reads exactly these. */
-const SSH_GROUP = Object.freeze(["VPS_HOST", "VPS_USER", "privateKey", "knownHosts"]);
+export const SSH_GROUP = Object.freeze(["VPS_HOST", "VPS_USER", "privateKey", "knownHosts"]);
+/**
+ * The two transport members of an environment (ruling ci-transport-one-home): the operator's member(s) `deploy.remote.sealed` names and
+ * the CI member `vps-ci`, two identities by design, neither of which reaches an app container. Only the SSH_GROUP keys may appear in both.
+ */
+export function sshTransportMembers(spec) {
+    const sealed = spec?.deploy?.remote?.sealed;
+    const operator = typeof sealed === "string" ? [sealed] : Object.values(sealed ?? {});
+    return new Set([...operator.filter((slug) => typeof slug === "string"), CI_MEMBER]);
+}
 /**
  * True when the stack groups `member` on purpose: every key of it is declared in the environment's `secrets:`, per key (`key` with
  * `member: <member>`) or in the `keys` list of an entry naming the member, or is a key of the sealed SSH member the deploy names.

package/runtime/scripts/lib/sealed-member.d.mts

@@ -1,6 +1,8 @@
 /** The suffix of a member, and of a legacy one. */
 export declare const MEMBER_SUFFIX = ".enc.yaml";
 export declare const LEGACY_SUFFIX = ".enc";
+/** The sealed member that holds the CI transport of an environment: its own identity with a forced command, never the operator's SSH member. */
+export declare const CI_MEMBER = "vps-ci";
 /** A sealed member's file name (either suffix), as a pattern for a name or the tail of a path. */
 export declare const SEALED_NAME: RegExp;
 /** True for the file name of a sealed member, current or legacy. */

package/runtime/scripts/lib/sealed-member.mjs

@@ -7,6 +7,8 @@ import path from 'node:path';
 /** The suffix of a member, and of a legacy one. */
 export const MEMBER_SUFFIX = '.enc.yaml';
 export const LEGACY_SUFFIX = '.enc';
+/** The sealed member that holds the CI transport of an environment: its own identity with a forced command, never the operator's SSH member. */
+export const CI_MEMBER = 'vps-ci';
 /** A sealed member's file name (either suffix), as a pattern for a name or the tail of a path. */
 export const SEALED_NAME = /\.enc(?:\.yaml)?$/u;
 /** True for the file name of a sealed member, current or legacy. */

package/stack/remote.d.mts

@@ -1,3 +1,4 @@
+import { CI_MEMBER } from '../runtime/scripts/lib/sealed-member.mjs';
 import type { DeployConfig } from './config.mjs';
 import type { StackContext } from './context.mjs';
 import type { RemoteArgv } from './ssh-session.mjs';
@@ -74,7 +75,7 @@ export declare const ownerSshRunner: (ctx: StackContext, config: DeployConfig, o
 /** Opens the runner (`deps.ssh` wins in specs), calls `body(run, notes)` and always cleans the session up. */
 export declare function withRunner<T>(ctx: StackContext, config: DeployConfig, options: SshOptions, deps: RunnerDeps, body: (run: Runner, notes: string[]) => T | Promise<T>): Promise<T>;
 /** The sealed member that holds the CI transport of an environment: VPS_SSH_KEY (the CI-only deploy key), VPS_KNOWN_HOSTS, VPS_HOST and VPS_USER. */
-export declare const CI_MEMBER = "vps-ci";
+export { CI_MEMBER };
 /** CI transport: pinned key, known_hosts, ssh config block and DOCKER_HOST=ssh://<alias> in $GITHUB_ENV. */
 export declare function connectCi(ctx: StackContext, config: DeployConfig, { execute }?: {
     execute?: boolean;

package/stack/remote.mjs

@@ -9,7 +9,7 @@
 // `bash -s` fail with `set: pipefail`). Key material lives in memory and in a private temp directory only; it is never in argv (only the key
 // FILE path is), in a line, in a result or in an error message.
 import fs from 'node:fs';
-import { isLegacyName, memberFile } from '../runtime/scripts/lib/sealed-member.mjs';
+import { CI_MEMBER, isLegacyName, memberFile } from '../runtime/scripts/lib/sealed-member.mjs';
 import os from 'node:os';
 import path from 'node:path';
 import { tool } from './context.mjs';
@@ -217,7 +217,7 @@ function ciHome(ctx) {
     return path.join(ctx.env.HOME, '.ssh');
 }
 /** The sealed member that holds the CI transport of an environment: VPS_SSH_KEY (the CI-only deploy key), VPS_KNOWN_HOSTS, VPS_HOST and VPS_USER. */
-export const CI_MEMBER = 'vps-ci';
+export { CI_MEMBER };
 /**
  * The CI transport values: the sealed member `vps-ci` of the environment (opened with the server identity the job holds) when it exists, else the
  * variables of the job (the transition, and the owner's own runs). The member keeps the host, the account, the key and the pinned host keys out of

package/stack/ssh-gate.d.mts

@@ -1,5 +1,5 @@
 /** 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';
+export type ArgKind = 'base' | 'release' | 'pointer' | 'token' | 'trigger' | 'attempt' | 'seconds' | 'recipient';
 /** 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;
@@ -20,6 +20,8 @@ export declare function gateOp(name: string): GateOp;
 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 command of an operation up to its arguments (`sh -c '<body>' starci-op`): the text a workflow template renders for a key without the gate. */
+export declare function inlinePrefix(name: 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"`). */

package/stack/ssh-gate.mjs

@@ -10,9 +10,11 @@
 // 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';
+import { SERVER_AGE_IDENTITY } from './server-key.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 RECIPIENT = /^age1[a-z0-9]{58}$/u;
 const BASE = /^\/[A-Za-z0-9._/-]+$/u;
 /** The closed alphabet of each argument kind. */
 export const ARG_TESTS = Object.freeze({
@@ -23,7 +25,14 @@ export const ARG_TESTS = Object.freeze({
     trigger: (value) => value === 'ci' || value === 'dispatch' || value === 'urgent',
     attempt: (value) => ATTEMPT.test(value),
     seconds: (value) => /^[0-9]{1,6}$/u.test(value),
+    recipient: (value) => RECIPIENT.test(value),
 });
+/**
+ * Writes the deploy server's age identity from stdin (stack-key-restore.yml, `--restore github`): the file is the one fixed path SERVER_AGE_IDENTITY,
+ * never an argument, it is kept only when its public key is the recipient $1, it is owned by root with mode 600, and an existing identity is never overwritten.
+ */
+const INNER_RESTORE = 'PATH="$PATH:/usr/local/bin"; umask 077; f="$1"; r="$2"; d="$(dirname "$f")"; mkdir -p "$d"; t="$(mktemp "$d/.restore.XXXXXX")"; cat > "$t"; if [ "$(age-keygen -y "$t" 2>/dev/null)" != "$r" ]; then rm -f "$t"; echo "the secret is not the identity of $r (or age-keygen is missing); nothing was written" >&2; exit 6; fi; chown root:root "$t"; chmod 600 "$t"; mv "$t" "$f"; age-keygen -y "$f"';
+const IDENTITY_RESTORE = `f=${shellQuote(SERVER_AGE_IDENTITY)}; r="$1"; if [ "$(id -u)" -eq 0 ]; then S=; else S="sudo -n"; fi; if $S test -e "$f"; then cat >/dev/null; echo "the server already holds $f; move it aside first" >&2; exit 3; fi; $S sh -c ${shellQuote(INNER_RESTORE)} sh "$f" "$r"`;
 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';
@@ -32,6 +41,7 @@ const POINTER = 'if [ -L "$1/$2" ]; then basename "$(readlink "$1/$2")"; else pr
  * 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: 'identity-restore', args: ['recipient'], stdin: true, body: IDENTITY_RESTORE },
     { 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` },
@@ -80,10 +90,14 @@ export function gatedCommand(name, args) {
 /** 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(' ')}`;
+    return `${inlinePrefix(name)} ${checkedArguments(op, args).map(shellQuote).join(' ')}`;
+}
+/** The command of an operation up to its arguments (`sh -c '<body>' starci-op`): the text a workflow template renders for a key without the gate. */
+export function inlinePrefix(name) {
+    return `sh -c ${shellQuote(gateOp(name).body)} starci-op`;
 }
 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',
+    base: 'v_base', release: 'v_release', pointer: 'v_pointer', token: 'v_token', trigger: 'v_trigger', attempt: 'v_attempt', seconds: 'v_seconds', recipient: 'v_recipient',
 });
 /** The sh variable that holds the body of an operation. */
 const bodyVariable = (name) => `OP_${name.replaceAll('-', '_')}`;
@@ -108,6 +122,7 @@ export function gateScript() {
         '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_recipient() { case "$1" in age1*) ;; *) return 1;; esac; case "$1" in *[!a-z0-9]*) return 1;; esac; [ "${#1}" -eq 62 ]; }',
         'v_seconds() { case "$1" in \'\'|*[!0-9]*) return 1;; esac; [ "${#1}" -le 6 ]; }',
         ...bodies,
         'cmd=${SSH_ORIGINAL_COMMAND-}',

package/sync/index.mjs

@@ -42,6 +42,7 @@ import { readTruths } from '../runtime/scripts/lib/loosening-state.mjs';
 import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
 import { bootstrapSection } from '../runtime/scripts/hfs/rules/database-constants.mjs';
 import { SERVER_AGE_IDENTITY } from '../stack/server-key.mjs';
+import { inlinePrefix } from '../stack/ssh-gate.mjs';
 export const TEMPLATES_DIR = path.join(import.meta.dirname, '..', 'templates');
 const NODE_MAJOR = 22;
 const APP_BINARY = 'starci app';
@@ -408,6 +409,8 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
         nodeMajor: String(NODE_MAJOR),
         // The deploy server's age identity the restore workflow writes (stack/server-key.mjs owns the path).
         serverAgeIdentity: SERVER_AGE_IDENTITY,
+        // The operation `identity-restore` of the ssh gate, as one command for a CI key without the gate (stack/ssh-gate.mjs owns the body), a JSON string so the workflow carries it as one YAML scalar.
+        identityRestoreInline: JSON.stringify(inlinePrefix('identity-restore')),
         sonarKey: sonarKey ?? app.project,
         sonarHostLine: sonarHostLine(quality.sonar),
         sonarExclusions: sonarScope(presets).exclusions.join(','),

package/templates/app/ci-workflows/github/workflows/stack-key-restore.yml

@@ -3,10 +3,9 @@
 # stored it; --restore github dispatches this file). It runs by hand only and writes {{serverAgeIdentity}} on the server when no
 # identity is there and the secret's public key is the recipient input (deploy.remote.serverRecipient), with umask 077 and mode 600,
 # owned by root; it never echoes the identity and never overwrites one.
-# The environment input names the protected GitHub environment of the deploy (required reviewers or main only), which holds:
-#   vars    VPS_HOST, VPS_USER (the swarm manager)
-#   secrets SOPS_AGE_KEY (that environment's server identity, the one its deploy jobs read), VPS_SSH_KEY (CI-only deploy key),
-#           VPS_KNOWN_HOSTS (pinned host keys)
+# The environment input names the protected GitHub environment of the deploy (required reviewers or main only), which holds the secret
+# SOPS_AGE_KEY (that environment's server identity, the one its deploy jobs read). The transport is the sealed member vps-ci of that
+# environment, opened with that identity by the same "stack connect" step the deploy uses: GitHub holds no SSH key, host key, host or account.
 name: restore stack key
 
 on:
@@ -33,26 +32,46 @@ jobs:
     runs-on: ubuntu-latest
     environment: ${{ inputs.environment }}
     timeout-minutes: 10
+    env:
+      STACK_ENVIRONMENT: ${{ inputs.environment }}
     steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci --ignore-scripts
+      - name: install SOPS
+        uses: mdgreenwald/mozilla-sops-action@bb2d96a13ef438ad122e5827a57ebd75d6ff118d # v2.1.0
+        with:
+          version: v3.13.2
+      - name: connect to the swarm manager
+        env:
+          XDG_DATA_HOME: ${{ runner.temp }}/starci-data
+          SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
+        run: npx --no-install starci app stack connect --env "$STACK_ENVIRONMENT" --execute
       - name: write the identity on the server
         env:
           RECIPIENT: ${{ inputs.recipient }}
           AGE_IDENTITY: ${{ secrets.SOPS_AGE_KEY }}
-          VPS_SSH_KEY: ${{ secrets.VPS_SSH_KEY }}
-          VPS_KNOWN_HOSTS: ${{ secrets.VPS_KNOWN_HOSTS }}
-          VPS_HOST: ${{ vars.VPS_HOST }}
-          VPS_USER: ${{ vars.VPS_USER }}
+          INLINE_RESTORE: {{identityRestoreInline}}
         shell: bash
         run: |
           set -euo pipefail
           [[ "$RECIPIENT" =~ ^age1[a-z0-9]+$ ]] || { echo "recipient must be one public age recipient (age1...)" >&2; exit 1; }
           [ -n "$AGE_IDENTITY" ] || { echo "SOPS_AGE_KEY is not set in this environment" >&2; exit 1; }
           umask 077
-          dir="$(mktemp -d)"
-          trap 'rm -rf "$dir"' EXIT
-          printf '%s\n' "$VPS_SSH_KEY" > "$dir/id"
-          printf '%s\n' "$VPS_KNOWN_HOSTS" > "$dir/known_hosts"
-          # The server writes the identity beside its target, keeps it only when its public key is the recipient, then moves it in.
-          remote="f={{serverAgeIdentity}}; r=$RECIPIENT; "'if [ "$(id -u)" -eq 0 ]; then S=; else S="sudo -n"; fi; if $S test -e "$f"; then cat >/dev/null; echo "the server already holds $f; move it aside first" >&2; exit 3; fi; $S sh -c '"'"'PATH="$PATH:/usr/local/bin"; umask 077; f="$1"; r="$2"; d="$(dirname "$f")"; mkdir -p "$d"; t="$(mktemp "$d/.restore.XXXXXX")"; cat > "$t"; if [ "$(age-keygen -y "$t" 2>/dev/null)" != "$r" ]; then rm -f "$t"; echo "the secret is not the identity of $r (or age-keygen is missing); nothing was written" >&2; exit 6; fi; chown root:root "$t"; chmod 600 "$t"; mv "$t" "$f"; age-keygen -y "$f"'"'"' sh "$f" "$r"'
-          printf '%s\n' "$AGE_IDENTITY" | ssh -T -i "$dir/id" -o IdentitiesOnly=yes -o UserKnownHostsFile="$dir/known_hosts" \
-            -o StrictHostKeyChecking=yes -o BatchMode=yes -o ConnectTimeout=20 "$VPS_USER@$VPS_HOST" "$remote"
+          manager="${DOCKER_HOST#ssh://}"
+          # The operation is the ssh gate's identity-restore (stack/ssh-gate.mjs): the server writes the identity beside its target, keeps it only
+          # when its public key is the recipient, then moves it in. A CI key forced through the gate (STARCI_SSH_GATE=1) names it; a key without the gate runs its body.
+          if [ "${STARCI_SSH_GATE:-}" = 1 ]; then
+            remote="starci-op identity-restore $RECIPIENT"
+          else
+            remote="$INLINE_RESTORE $RECIPIENT"
+          fi
+          printf '%s\n' "$AGE_IDENTITY" | ssh -T "$manager" "$remote"
+      - name: disconnect from the swarm manager
+        if: ${{ always() }}
+        env:
+          XDG_DATA_HOME: ${{ runner.temp }}/starci-data
+        run: npx --no-install starci app stack disconnect --env "$STACK_ENVIRONMENT" --execute

package/templates/app/ci-workflows-lite/github/workflows/stack-key-restore.yml

@@ -3,10 +3,9 @@
 # stored it; --restore github dispatches this file). It runs by hand only and writes {{serverAgeIdentity}} on the server when no
 # identity is there and the secret's public key is the recipient input (deploy.remote.serverRecipient), with umask 077 and mode 600,
 # owned by root; it never echoes the identity and never overwrites one.
-# The environment input names the protected GitHub environment of the deploy (required reviewers or main only), which holds:
-#   vars    VPS_HOST, VPS_USER (the swarm manager)
-#   secrets SOPS_AGE_KEY (that environment's server identity, the one its deploy jobs read), VPS_SSH_KEY (CI-only deploy key),
-#           VPS_KNOWN_HOSTS (pinned host keys)
+# The environment input names the protected GitHub environment of the deploy (required reviewers or main only), which holds the secret
+# SOPS_AGE_KEY (that environment's server identity, the one its deploy jobs read). The transport is the sealed member vps-ci of that
+# environment, opened with that identity by the same "stack connect" step the deploy uses: GitHub holds no SSH key, host key, host or account.
 name: restore stack key
 
 on:
@@ -33,26 +32,46 @@ jobs:
     runs-on: ubuntu-latest
     environment: ${{ inputs.environment }}
     timeout-minutes: 10
+    env:
+      STACK_ENVIRONMENT: ${{ inputs.environment }}
     steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci --ignore-scripts
+      - name: install SOPS
+        uses: mdgreenwald/mozilla-sops-action@bb2d96a13ef438ad122e5827a57ebd75d6ff118d # v2.1.0
+        with:
+          version: v3.13.2
+      - name: connect to the swarm manager
+        env:
+          XDG_DATA_HOME: ${{ runner.temp }}/starci-data
+          SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
+        run: npx --no-install starci app stack connect --env "$STACK_ENVIRONMENT" --execute
       - name: write the identity on the server
         env:
           RECIPIENT: ${{ inputs.recipient }}
           AGE_IDENTITY: ${{ secrets.SOPS_AGE_KEY }}
-          VPS_SSH_KEY: ${{ secrets.VPS_SSH_KEY }}
-          VPS_KNOWN_HOSTS: ${{ secrets.VPS_KNOWN_HOSTS }}
-          VPS_HOST: ${{ vars.VPS_HOST }}
-          VPS_USER: ${{ vars.VPS_USER }}
+          INLINE_RESTORE: {{identityRestoreInline}}
         shell: bash
         run: |
           set -euo pipefail
           [[ "$RECIPIENT" =~ ^age1[a-z0-9]+$ ]] || { echo "recipient must be one public age recipient (age1...)" >&2; exit 1; }
           [ -n "$AGE_IDENTITY" ] || { echo "SOPS_AGE_KEY is not set in this environment" >&2; exit 1; }
           umask 077
-          dir="$(mktemp -d)"
-          trap 'rm -rf "$dir"' EXIT
-          printf '%s\n' "$VPS_SSH_KEY" > "$dir/id"
-          printf '%s\n' "$VPS_KNOWN_HOSTS" > "$dir/known_hosts"
-          # The server writes the identity beside its target, keeps it only when its public key is the recipient, then moves it in.
-          remote="f={{serverAgeIdentity}}; r=$RECIPIENT; "'if [ "$(id -u)" -eq 0 ]; then S=; else S="sudo -n"; fi; if $S test -e "$f"; then cat >/dev/null; echo "the server already holds $f; move it aside first" >&2; exit 3; fi; $S sh -c '"'"'PATH="$PATH:/usr/local/bin"; umask 077; f="$1"; r="$2"; d="$(dirname "$f")"; mkdir -p "$d"; t="$(mktemp "$d/.restore.XXXXXX")"; cat > "$t"; if [ "$(age-keygen -y "$t" 2>/dev/null)" != "$r" ]; then rm -f "$t"; echo "the secret is not the identity of $r (or age-keygen is missing); nothing was written" >&2; exit 6; fi; chown root:root "$t"; chmod 600 "$t"; mv "$t" "$f"; age-keygen -y "$f"'"'"' sh "$f" "$r"'
-          printf '%s\n' "$AGE_IDENTITY" | ssh -T -i "$dir/id" -o IdentitiesOnly=yes -o UserKnownHostsFile="$dir/known_hosts" \
-            -o StrictHostKeyChecking=yes -o BatchMode=yes -o ConnectTimeout=20 "$VPS_USER@$VPS_HOST" "$remote"
+          manager="${DOCKER_HOST#ssh://}"
+          # The operation is the ssh gate's identity-restore (stack/ssh-gate.mjs): the server writes the identity beside its target, keeps it only
+          # when its public key is the recipient, then moves it in. A CI key forced through the gate (STARCI_SSH_GATE=1) names it; a key without the gate runs its body.
+          if [ "${STARCI_SSH_GATE:-}" = 1 ]; then
+            remote="starci-op identity-restore $RECIPIENT"
+          else
+            remote="$INLINE_RESTORE $RECIPIENT"
+          fi
+          printf '%s\n' "$AGE_IDENTITY" | ssh -T "$manager" "$remote"
+      - name: disconnect from the swarm manager
+        if: ${{ always() }}
+        env:
+          XDG_DATA_HOME: ${{ runner.temp }}/starci-data
+        run: npx --no-install starci app stack disconnect --env "$STACK_ENVIRONMENT" --execute

package/templates/app/skeleton/.starcistacks/application-stacks.yaml

@@ -167,12 +167,8 @@ ci:
   secrets:
     - {name: SONAR_TOKEN, scope: repository, purpose: Sonar analysis token provisioned for this app}
     - {name: SOPS_AGE_KEY, scope: environment, environment: production, purpose: Decrypt app members during deployment, optional: true}
-    - {name: VPS_SSH_KEY, scope: environment, environment: production, purpose: Deployment SSH key, optional: true}
-    - {name: VPS_KNOWN_HOSTS, scope: environment, environment: production, purpose: Pinned deployment SSH host keys, optional: true}
   vars:
     - {name: SONAR_HOST_URL, scope: repository, value: "https://sonar.{{project}}.example.invalid", purpose: Documentation endpoint to replace with this app's public Sonar host}
-    - {name: VPS_HOST, scope: environment, environment: production, value: 203.0.113.10, purpose: Documentation deployment address to replace before use, optional: true}
-    - {name: VPS_USER, scope: environment, environment: production, value: deploy, purpose: Documentation deployment user to replace before use, optional: true}
 services:
   sonar:
     provider: sonarqube

package/templates/app/skeleton-lite/.starcistacks/application-stacks.yaml

@@ -256,12 +256,8 @@ ci:
   secrets:
     - {name: SONAR_TOKEN, scope: repository, purpose: Sonar analysis token provisioned for this app}
     - {name: SOPS_AGE_KEY, scope: environment, environment: production, purpose: Decrypt app members during deployment, optional: true}
-    - {name: VPS_SSH_KEY, scope: environment, environment: production, purpose: Deployment SSH key, optional: true}
-    - {name: VPS_KNOWN_HOSTS, scope: environment, environment: production, purpose: Pinned deployment SSH host keys, optional: true}
   vars:
     - {name: SONAR_HOST_URL, scope: repository, value: "https://sonar.{{project}}.example.invalid", purpose: Documentation endpoint to replace with this app's public Sonar host}
-    - {name: VPS_HOST, scope: environment, environment: production, value: 203.0.113.10, purpose: Documentation deployment address to replace before use, optional: true}
-    - {name: VPS_USER, scope: environment, environment: production, value: deploy, purpose: Documentation deployment user to replace before use, optional: true}
 services:
   sonar:
     provider: sonarqube