@hiveku-apps/sync 0.5.4 → 0.5.6

package/README.md

@@ -11,8 +11,8 @@ Local sync CLI for a Hiveku account. Pairs with the Hiveku MCP server at
    (id, name, type, domain, owner, version, updated_at).
    It also writes the account memory (see "Account memory" below) to
    `hiveku-data/account/ACCOUNT_MEMORY.md`, read-only, and brings the folder
-   layout and memory rules in `CLAUDE.md` up to date (see "CLAUDE.md stays
-   current" below).
+   layout, the memory rules and the plan rules in `CLAUDE.md` up to date (see
+   "CLAUDE.md stays current" below).
 
 The goal: open one folder per Hiveku tenant in VS Code with Claude Code,
 with the account's memory mirrored as local `.md` files Claude can read
@@ -130,8 +130,8 @@ Pass `--trust` to pre-trust the folder in `~/.codex/config.toml` (so Codex loads
 the repo config without its first-run trust prompt).
 
 **Approvals.** Codex asks first only for a **fixed list** of high-risk Hiveku
-tools: the 246 names in `src/codex-prompt-tools.json`, the same list as the
-Hiveku Codex plugin 0.1.16. It includes `deploy_site`, `site_delete`,
+tools: the 278 names in `src/codex-prompt-tools.json`, the same list as the
+Hiveku Codex plugin 0.3.13. It includes `deploy_site`, `site_delete`,
 `project_files_bulk_save` and every `hiveku_batch`, and it is written as
 `[mcp_servers.hiveku.tools.<tool>] approval_mode = "prompt"`. **Every other tool
 on the `hiveku` server runs without asking** (`default_tools_approval_mode =
@@ -160,6 +160,15 @@ The folder has to carry the list itself: Codex uses the folder's
 `[mcp_servers.hiveku]` instead of the plugin's, including for approvals, so the
 plugin's prompts do not apply here.
 
+**Revealing values.** Because `project_secrets_reveal` and `hiveku_batch` ask
+first here, the block also sends the header `X-Hiveku-Client =
+"hiveku-sync/<version>"`: the declaration that this folder asks a person before
+a reveal. Hiveku then lets a reveal through after your Codex prompt instead of
+also asking for a dashboard approval (a reveal inside `hiveku_batch` still gets
+the dashboard approval). When your own table for either of those two tools wins
+over the block, the block sends the plain `codex` label instead, and every
+reveal takes the dashboard approval.
+
 Headless and bypass modes:
 
 - **`codex exec` never stops to ask.** Under a `read-only` or `workspace-write`
@@ -253,7 +262,7 @@ Your site, unless the tier is bound to the branch.
 
 ```bash
 hiveku-sync deploy <development|staging|production> [<slug>] [--wait]
-hiveku-sync pull-env [<slug>] [--target development|staging|production]
+hiveku-sync pull-env [<slug>] [--target development|staging|production] [--yes] [--no-wait] [--approval-token <token>]
 ```
 
 ## Versions
@@ -295,9 +304,16 @@ their own version first, and never publishes: run `hiveku-sync deploy` after
 it when the live site should match. Images, fonts and videos in the shared
 asset store, the database, CMS entries and secrets are not part of versions.
 
-`pull-env` applies the same `_DEV` / `_PROD` / `_STAGING` suffix resolution the
-preview machine uses: for `development` it strips `_DEV` to the base key and
-skips `_PROD`/`_STAGING`; `--target production` does the inverse.
+`pull-env` writes the values one tier runs with, through
+`project_secrets_reveal`, as Hiveku resolves them (`FOO_PROD` over `FOO` for
+production, `FOO_DEV` for development). A person approves every pull: it prints
+the approval link, then waits up to 10 minutes, asking again every 5 seconds
+(`--no-wait` stops after the link, and `--approval-token <token>` resumes the
+wait). Development goes to `.env.local`; `--target staging` to
+`.env.staging.local`; `--target production` to `.env.production.local`, and only
+with `--yes`. The file is mode 0600, git-ignored, and written only when a value
+came back. Sensitive (write-only) variables and platform credentials never come
+back; their names are listed in the file as comments with the reason.
 
 ## Safety
 
@@ -331,7 +347,8 @@ region `hiveku-sync codex` rewrites.
 ## CLAUDE.md stays current
 
 `init` writes `CLAUDE.md` once, and the rest of the file is yours from then on,
-except its "Folder layout" and "Memory writes" sections. They sit between
+except its "Folder layout", "Memory writes" and "Your plan and its limits"
+sections. They sit between
 `<!-- hiveku:memory:begin -->` and `<!-- hiveku:memory:end -->`, and `pull` (and
 `codex`) bring them up to date, so a folder an older release made stops teaching
 the old layout and the old `memory_update` call:
@@ -347,6 +364,12 @@ The kept-current part also states that Hiveku Memory is the source of truth,
 in the Hiveku MCP server's own words, and that the local files are a mirror
 memory wins over. `AGENTS.md` says the same.
 
+Since 0.5.6 it also carries the account's plan and its limits, in the words
+Hiveku writes once for every agent (copied byte for byte and pinned by
+sha256): call `account_usage_get` before work the plan counts, and a tool
+answer with `limit_kind` is the plan's answer, not a fault, so tell the person
+and never retry or report it. `AGENTS.md` carries the one-line version.
+
 A `CLAUDE.md` that is read-only, a link to another file, or whose markers are not
 there once each and in order is left alone (`pull` says so). `pull` never creates
 a missing one.

package/bin/hiveku-sync.mjs

@@ -40,6 +40,7 @@ export function parseFlags(argv) {
     'confirm',
     'fingerprint',
     'limit',
+    'approval-token',
   ]);
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -130,10 +131,14 @@ Ship a project (the agent-native deploy loop):
                                       and version ARE saved, the deploy failed.
   deploy <env> [<slug>] [--wait]    Deploy to development | staging | production and
                                     (with --wait) poll to a terminal status.
-  pull-env [<slug>]                 Write project secrets → .env.local (git-ignored),
-           [--target <env>]           with the same _DEV/_PROD/_STAGING resolution the
-                                      preview uses. --target staging|production for the
-                                      other tiers.
+  pull-env [<slug>]                 Write one tier's values → .env.local (git-ignored,
+           [--target <env>] [--yes]   mode 0600, values never printed) through the
+           [--approval-token <t>]     reveal: a person approves on the link it prints,
+           [--no-wait]                and it waits up to 10 minutes. --target staging
+                                      writes .env.staging.local; --target production
+                                      writes .env.production.local and needs --yes.
+                                      --no-wait stops after the link (exit 3);
+                                      --approval-token resumes that wait.
 
 Versions (Your site = the project's main source; rollback never publishes):
   commit [<slug>] [-m "<name>"]     Save what is on Hiveku and not yet in a version as
@@ -401,11 +406,16 @@ async function main() {
       break;
     }
     case 'pull-env': {
-      await runPullEnv({
-        slug: positional[0],
-        profile: flags['profile'],
-        target: typeof flags['target'] === 'string' ? flags['target'] : 'development',
-      });
+      setExitCode(
+        await runPullEnv({
+          slug: positional[0],
+          profile: flags['profile'],
+          target: typeof flags['target'] === 'string' ? flags['target'] : 'development',
+          yes: flags['yes'] === true,
+          approvalToken: typeof flags['approval-token'] === 'string' ? flags['approval-token'] : undefined,
+          wait: flags['no-wait'] !== true,
+        }),
+      );
       break;
     }
     case 'commit': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiveku-apps/sync",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Sync a Hiveku account's memory/rules/skills + coder projects into a local folder, and ship projects (push/deploy/pull-env) from the terminal. Pairs with the Hiveku MCP at core.hiveku.com/mcp so Claude Code can drive Hiveku tools per-folder.",
   "type": "module",
   "license": "MIT",

package/src/claude-md.mjs

@@ -2,7 +2,8 @@
  * The part of an account folder's CLAUDE.md that hiveku-sync keeps current:
  * the folder layout and the memory-write rules, between two markers. Since
  * 2026-10-03 it also states that Hiveku Memory is the source of truth (the MCP
- * server's words) and that the local files are a mirror memory wins over.
+ * server's words) and that the local files are a mirror memory wins over, and
+ * since 0.5.6 the account's plan and its limits (the builder's words, pinned).
  *
  * `init` writes CLAUDE.md once. Everything outside the markers is the user's
  * from then on, but the layout and the memory rules change with releases
@@ -55,6 +56,42 @@ export const WORK_LOG_LINE =
   "Hiveku records this session's Doing at its first change and its Done when the session goes quiet " +
   'or ends. When the work ends, send a Done with `memory_log_add` and a one-line summary of what you ' +
   'did, if you want the log to say more than the count of changes; leave `thread` out.';
+
+/**
+ * What every agent is told about the account's plan and its limits, written once
+ * in the builder (hiveku_builder src/lib/platform-guide/plan-usage.ts, builder
+ * #1332, served with no key at /api/public/platform-guide/plan-usage) and copied
+ * here byte for byte, as the MCP server, the agent servers, the Claude Code and
+ * Codex plugins and the VS Code extension copy it. test/claude-md.test.mjs pins
+ * both texts to the builder's sha256, so a change there is a change here, made on
+ * purpose. Never reword them.
+ *
+ * PLAN_USAGE_RULES, the full block, is the kept-current part's "Your plan and its
+ * limits" section, so `pull` brings it to folders an earlier release made.
+ */
+export const PLAN_USAGE_RULES = `Hiveku rules: the account's plan and its limits
+- Every paid plan (Starter, Standard, Premium) opens every feature except the Outbound add-on. Plans differ in how much of each thing they include.
+- Before work that adds something the plan counts (a contact import, a marketing send, phone numbers, social profiles, ad campaigns, websites, automations, databases, AI images or video), call account_usage_get and tell the person what the plan includes, what is used and what happens past the number.
+- A tool answer with limit_kind is not a fault: nothing was done. Never retry it unchanged, never look for a way around it, and never report it as a Hiveku problem. Tell the person in one or two calm sentences what waits and why (the answer's message), and do what its hint says.
+- When limit_kind is plan_limit, not_on_plan or ai_credits, also say when it starts again (resets_at, if any), and the next plan with its number and price (next_plan, next_limit, plans). An owner or admin can upgrade in Settings > Billing (billing_url). When try_next_plan.available is true, they can instead try the next plan free for 14 days, once (try_next_plan.how says where). For billing, add_on, setup and spend_cap, say only what the message and the hint say.
+- Where past is billed, going past the number costs money (rate, up to ceiling): say what it costs before you go past it.
+- Take every number, price and date from account_usage_get or the answer itself, never from memory. Never change the plan, start a try or buy credits or add-ons: an owner or admin does that (billing_url, try_next_plan.how and features.outbound.how say where).
+- Say this only to the account's own people, never to a customer or caller.`;
+
+/**
+ * The builder's PLAN_LIMIT_LINE (same source and pins as PLAN_USAGE_RULES): one
+ * line for AGENTS.md's "Hiveku itself in your way?" item, right after the
+ * memory_write_refused sentence (codex.mjs), so a tool refused at the plan's
+ * number is told to the person and never retried or reported.
+ */
+export const PLAN_LIMIT_LINE =
+  "A tool answer with limit_kind (a plan's number reached, something the plan does not include, AI " +
+  "credits used up, billing that needs attention, an add-on or phones not set up, a chat's spending " +
+  'limit reached) is not a fault: nothing was done. Never retry it unchanged or report it; tell the ' +
+  'person its message and do what its hint says. Only for plan_limit, not_on_plan and ai_credits, also ' +
+  'say when it starts again and the next plan and its number, using account_usage_get or the answer for ' +
+  'every number, and point an owner or admin to its billing_url.';
+
 export const CLAUDE_MD_END = '<!-- hiveku:memory:end -->';
 
 /** The kept-current part: the markers and the two sections between them. */
@@ -62,8 +99,9 @@ export function claudeMdMemoryRegion() {
   return `${CLAUDE_MD_BEGIN}
 ## Folder layout
 
-\`hiveku-sync pull\` keeps this section and "Memory writes" below current. Where
-anything else in this file disagrees with them, follow these two sections.
+\`hiveku-sync pull\` keeps this section, "Memory writes" and "Your plan and its
+limits" below current. Where anything else in this file disagrees with them,
+follow these three sections.
 
 ${SOURCE_OF_TRUTH_LINE}
 ${WORK_LOG_LINE}
@@ -143,6 +181,10 @@ keeps or removes it), and tell the user that owners and admins edit it on the
 Hiveku dashboard under Account memory.
 
 Then run \`hiveku-sync pull\` to refresh the local copies.
+
+## Your plan and its limits
+
+${PLAN_USAGE_RULES}
 ${CLAUDE_MD_END}`;
 }
 

package/src/codex-prompt-tools.json

@@ -1,5 +1,5 @@
 {
-  "source": "locus2012/hiveku-codex-plugin main (5ed2e1a, 0.3.11), plugins/hiveku/.mcp.json: every hiveku.tools entry with approval_mode \"prompt\" (project_vcs_rollback included)",
+  "source": "locus2012/hiveku-codex-plugin feature/secrets-b3-declare-client (4f9d569, 0.3.14), plugins/hiveku/.mcp.json: every hiveku.tools entry with approval_mode \"prompt\" (project_vcs_rollback included)",
   "why": "hiveku-sync writes its own [mcp_servers.hiveku] into a Codex folder. Codex then uses that entry, not the plugin's, for the server's connection and for every tool's approval mode, so these prompts must be written here too. Refresh this list whenever the Codex plugin's prompt list changes.",
   "tools": [
     "deploy_site",
@@ -23,6 +23,12 @@
     "project_secrets_delete",
     "project_secrets_apply_to_preview",
     "project_secrets_reveal",
+    "project_secrets_replace",
+    "project_secrets_mark_sensitive",
+    "project_ab_test_create",
+    "project_ab_test_update",
+    "project_ab_test_action",
+    "project_ab_test_delete",
     "hiveku_batch",
     "project_checkpoint_restore",
     "checkpoint_restore",

package/src/codex.mjs

@@ -45,7 +45,7 @@ import { formatKey, readTomlDeclarations } from './toml.mjs';
 import { loadDotenv, safeSlug } from './util.mjs';
 import { ownerFolder } from './knowledge-files.mjs';
 import { SHARED_OWNER, ownerLabel, ownerOrder } from './memory-owner.mjs';
-import { SOURCE_OF_TRUTH_LINE, WORK_LOG_LINE } from './claude-md.mjs';
+import { PLAN_LIMIT_LINE, SOURCE_OF_TRUTH_LINE, WORK_LOG_LINE } from './claude-md.mjs';
 
 /**
  * The FIXED list of high-risk Hiveku tools that Codex asks about before
@@ -95,6 +95,35 @@ export const CODEX_PROMPT_TOOLS = [
   ...new Set(JSON.parse(readFileSync(new URL('./codex-prompt-tools.json', import.meta.url), 'utf8')).tools),
 ];
 
+/** This package's version, as published (package.json ships in every npm package). */
+export const SYNC_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+/**
+ * X-Hiveku-Client for the folder's [mcp_servers.hiveku]: `hiveku-sync/<version>`,
+ * the declaration that this config asks a person before project_secrets_reveal
+ * (plan "Server-side approval"; the builder's src/lib/secrets/reveal-client.ts).
+ * The MCP server forwards it to the builder, which lets a release at or above
+ * its listed minimum skip the dashboard approval for a reveal Codex prompted
+ * for. Set here, never by the model.
+ *
+ * True only while the block itself writes the prompt for the reveal and for
+ * hiveku_batch (which can carry a reveal): when the folder's own config
+ * declares either table, the user's setting wins (userTables) and may not ask,
+ * so the block sends the plain `codex` label instead. The MCP server reads
+ * both as Codex for its memory-log label and rate-limit bucket. The CLI's own
+ * calls (pull-env included) send no X-Hiveku-Client at all, so a reveal they
+ * make takes the dashboard approval.
+ */
+export const DECLARED_CLIENT = `hiveku-sync/${SYNC_VERSION}`;
+const DECLARATION_NEEDS_PROMPTS = ['project_secrets_reveal', 'hiveku_batch'];
+
+/** The X-Hiveku-Client value for a block that leaves out the user's own tables. */
+export function codexClientHeader(userTables = []) {
+  const skip = new Set(userTables);
+  const asks = DECLARATION_NEEDS_PROMPTS.every((tool) => CODEX_PROMPT_TOOLS.includes(tool) && !skip.has(tool));
+  return asks ? DECLARED_CLIENT : 'codex';
+}
+
 /** A TOML bare key when the name allows it, a quoted key otherwise. */
 function tomlKey(name) {
   return /^[A-Za-z0-9_-]+$/.test(name) ? name : JSON.stringify(name);
@@ -183,6 +212,7 @@ ${digest}
 - **Hiveku itself in your way?** A Hiveku tool still failing after one sensible retry → \`hiveku_report_issue\`;
   a capability no tool offers (search \`hiveku_docs_search\` first) → \`hiveku_request_feature\`. No secrets or personal data.
   A memory write refused with \`memory_write_refused\` is not a failure: show the person its message and link, follow its hint, and never retry it unchanged or report it.
+  ${PLAN_LIMIT_LINE}
 - **Tell the user only if it changes what they get:** one or two calm sentences — flagged to the Hiveku team (give the
   ref), the team is quick to fix these, you'll let them know when it's sorted. No error codes, blame or promised times.
 - Video generation is paid + capped — \`marketing_generate_video\` with \`dry_run: true\` first.
@@ -309,14 +339,16 @@ function codexTomlRegion({ baseUrl, profile, apiKey, userTables = [] }) {
   // MCP server (Codex config reference, "mcp_servers.<id>.http_headers"; the
   // docs' example is `http_headers = { "X-Figma-Region" = "us-east-1" }`, next
   // to bearer_token_env_var). TOML allows the key once per table, so the
-  // client label rides in the same inline table as an inlined key.
-  // X-Hiveku-Client: codex is what the MCP server's memory log shows as
-  // "via Codex"; it is a label, never authentication. The key and the URL come
-  // from .env, so they are escaped: a quote in either would otherwise end the
-  // string early and leave the block itself unreadable.
+  // client header rides in the same inline table as an inlined key.
+  // X-Hiveku-Client is hiveku-sync/<version> (codexClientHeader): the
+  // declaration that this block asks before a reveal, which the MCP server's
+  // memory log still shows as "via Codex"; it is never authentication. The key
+  // and the URL come from .env, so they are escaped: a quote in either would
+  // otherwise end the string early and leave the block itself unreadable.
+  const client = tomlString(codexClientHeader(userTables));
   const auth = apiKey
-    ? `http_headers = { "Authorization" = ${tomlString(`Bearer ${apiKey}`)}, "X-Hiveku-Client" = "codex" }`
-    : `bearer_token_env_var = "OLYMPUS_API_KEY"\nhttp_headers = { "X-Hiveku-Client" = "codex" }`;
+    ? `http_headers = { "Authorization" = ${tomlString(`Bearer ${apiKey}`)}, "X-Hiveku-Client" = ${client} }`
+    : `bearer_token_env_var = "OLYMPUS_API_KEY"\nhttp_headers = { "X-Hiveku-Client" = ${client} }`;
   // default_tools_approval_mode = "approve": this folder exists so the agent
   // can operate the account — per-call approval prompts would also cancel
   // every tool call in headless `codex exec` (CI/cron, this lane's core use)

package/src/envPull.mjs

@@ -0,0 +1,311 @@
+/**
+ * `hiveku-sync pull-env`: one tier of a project's variables into a local env
+ * file, through project_secrets_reveal (plan B3), never project_secrets_list.
+ *
+ * The same flow and file rules as the Claude Code plugin's `hiveku env pull`
+ * (hiveku-claude-plugin lib/env-pull.mjs): keep the two in step.
+ *
+ * WHY THE REVEAL. Agents read secret values only for non-sensitive keys,
+ * through a reveal that asks every time and is logged (Abe, 2026-10-06).
+ * project_secrets_list stops returning values at the cutover (it answers
+ * values_moved without metadata_only); the reveal returns the values the tier
+ * runs with, resolved by the server (FOO_PROD over FOO, the deploy's own
+ * precedence), never a sensitive key and never a platform credential.
+ *
+ * WHO APPROVES. This CLI's own MCP client sends no X-Hiveku-Client, so it does
+ * not declare that it asked anyone (the Codex config this package writes does,
+ * codex.mjs DECLARED_CLIENT, because Codex prompts there). Every pull takes
+ * the dashboard approval: the CLI prints the approval link, then repeats the
+ * same call with the token every 5 seconds for up to 10 minutes. A poll while
+ * nobody has decided does not spend the project's reveals.
+ *
+ * THE FILE: written only when a value came back (an empty answer never
+ * replaces an existing file); mode 0600 even over an existing file; values
+ * encoded so dotenv + dotenv-expand (Next.js, Vite, Expo) read them back
+ * exactly; withheld names as one-line comments with their reasons. Only names
+ * reach the terminal.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const REVEAL_TOOL = 'project_secrets_reveal';
+
+/** How often the CLI asks again while a person decides, and for how long. */
+export const APPROVAL_POLL_MS = 5_000;
+export const APPROVAL_WAIT_MS = 10 * 60_000;
+/** Polls that fail in a row (network, 5xx) before the wait gives up. */
+const MAX_POLL_FAILURES = 3;
+
+const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const TOKEN_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export class EnvPullError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'EnvPullError';
+    this.code = code;
+  }
+}
+
+/** Which file a tier's values go to (Next.js loads .env.production.local only for production builds). */
+export function envFileForTier(tier) {
+  if (tier === 'production') return '.env.production.local';
+  if (tier === 'staging') return '.env.staging.local';
+  return '.env.local';
+}
+
+/** An approval token from the command line: refused unless it has the token's shape. */
+export function approvalTokenFrom(raw) {
+  if (raw === undefined) return undefined;
+  const token = String(raw).trim();
+  if (!TOKEN_RE.test(token)) throw new EnvPullError('bad_token', 'That is not an approval token. Use the token the first run printed.');
+  return token;
+}
+
+/** One line of server text for a comment or the terminal: no line breaks or control characters. */
+function oneLine(text, max = 300) {
+  return String(text ?? '')
+    .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, max);
+}
+
+function asObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+
+/**
+ * What one tools/call of project_secrets_reveal answered:
+ *   { kind: 'values', values, withheld, notApproved, tier }
+ *   { kind: 'approval_required', approval, withheld }
+ *   { kind: 'pending' }
+ *   { kind: 'refused', code, message }
+ * The MCP proxy returns a builder error as a tool result
+ * { error, status, details: { code, message } }, with isError set.
+ */
+export function readRevealAnswer(res) {
+  if (res?.error) {
+    return { kind: 'refused', code: 'rpc_error', message: oneLine(res.error.message || 'The Hiveku server refused the call.') };
+  }
+  const text = res?.result?.content?.[0]?.text;
+  let body = null;
+  try {
+    body = typeof text === 'string' ? JSON.parse(text) : null;
+  } catch {
+    body = null;
+  }
+  body = asObject(body);
+  if (!body) return { kind: 'refused', code: 'unreadable_answer', message: 'The reveal answered with something that is not JSON.' };
+
+  const failed = res?.result?.isError === true || (typeof body.error === 'string' && typeof body.status === 'number' && body.status >= 400);
+  if (failed) {
+    const details = asObject(body.details) ?? body;
+    const code = String(details.code || body.code || details.error || body.error || 'refused');
+    if (code === 'approval_pending') return { kind: 'pending' };
+    return { kind: 'refused', code, message: oneLine(details.message || body.message || body.error || 'The reveal was refused.') };
+  }
+
+  const data = asObject(body.data) && !('values' in body) && !('code' in body) ? body.data : body;
+  const withheld = Array.isArray(data.withheld) ? data.withheld.filter((w) => asObject(w) && typeof w.key === 'string') : [];
+  if (data.code === 'approval_required') {
+    const approval = asObject(data.approval);
+    // The link and the token are printed for the person, so both must be plain: an https link with
+    // no spaces or control characters, and a token of the token's own shape.
+    if (!approval || !TOKEN_RE.test(String(approval.token)) || !/^https:\/\/[^\s\u0000-\u001f\u007f]+$/.test(String(approval.approve_url))) {
+      return { kind: 'refused', code: 'unexpected_answer', message: 'The reveal asked for an approval without a usable link.' };
+    }
+    return { kind: 'approval_required', approval, withheld };
+  }
+  const values = asObject(data.values);
+  if (values) {
+    const clean = {};
+    for (const [key, value] of Object.entries(values)) if (typeof value === 'string') clean[key] = value;
+    const notApproved = Array.isArray(data.not_approved) ? data.not_approved.filter((k) => typeof k === 'string') : [];
+    return { kind: 'values', values: clean, withheld, notApproved, tier: data.tier };
+  }
+  return { kind: 'refused', code: 'unexpected_answer', message: 'The reveal answered in a shape this version does not read. Update hiveku-sync.' };
+}
+
+/** A refusal as one sentence for the terminal. */
+function refusalText(answer) {
+  const byCode = {
+    approval_declined: 'A person declined the request. Nothing was written.',
+    approval_used: 'That approval was already used. Run pull-env again to ask once more.',
+    approval_unknown: 'That approval is unknown or its 10 minutes ran out. Run pull-env again to ask once more.',
+    approval_mismatch: 'That approval was for another tier or another key. Run pull-env again without --approval-token.',
+    reveal_rate_limited: 'This site\'s values were revealed 20 times in the last hour, the most allowed. Try again later.',
+    reveal_requests_rate_limited: '20 approvals were asked for this site in the last hour, the most allowed. Try again later.',
+    scope_denied: 'This folder\'s key is read-only, and revealing values needs a full key.',
+  };
+  return byCode[answer.code] || `${answer.message || 'The reveal was refused.'} (${answer.code})`;
+}
+
+/**
+ * Reveal one tier's values, waiting for a person's approval when the server
+ * asks for one. `call(args)` sends one project_secrets_reveal and returns the
+ * JSON-RPC answer. With `approvalToken` it resumes a wait a first run started
+ * (no new request is made). `onApprovalRequired(approval)` is told the link
+ * once, before the wait; with `wait: false` the pull stops there and throws
+ * approval_waiting (the token is in the error's `approval`).
+ */
+export async function revealTier({
+  call,
+  projectId,
+  tier,
+  approvalToken,
+  wait = true,
+  onApprovalRequired,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  now = () => Date.now(),
+  pollMs = APPROVAL_POLL_MS,
+  waitMs = APPROVAL_WAIT_MS,
+}) {
+  const args = { project_id: projectId, tier };
+  let answer;
+  let token = approvalToken;
+  if (token) {
+    answer = readRevealAnswer(await call({ ...args, approval_token: token }));
+  } else {
+    answer = readRevealAnswer(await call(args));
+    if (answer.kind === 'approval_required') {
+      token = answer.approval.token;
+      await onApprovalRequired?.(answer.approval, answer.withheld);
+      if (!wait) {
+        const err = new EnvPullError('approval_waiting', 'Waiting for a person to approve. Run pull-env again with --approval-token once they have.');
+        err.approval = answer.approval;
+        throw err;
+      }
+      answer = { kind: 'pending' };
+    }
+  }
+  if (answer.kind === 'pending') {
+    // Only a call that carries a token can be pending; without one, a repeat would
+    // ask a person again on every poll.
+    if (!token) throw new EnvPullError('unexpected_answer', 'The reveal said it is waiting for an approval it never asked for. Pull again.');
+    const deadline = now() + waitMs;
+    let failures = 0;
+    while (answer.kind === 'pending') {
+      if (now() >= deadline) {
+        throw new EnvPullError('approval_timeout', 'Nobody approved within 10 minutes, so nothing was written. Run pull-env again to ask once more.');
+      }
+      await sleep(pollMs);
+      try {
+        answer = readRevealAnswer(await call({ ...args, approval_token: token }));
+        failures = 0;
+      } catch (err) {
+        failures += 1;
+        if (failures >= MAX_POLL_FAILURES) throw err;
+        answer = { kind: 'pending' };
+      }
+    }
+  }
+  if (answer.kind === 'values') return answer;
+  if (answer.kind === 'approval_required') {
+    throw new EnvPullError('unexpected_answer', 'The reveal asked for a new approval in the middle of a wait. Run pull-env again.');
+  }
+  throw new EnvPullError(answer.code || 'refused', refusalText(answer));
+}
+
+/**
+ * A value in the form the dotenv loaders read back exactly (dotenv parse plus
+ * dotenv-expand, as Next.js 15, Vite and Expo load .env files), or null when
+ * no form does:
+ *   - nothing to quote or expand: written bare;
+ *   - otherwise in single quotes, which dotenv keeps literally (line breaks
+ *     included), with every `$` written `\$` so it is not expanded into
+ *     another variable;
+ *   - a value with a single quote goes in backticks the same way;
+ *   - null for a value with both, with a carriage return or NUL (dotenv turns
+ *     CR into LF), or ending in a backslash (dotenv reads `\'` as a quote
+ *     inside the value and runs on to the next line).
+ */
+export function encodeEnvValue(value) {
+  const v = String(value);
+  if (v === '') return '';
+  if (/[\r\0]/.test(v) || v.endsWith('\\')) return null;
+  if (/^[A-Za-z0-9_\-.,:/@+%~^=]+$/.test(v)) return v;
+  const escaped = v.replace(/\$/g, '\\$');
+  if (!v.includes("'")) return `'${escaped}'`;
+  if (!v.includes('`')) return `\`${escaped}\``;
+  return null;
+}
+
+/**
+ * The env file's text: the values, sorted, then what was not included and
+ * why, as comments. Returns the names written and the names left out.
+ */
+export function renderEnvFile({ values, withheld = [], notApproved = [], tier, file }) {
+  const written = [];
+  const unwritable = [];
+  const lines = [
+    `# Written by \`hiveku-sync pull-env\` from Hiveku: this site's ${tier} values, revealed with a person's approval.`,
+    `# ${file} holds real values: keep it out of git and never paste it anywhere.`,
+  ];
+  for (const key of Object.keys(values).sort()) {
+    if (!KEY_RE.test(key)) {
+      unwritable.push({ key: oneLine(key, 80), why: 'not a variable name a .env file can hold' });
+      continue;
+    }
+    const encoded = encodeEnvValue(values[key]);
+    if (encoded === null) {
+      unwritable.push({ key, why: 'its value cannot be written to a .env file exactly (set it by hand)' });
+      continue;
+    }
+    lines.push(`${key}=${encoded}`);
+    written.push(key);
+  }
+  const notes = [
+    ...withheld.map((w) => ({ key: oneLine(w.key, 80), why: oneLine(w.why || w.reason || 'withheld') })),
+    ...notApproved.map((key) => ({ key: oneLine(key, 80), why: 'added after the person approved; pull again to include it' })),
+    ...unwritable,
+  ];
+  if (notes.length) {
+    lines.push('', '# Not included (their values are never shown; set them by hand if local dev needs them):');
+    for (const note of notes) lines.push(`# ${note.key}: ${note.why}`);
+  }
+  lines.push('');
+  return { text: lines.join('\n'), written, notes };
+}
+
+/**
+ * Write `text` to `target` with mode 0600, also over an existing file: a new
+ * file is created 0600 beside it and renamed over it.
+ */
+export async function writeEnvFileSecure(target, text) {
+  const dir = path.dirname(target);
+  const temp = path.join(dir, `.${path.basename(target)}.${randomUUID()}.tmp`);
+  const handle = await fs.open(temp, 'wx', 0o600);
+  try {
+    await handle.writeFile(text, 'utf8');
+    await handle.chmod(0o600);
+  } finally {
+    await handle.close();
+  }
+  try {
+    await fs.rename(temp, target);
+  } catch (err) {
+    await fs.unlink(temp).catch(() => {});
+    throw err;
+  }
+}
+
+/** Add `file` to the folder's .gitignore unless a line there already covers it. */
+export async function ensureGitignored(dir, file) {
+  const gi = path.join(dir, '.gitignore');
+  let text = '';
+  try {
+    text = await fs.readFile(gi, 'utf8');
+  } catch {
+    /* no .gitignore yet */
+  }
+  const covered = text.split(/\r?\n/).some((line) => {
+    const rule = line.trim();
+    return rule === file || rule === `/${file}` || rule === '.env*' || rule === '*.local' || rule === '.env*.local';
+  });
+  if (covered) return false;
+  const prefix = text && !text.endsWith('\n') ? '\n' : '';
+  await fs.writeFile(gi, `${text}${prefix}${file}\n`, 'utf8');
+  return true;
+}

package/src/mcp.mjs

@@ -68,6 +68,16 @@ export class HivekuMcpClient {
     return result;
   }
 
+  /**
+   * The tools/call result as it came, a tool error (isError) included, for a
+   * caller that reads the error's code itself: pull-env waits on
+   * approval_pending, which arrives as a tool error. A JSON-RPC error or an
+   * HTTP failure still throws.
+   */
+  async callToolResult(name, args = {}) {
+    return this._request('tools/call', { name, arguments: args });
+  }
+
   async callTool(name, args = {}) {
     const result = await this._request('tools/call', { name, arguments: args });
     if (result?.isError) {

package/src/push.mjs

@@ -10,8 +10,9 @@
  *             batched, per-batch-verified project_files_bulk_save. This is what
  *             deploy_site actually reads — NOT project_commit's GitHub branch.
  *   deploy    deploy_site + poll deploy_get to a terminal status (--wait).
- *   pull-env  project_secrets_list → .env.local with the same _DEV/_PROD/
- *             _STAGING resolution the preview machine uses.
+ *   pull-env  project_secrets_reveal → .env.local (or .env.staging.local /
+ *             .env.production.local): the values the tier runs with, after a
+ *             person approves (src/envPull.mjs).
  *
  * After a push whose files all landed, push saves them as ONE version of Your
  * site (or of the branch it pushed to): project_vcs_commit with NO files and
@@ -41,7 +42,16 @@ import {
   readProjectsManifest,
   writeProjectsManifest,
 } from './projects.mjs';
-import { writeFileAtomic, readEnv, loadDotenv } from './util.mjs';
+import {
+  EnvPullError,
+  REVEAL_TOOL,
+  approvalTokenFrom,
+  ensureGitignored,
+  envFileForTier,
+  renderEnvFile,
+  revealTier,
+  writeEnvFileSecure,
+} from './envPull.mjs';
 import {
   branchLabel,
   checkedVersionName,
@@ -674,106 +684,82 @@ export async function runDeploy({ slugOrId, environment, wait = false, profile,
 
 // ── pull-env ──────────────────────────────────────────────────────────────
 
-// Resolution mirrors the preview machine (project_secrets_set): _DEV wins for
-// development and is stripped to its base key; _PROD/_PRODUCTION are for
-// production, _STAGING for staging. Suffixes for OTHER tiers are skipped.
-const TIER_SUFFIX = {
-  development: ['_DEV'],
-  staging: ['_STAGING'],
-  production: ['_PROD', '_PRODUCTION'],
-};
-const ALL_SUFFIXES = ['_DEV', '_STAGING', '_PROD', '_PRODUCTION'];
-
-export function resolveSecretsForTier(secrets, tier) {
-  const want = TIER_SUFFIX[tier] || TIER_SUFFIX.development;
-  const base = {};
-  const overrides = {};
-  for (const [key, value] of Object.entries(secrets || {})) {
-    const suffix = ALL_SUFFIXES.find((s) => key.endsWith(s));
-    if (!suffix) {
-      base[key] = value;
-      continue;
-    }
-    if (want.includes(suffix)) {
-      overrides[key.slice(0, -suffix.length)] = value; // strip suffix → base name
-    }
-    // suffix for another tier → skip
-  }
-  return { ...base, ...overrides }; // tier override wins over the base key
-}
-
-function envFileForTier(tier) {
-  if (tier === 'production') return '.env.production.local';
-  if (tier === 'staging') return '.env.staging.local';
-  return '.env.local';
-}
-
-export function serializeEnv(map) {
-  const lines = [
-    '# Generated by `hiveku-sync pull-env` from Hiveku project secrets.',
-    '# Do NOT commit — this file is git-ignored.',
-    '',
-  ];
-  for (const key of Object.keys(map).sort()) {
-    let v = String(map[key] ?? '');
-    // Quote if it contains whitespace, #, quotes, or newlines.
-    if (/[\s#'"\n]/.test(v)) {
-      v = `"${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`;
-    }
-    lines.push(`${key}=${v}`);
-  }
-  return lines.join('\n') + '\n';
-}
-
-export async function runPullEnv({ slug, profile, target = 'development' } = {}) {
+/**
+ * `hiveku-sync pull-env [<slug>] [--target <tier>] [--yes]`: one tier's values
+ * into a local env file, through project_secrets_reveal (src/envPull.mjs),
+ * never project_secrets_list. The server resolves the tier (FOO_PROD over FOO,
+ * the dev/staging fallback), so nothing is resolved here.
+ *
+ *   - development is the default; staging needs --target staging, and
+ *     production needs --target production AND --yes;
+ *   - a person approves on the link it prints, and it waits up to 10 minutes
+ *     (--no-wait prints the link and stops with exit 3; --approval-token
+ *     resumes that wait without asking again);
+ *   - the file is written only when a value came back, mode 0600 even over an
+ *     existing file, with the withheld names as comments; only names are
+ *     printed.
+ *
+ * Returns { written, notIncluded, path, tier }, or { exit_code } when it
+ * stopped before writing.
+ */
+export async function runPullEnv({ slug, profile, target = 'development', yes = false, approvalToken, wait = true, client: givenClient, log = console.log } = {}) {
   const tier = normalizeEnv(target);
   if (!['development', 'staging', 'production'].includes(tier)) {
     throw new Error(`Invalid --target "${target}" — use development | staging | production.`);
   }
+  if (tier === 'production' && yes !== true) {
+    throw new Error(
+      'pull-env --target production writes the values production runs with to .env.production.local. ' +
+        'Add --yes to confirm that is what you want.',
+    );
+  }
+  const token = approvalTokenFrom(approvalToken);
   const baseDir = resolveBaseDir();
-  const { client } = await clientFromCwd({ profileOverride: profile });
-  const { slug: resolvedSlug, info, folder } = await findProjectFolder({ slug, baseDir });
+  const client = givenClient ?? (await clientFromCwd({ profileOverride: profile })).client;
+  const { slug: resolvedSlug, folder, info } = await findProjectFolder({ slug, baseDir });
   const projectId = info.project_id;
+  const file = envFileForTier(tier);
 
-  const res = (await client.callToolJson('project_secrets_list', { project_id: projectId })).data;
-  const secrets = res?.secrets || {};
-  // Variables marked sensitive are write-only on the platform: the server OMITS them
-  // from `secrets` and lists their names here. Without saying so, the .env file below
-  // would be silently incomplete and the user would go debugging a phantom.
-  const sensitiveKeys = Array.isArray(res?.sensitive_keys) ? res.sensitive_keys : [];
-  const count = Object.keys(secrets).length;
-  if (count === 0 && sensitiveKeys.length === 0) {
-    console.log(`No secrets set on ${resolvedSlug}. Nothing to write.`);
-    return { written: 0 };
-  }
-
-  const resolved = resolveSecretsForTier(secrets, tier);
-  const outName = envFileForTier(tier);
-  const outPath = join(folder, outName);
-  await writeFileAtomic(outPath, serializeEnv(resolved));
-
-  // Make sure the env file is git-ignored so it never gets pushed.
-  const gitignorePath = join(folder, '.gitignore');
-  let ignore = '';
+  const call = async (args) => ({ result: await client.callToolResult(REVEAL_TOOL, args) });
+  let answer;
   try {
-    ignore = await readFile(gitignorePath, 'utf8');
-  } catch {
-    /* no .gitignore yet */
-  }
-  if (!ignore.split('\n').some((l) => l.trim() === outName)) {
-    await writeFileAtomic(
-      gitignorePath,
-      (ignore && !ignore.endsWith('\n') ? ignore + '\n' : ignore) + outName + '\n',
-    );
+    answer = await revealTier({
+      call,
+      projectId,
+      tier,
+      approvalToken: token,
+      wait,
+      onApprovalRequired: (approval) => {
+        log(`A person must approve revealing ${resolvedSlug}'s ${tier} values before ${file} is written.`);
+        log(`Approve here (anyone in the account who can see the site's variables): ${approval.approve_url}`);
+        log(
+          wait
+            ? 'Waiting up to 10 minutes for the approval...'
+            : `Then run: hiveku-sync pull-env ${resolvedSlug} --target ${tier}${tier === 'production' ? ' --yes' : ''} --approval-token ${approval.token}`,
+        );
+      },
+    });
+  } catch (err) {
+    if (err instanceof EnvPullError && err.code === 'approval_waiting') {
+      log(err.message);
+      return { written: 0, exit_code: 3, tier };
+    }
+    throw err;
   }
 
-  console.log(`Wrote ${Object.keys(resolved).length} var${Object.keys(resolved).length !== 1 ? 's' : ''} → ${outName} (tier: ${tier}, from ${count} secret${count !== 1 ? 's' : ''}).`);
-  if (sensitiveKeys.length > 0) {
-    const names = sensitiveKeys.slice().sort();
-    console.log(
-      `Skipped ${names.length} sensitive var${names.length !== 1 ? 's' : ''}: ${names.join(', ')}.`,
-    );
-    console.log('These are write-only on Hiveku and cannot be read back. Set them by hand if your local build needs them.');
+  const { text, written, notes } = renderEnvFile({ values: answer.values, withheld: answer.withheld, notApproved: answer.notApproved, tier, file });
+  const notIncluded = notes.map((n) => `${n.key} (${n.why})`);
+  if (written.length === 0) {
+    // Never an empty file over a real one (the list-based pull did exactly that).
+    log(`No ${tier} value could be revealed for ${resolvedSlug}, so ${file} was left as it was.`);
+    if (notIncluded.length) log(`Not revealed: ${notIncluded.join('; ')}`);
+    return { written: 0, notIncluded: notes.map((n) => n.key), exit_code: 1, tier };
   }
-  return { written: Object.keys(resolved).length, skippedSensitive: sensitiveKeys, path: outPath, tier };
+  const outPath = join(folder, file);
+  await writeEnvFileSecure(outPath, text);
+  // Make sure the env file is git-ignored so it never gets pushed.
+  await ensureGitignored(folder, file);
+  log(`Wrote ${written.length} ${tier} value${written.length === 1 ? '' : 's'} → ${file} (mode 0600; values not shown): ${written.join(', ')}`);
+  if (notIncluded.length) log(`Not included (set by hand if needed): ${notIncluded.join('; ')}`);
+  return { written: written.length, notIncluded: notes.map((n) => n.key), path: outPath, tier };
 }