@logic-joe/fleek 0.2.13 → 0.2.15

package/dist/fleek.mjs

@@ -4652,7 +4652,7 @@ var require_setup_session = __commonJS({
     exports.SETUP_SESSION_TTL_MINUTES = 30;
     exports.SETUP_SESSION_OPEN_MAX = 10;
     exports.SETUP_SESSION_CLAIM_LIMIT = 10;
-    exports.FLEEK_CLI_SETUP_VERSION_DEFAULT = "0.2.13";
+    exports.FLEEK_CLI_SETUP_VERSION_DEFAULT = "0.2.15";
     exports.FLEEK_CLI_PACKAGE = "@logic-joe/fleek";
     exports.FLEEK_CANONICAL_SERVER = "https://api.onfleek.app";
     exports.SETUP_CLIENT_APPS = ["claude-code", "codex", "orca", "cursor", "other"];
@@ -36131,6 +36131,7 @@ var require_agent_error_details = __commonJS({
       TICKET_TEXT_LIMIT: {},
       TICKET_TEXT_FORMAT: {},
       TICKET_TEXT_LOSSY_REPLACEMENT: {},
+      NOT_FOUND: { reason: oneOf3(["no_setup"]) },
       ACCESS_DENIED: { reason: oneOf3(["approval_denied", "field_right", "variant_admin"]), field: bindingField, changeRequest },
       // ENGINE-AUTHORITY: engine setup refusals (`workflows.engine.*`) - closed lists only
       CONFLICT: {
@@ -36149,7 +36150,7 @@ var require_agent_error_details = __commonJS({
       // PRIVACY-WORKCTX: additive `holderRef` (person ref of the holder, null without a handle key / release owner)
       ALREADY_CLAIMED: { holderLabel: string4, expiresAt: string4, holderRef: personRef },
       CLAIMED_BY_OTHER: { holderLabel: string4, expiresAt: string4, holderRef: personRef },
-      CLAIM_REQUIRED: { issueIds: list2 },
+      CLAIM_REQUIRED: { issueIds: list2, requiredPurpose: oneOf3(["work"]), providedPurpose: oneOf3(["review"]) },
       RENEW_LIMIT: { hardExpiresAt: string4 },
       NOT_READY: { readySelector: string4 },
       REVISION_CONFLICT: { currentRevision: integer },
@@ -37483,6 +37484,7 @@ var EN = {
   "errors.setupInstall": "The pinned CLI could not be installed permanently.",
   "init.agentMissing": "Claude Code was not found. Manual mode is available.",
   "init.agentUnknown": "Claude Code {version} is not yet verified for the analysis.",
+  "init.agentOutdated": "Claude Code {version} is older than {minimum} and likely fails the analysis. Run claude update first.",
   "init.confirmUnknownAgent": "Start it anyway with the same safety settings? (y/N)",
   "init.agentBoundary": "Claude receives the prepared files with MCP, hooks and customizations disabled. Your provider sign-in remains available; this does not isolate the whole computer.",
   "init.confirmAgent": "Start the read-only analysis now? (y/N)",
@@ -37490,7 +37492,14 @@ var EN = {
   "errors.initAgentTimeout": "The analysis timed out; the agent was stopped.",
   "errors.initAgentOutput": "The agent output exceeds the allowed size; nothing sent.",
   "errors.initAgentStart": "Could not start Claude Code directly. Use --agent manual --verbose.",
-  "errors.initAgentFailed": "Claude exited with code {code}. Shell aliases/functions are bypassed; update Claude or use --agent manual --verbose.",
+  "errors.initAgentFailed": "Claude exited with code {code} for an unknown reason; its output is not shown here. Rerun with --agent manual --verbose: Claude's own message is then in agent-output.json.tmp in the output directory.",
+  "errors.initAgentFailed.next": "fleek init --agent manual --verbose",
+  "errors.initAgentSignIn": "Claude is not signed in or its sign-in is no longer valid (code {code}). Sign in again, then rerun fleek init.",
+  "errors.initAgentSignIn.next": "claude auth login",
+  "errors.initAgentVersion": "Claude Code does not support the analysis start (code {code}); it is probably outdated. Update it, then rerun fleek init.",
+  "errors.initAgentVersion.next": "claude update",
+  "errors.initAgentRateLimit": "Claude reports a rate limit or overload (code {code}). Wait a moment, then rerun fleek init.",
+  "errors.initAgentNetwork": "Claude could not reach its service (code {code}). Check the network connection, then rerun fleek init.",
   "errors.initManualFallback": "Automatic analysis was not started. Continue with --agent manual --verbose.",
   "login.serviceVisit": "Open {url} on your own computer and enter code {code}",
   "login.serviceSetupConfirm": 'Confirm in the Fleek window where you generated the command ("Server asks to sign in"). Code: {code}',
@@ -37921,7 +37930,7 @@ var EN = {
   "init.detected": "Detected: {sources}",
   "init.detectedNone": "no verified design sources",
   "init.manualCommand": "In a separate terminal, with approved current Claude Code (keep every isolation flag):",
-  "init.manualCommandHint": "Copy it whole, with the outer parentheses. command claude bypasses shell aliases and functions; keep every isolation flag.",
+  "init.manualCommandHint": "Copy it whole, with the outer parentheses. command claude bypasses shell aliases and functions; keep every isolation flag. If Claude fails, its message is in agent-output.json.tmp in the output directory.",
   "init.manualPrompt": "Read FLEEK-INIT.md and fleek-input.json. Read only the staged files. Return only the agent-output.json JSON object on stdout, without Markdown; the launcher saves it. Do not write files, run commands, use MCP or access the network.",
   "init.manualBoundary": "You start the agent yourself: the file selection is only a recommendation, the agent may read more on your machine.",
   "init.outputTimeout": "{app}: no output file in time.",
@@ -38250,6 +38259,7 @@ var DE = {
   "errors.setupInstall": "Die festgelegte CLI-Version konnte nicht dauerhaft installiert werden.",
   "init.agentMissing": "Claude Code wurde nicht gefunden. Der manuelle Modus ist verfügbar.",
   "init.agentUnknown": "Claude Code {version} ist für die Analyse noch nicht geprüft.",
+  "init.agentOutdated": "Claude Code {version} ist älter als {minimum} und scheitert wahrscheinlich an der Analyse. Führe zuerst claude update aus.",
   "init.confirmUnknownAgent": "Trotzdem mit denselben Schutzeinstellungen starten? (j/N)",
   "init.agentBoundary": "Claude erhält die vorbereiteten Dateien; MCP, Hooks und Anpassungen sind deaktiviert. Deine Anbieteranmeldung bleibt verfügbar; der Rechner wird dabei nicht vollständig isoliert.",
   "init.confirmAgent": "Die Analyse jetzt nur lesend starten? (j/N)",
@@ -38257,7 +38267,14 @@ var DE = {
   "errors.initAgentTimeout": "Die Analyse hat die Frist überschritten; der Agent wurde gestoppt.",
   "errors.initAgentOutput": "Die Agentenausgabe überschreitet die erlaubte Größe; nichts gesendet.",
   "errors.initAgentStart": "Claude Code konnte nicht direkt gestartet werden. Nutze --agent manual --verbose.",
-  "errors.initAgentFailed": "Claude wurde mit Code {code} beendet. Shell-Aliase und Funktionen werden umgangen; aktualisiere Claude oder nutze --agent manual --verbose.",
+  "errors.initAgentFailed": "Claude wurde aus unbekanntem Grund mit Code {code} beendet; seine Ausgabe wird hier nicht angezeigt. Starte erneut mit --agent manual --verbose: Claudes eigene Meldung steht dann in agent-output.json.tmp im Ausgabeverzeichnis.",
+  "errors.initAgentFailed.next": "fleek init --agent manual --verbose",
+  "errors.initAgentSignIn": "Claude ist nicht angemeldet oder die Anmeldung ist nicht mehr gültig (Code {code}). Melde dich neu an und starte fleek init dann erneut.",
+  "errors.initAgentSignIn.next": "claude auth login",
+  "errors.initAgentVersion": "Claude Code unterstützt den Analysestart nicht (Code {code}); vermutlich ist es veraltet. Aktualisiere es und starte fleek init dann erneut.",
+  "errors.initAgentVersion.next": "claude update",
+  "errors.initAgentRateLimit": "Claude meldet ein Nutzungslimit oder eine Überlastung (Code {code}). Warte kurz und starte fleek init dann erneut.",
+  "errors.initAgentNetwork": "Claude konnte seinen Dienst nicht erreichen (Code {code}). Prüfe die Netzwerkverbindung und starte fleek init dann erneut.",
   "errors.initManualFallback": "Die automatische Analyse wurde nicht gestartet. Fahre mit --agent manual --verbose fort.",
   "login.serviceVisit": "Öffne {url} am eigenen Rechner und gib den Code {code} ein.",
   "login.serviceSetupConfirm": "Bestätige im Fleek-Fenster, in dem du den Befehl erzeugt hast (‚Server fragt Anmeldung an‘). Code: {code}",
@@ -38688,7 +38705,7 @@ var DE = {
   "init.detected": "Erkannt: {sources}",
   "init.detectedNone": "keine belegten Design-Quellen",
   "init.manualCommand": "In einem separaten Terminal mit freigegebenem aktuellem Claude Code (alle Isolationsflags beibehalten):",
-  "init.manualCommandHint": "Ganz kopieren, mit den äußeren Klammern. command claude umgeht Shell-Aliase und Funktionen; behalte alle Isolationsflags bei.",
+  "init.manualCommandHint": "Ganz kopieren, mit den äußeren Klammern. command claude umgeht Shell-Aliase und Funktionen; behalte alle Isolationsflags bei. Scheitert Claude, steht seine Meldung in agent-output.json.tmp im Ausgabeverzeichnis.",
   "init.manualPrompt": "Lies FLEEK-INIT.md und fleek-input.json. Lies nur die bereitgestellten Dateien. Gib nur das JSON-Objekt für agent-output.json auf stdout aus, ohne Markdown; der Startbefehl speichert es. Keine Dateien schreiben, keine Befehle, kein MCP und kein Netzzugriff.",
   "init.manualBoundary": "Du startest den Agenten selbst: Die Dateiauswahl ist nur eine Empfehlung, der Agent kann auf deinem Rechner mehr lesen.",
   "init.outputTimeout": "{app}: keine Ausgabedatei innerhalb der Frist.",
@@ -51146,7 +51163,7 @@ var KIT_CAPABILITIES = Object.freeze({
     checkout: { filePrefix: ".claude/", instructions: "CLAUDE.md", mcpFile: ".mcp.json", mcpWithType: true },
     globalE1: { path: ".claude/skills/fleek-work/SKILL.md" },
     verifiedWith: "Claude Code 2.1.303",
-    initIsolation: ["2.1.310"]
+    initIsolation: ["2.1.310", "2.1.319"]
   },
   // Orca terminals run Claude Code: same mechanism, Orca rendering (plan §4.4 "Orca as Claude").
   orca: {
@@ -51156,7 +51173,7 @@ var KIT_CAPABILITIES = Object.freeze({
     checkout: { filePrefix: ".claude/", instructions: "CLAUDE.md", mcpFile: ".mcp.json", mcpWithType: true },
     globalE1: { path: ".claude/skills/fleek-work/SKILL.md" },
     verifiedWith: "Claude Code 2.1.303 (inside Orca)",
-    initIsolation: ["2.1.310"]
+    initIsolation: ["2.1.310", "2.1.319"]
   },
   codex: {
     target: "codex",
@@ -51734,7 +51751,7 @@ var USER_SKILL_MARKER = "<!-- Generated by scripts/agent-guidance/generate.mjs f
 var USER_SKILLS = [
   {
     "name": "fleek-orca-coordinator",
-    "content": "---\nname: fleek-orca-coordinator\ndescription: \"Coordinate Fleek tickets in Orca: find claimable work, claim it for this machine, start a builder in its own worktree with the project kit, review with the other model, leave gates to people and deliver to review. Use when you coordinate Orca agents for a Fleek project.\"\nmetadata:\n  protocol: fleek-work-protocol/1.13\n---\n\n<!-- Generated by scripts/agent-guidance/generate.mjs from scripts/agent-guidance/protocol.json - do not edit by hand. -->\n\n# Fleek in Orca: coordinator recipe\n\nFleek holds the tickets and every human decision; Orca runs worktrees and agents. Follow the fleek-work skill for every Fleek call. Never change Orca's code or settings.\n\n## 1. Ready check\n- `fleek doctor` in the repo: Fleek MCP current for Claude Code, Codex and every Orca account, repo bound to its Fleek project. Otherwise ask the person to run the setup command from Fleek once per machine (Settings › Connections › Set up this computer: `fleek setup <code>`). Never sign in for them.\n\n## 2. Find work\n- fleek_find_work and fleek_my_work_inbox (claimable: agent-ready or assigned to your person; addressed work first); `fleek orca tasks` lists the project's open tickets. Take only status roles where agents work: intake_review, ready, analysis, design, implementation, review. Skip tickets another holder claims.\n- Read stage in fleek_get_work_context before starting a worker, then use this role table. Do not infer a role from the displayed status name or from the ticket title.\n\n| Status role | Work and delivery |\n| --- | --- |\n| intake_review | One triage agent: duplicates, criteria and readiness; no product code or PR. |\n| ready | Claim, then re-read the live stage and use its row. A claim is not permission to skip analysis or design. |\n| analysis / design | One agent: concept or design proposal with evidence; no product code or PR. |\n| implementation | Builder, other-model review, then deliver the work claim (sections 3-5). |\n| review | One reviewer with a review claim (`fleek orca start KEY --yes --agent OTHER-MODEL` takes it on the delivered branch in its own worktree): checklist, acceptance and evidence; record the verdict, then release that review claim. No builder, implementation, PR or complete_work outcome done loop. Findings go back to the existing implementation work or to the person. |\n| collecting / clarification / acceptance / customer gate | Start no builder; prepare a draft only if requested and wait for the responsible person or customer. Never decide their gate. |\n| done / cancelled | Start nothing. |\n\n- Only implementation uses sections 3-5. `fleek orca tasks` is an overview; `fleek orca pick` works only in a person's terminal and offers only server candidates without an existing work claim. Re-read the live context after claiming: availability is not a status-role decision.\n\n## 3. Claim, worktree, builder\n- `fleek orca start KEY --yes` (the core of `fleek start` for coordinators: Orca required; a new or restarted agent stays in the background, one already running comes to the front) takes or reuses the claim for this machine, creates the Orca worktree named after the key from the project's base branch with the Fleek ticket as reference and starts the agent with a first prompt naming key and claim. You run without a terminal: only `--yes` replaces the person's confirmation, without it the command refuses with CONFIRMATION_REQUIRED. Use it only for tickets your person lets you start; the web link and a person's own terminal keep asking. With the Fleek start command as Orca's agent command (`fleek setup` names it), the agent loads the project's kit. Your own claim is reused, no error. Another holder's claim or NOT_READY: pick another ticket.\n- By hand: fleek_claim_issue (purpose work, runLabel \"orca\" plus the worktree name), then `orca worktree create --name eng-123-slug --reference TICKET-URL --agent claude` from the base branch of fleek_get_project_brief.\n- The builder's task is a pointer: key, claimId, worktree, branch, role builder. Never paste ticket text, criteria or sign-in data; the agent reads them live from Fleek.\n- Models only from providers conventions.aiProviders allows (fleek_get_work_context); a customer's code never goes to another provider.\n- Card: `orca worktree set --worktree id:WORKTREE-ID --workspace-status in-progress`.\n\n## 4. Review by the other model\n- After the builder's worker_done with a pushed commit: start a reviewer with the other model (Claude and Codex swap; only one provider allowed: a fresh session of it) in the same worktree, role reviewer. It claims purpose review, checks criteria and checklist and records its verdict at the ticket.\n- Verdict not ready or a criterion not_met: builder round 2 in the same worktree, then review again. After two rounds ask the person.\n\n## 5. Deliver\n- Clean review: load the guidance (fleek_get_work_context), then fleek_complete_work on the work claim, outcome done, with SHA, branch, PR, checks and result, acceptance per criterion and nextStep. The ticket moves to the project's review state, never Done; check moved and toStateId.\n- A coordination or review claim that only records a status writes fleek_post_progress, not a result. One completion = one fleek_complete_work; no extra summary or analysis comment. Put the recommendation in nextStep; do not add a note about your own draft or publication request.\n- Parts open: outcome partial. Blocked: fleek_release_issue outcome not_doable. Interrupted: outcome paused. A failed dispatch is never done.\n- Card in-review with the existing result; no extra ticket comment.\n\n## 6. People decide\n- Questions only a person can answer go to the ticket (fleek_ask_question); the worker waits, the card gets `--unread`. Gates, acceptance, customer text and Done are decided by a person in Fleek, by an agent only where the project rule allows it and the person approved or gave a standing mandate. Never orca gate-resolve or a terminal yes on their behalf.\n\n## 7. Keep claims alive\n- Renew by expiresAt (about every 20 minutes) while a worker runs or waits; an Orca heartbeat is no renewal. The claim belongs to the machine, so a switched account or a usage-limit pause keeps it: renew and resume. Nobody can continue before expiry: release paused.\n- After a crash read your live claims (fleek_my_work_inbox) and `orca worktree list`, then continue on the same claim (`fleek orca start KEY --yes` restarts an ended agent) or release it. Never claim or complete twice.\n\n## 8. Limits\n- One builder per ticket, one ticket per worktree. Parallel tickets: as many as the person allows, default 2, each with its reviewer; queue the rest. QUOTA_EXCEEDED: the machine's claims are used up - finish or release one first.\n- No Orca code changes, forks or pull requests on Orca. Git effects only as far as the project brief allows.\n"
+    "content": "---\nname: fleek-orca-coordinator\ndescription: \"Coordinate Fleek tickets in Orca: find claimable work, claim it for this machine, start a builder in its own worktree with the project kit, review with the other model, leave gates to people and deliver to review. Use when you coordinate Orca agents for a Fleek project.\"\nmetadata:\n  protocol: fleek-work-protocol/1.13\n---\n\n<!-- Generated by scripts/agent-guidance/generate.mjs from scripts/agent-guidance/protocol.json - do not edit by hand. -->\n\n# Fleek in Orca: coordinator recipe\n\nFleek holds the tickets and every human decision; Orca runs worktrees and agents. Follow the fleek-work skill for every Fleek call. Never change Orca's code or settings.\n\n## 1. Ready check\n- `fleek doctor` in the repo: Fleek MCP current for Claude Code, Codex and every Orca account, repo bound to its Fleek project. Otherwise ask the person to run the setup command from Fleek once per machine (Settings › Connections › Set up this computer: `fleek setup <code>`). Never sign in for them.\n\n## 2. Find work\n- fleek_find_work and fleek_my_work_inbox (claimable: agent-ready or assigned to your person; addressed work first); `fleek orca tasks` lists the project's open tickets. Take only status roles where agents work: intake_review, ready, analysis, design, implementation, review. Skip tickets another holder claims.\n- Read stage in fleek_get_work_context before starting a worker, then use this role table. Do not infer a role from the displayed status name or from the ticket title.\n\n| Status role | Work and delivery |\n| --- | --- |\n| intake_review | One triage agent: duplicates, criteria and readiness; no product code or PR. |\n| ready | Claim, then re-read the live stage and use its row. A claim is not permission to skip analysis or design. |\n| analysis / design | One agent: concept or design proposal with evidence; no product code or PR. |\n| implementation | Builder, other-model review, then deliver the work claim (sections 3-5). |\n| review | One reviewer with a review claim (`fleek orca start KEY --yes --agent OTHER-MODEL` takes it on the delivered branch in its own worktree): checklist, acceptance and evidence; record the verdict, then release that review claim. No builder, implementation, PR or complete_work outcome done loop. Findings go back to the existing implementation work or to the person. |\n| collecting / clarification / acceptance / customer gate | Start no builder; prepare a draft only if requested and wait for the responsible person or customer. Never decide their gate. |\n| done / cancelled | Start nothing. |\n\n- Only implementation uses sections 3-5. `fleek orca tasks` is an overview; `fleek orca pick` works only in a person's terminal and offers only server candidates without an existing work claim. Re-read the live context after claiming: availability is not a status-role decision.\n\n## 3. Claim, worktree, builder\n- `fleek orca start KEY --yes` (the core of `fleek start` for coordinators: Orca required; a new or restarted agent stays in the background, one already running comes to the front) takes or reuses the claim for this machine, creates the Orca worktree named after the key from the project's base branch with the Fleek ticket as reference and starts the agent with a first prompt naming key and claim. You run without a terminal: only `--yes` replaces the person's confirmation, without it the command refuses with CONFIRMATION_REQUIRED. Use it only for tickets your person lets you start; the web link and a person's own terminal keep asking. With the Fleek start command as Orca's agent command (`fleek setup` names it), the agent loads the project's kit. Your own claim is reused, no error. Another holder's claim or NOT_READY: pick another ticket.\n- By hand: fleek_claim_issue (purpose work, runLabel \"orca\" plus the worktree name), then `orca worktree create --name eng-123-slug --reference TICKET-URL --agent claude` from the base branch of fleek_get_project_brief.\n- The builder's task is a pointer: key, claimId, worktree, branch, role builder. Never paste ticket text, criteria or sign-in data; the agent reads them live from Fleek.\n- Models only from providers conventions.aiProviders allows (fleek_get_work_context); a customer's code never goes to another provider.\n- Card: `orca worktree set --worktree id:WORKTREE-ID --workspace-status in-progress`.\n\n## 4. Review by the other model\n- After the builder's worker_done verify its report in two reads before starting a reviewer: the fetched feature branch head equals the reported SHA and the worktree has no uncommitted changes; the test note is on the ticket when the project kit asks for one. A mismatch goes back to the builder, not to the reviewer.\n- Then start a reviewer with the other model (Claude and Codex swap; only one provider allowed: a fresh session of it) in the same worktree, role reviewer. It claims purpose review, checks criteria and checklist and records its verdict at the ticket.\n- Check the review's shape (fleek-work, In Orca, reviewer): verdict on the first line, blockers each with a reproduction, anchors only inside the reviewed range, each finding read or measured, questions for a person at the ticket. A review that misses it goes back to the reviewer once with the exact points.\n- Verdict not ready or a criterion not_met: builder round 2 in the same worktree, then review again. After two rounds ask the person.\n\n## 5. Deliver\n- Clean review: load the guidance (fleek_get_work_context), then fleek_complete_work on the work claim, outcome done, with SHA, branch, PR, checks and result, acceptance per criterion and nextStep. The ticket moves to the project's review state, never Done; check moved and toStateId.\n- A coordination or review claim that only records a status writes fleek_post_progress, not a result. One completion = one fleek_complete_work; no extra summary or analysis comment. Put the recommendation in nextStep; do not add a note about your own draft or publication request.\n- Parts open: outcome partial. Blocked: fleek_release_issue outcome not_doable. Interrupted: outcome paused. A failed dispatch is never done.\n- Card in-review with the existing result; no extra ticket comment.\n\n## 6. People decide\n- Questions only a person can answer go to the ticket (fleek_ask_question); the worker waits, the card gets `--unread`. Gates, acceptance, customer text and Done are decided by a person in Fleek, by an agent only where the project rule allows it and the person approved or gave a standing mandate. Never orca gate-resolve or a terminal yes on their behalf.\n- Answer an orca ask only when a rule or a decision recorded at the ticket settles it, and cite it. Anything else a person decides goes back as \"ask at the ticket\": the asking agent calls fleek_ask_question with the deciding person as addressee and waits. Your own person's answer in chat or terminal is recorded verbatim as an internal ticket comment (\"Answer NAME in chat, DATE: ...\"); pass it on only together with that comment, never a chat answer alone. The comment only records the factual answer of your own person; it decides no gate, customer acceptance or publication and grants or widens no mandate or agent_git_* right - those stay decisions in Fleek.\n\n## 7. Keep claims alive\n- Renew by expiresAt (about every 20 minutes) while a worker runs or waits; an Orca heartbeat is no renewal. The claim belongs to the machine, so a switched account or a usage-limit pause keeps it: renew and resume. Nobody can continue before expiry: release paused.\n- After a crash read your live claims (fleek_my_work_inbox) and `orca worktree list`, then continue on the same claim (`fleek orca start KEY --yes` restarts an ended agent) or release it. Never claim or complete twice.\n\n## 8. Limits\n- One builder per ticket, one ticket per worktree. Parallel tickets: as many as the person allows, default 2, each with its reviewer; queue the rest. QUOTA_EXCEEDED: the machine's claims are used up - finish or release one first.\n- No Orca code changes, forks or pull requests on Orca. Git effects only as far as the project brief allows.\n"
   }
 ];
 
@@ -51990,6 +52007,19 @@ function initAgentEnv(env) {
   }
   return result;
 }
+var CLASS_LINES = 5;
+var FAILURE_CLASSES = [
+  // 401 only with an HTTP/auth context, never a bare number (a file diagnosis "line 401" is not a sign-in failure)
+  ["signIn", /Not logged in|Failed to authenticate|\bauthentication[_ ](?:error|failed)\b|\b401 Unauthorized\b|\b(?:HTTP|status(?: code)?:?)\s*401\b|\b(?:OAuth )?token (?:has been |was )?(?:revoked|expired)\b|Invalid API key/i],
+  ["version", /\b(?:unknown|unrecognized) (?:option|argument|flag)\b|\bclaude update\b|\b(?:requires|needs) (?:a )?newer version\b|\bversion\b.*\b(?:not supported|unsupported|outdated)\b/i],
+  ["rateLimit", /\brate[ _-]?limit|\boverloaded(?:_error)?\b|\busage limit\b|\b429 Too Many Requests\b|\b(?:HTTP|status(?: code)?:?)\s*(?:429|529)\b/i],
+  ["network", /\b(?:ECONNREFUSED|ECONNRESET|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|ENETUNREACH)\b|\bnetwork error\b|\bsocket hang up\b|\bfetch failed\b|\bunable to connect\b/i]
+];
+function classifyInitFailure(result) {
+  const tail = `${result.stderr ?? ""}
+${result.stdout}`.split(/\r?\n/).filter((line) => line.trim()).slice(-CLASS_LINES).join("\n");
+  return FAILURE_CLASSES.find(([, pattern]) => pattern.test(tail))?.[0] ?? "unknown";
+}
 var runInitProcess = (program, args, options) => new Promise((resolve9, reject) => {
   if (options.signal?.aborted) {
     reject(new CliError("errors.aborted", EXIT.failed, {}, "ABORTED"));
@@ -52000,9 +52030,10 @@ var runInitProcess = (program, args, options) => new Promise((resolve9, reject)
     env: options.env,
     shell: false,
     detached: process.platform !== "win32",
-    stdio: ["ignore", "pipe", "ignore"]
+    stdio: ["ignore", "pipe", "pipe"]
   });
   const chunks = [];
+  let errorTail = Buffer.alloc(0);
   let bytes = 0, failure2;
   const kill = (signal) => {
     try {
@@ -52027,6 +52058,10 @@ var runInitProcess = (program, args, options) => new Promise((resolve9, reject)
     if (bytes > options.maxBytes) stop(new CliError("errors.initAgentOutput", EXIT.failed, {}, "AGENT_OUTPUT_LIMIT"));
     else chunks.push(chunk);
   });
+  child.stderr.on("data", (chunk) => {
+    errorTail = Buffer.concat([errorTail, chunk]);
+    if (errorTail.length > options.maxBytes) errorTail = errorTail.subarray(errorTail.length - options.maxBytes);
+  });
   const cleanup = () => {
     clearTimeout(timer);
     if (hard) clearTimeout(hard);
@@ -52039,7 +52074,7 @@ var runInitProcess = (program, args, options) => new Promise((resolve9, reject)
   child.once("close", (code) => {
     cleanup();
     if (failure2) reject(failure2);
-    else resolve9({ code: code ?? 1, stdout: Buffer.concat(chunks).toString("utf8") });
+    else resolve9({ code: code ?? 1, stdout: Buffer.concat(chunks).toString("utf8"), stderr: errorTail.toString("utf8") });
   });
 });
 
@@ -57327,6 +57362,19 @@ async function ask(ctx, lines) {
     rl.close();
   }
 }
+var MIN_INIT_CLAUDE = "2.1.310";
+function olderThan(version2, minimum) {
+  const a = version2.split(".").map(Number), b = minimum.split(".").map(Number);
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] < b[i];
+  return false;
+}
+var AGENT_FAILURE_KEYS = {
+  signIn: "errors.initAgentSignIn",
+  version: "errors.initAgentVersion",
+  rateLimit: "errors.initAgentRateLimit",
+  network: "errors.initAgentNetwork",
+  unknown: "errors.initAgentFailed"
+};
 async function startAgent(ctx, values, stagingDir, outputFile, timeoutMs, app) {
   if (values.agent !== "claude") return false;
   const program = await resolveExecutable("claude", ctx.env);
@@ -57339,7 +57387,8 @@ async function startAgent(ctx, values, stagingDir, outputFile, timeoutMs, app) {
   const versionResult = await run2(program, ["--version"], { cwd: stagingDir, env, signal: ctx.deps.signal, timeoutMs: 1e4, maxBytes: 1024 });
   const version2 = versionResult.code === 0 ? versionResult.stdout.trim().match(/^(\d+\.\d+\.\d+) \(Claude Code\)$/)?.[1] : void 0;
   if (!version2 || !KIT_CAPABILITIES.claude.initIsolation?.includes(version2)) {
-    if (!await ask(ctx, [ctx.t("init.agentUnknown", { version: version2 ?? "?" }), ctx.t("init.confirmUnknownAgent")])) return false;
+    const outdated = !!version2 && olderThan(version2, MIN_INIT_CLAUDE);
+    if (!await ask(ctx, [ctx.t(outdated ? "init.agentOutdated" : "init.agentUnknown", { version: version2 ?? "?", minimum: MIN_INIT_CLAUDE }), ctx.t("init.confirmUnknownAgent")])) return false;
   }
   if (!await ask(ctx, [ctx.t("init.agentBoundary"), ctx.t("init.confirmAgent")])) return false;
   if (values.verbose && !ctx.json) ctx.info(ctx.out.style.cmd(neutralizeLine(program)));
@@ -57352,7 +57401,10 @@ async function startAgent(ctx, values, stagingDir, outputFile, timeoutMs, app) {
       timeoutMs: Math.max(1, timeoutMs),
       maxBytes: import_validation3.PROJECT_INIT_LIMITS.summaryBytes
     }));
-    if (result.code !== 0) throw new CliError("errors.initAgentFailed", EXIT.failed, { code: result.code }, "AGENT_FAILED");
+    if (result.code !== 0) {
+      const diagnosis = classifyInitFailure(result);
+      throw new CliError(AGENT_FAILURE_KEYS[diagnosis], EXIT.failed, { code: result.code, diagnosis }, "AGENT_FAILED");
+    }
     const temporary = `${outputFile}.tmp`;
     await writeFile6(temporary, result.stdout, { mode: 384, flag: "wx" });
     await rename4(temporary, outputFile);
@@ -57559,8 +57611,12 @@ async function initCommand(ctx, values) {
         failed2++;
         if (error instanceof CliError && error.code === "UNKNOWN_OUTCOME") unknownOutcome = true;
         if (error instanceof CliError && error.exitCode === EXIT.needsLogin) throw error;
-        emit(ctx, { event: "error", app: app.key, code: errorCode(error) });
-        if (!ctx.json) ctx.out.error(s.fail(error instanceof CliError && /^AGENT_/.test(error.code ?? "") ? ctx.t(error.key, error.params) : ctx.t("init.appFailed", { app: app.key, code: errorCode(error) })));
+        const agentError = error instanceof CliError && /^AGENT_/.test(error.code ?? "") ? error : null;
+        emit(ctx, { event: "error", app: app.key, code: errorCode(error), ...typeof agentError?.params.diagnosis === "string" ? { diagnosis: agentError.params.diagnosis } : {} });
+        if (!ctx.json) {
+          ctx.out.error(s.fail(agentError ? ctx.t(agentError.key, agentError.params) : ctx.t("init.appFailed", { app: app.key, code: errorCode(error) })));
+          if (agentError && `${agentError.key}.next` in EN) ctx.out.error(`  ${ctx.t("next.step", { command: s.cmd(ctx.t(`${agentError.key}.next`)) })}`);
+        }
       }
     }
     if (values.keep && !unknownOutcome) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logic-joe/fleek",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "fleek - command line client for the Fleek agent hub (MCP over OAuth, OS keychain, signed role/project kits)",
   "license": "Apache-2.0",
   "type": "module",