@starci/hfs 4.11.12 → 4.11.13

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 4.11.13 - 2026-10-29
+
+- Fixed: a member sealed to an environment's whole recipient set (the owner key and the deploy server key, the production standard after `server-key --execute`) opens with either identity alone. The selected-identity decrypt (`runtime/scripts/lib/sops-envelope.mjs` `selectedAgeEnvelope`) refused every envelope whose age list held more than one entry (`unsupported-age-set`), so every production read failed once the server key joined; it now admits a set that holds the selected recipient and refuses an empty entry or gap (`invalid-age-entry`) and a recipient named twice (`duplicate-age-recipient`); a dotenv envelope reads every `sops_age__list_<n>__` entry.
+- Fixed: every seal keeps the member's full recipient set (`secret-sops.mjs` `sealRecipients`): the caller's set, else the environment's `.sops.yaml` rule, else the set the existing member is sealed to, under a private one-rule sops config when no rule of the app matches (sops refuses an unmatched file even with `--age`). `set`, `migrate`, `split` and the edit verbs on a production member keep the server recipient.
+- Changed: one age identity lookup for every decrypt of a member, `decryptionIdentity` (`secret-init.mjs`): the environment, the app's `.claude/secret.env`, its main checkout's, the harness CLI's secret.env (`hostIdentity`), then sops' keys.txt. `defaultSops` uses it, `stack`, `release` and `db` hand their context `hostIdentity` (`stackContext`, `release/index.mjs` `contextOf`, `main.mjs`), so a stack deploy opens its members with the same identity `app secret` does; `stack/sealed.mjs` `hasAgeIdentity` reads the seam's finding instead of guessing from files.
+- Changed: a member that cannot be opened is refused naming the member, the format it was read as, its recipients, where the identity came from and its recipient, and why: a failed selected sops run names its class (`sopsFailureClass`: no-matching-identity, mac-mismatch, unparsable-document, timeout, exit-<n>) instead of "the selected invocation was not qualified" alone.
+- Changed: the deploy's sealed SSH members (`deploy.remote.sealed`) are read as what they are: a `.enc.yaml` member through `decrypt(file, "yaml")` and its key, a legacy `.enc` through the binary envelope. The keys are `SEALED_SSH_KEYS` (`stack/remote.mjs`): `privateKey` of `sshKey`, `knownHosts` of `knownHosts`; the `key` and `known_hosts` aliases are gone, and a member without its key is refused naming the keys it holds.
+- Fixed: `server-key` resolves age-keygen as root, the way it calls it (`RESOLVE_AGE_KEYGEN`, `ageKeygenScript`: root's PATH, then `/usr/local/bin`, `/usr/bin`, `/bin`): on AlmaLinux 10 sudo's secure_path leaves `/usr/local/bin` out, so the deploy user's `command -v age-keygen` passed and the root script exited 127 ("age-keygen failed on the server"). The static age installer links age and age-keygen from `/usr/bin` and counts age as present only when root sees it too; `stack-key-restore.yml` (both editions) adds `/usr/local/bin` to its root shell's PATH.
+- Changed: the bundled canon pins name hfs 4.11.13, eslint-canon-be 3.8.12, eslint-canon-fe 9.5.14 and the Grammar family 0.15.25.
+
 ## 4.11.12 - 2026-10-29
 
 - Changed: the skeleton canon gate (`src/scaffold-template-canon-be.spec.mjs`) lints every file under `be/src/modules/platform` of both editions with the starci-be rules, no longer `platform/http` alone; both editions are green.

package/README.md

@@ -230,7 +230,7 @@ one key its whole text or several one `KEY=value` line each, `--from-file KEY=pa
 A member is sealed to its environment's rule of the managed `.sops.yaml`; `recipients <env> [--add|--remove <age1...|owner>]`
 rewrites that rule (`environmentRecipients`, `secret-init.mjs`), and `init` takes the owner's identity as the app's recipient.
 Re-sealing a member whose every key the set replaces needs no age identity; adding a key to one does, and the identity is found
-by itself (`localAgeIdentity`): SOPS_AGE_KEY or SOPS_AGE_KEY_FILE of the environment, else of the app's git-ignored
+by itself (`decryptionIdentity`, the one lookup every decrypt of a member uses: secret, stack, release, db): SOPS_AGE_KEY or SOPS_AGE_KEY_FILE of the environment, else of the app's git-ignored
 `.claude/secret.env`, else of its main checkout's when the app is a git worktree, else the `hostIdentity` the harness CLI passes
 (its own secret.env), else the sops `keys.txt`; with none, the verb refuses before asking for a value, naming every place it
 looked and the one line that fixes it. `audit [<env>]` names every deviation and exits 1; `migrate <env> <member> [--to

package/package.json

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

package/release/index.mjs

@@ -18,9 +18,9 @@ import { RELEASE_CODE, VERSION, normalizeRelease, releaseGate } from './gate.mjs
 import { releasePush } from './push.mjs';
 import { releaseUrgentPush } from './urgent.mjs';
 
-const IO_KEYS = ['cwd', 'stdout', 'stderr', 'env', 'sops'];
+const IO_KEYS = ['cwd', 'stdout', 'stderr', 'env', 'sops', 'hostIdentity'];
 
-/** The stack context of one invocation: the IO of the app (cwd, writers, env, sops) over the injectable seams of `io.stackIo` (spawn, sleep, now, fetch). */
+/** The stack context of one invocation: the IO of the app (cwd, writers, env, sops, hostIdentity) over the injectable seams of `io.stackIo` (spawn, sleep, now, fetch). */
 export function contextOf(io = {}) {
   const own = Object.fromEntries(IO_KEYS.filter((key) => io[key] !== undefined).map((key) => [key, io[key]]));
   return stackContext({ ...io.stackIo, ...own });

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.15.24
+    version: 0.15.25
     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.8.11
+    version: 3.8.12
     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.5.13
+    version: 9.5.14
     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.15.24
+    version: 0.15.25
     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.15.24
+    version: 0.15.25
     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.11.12
+    version: 4.11.13
     group: starci
     install: registry
     side: both

package/runtime/scripts/api/sops/lib.mjs

@@ -116,7 +116,11 @@ function isolatedSopsEnv(env, inlineName = 'SOPS_AGE_KEY') {
   return out;
 }
 
-const held = reason => ({ status: null, stdout: '', stderr: '', error: Object.assign(new Error(`SOPS selected identity [${reason}]: the selected invocation was not qualified`), { name: 'SopsIdentityRefusal', identityRefusal: reason }) });
+/**
+ * A refusal of the selected invocation. `detail` says what failed in public words; `facts` carries only public values the caller
+ * names in its own refusal (`publicRecipient`, the selected identity's recipient; `sopsFailure`, the class of a failed sops run).
+ */
+const held = (reason, detail = 'the selected invocation was not qualified', facts = {}) => ({ status: null, stdout: '', stderr: '', error: Object.assign(new Error(`SOPS selected identity [${reason}]: ${detail}`), { name: 'SopsIdentityRefusal', identityRefusal: reason, ...facts }) });
 const nativeFile = file => {
   if (typeof file !== 'string' || !path.isAbsolute(file) || /\.(?:[cm]?js|cmd|bat|ps1|sh)$/i.test(file)) return false;
   let fd;
@@ -175,11 +179,29 @@ const selectedAdmission = (selection, spec, invocation, env) => {
 
 const decryptArgs = (file, inputType, outputType) => ['decrypt', '--input-type', inputType, '--output-type', outputType, '--filename-override', file, '--enable-local-keyservice=true', '--decryption-order', 'age'];
 
+/**
+ * The class of a failed sops run, read from its stderr and exit; sops prints no value there, and only the class leaves. Classes:
+ * no-matching-identity (no age entry opens with the identity), mac-mismatch (the document changed after it was sealed),
+ * unparsable-document (the bytes are not the format they were read as), timeout, or exit-<n>.
+ */
+export function sopsFailureClass(result) {
+  if (result?.error?.code === 'ETIMEDOUT' || result?.signal === 'SIGTERM') return 'timeout';
+  const text = Buffer.isBuffer(result?.stderr) ? result.stderr.toString('utf8') : String(result?.stderr ?? '');
+  if (/MAC mismatch/iu.test(text)) return 'mac-mismatch';
+  if (/no identity matched|failed to get the data key|could not decrypt data key|0 successful groups/iu.test(text)) return 'no-matching-identity';
+  if (/unmarshal|could not parse|error loading file|invalid character|yaml:/iu.test(text)) return 'unparsable-document';
+  return `exit-${String(result?.status ?? 'none')}`;
+}
+
 const decryptSelected = (run, exe, file, input, spec, recipient) => {
+  const facts = { publicRecipient: recipient };
   const envelope = selectedAgeEnvelope(decoded(input), spec.inputType, recipient);
-  if (!envelope.ok) return held(envelope.reason);
+  if (!envelope.ok) return held(envelope.reason, `the ${spec.inputType} envelope was refused for the selected recipient ${recipient}`, facts);
   const result = run(exe, decryptArgs(file, spec.inputType, spec.outputType), input);
-  if (!captured(result)) return held('selected-decryption-failed');
+  if (!captured(result)) {
+    const failure = sopsFailureClass(result);
+    return held('selected-decryption-failed', `sops could not decrypt the ${spec.inputType} document with the selected recipient ${recipient} (${failure})`, { ...facts, sopsFailure: failure });
+  }
   return { status: 0, stdout: decoded(result.stdout), stderr: '', error: null };
 };
 

package/runtime/scripts/api/sops/seal.mjs

@@ -7,10 +7,11 @@ import { resolveSops, runSelectedSops } from './lib.mjs';
 
 /**
  * Run `<bin> encrypt` (bin null: the sops resolveSops finds) over `plaintext` of format `inputType` (json, yaml or dotenv). Sops reads stdin only with a `--filename-override`, the path the sealed
- * file will have: recipients are age keys (`--age`), and when none are given sops picks them from the repository's .sops.yaml for that path. {status, stdout, stderr, error}.
+ * file will have: recipients are age keys (`--age`), and when none are given sops picks them from the repository's .sops.yaml for that path. `config` names
+ * the sops configuration to read instead of the repository's (a rule-less member sealed to its own recipients). {status, stdout, stderr, error}.
  */
-export function seal(bin, { inputType, plaintext, recipients = [], filenameOverride }, { invocation = null, env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024, timeout = undefined } = {}) {
-  const args = ['encrypt', '--input-type', inputType, '--output-type', inputType, '--filename-override', filenameOverride];
+export function seal(bin, { inputType, plaintext, recipients = [], filenameOverride, config = null }, { invocation = null, env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024, timeout = undefined } = {}) {
+  const args = [...(config ? ['--config', config] : []), 'encrypt', '--input-type', inputType, '--output-type', inputType, '--filename-override', filenameOverride];
   if (recipients.length) args.push('--age', recipients.join(','));
   const selected = sopsIdentityEnv(env);
   if (selected.error?.identityRefusal === 'inline-context-unqualified') return runSelectedSops(bin, { operation: 'seal', params: { inputType, plaintext, recipients, filenameOverride } }, { selection: selected, invocation, env, cwd, maxBuffer, timeout });

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

@@ -106,6 +106,21 @@ export function localAgeIdentity(repoRoot, env, tools, host = null) {
   return { env: { ...env }, source: null, looked };
 }
 
+/**
+ * The one age identity every decrypt of a sealed member opens with (secret get, verify, materialize, set over an existing member,
+ * migrate, split, the edit verbs, updatekeys, server-key, the stack's sealed members and the CLI's custody): localAgeIdentity's
+ * order (the environment, the app's `.claude/secret.env`, its main checkout's, the `host` port), then sops' per-user keys.txt.
+ * Same shape as localAgeIdentity; `looked` names every place read, keys.txt last.
+ */
+export function decryptionIdentity(repoRoot, env, { tools, host = null, platform = process.platform } = {}) {
+  const local = localAgeIdentity(repoRoot, env, tools, host);
+  if (local.source !== null) return local;
+  const keys = secretRoots(env, platform).identity;
+  const looked = [...local.looked, keys];
+  if (!fs.existsSync(keys)) return { ...local, looked };
+  return { env: { ...local.env, SOPS_AGE_KEY_FILE: keys }, source: keys, looked };
+}
+
 /** Load host-local age selections below the explicit environment (localAgeIdentity), without copying any other credentials. */
 export function ageIdentityEnv(repoRoot, env, tools) {
   return localAgeIdentity(repoRoot, env, tools).env;

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

@@ -1,5 +1,6 @@
 // secret-sops.mjs - runtime SOPS adapter and age identity selection.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { runProgram } from "../api/process/run-program.mjs";
 import { resolveRealTool } from "../api/process/resolve-real-tool.mjs";
@@ -9,8 +10,8 @@ import { updateKeys as sopsUpdateKeys } from "../api/sops/update-keys.mjs";
 import { isLegacyName } from "../lib/sealed-member.mjs";
 import { invocationDir } from "../lib/roots.mjs";
 import { envelopeOf } from "./secret-document.mjs";
-import { configuredRecipients, localAgeIdentity, secretTools } from "./secret-init.mjs";
-import { outsideRepository, secretRoots } from "./secret-files.mjs";
+import { configuredRecipients, decryptionIdentity, secretTools } from "./secret-init.mjs";
+import { outsideRepository } from "./secret-files.mjs";
 import { SecretError, publicStorage } from "./secret-errors.mjs";
 
 const sopsInvocation = Object.freeze({ runProgram, resolveRealTool });
@@ -45,15 +46,27 @@ function recipientsOf(file) {
  * The refusal of a decrypt whose selected identity is not one `file` is sealed to: names where the identity came from and the
  * member's recipients, and the two ways out. It carries no value.
  */
-function identityMismatch(repoRoot, identity, file) {
+function identityMismatch(repoRoot, identity, file, publicRecipient) {
   const recipients = recipientsOf(file);
+  const own = publicRecipient ? ` (recipient ${publicRecipient})` : "";
   return new SecretError(
-    `the age identity of ${identity.source ?? "the environment"} does not open ${path.basename(file)}, ` +
-      `sealed to ${recipients.join(", ") || "another recipient"}. Fix: put that recipient's age secret key in ${path.join(repoRoot, ".claude", "secret.env")} as SOPS_AGE_KEY, ` +
-      "or, when no one holds it any more, seal the member's keys again (remove it and set them) after .sops.yaml names this identity's recipient",
+    `the age identity of ${identity.source ?? "the environment"}${own} does not open ${path.basename(file)}, ` +
+      `sealed to ${recipients.join(", ") || "another recipient"}. Fix: put one of those recipients' age secret key in ${path.join(repoRoot, ".claude", "secret.env")} as SOPS_AGE_KEY, ` +
+      "or, when no one holds any of them any more, seal the member's keys again (remove it and set them) after .sops.yaml names this identity's recipient",
   );
 }
 
+/**
+ * Any other refusal of a decrypt: the member, the format it was read as, the recipients it is sealed to, where the age identity
+ * came from and (when derived) its recipient, then the refusal itself. Public facts only.
+ */
+function identityRefused(identity, file, format, error) {
+  const recipients = recipientsOf(file);
+  const own = error.publicRecipient ? `, recipient ${error.publicRecipient}` : "";
+  const source = identity.source ? `the age identity of ${identity.source}${own}` : `no age identity (looked in ${identity.looked.join(", ") || "the environment"})`;
+  return `${path.basename(file)} (read as ${format ?? "its own format"}, sealed to ${recipients.join(", ") || "no age recipient"}) cannot be opened with ${source}: ${error.message}`;
+}
+
 /**
  * The refusal of an operation that must decrypt `file` with no age identity selected: it names the recipient the member is
  * sealed to, every place looked, and the one line that fixes it. It carries no value.
@@ -70,8 +83,40 @@ function identityMissing(repoRoot, identity, file) {
 }
 
 /**
- * The default sops seam: the runtime's sops api, which finds the binary on this machine; the age identity is localAgeIdentity's
- * (`host` its last source), then the legacy sops keys.txt. `identity` says where the age identity
+ * The recipient set a seal of `file` writes: the caller's `named` set, else the environment's .sops.yaml rule, else the full set
+ * the existing member is sealed to, so no rewrite (set, migrate, split, an edit) drops a recipient such as the deploy server's.
+ * `ruled` says whether a rule of the app's .sops.yaml matches the file. Refused, as the rule refuses, when none names one.
+ */
+function sealRecipients(repoRoot, file, named) {
+  try {
+    const rule = configuredRecipients(repoRoot, file);
+    return { recipients: named.length ? named : rule, ruled: true };
+  } catch (error) {
+    const existing = named.length ? named : fs.existsSync(file) ? recipientsOf(file) : [];
+    if (existing.length) return { recipients: existing, ruled: false };
+    throw error;
+  }
+}
+
+/**
+ * Runs `seal` with a private sops configuration naming only `recipients` when the app's .sops.yaml has no rule for the member
+ * (sops refuses a file no rule matches even with --age); the folder is removed after. Public keys only.
+ */
+function withOwnRule(ruled, recipients, seal) {
+  if (ruled) return seal(null);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "starci-sops-rule-"));
+  try {
+    const config = path.join(dir, ".sops.yaml");
+    fs.writeFileSync(config, `creation_rules:\n  - age: ${recipients.join(",")}\n`);
+    return seal(config);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The default sops seam: the runtime's sops api, which finds the binary on this machine; the age identity is decryptionIdentity's
+ * (`host` the harness CLI's secret.env, then sops' keys.txt). `identity` says where the age identity
  * was found (`source`, null when nowhere) and where it was looked for; `requireIdentity(file)` refuses, before any value is
  * read, an operation that must decrypt `file` with no identity.
  */
@@ -83,7 +128,7 @@ export function defaultSops(
   host = null,
 ) {
   const { sops: binary } = publicStorage(() => secretTools(env, tools));
-  const local = localAgeIdentity(repoRoot, env, tools, host);
+  const local = decryptionIdentity(repoRoot, env, { tools, host, platform });
   const selectedEnv = local.env;
   const identity = { source: local.source, looked: [...local.looked] };
   const invocation = {
@@ -109,27 +154,16 @@ export function defaultSops(
         );
       checkIdentity(value);
     }
-  if (
-    !Object.keys(selectedEnv).some((name) => AGE_IDENTITY_NAME.test(name))
-  ) {
-    const keys = secretRoots(env, platform).identity;
-    checkIdentity(keys);
-    identity.looked.push(keys);
-    if (fs.existsSync(keys)) {
-      selectedEnv.SOPS_AGE_KEY_FILE = keys;
-      identity.source = keys;
-    }
-  }
   const requireIdentity = (file) => {
     if (identity.source === null) throw identityMissing(repoRoot, identity, file);
   };
-  const refuse = (what, result, file) => {
+  const refuse = (what, result, file, format) => {
     if (result.error?.identityRefusal === "identity-not-supplied" && file)
       return identityMissing(repoRoot, identity, file);
     if (result.error?.identityRefusal === "recipient-mismatch" && file)
-      return identityMismatch(repoRoot, identity, file);
+      return identityMismatch(repoRoot, identity, file, result.error.publicRecipient);
     if (result.error?.identityRefusal)
-      return Object.assign(new SecretError(result.error.message), {
+      return Object.assign(new SecretError(file ? identityRefused(identity, file, format, result.error) : result.error.message), {
         identityRefusal: result.error.identityRefusal,
       });
     if (result.error?.code === "SOPS_MISSING")
@@ -157,6 +191,7 @@ export function defaultSops(
           `decrypt ${path.basename(file)}; is the age identity installed?`,
           result,
           file,
+          format,
         );
       if (exact) return exactMap(result.stdout);
       const map = Object.create(null);
@@ -193,6 +228,7 @@ export function defaultSops(
           `decrypt ${path.basename(file)}; is the age identity installed?`,
           result,
           file,
+          types[0],
         );
       return String(result.stdout);
     },
@@ -207,21 +243,17 @@ export function defaultSops(
         { env: selectedEnv, cwd: repoRoot, invocation },
       );
       if (result.status !== 0)
-        throw refuse(`update the keys of ${path.basename(file)}; is the age identity a recipient of it?`, result, file);
+        throw refuse(`update the keys of ${path.basename(file)}; is the age identity a recipient of it?`, result, file, isLegacyName(file) ? "dotenv" : "yaml");
     },
     seal(request) {
-      const recipients = request.recipients.length
-        ? request.recipients
-        : publicStorage(() =>
-            configuredRecipients(repoRoot, request.filenameOverride),
-          );
-      // Sealing needs only public recipients, so it runs with no identity selected and may name several (an environment's
+      const { recipients, ruled } = publicStorage(() => sealRecipients(repoRoot, request.filenameOverride, request.recipients));
+      // Sealing needs only public recipients, so it runs with no identity selected and seals to the whole set (an environment's
       // server key and the owner key both).
-      const result = sopsSeal(
+      const result = withOwnRule(ruled, recipients, (config) => sopsSeal(
         binary,
-        { ...request, recipients },
+        { ...request, recipients, config },
         { env: withoutIdentity(selectedEnv), cwd: repoRoot, invocation },
-      );
+      ));
       if (result.status !== 0) throw refuse("seal the secret", result);
       return result.stdout;
     },

package/runtime/scripts/lib/sops-envelope.mjs

@@ -62,13 +62,17 @@ export function isSopsEnvelope(text) {
   try { return sopsTree(parseYaml(src)); } catch { return false; }
 }
 
-/** Admit one flat age envelope for the native selected-identity invocation; this is shape admission, never cryptographic proof. */
+/** A refused admission, named by its reason. */
 const refusal = (reason) => ({ ok: false, reason });
 
+const DOTENV_AGE_FIELD = /^age__list_(0|[1-9]\d{0,2})__map_(recipient|enc)$/u;
+
 function dotenvMetadataValue(meta, age, key, value) {
-  if (key === 'age__list_0__map_recipient') age.recipient = value;
-  else if (key === 'age__list_0__map_enc') age.enc = value;
-  else if (key === 'mac_only_encrypted') {
+  const field = DOTENV_AGE_FIELD.exec(key);
+  if (field) {
+    const entry = (age[Number(field[1])] ??= {});
+    entry[field[2]] = value;
+  } else if (key === 'mac_only_encrypted') {
     if (value !== 'false') return 'partial-mac';
     meta[key] = false;
   } else if (key.includes('__')) return 'unsupported-key-group';
@@ -88,13 +92,14 @@ function readDotenvMetadata(text) {
     pairs.set(name, line.slice(at + 1).replaceAll(String.raw`\n`, '\n'));
   }
   const meta = {};
-  const age = {};
+  const age = [];
   for (const [name, value] of pairs) {
     if (!name.startsWith('sops_')) continue;
     const reason = dotenvMetadataValue(meta, age, name.slice('sops_'.length), value);
     if (reason) return { refusal: reason };
   }
-  meta.age = [age];
+  // A gap in the list indices is an entry sops never wrote: refused as an empty entry, never skipped.
+  meta.age = Array.from(age, (entry) => entry ?? null);
   return { meta };
 }
 
@@ -142,15 +147,35 @@ function validateAgeMetadata(meta, text, recipient) {
   const fields = new Set([...providers, 'age', 'lastmodified', 'mac', 'version', 'unencrypted_suffix', 'encrypted_suffix', 'unencrypted_regex', 'encrypted_regex', 'unencrypted_comment_regex', 'encrypted_comment_regex', 'mac_only_encrypted']);
   if (Object.keys(meta).some(name => !fields.has(name))) return refusal('unknown-metadata');
   if (Object.hasOwn(meta, 'mac_only_encrypted') && meta.mac_only_encrypted !== false) return refusal('partial-mac');
-  if (!Array.isArray(meta.age) || meta.age.length !== 1) return refusal('unsupported-age-set');
-  const entry = meta.age[0];
-  if (!isAgeEntry(entry)) return refusal('invalid-age-entry');
-  if (typeof entry.recipient !== 'string' || entry.recipient !== recipient) return refusal('recipient-mismatch');
-  if (!hasValidAgePayload(entry)) return refusal('invalid-age-entry');
+  const set = ageSet(meta.age);
+  if (!set.ok) return set;
+  if (!set.recipients.includes(recipient)) return refusal('recipient-mismatch');
   if (!hasValidEnvelopeVersion(meta)) return refusal('invalid-envelope');
   return { ok: true };
 }
 
+const AGE_RECIPIENT = /^age1[ac-hj-np-z02-9]+$/u;
+
+/**
+ * The age set of an envelope: one or more entries (the owner key and an environment's server key are the standard pair), each a
+ * well-formed recipient with its wrapped data key; an empty entry or a recipient named twice is refused.
+ */
+function ageSet(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return refusal('unsupported-age-set');
+  const recipients = [];
+  for (const entry of entries) {
+    if (!isAgeEntry(entry) || typeof entry.recipient !== 'string' || !AGE_RECIPIENT.test(entry.recipient) || !hasValidAgePayload(entry))
+      return refusal('invalid-age-entry');
+    if (recipients.includes(entry.recipient)) return refusal('duplicate-age-recipient');
+    recipients.push(entry.recipient);
+  }
+  return { ok: true, recipients };
+}
+
+/**
+ * Admit one flat age envelope for the native selected-identity invocation when `recipient` (the selected identity's public key) is
+ * one of its age set. Shape admission, never cryptographic proof.
+ */
 export function selectedAgeEnvelope(text, format, recipient) {
   if (!['binary', 'json', 'yaml', 'dotenv'].includes(format)) return refusal('unsupported-format');
   const parsed = readAgeMetadata(text, format);

package/src/main.mjs

@@ -435,8 +435,8 @@ function declaredEdition(cwd) {
  * `starci app stack`: the deploy actions (prepare, doctor, render, deploy, converge, verify, rollback, prune, backup, jobs, ...) are the Swarm
  * tooling of stack/cli.mjs; up, down and status are the full edition's test-world infrastructure.
  */
-async function stackAppMain(argv, { cwd, edition, stackMain, stdout: out, stderr: err, env, sops, stackIo }) {
-  if (STACK_ACTIONS.includes(argv[0])) return deployStackMain(argv, { ...stackIo, cwd, stdout: out, stderr: err, env, ...(sops ? { sops } : {}) });
+async function stackAppMain(argv, { cwd, edition, stackMain, stdout: out, stderr: err, env, sops, hostIdentity, stackIo }) {
+  if (STACK_ACTIONS.includes(argv[0])) return deployStackMain(argv, { ...stackIo, cwd, stdout: out, stderr: err, env, hostIdentity, ...(sops ? { sops } : {}) });
   if ((edition ?? declaredEdition(cwd)) === 'lite') throw new Error('starci app stack up|down|status manage the local test world of the full edition; a lite app starts its local database with npm run db:start');
   const run = stackMain ?? await installedStackMain(cwd);
   return run(argv, { cwd, out, err });
@@ -462,7 +462,7 @@ function errorMessage(error) {
  * `harness` ({ version }) is the CLI that runs this package in-process: its version is the starci-harness an app is judged and
  * scaffolded at (runtime/scripts/hfs/canon-pins.mjs). `run` injects the database runner, `runLinter` the linter transport, `checkApp`
  * the HFS check and `stackIo` Swarm tools; production defaults execute every check. `hostIdentity` ({ label, read }) is the
- * harness CLI's own secret.env SOPS_AGE_KEY, which `secret` reads last for the age identity; `prompt` replaces its masked prompt.
+ * harness CLI's own secret.env SOPS_AGE_KEY, which every verb that opens a sealed member (secret, stack, release, db) reads last for the age identity (decryptionIdentity); `prompt` replaces its masked prompt.
  */
 export async function main(argv, {
   cwd: baseCwd = process.cwd(), harness, stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier, lock, run, stackMain,

package/stack/age-install.mjs

@@ -17,10 +17,18 @@ const STATIC_INSTALL = [
   `echo "${AGE_SHA256}  $tmp/age.tgz" | sha256sum -c -`,
   'tar -xzf "$tmp/age.tgz" -C "$tmp"',
   'sudo -n install -m 0755 "$tmp/age/age" "$tmp/age/age-keygen" /usr/local/bin/',
+  // sudo's secure_path (AlmaLinux 10, RHEL) leaves /usr/local/bin out: a link in /usr/bin makes both tools visible to the deploy
+  // user and to root alike; an existing /usr/bin tool (a packaged age) is kept.
+  'for b in age age-keygen; do if [ ! -e "/usr/bin/$b" ]; then sudo -n ln -s "/usr/local/bin/$b" "/usr/bin/$b"; fi; done',
 ].join('; ');
 
 const packageManager = (run) => run('for m in dnf yum apk apt-get; do command -v $m >/dev/null 2>&1 && echo $m && break; done').stdout.trim();
-const present = (run) => run('command -v age').status === 0;
+/**
+ * Both tools, as the deploy user and, where passwordless sudo exists, as root: an install the root PATH cannot see is not taken
+ * for present.
+ */
+const PRESENT = 'command -v age >/dev/null 2>&1 && command -v age-keygen >/dev/null 2>&1 && { [ "$(id -u)" -eq 0 ] || ! sudo -n true 2>/dev/null || sudo -n sh -c \'command -v age >/dev/null 2>&1 && command -v age-keygen >/dev/null 2>&1\'; }';
+const present = (run) => run(PRESENT).status === 0;
 
 /** Installs age when it is missing; reports through `report`. */
 export function installAge(run, report) {
@@ -33,6 +41,6 @@ export function installAge(run, report) {
     failure = `${manager} could not install age: ${firstLine(packaged.stderr)}`;
   }
   const fetched = run(STATIC_INSTALL);
-  if (fetched.status === 0 && present(run)) report.note(`installed the official static age ${AGE_VERSION} (sha256 verified) into /usr/local/bin; ${failure}`);
+  if (fetched.status === 0 && present(run)) report.note(`installed the official static age ${AGE_VERSION} (sha256 verified) into /usr/local/bin, linked from /usr/bin; ${failure}`);
   else report.bad(`cannot install age (${failure}); the static install failed too: ${firstLine(fetched.stderr)} (needs passwordless sudo once, or install age by hand)`);
 }

package/stack/context.mjs

@@ -57,7 +57,7 @@ const realSleep = (ms) => new Promise((done) => { setTimeout(done, ms); });
  *   stdout, stderr text writers
  *   fetch          the HTTP seam of verify (url, init) -> Response
  *   pipe           (source, sink) -> Promise<{ source, sink, stderr }>: one process's stdout streamed into another's stdin (realPipe)
- *   sops           the secret seam (decrypt(file, format) -> map; decryptBinary(file) -> text); `io.sops`, else on first use `io.openSops()` or the app's own sops/age tools
+ *   sops           the secret seam (decrypt(file, format) -> map; decryptBinary(file) -> text); `io.sops`, else on first use `io.openSops()` or the app's own sops/age tools with the age identity decryptionIdentity finds (`io.hostIdentity` the harness CLI's secret.env)
  */
 export function stackContext(io = {}) {
   const cwd = io.cwd ?? process.cwd();
@@ -78,7 +78,7 @@ export function stackContext(io = {}) {
     pipe: io.pipe ?? realPipe,
     /** The secret seam: the app's own sops/age tools, created on first use so verbs that open no custody never need them. */
     get sops() {
-      sops ??= io.openSops?.() ?? defaultSops(env, cwd);
+      sops ??= io.openSops?.() ?? defaultSops(env, cwd, io.platform ?? process.platform, undefined, io.hostIdentity ?? null);
       return sops;
     },
   });

package/stack/remote.mjs

@@ -64,24 +64,36 @@ function sshCommandArgv(sshCmd) {
   return parts;
 }
 
-/** A sealed binary member is the file itself; a JSON object around it ({ data | <names> }, the re-sealed shape of `starci app secret rename`) is unwrapped. */
-function unwrap(text, names) {
+/**
+ * The key each sealed SSH member of `deploy.remote.sealed` holds (contexts/project/stacks.md PROJECT-STACKS-5): the one owner of
+ * these names. `sshKey` names the member whose `privateKey` is the PEM private key, `knownHosts` the member whose `knownHosts` is
+ * the pinned known_hosts text.
+ */
+export const SEALED_SSH_KEYS = Object.freeze({ sshKey: 'privateKey', knownHosts: 'knownHosts' });
+
+/** A legacy binary member is the file itself; a JSON object around it ({ data | <key> }, the re-sealed shape of `starci app secret rename`) is unwrapped. */
+function unwrap(text, key) {
   const body = lfOnly(text);
   const trimmed = body.trim();
   if (!trimmed.startsWith('{')) return body;
   let parsed;
   try { parsed = JSON.parse(trimmed); } catch { return body; }
-  for (const name of ['data', ...names]) if (typeof parsed[name] === 'string') return lfOnly(parsed[name]);
+  for (const name of ['data', key]) if (typeof parsed[name] === 'string') return lfOnly(parsed[name]);
   return body;
 }
 
+/** The sops format a sealed member is read as: a `.enc.yaml` member is YAML, a legacy `.enc` one dotenv. */
+const memberFormat = (file) => (isLegacyName(file) ? 'dotenv' : 'yaml');
+
+/** Opens one member through the sops seam; a failure is refused naming the member and the seam's own reason (format, recipients, identity). */
 function openMember(slug, read) {
   try { return read(); } catch (error) { throw refusal('STACK_REMOTE_SEALED', `cannot open the sealed member ${slug}: ${error.message}`); }
 }
 
 function opsAccount(ctx, config) {
   const slug = config.remote.sealed.ops;
-  const map = openMember(slug, () => ctx.sops.decrypt(memberFile(config.secretsDir, slug), isLegacyName(memberFile(config.secretsDir, slug)) ? 'dotenv' : 'yaml'));
+  const file = memberFile(config.secretsDir, slug);
+  const map = openMember(slug, () => ctx.sops.decrypt(file, memberFormat(file)));
   for (const name of ['VPS_HOST', 'VPS_USER']) {
     const value = map[name];
     if (typeof value !== 'string' || !ACCOUNT.test(value) || value.startsWith('-')) throw refusal('STACK_REMOTE_OPS', `${slug} must hold ${name} (letters, digits, . _ @ -)`);
@@ -89,8 +101,17 @@ function opsAccount(ctx, config) {
   return `${map.VPS_USER}@${map.VPS_HOST}`;
 }
 
-function binaryMember(ctx, config, slug, names) {
-  return unwrap(openMember(slug, () => ctx.sops.decryptBinary(memberFile(config.secretsDir, slug))), names);
+/**
+ * The text a sealed SSH member holds under `key` (SEALED_SSH_KEYS): a `.enc.yaml` member is read as YAML and the key taken from
+ * its map; a legacy `.enc` member is the sops binary or JSON envelope it was sealed as.
+ */
+function sshMember(ctx, config, slug, key) {
+  const file = memberFile(config.secretsDir, slug);
+  if (isLegacyName(file)) return unwrap(openMember(slug, () => ctx.sops.decryptBinary(file)), key);
+  const map = openMember(slug, () => ctx.sops.decrypt(file, 'yaml'));
+  if (typeof map[key] !== 'string' || map[key] === '')
+    throw refusal('STACK_REMOTE_SEALED', `the sealed member ${slug} holds no ${key} (it holds ${Object.keys(map).join(', ') || 'no key'}): seal it with starci app secret set ${config.env ?? '<env>'} ${slug} ${key} --from-file ${key}=<file>`);
+  return lfOnly(map[key]);
 }
 
 const withNewline = (text) => `${text.trim()}\n`;
@@ -107,9 +128,9 @@ export function openSealedSession(ctx, config) {
   const account = opsAccount(ctx, config);
   if (config.nativeTarget && account !== `${config.nativeTarget.user}@${config.nativeTarget.host}`)
     throw refusal('STACK_REMOTE_OPS', 'the sealed SSH account differs from the accepted native target');
-  const key = binaryMember(ctx, config, sealed.sshKey, ['privateKey', 'key']);
+  const key = sshMember(ctx, config, sealed.sshKey, SEALED_SSH_KEYS.sshKey);
   if (!key.includes('PRIVATE KEY')) throw refusal('STACK_REMOTE_KEY', `${sealed.sshKey} does not hold a PEM private key`);
-  const known = binaryMember(ctx, config, sealed.knownHosts, ['knownHosts', 'known_hosts']).trim();
+  const known = sshMember(ctx, config, sealed.knownHosts, SEALED_SSH_KEYS.knownHosts).trim();
   assertStackAccount(config.nativeTarget, account, known);
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-ssh-'));
   const keyFile = path.join(dir, 'id');

package/stack/sealed.mjs

@@ -5,7 +5,6 @@ import { createHash, createHmac } from 'node:crypto';
 import { memberFile } from '../runtime/scripts/lib/sealed-member.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
-import { secretRoots } from '../runtime/scripts/hfs/secret-files.mjs';
 import { readMap } from '../runtime/scripts/hfs/secret-store.mjs';
 import { refusal } from './errors.mjs';
 
@@ -52,27 +51,32 @@ function secretRuntimeName(stack, key, value, versionKey) {
   return name;
 }
 
-const AGE_IDENTITY_ENV = /^SOPS_AGE_KEY(?:_FILE)?$/iu;
-const AGE_HINT = 'load the age identity into SOPS_AGE_KEY (the secret.env of the owner machine, or the CI secret) and retry';
+const AGE_HINT = 'add SOPS_AGE_KEY to .claude/secret.env of the app or the harness secret.env of the owner machine (the CI secret in a workflow) and retry';
 
-/** True when an age identity is reachable: SOPS_AGE_KEY or SOPS_AGE_KEY_FILE in the environment, the repository's .claude/secret.env or the per-user keys.txt. */
-export function hasAgeIdentity(ctx, config) {
-  const named = Object.entries(ctx.env).some(([name, value]) => AGE_IDENTITY_ENV.test(name) && value);
-  return named || fs.existsSync(path.join(config.repoRoot, '.claude', 'secret.env')) || fs.existsSync(secretRoots(ctx.env).identity);
+/**
+ * True when the sops seam found an age identity (secret-init.mjs decryptionIdentity, the one lookup every decrypt uses). A seam
+ * that reports no `identity` (a spec double) decides for itself.
+ */
+export function hasAgeIdentity(ctx) {
+  const { identity } = ctx.sops;
+  return identity === undefined || identity.source !== null;
 }
 
 /** Refuses up front, before any work, when sealed custody must be opened and no age identity is reachable. */
 export function requireAgeIdentity(ctx, config, purpose) {
-  if (!hasAgeIdentity(ctx, config)) throw refusal('STACK_AGE_IDENTITY_MISSING', `${purpose} needs the sealed members, and no age identity is available: ${AGE_HINT}`);
+  if (!hasAgeIdentity(ctx)) throw refusal('STACK_AGE_IDENTITY_MISSING', `${purpose} needs the sealed members, and no age identity is available (looked in ${ctx.sops.identity.looked.join(', ')}): ${AGE_HINT}`);
 }
 
-/** Opens one sealed member (`<secretsDir>/<member>.enc.yaml`, or a legacy `.enc`) into a { KEY: value } map. Names the member only on failure. */
+/**
+ * Opens one sealed member (`<secretsDir>/<member>.enc.yaml`, or a legacy `.enc`) into a { KEY: value } map. A failure is refused
+ * naming the member and the seam's reason (its format, recipients and the identity tried); no value.
+ */
 export function openMember(ctx, config, member) {
   try {
     const map = readMap(memberFile(config.secretsDir, member), ctx.sops);
     return Object.fromEntries(Object.entries(map).map(([key, value]) => [key, typeof value === 'string' && !value.includes(String.fromCodePoint(0)) ? lfText(value) : value]));
-  } catch {
-    throw refusal('STACK_SECRET_MEMBER_UNREADABLE', `the sealed member ${member} cannot be opened${hasAgeIdentity(ctx, config) ? ' (is the age identity a recipient of this member?)' : `: no age identity is available, ${AGE_HINT}`}`);
+  } catch (error) {
+    throw refusal('STACK_SECRET_MEMBER_UNREADABLE', `the sealed member ${member} cannot be opened: ${error.message}${hasAgeIdentity(ctx) ? '' : `; ${AGE_HINT}`}`);
   }
 }
 

package/stack/server-key.mjs

@@ -42,6 +42,22 @@ const RECIPIENT = /^age1[a-z0-9]+$/u;
 /** A command run as root: directly when the deploy user is root, else over passwordless sudo, the script read from stdin. */
 const AS_ROOT = 'if [ "$(id -u)" -eq 0 ]; then sh -s; else sudo -n sh -s; fi';
 
+/**
+ * The directories, after root's PATH, where age-keygen is looked for: sudo's secure_path (AlmaLinux 10, RHEL) leaves out
+ * /usr/local/bin, where the static installer puts it, so the presence check and every call resolve it the same way, as root.
+ */
+export const AGE_KEYGEN_DIRS = ['/usr/local/bin', '/usr/bin', '/bin'];
+
+/** The shell lines that set k to age-keygen's absolute path as root sees it, or exit 127 naming it missing. Every root script holds them. */
+export const RESOLVE_AGE_KEYGEN = [
+  'k="$(command -v age-keygen 2>/dev/null || true)"',
+  `for d in ${AGE_KEYGEN_DIRS.join(' ')}; do if [ -z "$k" ] && [ -x "$d/age-keygen" ]; then k="$d/age-keygen"; fi; done`,
+  'if [ -z "$k" ]; then echo "age-keygen is not installed" >&2; exit 127; fi',
+].join('\n');
+
+/** The root script that only resolves age-keygen and prints its path: the presence check, run exactly as the calls run. */
+export const ageKeygenScript = () => ['set -eu', RESOLVE_AGE_KEYGEN, String.raw`printf '%s\n' "$k"`].join('\n');
+
 /**
  * The GitHub Environment secret that holds an environment's server identity. It carries the name the deploy workflows read
  * (secrets.SOPS_AGE_KEY), scoped to the Environment <env>: for a job bound to <env> it overrides a repository secret of that name.
@@ -54,24 +70,25 @@ export function ensureIdentityScript(file) {
   return [
     'set -eu',
     'umask 077',
+    RESOLVE_AGE_KEYGEN,
     `f=${quoted}`,
     'if [ -e "$f" ] || [ -L "$f" ]; then',
     '  if [ -L "$f" ] || [ ! -f "$f" ]; then echo "the identity path is not an ordinary file" >&2; exit 4; fi',
     '  echo "identity kept" >&2',
     'else',
     '  mkdir -p "$(dirname "$f")"',
-    '  age-keygen -o "$f" >/dev/null 2>&1',
+    '  "$k" -o "$f" >/dev/null 2>&1',
     '  echo "identity created" >&2',
     'fi',
     'chown root:root "$f"',
     'chmod 600 "$f"',
-    'age-keygen -y "$f"',
+    '"$k" -y "$f"',
   ].join('\n');
 }
 
 /** The shell that prints only the public key of `file`, or exits 5 when there is none. */
 export function publicKeyScript(file) {
-  return ['set -eu', `f=${shellQuote(file)}`, '[ -f "$f" ] || exit 5', 'age-keygen -y "$f"'].join('\n');
+  return ['set -eu', RESOLVE_AGE_KEYGEN, `f=${shellQuote(file)}`, '[ -f "$f" ] || exit 5', '"$k" -y "$f"'].join('\n');
 }
 
 /** The shell that swaps the staged `<file>.next` in, keeping the old identity as `retired`, then prints only the new public key. */
@@ -79,6 +96,7 @@ export function swapIdentityScript(file, retired) {
   return [
     'set -eu',
     'umask 077',
+    RESOLVE_AGE_KEYGEN,
     `f=${shellQuote(file)}`,
     `r=${shellQuote(retired)}`,
     'n="$f.next"',
@@ -87,7 +105,7 @@ export function swapIdentityScript(file, retired) {
     'mv "$f" "$r"',
     'mv "$n" "$f"',
     'chmod 600 "$f" "$r"',
-    'age-keygen -y "$f"',
+    '"$k" -y "$f"',
   ].join('\n');
 }
 
@@ -112,14 +130,20 @@ function declaredRemote(repoRoot, env) {
   return remote;
 }
 
-/** Ensures age-keygen on the server: stack prepare's installer owns the install (with --execute); without it the exact commands. */
+/** True when root resolves age-keygen the way every server-key script does (ageKeygenScript). */
+const hasKeygen = (run) => asRoot(run, ageKeygenScript()).status === 0;
+
+/**
+ * Ensures age-keygen on the server, checked as root exactly as it is called: stack prepare's installer owns the install (with
+ * --execute); without it the exact commands.
+ */
 function ensureTool(run, execute, lines) {
-  if (run('command -v age-keygen').status === 0) return true;
+  if (hasKeygen(run)) return true;
   const install = `install age on the server (one of: ${Object.values(AGE_INSTALL).join('; ')})`;
   if (!execute) { lines.push(`dry run: age-keygen is missing on the server; --execute installs it with stack prepare's installer, or ${install}`); return false; }
   const problems = [];
   installAge(run, { note: (text) => lines.push(text), bad: (text) => problems.push(text) });
-  if (problems.length || run('command -v age-keygen').status !== 0)
+  if (problems.length || !hasKeygen(run))
     throw refusal('STACK_SERVER_KEY_NO_AGE', `age-keygen is not on the server and could not be installed (${problems.join('; ') || 'still missing'}): ${install}`);
   return true;
 }

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

@@ -53,6 +53,6 @@ jobs:
           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 '"'"'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"'
+          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"

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

@@ -53,6 +53,6 @@ jobs:
           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 '"'"'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"'
+          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"