turnzero 0.31.1 → 0.33.0-next.1

package/dist/turnzero-cloud.mjs

@@ -64,7 +64,7 @@ var TURNZERO_CLOUD_PACKAGE = "turnzero";
 var LOGIN_SUBCOMMAND = "login";
 var LOGIN_OPTION = Object.freeze({ origin: "--origin", noBrowser: "--no-browser" });
 var loginLineOf = (origin) => commandLineOf(origin, LOGIN_SUBCOMMAND, origin !== DEFAULT_COMMAND_ORIGIN ? { origin } : {});
-var HAND_OVER_SENTENCE = "If your tool's own safety check refuses a line, give the person that exact line to run once in their own terminal, never a rewritten one.";
+var HAND_OVER_SENTENCE = "If your tool's own safety check refuses a line, first take any route named above that your tool can still use, telling the person which and why. Only where none works, give the person that exact line to run once in their own terminal, never a rewritten one.";
 var COMPUTER_LOGIN_PATH = "/approve/computer";
 var COMPUTER_LOGIN_QUERY = Object.freeze({ challenge: "challenge", state: "state", port: "port", label: "label" });
 var LOGIN_STATE_FORM = /^[A-Za-z0-9_-]{43}$/;
@@ -169,6 +169,9 @@ var SECRET_NAME_FORM = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
 var PUT_SUBCOMMAND = "put";
 var PUT_OPTION = Object.freeze({ area: "--area", name: "--name", path: DEPLOY_OPTION.path, origin: DEPLOY_OPTION.origin });
 var PUT_AREA_FORM = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+var LINE_PATH_SHELL_CLASS = /["$`%!&|<>^\u201c\u201d\u201e]|\\\\|\\$/;
+var LINE_CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/;
+var lineValueCarries = (value) => !LINE_CONTROL_CHARACTER.test(value) && !LINE_PATH_SHELL_CLASS.test(value);
 var EXPORT_AREA_PREFIX = "export-";
 var exportAreaName = (application) => `${EXPORT_AREA_PREFIX}${application}`;
 var EXPORT_MANIFEST_FILE = "manifest.json";
@@ -292,7 +295,14 @@ var TZMESH_OPTION = {
   force: "--force",
   origin: "--origin",
   tzmeshEstate: "--tzmesh-estate",
-  mint: "--mint"
+  mint: "--mint",
+  // The hosted setup's options (the tzmesh hosted setup plan's decision 1).
+  webhookOrigin: "--webhook-origin",
+  webhookSecret: "--webhook-secret",
+  description: "--description",
+  title: "--title",
+  join: "--join",
+  public: "--public"
 };
 var TZMESH_ESTATES = Object.freeze(["production", "development"]);
 var TZMESH_ESTATE_ORIGINS = Object.freeze({
@@ -315,6 +325,13 @@ var TZMESH_SECRET_FORM = new RegExp(`^${TZMESH_SECRET_PREFIX}[A-Za-z0-9_-]{16,25
 var TZMESH_NAME_FORM = /^[A-Za-z0-9_-]{1,32}$/;
 var TZMESH_REGISTER_PATH = "/v1/register";
 var TZMESH_END_PATH = "/v1/end";
+var TZMESH_WEBHOOK_SET_PATH = "/v1/webhook_set";
+var TZMESH_JOIN_PATH = "/v1/join";
+var TZMESH_WEBHOOK_ROUTE = "/tzmesh/webhook";
+var TZMESH_WEBHOOK_SECRET_PREFIX = "turnzero_tzmesh_whk_";
+var TZMESH_WEBHOOK_SECRET_FORM = new RegExp(`^${TZMESH_WEBHOOK_SECRET_PREFIX}[A-Za-z0-9_-]{43}$`);
+var TZMESH_TITLE_MAX = 80;
+var TZMESH_DESCRIPTION_MAX = 120;
 var tzmeshMintMembers = (challenge) => [
   [CODE_CHALLENGE_MEMBER, challenge],
   ["scope_kind", "account"],
@@ -328,6 +345,12 @@ var tzmeshRegisterOptionsOf = (call) => [
   call.secret !== void 0 ? `${TZMESH_OPTION.secret} ${call.secret}` : `${TZMESH_OPTION.toFile} "${call.toFile ?? ""}"`,
   ...call.application !== void 0 ? [`${TZMESH_OPTION.application} ${call.application}`] : [],
   ...call.environment !== void 0 ? [`${TZMESH_OPTION.environment} ${call.environment}`] : [],
+  ...call.webhookOrigin !== void 0 ? [`${TZMESH_OPTION.webhookOrigin} ${call.webhookOrigin}`] : [],
+  ...call.webhookSecret !== void 0 ? [`${TZMESH_OPTION.webhookSecret} ${call.webhookSecret}`] : [],
+  ...call.description !== void 0 ? [`${TZMESH_OPTION.description} "${call.description}"`] : [],
+  ...call.title !== void 0 ? [`${TZMESH_OPTION.title} "${call.title}"`] : [],
+  ...call.join !== void 0 && call.join.length > 0 ? [`${TZMESH_OPTION.join} "${call.join.join(",")}"`] : [],
+  ...call.public === true ? [TZMESH_OPTION.public] : [],
   ...call.force === true ? [TZMESH_OPTION.force] : [],
   `${TZMESH_OPTION.origin} ${originWord(call.origin)}`,
   `${TZMESH_OPTION.tzmeshEstate} ${call.tzmeshEstate}`
@@ -995,11 +1018,11 @@ var noTokenSentence = (origin, expiredAt) => expiredAt === null ? `No credential
 var VARIABLE_ROUTE_SENTENCES = `A tool connected by a minted token, or a job, sets ${MINTED_TOKEN_VARIABLE} from where its token is kept, never by writing the value in a line. It sets ${ORIGIN_VARIABLE} to the address that minted the token where that is not ${DEFAULT_COMMAND_ORIGIN}, then runs the line again. Such a tool cannot use ${MINT_TOKEN_ACTION}, which takes a sign-in alone. A tool sets ${MINTED_TOKEN_VARIABLE} for one line at a time and unsets it once that line ends.`;
 var authorizeRouteSentence = (origin) => `${AUTHORIZE_SUBCOMMAND}${originWordsOf(origin)} run with nothing piped prints the ${MINT_TOKEN_ACTION} call a signed-in tool makes to authorize this computer.`;
 var LOGIN_ROUTE_OPENER = "A person logs this computer in once, in a terminal of their own, and its token then stays on this computer for 30 days:";
-var DEPLOY_FILES_ROUTE_SENTENCE = "A folder within the caps of your tool's deploy_files call deploys now through deploy_files, with no login; past them, through mint_upload_grant and deploy's artifact.";
+var DEPLOY_ROUTES_SENTENCE = "For regular use, prefer this command wherever your tool can install and run it and reach the platform. A first simple test within the caps of your tool's deploy_files call may deploy through deploy_files, as may any folder within them where this command cannot work. Past the caps, where your tool may not install or run this command, upload a zip with mint_upload_grant, then name it as deploy's artifact.";
 var loginRouteLines = (io2, origin, deployFiles = true) => [
   LOGIN_ROUTE_OPENER,
   ...loginLinesFor(io2, origin),
-  ...deployFiles ? [DEPLOY_FILES_ROUTE_SENTENCE] : [],
+  ...deployFiles ? [DEPLOY_ROUTES_SENTENCE] : [],
   HAND_OVER_SENTENCE
 ];
 var loginRouteRefusalOf = (io2, closing) => {
@@ -1018,6 +1041,8 @@ var GRANT_TEXT = new RegExp(`${UPLOAD_GRANT_PREFIX}[A-Za-z0-9_-]*(?:\\.[A-Za-z0-
 var TOKEN_TEXT = new RegExp(`${MINTED_TOKEN_PREFIX}[A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*`, "g");
 var PROGRAM_SECRET_TEXT = new RegExp(`${TZMESH_SECRET_PREFIX}[A-Za-z0-9_-]*`, "g");
 var REDACTED_PROGRAM_SECRET = "<program secret>";
+var WEBHOOK_SECRET_TEXT = new RegExp(`${TZMESH_WEBHOOK_SECRET_PREFIX}[A-Za-z0-9_-]*`, "g");
+var REDACTED_WEBHOOK_SECRET = "<webhook signing secret>";
 var REDACTED_GRANT = "<grant>";
 var REDACTED_VALUE = "<value>";
 var REDACTED_TOKEN_CODE = "<token code>";
@@ -1025,7 +1050,7 @@ var REDACTED_VERIFIER = "<verifier>";
 var REDACTED_CHALLENGE = "<challenge>";
 var HIDDEN_TEXT_MIN = 8;
 var redactGrants = (line) => line.replace(GRANT_TEXT, REDACTED_GRANT);
-var redactCredentials = (line) => redactGrants(line).replace(TOKEN_TEXT, REDACTED_TOKEN).replace(PROGRAM_SECRET_TEXT, REDACTED_PROGRAM_SECRET);
+var redactCredentials = (line) => redactGrants(line).replace(TOKEN_TEXT, REDACTED_TOKEN).replace(PROGRAM_SECRET_TEXT, REDACTED_PROGRAM_SECRET).replace(WEBHOOK_SECRET_TEXT, REDACTED_WEBHOOK_SECRET);
 var VALUE_LINE_REFUSED = Object.freeze({
   twice: "the value line is printed once in a run",
   form: "only a value of a form token claim prints is printed whole",
@@ -1110,6 +1135,8 @@ var firstActNamed = (kind, origin = DEFAULT_COMMAND_ORIGIN) => kind === "tzmesh"
 ) : `${kind === "authorized computer" ? AUTHORIZE_SUBCOMMAND : `${TOKEN_SUBCOMMAND} ${TOKEN_REQUEST_ACT}`}${originWordsOf(origin)}`;
 var noConnectionLine = (origin) => `Where your tool holds no connection signed in to ${origin}, ${MINT_TOKEN_ACTION} is not among its tools: a person connects the tool and signs in, in a browser, before the call.`;
 var loginWaySentence = (loginLines) => `A person can instead log this computer in themselves, in a terminal of their own, by running ${loginLines.join(", then ")}, and approving the login in the browser.`;
+var AUTHORIZE_HAND_OVER_SENTENCE = "If your tool's own safety check refuses the answered line, a deploy can still go through a route that does not require the turnzero command. That is deploy_files within its caps or, past them where your tool can zip and upload the folder, mint_upload_grant followed by deploy naming the uploaded zip as artifact. Tell the person which route you take and why. Only where no such route serves, give the person that exact line to run once in their own terminal, never a rewritten one.";
+var TZMESH_HAND_OVER_SENTENCE = "If your tool's own safety check refuses the answered line, give the person that exact line to run once in their own terminal, never a rewritten one.";
 var OPTIONS_LINE_HEAD = "options: ";
 var tzmeshFirstActLines = (origin, pending, completing2) => [
   `To register a tzMesh agent, call ${MINT_TOKEN_ACTION} at ${origin} from your tool, through the connection you signed in with, naming the members below and no others. Then run the line it answers once, on this computer, with the options below after it.`,
@@ -1120,7 +1147,7 @@ var tzmeshFirstActLines = (origin, pending, completing2) => [
   `${OPTIONS_LINE_HEAD}${completing2}`,
   `The line it answers holds no code. The run presents this computer's verifier, registers the agent with the token it mints, keeps the agent's secret where the options say, and revokes the token. No line prints the secret.`,
   `The request is pending until ${pending.expires_at}: ${firstActNamed("tzmesh", origin)} run again with the same options before then prints this challenge again.`,
-  HAND_OVER_SENTENCE
+  TZMESH_HAND_OVER_SENTENCE
 ];
 var firstActLines = (origin, kind, pending, label, loginLines = [], completing2 = "") => kind === "tzmesh" ? tzmeshFirstActLines(origin, pending, completing2) : [
   kind === "authorized computer" ? `To authorize this computer at ${origin}, call ${MINT_TOKEN_ACTION} from your tool, through the connection you signed in with, naming the members below and no others. Then run the line it answers once, as given, on this computer.` : `To mint a token whose value never passes through the chat, call ${MINT_TOKEN_ACTION} at ${origin} from your tool, through the connection you signed in with. Name the member below beside the scope_kind, application, grants, label, and expires_in_days the task needs.`,
@@ -1132,7 +1159,7 @@ var firstActLines = (origin, kind, pending, label, loginLines = [], completing2
   ...mintCallMembers(kind, pending.challenge, label).map(([name, value]) => `  ${name}: ${JSON.stringify(value)}`),
   kind === "authorized computer" ? `The line it answers holds no code. It keeps the token it mints in this computer's credential file and revokes the one this computer held there before. The token is account-scoped and works from any computer until it expires or revoke_token ends it, and list_tokens shows it by its label. The request is pending until ${pending.expires_at}: ${firstActNamed(kind, origin)} run again before then prints this challenge again.` : `It answers a ${TOKEN_SUBCOMMAND} ${TOKEN_CLAIM_ACT} line, which is yours to run in a terminal outside the AI coding tool, on this computer as this user, and never through the tool. That line prints the token's value once to standard output, so pipe it into your secret store's command where the token is a job's. The request is pending until ${pending.expires_at}: ${firstActNamed(kind, origin)} run again before then prints this challenge again.`,
   ...kind === "authorized computer" && loginLines.length > 0 ? [loginWaySentence(loginLines)] : [],
-  ...kind === "authorized computer" ? [HAND_OVER_SENTENCE] : []
+  ...kind === "authorized computer" ? [AUTHORIZE_HAND_OVER_SENTENCE] : []
 ];
 var reusedRequestSentence = (origin, pending) => `A request for ${origin} is pending until ${pending.expires_at}, so its challenge is printed again and no new verifier was made.`;
 var replacedRequestSentence = (origin, expired2) => `The request pending for ${origin} expired at ${expired2.expires_at}, so a new one replaces it. A line minted against the old challenge is refused at its exchange, and a ${MINT_TOKEN_ACTION} call naming the new challenge below answers a fresh one.`;
@@ -1257,6 +1284,16 @@ var mintedTokenOf = (answer, kind = "authorized computer") => {
 var mintAgainSentence = (kind, origin = DEFAULT_COMMAND_ORIGIN, login2 = null) => login2 !== null ? `Run ${login2} again to log this computer in.` : `Call ${MINT_TOKEN_ACTION} from your tool again with the challenge ${firstActNamed(kind, origin)} prints, and run the line it answers.`;
 var exchangeUnknownSentence = (kind, origin = DEFAULT_COMMAND_ORIGIN, login2 = null) => `Whether a token was minted is unknown: list_tokens from your tool shows each token by its label, and revoke_token ends one nothing holds. ${mintAgainSentence(kind, origin, login2)}`;
 var noPendingSentence = (origin, kind, presented = "code") => `No request is pending for ${origin} on this computer, so ${presented === "mint" ? "nothing was sent: the verifier the mint needs" : "the token code was not presented and nothing was sent: the verifier it needs"} is kept only on the computer whose ${firstActNamed(kind)} printed its challenge. Run ${firstActNamed(kind, origin)} on this computer, call ${MINT_TOKEN_ACTION} from your tool with the challenge it prints, and run the line it answers.`;
+var otherLivingRequestOf = (pending, origin, now) => {
+  let found = null;
+  for (const [other, entry] of pending) {
+    const expires = Date.parse(entry.expires_at);
+    if (other === origin || !Number.isFinite(expires) || expires <= now.getTime()) continue;
+    if (found === null || expires > found.expires) found = { origin: other, expires };
+  }
+  return found?.origin ?? null;
+};
+var elsewhereRequestSentence = (origin, other) => `A request is pending on this computer for ${other} instead, so the first act ran against ${other}. Where the mint was made at ${origin}, run the first act above. Where it was made at ${other}, run the line its ${MINT_TOKEN_ACTION} call answered exactly as given.`;
 var markerDisagreesSentence = (kind, origin = DEFAULT_COMMAND_ORIGIN) => kind === "authorized computer" ? `The exchange minted a token that is not an authorized computer's, and ${AUTHORIZE_SUBCOMMAND} keeps only an authorized computer's, so nothing of its value was printed or kept. Call ${MINT_TOKEN_ACTION} from your tool again naming ${AUTHORIZED_COMPUTER_MEMBER}: true, as ${AUTHORIZE_SUBCOMMAND} prints it, and run the line it answers.` : `The exchange minted an authorized computer's token, and ${TOKEN_SUBCOMMAND} ${TOKEN_CLAIM_ACT} prints only a token that is not one, so nothing of its value was printed or kept. Call ${MINT_TOKEN_ACTION} from your tool again without ${AUTHORIZED_COMPUTER_MEMBER}, as ${TOKEN_SUBCOMMAND} ${TOKEN_REQUEST_ACT} prints it, and run the line it answers; to authorize this computer, run ${AUTHORIZE_SUBCOMMAND}${originWordsOf(origin)}.`;
 var unclaimableFormSentence = (origin = DEFAULT_COMMAND_ORIGIN) => `The exchange minted a token whose value is of no form ${TOKEN_SUBCOMMAND} ${TOKEN_CLAIM_ACT} prints, so nothing of its value was printed or kept. ${mintAgainSentence("general", origin)}`;
 var mintedRevocationLines = (revocation, minted) => "lines" in revocation ? [...revocation.lines, standsSentence(`The token it minted, ${minted.id},`, minted.id, minted.expiresAt)] : [`The token it minted, ${minted.id}, is revoked.`];
@@ -1301,6 +1338,8 @@ async function completeAct(io2, origin, kind, presentation, userAgent, say, deli
   const pending = read2.state.pending.get(origin);
   if (pending === void 0) {
     say(noPendingSentence(origin, kind, held ? "mint" : "code"));
+    const other = otherLivingRequestOf(read2.state.pending, origin, io2.clock());
+    if (other !== null) say(elsewhereRequestSentence(origin, other));
     return COMMAND_STATUS.nothing_started;
   }
   io2.hide(pending.verifier, REDACTED_VERIFIER);
@@ -2626,7 +2665,14 @@ var localWriteLineIn = (data) => {
 var localWriteLineOf = (found) => found === null ? null : `${WARNING_LINE_HEAD}${shownNoteName(found.name)}, line ${found.line}, writes to a local file inside the application's folder. A running copy's disk is lost whenever the copy is replaced or stops: keep files in a storage area and records in a database, as read_documentation's pages /cloud/guides/store-files/ and /cloud/guides/add-a-database/ describe.`;
 var LIST_LINE_HEAD = "file: ";
 var listLineOf = (file) => `${LIST_LINE_HEAD}${file.size} ${shownWhole(file.name)}`;
-var NO_NOTES = Object.freeze({ leftOut: Object.freeze([]), rootZips: Object.freeze([]), rootRunOutput: Object.freeze([]), credentialFiles: Object.freeze([]), localWrite: null, unservedHealthPath: null, nearestHealthPath: null });
+var NO_NOTES = Object.freeze({ leftOut: Object.freeze([]), rootZips: Object.freeze([]), rootRunOutput: Object.freeze([]), credentialFiles: Object.freeze([]), localWrite: null, unservedHealthPath: null, nearestHealthPath: null, gitignored: Object.freeze([]) });
+var gitignoredLineOf = (entries) => entries.length === 0 ? null : `note: .gitignore lists ${entries.length === 1 ? "a file" : `${entries.length} files`} the upload includes, since the zip never honours .gitignore: a build's output is often listed there, and the image build runs no build script. ${listedPairs(entries)}. To leave a path out, list it in .deployignore at the folder's root.`;
+var listedPairs = (entries) => {
+  const sorted = [...entries].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  const shown2 = sorted.slice(0, NOTE_NAMES_MAX).map((entry) => `${shownNoteName(entry.name)} (${shownNoteName(entry.pattern)})`).join(", ");
+  const rest = sorted.length - NOTE_NAMES_MAX;
+  return rest > 0 ? `${shown2}, and ${rest} more` : shown2;
+};
 var noteLinesOf = (notes, health, zipped = null) => {
   const lines = [];
   const files = zipped === null ? null : filesLineOf(zipped.map((file) => file.name));
@@ -2641,6 +2687,8 @@ var noteLinesOf = (notes, health, zipped = null) => {
   if (credential !== null) lines.push(credential);
   const localWrite = localWriteLineOf(notes.localWrite);
   if (localWrite !== null) lines.push(localWrite);
+  const gitignored = gitignoredLineOf(notes.gitignored ?? []);
+  if (gitignored !== null) lines.push(gitignored);
   if (health && notes.unservedHealthPath !== null) {
     lines.push(healthLineOf(notes.unservedHealthPath));
     if (notes.nearestHealthPath !== null) lines.push(nearestHealthLineOf(notes.nearestHealthPath));
@@ -3512,6 +3560,96 @@ import { readdirSync, readFileSync as readFileSync3, statSync as statSync2 } fro
 import { join as join5 } from "node:path";
 import * as zlib from "node:zlib";
 import { deflateRawSync, inflateRawSync as inflateRawSync2 } from "node:zlib";
+
+// src/turnzero_cloud_command/ignore_rules.ts
+var DEPLOY_IGNORE_FILE = ".deployignore";
+var GIT_IGNORE_FILE = ".gitignore";
+var matcherOf = (body, anchored) => {
+  let source = "";
+  for (let i2 = 0; i2 < body.length; i2 += 1) {
+    const c = body[i2];
+    if (c === "\\" && i2 + 1 < body.length) {
+      source += body[i2 + 1].replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+      i2 += 1;
+    } else if (c === "*" && body[i2 + 1] === "*") {
+      const before = i2 === 0 || body[i2 - 1] === "/";
+      const after = i2 + 2 === body.length || body[i2 + 2] === "/";
+      if (before && after) {
+        if (i2 + 2 === body.length) source += ".*";
+        else {
+          source += "(?:.*/)?";
+          i2 += 1;
+        }
+        i2 += 1;
+      } else {
+        source += "[^/]*";
+        i2 += 1;
+      }
+    } else if (c === "*") source += "[^/]*";
+    else if (c === "?") source += "[^/]";
+    else if (c === "[") {
+      const found = classOf(body, i2);
+      if (found === null) source += "\\[";
+      else {
+        source += found.source;
+        i2 = found.end;
+      }
+    } else source += c.replace(/[.+^${}()|\\]/g, "\\$&");
+  }
+  return new RegExp(anchored ? `^${source}$` : `^(?:.*/)?${source}$`);
+};
+var classOf = (body, open) => {
+  let i2 = open + 1;
+  const negated = body[i2] === "!" || body[i2] === "^";
+  if (negated) i2 += 1;
+  let inner = "";
+  for (let first = true; i2 < body.length; i2 += 1, first = false) {
+    const c = body[i2];
+    if (c === "]" && !first) return { source: negated ? `[^/${inner}]` : `(?!/)[${inner}]`, end: i2 };
+    if (c === "\\" && i2 + 1 < body.length) {
+      i2 += 1;
+      inner += inClass(body[i2]);
+    } else inner += c === "-" ? c : inClass(c);
+  }
+  return null;
+};
+var inClass = (c) => c.replace(/[\\\]\[^-]/g, "\\$&");
+function ignoreRulesOf(text) {
+  const rules = [];
+  for (const [index, raw] of text.split(/\r?\n/).entries()) {
+    let line = raw.replace(/(?<!\\) +$/, "");
+    if (line === "" || line.startsWith("#") || /(?:^|[^\\])(?:\\\\)*\\$/.test(line)) continue;
+    const negated = line.startsWith("!");
+    if (negated) line = line.slice(1);
+    else if (line.startsWith("\\!") || line.startsWith("\\#")) line = line.slice(1);
+    const folderOnly = line.endsWith("/");
+    let body = folderOnly ? line.slice(0, -1) : line;
+    const anchored = body.includes("/");
+    if (body.startsWith("/")) body = body.slice(1);
+    if (body === "") continue;
+    rules.push({ pattern: raw.trim(), line: index + 1, negated, folderOnly, matcher: matcherOf(body, anchored) });
+  }
+  return rules;
+}
+function ignoringRuleOf(rules, path, folder) {
+  if (rules.length === 0) return null;
+  const segments = path.split("/");
+  for (let depth = 1; depth < segments.length; depth += 1) {
+    const ancestor = ruleAt(rules, segments.slice(0, depth).join("/"), true);
+    if (ancestor !== null) return ancestor;
+  }
+  return ruleAt(rules, path, folder);
+}
+var ruleAt = (rules, path, folder) => {
+  let decided = null;
+  for (const rule of rules) {
+    if (rule.folderOnly && !folder) continue;
+    if (rule.matcher.test(path)) decided = rule.negated ? null : rule;
+  }
+  return decided;
+};
+
+// src/turnzero_cloud_command/zip.ts
 var AI_TOOL_NAMES = Object.freeze([
   ".claude",
   ".mcp.json",
@@ -3537,14 +3675,23 @@ var ZIP_VERSION = 20;
 var ZIP32_MAX = 4294967295;
 var ZipRefusal = class extends Error {
 };
-var walkFolder = (root, limit, leftOut) => {
+var rootIgnoreRulesOf = (root, name) => {
+  try {
+    const path = join5(root, name);
+    return statSync2(path).isFile() ? ignoreRulesOf(readFileSync3(path, "utf8")) : [];
+  } catch {
+    return [];
+  }
+};
+var walkFolder = (root, limit, leftOut, ignore = []) => {
   const found = [];
   const pending = [{ path: root, name: "" }];
   while (pending.length > 0) {
     const folder = pending.pop();
     for (const entry of readdirSync(folder.path, { withFileTypes: true })) {
       const name = folder.name === "" ? entry.name : `${folder.name}/${entry.name}`;
-      if (leftOutName(entry.name)) {
+      const kept2 = folder.name === "" && (entry.name === "package.json" || entry.name === MANIFEST_FILE);
+      if (leftOutName(entry.name) || !kept2 && ignoringRuleOf(ignore, name, entry.isDirectory()) !== null) {
         leftOut?.push(entry.isDirectory() ? `${name}/` : name);
         continue;
       }
@@ -3644,7 +3791,9 @@ function zipFolder(root, seams = {}) {
   }
   if (!rootFile) throw new ZipRefusal(NO_PACKAGE_SENTENCE);
   const leftOut = [];
-  const files = (seams.walk ?? walkFolder)(root, ARTIFACT_ENTRIES_MAX + 1, leftOut);
+  const deployIgnore = rootIgnoreRulesOf(root, DEPLOY_IGNORE_FILE);
+  const gitIgnore = rootIgnoreRulesOf(root, GIT_IGNORE_FILE);
+  const files = (seams.walk ?? walkFolder)(root, ARTIFACT_ENTRIES_MAX + 1, leftOut, deployIgnore);
   if (files.length > ARTIFACT_ENTRIES_MAX) throw new ZipRefusal(entryBoundSentence());
   const manifest = files.find((file) => file.name === MANIFEST_FILE);
   let healthPath = null;
@@ -3692,7 +3841,11 @@ function zipFolder(root, seams = {}) {
       credentialFiles,
       localWrite,
       unservedHealthPath: segment !== null && !held ? healthPath : null,
-      nearestHealthPath: segment !== null && !held && healthPath !== null ? nearestHealthPathOf(healthLike, healthPath) : null
+      nearestHealthPath: segment !== null && !held && healthPath !== null ? nearestHealthPathOf(healthLike, healthPath) : null,
+      gitignored: files.flatMap((file) => {
+        const rule = ignoringRuleOf(gitIgnore, file.name, false);
+        return rule === null ? [] : [{ name: file.name, pattern: rule.pattern }];
+      })
     }
   };
 }
@@ -4139,8 +4292,9 @@ var DEPLOY_ROW = Object.freeze({
   note: [
     `A deploy is one line, which carries no credential: run the line your tool's deploy call answers, or ${DEPLOY_SUBCOMMAND} ${DEPLOY_OPTION.application} <application id>, from the application's folder. It reads no standard input. On an authorized computer it runs under this computer's token, which ${LOGIN_SUBCOMMAND} or ${AUTHORIZE_SUBCOMMAND} keeps in the credential file for each platform address. It sends that token only to the address it is kept under: ${DEPLOY_OPTION.origin} where the line names one, else the address ${ORIGIN_VARIABLE} holds, else ${DEFAULT_COMMAND_ORIGIN}.`,
     `On a computer with no token for that address, or one that has expired, it sends nothing, ends 3, and prints two routes, in this order. A tool connected by a minted token, or a job with no tool, such as a CI job's, sets ${MINTED_TOKEN_VARIABLE} from where its token is kept, never by writing the value in a line. It sets ${ORIGIN_VARIABLE} to the address that minted the token where that is not ${DEFAULT_COMMAND_ORIGIN}, then runs the deploy line again. Such a tool cannot use ${MINT_TOKEN_ACTION}, which takes a sign-in alone.`,
-    `Otherwise a person logs this computer in once with ${LOGIN_SUBCOMMAND}, in a terminal of their own, then runs the deploy line again. The credential file is ${CREDENTIAL_FILE_WORDS}.`,
-    `${DEPLOY_FILES_ROUTE_SENTENCE} ${HAND_OVER_SENTENCE}`,
+    `The second route authorizes this computer, and the deploy line then runs again. A tool signed in to the platform may do it itself with ${AUTHORIZE_SUBCOMMAND}, and the run prints the person's way, ${LOGIN_SUBCOMMAND}, run once in a terminal of their own. The credential file is ${CREDENTIAL_FILE_WORDS}.`,
+    DEPLOY_ROUTES_SENTENCE,
+    HAND_OVER_SENTENCE,
     `A tool sets ${MINTED_TOKEN_VARIABLE} for one line at a time and unsets it once that line ends, since the command cannot unset a variable of the shell that started it. A value a job's environment already supplies stays as it stands. A job's token is minted for the application, with an expiry. The variable's token wins over the credential file: the command makes the preparing call under that token, and sends the token in no other request.`,
     `Under the variable, the command sends its token only to the address ${ORIGIN_VARIABLE} holds, or to ${DEFAULT_COMMAND_ORIGIN} where that variable is unset. Under the token, ${DEPLOY_OPTION.origin} may name that address alone, and where the line names none the command addresses it. ${DEPLOY_OPTION.env} names the environment where a line names one, ${COMMAND_ENVIRONMENTS.join(" or ")}. Where none is named, the platform chooses, and the command deploys to the environment the platform answers.`,
     `A progress read answered 502, 503, or 504, which is often temporary, is made again, at most three more times. An upload answered 503 credential_lookup_busy, which wrote nothing, is made again after the wait it names, at most twice.`,
@@ -6242,7 +6396,7 @@ var whoamiLinesOf = (origin, account, entry) => [
   `${WHOAMI_LINE_HEADS.token}label ${entry.label !== null ? JSON.stringify(entry.label) : "none"}, expiring ${entry.expires_at !== null ? `at ${entry.expires_at}` : "never"}`
 ];
 var noComputerTokenSentence = (origin, expiredAt) => expiredAt === null ? `This computer's credential file holds no token for ${origin}, so nothing was sent.` : `This computer's token for ${origin} in its credential file expired at ${expiredAt}, so nothing was sent.`;
-var noLoginRoutesSentence = (origin) => `Your AI coding tool's own sign-in is not this computer's credential. With no login, deploy_files deploys a folder within its caps; past them, upload a zip with mint_upload_grant, then name it as deploy's artifact. ${PROVISION_SUBCOMMAND}${originWordsOf(origin)} run with nothing piped prints the call that answers its line.`;
+var noLoginRoutesSentence = (origin) => `Your AI coding tool's own sign-in is not this computer's credential. For regular use, prefer this command where it works. A signed-in tool can authorize this computer with ${AUTHORIZE_SUBCOMMAND}${originWordsOf(origin)}; the login route below is the person's alternative. A first simple test within the caps of your tool's deploy_files call may deploy through deploy_files with no login, as may any folder within them where this command cannot work. Past the caps, or for a file deploy_files cannot carry, where this command cannot run, upload a zip with mint_upload_grant, then name it as deploy's artifact. ${PROVISION_SUBCOMMAND}${originWordsOf(origin)} run with nothing piped prints the call that answers its line.`;
 var whoamiAfterLoginSentence = (whoami2) => `Once login has printed authorized:, run ${whoami2} again.`;
 async function whoami(call, io2) {
   const origin = entryOriginOf(io2.env, call.named[DEPLOY_OPTION.origin], NOTHING_SENT_OR_READ);
@@ -6298,7 +6452,7 @@ async function whoami(call, io2) {
 }
 var WHOAMI_ROW = Object.freeze({
   name: WHOAMI_SUBCOMMAND,
-  summary: `Names the account this computer's token acts as at the platform's address. It reads the token the credential file keeps for the address, and makes one ${READ_ACCOUNT_ACTION} call under it. It prints the address, the account's sign-in address and id, and the token's label and expiry. With no token for the address, it sends nothing. It names the ways on with no login (deploy_files, the upload route, and ${PROVISION_SUBCOMMAND}), then prints the login route. It prints no token.`,
+  summary: `Names the account this computer's token acts as at the platform's address. It reads the token the credential file keeps for the address, and makes one ${READ_ACCOUNT_ACTION} call under it. It prints the address, the account's sign-in address and id, and the token's label and expiry. With no token for the address, it sends nothing. It names the routes a tool takes itself (${AUTHORIZE_SUBCOMMAND}, deploy_files, the upload route, and ${PROVISION_SUBCOMMAND}), then the person's login route. It prints no token.`,
   example: WHOAMI_SUBCOMMAND,
   options: WHOAMI_OPTIONS,
   credential: null,
@@ -9761,6 +9915,43 @@ var TZMESH_OPTIONS = Object.freeze([
     required: false,
     description: `Under ${TZMESH_OPTION.secret}, the environment of that application whose scope holds the secret, ${COMMAND_ENVIRONMENTS.join(" or ")}. It goes with ${TZMESH_OPTION.application}.`
   },
+  {
+    name: TZMESH_OPTION.webhookOrigin,
+    value: "<origin>",
+    required: false,
+    description: `Under ${TZMESH_OPTION.secret}, the https origin of the application that hosts the agent. The run sets the agent's webhook to ${TZMESH_WEBHOOK_ROUTE} at that origin, and stores its signing secret under ${TZMESH_OPTION.webhookSecret}.`
+  },
+  {
+    name: TZMESH_OPTION.webhookSecret,
+    value: "<secret name>",
+    required: false,
+    description: `With ${TZMESH_OPTION.webhookOrigin}, the name the webhook's signing secret is stored under, in the scope ${TZMESH_OPTION.secret} is stored in. It names the secret and never holds it.`
+  },
+  {
+    name: TZMESH_OPTION.description,
+    value: "<text>",
+    required: false,
+    description: `Under ${TZMESH_OPTION.secret}, the agent's description, at most ${TZMESH_DESCRIPTION_MAX} characters.`
+  },
+  {
+    name: TZMESH_OPTION.title,
+    value: "<text>",
+    required: false,
+    description: `Under ${TZMESH_OPTION.secret}, the agent's title, at most ${TZMESH_TITLE_MAX} characters.`
+  },
+  {
+    name: TZMESH_OPTION.join,
+    value: "<channels>",
+    required: false,
+    description: `Under ${TZMESH_OPTION.secret}, the channels the agent joins, as one value: channel ids, #names, or account/#names, separated by commas.`
+  },
+  {
+    name: TZMESH_OPTION.public,
+    value: "",
+    required: false,
+    flag: true,
+    description: `Under ${TZMESH_OPTION.secret}, makes the agent public at its register. Whether it is public is your choice: a tool passes this only after you answer.`
+  },
   {
     name: TZMESH_OPTION.force,
     value: "",
@@ -9787,7 +9978,69 @@ var TZMESH_OPTIONS = Object.freeze([
     description: `The mint the line names, by its id, as the line a ${MINT_TOKEN_ACTION} call answers names it. The id is no credential. Under it, the command presents this computer's verifier for that mint.`
   }
 ]);
-var UNPRINTABLE_PATH = /["$`%\u0000-\u001f\u007f]/;
+var SETUP_OPTIONS = [TZMESH_OPTION.webhookOrigin, TZMESH_OPTION.webhookSecret, TZMESH_OPTION.description, TZMESH_OPTION.title, TZMESH_OPTION.join];
+var UNCARRIED_WORDS = "a double quote, $, a backtick, %, !, &, |, <, >, ^, a curly double quote, a doubled or trailing backslash, or a control character";
+var JOIN_CHANNEL_FORM = /^[^\s,]{1,200}$/;
+var WEBHOOK_ORIGIN_FORM = /^https:\/\/[a-z0-9.-]+(?::[0-9]{1,5})?$/;
+var isHttpsOrigin = (value) => {
+  if (!WEBHOOK_ORIGIN_FORM.test(value)) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && url.origin === value && url.username === "" && url.password === "";
+  } catch {
+    return false;
+  }
+};
+var setupOptionsOf = (call, toFile, closing) => {
+  const named = (option) => call.named[option] ?? null;
+  const isPublic = call.flags.has(TZMESH_OPTION.public);
+  if (toFile) {
+    const given = [...SETUP_OPTIONS.filter((option) => named(option) !== null), ...isPublic ? [TZMESH_OPTION.public] : []];
+    if (given.length > 0) return { refusal: `${given[0]} goes with ${TZMESH_OPTION.secret} alone: an agent whose secret goes into a file is set up by its own program. ${closing}` };
+  }
+  const webhookOrigin = named(TZMESH_OPTION.webhookOrigin);
+  const webhookSecret = named(TZMESH_OPTION.webhookSecret);
+  if (webhookOrigin === null !== (webhookSecret === null)) {
+    return { refusal: `${TZMESH_OPTION.webhookOrigin} and ${TZMESH_OPTION.webhookSecret} go together: the webhook's address, and the name its signing secret is stored under. ${closing}` };
+  }
+  if (webhookOrigin !== null && !isHttpsOrigin(webhookOrigin)) {
+    return {
+      refusal: `${TZMESH_OPTION.webhookOrigin} names the https origin of the application that hosts the agent, such as https://<name>.ai.host: its host in lowercase letters, digits, hyphens, and dots, with no path. ${closing}`
+    };
+  }
+  if (webhookSecret !== null && !SECRET_NAME_FORM.test(webhookSecret)) {
+    return { refusal: `${TZMESH_OPTION.webhookSecret} names the secret the webhook's signing secret is stored under: a letter or digit first, then letters, digits, _ or -, up to 64 characters. ${closing}` };
+  }
+  const secret2 = named(TZMESH_OPTION.secret);
+  if (webhookSecret !== null && secret2 !== null && webhookSecret.toLowerCase() === secret2.toLowerCase()) {
+    return { refusal: `${TZMESH_OPTION.webhookSecret} names a secret other than the one ${TZMESH_OPTION.secret} names: the agent's secret and the webhook's signing secret are stored under two names. ${closing}` };
+  }
+  const bounded = (option, max) => {
+    const value = named(option);
+    if (value === null) return null;
+    if (value === "" || [...value].length > max) return { refusal: `${option} takes 1 to ${max} characters. ${closing}` };
+    if (!lineValueCarries(value)) return { refusal: `${option} holds a character a line cannot carry alike in every shell between double quotes: ${UNCARRIED_WORDS}. ${closing}` };
+    return value;
+  };
+  const description = bounded(TZMESH_OPTION.description, TZMESH_DESCRIPTION_MAX);
+  if (description !== null && typeof description === "object") return description;
+  const title = bounded(TZMESH_OPTION.title, TZMESH_TITLE_MAX);
+  if (title !== null && typeof title === "object") return title;
+  const joinValue = named(TZMESH_OPTION.join);
+  const join12 = joinValue === null ? [] : joinValue.split(",");
+  if (joinValue !== null && (join12.some((channel) => !JOIN_CHANNEL_FORM.test(channel)) || !lineValueCarries(joinValue))) {
+    return {
+      refusal: `${TZMESH_OPTION.join} lists the channels the agent joins, as one value: ids, #names, or account/#names, separated by commas, with no space and nothing a line cannot carry between double quotes: ${UNCARRIED_WORDS}. ${closing}`
+    };
+  }
+  return {
+    webhook: webhookOrigin !== null && webhookSecret !== null ? { origin: webhookOrigin, secretName: webhookSecret } : null,
+    description,
+    title,
+    join: join12,
+    public: isPublic
+  };
+};
 var closingOf = (call) => call.named[TZMESH_OPTION.mint] !== void 0 ? MINT_UNPRESENTED : NOTHING_SENT;
 var TZMESH_MINT_ID_REFUSAL = `${TZMESH_OPTION.mint} names the mint by its id, a lowercase UUID, as the line the ${MINT_TOKEN_ACTION} call answered names it: run that line as given, with the options the first act printed after it. ${NOTHING_SENT}`;
 var tzmeshOriginRefusal = (closing) => `${TZMESH_OPTION.origin} names the platform's address the secret is stored at, and ${TZMESH_ACT_WORDS} reaches only ${DEFAULT_COMMAND_ORIGIN} or ${DEVELOPMENT_COMMAND_ORIGIN}. Where the line names none, ${ORIGIN_VARIABLE} must hold one of those two, or be unset. ${closing}`;
@@ -9820,9 +10073,11 @@ var tzmeshOptionsOf = (call, io2) => {
   const force = call.flags.has(TZMESH_OPTION.force);
   if (force && toFile === void 0) return { refusal: `${TZMESH_OPTION.force} goes with ${TZMESH_OPTION.toFile} alone: it replaces a file that stands there. ${closing}` };
   const path = toFile !== void 0 ? resolve13(io2.cwd, toFile) : null;
-  if (path !== null && UNPRINTABLE_PATH.test(path)) {
-    return { refusal: `${TZMESH_OPTION.toFile} names a path holding a character a line cannot carry between double quotes: a double quote, $, a backtick, %, or a control character. Name a path without one. ${closing}` };
+  if (path !== null && !lineValueCarries(path)) {
+    return { refusal: `${TZMESH_OPTION.toFile} names a path holding a character a line cannot carry alike in every shell between double quotes: ${UNCARRIED_WORDS}. Name a path without one. ${closing}` };
   }
+  const setup = setupOptionsOf(call, toFile !== void 0, closing);
+  if ("refusal" in setup) return setup;
   const origin = entryOriginOf(io2.env, call.named[TZMESH_OPTION.origin], closing);
   if ("refusal" in origin) return origin;
   if (!FIRST_PARTY_COMMAND_ORIGINS.includes(origin.origin)) return { refusal: tzmeshOriginRefusal(closing) };
@@ -9837,7 +10092,8 @@ var tzmeshOptionsOf = (call, io2) => {
     force,
     origin: origin.origin,
     estate,
-    mint
+    mint,
+    ...setup
   };
 };
 var completingOptionsOf = (options) => {
@@ -9846,6 +10102,11 @@ var completingOptionsOf = (options) => {
     ..."secret" in options.route ? { secret: options.route.secret } : { toFile: options.route.toFile },
     ...options.application !== null ? { application: options.application } : {},
     ...options.environment !== null ? { environment: options.environment } : {},
+    ...options.webhook !== null ? { webhookOrigin: options.webhook.origin, webhookSecret: options.webhook.secretName } : {},
+    ...options.description !== null ? { description: options.description } : {},
+    ...options.title !== null ? { title: options.title } : {},
+    ...options.join.length > 0 ? { join: options.join } : {},
+    ...options.public ? { public: true } : {},
     ...options.force ? { force: true } : {},
     origin: options.origin,
     tzmeshEstate: options.estate
@@ -9930,13 +10191,20 @@ var postWire = async (io2, wire, path, bearer, userAgent, body) => {
     cancel();
   }
 };
-var register = async (io2, wire, token2, userAgent, name) => {
-  const answered = await postWire(io2, wire, TZMESH_REGISTER_PATH, token2, userAgent, { kind: "standing", name, label: TZMESH_COMMAND_LABEL });
+var register = async (io2, wire, token2, userAgent, options) => {
+  const answered = await postWire(io2, wire, TZMESH_REGISTER_PATH, token2, userAgent, {
+    kind: "standing",
+    name: options.name,
+    label: TZMESH_COMMAND_LABEL,
+    ...options.title !== null ? { title: options.title } : {},
+    ...options.description !== null ? { description: options.description } : {},
+    ...options.public ? { visibility: "public" } : {}
+  });
   if (answered === null) return { unknown: [`The ${REGISTER_ACT} drew no answer.`] };
   if (answered.redirected) return { unknown: [`The ${REGISTER_ACT} was answered ${answeredHow(answered.status)}, which the command never follows, so the token was sent to no second address.`] };
-  if (answered.status >= PLATFORM_FAILURE_STATUS) return { unknown: failureLines(REGISTER_ACT, answered.status, planeRefusalOf(answered.text)) };
   const answer = planeObjectOf(answered.text);
   if (answer !== null && typeof answer.secret === "string") io2.hide(answer.secret, REDACTED_PROGRAM_SECRET);
+  if (answered.status >= PLATFORM_FAILURE_STATUS) return { unknown: failureLines(REGISTER_ACT, answered.status, planeRefusalOf(answered.text)) };
   if (answered.status < 200 || answered.status > 299) {
     const refusal = planeRefusalOf(answered.text);
     if (refusal === null) return { unknown: [`The ${REGISTER_ACT} was answered HTTP ${answered.status}, not by the tzMesh service.`] };
@@ -9956,10 +10224,60 @@ var register = async (io2, wire, token2, userAgent, name) => {
 var deleteAgent = async (io2, wire, token2, userAgent, agent) => {
   const answered = await postWire(io2, wire, TZMESH_END_PATH, token2, userAgent, { participant: agent.id, delete: true });
   const deleted = answered !== null && !answered.redirected && answered.status >= 200 && answered.status <= 299 && planeObjectOf(answered.text) !== null;
-  if (deleted) return [`The agent ${agentWords(agent)} was deleted, and its name is free again.`];
-  const why = answered === null ? [`The ${END_ACT} drew no answer.`] : answered.redirected ? [`The ${END_ACT} was answered ${answeredHow(answered.status)}, which the command never follows.`] : answered.status >= PLATFORM_FAILURE_STATUS ? failureLines(END_ACT, answered.status, planeRefusalOf(answered.text)) : planeRefusalOf(answered.text) !== null ? refusalLines(END_ACT, answered.status, planeRefusalOf(answered.text)) : [`The ${END_ACT} was answered HTTP ${answered.status}, not by the tzMesh service.`];
-  return [...why, agentStandsSentence(agent)];
-};
+  if (deleted) return { deleted: true, lines: [`The agent ${agentWords(agent)} was deleted, and its name is free again.`], unknown: false };
+  const refusal = answered === null || answered.redirected || answered.status >= PLATFORM_FAILURE_STATUS ? null : planeRefusalOf(answered.text);
+  const why = answered === null ? [`The ${END_ACT} drew no answer.`] : answered.redirected ? [`The ${END_ACT} was answered ${answeredHow(answered.status)}, which the command never follows.`] : answered.status >= PLATFORM_FAILURE_STATUS ? failureLines(END_ACT, answered.status, planeRefusalOf(answered.text)) : refusal !== null ? refusalLines(END_ACT, answered.status, refusal) : [`The ${END_ACT} was answered HTTP ${answered.status}, not by the tzMesh service.`];
+  return { deleted: false, lines: why, unknown: refusal === null };
+};
+var WEBHOOK_ACT = "webhook_set";
+var JOIN_ACT = "join";
+var WEBHOOK_LINE_HEAD = "webhook: ";
+var JOINED_LINE_HEAD = "joined: ";
+var webhookLineOf = (url) => `${WEBHOOK_LINE_HEAD}set to ${url}, its signing secret printed nowhere`;
+var setupCall = async (io2, wire, path, secret2, userAgent, act, body, hide) => {
+  const answered = await postWire(io2, wire, path, secret2, userAgent, body);
+  if (answered === null) return { unknown: [`The ${act} drew no answer.`] };
+  if (answered.redirected) return { unknown: [`The ${act} was answered ${answeredHow(answered.status)}, which the command never follows, so the secret was sent to no second address.`] };
+  const answer = planeObjectOf(answered.text);
+  hide(answer);
+  if (answered.status >= PLATFORM_FAILURE_STATUS) return { unknown: failureLines(act, answered.status, planeRefusalOf(answered.text)) };
+  if (answered.status < 200 || answered.status > 299) {
+    const refusal = planeRefusalOf(answered.text);
+    if (refusal === null) return { unknown: [`The ${act} was answered HTTP ${answered.status}, not by the tzMesh service.`] };
+    return { refused: refusalLines(act, answered.status, refusal) };
+  }
+  if (answer === null) return { unknown: [`The ${act} was answered HTTP ${answered.status}, not by the tzMesh service.`] };
+  return { answer };
+};
+var setUpAgent = async (io2, wire, secret2, userAgent, options, ended) => {
+  let signing = null;
+  if (options.webhook !== null) {
+    const url = `${options.webhook.origin}${TZMESH_WEBHOOK_ROUTE}`;
+    const set = await setupCall(io2, wire, TZMESH_WEBHOOK_SET_PATH, secret2, userAgent, WEBHOOK_ACT, { url }, (answer) => {
+      if (typeof answer?.signing_secret === "string") io2.hide(answer.signing_secret, REDACTED_WEBHOOK_SECRET);
+    });
+    if (ended()) return "ended";
+    if (!("answer" in set)) return "refused" in set ? { refused: [...set.refused, "The webhook was not set."] } : set;
+    const value = set.answer.signing_secret;
+    if (typeof value !== "string" || !TZMESH_WEBHOOK_SECRET_FORM.test(value)) {
+      return { refused: [`The ${WEBHOOK_ACT} answered no signing secret of its form, so the command keeps none.`] };
+    }
+    signing = value;
+    io2.print(webhookLineOf(url));
+  }
+  for (const channel of options.join) {
+    const joined = await setupCall(io2, wire, TZMESH_JOIN_PATH, secret2, userAgent, JOIN_ACT, { channel }, () => void 0);
+    if (ended()) return "ended";
+    if (!("answer" in joined)) return "refused" in joined ? { refused: [...joined.refused, `The agent did not join ${channel}.`] } : joined;
+    io2.print(`${JOINED_LINE_HEAD}${channel}`);
+  }
+  return { signing };
+};
+var firstStoreStandsSentence = (secretName) => `${secretName} now holds the deleted agent's secret, which works nowhere, until the line runs again.`;
+var signingUnknownSentence = (signingName, agent) => `Whether the webhook's signing secret was stored is unknown: list_secrets from your tool shows when ${signingName} was last written. Where it was not written, end from your tool, naming participant ${agent.id} and delete true, deletes the agent ${agentWords(agent)}, and the line runs again.`;
+var unfinishableSentence = (agent) => `The agent ${agentWords(agent)} cannot be finished, since its webhook's signing secret ended with the run: end from your tool, naming participant ${agent.id} and delete true, deletes it, and the line runs again.`;
+var firstStoreUnknownSentence = (secretName) => `Whether ${secretName} was written is unknown: list_secrets from your tool shows when it was last written. Where it was, it holds the deleted agent's secret, which works nowhere, until the line runs again.`;
+var unfinishedStandsSentence = (agent, kept2) => `${kept2.known ? `${kept2.name} holds the secret of the agent ${agentWords(agent)}.` : `Whether ${kept2.name} holds the secret of the agent ${agentWords(agent)} is unknown: list_secrets from your tool shows when it was last written.`} ${unfinishableSentence(agent)}`;
 var revokeRunToken = async (io2, plane, bearer, id, userAgent) => {
   const answered = await postAction(io2, plane, REVOKE_TOKEN_ACTION, bearer, userAgent, revocationBodyOf(id));
   let lines;
@@ -9979,7 +10297,8 @@ var revokeRunToken = async (io2, plane, bearer, id, userAgent) => {
   }
   return [...lines, tokenStandsSentence(id)];
 };
-var endedLineOf = (stage, plane, agent, route) => {
+var endedLineOf = (stage, plane, agent, options) => {
+  const route = options.route;
   switch (stage) {
     case "unsent":
       return `The run was ended before its exchange. ${MINT_UNPRESENTED}`;
@@ -9990,7 +10309,11 @@ var endedLineOf = (stage, plane, agent, route) => {
     case "registering":
       return `The run was ended during the register. ${REGISTER_UNKNOWN} ${TOKEN_LEFT}`;
     case "registered":
-      return agent === null ? `The run was ended after the register. ${REGISTER_UNKNOWN} ${TOKEN_LEFT}` : "secret" in route ? `The run was ended after the register, while its secret was being stored. ${storeUnknownSentence(route.secret, agent)} ${TOKEN_LEFT}` : `The run was ended after the register, before its secret was written. ${agentStandsSentence(agent)} ${TOKEN_LEFT}`;
+      return agent === null ? `The run was ended after the register. ${REGISTER_UNKNOWN} ${TOKEN_LEFT}` : "secret" in route ? options.webhook !== null ? `The run was ended after the register, while its secret was being stored. ${unfinishableSentence(agent)} ${TOKEN_LEFT}` : `The run was ended after the register, while its secret was being stored. ${storeUnknownSentence(route.secret, agent)} ${TOKEN_LEFT}` : `The run was ended after the register, before its secret was written. ${agentStandsSentence(agent)} ${TOKEN_LEFT}`;
+    case "setting up":
+      return agent === null ? `The run was ended after the register. ${REGISTER_UNKNOWN} ${TOKEN_LEFT}` : `The run was ended while the agent's webhook or channels were being set. tzmesh_participants from your tool shows the agent and its webhook. ${agentStandsSentence(agent)} ${TOKEN_LEFT}`;
+    case "storing signing":
+      return agent === null || options.webhook === null ? `The run was ended after the register. ${REGISTER_UNKNOWN} ${TOKEN_LEFT}` : `The run was ended while the webhook's signing secret was being stored. ${signingUnknownSentence(options.webhook.secretName, agent)} ${TOKEN_LEFT}`;
     case "stored":
       return `The run was ended after the agent's secret was kept, before the run's token was revoked. ${TOKEN_LEFT}`;
   }
@@ -10011,15 +10334,43 @@ var completing = async (io2, options, mint, tokens, userAgent) => {
     for (const line of lines) io2.print(line);
     return Math.max(status, COMMAND_STATUS.failed);
   };
-  const deletedThen = async (minted, standing) => {
-    const lines = await deleteAgent(io2, wire, minted.value, userAgent, standing);
+  const deletedThen = async (minted, standing, whenUnknown = COMMAND_STATUS.failed, kept2 = null) => {
+    const deleted = await deleteAgent(io2, wire, minted.value, userAgent, standing);
     if (stage.ended) return COMMAND_STATUS.unknown;
-    for (const line of lines) io2.print(line);
-    return revokedThen(minted, COMMAND_STATUS.failed);
+    for (const line of deleted.lines) io2.print(line);
+    if (deleted.deleted) {
+      if (kept2 !== null) io2.print(kept2.known ? firstStoreStandsSentence(kept2.name) : firstStoreUnknownSentence(kept2.name));
+    } else io2.print(kept2 === null ? agentStandsSentence(standing) : unfinishedStandsSentence(standing, kept2));
+    return revokedThen(minted, deleted.unknown ? whenUnknown : COMMAND_STATUS.failed);
+  };
+  const storeNamed = async (name, value) => {
+    const action = SECRET_ACTION.store;
+    const answered = await postAction(io2, options.origin, action, (tokens.store ?? tokens.mint).token, userAgent, {
+      name,
+      value,
+      ...options.application !== null ? { application: options.application } : {},
+      ...options.environment !== null ? { environment: options.environment } : {}
+    });
+    if (stage.ended) return "ended";
+    if (answered === null) return { unknown: [`${action} drew no answer.`] };
+    if (answered.redirected) return { unknown: [`${action} was answered ${answeredHow(answered.status)}, which the command never follows, so the value was sent to no second address.`] };
+    if (answered.status >= PLATFORM_FAILURE_STATUS) return { unknown: failureLines(action, answered.status, planeRefusalOf(answered.text)) };
+    const answer = planeObjectOf(answered.text);
+    if (answered.status < 200 || answered.status > 299) {
+      const refusal = markedRefusalOf(answered.status, answered.text);
+      if (refusal === null) return { unknown: [`${action} was answered HTTP ${answered.status}, not by the platform.`] };
+      for (const line of refusalLines(action, answered.status, refusal)) io2.print(line);
+      return "refused";
+    }
+    if (answer === null) return { unknown: [`${action} was answered HTTP ${answered.status}, not by the platform.`] };
+    io2.print(`${SECRET_LINE_HEAD.store}${JSON.stringify(Object.fromEntries(SECRET_SHOWN.filter((member) => member in answer).map((member) => [member, answer[member]])))}`);
+    if (typeof answer.detail === "string") io2.print(oneLine(answer.detail));
+    if ("value" in answer) io2.print("The answer carried a value, which the command never prints.");
+    return "stored";
   };
   const carried = {
     stage,
-    endedLine: (now) => endedLineOf(now, plane, agent, route),
+    endedLine: (now) => endedLineOf(now, plane, agent, options),
     // The file's try, by an empty file beside it under the run's tag,
     // owner-only, before any request (decision 6).
     prepare: () => {
@@ -10039,7 +10390,7 @@ var completing = async (io2, options, mint, tokens, userAgent) => {
     },
     deliver: async (minted) => {
       stage.now = "registering";
-      const registered = await register(io2, wire, minted.value, userAgent, options.name);
+      const registered = await register(io2, wire, minted.value, userAgent, options);
       if (stage.ended) return COMMAND_STATUS.unknown;
       if ("refused" in registered) {
         for (const line of registered.refused) io2.print(line);
@@ -10072,34 +10423,43 @@ var completing = async (io2, options, mint, tokens, userAgent) => {
         io2.print(WRITTEN_LINE);
         return revokedThen(minted, COMMAND_STATUS.done);
       }
-      const action = SECRET_ACTION.store;
-      const answered = await postAction(io2, options.origin, action, (tokens.store ?? tokens.mint).token, userAgent, {
-        name: route.secret,
-        value: secret2,
-        ...options.application !== null ? { application: options.application } : {},
-        ...options.environment !== null ? { environment: options.environment } : {}
-      });
-      if (stage.ended) return COMMAND_STATUS.unknown;
-      const unknownStore = async (lines) => {
-        for (const line of lines) io2.print(line);
+      let signing = null;
+      if (options.webhook !== null || options.join.length > 0) {
+        stage.now = "setting up";
+        const set = await setUpAgent(io2, wire, secret2, userAgent, options, () => stage.ended);
+        if (set === "ended" || stage.ended) return COMMAND_STATUS.unknown;
+        if ("refused" in set) {
+          for (const line of set.refused) io2.print(line);
+          return deletedThen(minted, agent);
+        }
+        if ("unknown" in set) {
+          for (const line of set.unknown) io2.print(line);
+          return deletedThen(minted, agent, COMMAND_STATUS.unknown);
+        }
+        signing = set.signing;
+        stage.now = "registered";
+      }
+      const stored = await storeNamed(route.secret, secret2);
+      if (stored === "ended" || stage.ended) return COMMAND_STATUS.unknown;
+      if (stored === "refused") return deletedThen(minted, agent);
+      if (stored !== "stored") {
+        for (const line of stored.unknown) io2.print(line);
+        if (options.webhook !== null) return deletedThen(minted, agent, COMMAND_STATUS.unknown, { name: route.secret, known: false });
         io2.print(storeUnknownSentence(route.secret, agent));
         return revokedThen(minted, COMMAND_STATUS.unknown);
-      };
-      if (answered === null) return unknownStore([`${action} drew no answer.`]);
-      if (answered.redirected) return unknownStore([`${action} was answered ${answeredHow(answered.status)}, which the command never follows, so the value was sent to no second address.`]);
-      if (answered.status >= PLATFORM_FAILURE_STATUS) return unknownStore(failureLines(action, answered.status, planeRefusalOf(answered.text)));
-      const answer = planeObjectOf(answered.text);
-      if (answered.status < 200 || answered.status > 299) {
-        const refusal = markedRefusalOf(answered.status, answered.text);
-        if (refusal === null) return unknownStore([`${action} was answered HTTP ${answered.status}, not by the platform.`]);
-        for (const line of refusalLines(action, answered.status, refusal)) io2.print(line);
-        return deletedThen(minted, agent);
       }
-      if (answer === null) return unknownStore([`${action} was answered HTTP ${answered.status}, not by the platform.`]);
+      if (options.webhook !== null && signing !== null) {
+        stage.now = "storing signing";
+        const kept2 = await storeNamed(options.webhook.secretName, signing);
+        if (kept2 === "ended" || stage.ended) return COMMAND_STATUS.unknown;
+        if (kept2 === "refused") return deletedThen(minted, agent, COMMAND_STATUS.failed, { name: route.secret, known: true });
+        if (kept2 !== "stored") {
+          for (const line of kept2.unknown) io2.print(line);
+          io2.print(signingUnknownSentence(options.webhook.secretName, agent));
+          return revokedThen(minted, COMMAND_STATUS.unknown);
+        }
+      }
       stage.now = "stored";
-      io2.print(`${SECRET_LINE_HEAD.store}${JSON.stringify(Object.fromEntries(SECRET_SHOWN.filter((member) => member in answer).map((member) => [member, answer[member]])))}`);
-      if (typeof answer.detail === "string") io2.print(oneLine(answer.detail));
-      if ("value" in answer) io2.print("The answer carried a value, which the command never prints.");
       return revokedThen(minted, COMMAND_STATUS.done);
     }
   };
@@ -10173,6 +10533,7 @@ var TZMESH_ROW = Object.freeze({
     `Registering an agent takes two acts around one ${MINT_TOKEN_ACTION} call, which your signed-in tool makes itself. ${TZMESH_ACT_WORDS} run without ${TZMESH_OPTION.mint} prints a challenge, the call to make, and the options its completing line takes. Your tool makes that call, and runs the line it answers once, on this computer, with those options after it. That line holds no code.`,
     `The completing line presents this computer's verifier and receives a tzMesh token minted for this run alone. It registers the agent with that token, keeps the agent's secret, and revokes the token. Where the secret could not be kept, it deletes the agent.`,
     `With ${TZMESH_OPTION.secret}, the secret goes from the register's answer to your account's secret store, and never reaches your tool. With ${TZMESH_OPTION.toFile}, it goes into that file, which anything that runs as you can read, your tool among them. Keep that file outside any application's folder.`,
+    `For an agent a Turn Zero Cloud application hosts, the same run sets it up. ${TZMESH_OPTION.webhookOrigin} sets its webhook at that application's origin, and ${TZMESH_OPTION.webhookSecret} names where the webhook's signing secret is stored. ${TZMESH_OPTION.join} joins its channels. Its description, title, and ${TZMESH_OPTION.public} go into the register. Where a step fails, follow the recovery the run prints before running the line again.`,
     `The run reads this computer's token for each address it sends to: the ${TZMESH_OPTION.tzmeshEstate} platform's, to revoke the run's token, and under ${TZMESH_OPTION.secret} the ${TZMESH_OPTION.origin} platform's, to store the secret. Authorize this computer at each first.`
   ],
   afterOwnError: (call) => call.named[TZMESH_OPTION.mint] !== void 0 ? TZMESH_AFTER_OWN_ERROR : TZMESH_FIRST_ACT_AFTER_OWN_ERROR,
@@ -10519,7 +10880,7 @@ var SUBCOMMANDS = Object.freeze([
 ]);
 var listedSubcommands = () => SUBCOMMANDS.filter((subcommand) => subcommand.listed !== false);
 var SERVED = LINE_RUNNER;
-var NPX_FORM_SENTENCE = `Where the command is not installed, install it with ${installLineOf(DEFAULT_COMMAND_ORIGIN)}. A person or a job may instead run the same line through npx: write ${commandRunnerOf("latest")} for ${LINE_RUNNER}. A tool where the command is not installed deploys through deploy_files within its caps and the upload route past them. For any other line it takes the deploy skill's setup steps, never the npx line.`;
+var NPX_FORM_SENTENCE = `Where the command is not installed, install it with ${installLineOf(DEFAULT_COMMAND_ORIGIN)}. A person or a job may instead run the same line through npx: write ${commandRunnerOf("latest")} for ${LINE_RUNNER}. A tool where the command is not installed chooses its deploy route. It installs the command for regular use where it can install and run it and reach the platform. It uses deploy_files within its caps for a first simple test or where the command cannot work. Past the caps, where it may not install or run the command, it uploads a zip with mint_upload_grant and names it as deploy's artifact. For any other line it takes the deploy skill's setup steps, never the npx line.`;
 var namedWithActs = (subcommand) => subcommand.acts ? `${subcommand.name} ${subcommand.acts.join("|")}` : subcommand.name;
 var shown = (option) => option.flag ? option.name : `${option.name} ${option.value}`;
 var listed = (names) => names.length < 3 ? names.join(" and ") : `${names.slice(0, -1).join(", ")}, and ${names[names.length - 1]}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turnzero",
-  "version": "0.31.1",
+  "version": "0.33.0-next.1",
   "type": "module",
   "description": "Deploy and run AI-built apps with Turn Zero Cloud hosting and backend services.",
   "license": "Apache-2.0",