run402 4.68.3 → 4.69.0

package/lib/deploy-v2.mjs

@@ -891,7 +891,7 @@ async function mergeAstroReleaseSlice(spec, dirArg) {
  * (inline bytes). Only `{ path }` entries with no `data` resolve to a disk
  * file; inline entries are skipped (nothing to scan on disk). Returns a
  * de-duped list of absolute paths. Existence + extension filtering is the
- * caller's job (GH-409). Defensive: tolerates missing/odd shapes silently —
+ * caller's job. Defensive: tolerates missing/odd shapes silently —
  * the manifest normalizer is the authority on shape validity, not this
  * best-effort extractor.
  */
@@ -1017,7 +1017,7 @@ async function applyCmd(args) {
     await mergeAstroReleaseSlice(spec, opts.dir);
   }
 
-  // GH-232: Reject empty specs client-side. Without this guard,
+  // Reject empty specs client-side. Without this guard,
   // `run402 deploy apply --spec '{}'` (and `--manifest <empty>`) would silently
   // send an empty ReleaseSpec to /apply/v1/plans with no signal that nothing
   // was deployed.
@@ -1117,7 +1117,7 @@ async function applyCmd(args) {
   // the scanner has a false positive that the operator has confirmed
   // is fine. Hits with severity `error` fail the deploy.
   //
-  // Scope (GH-409): a `--dir` (Astro SSR build) deploy walks that dir —
+  // Scope: a `--dir` (Astro SSR build) deploy walks that dir —
   // it IS the artifact. A manifest/spec/stdin deploy scans ONLY the
   // on-disk source files the manifest actually references, resolved
   // against the manifest's baseDir. We must NOT walk cwd/src for a

package/lib/doctor-source-scan.mjs

@@ -425,7 +425,7 @@ export function scanSourceTree(srcDir, opts = {}) {
 /** Scan an explicit list of on-disk file paths — no directory walk.
  *  Used by `run402 deploy apply` for manifest/spec/stdin deploys, where
  *  the artifact is exactly the set of files the manifest references, NOT
- *  whatever happens to live under cwd/src (GH-409). Files without a
+ *  whatever happens to live under cwd/src. Files without a
  *  scannable extension are ignored; unreadable files become a WARN
  *  finding (never throw). Returns the combined findings list, sorted by
  *  file + line for stable output, exactly like `scanSourceTree`. */

package/lib/doctor.mjs

@@ -27,12 +27,12 @@ import { queueBuzzDoctorTelemetry } from "./diagnostic-telemetry.mjs";
 import { fail } from "./sdk-errors.mjs";
 import { normalizeArgv, assertKnownFlags, flagValue } from "./argparse.mjs";
 
-/** Value-taking flags (kychee-com/run402#566 — the flag set doctor actually parses; anything else is BAD_USAGE via assertKnownFlags, never silently ignored). */
+/** Value-taking flags — the flag set doctor actually parses; anything else is BAD_USAGE via assertKnownFlags, never silently ignored. */
 const DOCTOR_VALUE_FLAGS = ["--scan-dir", "--buzz-agent", "--project", "--only"];
 
 /**
- * The stable, complete registry of ordinary-mode check names (kychee-com/run402#566,
- * the remaining half). One entry per `checks.push({ name: ... })` call below,
+ * The stable, complete registry of ordinary-mode check names. One entry
+ * per `checks.push({ name: ... })` call below,
  * in the order each check normally runs. This is the ONE place `--only`
  * validates its argument against and the ONE place its help text is derived
  * from, so a check can never be selectable-but-undocumented or
@@ -195,11 +195,10 @@ export async function run(sub, args = []) {
     console.log(HELP);
     return;
   }
-  // kychee-com/run402#566 (--project half): doctor used to accept ANY flag
-  // silently — an unrecognized one (a typo, or --project before this fix)
-  // was simply never looked at. Any flag doctor actually parses is listed
-  // here; anything else is now a structured BAD_USAGE/UNKNOWN_FLAG rejection
-  // instead of quietly doing nothing.
+  // Accepting ANY flag silently means an unrecognized one (a typo) is
+  // never looked at. Any flag doctor actually parses is listed here;
+  // anything else is a structured BAD_USAGE/UNKNOWN_FLAG rejection instead
+  // of quietly doing nothing.
   assertKnownFlags(all, ["--verbose", "--refresh", "--no-scan", "--buzz", ...DOCTOR_VALUE_FLAGS], DOCTOR_VALUE_FLAGS);
   const verbose = all.includes("--verbose");
   const refresh = all.includes("--refresh");
@@ -210,11 +209,10 @@ export async function run(sub, args = []) {
   // wallet/machine-wide, not per-project.
   const projectOverride = flagValue(all, "--project");
 
-  // kychee-com/run402#566 (the remaining half): --only <check>, repeatable.
-  // Validated against the stable registry ABOVE the buzz early-return, so an
-  // unknown name is BAD_USAGE regardless of which mode was also requested —
-  // the same "every accepted flag must work or BAD_USAGE" bar #569 named for
-  // doctor's own --human bug.
+  // --only <check>, repeatable. Validated against the stable registry
+  // ABOVE the buzz early-return, so an unknown name is BAD_USAGE regardless
+  // of which mode was also requested — the same "every accepted flag must
+  // work or BAD_USAGE" bar as every other doctor flag.
   const onlyChecks = collectRepeatableFlag(all, "--only");
   for (const name of onlyChecks) {
     if (!DOCTOR_CHECK_NAMES.includes(name)) {
@@ -227,9 +225,8 @@ export async function run(sub, args = []) {
     }
   }
   // Buzz mode is a wholly separate, always-complete report shape — an --only
-  // that named ordinary-mode checks would be silently ignored under --buzz,
-  // exactly the class of bug #569 flagged for --human. Reject the
-  // combination instead.
+  // that named ordinary-mode checks would be silently ignored under --buzz
+  // — an accepted-but-inert flag. Reject the combination instead.
   if (onlyChecks.length > 0 && all.includes("--buzz")) {
     fail({
       code: "BAD_USAGE",
@@ -594,8 +591,7 @@ export async function run(sub, args = []) {
   // deployed is a first-class shape (protocol D183), so its mere absence of a
   // deploy raises nothing.
   //
-  // TARGETING (repo-first-onramp follow-up, kychee-com/run402#559d, extended
-  // by kychee-com/run402#566's --project half): when cwd is a repository
+  // TARGETING: when cwd is a repository
   // with its own pinned repo id or run402/origin remote, doctor checks THAT
   // vault, not the profile's active project — the same pin > remote >
   // RUN402_PROJECT_ID env > active-project order every other gitvault verb
@@ -683,8 +679,30 @@ export async function run(sub, args = []) {
           // to the durability sentence instead of the terminal-loss claim.
           covering_recipients: gv.covering_recipients ?? null,
           daemon: daemonInfo,
+          // gitvault-multi-writer (rev 47) task 6.2 — this machine's own
+          // standing on the vault's chain-verified writer set. `null` only
+          // when there is no vault at all (nothing to be a writer OF).
+          // `read_only_vault` takes priority over the caller's own standing
+          // — the D228 terminal state blocks EVERY push regardless of who
+          // is asking.
+          writer: gv.vault === null
+            ? null
+            : gv.vault.read_only_terminal
+              ? "read_only_vault"
+              : gv.vault.writer_set?.writers.some((w) => w.writer_key_id === gv.keystore.identity_fingerprint)
+                ? "active"
+                : gv.vault.pending_writers?.some((p) => p.writer_key_id === gv.keystore.identity_fingerprint)
+                  ? "pending"
+                  : "not_admitted",
         };
         const gaps = [];
+        if (value.writer === "read_only_vault") {
+          gaps.push("this vault has lost its last writer (D228 read-only terminal) — it still serves reads, but no push can be admitted until a new writer is admitted through a recovery path");
+        } else if (value.writer === "pending") {
+          gaps.push("this machine's key is an eligible writer candidate but not yet admitted — run 'run402 repos access sync' if you already hold writer standing on this vault, or ask a current writer to run any gitvault operation");
+        } else if (value.writer === "not_admitted") {
+          gaps.push("this machine's key is not an active writer on this vault — a push from here is refused GITVAULT_WRITER_NOT_ADMITTED; ask a current writer to admit you (org membership at role developer+ and a published signing key make you eligible)");
+        }
         // The one that actually breaks the next deploy: the project demands a
         // vaulted capture and THIS machine cannot produce one.
         if (gv.gitvault_policy === "required" && !gv.keystore.holds_repo_key) {
@@ -698,15 +716,14 @@ export async function run(sub, args = []) {
         if (gv.pending_overrides > 0) {
           gaps.push(`${gv.pending_overrides} unvaulted-override journal(s) are still open — run 'run402 repos snapshot' to drain them`);
         }
-        // `matches` is a TRI-STATE (kychee-com/run402#562): `false` alone is
+        // `matches` is a TRI-STATE: `false` alone is
         // a real mismatch. `null` (a slug-form remote not yet resolved on
-        // this machine) is not evidence of anything wrong — `!gv.remote.matches`
-        // used to treat null the same as false and would have warned here.
+        // this machine) is not evidence of anything wrong — a bare
+        // `!gv.remote.matches` would treat null the same as false and warn.
         if (gv.remote && gv.remote.matches === false) {
           gaps.push(`the '${gv.remote.name}' git remote points at a different project than ${value.project_id} (${gv.remote.url})`);
         }
-        // kygit-handoff design D8: the mirror of the OLD `npm i -g @kychee/kygit`
-        // bug, pointing the other way — a `kygit::` remote with no
+        // A `kygit::` remote with no
         // `git-remote-kygit` helper on PATH means every push/clone/fetch
         // in this checkout fails inside git with an opaque error.
         if (gv.remote?.url?.startsWith("kygit::")) {
@@ -786,8 +803,8 @@ export async function run(sub, args = []) {
   // direct mutation of internal.sessions.authz_version. Hits with severity
   // `error` block deploy (`run402 deploy` wraps doctor and respects exit
   // code). Skipped via --no-scan when the user wants config-only checks, and
-  // by any --only that omits it (kychee-com/run402#566 — this is the check
-  // that used to bury the gitvault diagnosis under ~1,800 monorepo findings).
+  // by any --only that omits it — on a monorepo this check's findings can
+  // otherwise bury the gitvault diagnosis under thousands of hits.
   if (!skipScan && wanted("source_scan")) {
     try {
       const scanRoot = scanDirOverride ?? resolveScanRoot(process.cwd());

package/lib/email.mjs

@@ -366,9 +366,8 @@ function mailboxIdFromSelector(envelope, selector, flag) {
   if (/^mbx_/.test(selector)) return selector;
   const hit = (envelope.mailboxes ?? []).find((m) => m.mailbox_id === selector || m.slug === selector);
   if (!hit) {
-    // A selector that matches nothing is a value we know nothing about — see
-    // core-dist/redact.js's doc comment (kychee-com/run402-private#640) —
-    // so it must not be echoed verbatim.
+    // A selector that matches nothing is a value we know nothing about (see
+    // core-dist/redact.js's doc comment), so it must not be echoed verbatim.
     fail({
       code: "MAILBOX_NOT_FOUND",
       message: `No mailbox matching ${JSON.stringify(describeRejectedValue(selector))} for ${flag}.`,

package/lib/harness-context.mjs

@@ -11,8 +11,7 @@
  * long its TTL has silently decayed, so a session that can re-derive its OWN
  * key independently of any local file needs no cache at all to pick up where
  * it left off. Two genuinely concurrent sessions must NEVER derive the same
- * key — that would be the #663 regression this design exists to avoid (see
- * run402-private's agent-presence.ts, resolvePresence's own comment) — so
+ * key — that is the regression this design exists to avoid — so
  * every source below is either a value the harness itself guarantees is
  * unique per session, or a value generated here and persisted only for THIS
  * checkout.

package/lib/init.mjs

@@ -404,7 +404,7 @@ export async function run(args = []) {
         const data = await res.json();
         if (data.result) {
           // Tempo faucet is "instant" on-chain, but the client RPC read can be
-          // racy relative to faucet settlement — poll up to 30s (GH-81), mirroring
+          // racy relative to faucet settlement — poll up to 30s, mirroring
           // the x402 path below.
           for (let i = 0; i < 30; i++) {
             await new Promise(r => setTimeout(r, 1000));

package/lib/next-actions.mjs

@@ -70,7 +70,7 @@ export function deployAction() {
 /**
  * `repos create` (and `gitvault init`) on an org with no claimed slug: the
  * response's `address: null` had no pointer to WHY, or to the named-addressing
- * feature at all (kychee-com/run402#560). Owner-only. Wording deliberately
+ * feature at all. Owner-only. Wording deliberately
  * omits a price: the first slug per org is free, and renames/re-claims cost
  * $1 — a gateway change lands the fee separately, so this stays true under
  * both the old and new pricing rule.

package/lib/org-context.mjs

@@ -39,7 +39,7 @@
  *   different organization than the caller named).
  */
 import { getSdk } from "./sdk.mjs";
-import { flagValue } from "./argparse.mjs";
+import { flagValue, positionalArgs } from "./argparse.mjs";
 import { findBindingKey } from "./wallet-context.mjs";
 import { fail } from "./sdk-errors.mjs";
 import { nextAction } from "./next-actions.mjs";
@@ -69,7 +69,7 @@ const trimmed = (v) => (typeof v === "string" && v.trim() ? v.trim() : null);
  * NEVER checked here — only that the value could be an org id at all.
  *
  * A rejected value is a value we know nothing about — see
- * core-dist/redact.js's doc comment (kychee-com/run402-private#640): the
+ * core-dist/redact.js's doc comment: the
  * same class of mistake that put a private key into RUN402_WALLET can put
  * one into RUN402_ORG / --org, so this must never echo the raw value.
  */
@@ -290,6 +290,87 @@ export async function resolveOrgId(a, opts = {}) {
   return resolved ? resolved.orgId : null;
 }
 
+/**
+ * The org-scoped POSITIONAL contract (cli-org-context, "One Resolver Serves
+ * Every Org-Scoped Command").
+ *
+ * `<org_id>` is optional sugar on every verb that acts on an organization —
+ * `org get`, `org member add`, `billing link-wallet`, … A leading positional
+ * that IS an org id (a UUID) addresses that org; anything else is the verb's
+ * own next positional (a wallet, an email, a principal) and the org comes from
+ * the shared chain: `--org`, then `RUN402_ORG`, then the `.run402.json`
+ * binding, then `org use`. So inside a bound checkout the two-agent case reads
+ * `run402 org member add 0xB… --role developer` with nothing else to know.
+ *
+ * Naming the org twice with different values (positional AND `--org`) is
+ * `AMBIGUOUS_ORG`, never a silent pick — the same refusal the env-vs-binding
+ * pair gets. A non-org first positional with no chain answer fails
+ * `ORG_REQUIRED` and NAMES the rejected value, so `org get foo` says why `foo`
+ * did not count rather than reporting a bare "no organization".
+ *
+ * Returns the org id with provenance plus the REMAINING positionals; bound
+ * those with {@link requireRest} using the verb's own usage line. Enforced
+ * mechanically: every `orgScoped` entry in the command manifest is driven
+ * through this shape by `cli-conventions-gate.test.mjs`.
+ *
+ * @param {string[]} a          normalized argv
+ * @param {string[]} valueFlags flags that take a value (must include "--org")
+ * @param {object}   [opts]     forwarded to {@link resolveOrg} (cmd, env, cwd)
+ */
+export async function takeOrgPositional(a, valueFlags = [], opts = {}) {
+  const positionals = positionalArgs(a, valueFlags);
+  const first = positionals[0];
+  if (typeof first === "string" && ORG_ID_RE.test(first)) {
+    const flag = trimmed(flagValue(a, "--org"));
+    if (flag && flag.toLowerCase() !== first.toLowerCase()) {
+      fail({
+        code: "AMBIGUOUS_ORG",
+        message: `Ambiguous organization: positional ${first} but --org ${flag}.`,
+        hint: "Name the organization once — as the leading <org_id> positional or as --org <org_id>, not both.",
+        details: {
+          candidates: [
+            { org_id: first, source: "positional", source_detail: "<org_id>" },
+            { org_id: flag, source: "flag", source_detail: "--org" },
+          ],
+        },
+      });
+    }
+    return { orgId: first, rest: positionals.slice(1), source: "positional", sourceDetail: "<org_id>" };
+  }
+  const resolved = await resolveOrg(a, { ...opts, optional: true });
+  if (resolved) return { orgId: resolved.orgId, rest: positionals, source: resolved.source, sourceDetail: resolved.sourceDetail };
+  fail({
+    code: "ORG_REQUIRED",
+    message: typeof first === "string"
+      ? `No organization specified and no current organization set (${JSON.stringify(first)} is not an org_id — an org_id is a UUID).`
+      : "No organization specified and no current organization set.",
+    hint: `Pass --org <org_id> (or a leading <org_id> positional), set ${ORG_ENV}, bind this directory in .run402.json, or run: run402 org use <org_id>`,
+    ...(typeof first === "string" ? { details: { rejected_positional: first } } : {}),
+    next_actions: orgRequiredActions(),
+  });
+  return null; // unreachable — fail() exits
+}
+
+/**
+ * Bound the positionals LEFT after {@link takeOrgPositional} took the org —
+ * the same `BAD_USAGE` shapes `requirePositionalCount` emits, on an array the
+ * caller already holds.
+ */
+export function requireRest(rest, opts = {}) {
+  const { min = 0, max = min, command = "command", missing = "Missing required argument." } = opts;
+  if (rest.length < min) {
+    fail({ code: "BAD_USAGE", message: missing, hint: command });
+  }
+  if (rest.length > max) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Unexpected argument for ${command}: ${rest[max]}`,
+      hint: `Use \`${command}\`.`,
+    });
+  }
+  return rest;
+}
+
 /** Validate an org id supplied by a human, naming the origin. Throws via fail(). */
 export function requireOrgIdShape(orgId, origin = "--org") {
   return assertOrgIdShape(orgId, origin);