@biznetgio/neo-app 0.4.49 → 0.4.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biznetgio/neo-app",
-  "version": "0.4.49",
+  "version": "0.4.63",
   "description": "NEO App CLI — one-command agent onboarding, MCP server, and project ops for coding agents (Codex, Claude Code).",
   "type": "module",
   "bin": {

package/src/api.js

@@ -108,6 +108,18 @@ export class NeoApi {
     return { user: me, orgs };
   }
 
+  // actingIdentity returns the signed-in account (memoized, best-effort) so confirmation /
+  // dry-run responses can show WHO/WHERE an action will run and a wrong-account deploy is
+  // obvious before it happens (JNG #131). Never throws — returns {} if identity is unavailable.
+  async actingIdentity() {
+    if (this._acting !== undefined) return this._acting;
+    try {
+      const me = (await this.get('/api/v1/auth/me')).data || {};
+      this._acting = { account: me.email || me.login || me.name || me.id, accountId: me.id };
+    } catch { this._acting = {}; }
+    return this._acting;
+  }
+
   // resolveOrgId returns the preferred org id, or the first org the user belongs to.
   async resolveOrgId(preferred) {
     if (preferred) return preferred;

package/src/deploySource.js

@@ -309,7 +309,12 @@ export async function deploySource(api, { projectId, src, name, port, build, ser
       const book = (await api.get('/api/v1/pricing')).data;
       estimatedCost = estimateCost(book, { computeTier: 'micro' });
     } catch { /* price book unavailable — skip the estimate */ }
-    return { dryRun: true, plan, service: svc, environment: targetEnv, serviceType: svcType, estimatedCost, confirmToken: token };
+    // Include the acting account/env/project so a wrong-account or wrong-environment deploy
+    // is obvious before it happens (JNG #131). Best-effort — never fail the preview on it.
+    let ident = {};
+    try { if (typeof api.actingIdentity === 'function') ident = await api.actingIdentity(); } catch { /* ignore */ }
+    const acting = { ...ident, environment: targetEnv, project: projectId };
+    return { dryRun: true, plan, service: svc, environment: targetEnv, serviceType: svcType, estimatedCost, confirmToken: token, acting };
   };
 
   // Preview path (explicit dry-run OR an unapproved real deploy). No mutation ran above,
@@ -377,7 +382,18 @@ export async function deploySource(api, { projectId, src, name, port, build, ser
   const result = await pollDeployment(api, deployId, timeout, log);
   const view = (await api.get(`/api/v1/apps/${app.id}`)).data?.application || {};
   const url = view.domain ? `https://${view.domain}` : '';
-  return { appId: app.id, url, result };
+  const out = { appId: app.id, url, result, deploymentId: deployId };
+  // On a non-success, surface the deployment id + the tail of the build log + error so the
+  // caller can see WHY it failed without triggering a second build (JNG #117).
+  if (result !== 'success' && deployId) {
+    try {
+      const d = (await api.get(`/api/v1/deployments/${deployId}`)).data || {};
+      const lines = String(d.log || '').replace(/\n$/, '').split('\n').filter((l) => l.length);
+      if (lines.length) out.buildLogTail = lines.slice(-50).join('\n');
+      if (d.error) out.error = d.error;
+    } catch { /* best-effort — the id is still returned for a manual neo_get_deployment */ }
+  }
+  return out;
 }
 
 async function pollDeployment(api, id, timeoutSec, log) {

package/src/mcp/tools.js

@@ -31,14 +31,43 @@ function result(status, data) {
 // §2 safety: a create/deploy mutation must name its environment explicitly —
 // NEVER default to production. A silent prod mutation is the exact risk the
 // handoff calls out ("Never default a missing environment to production").
-function requireEnv(env) {
+// sessionEnv pins ONE target environment (staging|production) for this MCP session so an
+// agent doesn't mix staging and production within a task (JNG #136). Seeded from
+// NEO_APP_TARGET_ENV; set at runtime with neo_set_context. null = not chosen yet.
+let sessionEnv = (() => { const e = String(process.env.NEO_APP_TARGET_ENV || '').toLowerCase(); return (e === 'staging' || e === 'production') ? e : null; })();
+
+// envStrict validates an explicit staging|production value (no fallback).
+function envStrict(env) {
   const e = String(env || '').toLowerCase();
-  if (e !== 'staging' && e !== 'production') {
-    throw new Error('environment is required and must be "staging" or "production" — it is never defaulted (handoff §2: never silently mutate production). Test on staging first.');
-  }
+  if (e !== 'staging' && e !== 'production') throw new Error('environment must be "staging" or "production"');
   return e;
 }
 
+// requireEnv resolves the target environment and enforces the one-environment-per-session
+// invariant (JNG #136): once an environment is pinned (neo_set_context or the first explicit
+// call), a later call for a DIFFERENT environment is refused unless allowCrossEnvironment is
+// set — so staging and production can't be mixed in one session. The first explicit choice
+// pins the session so subsequent calls inherit it. Never silently defaulted.
+function requireEnv(env, allowCross = false) {
+  const e = String(env || '').toLowerCase();
+  const explicit = (e === 'staging' || e === 'production') ? e : null;
+  if (sessionEnv) {
+    if (explicit && explicit !== sessionEnv && !allowCross) {
+      throw new Error(`environment_mismatch: this session is pinned to "${sessionEnv}" but the call requested "${explicit}". Staging and production must not be mixed in one session (JNG #136). Pass allowCrossEnvironment:true to allow this one call, or re-pin with neo_set_context.`);
+    }
+    return explicit || sessionEnv;
+  }
+  if (explicit) { sessionEnv = explicit; return explicit; } // pin the first explicit choice
+  throw new Error('environment_not_chosen: pin it once with neo_set_context({environment:"staging"|"production"}) (ask the user which if unclear; prefer staging), or pass environment explicitly. Never defaulted so staging and production don\'t get mixed (JNG #136).');
+}
+
+// Shared schema fragment: the per-call escape hatch for the session environment pin.
+const allowCrossEnvProp = { allowCrossEnvironment: { type: 'boolean', description: 'Override the session environment pin for THIS call only (JNG #136). A call whose environment differs from the pinned one is refused by default so staging and production are not mixed; set true to allow this one cross-environment action.' } };
+
+// resetSessionEnv clears the session pin. Exported for tests that exercise the pin
+// invariant in sequence (each must start from a clean, unpinned session).
+export function resetSessionEnv() { sessionEnv = null; }
+
 // deleteAndConverge deletes a resource, then polls its endpoint until the inventory
 // actually converges (GET → 404), so a delete isn't reported done while the record
 // still exists. Returns a durable operation reference (`del-<id>`) + convergence
@@ -59,6 +88,22 @@ async function deleteAndConverge(api, path, resourceId, kind, delQuery = '') {
   return { operationId: 'del-' + resourceId, kind, status: (data && data.status) || 'deleted', converged, convergenceChecks: checks };
 }
 
+// cpuToVcpu parses a k8s CPU quantity ("500m" → 0.5, "1"/"2" → vCPUs) for cost estimates.
+function cpuToVcpu(v) {
+  if (!v) return 0;
+  const s = String(v).trim();
+  return s.endsWith('m') ? (parseFloat(s) || 0) / 1000 : parseFloat(s) || 0;
+}
+// memToMB parses a k8s memory quantity ("512Mi"/"1Gi"/"512M"/"1G") → MB for cost estimates.
+function memToMB(v) {
+  if (!v) return 0;
+  const m = String(v).match(/([\d.]+)\s*(Gi|Mi|G|M)?/i);
+  if (!m) return 0;
+  const n = parseFloat(m[1]) || 0;
+  const u = (m[2] || 'Mi').toLowerCase();
+  return u === 'gi' || u === 'g' ? n * 1024 : n;
+}
+
 // gbFromSize parses "10Gi"/"10G"/"10" → 10 (integer GB), else undefined.
 function gbFromSize(v) {
   if (v == null) return undefined;
@@ -66,6 +111,31 @@ function gbFromSize(v) {
   return m ? parseInt(m[1], 10) : undefined;
 }
 
+// Portal-equivalent limits mirrored here so a quote rejects an invalid config BEFORE
+// showing a price (JNG #132). The server re-enforces these on create (authoritative).
+const MIN_DB_VOLUME_GB = 10;
+const MIN_BUCKET_QUOTA_GB = 10;
+const MIN_PG_MAJOR = 13;
+function validateDbArgs(args) {
+  const gb = gbFromSize(args.volumeSize);
+  if (gb !== undefined && gb < MIN_DB_VOLUME_GB) throw new Error(`volumeSize must be at least ${MIN_DB_VOLUME_GB}Gi (the portal minimum); got ${args.volumeSize}`);
+  if (args.engine === 'postgres' && args.version) {
+    const maj = parseInt(String(args.version), 10);
+    if (maj > 0 && maj < MIN_PG_MAJOR) throw new Error(`PostgreSQL ${args.version} is end-of-life; use ${MIN_PG_MAJOR} or newer`);
+  }
+}
+// actingOf returns the signed-in account merged with scope (org/project/env) for a
+// confirmation/dry-run response (JNG #131). Tolerant of an api without actingIdentity.
+async function actingOf(api, extra) {
+  let base = {};
+  try { if (typeof api.actingIdentity === 'function') base = await api.actingIdentity(); } catch { /* best-effort */ }
+  return { ...base, ...extra };
+}
+function validateBucketArgs(args) {
+  const gb = args.quotaGB;
+  if (gb != null && gb !== 0 && gb < MIN_BUCKET_QUOTA_GB) throw new Error(`quotaGB must be at least ${MIN_BUCKET_QUOTA_GB} (the portal minimum) or 0 for unset; got ${gb}`);
+}
+
 // confirmCost is the Approve & Create gate for billable one-shot creates: unless
 // args.confirm===true it returns the live-priced cost and creates NOTHING — the
 // agent shows the user, then re-calls with confirm:true. plan/apply remains the
@@ -82,8 +152,9 @@ async function confirmCost(api, args, spec) {
   return {
     requiresConfirmation: true,
     cost,
+    acting: await actingOf(api, { orgId, projectId: args.projectId }), // whose/where — JNG #131
     priceBook: orgId ? `org:${orgId}` : 'global-defaults',
-    message: 'Billable resource — show the user this cost, then re-call with confirm:true to create. For an immutable, server-pinned quote use neo_plan_stack → neo_apply_stack.',
+    message: 'Billable resource — show the user this cost (and the acting account/org), then re-call with confirm:true to create. For an immutable, server-pinned quote use neo_plan_stack → neo_apply_stack.',
   };
 }
 
@@ -128,9 +199,10 @@ async function billableGate(api, { projectId, kind, name, confirmationId, confir
   return {
     requiresConfirmation: true,
     cost,
+    acting: await actingOf(api, { orgId, projectId }), // whose/where — JNG #131
     priceBook: orgId ? `org:${orgId}` : 'global-defaults',
     confirmationId: id,
-    message: `Billable ${kind} — show the user this cost, then approve server-side: neo_confirm_action("${id}", "approve"), and re-call this tool with confirmationId="${id}". (Shortcut: re-call with confirm:true.) Nothing was created.`,
+    message: `Billable ${kind} — show the user this cost AND the acting account/org, then approve server-side: neo_confirm_action("${id}", "approve"), and re-call this tool with confirmationId="${id}". (Shortcut: re-call with confirm:true.) Nothing was created.`,
   };
 }
 
@@ -161,6 +233,30 @@ export const TOOLS = [
       return api.whoami();
     },
   },
+  {
+    name: 'neo_set_context',
+    description: 'Pin the target ENVIRONMENT (staging | production) for THIS session so every deploy/create uses it and staging/production don\'t get mixed in one task (JNG #136). Set it ONCE — ask the user which environment if unclear; prefer staging. After this, env-requiring tools (neo_deploy_folder, neo_create_database/queue/cron, neo_plan_stack, …) use it unless a call passes environment explicitly. Without a pin (and no explicit environment), those tools error asking you to choose.',
+    mutating: false,
+    schema: {
+      type: 'object',
+      properties: { environment: { type: 'string', enum: ['staging', 'production'], description: 'staging | production — the one environment this session targets' } },
+      required: ['environment'],
+    },
+    async call(api, args) {
+      sessionEnv = envStrict(args.environment);
+      return { environment: sessionEnv, pinned: true, note: 'Pinned for this session. Env-requiring tools now use it; override per-call by passing environment explicitly.' };
+    },
+  },
+  {
+    name: 'neo_get_context',
+    description: 'Show the current session context: the pinned target environment (from neo_set_context / NEO_APP_TARGET_ENV) and the acting account — so you can confirm WHICH environment and WHO before acting (JNG #136/#131). environment is null when not pinned yet.',
+    mutating: false,
+    schema: { type: 'object', properties: {} },
+    async call(api) {
+      const acct = (typeof api.actingIdentity === 'function') ? await api.actingIdentity().catch(() => ({})) : {};
+      return { environment: sessionEnv, ...acct };
+    },
+  },
   {
     name: 'neo_get_capabilities',
     description:
@@ -208,6 +304,17 @@ export const TOOLS = [
         bindings: { supported: true, targets: ['neo_db', 'neo_queue', 'neo_object_storage'], writeOnly: true, note: 'neo_bind_resource + neo_plan_stack bindings inject DATABASE_URL / NATS_URL (+ NATS_HOST/PORT/USER/PASSWORD) / S3_* server-side at deploy; secrets never returned (handoff 5)' },
         sourceTypes: ['git', 'image', 'dockerfile', 'local', 'template'],
         environments: ['staging', 'production'],
+        // Active session context + the one-environment-per-session invariant (JNG #136).
+        context: { environment: sessionEnv, pinned: !!sessionEnv },
+        environmentIsolation: {
+          supported: true,
+          pinnedBy: ['neo_set_context', 'first explicit environment on an env-requiring call'],
+          failsClosed: true, // env-requiring tools error (environment_not_chosen) instead of defaulting
+          refusesMixing: true, // an explicit env != the pin is rejected (environment_mismatch)
+          escapeHatch: 'allowCrossEnvironment:true (per call)',
+          bucketScope: 'shared', // buckets carry no environment
+          note: 'One target environment per MCP session; set once with neo_set_context (or the first explicit call), then reads/writes inherit it; cross-environment calls are refused unless allowCrossEnvironment:true.',
+        },
         pricing,
         costConsent: { estimateAvailable: true, dryRunIncludesCost: true, planApplyEnforced: true, note: 'neo_plan_stack returns a costed immutable plan; neo_apply_stack is server-enforced (hash/expiry/one-shot) so a billable stack requires a reviewed plan (handoff 3.3-3.5)' },
         // Project/organization lifecycle (issue #107 §3). Honest to THIS build: project
@@ -308,7 +415,7 @@ export const TOOLS = [
   },
   {
     name: 'neo_update_service',
-    description: 'Update a service/app config (handoff §4.1/§4.2). Exposes compute (computeTier OR cpuLimit+memoryLimit), replicas, autoscale, port, command, domain, tls, ingress path, and health/liveness/readiness/startup checks. Cost-changing fields (compute/replicas/autoscale) require confirm:true — without it the new cost is returned and nothing is applied. Redeploy the service for changes to take effect. Omitted fields are left unchanged.',
+    description: 'Update a service/app config (handoff §4.1/§4.2). Exposes compute (computeTier OR cpuLimit+memoryLimit), replicas, autoscale, port, command, domain, tls, ingress path, PERSISTENT VOLUMES (mounts+volumeSize — so local-disk data survives redeploys/restarts, JNG #129), and health/liveness/readiness/startup checks. Cost-changing fields (compute/replicas/autoscale/volume) require confirm:true — without it the new cost is returned and nothing is applied. Redeploy the service for changes to take effect. Omitted fields are left unchanged.',
     mutating: true,
     schema: {
       type: 'object',
@@ -324,6 +431,8 @@ export const TOOLS = [
         autoscaleMemory: int('Autoscale target memory %'),
         port: int('Container port'),
         command: { type: 'array', items: { type: 'string' }, description: 'Override the image command (argv)' },
+        mounts: { type: 'array', description: 'Persistent volume mounts so on-disk data (uploads, caches) survives redeploys/restarts (JNG #129). Each: {name, path} where path is the in-container dir, e.g. {name:"uploads", path:"/app/.emdash/uploads"}. Set volumeSize too. NOTE: volumes are ReadWriteOnce (single-writer) — don\'t run >1 replica/autoscale with a mount.', items: { type: 'object', properties: { name: str('Volume name'), path: str('Mount path in the container') }, required: ['name', 'path'] } },
+        volumeSize: str('PVC size for the mounts, e.g. "10Gi" (required when setting mounts)'),
         domain: str('Primary domain ("" clears it back to the default host)'),
         tls: { type: 'boolean', description: 'Enable/disable managed TLS on the domain' },
         path: str('Ingress path prefix'),
@@ -333,7 +442,7 @@ export const TOOLS = [
         startupPath: str('Startup probe path'),
         healthTimeoutSeconds: int('Health-check timeout (s)'),
         healthGraceSeconds: int('Health-check grace period (s)'),
-        confirm: { type: 'boolean', description: 'Approve a cost change (compute/replicas/autoscale): without it the new cost is returned and nothing is applied.' },
+        confirm: { type: 'boolean', description: 'Approve a cost change (compute/replicas/autoscale/volume): without it the new cost is returned and nothing is applied.' },
       },
       required: ['appId'],
     },
@@ -342,49 +451,149 @@ export const TOOLS = [
       const body = { ...rest };
       if (computeTier) { body.billingMode = 'bundled'; body.cpuLimit = computeTier; }
       else if (args.cpuLimit || args.memoryLimit) { body.billingMode = 'unbundled'; }
-      const costChanging = computeTier || args.cpuLimit || args.memoryLimit || args.replicas !== undefined || args.autoscaleMax !== undefined;
+      const costChanging = computeTier || args.cpuLimit || args.memoryLimit || args.replicas !== undefined || args.autoscaleMax !== undefined || args.autoscaleMin !== undefined || args.volumeSize !== undefined || (Array.isArray(args.mounts) && args.mounts.length > 0);
       if (costChanging && confirm !== true) {
-        const gate = await confirmCost(api, args, { computeTier, replicas: args.replicas ?? args.autoscaleMax });
-        if (gate) return { ...gate, change: 'update service compute/scaling', message: 'This changes cost — re-call with confirm:true to apply.' };
+        // Price the change against the NEW replica count (autoscale uses its ceiling) and the
+        // effective compute — the one being set, else the service's CURRENT compute. Without
+        // the current compute, an autoscale-only change estimated to IDR 0 (#123).
+        const replicas = args.replicas ?? args.autoscaleMax ?? args.autoscaleMin;
+        let spec;
+        if (computeTier) spec = { computeTier, replicas };
+        else if (args.cpuLimit || args.memoryLimit) spec = { vcpu: cpuToVcpu(args.cpuLimit), memoryMB: memToMB(args.memoryLimit), replicas };
+        else {
+          let svc = {};
+          try { const d = (await api.get(`/api/v1/apps/${appId}`)).data; svc = (d && d.application) || d || {}; } catch { /* best-effort */ }
+          // A bundled service with no explicit tier bills at the default "micro" (store.DefaultTierKey);
+          // using the empty cpuLimit as-is priced the gate at IDR 0 (#123).
+          spec = (svc.billingMode === 'unbundled' && (svc.cpuLimit || svc.memoryLimit))
+            ? { vcpu: cpuToVcpu(svc.cpuLimit), memoryMB: memToMB(svc.memoryLimit), replicas }
+            : { computeTier: svc.cpuLimit || 'micro', replicas };
+        }
+        if (args.volumeSize !== undefined) spec = { ...spec, storageGB: gbFromSize(args.volumeSize) }; // persistent-volume price in the gate (JNG #129)
+        const gate = await confirmCost(api, args, spec);
+        if (gate) return { ...gate, change: 'update service compute/scaling/volume', message: 'This changes cost — re-call with confirm:true to apply.' };
       }
       const { status, data } = await api.put(`/api/v1/apps/${appId}`, body);
-      return redactSecrets(result(status, data));
+      const out = redactSecrets(result(status, data));
+      // Persistent volumes are ReadWriteOnce (single-writer): warn if run with >1 replica (JNG #129).
+      if (Array.isArray(args.mounts) && args.mounts.length > 0 && out && typeof out === 'object') {
+        const maxReplicas = Math.max(args.replicas || 0, args.autoscaleMax || 0);
+        out.volumeNote = 'Persistent volumes are ReadWriteOnce (single-writer). Keep this service at 1 replica (no autoscale) unless the volume is shareable, or pods will fail to mount it.';
+        if (maxReplicas > 1) out.warning = `This sets a volume AND ${maxReplicas} replicas — a ReadWriteOnce volume can't attach to multiple pods. Use 1 replica, or don't mount a volume here.`;
+      }
+      return out;
     },
   },
   {
     name: 'neo_add_service_domain',
-    description: 'Attach an additional custom ingress domain to a service (handoff §4.1). Point the domain\'s DNS at the platform first; managed TLS is issued automatically. The default platform host is preserved.',
+    description: 'Attach a custom ingress domain to a service (handoff §4.1; JNG #112). Call WITHOUT confirmed to get the exact CNAME target to point DNS at — nothing is attached until the DNS resolves OR you re-call with confirmed:true (so an unpointed host can\'t attach with broken TLS). Managed TLS is issued on the next deploy. The default platform host is preserved.',
     mutating: true,
-    schema: { type: 'object', properties: { appId: str('Service/app id'), domain: str('Custom domain host, e.g. "app.example.com"') }, required: ['appId', 'domain'] },
+    schema: { type: 'object', properties: { appId: str('Service/app id'), domain: str('Custom domain host, e.g. "app.example.com"'), confirmed: { type: 'boolean', description: 'Confirm DNS is pointed at the returned CNAME target; without it an unpointed host returns the CNAME instructions and attaches nothing' } }, required: ['appId', 'domain'] },
     async call(api, args) {
-      const { status, data } = await api.post(`/api/v1/apps/${args.appId}/domains`, { domain: args.domain });
+      const { status, data } = await api.post(`/api/v1/apps/${args.appId}/domains`, { domain: args.domain, confirmed: !!args.confirmed });
       return result(status, data);
     },
   },
   {
     name: 'neo_remove_service_domain',
-    description: 'Detach a custom domain from a service. The default platform host and other domains are untouched.',
+    description: 'Detach a custom domain from a service (JNG #112). SAFE BY DEFAULT: without confirm:true it returns a preview (what will be detached) and removes nothing; re-call with confirm:true to detach — dropping its ingress + managed TLS on the next deploy. The default platform host and other domains are untouched.',
     mutating: true,
     destructive: true,
-    schema: { type: 'object', properties: { appId: str('Service/app id'), domain: str('Custom domain host to remove') }, required: ['appId', 'domain'] },
+    schema: { type: 'object', properties: { appId: str('Service/app id'), domain: str('Custom domain host to remove'), confirm: { type: 'boolean', description: 'Approve the destructive detach; without it a preview is returned and nothing is removed' } }, required: ['appId', 'domain'] },
     async call(api, args) {
-      const { status, data } = await api.del(`/api/v1/apps/${args.appId}/domains`, { body: { domain: args.domain } });
+      const { status, data } = await api.del(`/api/v1/apps/${args.appId}/domains`, { body: { domain: args.domain, confirm: !!args.confirm } });
       return result(status, data);
     },
   },
   {
     name: 'neo_get_deployment',
-    description: 'Get a deployment by id (poll this after neo_deploy until status is terminal).',
+    description: 'Get a deployment by id (poll this after neo_deploy until status is terminal). The build log is returned NEWEST-FIRST and TRUNCATED to the last 200 lines by default so the failure reason is at the top and huge logs do not overflow the tool output (JNG #124, #117). Use tail to change the line count, full:true for the entire log, order:"asc" for chronological build output. logTotalLines/logTruncated report how much was cut.',
     mutating: false,
-    schema: { type: 'object', properties: { deploymentId: str('Deployment id') }, required: ['deploymentId'] },
+    schema: {
+      type: 'object',
+      properties: {
+        deploymentId: str('Deployment id'),
+        order: { type: 'string', enum: ['desc', 'asc'], description: 'build-log order: desc = newest-first (default); asc = oldest-first (chronological)' },
+        tail: int('Number of build-log lines to return (default 200, newest end); ignored when full:true'),
+        full: { type: 'boolean', description: 'Return the entire build log instead of the last `tail` lines' },
+      },
+      required: ['deploymentId'],
+    },
+    async call(api, args) {
+      const dep = (await api.get(`/api/v1/deployments/${args.deploymentId}`)).data;
+      if (dep && typeof dep.log === 'string' && dep.log) {
+        let lines = dep.log.replace(/\n$/, '').split('\n');
+        dep.logTotalLines = lines.length;
+        const tail = args.full ? lines.length : (args.tail > 0 ? args.tail : 200);
+        dep.logTruncated = !args.full && lines.length > tail;
+        lines = lines.slice(-tail);                       // keep the newest `tail` lines
+        if (args.order !== 'asc') lines.reverse();        // newest-first by default
+        dep.log = lines.join('\n');
+      }
+      return dep;
+    },
+  },
+  {
+    name: 'neo_wait_deployment',
+    description: 'Block until a deployment reaches a terminal state (success | failed) or the timeout — polls server-side so you do NOT sleep/guess or re-pull the whole build log (JNG #121). Returns status, error, the last ~50 build-log lines (newest-first), logTotalLines, and rolloutReady (whether the service has a Ready pod after a successful build — the new revision is actually serving). One call replaces a poll loop.',
+    mutating: false,
+    schema: {
+      type: 'object',
+      properties: {
+        deploymentId: str('Deployment id (from neo_deploy / neo_deploy_folder)'),
+        timeoutSeconds: int('Max wait in seconds (default 300)'),
+      },
+      required: ['deploymentId'],
+    },
     async call(api, args) {
-      return (await api.get(`/api/v1/deployments/${args.deploymentId}`)).data;
+      const deadline = Date.now() + (args.timeoutSeconds > 0 ? args.timeoutSeconds : 300) * 1000;
+      const terminal = new Set(['success', 'failed']);
+      let dep = {};
+      for (;;) {
+        dep = (await api.get(`/api/v1/deployments/${args.deploymentId}`)).data || {};
+        if (terminal.has(dep.status) || Date.now() >= deadline) break;
+        await new Promise((r) => setTimeout(r, 4000));
+      }
+      const lines = String(dep.log || '').replace(/\n$/, '').split('\n').filter((l) => l.length);
+      const out = {
+        deploymentId: args.deploymentId,
+        status: dep.status,
+        error: dep.error || undefined,
+        logTotalLines: lines.length,
+        buildLogTail: lines.length ? lines.slice(-50).reverse().join('\n') : undefined, // newest-first
+      };
+      if (!terminal.has(dep.status)) {
+        out.timedOut = true;
+        out.note = 'still in progress at timeout — call neo_wait_deployment again';
+        return out;
+      }
+      // Best-effort: after a successful BUILD, wait until the service has a Ready pod so the
+      // caller knows the new revision is actually serving (not just built) — JNG #121.
+      if (dep.status === 'success') {
+        try {
+          const appId = dep.applicationId || dep.composeAppId;
+          const pid = dep.projectId;
+          let svcName = '';
+          try { const a = (await api.get(`/api/v1/apps/${appId}`)).data; svcName = ((a && a.application) || a || {}).name || ''; } catch { /* name best-effort */ }
+          const isReady = (p) => { const m = /^(\d+)\/(\d+)$/.exec(p.ready || ''); return p.status === 'Running' && m && +m[1] > 0 && m[1] === m[2]; };
+          if (pid) {
+            for (;;) {
+              const pods = (await api.get(`/api/v1/projects/${pid}/pods`)).data?.pods || [];
+              const mine = svcName ? pods.filter((p) => p.service === svcName) : pods;
+              if (mine.some(isReady)) { out.rolloutReady = true; break; }
+              if (Date.now() >= deadline) { out.rolloutReady = false; out.note = 'build succeeded but no Ready pod yet at timeout'; break; }
+              await new Promise((r) => setTimeout(r, 4000));
+            }
+          }
+        } catch { /* rollout check best-effort */ }
+      }
+      return out;
     },
   },
   {
     name: 'neo_deploy',
     description:
-      'Trigger a deployment of an app (service). Returns a deployment to poll, or a pending_approval result when org policy gates it. Deploy to staging first.',
+      'Trigger a deployment of an app (service). Returns a deployment id — pass it to neo_wait_deployment to block until it finishes (don\'t sleep/guess), or a pending_approval result when org policy gates it. Deploy to staging first.',
     mutating: true,
     schema: { type: 'object', properties: { appId: str('App/service id') }, required: ['appId'] },
     async call(api, args) {
@@ -394,59 +603,150 @@ export const TOOLS = [
   },
   {
     name: 'neo_get_logs',
-    description: 'Read recent logs for a service in a project (plain text). Summarize; redact secrets.',
+    description: 'Read recent logs for a service in a project (plain text), NEWEST-FIRST by default so the latest error is at the top (JNG #124). Pass order:"asc" for oldest-first/chronological. Each line is prefixed with the kubelet UTC timestamp. Target one pod with `pod` (from neo_list_pods). When no pod exists (a failed build), the latest deployment BUILD log is returned instead (JNG #117). Summarize; redact secrets.',
     mutating: false,
     schema: {
       type: 'object',
       properties: {
         projectId: str('Project id'),
         service: str('Service/app name (optional)'),
+        pod: str('Pod name to read (optional; from neo_list_pods) — otherwise the first pod of the service'),
         tail: int('Number of lines (default 200)'),
+        order: { type: 'string', enum: ['desc', 'asc'], description: 'desc = newest-first (default); asc = oldest-first (chronological)' },
       },
       required: ['projectId'],
     },
     async call(api, args) {
       const { data } = await api.get(`/api/v1/projects/${args.projectId}/logs`, {
-        query: { service: args.service, tail: args.tail },
+        query: { service: args.service, pod: args.pod, tail: args.tail, order: args.order },
         accept: 'text/plain',
       });
       return typeof data === 'string' ? data : JSON.stringify(data);
     },
   },
+  {
+    name: 'neo_list_pods',
+    description: 'List the running pods for a project (optionally one service) so you can see what is ACTUALLY running, not just the desired config (JNG #130): per pod — name, service, ready (readyContainers/total), status, restarts, image (which build), startedAt (UTC), node, and reason (ImagePullBackOff/CrashLoopBackOff when unhealthy). Use a pod name with neo_get_logs to target it.',
+    mutating: false,
+    schema: {
+      type: 'object',
+      properties: {
+        projectId: str('Project id'),
+        service: str('Service/app name to filter by (optional)'),
+      },
+      required: ['projectId'],
+    },
+    async call(api, args) {
+      const pods = (await api.get(`/api/v1/projects/${args.projectId}/pods`)).data?.pods || [];
+      const filtered = args.service ? pods.filter((p) => p.service === args.service) : pods;
+      return { pods: filtered, running: filtered.filter((p) => p.status === 'Running').length, total: filtered.length };
+    },
+  },
   {
     name: 'neo_list_variables',
-    description: 'List environment variable names/values for a project environment. Secret values are masked by the server.',
+    description: 'List the project/environment DEFAULT environment variables. Uses the session-pinned environment (neo_set_context) unless you pass environment explicitly; fails closed if neither is set — it is never defaulted to production (JNG #136). These are inherited by every service in that environment. For what ONE service actually receives — including per-service vars and binding-injected ones — use neo_get_effective_env. Secret values are masked by the server.',
     mutating: false,
     schema: {
       type: 'object',
       properties: {
         projectId: str('Project id'),
-        environment: str('production or staging (default production)'),
+        environment: str('production or staging (optional; defaults to the session pin — errors if neither is set, never silently production)'),
+        ...allowCrossEnvProp,
       },
       required: ['projectId'],
     },
     async call(api, args) {
-      const env = args.environment || 'production';
-      return (await api.get(`/api/v1/projects/${args.projectId}/environments/${env}/config`)).data;
+      const env = requireEnv(args.environment, args.allowCrossEnvironment);
+      return { environment: env, ...(await api.get(`/api/v1/projects/${args.projectId}/environments/${env}/config`)).data };
+    },
+  },
+  {
+    name: 'neo_get_effective_env',
+    description: 'Show the EFFECTIVE environment of one service (JNG #130): every variable name the container actually receives, each tagged with its source (environment | service | binding:<name>) and the value masked when it is secret. Unlike neo_list_variables (project/env defaults only), this includes per-service variables AND binding-injected ones (DATABASE_URL, S3_*, NATS_*).',
+    mutating: false,
+    schema: {
+      type: 'object',
+      properties: { appId: str('Service/app id (from neo_list_services)') },
+      required: ['appId'],
+    },
+    async call(api, args) {
+      // Server already masks secret VALUES (value:"***", secret:true); don't run redactSecrets
+      // here — it would clobber our own `source`/`secret` field names (JNG #130).
+      return (await api.get(`/api/v1/apps/${args.appId}/effective-env`)).data;
+    },
+  },
+  {
+    name: 'neo_restart_service',
+    description: 'Rolling-restart a service with its CURRENT image + config — no rebuild (JNG #128). Use after a config-only change (neo_set_service_variable, neo_update_service) that doesn\'t need a new build, instead of a full neo_deploy. Returns immediately; poll neo_list_pods for the new pods.',
+    mutating: true,
+    schema: { type: 'object', properties: { appId: str('Service/app id (from neo_list_services)') }, required: ['appId'] },
+    async call(api, args) {
+      return (await api.post(`/api/v1/apps/${args.appId}/restart`, {})).data;
+    },
+  },
+  {
+    name: 'neo_exec',
+    description: 'Run a one-off shell command in a running pod of a service and return stdout/stderr/exitCode (JNG #128) — e.g. command:"env | grep ^S3_" to see injected vars, or "ls -la". Service-level secret values are masked in the output (best-effort). Not a shell session; for interactive use the portal terminal. CAUTION: runs real commands in the live pod.',
+    mutating: true,
+    schema: {
+      type: 'object',
+      properties: {
+        appId: str('Service/app id (from neo_list_services)'),
+        command: str('Shell command to run (executed via /bin/sh -c)'),
+        pod: str('Specific pod name (optional; from neo_list_pods) — else the first running pod'),
+        timeoutSeconds: int('Max seconds to wait (default 30, max 120)'),
+      },
+      required: ['appId', 'command'],
+    },
+    async call(api, args) {
+      const { appId, ...body } = args;
+      return (await api.post(`/api/v1/apps/${appId}/exec`, body)).data;
+    },
+  },
+  {
+    name: 'neo_get_database_metrics',
+    description: 'Current resource usage for a managed postgres database (JNG #133): cpuMillicores + memoryBytes (metrics-server), databaseSizeBytes vs volumeSize (is it filling up?), and connections / maxConnections / connectionsPercent. Snapshot only (no history). Use before a migration or resize to check headroom.',
+    mutating: false,
+    schema: { type: 'object', properties: { databaseId: str('Database id (postgres, deployed)') }, required: ['databaseId'] },
+    async call(api, args) {
+      return (await api.get(`/api/v1/databases/${args.databaseId}/metrics`)).data;
+    },
+  },
+  {
+    name: 'neo_db_query',
+    description: 'Run a SQL query inside a managed postgres database\'s primary pod and return the result (JNG #128). READ-ONLY by default (the session is set read-only, so any write errors); pass readOnly:false to allow writes (CAUTION). Credentials are never exposed. The database must be deployed. Use for quick checks like "SELECT count(*) FROM sessions;".',
+    mutating: true,
+    schema: {
+      type: 'object',
+      properties: {
+        databaseId: str('Database id (postgres, deployed)'),
+        sql: str('SQL to run (piped into psql)'),
+        readOnly: { type: 'boolean', description: 'true (default) runs in a read-only session; false allows writes' },
+      },
+      required: ['databaseId', 'sql'],
+    },
+    async call(api, args) {
+      return (await api.post(`/api/v1/databases/${args.databaseId}/query`, { sql: args.sql, readOnly: args.readOnly })).data;
     },
   },
   {
     name: 'neo_set_variable',
     description:
-      'Set one environment variable for a project environment (read-merge-write; other vars preserved). Never echo secret values.',
+      'Set one environment variable for a project environment (read-merge-write; other vars preserved). Uses the session-pinned environment (neo_set_context) unless you pass environment explicitly; fails closed if neither is set — never defaulted to production (JNG #136). Never echo secret values.',
     mutating: true,
     schema: {
       type: 'object',
       properties: {
         projectId: str('Project id'),
-        environment: str('production or staging (default production)'),
+        environment: str('production or staging (optional; defaults to the session pin — errors if neither is set, never silently production)'),
+        ...allowCrossEnvProp,
         key: str('Variable name'),
         value: str('Variable value'),
       },
       required: ['projectId', 'key', 'value'],
     },
     async call(api, args) {
-      const env = args.environment || 'production';
+      const env = requireEnv(args.environment, args.allowCrossEnvironment);
       const path = `/api/v1/projects/${args.projectId}/environments/${env}/config`;
       // The PUT replaces the whole set, so merge current vars first.
       const current = (await api.get(path)).data?.vars || [];
@@ -457,7 +757,7 @@ export const TOOLS = [
       const out = result(status, data);
       // Don't return the value we just set.
       if (out && out.vars) out.vars = out.vars.map((v) => (v.key === args.key ? { ...v, value: '••••••••' } : v));
-      return out;
+      return { environment: env, ...out };
     },
   },
   {
@@ -682,6 +982,7 @@ export const TOOLS = [
         publishDirectory: str('static_site: directory of built files to serve via nginx (e.g. "dist"); enables native static hosting'),
         port: int('Container port (optional; ignored for worker)'),
         environment: { type: 'string', enum: ['staging', 'production'], description: 'REQUIRED — staging or production. Never defaulted (handoff §2). Deploy to staging first.' },
+        ...allowCrossEnvProp,
         dryRun: { type: 'boolean', description: 'Preview the plan without creating/uploading/deploying anything (JNG #93). Returns a confirmToken.' },
         confirmToken: str('The confirmToken from a prior dryRun — pass it on the real deploy to guarantee the spec/cost the user approved has not changed (rejected on mismatch).'),
         confirm: { type: 'boolean', description: 'Approve the billable deploy after showing the user the cost (alternative to confirmToken). Without confirmToken or confirm:true the tool returns the cost and deploys nothing.' },
@@ -689,7 +990,7 @@ export const TOOLS = [
       required: ['projectId', 'path', 'environment'],
     },
     async call(api, args) {
-      const environment = requireEnv(args.environment);
+      const environment = requireEnv(args.environment, args.allowCrossEnvironment);
       const p = resolve(args.path);
       let src;
       try {
@@ -713,9 +1014,11 @@ export const TOOLS = [
         confirm: args.confirm === true,
         dryRun: !!args.dryRun,
       });
-      if (r.dryRun) return { status: r.requiresConfirmation ? 'requires_confirmation' : 'dry_run', requiresConfirmation: r.requiresConfirmation || undefined, plan: r.plan, service: r.service, environment: r.environment, estimatedCost: r.estimatedCost, confirmToken: r.confirmToken, note: r.note || 'To deploy exactly this, re-call without dryRun and pass this confirmToken.' };
+      if (r.dryRun) return { status: r.requiresConfirmation ? 'requires_confirmation' : 'dry_run', requiresConfirmation: r.requiresConfirmation || undefined, plan: r.plan, service: r.service, environment: r.environment, acting: r.acting, estimatedCost: r.estimatedCost, confirmToken: r.confirmToken, note: r.note || 'To deploy exactly this, re-call without dryRun and pass this confirmToken.' };
       if (r.pending) return { status: 'pending_approval', approvalId: r.approvalId };
-      return { status: r.result, url: r.url || undefined, appId: r.appId };
+      // Always return the deploymentId; on failure include the error + build-log tail so
+      // the caller can diagnose without a second build (JNG #117).
+      return { environment, status: r.result, url: r.url || undefined, appId: r.appId, deploymentId: r.deploymentId, error: r.error, buildLogTail: r.buildLogTail };
     },
   },
   {
@@ -750,6 +1053,7 @@ export const TOOLS = [
         engine: { type: 'string', description: 'postgres | mysql (engine)' },
         version: str('Engine version, e.g. "16" (optional)'),
         environment: { type: 'string', enum: ['staging', 'production'], description: 'REQUIRED — staging or production (never defaulted, handoff §2)' },
+        ...allowCrossEnvProp,
         volumeSize: str('Storage size, e.g. "10Gi" (optional)'),
         replicas: int('Read/failover replicas for HA (optional; postgres/CNPG only)'),
         deploymentMode: { type: 'string', description: 'single | ha (optional)' },
@@ -759,12 +1063,14 @@ export const TOOLS = [
       required: ['projectId', 'name', 'engine', 'environment'],
     },
     async call(api, args) {
-      requireEnv(args.environment);
+      const environment = requireEnv(args.environment, args.allowCrossEnvironment); // explicit, else the session pin (JNG #136)
+      validateDbArgs(args); // reject sub-10Gi / EOL config before pricing (JNG #132)
       const gate = await billableGate(api, { projectId: args.projectId, kind: 'database', name: args.name, confirmationId: args.confirmationId, confirm: args.confirm }, { storageGB: gbFromSize(args.volumeSize), replicas: args.replicas });
-      if (gate.requiresConfirmation) return gate;
+      if (gate.requiresConfirmation) return { environment, ...gate };
       const { projectId, confirm, confirmationId, orgId, ...body } = args;
+      body.environment = environment; // send the resolved env so the pin actually targets it
       const { status, data } = await api.post(`/api/v1/projects/${projectId}/databases${gate.query}`, body);
-      return redactSecrets(result(status, data));
+      return { environment, ...redactSecrets(result(status, data)) };
     },
   },
   {
@@ -922,6 +1228,7 @@ export const TOOLS = [
         name: str('Queue name'),
         planClass: str('Plan/engine class (optional)'),
         environment: { type: 'string', enum: ['staging', 'production'], description: 'REQUIRED — staging or production (never defaulted, handoff §2)' },
+        ...allowCrossEnvProp,
         volumeSize: str('Storage size, e.g. "10Gi" (optional)'),
         dlqEnabled: { type: 'boolean', description: 'Enable a dead-letter queue (optional, default true). Pass false to disable — this is now honored.' },
         confirm: { type: 'boolean', description: 'Approve & Create in one call: mints + auto-approves a server-side billable confirmation, then creates. Without confirm (or confirmationId) the tool returns the cost + a pending confirmationId and creates nothing.' },
@@ -930,12 +1237,13 @@ export const TOOLS = [
       required: ['projectId', 'name', 'environment'],
     },
     async call(api, args) {
-      requireEnv(args.environment);
+      const environment = requireEnv(args.environment, args.allowCrossEnvironment); // explicit, else the session pin (JNG #136)
       const gate = await billableGate(api, { projectId: args.projectId, kind: 'queue', name: args.name, confirmationId: args.confirmationId, confirm: args.confirm }, { storageGB: gbFromSize(args.volumeSize) });
-      if (gate.requiresConfirmation) return gate;
+      if (gate.requiresConfirmation) return { environment, ...gate };
       const { projectId, confirm, confirmationId, orgId, ...body } = args;
+      body.environment = environment; // send the resolved env so the pin actually targets it
       const { status, data } = await api.post(`/api/v1/projects/${projectId}/queues${gate.query}`, body);
-      return redactSecrets(result(status, data));
+      return { environment, ...redactSecrets(result(status, data)) };
     },
   },
   {
@@ -1062,22 +1370,24 @@ export const TOOLS = [
         retryCount: int('Retries on failure (optional) → backoffLimit'),
         concurrencyPolicy: { type: 'string', enum: ['Allow', 'Forbid', 'Replace'], description: 'Overlap policy if a run is still going when the next is due (optional, default Allow)' },
         environment: { type: 'string', enum: ['staging', 'production'], description: 'REQUIRED — staging or production (never defaulted, handoff §2)' },
+        ...allowCrossEnvProp,
         confirm: { type: 'boolean', description: 'Approve & Create in one call: mints + auto-approves a server-side billable confirmation (crons are billed per run — variable), then creates. Without confirm (or confirmationId) the tool returns the cost + a pending confirmationId and creates nothing.' },
         confirmationId: str('An APPROVED billable_create confirmation id (from neo_confirm_action) — re-call with it to create. Alternative to confirm:true.'),
       },
       required: ['projectId', 'name', 'mode', 'scheduleType', 'environment'],
     },
     async call(api, args) {
-      requireEnv(args.environment);
+      const environment = requireEnv(args.environment, args.allowCrossEnvironment); // explicit, else the session pin (JNG #136)
       const gate = await billableGate(api, { projectId: args.projectId, kind: 'cron', name: args.name, confirmationId: args.confirmationId, confirm: args.confirm }, {}); // cron cost is variable (per-run) — gate surfaces the rate
-      if (gate.requiresConfirmation) return gate;
+      if (gate.requiresConfirmation) return { environment, ...gate };
       // Merge contentType into headers for convenience (unless already set).
       if (args.contentType) {
         args = { ...args, headers: { 'Content-Type': args.contentType, ...(args.headers || {}) } };
       }
       const { projectId, confirm, confirmationId, orgId, contentType, ...body } = args;
+      body.environment = environment; // send the resolved env so the pin actually targets it
       const { status, data } = await api.post(`/api/v1/projects/${projectId}/crons${gate.query}`, body);
-      return redactSecrets(result(status, data));
+      return { environment, ...redactSecrets(result(status, data)) };
     },
   },
   {
@@ -1119,7 +1429,7 @@ export const TOOLS = [
   },
   {
     name: 'neo_create_bucket',
-    description: 'Create an S3-compatible object-storage bucket in a project (handoff 4.7). Access keys are provisioned server-side and are NOT returned (write-only). May return pending_approval.',
+    description: 'Create an S3-compatible object-storage bucket in a project (handoff 4.7). Buckets are project-scoped and SHARED across environments — they carry no staging/production environment (scope:"shared"), unlike services/databases (JNG #136). Access keys are provisioned server-side and are NOT returned (write-only). May return pending_approval.',
     mutating: true,
     schema: {
       type: 'object',
@@ -1135,11 +1445,13 @@ export const TOOLS = [
       required: ['projectId', 'name'],
     },
     async call(api, args) {
+      validateBucketArgs(args); // reject sub-10GB quota before pricing (JNG #132)
       const gate = await billableGate(api, { projectId: args.projectId, kind: 'bucket', name: args.name, confirmationId: args.confirmationId, confirm: args.confirm }, { objectStorageGB: gbFromSize(args.quotaGB) });
       if (gate.requiresConfirmation) return gate;
       const { projectId, confirm, confirmationId, orgId, ...body } = args;
       const { status, data } = await api.post(`/api/v1/projects/${projectId}/buckets${gate.query}`, body);
-      return redactSecrets(result(status, data));
+      // Buckets have no environment — label the scope so the agent doesn't expect one (JNG #136).
+      return { scope: 'shared', ...redactSecrets(result(status, data)) };
     },
   },
   {
@@ -1220,7 +1532,7 @@ export const TOOLS = [
   {
     name: 'neo_bind_resource',
     description:
-      'Bind a managed database, queue, or object-storage bucket to a consumer service so its connection is injected as environment variable(s) at the consumer\'s next deploy — WITHOUT ever exposing the secret to you (handoff 5, write-only). envKey defaults: DATABASE_URL (neo_db), NATS_URL (neo_queue); for neo_object_storage it is a PREFIX (default S3) injecting <P>_ENDPOINT/_BUCKET/_REGION + secret <P>_ACCESS_KEY/_SECRET_KEY. After binding, redeploy the consumer. Target and consumer must be in the same project.',
+      'Bind a managed database, queue, or object-storage bucket to a consumer service so its connection is injected as environment variable(s) at the consumer\'s next deploy — WITHOUT ever exposing the secret to you (handoff 5, write-only). envKey defaults: DATABASE_URL (neo_db), NATS_URL (neo_queue); for neo_object_storage it is a PREFIX (default S3) injecting <P>_ENDPOINT/_BUCKET/_REGION + secret creds under both <P>_ACCESS_KEY/_SECRET_KEY and the AWS-SDK names <P>_ACCESS_KEY_ID/_SECRET_ACCESS_KEY (use envKey="AWS" for AWS_* names). <P>_ENDPOINT is the public S3 host apps can actually reach. After binding, redeploy the consumer. Target and consumer must be in the same project.',
     mutating: true,
     schema: {
       type: 'object',
@@ -1312,6 +1624,7 @@ export const TOOLS = [
       properties: {
         projectId: str('Project id'),
         environment: { type: 'string', enum: ['staging', 'production'], description: 'REQUIRED — staging or production (never defaulted, handoff §2)' },
+        ...allowCrossEnvProp,
         resources: {
           type: 'array',
           description: 'The stack resources. Each needs a unique name + kind (app | database | queue | bucket | cron).',
@@ -1373,10 +1686,12 @@ export const TOOLS = [
       required: ['projectId', 'environment', 'resources'],
     },
     async call(api, args) {
-      requireEnv(args.environment);
+      const environment = requireEnv(args.environment, args.allowCrossEnvironment); // explicit, else the session pin (JNG #136)
       const { projectId, ...body } = args;
+      body.environment = environment; // send the resolved env so the pin actually targets it
       const { status, data } = await api.post(`/api/v1/projects/${projectId}/plans`, body);
-      return result(status, data);
+      const out = result(status, data);
+      return (out && typeof out === 'object') ? { environment, ...out } : out;
     },
   },
   {
@@ -1563,12 +1878,35 @@ export const TOOLS = [
   },
   {
     name: 'neo_delete_bucket',
-    description: 'Permanently delete an object-storage bucket. Destructive and irreversible — bucket contents are lost.',
+    description: 'Delete an object-storage bucket and all its objects. SAFE BY DEFAULT: with no confirmationId it returns the bucket details + a server-side CONFIRMATION, deleting NOTHING. Then: show the user, call neo_confirm_action(confirmationId, "approve", confirmationPhrase=<EXACT bucket name>), then re-call with that confirmationId. Server-enforced, single-use, exact-name (JNG #138). Destructive and irreversible — bucket contents are lost.',
     mutating: true,
     destructive: true,
-    schema: { type: 'object', properties: { bucketId: str('Bucket id') }, required: ['bucketId'] },
+    schema: {
+      type: 'object',
+      properties: {
+        bucketId: str('Bucket id'),
+        confirmationId: str('An APPROVED confirmation id (from neo_confirm_action). Omit to get the confirmation.'),
+      },
+      required: ['bucketId'],
+    },
     async call(api, args) {
-      return deleteAndConverge(api, `/api/v1/buckets/${args.bucketId}`, args.bucketId, 'bucket');
+      if (args.confirmationId) {
+        return deleteAndConverge(api, `/api/v1/buckets/${args.bucketId}`, args.bucketId, 'bucket', `?confirmationId=${encodeURIComponent(args.confirmationId)}`);
+      }
+      let bk = null;
+      try { bk = (await api.get(`/api/v1/buckets/${args.bucketId}`)).data; } catch { /* preview best-effort */ }
+      let c;
+      try { c = (await api.post('/api/v1/confirmations', { action: 'bucket_delete', targetId: args.bucketId })).data; }
+      catch (e) { return { deleted: false, error: 'confirmation_failed', message: 'Could not create a deletion confirmation: ' + (e.message || e) }; }
+      const bkView = (c.summary && c.summary.bucket) || (bk ? { id: bk.id, name: bk.name, region: bk.region } : { id: args.bucketId });
+      const phrase = (c.summary && c.summary.phraseRequired) || bkView.name;
+      return {
+        deleted: false, requiresConfirmation: true,
+        bucket: bkView,
+        warning: 'IRREVERSIBLE: deletes the bucket AND all objects in it.',
+        confirmationId: c.confirmationId, phraseRequired: phrase,
+        message: `To delete: call neo_confirm_action("${c.confirmationId}", "approve", confirmationPhrase="${phrase}") — the human must type the exact bucket name — then re-call neo_delete_bucket with confirmationId="${c.confirmationId}".`,
+      };
     },
   },
   {

package/src/skill/SKILL.md

@@ -18,8 +18,10 @@ NEO App is Biznet Gio's managed-app platform. You operate it two ways:
 
 ## Environments: staging first
 
+- **Pin ONE environment for the session up front**: call `neo_set_context({environment})` once (confirm `neo_get_context` shows the right account + environment). After that, every deploy/create **and read** (`neo_list_variables`, `neo_set_variable`) inherits it — don't mix staging and production in one task. If you haven't pinned and don't pass `environment`, the tools fail closed (`environment_not_chosen`) asking you to choose — they are never defaulted to production.
+- Once pinned, a call for a **different** environment is refused (`environment_mismatch`). That guard is deliberate: start a new session or re-pin to switch. Only when you truly must touch the other environment in the same session, pass `allowCrossEnvironment:true` on that one call. Buckets carry no environment (`scope:"shared"`).
 - Prefer **staging** for every change: deploy, test, and read logs on staging before touching production.
-- Only deploy to production when the user explicitly asks, and expect it to require approval (see below).
+- Only deploy to production when the user explicitly asks (pin `production` deliberately), and expect it to require approval (see below).
 
 ## Deployments