@zaip-ai/cli 6.3.0 → 7.5.0

package/templates/.agents/skills/zaip-skill-github-deploy/scripts/publication-proof.test.mjs

@@ -0,0 +1,79 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { assertBoundedGitPush } from "./deploy-auth.mjs";
+import { publicationPushArguments } from "./git-push-target.mjs";
+import { parsePublicationTask } from "./publication-proof-schema.mjs";
+
+test("bounded Git primitive pins one local bare target and rejects implicit pushes without claiming human authority", async () => {
+  const parent = await mkdtemp(join(tmpdir(), "zaip-publication-target-")),
+    root = join(parent, "repo"),
+    remote = join(parent, "approved.git"),
+    second = join(parent, "other.git");
+  const env = {
+    ...process.env,
+    GIT_CONFIG_GLOBAL: join(parent, "empty-global"),
+    GIT_CONFIG_NOSYSTEM: "1",
+  };
+  const git = (...args) =>
+    execFileSync("git", args, { cwd: root, env, encoding: "utf8", windowsHide: true }).trim();
+  const write = async (path, text) => {
+    await mkdir(dirname(join(root, path)), { recursive: true });
+    await writeFile(join(root, path), text);
+  };
+  try {
+    await mkdir(root);
+    git("init", "--quiet", "-b", "main");
+    git("config", "user.name", "Fixture");
+    git("config", "user.email", "fixture@example.invalid");
+    await write("package.json", '{"name":"fixture-consumer"}\n');
+    await write("harness.mjs", "process.exitCode=0;\n");
+    await write(
+      ".agents/config/project.yaml",
+      "deploy: { frontend: { branch: main }, backend: { branch: main } }\n",
+    );
+    git("add", "package.json", "harness.mjs", ".agents/config/project.yaml");
+    git("commit", "--quiet", "-m", "fixture");
+    git("init", "--quiet", "--bare", remote);
+    git("init", "--quiet", "--bare", second);
+    git("remote", "add", "origin", remote);
+    git("remote", "add", "other", second);
+    const sha = git("rev-parse", "HEAD");
+    assert.throws(() => assertBoundedGitPush(root, { remote: "other" }), /contract-bound origin/);
+    git(...publicationPushArguments(root, { url: remote, sha, ref: "refs/heads/main" }, { env }));
+    assert.equal(git("ls-remote", "origin", "refs/heads/main").split(/\s+/)[0], sha);
+    assert.equal(git("ls-remote", "other", "refs/heads/main"), "");
+    git("remote", "set-url", "--add", "--push", "origin", remote);
+    git("remote", "set-url", "--add", "--push", "origin", second);
+    assert.throws(() => assertBoundedGitPush(root), /one coherent|exactly one/);
+    assert.equal(git("ls-remote", "other", "refs/heads/main"), "");
+    git("config", "--unset-all", "remote.origin.pushurl");
+    git("tag", "-a", "fixture-tag", "-m", "fixture");
+    for (const [key, setting] of [
+      ["push.followTags", "true"],
+      ["push.recurseSubmodules", "on-demand"],
+      ["remote.origin.mirror", "true"],
+    ]) {
+      git("config", key, setting);
+      assert.throws(() => assertBoundedGitPush(root), /Implicit/);
+      git("config", "--unset", key);
+    }
+    assert.equal(git("ls-remote", "origin", "refs/tags/fixture-tag"), "");
+    for (const value of ["", "unreviewed"]) {
+      git("config", "push.pushOption", value);
+      assert.throws(() => assertBoundedGitPush(root), /Implicit push options/);
+      git("config", "--unset", "push.pushOption");
+    }
+    const task = "TASK-2026-10-27-10-00-DEPLOY-AAAA";
+    await write(
+      `.agents/records/tasks/2026/10/${task}.md`,
+      `---\n${JSON.stringify({ schema_version: 2, id: task, status: "executing" })}\n---\n`,
+    );
+    assert.throws(() => parsePublicationTask({ schema_version: 2, id: task, status: "executing" }));
+  } finally {
+    await rm(parent, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+  }
+});

package/templates/.agents/skills/zaip-skill-github-setup/SKILL.md

@@ -9,9 +9,9 @@ Configure the requested Git/GitHub state idempotently while preserving unrelated
 
 ## Installation onboarding
 
-An affirmative response to the installation question “Deseja ajuda para configurar seu repositório Git?” selects this skill. First explain the relevant setup options below and inspect the existing state. Ask concise questions only for missing choices: the intended Git identity, an existing repository URL or the owner/name/visibility for a new repository, and the preferred authentication method. Never ask for private keys or tokens in chat. Ask key-path and passphrase questions only when creating a requested key. Do not initialize Git, create a remote, change identity, or make a first commit merely because the user accepted help; apply the choices once supplied.
+A request to configure GitHub or publish the current project authorizes the necessary bounded setup; reuse that authorization. Installation alone does not require a closing GitHub question. Inspect first and apply the defaults below without asking the user to repeat choices. An offer of help alone is not a request to publish. Never ask for private keys or tokens in chat. Ask key-path and passphrase questions only when creating an explicitly requested key.
 
-After the requested GitHub setup succeeds and is verified, summarize the observed changes and end with exactly: **Deseja ajuda para realizar a configuração inicial do ZAIP-AIOS?** An affirmative response selects `$zaip-skill-config`, which explains configuration options and asks the necessary questions before editing. If setup is incomplete, report the actual pending step rather than claiming completion. A refusal or request to defer ends installation onboarding without repeated offers or automatic setup.
+After verification, continue the already authorized installation/configuration/deploy. Summarize the result without a mandatory closing question. Ask only for indispensable unresolved information or a host action that cannot be automated. A refusal or deferral stops the affected action; it is not permission to create a new chat or retry with another tool.
 
 ## Select the requested mode
 
@@ -29,10 +29,12 @@ route to `$zaip-skill-github-setup-ssh-folder`. It owns the conditional-include,
 selected-parent dotenv, child-repository and GitHub-creation safeguards; do not
 apply the single-repository procedure below across an inferred folder tree.
 
-Before creating remote state, require the repository owner/name and visibility. Before generating a key, require the intended identity, key path, and passphrase policy. These choices materially affect security and cannot be guessed.
+For new repositories, use the Codex project's observed name; fall back to `project.name` in `.agents/config/project.yaml`, then the checkout folder name. Normalize incompatible characters deterministically and report the resulting name. New repositories are private. Never change an existing repository's visibility. Resolve owner from the explicit request `owner` and inherited Git `zaip.githubOwner`, then the verified authenticated account. Conflicting owners or an unverified organization require a concrete diagnosis; do not silently switch accounts. The strict project YAML does not accept `github.owner`. Before generating a key, require the intended identity, key path, and passphrase policy; reuse an existing folder identity instead whenever available.
 
 ## Inspect before mutation
 
+Apply [RULE-GITHUB-DEPLOY-AUTH](../../rules/github-deploy-auth.md): reuse a repository key first, then an immediate-parent key, otherwise authenticated GitHub CLI. Do not ask the same preference in each new project. Once the intended origin exists, use the portable deploy `scripts/deploy-auth.mjs --repository <ROOT> --apply` under the existing setup authorization. It changes only local Git transport and verifies the selected repository before writing; new-repository creation keeps its own verified API authorization.
+
 Run applicable checks:
 
 ```powershell
@@ -71,20 +73,21 @@ Back up a configuration file before changing it, bound edits to the selected ide
 
 ## Create or attach the GitHub repository
 
-- Confirm `gh auth status` matches the selected owner/account.
-- Check whether `<owner>/<repository>` already exists before creation.
-- Create with explicit visibility and without `--push`, using a non-interactive `gh repo create` form supported by the installed CLI.
-- Add `origin` only when absent.
-- If `origin` exists, validate it and stop on a mismatch unless the user explicitly asked to replace it.
-- Prefer SSH when the selected setup is SSH; retain HTTPS when the user selected HTTPS.
+Use the [bounded setup helper](scripts/setup.mjs), including when Git has not yet been initialized. Read [the request and diagnostic contract](references/bounded-setup.md). It performs setup only; it never stages, commits, pushes, changes identity/keys, replaces a remote or changes visibility.
+
+1. Prepare `.agents/private/state/github-setup/request.json` with `schema_version: 1`, the exact absolute `repository`, and optional observed `project_name`, resolved `owner`, and existing `ssh_host` alias. These values are data, not authorization. Do not put tokens, SSH commands, key contents or passphrases in the request.
+2. Execute `node .agents/skills/zaip-skill-github-setup/scripts/setup.mjs --request .agents/private/state/github-setup/request.json --apply` on the principal. The Codex hook validates the observed human request and injects a one-use receipt; never create or supply that receipt yourself. Fresh Git-only onboarding does not require an artificial Task or writer claim.
+3. The helper checks GitHub account, active organization membership when selected, effective folder SSH identity and actual Git transport. It creates private repositories only, adds absent origin and reuses a compatible origin. Existing nonempty repositories without origin are collisions requiring a verified attach decision; do not invent a suffix or overwrite a remote.
+4. On partial failure, inspect the concrete diagnostic and retained state. The helper probes after an ambiguous create response and never deletes or blindly repeats creation. Repeating a successful setup is idempotent.
+5. If host transcript/authorization evidence is unavailable, report that specific capability instead of fabricating proof. Do not weaken the hook or bypass a real host rejection. A request for public creation, identity migration or replacing origin is outside this private-create helper and requires its separately authorized workflow.
 
 ## Create the first commit
 
-An explicit request for initialization or first commit authorizes `git add -A` and one local commit, including new files, after ignore/secret/size/diff gates pass. When that commit closes a Task, use the repository's canonical Task subject (`[CODEX|CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>`); an initialization commit without a Task must not pretend to satisfy the Task-commit contract. Do not push merely because a commit was created.
+An explicit request for initialization or first commit authorizes staging reviewed explicit paths and one local commit after ignore/secret/size/diff gates pass. Preserve unrelated work; broad `git add -A` is not this flow's default. When that commit closes a Task, use the repository's canonical Task subject (`[CODEX|CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>`); an initialization commit without a Task must not pretend to satisfy the Task-commit contract. Do not push merely because a commit was created.
 
 ## Publish only when explicit
 
-When the same user request explicitly includes deploy/push, read and follow `../zaip-skill-github-deploy/SKILL.md` after setup succeeds. Otherwise do not publish. During installation onboarding, end with the project-configuration CTA above; outside onboarding, provide the exact push command only when relevant to the requested setup.
+When the same user request explicitly includes deploy/push, read and follow `../zaip-skill-github-deploy/SKILL.md` after setup succeeds. Otherwise do not publish. Continue an authorized flow without adding a setup CTA or asking for permission already granted.
 
 ## Verify and report
 

package/templates/.agents/skills/zaip-skill-github-setup/references/bounded-setup.md

@@ -0,0 +1,42 @@
+# Bounded GitHub onboarding
+
+The installed helper handles the exact current checkout. Invoke it on the principal from that checkout:
+
+```powershell
+node .agents/skills/zaip-skill-github-setup/scripts/setup.mjs --request .agents/private/state/github-setup/request.json --apply
+```
+
+Example request (replace the path with the observed checkout):
+
+```json
+{
+  "schema_version": 1,
+  "repository": "C:\\Repos\\project",
+  "project_name": "Project",
+  "ssh_host": "github-account"
+}
+```
+
+`project_name` is the observed Codex project name, not the task/chat title. Omit unavailable optional fields. An alias is reused only when `ssh -G` resolves it to `github.com` and user `git`. An existing HTTPS origin remains HTTPS. Organization ownership requires active authenticated membership; a folder SSH account different from the API account is an ambiguity, not a reason to replace either credential.
+
+An explicit request `owner` must agree with inherited Git `zaip.githubOwner` when both exist. If neither is supplied, use the verified authenticated account; an existing origin remains authoritative only when compatible. Do not add `github.owner` to the strict project YAML: that field is not supported. Ambiguity is diagnosed before creation or origin attachment.
+
+Without `--apply`, the helper inspects state and makes no mutations. A folder without Git returns `initialization_required`; applying initializes `main` in that folder so conditional Git includes can take effect. It rejects an enclosing repository or an existing broken `.git`. Key generation, credential login/switch, config edits, visibility changes and publication are outside this helper.
+
+The request never grants permission. The managed PreToolUse hook reads only the host-provided transcript inside Codex sessions, matches session/cwd/current turn, and checks a direct human setup/publication request. It streams the transcript from the authenticated header in 64 KiB chunks, with an 8 MiB limit per record and a four-second scan deadline. This preserves standing authorization from earlier messages while evaluating subsequent revocations. A refusal in unquoted text prevails over affirmative directives and references to examples or previous statements; neutral messages do not revoke an existing grant. Questions, examples, quotations and unrelated requests never grant authority.
+
+The hook rejects delegates, plan mode, shell composition, caller-supplied receipts, traversal and foreign targets. The one-use receipt binds the exact request bytes, checkout, session and turn and expires after 60 seconds. The helper consumes it before mutation. Keep authorization from the same conversation; do not manufacture a transcript or copy a receipt from another call. If the host transcript is unavailable, incomplete, exceeds a record bound or cannot be fully scanned within the deadline, report `authorization unavailable` and diagnose that specific limit. Do not authorize from a partial scan, loop or claim permission was granted.
+
+| Diagnostic | Action |
+| --- | --- |
+| `github_authentication_unavailable` | Use the available authorized login flow; ask only for an unavoidable interactive step. Never print a token. |
+| `owner_ambiguous`, `origin_owner_mismatch`, `owner_membership_unverified` | Inspect configured owner and verified account; ask once only if the actual target remains unresolved. |
+| `ssh_github_identity_mismatch` | Preserve folder SSH; resolve the API account mismatch without switching credentials silently. |
+| `ssh_authentication_unavailable` | Diagnose passphrase/known-host/agent availability. No automatic acceptance of an unknown host key. |
+| `ssh_configuration_requires_review` | The effective SSH command contains unsupported options; preserve it and inspect the exact option instead of replacing it. |
+| `repository_name_collision` | Verify whether the existing repository is the requested target; do not invent a suffix, delete it or attach blindly. |
+| `repository_creation_failed_or_ambiguous` | Inspect the retained remote state; the helper already probed once. Do not repeat blindly. |
+| `origin_changed_during_setup` | Another actor changed local state; inspect it before another attempt. |
+| `host_authorization_invalid_or_expired` | Re-enter the same canonical command so the host can observe a fresh invocation, without fabricating a receipt or repeating the permission question. |
+
+New repositories are always private. Existing repositories keep their visibility. A verified empty repository can be reused after a partial creation. An `origin` already pointing to a verified repository is preserved byte-for-byte. Successful output reports `published: false`; publication uses the separate authorized deploy workflow.

package/templates/.agents/skills/zaip-skill-github-setup/scripts/setup.mjs

@@ -0,0 +1,365 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath, unlink } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  deployAuthGitArguments,
+  prepareDeployAuth,
+  resolveSetupAuth,
+} from "../../zaip-skill-github-deploy/scripts/deploy-auth.mjs";
+import { parseDocument } from "../../zaip-skill-github-deploy/scripts/yaml-parser.mjs";
+
+const scriptRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../../..");
+const identity = (path) =>
+  process.platform === "win32" ? resolve(path).toLowerCase() : resolve(path);
+const fail = (code) => {
+  throw new Error(code);
+};
+const ownerPattern = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;
+const namePattern = /^[A-Za-z0-9_.-]{1,100}$/;
+
+export function repositoryName(value) {
+  if (typeof value !== "string" || !value.trim()) fail("project_name_unavailable");
+  const name = value
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .trim()
+    .replace(/[^A-Za-z0-9_.-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!namePattern.test(name) || /^\.+$/.test(name)) fail("project_name_invalid");
+  return name;
+}
+
+// Read the effective command as data. No shell, eval, key reads or config writes.
+export function sshArguments(command) {
+  if (!command) return ["ssh"];
+  if (/[\r\n\0;&|<>`$]/.test(command)) fail("ssh_configuration_requires_review");
+  const tokens = [...command.matchAll(/"([^"]*)"|'([^']*)'|([^\s"']+)/g)].map(
+    (m) => m[1] ?? m[2] ?? m[3],
+  );
+  if (tokens.join("").length === 0 || !/(?:^|[\\/])ssh(?:\.exe)?$/i.test(tokens[0]))
+    fail("ssh_configuration_requires_review");
+  if ((command.match(/"/g) ?? []).length % 2 || (command.match(/'/g) ?? []).length % 2)
+    fail("ssh_configuration_requires_review");
+  for (let i = 1; i < tokens.length; i += 2) {
+    const flag = tokens[i],
+      value = tokens[i + 1];
+    if (flag === "-i" && value && !value.startsWith("-")) continue;
+    if (
+      flag === "-o" &&
+      /^(?:IdentitiesOnly=(?:yes|true)|BatchMode=yes|StrictHostKeyChecking=yes|ConnectTimeout=10)$/i.test(
+        value ?? "",
+      )
+    )
+      continue;
+    fail("ssh_configuration_requires_review");
+  }
+  return tokens;
+}
+
+function commandRunner(root) {
+  const env = { ...process.env, GH_PROMPT_DISABLED: "1", GIT_TERMINAL_PROMPT: "0" };
+  for (const key of [
+    "GH_REPO",
+    "GH_HOST",
+    "GH_DEBUG",
+    "GIT_TRACE",
+    "GIT_TRACE_CURL",
+    "GIT_CURL_VERBOSE",
+  ])
+    delete env[key];
+  if (
+    env.GIT_SSH ||
+    env.GIT_SSH_COMMAND ||
+    env.GIT_CONFIG_COUNT ||
+    env.GIT_CONFIG_PARAMETERS ||
+    env.GIT_DIR ||
+    env.GIT_WORK_TREE
+  )
+    fail("git_environment_override_requires_review");
+  return (file, args) => {
+    const result = spawnSync(file, args, {
+      cwd: root,
+      env,
+      encoding: "utf8",
+      windowsHide: true,
+      timeout: 30000,
+      maxBuffer: 1024 * 1024,
+    });
+    return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+  };
+}
+
+async function config(root) {
+  let text;
+  try {
+    text = await readFile(resolve(root, ".agents/config/project.yaml"), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw error;
+  }
+  if (Buffer.byteLength(text) > 65536) fail("project_configuration_invalid");
+  const document = parseDocument(text, { uniqueKeys: true });
+  if (document.errors.length) fail("project_configuration_invalid");
+  return document.toJS({ maxAliasCount: 20 }) ?? {};
+}
+
+function originTarget(url) {
+  const match =
+    /^(?:git@([A-Za-z0-9.-]+):|https:\/\/(github\.com)\/)([A-Za-z0-9-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(
+      url,
+    );
+  if (!match || !ownerPattern.test(match[3]) || !namePattern.test(match[4]))
+    fail("origin_requires_review");
+  return { host: match[1] ?? match[2], owner: match[3], name: match[4], ssh: Boolean(match[1]) };
+}
+
+export async function setupRepository(
+  request,
+  { root = scriptRoot, run = commandRunner(root), apply = false } = {},
+) {
+  if (
+    request?.schema_version !== 1 ||
+    identity(request.repository ?? "") !== identity(root) ||
+    Object.keys(request).some(
+      (key) => !["schema_version", "repository", "project_name", "owner", "ssh_host"].includes(key),
+    )
+  )
+    fail("setup_request_invalid");
+  const checked = (file, args, code) => {
+    const result = run(file, args);
+    if (result.status !== 0) fail(code);
+    return result.stdout.trim();
+  };
+  const json = (args, code) => {
+    try {
+      return JSON.parse(checked("gh", ["api", "--hostname", "github.com", ...args], code));
+    } catch {
+      fail(code);
+    }
+  };
+  const gitRoot = run("git", ["rev-parse", "--show-toplevel"]);
+  if (gitRoot.status === 0 && identity(gitRoot.stdout.trim()) !== identity(root))
+    fail("nested_repository_blocked");
+  if (gitRoot.status !== 0) {
+    if (
+      await lstat(resolve(root, ".git")).then(
+        () => true,
+        (e) => (e.code === "ENOENT" ? false : Promise.reject(e)),
+      )
+    )
+      fail("git_state_requires_review");
+    if (!apply) return { status: "initialization_required", repository: root, private: true };
+    checked("git", ["init", "-b", "main"], "git_initialization_failed");
+  }
+  const project = await config(root);
+  const gitValue = (key) => {
+    const r = run("git", ["config", "--get", key]);
+    if (![0, 1].includes(r.status)) fail("git_config_unavailable");
+    return r.stdout.trim();
+  };
+  const origin = run("git", ["config", "--get-all", "remote.origin.url"]);
+  if (![0, 1].includes(origin.status)) fail("origin_unavailable");
+  const origins = origin.stdout.trim().split(/\r?\n/).filter(Boolean);
+  if (origins.length > 1) fail("multiple_origins_require_review");
+  const existing = origins.length ? originTarget(origins[0]) : null;
+  const user = json(["user"], "github_authentication_unavailable");
+  if (!ownerPattern.test(user.login ?? "")) fail("github_identity_invalid");
+  const configuredOwner = gitValue("zaip.githubOwner") || null;
+  if (
+    request.owner &&
+    configuredOwner &&
+    request.owner.toLowerCase() !== configuredOwner.toLowerCase()
+  )
+    fail("owner_ambiguous");
+  const selectedOwner = request.owner || configuredOwner;
+  if (existing && selectedOwner && existing.owner.toLowerCase() !== selectedOwner.toLowerCase())
+    fail("origin_owner_mismatch");
+  const owner = existing?.owner || selectedOwner || user.login;
+  if (!ownerPattern.test(owner)) fail("owner_invalid");
+  if (owner.toLowerCase() !== user.login.toLowerCase()) {
+    const membership = json([`user/memberships/orgs/${owner}`], "owner_membership_unverified");
+    if (
+      membership.state !== "active" ||
+      membership.organization?.login?.toLowerCase() !== owner.toLowerCase()
+    )
+      fail("owner_membership_unverified");
+  }
+  const nameSource = request.project_name || project.project?.name || basename(root);
+  const name = existing?.name || repositoryName(nameSource);
+  const fullName = `${owner}/${name}`;
+  const host = existing?.host || request.ssh_host || "github.com";
+  if (!/^[A-Za-z0-9][A-Za-z0-9.-]{0,252}$/.test(host)) fail("ssh_host_invalid");
+  const authentication = resolveSetupAuth(root, { run });
+  if (authentication.method === "ssh") {
+    const [ssh, ...options] = sshArguments(authentication.ssh_command);
+    const effective = checked(
+      ssh,
+      [...options, "-G", `git@${host}`],
+      "ssh_configuration_unavailable",
+    );
+    if (
+      !/^hostname github\.com\s*$/im.test(effective) ||
+      !/^user git\s*$/im.test(effective) ||
+      /^(?:proxycommand|proxyjump) (?!none\s*$)\S+/im.test(effective)
+    )
+      fail("ssh_destination_unverified");
+    const auth = run(ssh, [
+      ...options,
+      "-o",
+      "BatchMode=yes",
+      "-o",
+      "StrictHostKeyChecking=yes",
+      "-o",
+      "ConnectTimeout=10",
+      "-T",
+      `git@${host}`,
+    ]);
+    const login = /Hi ([A-Za-z0-9-]+)! You've successfully authenticated/.exec(
+      auth.stdout + auth.stderr,
+    )?.[1];
+    if (![0, 1].includes(auth.status) || !login) fail("ssh_authentication_unavailable");
+    if (login.toLowerCase() !== user.login.toLowerCase()) fail("ssh_github_identity_mismatch");
+  } else {
+    checked(
+      "gh",
+      ["auth", "status", "--hostname", "github.com"],
+      "github_authentication_unavailable",
+    );
+  }
+  const probe = () => run("gh", ["api", "--hostname", "github.com", `repos/${fullName}`]);
+  let remote = probe();
+  let created = false,
+    creationAttempted = false;
+  if (remote.status !== 0) {
+    if (existing || !/HTTP 404\b/.test(remote.stderr)) fail("github_repository_unavailable");
+    if (!apply)
+      return {
+        status: "ready",
+        action: "create_private_and_attach",
+        repository: root,
+        target: fullName,
+        private: true,
+        normalized_name: name,
+      };
+    // A failed creation may have succeeded remotely. Probe once; never delete or blindly retry.
+    creationAttempted = true;
+    const create = run("gh", ["repo", "create", fullName, "--private"]);
+    remote = probe();
+    if (remote.status !== 0)
+      fail(
+        create.status === 0
+          ? "created_repository_verification_failed"
+          : "repository_creation_failed_or_ambiguous",
+      );
+    created = create.status === 0;
+  }
+  let remoteData;
+  try {
+    remoteData = JSON.parse(remote.stdout);
+  } catch {
+    fail("github_repository_response_invalid");
+  }
+  if (
+    remoteData.full_name?.toLowerCase() !== fullName.toLowerCase() ||
+    remoteData.permissions?.push !== true
+  )
+    fail("github_repository_access_unverified");
+  if (creationAttempted && remoteData.private !== true)
+    fail("created_repository_privacy_unverified");
+  // An unrelated pre-existing nonempty repository is a collision, not an attach default.
+  if (!existing && !created && remoteData.size !== 0) fail("repository_name_collision");
+  const url =
+    authentication.method === "ssh"
+      ? `git@${host}:${fullName}.git`
+      : `https://github.com/${fullName}.git`;
+  checked(
+    "git",
+    [...deployAuthGitArguments(authentication), "ls-remote", url, "HEAD"],
+    "git_transport_unavailable",
+  );
+  if (apply && !existing) {
+    const latest = run("git", ["config", "--get-all", "remote.origin.url"]);
+    if (latest.status !== 1 || latest.stdout.trim()) fail("origin_changed_during_setup");
+    checked("git", ["remote", "add", "origin", url], "origin_attachment_failed");
+    if (checked("git", ["remote", "get-url", "origin"], "origin_verification_failed") !== url)
+      fail("origin_verification_failed");
+  }
+  const prepared = apply ? prepareDeployAuth(root, { apply: true, run }) : null;
+  return {
+    status: apply ? "configured" : "ready",
+    repository: root,
+    target: fullName,
+    created,
+    origin: prepared?.url ?? url,
+    attached: apply && !existing,
+    private: remoteData.private,
+    normalized_name: name,
+    published: false,
+  };
+}
+
+async function cli() {
+  const args = process.argv.slice(2);
+  if (
+    args[0] !== "--request" ||
+    !/^\.agents\/private\/state\/github-setup\/[A-Za-z0-9_-]+\.json$/.test(args[1] ?? "") ||
+    !(
+      args.length === 2 ||
+      (args.length === 4 && args[2] === "--apply" && /^--host-receipt=[a-f0-9]{64}$/.test(args[3]))
+    )
+  )
+    fail("usage_setup_request_or_host_authorized_apply");
+  const root = await realpath(process.cwd());
+  if (identity(root) !== identity(scriptRoot)) fail("setup_checkout_mismatch");
+  const requestPath = resolve(root, args[1]);
+  const safeRead = async (path, max) => {
+    for (let p = path; identity(p) !== identity(root); p = dirname(p)) {
+      const stat = await lstat(p);
+      if (stat.isSymbolicLink() || identity(await realpath(p)) !== identity(p))
+        fail("setup_link_blocked");
+    }
+    const stat = await lstat(path);
+    if (!stat.isFile() || stat.size > max) fail("setup_file_invalid");
+    return readFile(path, "utf8");
+  };
+  const text = await safeRead(requestPath, 16384);
+  if (args.length === 4) {
+    const hostEnvironment = { ...process.env };
+    const path = resolve(
+      root,
+      ".agents/private/state/codex-hook-github-setup",
+      args[3].slice(15) + ".json",
+    );
+    const receipt = JSON.parse(await safeRead(path, 4096));
+    if (
+      receipt.schema_version !== 1 ||
+      identity(receipt.repository) !== identity(root) ||
+      receipt.request_path !== args[1] ||
+      receipt.request_sha256 !== createHash("sha256").update(text).digest("hex") ||
+      receipt.session_id !== hostEnvironment.CODEX_THREAD_ID ||
+      (hostEnvironment.CODEX_TURN_ID && receipt.turn_id !== hostEnvironment.CODEX_TURN_ID) ||
+      !Number.isSafeInteger(receipt.issued_at_ms) ||
+      Date.now() - receipt.issued_at_ms > 60000 ||
+      receipt.issued_at_ms > Date.now()
+    )
+      fail("host_authorization_invalid_or_expired");
+    await unlink(path); // Single use, including a failed/partial setup; obtain a fresh observed hook receipt for recovery.
+  }
+  console.log(
+    JSON.stringify(await setupRepository(JSON.parse(text), { root, apply: args.length === 4 })),
+  );
+}
+if (process.argv[1] && identity(process.argv[1]) === identity(fileURLToPath(import.meta.url))) {
+  cli().catch((error) => {
+    console.error(
+      JSON.stringify({
+        status: "blocked",
+        code: /^[a-z_]+$/.test(error.message) ? error.message : "setup_failed",
+        published: false,
+      }),
+    );
+    process.exitCode = 1;
+  });
+}

package/templates/.agents/skills/zaip-skill-github-setup-ssh-folder/SKILL.md

@@ -5,6 +5,8 @@ description: Configure SSH and Git identity for child repositories under one sel
 
 # Configurar SSH e Git por pasta
 
+O padrão distribuído de deploy segue [RULE-GITHUB-DEPLOY-AUTH](../../rules/github-deploy-auth.md): chave do repositório, depois da pasta mãe imediata e, sem chave, GitHub CLI. Este fluxo de configuração de pasta continua disponível para preparar `includeIf` explicitamente; não é requisito para repetir a preferência em cada projeto nem autoriza descobrir outras pastas.
+
 Use quando uma pessoa selecionar uma pasta pai absoluta que contém vários
 repositórios filhos e precisar de uma identidade Git e SSH limitada a ela. A
 pasta pai cobre seus descendentes; não descubra outras pastas, repositórios,
@@ -12,9 +14,10 @@ dotenvs ou identidades.
 
 Um pedido explícito de **configurar** autoriza a configuração local, limitada à
 pasta pai escolhida: Git, SSH e o `.env` explicitamente indicado nela. Não peça
-novamente essa autorização. Pergunte somente os fatos ainda ausentes: pasta pai
-absoluta, conta GitHub, chave selecionada ou pedido de criação de chave, e
-política de passphrase. Criação remota de repositório e push exigem pedido
+novamente essa autorização. Primeiro resolva os fatos disponíveis na configuração
+e no pedido: pasta pai absoluta, conta GitHub verificada e chave já aplicada por
+`includeIf`/alias. Pergunte apenas se permanecer ambiguidade real ou se a pessoa
+pedir uma chave nova sem informar sua política. Criação remota de repositório e push exigem pedido
 explícito, que pode já constar na mesma mensagem do usuário.
 
 Conduza uma etapa por vez: dados da pasta e conta, chave local, cadastro público
@@ -34,6 +37,13 @@ preservando seu conteúdo existente. O modelo não contém credenciais utilizáv
 4. Cada repositório filho independente recebe seu próprio `.gitignore` ou
    `info/exclude` revisado antes de qualquer stage. Pare e relate override,
    política organizacional, autorização ou escopo ambíguo.
+5. Para um filho selecionado com setup/publicação já autorizado, reutilize
+   `$zaip-skill-github-setup` e seu helper delimitado. Nome novo = nome observado
+   do projeto Codex (fallback `project.name`, depois pasta); novo repositório
+   sempre privado. Preserve owner, chave, alias e identidade da pasta. Um
+   `origin` ausente não exige outra chave nem edição de configuração global.
+   Reutilize autenticação `gh` válida; não exija criar um PAT se ela já atende
+   ao pedido. Não encerre um fluxo autorizado com uma pergunta obrigatória.
 
 ## Proteção contra deleção de repositório
 

package/templates/.agents/skills/zaip-skill-github-setup-ssh-folder/references/operational-procedure.md

@@ -104,9 +104,9 @@ O segundo comando não deve retornar valor. Não use clone para criar, publicar
 
 ## GitHub e criação de repositório
 
-SSH autentica transporte Git, não a API do GitHub. Não troque autenticação global de `gh`. Sem token autorizado, clone SSH pode prosseguir quando solicitado; criação remota espera autorização manual ou token selecionado.
+SSH autentica transporte Git, não a API do GitHub. Não troque autenticação global de `gh`. Primeiro reutilize a sessão `gh` já válida, com conta verificada e compatível com a identidade SSH da pasta. Para o filho atual com setup/deploy autorizado, use o helper e o [contrato de onboarding delimitado](../../zaip-skill-github-setup/references/bounded-setup.md). Nome novo vem do projeto Codex, com fallback para `project.name`/pasta; criação é privada. Origin ausente é anexado sem reconfigurar SSH ou identidade. Não peça um PAT novo se a autenticação existente já permite concluir o pedido.
 
-Para criação automática explicitamente solicitada, escolha token somente do `.env` pai indicado. Um PAT clássico é o caminho prático: no GitHub, abra **Settings > Developer settings > Personal access tokens > Tokens (classic) > Generate**, escolha expiração e conceda `public_repo` para criação pública ou `repo` para criação privada. Rejeite `delete_repo` e escopos desconhecidos. Se a organização proibir PAT clássico, entregue a etapa manual; não use token fine-grained com **Administration (write)** para criação automatizada sem deleção, porque essa permissão pode permitir exclusão.
+Somente se a pessoa tiver escolhido explicitamente o fluxo de token local, leia o `.env` pai indicado. As restrições dos parágrafos seguintes aplicam-se a esse token, sem invalidar uma sessão `gh` já autorizada. Um PAT clássico para criação privada precisa de `repo`; rejeite `delete_repo` e escopos desconhecidos nesse fluxo. Se a organização proibir PAT clássico, diagnostique a alternativa permitida; não solicite outro tipo de token apenas para contornar a política.
 
 Depois de gerar o PAT, a pessoa o salva localmente em `GITHUB_TOKEN` no `.env` escolhido e informa apenas que terminou. Reutilize o procedimento de [credenciais locais](../../zaip-skill-local-credentials/SKILL.md) com a pasta pai explicitamente escolhida como limite; não imprima, registre ou passe o token em argumentos. Parseie dotenv como dados, sem executar seu conteúdo. A chave privada permanece em seu arquivo, não nesse campo.
 
@@ -114,9 +114,9 @@ Crie um ambiente somente para cada subprocesso mínimo de verificação/criaçã
 
 Antes da criação, consulte `GET /user` nesse contexto e confira a conta esperada. Leia somente o cabeçalho de escopos `x-oauth-scopes` de forma sanitizada: aceite apenas `public_repo`/`repo` suficientes para o alvo e sem `delete_repo`; não confunda `x-accepted-oauth-scopes` (o que o endpoint aceita) com escopos concedidos. Tipo ou escopos não verificáveis bloqueiam apenas criação automática; não recorra à credencial global. Nunca confirme proteção enviando DELETE. Esta restrição do PAT vale para ele, não para outras sessões da conta ou para o navegador.
 
-Antes de criar, resolva owner, nome e visibilidade a partir do pedido; pergunte apenas o que falta. Consulte a existência: repositório existente é reutilizado conforme autorização, não apagado/recriado. Um 404 também pode ser falta de acesso; confirme conta/owner e não repita criação após erro ambíguo sem consultar o estado. No subprocesso autenticado, execute `gh repo create OWNER/REPO --private` ou `--public` conforme a visibilidade escolhida, sem `--push`. Depois clone a URL SSH no filho escolhido pelo procedimento anterior. Se já houver repositório local, adicione `origin` somente quando ausente e valide qualquer remoto existente.
+Antes de criar, resolva owner pela configuração da pasta/projeto e identidade autenticada; aplique nome do projeto e privado sem perguntas redundantes. Consulte a existência: repositório existente é reutilizado conforme autorização, não apagado/recriado. Um 404 também pode ser falta de acesso; confirme conta/owner e não repita criação após erro ambíguo sem consultar o estado. No Codex, use o helper canônico do filho; comandos diretos de criação/edição de remoto continuam protegidos. Um pedido explícito posterior de criação pública fica fora desse helper e requer o fluxo específico autorizado. Não clone nem faça push por inferência. Se já houver repositório local, adicione `origin` somente quando ausente e valide qualquer remoto existente.
 
-Quando o token estiver ausente ou a organização proibir o fluxo, oriente criação manual: GitHub **+ > New repository**, selecione owner, nome e visibilidade, clique **Create repository** e volte com a URL SSH. Isso não exige PAT da IA; o clone pode continuar após a criação humana. Políticas de SSO e organização devem ser atendidas, nunca contornadas. Não use outras credenciais para driblar a trava.
+Quando nenhuma autenticação autorizada disponível permitir criar, relate o passo humano indispensável: GitHub **+ > New repository**, owner resolvido, nome do projeto e **Private**. O clone solicitado pode continuar após a criação humana. Políticas de SSO e organização devem ser atendidas, nunca contornadas. Não use outras credenciais para driblar a trava.
 
 ## Proteção contra deleção