@stigmer/cli 3.12.1 → 3.12.3

package/src/local/setup/wizard.ts

@@ -7,9 +7,9 @@
 // Local agent execution is Anthropic-only (the native runner only constructs
 // Anthropic clients and the registry's native entries are Anthropic models),
 // so the interactive flow is a single API-key prompt rather than a provider
-// menu. The model is deliberately NOT asked for: the platform model registry
-// owns the execution default, and an explicit override is a power-user flag
-// (`stigmer setup --model …`), not a setup question.
+// menu. There is no model concept here at all: the platform model registry
+// owns the execution default, and per-run overrides belong to `stigmer run
+// --model` (oss#314 removed the dead setup-level pin).
 
 import type { Config } from "../../config/config.js";
 import { type LlmSettings, setLlm } from "../llm-config.js";
@@ -27,19 +27,17 @@ export type ProviderChoice = (typeof PROVIDER_CHOICES)[number];
 
 export interface SelectionInputs {
   apiKey?: string;
-  model?: string;
 }
 
 /**
- * Resolve a provider choice (plus optional overrides) to the LLM settings to
- * persist. "skip" yields `undefined`, which clears the section. An omitted
- * model is stored as absent — meaning "platform default", resolved from the
- * model registry at execution time.
+ * Resolve a provider choice (plus an optional API key) to the LLM settings to
+ * persist. "skip" yields `undefined`, which clears the section — including any
+ * stale `model` key from a pre-oss#314 config, since setLlm replaces the
+ * section wholesale.
  */
 export function buildLlmForChoice(choice: ProviderChoice, inputs: SelectionInputs = {}): LlmSettings | undefined {
   if (choice === "skip") return undefined;
   const settings: LlmSettings = { provider: choice };
-  if (inputs.model) settings.model = inputs.model;
   if (inputs.apiKey) settings.api_key = inputs.apiKey;
   return settings;
 }

package/src/local/state/startup-config.ts

@@ -1,19 +1,23 @@
-// Configuration captured at `up` time so the daemon can restart components with
-// the same settings the user launched with. Persisted as `startup-config.json`
-// in the data dir; JSON keys are snake_case to match the Go CLI's file.
+// A diagnostic snapshot of the settings `up` launched with, persisted as
+// `startup-config.json` in the data dir and removed by `down`. Nothing in the
+// CLI or daemon reads it back — it exists for humans and support tooling
+// inspecting a running stack, so keep it truthful: a field that no component
+// consumes does not belong here (oss#314 removed the write-only llm_* trio).
+// JSON keys stay snake_case for continuity with previously-written files.
 
 import { readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { STARTUP_CONFIG_FILE } from "../constants.js";
 
-/** The persisted launch configuration. Mirrors the Go `StartupConfig` struct. */
+/**
+ * The persisted launch snapshot. `loadStartupConfig` parses leniently (a cast,
+ * not a validator), so files written by older CLIs with extra fields — e.g.
+ * the removed llm_* trio — load without migration.
+ */
 export interface StartupConfig {
   data_dir: string;
   log_dir: string;
   temporal_addr: string;
-  llm_provider: string;
-  llm_model: string;
-  llm_base_url: string;
   execution_mode: string;
   sandbox_image: string;
   sandbox_auto_pull: boolean;

package/src/local/state/state.test.ts

@@ -82,9 +82,6 @@ describe("startup-config", () => {
       data_dir: dir,
       log_dir: join(dir, "logs"),
       temporal_addr: "127.0.0.1:7233",
-      llm_provider: "anthropic",
-      llm_model: "claude",
-      llm_base_url: "",
       execution_mode: "local",
       sandbox_image: "",
       sandbox_auto_pull: false,
@@ -98,6 +95,29 @@ describe("startup-config", () => {
     removeStartupConfig(dir);
     expect(loadStartupConfig(dir)).toBeNull();
   });
+
+  it("loads files written by older CLIs carrying since-removed fields (e.g. the llm_* trio)", () => {
+    // The lenient-load contract oss#314 leans on: no migration for on-disk
+    // files — extra keys simply come along and nothing consumes them.
+    const dir = tempDir("stigmer-startup-");
+    const legacy = {
+      data_dir: dir,
+      log_dir: join(dir, "logs"),
+      temporal_addr: "127.0.0.1:7233",
+      llm_provider: "anthropic",
+      llm_model: "claude",
+      llm_base_url: "",
+      execution_mode: "local",
+      sandbox_image: "",
+      sandbox_auto_pull: false,
+      sandbox_cleanup: true,
+      sandbox_ttl: 0,
+      stigmer_server_pid: 999,
+      server_only: false,
+    };
+    writeFileSync(join(dir, "startup-config.json"), JSON.stringify(legacy));
+    expect(loadStartupConfig(dir)).toMatchObject({ temporal_addr: "127.0.0.1:7233", stigmer_server_pid: 999 });
+  });
 });
 
 describe("log-rotation", () => {

package/src/local/status.test.ts

@@ -62,12 +62,12 @@ describe("buildStatusResult", () => {
     expect(field(result, "Web UI", "Temporal")).toBe("http://localhost:8233");
   });
 
-  it("shows an explicit model override verbatim", async () => {
+  it("ignores a stale model key from a pre-oss#314 config — the pin never reached execution, so status must not display it", async () => {
     writeHealth({ daemon_pid: process.pid, started_at: new Date().toISOString(), components: {} });
     writeFileSync(configPath(home), "backend:\n  type: local\n  local:\n    llm:\n      provider: anthropic\n      model: claude-x\n      api_key: sk-x\n");
 
     const result = await buildStatusResult(home, open);
-    expect(field(result, "LLM Configuration", "Model")).toBe("claude-x");
+    expect(field(result, "LLM Configuration", "Model")).toBe("Auto (platform default)");
   });
 
   it("reports a non-anthropic provider as unknown — local execution is Anthropic-only", async () => {

package/src/local/status.ts

@@ -13,7 +13,7 @@ import { load as loadConfig } from "../config/config.js";
 import { configPath } from "../config/paths.js";
 import { CommandResult } from "../output/command-result.js";
 import { SERVER_PORT, TEMPORAL_UI_PORT, WEB_CONSOLE_PORT } from "./constants.js";
-import { resolveApiKey, resolveModel, resolveProvider } from "./llm-config.js";
+import { resolveApiKey, resolveProvider } from "./llm-config.js";
 import { tcpConnects } from "./net/tcp.js";
 import { dataDir } from "./paths.js";
 import { type ComponentState, type HealthState, loadHealthState } from "./state/health-state.js";
@@ -130,12 +130,11 @@ function addLlmSection(result: CommandResult, home: string): void {
     return;
   }
 
-  // An unset model is not a gap: the platform model registry picks the
-  // execution default, so the CLI reports that truthfully instead of asserting
-  // a version it does not control.
-  const model = resolveModel(config);
+  // The model line is a constant: the platform model registry picks the
+  // execution default and the CLI has no model concept to report (oss#314
+  // removed the dead config pin). Per-run overrides ride `stigmer run --model`.
   section.field("Provider", "Anthropic (Cloud)");
-  section.field("Model", model !== "" ? model : "Auto (platform default)");
+  section.field("Model", "Auto (platform default)");
   section.field("API Key", resolveApiKey(config) !== "" ? "Configured ✓" : "Not configured ✗");
 }
 

package/src/resources/skill.test.ts

@@ -1,13 +1,16 @@
 // Unit tests for the skill packaging layer: SKILL.md frontmatter parsing, the
 // ignore-filtered zip walk, dry-run analysis, and byte/hash formatting.
 
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { PushSkillRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import type { Stigmer } from "@stigmer/sdk";
-import { unzipSync } from "fflate";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { unzipSync, zipSync } from "fflate";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { classify, ExitCode } from "../errors/index.js";
 import {
   analyzeDryRun,
@@ -16,7 +19,10 @@ import {
   hasSkillFile,
   parseSkillMetadata,
   parseVisibility,
+  pushRouted,
   pushSkill,
+  pushSkillFromArchive,
+  readSkillArchive,
   shortHash,
 } from "./skill.js";
 
@@ -113,12 +119,17 @@ describe("parseVisibility", () => {
 
 // A minimal fake of the SDK surface pushSkill touches: skill.push + skill.updateVisibility.
 function fakeClient(pushMeta: { id?: string; visibility?: ApiResourceVisibility }) {
-  const calls = { push: 0, updateVisibility: [] as Array<{ resourceId: string; visibility: ApiResourceVisibility }> };
+  const calls = {
+    push: 0,
+    pushedArtifacts: [] as Uint8Array[],
+    updateVisibility: [] as Array<{ resourceId: string; visibility: ApiResourceVisibility }>,
+  };
   const skillMessage = { metadata: { ...pushMeta } };
   const client = {
     skill: {
-      async push() {
+      async push(request?: { artifact?: Uint8Array }) {
         calls.push++;
+        if (request?.artifact !== undefined) calls.pushedArtifacts.push(request.artifact);
         return skillMessage;
       },
       async updateVisibility(input: { resourceId: string; visibility: ApiResourceVisibility }) {
@@ -199,6 +210,113 @@ describe("createSkillZip", () => {
   });
 });
 
+describe("createSkillZip determinism", () => {
+  // Version identity is the server-side SHA-256 of the zip bytes, so identical
+  // content must produce identical bytes no matter when or where it was
+  // checked out (stigmer/stigmer#671). Distinct source mtimes model the fresh
+  // CI checkout; distinct wall-clock runs are inherent to running twice.
+  it("produces byte-identical zips for identical content across mtimes and wall-clock time", () => {
+    const otherDir = mkdtempSync(join(tmpdir(), "skill-test-b-"));
+    vi.useFakeTimers();
+    try {
+      for (const d of [dir, otherDir]) {
+        writeFileSync(join(d, "SKILL.md"), SKILL_MD);
+        mkdirSync(join(d, "references"));
+        writeFileSync(join(d, "references", "guide.md"), "# Guide\n");
+      }
+      // Backdate one copy: same content, different filesystem timestamps
+      // (models a fresh CI checkout).
+      const past = new Date("2020-06-15T12:00:00Z");
+      utimesSync(join(otherDir, "SKILL.md"), past, past);
+      utimesSync(join(otherDir, "references", "guide.md"), past, past);
+
+      // Advance the clock between runs: without a pinned mtime, fflate stamps
+      // zip-creation time into every entry (DOS 2-second granularity), so two
+      // pushes minutes apart would differ even from the same directory.
+      vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+      const a = createSkillZip(dir, NO_IGNORE).bytes;
+      vi.setSystemTime(new Date("2026-01-01T00:05:00Z"));
+      const b = createSkillZip(otherDir, NO_IGNORE).bytes;
+      expect(Buffer.from(a).equals(Buffer.from(b))).toBe(true);
+    } finally {
+      vi.useRealTimers();
+      rmSync(otherDir, { recursive: true, force: true });
+    }
+  });
+
+  it("changes bytes when content changes", () => {
+    writeFileSync(join(dir, "SKILL.md"), SKILL_MD);
+    const before = createSkillZip(dir, NO_IGNORE).bytes;
+    writeFileSync(join(dir, "extra.md"), "new content\n");
+    const after = createSkillZip(dir, NO_IGNORE).bytes;
+    expect(Buffer.from(before).equals(Buffer.from(after))).toBe(false);
+  });
+});
+
+describe("readSkillArchive", () => {
+  function writeArchive(files: Record<string, string>): string {
+    const zipped = zipSync(
+      Object.fromEntries(Object.entries(files).map(([p, c]) => [p, new TextEncoder().encode(c)])),
+    );
+    const archivePath = join(dir, "skill.zip");
+    writeFileSync(archivePath, zipped);
+    return archivePath;
+  }
+
+  it("accepts an archive with a root SKILL.md and reports entry stats", () => {
+    const archivePath = writeArchive({
+      "SKILL.md": SKILL_MD,
+      "references/guide.md": "# Guide\n",
+    });
+    const archive = readSkillArchive(archivePath);
+    expect(archive.meta.name).toBe("my-skill");
+    expect(archive.fileCount).toBe(2);
+    expect(archive.totalSize).toBeGreaterThan(0);
+  });
+
+  it("rejects an archive whose SKILL.md is only nested (root-only contract, DD-018)", () => {
+    const archivePath = writeArchive({ "my-skill/SKILL.md": SKILL_MD });
+    expect(() => readSkillArchive(archivePath)).toThrow(/root of/);
+  });
+
+  it("rejects a file that is not a ZIP archive", () => {
+    const archivePath = join(dir, "not-a-zip.zip");
+    writeFileSync(archivePath, "plain text");
+    expect(() => readSkillArchive(archivePath)).toThrow(/not a valid ZIP/);
+  });
+
+  it("rejects a missing file with a usage error", () => {
+    const err = (() => {
+      try {
+        readSkillArchive(join(dir, "absent.zip"));
+      } catch (e) {
+        return e;
+      }
+    })();
+    expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+  });
+});
+
+describe("pushSkillFromArchive", () => {
+  it("uploads the archive bytes untouched (checksum parity) and applies declared visibility", async () => {
+    const zipped = zipSync({
+      "SKILL.md": new TextEncoder().encode("---\nname: my-skill\nvisibility: public\n---\n# S\n"),
+    });
+    const archivePath = join(dir, "skill.zip");
+    writeFileSync(archivePath, zipped);
+    const { client, calls } = fakeClient({ id: "skill-123", visibility: ApiResourceVisibility.visibility_private });
+
+    const result = await pushSkillFromArchive(client, archivePath, "stigmer", "", "release v1.2.3");
+
+    expect(calls.push).toBe(1);
+    expect(Buffer.from(calls.pushedArtifacts[0]).equals(Buffer.from(zipped))).toBe(true);
+    expect(calls.updateVisibility).toEqual([
+      { resourceId: "skill-123", visibility: ApiResourceVisibility.visibility_public },
+    ]);
+    expect(result.skillName).toBe("my-skill");
+  });
+});
+
 describe("analyzeDryRun", () => {
   it("reports counts and pattern sources without producing bytes", () => {
     writeFileSync(join(dir, "SKILL.md"), SKILL_MD);
@@ -235,3 +353,77 @@ describe("formatBytes / shortHash", () => {
     expect(shortHash("abc")).toBe("sha256:abc");
   });
 });
+
+// ─── pushRouted — transfer-lane size routing (#675) ──────────────────────
+
+describe("pushRouted size routing", () => {
+  const INLINE_MAX = 10 * 1024 * 1024 - 64 * 1024;
+
+  function routingFakeClient(overrides: Record<string, any> = {}) {
+    const calls = { push: [] as any[], mint: [] as any[] };
+    const client = {
+      skill: {
+        async push(req: any) {
+          calls.push.push(req);
+          return { metadata: { id: "skill_x" } };
+        },
+        async createArtifactUploadUrl(req: any) {
+          calls.mint.push(req);
+          return { url: "http://localhost:7234/v1/skill-artifacts/uploads/sau_t", artifactUploadRef: "sau_t", ttlSeconds: 900 };
+        },
+        ...overrides,
+      },
+    } as any;
+    return { client, calls };
+  }
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("keeps small artifacts inline (no mint, bytes in the request)", async () => {
+    const { client, calls } = routingFakeClient();
+    const req = create(PushSkillRequestSchema, { org: "acme", artifact: new Uint8Array(1024) });
+
+    await pushRouted(client, req);
+
+    expect(calls.mint).toHaveLength(0);
+    expect(calls.push).toHaveLength(1);
+    expect(calls.push[0].artifact.length).toBe(1024);
+  });
+
+  it("stages large artifacts over HTTP and pushes by reference", async () => {
+    const { client, calls } = routingFakeClient();
+    const artifact = new Uint8Array(INLINE_MAX + 1);
+    const req = create(PushSkillRequestSchema, { org: "acme", artifact, tag: "stable", message: "big" });
+
+    let putBytes = 0;
+    vi.stubGlobal("fetch", vi.fn(async (_url: string, init: any) => {
+      putBytes = init.body.length;
+      return { ok: true } as any;
+    }));
+
+    await pushRouted(client, req);
+
+    expect(calls.mint).toHaveLength(1);
+    expect(calls.mint[0].sizeBytes).toBe(BigInt(artifact.length));
+    expect(putBytes).toBe(artifact.length);
+    expect(calls.push).toHaveLength(1);
+    expect(calls.push[0].artifact.length).toBe(0);
+    expect(calls.push[0].artifactUploadRef).toBe("sau_t");
+    // The rewrite must not lose the rest of the request.
+    expect(calls.push[0].tag).toBe("stable");
+    expect(calls.push[0].message).toBe("big");
+  });
+
+  it("fails loud against servers that predate the transfer lane", async () => {
+    const { client } = routingFakeClient({
+      async createArtifactUploadUrl() {
+        throw new ConnectError("unknown method", Code.Unimplemented);
+      },
+    });
+    const req = create(PushSkillRequestSchema, { org: "acme", artifact: new Uint8Array(INLINE_MAX + 1) });
+
+    await expect(pushRouted(client, req)).rejects.toThrow(/Upgrade stigmer-server/);
+  });
+});

package/src/resources/skill.ts

@@ -8,19 +8,32 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
 import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
-import { PushSkillRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import type { PushSkillRequest } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import { CreateSkillArtifactUploadUrlRequestSchema, PushSkillRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
 import { GitProvenanceSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/status_pb";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { UpdateVisibilityInputSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import type { Stigmer } from "@stigmer/sdk";
-import { zipSync } from "fflate";
+import { strFromU8, unzipSync, zipSync } from "fflate";
 import { parse as parseYaml } from "yaml";
 import { UsageError } from "../errors/index.js";
 import { getGitBranchName, getGitCommit, getGitRemoteUrl, getGitRepoRoot } from "./git.js";
 import { createMatcher, REASON_TEXT, type Reason } from "./ignore/index.js";
 
 export const SKILL_FILE = "SKILL.md";
+
+// A skill version's identity is the server-side SHA-256 of the uploaded zip
+// bytes, so packaging must be a pure function of content — otherwise
+// re-pushing unchanged content registers a new version and the server's
+// unchanged-content no-op never fires (stigmer/stigmer#671). fflate stamps
+// zip-creation time into every entry when no mtime is given; pinning the DOS
+// epoch (the earliest representable zip timestamp) removes the only
+// byte-level variance. Local-field Date construction is deliberate: DOS
+// timestamps store wall-clock fields, so this encodes identically in every
+// timezone.
+const DETERMINISTIC_ZIP_MTIME = new Date(1980, 0, 1);
 // Kebab-case, optionally scoped with dot-separated namespaces (e.g.
 // "platform.planton-architecture"). Every segment must be alphanumeric, so no
 // leading/trailing/consecutive separators. The derived slug renders dots as hyphens.
@@ -102,7 +115,16 @@ export function parseSkillMetadata(dir: string): SkillMetadata {
   } catch (err) {
     throw new Error(`failed to read ${SKILL_FILE}: ${(err as Error).message}`);
   }
+  return parseSkillMetadataContent(content);
+}
 
+/**
+ * Parse SKILL.md content directly — the shared core behind the directory
+ * path (`parseSkillMetadata`) and the pre-packaged archive path
+ * (`pushSkillFromArchive`), where the content comes out of a zip entry
+ * rather than the filesystem.
+ */
+export function parseSkillMetadataContent(content: string): SkillMetadata {
   const frontmatter = extractFrontmatter(content);
   const parsed = (parseYaml(frontmatter) ?? {}) as Record<string, unknown>;
   const name = typeof parsed.name === "string" ? parsed.name : "";
@@ -233,7 +255,7 @@ export function createSkillZip(
   };
   walk(dir, "");
 
-  const bytes = zipSync(files, { level: 6 });
+  const bytes = zipSync(files, { level: 6, mtime: DETERMINISTIC_ZIP_MTIME });
   return { bytes, stats };
 }
 
@@ -300,6 +322,68 @@ export function analyzeDryRun(dir: string, options: IgnoreOptions): DryRunAnalys
   return { stats, patternSources, sampleIgnored, sampleIncluded };
 }
 
+/**
+ * Largest artifact pushed inline in the gRPC request (#675). The server's
+ * transport cap is 10MB for the WHOLE message, so the artifact leaves 64KB
+ * of headroom for the request envelope (org, tag, provenance, framing).
+ * Mirrors the Go SDK's maxInlineArtifactBytes.
+ */
+const MAX_INLINE_ARTIFACT_BYTES = 10 * 1024 * 1024 - 64 * 1024;
+
+/**
+ * Push, routing the artifact by size (#675): small artifacts travel inline
+ * in the request (one round trip, unchanged behavior); larger ones are
+ * staged over HTTP via createArtifactUploadUrl — a capability URL, so no
+ * auth header — and pushed by reference. The 100MB skill limit therefore
+ * no longer collides with the 10MB gRPC message cap.
+ */
+export async function pushRouted(client: Stigmer, request: PushSkillRequest): Promise<Skill> {
+  if (request.artifact.length <= MAX_INLINE_ARTIFACT_BYTES) {
+    return client.skill.push(request);
+  }
+
+  let minted;
+  try {
+    minted = await client.skill.createArtifactUploadUrl(
+      create(CreateSkillArtifactUploadUrlRequestSchema, {
+        org: request.org,
+        sizeBytes: BigInt(request.artifact.length),
+      }),
+    );
+  } catch (err) {
+    if (err instanceof ConnectError && err.code === Code.Unimplemented) {
+      // Pre-transfer-lane server: an artifact this size physically cannot
+      // travel inline. Say so instead of surfacing the raw transport error.
+      throw new UsageError(
+        `skill artifact is ${formatBytes(request.artifact.length)}, above the ~10MB gRPC message cap, ` +
+          "and this server does not support the HTTP artifact transfer lane.\n\n" +
+          "Upgrade stigmer-server to push skills of this size.",
+      );
+    }
+    throw err;
+  }
+
+  const resp = await fetch(minted.url, {
+    method: "PUT",
+    // Buffer keeps undici's BodyInit typing happy where a bare Uint8Array
+    // view does not (Node-only code path, so Buffer is always available).
+    body: Buffer.from(request.artifact),
+    headers: { "content-type": "application/zip" },
+  });
+  if (!resp.ok) {
+    const detail = (await resp.text().catch(() => "")).slice(0, 512).trim();
+    throw new Error(`skill artifact upload rejected with HTTP ${resp.status}${detail === "" ? "" : `: ${detail}`}`);
+  }
+
+  // Same request, artifact traveling by reference instead of by value.
+  const byRef = create(PushSkillRequestSchema, {
+    ...request,
+    artifact: new Uint8Array(0),
+    artifactUploadRef: minted.artifactUploadRef,
+  });
+  return client.skill.push(byRef);
+}
+
 /** Push a skill from a local directory. Git provenance is auto-detected. */
 export async function pushSkill(
   client: Stigmer,
@@ -326,7 +410,7 @@ export async function pushSkill(
     message,
     gitProvenance: provenance,
   });
-  const response = await client.skill.push(request);
+  const response = await pushRouted(client, request);
   const applied = await applyDeclaredVisibility(client, response, visibility);
   return toResult(applied, name, message, stats.totalSize, visibility);
 }
@@ -368,11 +452,99 @@ export async function pushSkillFromClone(
     message: params.message,
     gitProvenance: provenance,
   });
-  const response = await client.skill.push(request);
+  const response = await pushRouted(client, request);
   const applied = await applyDeclaredVisibility(client, response, visibility);
   return toResult(applied, name, params.message, stats.totalSize, visibility);
 }
 
+/** A validated pre-packaged skill archive (`--archive`), ready to upload. */
+export interface SkillArchive {
+  /** The archive file's exact bytes — uploaded untouched. */
+  readonly bytes: Uint8Array;
+  /** Metadata parsed from the archive's root SKILL.md. */
+  readonly meta: SkillMetadata;
+  /** Number of file entries (directory markers excluded). */
+  readonly fileCount: number;
+  /** Total uncompressed size of all file entries, in bytes. */
+  readonly totalSize: number;
+}
+
+/**
+ * Read and validate a pre-packaged skill archive.
+ *
+ * Client-side validation is deliberately minimal — root SKILL.md present and
+ * frontmatter parses (the same contract the console's upload preview checks);
+ * the server remains the authoritative validator. The unzip filter inflates
+ * ONLY SKILL.md: entry metadata is enough for the count/size summary, and
+ * validation must not pay for decompressing a large artifact.
+ */
+export function readSkillArchive(archivePath: string): SkillArchive {
+  let raw: Buffer;
+  try {
+    raw = readFileSync(archivePath);
+  } catch (err) {
+    throw new UsageError(`failed to read archive ${archivePath}: ${(err as Error).message}`);
+  }
+  const bytes = new Uint8Array(raw);
+
+  let fileCount = 0;
+  let totalSize = 0;
+  let unzipped: Record<string, Uint8Array>;
+  try {
+    unzipped = unzipSync(bytes, {
+      filter: (info) => {
+        if (!info.name.endsWith("/")) {
+          fileCount++;
+          totalSize += info.originalSize;
+        }
+        return info.name === SKILL_FILE;
+      },
+    });
+  } catch (err) {
+    throw new UsageError(`${archivePath} is not a valid ZIP archive: ${(err as Error).message}`);
+  }
+
+  const skillMd = unzipped[SKILL_FILE];
+  if (skillMd === undefined) {
+    throw new UsageError(
+      `${SKILL_FILE} not found at the root of ${archivePath}\n\n` +
+        `A skill archive must contain ${SKILL_FILE} at its root (not inside a directory) defining the skill interface`,
+    );
+  }
+
+  return { bytes, meta: parseSkillMetadataContent(strFromU8(skillMd)), fileCount, totalSize };
+}
+
+/**
+ * Push a pre-packaged skill archive as-is (`--archive`).
+ *
+ * The bytes are uploaded untouched, so the engine's version hash is the
+ * SHA-256 of the file on disk — release pipelines that publish checksums get
+ * engine version identities that match them (stigmer/stigmer#671). Git
+ * provenance is deliberately omitted: the archive was built elsewhere, so the
+ * local checkout says nothing about the artifact's origin.
+ */
+export async function pushSkillFromArchive(
+  client: Stigmer,
+  archivePath: string,
+  org: string,
+  tag: string,
+  message: string,
+): Promise<PushResult> {
+  const archive = readSkillArchive(archivePath);
+  const request = create(PushSkillRequestSchema, {
+    org,
+    artifact: archive.bytes,
+    tag: tag === "" ? "latest" : tag,
+    message,
+  });
+  // Size-routed like every other push path (#675): pre-packaged archives are
+  // the release-pipeline lane, exactly where content-heavy skills come from.
+  const response = await pushRouted(client, request);
+  const applied = await applyDeclaredVisibility(client, response, archive.meta.visibility);
+  return toResult(applied, archive.meta.name, message, archive.totalSize, archive.meta.visibility);
+}
+
 /**
  * Apply the SKILL.md-declared visibility after a push. The push RPC carries
  * artifact + provenance but not access level (visibility is metadata, not part