@zaip-ai/cli 2.2.0 → 3.0.0

package/templates/.agents/dashboard/apps/frontend/src/dashboard-localization.test.ts

@@ -1,53 +1,47 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { describe, expect, it } from "vitest";
 import { buildHelpDocuments, pricingCopy } from "./dashboard-localization.js";
 
-describe("dashboard localization", () => {
-  it("uses localized English content for the README and framework guides", () => {
-    const documents = buildHelpDocuments("en-US", "# ZAIP-AIOS\n\nConteúdo em português.", {
-      "../../../../zaip-aios/guides/01-primeiros-passos.md":
-        "# Primeiros passos\n\nLeia a configuração.",
-      "../../../../zaip-aios/guides/10-seguranca.md": "# Segurança\n\nProteja o projeto.",
-    });
+const root = resolve(import.meta.dirname, "../../../../..");
+const guidesRoot = resolve(root, ".agents/zaip-aios/guides");
+const sources = Object.fromEntries(
+  readdirSync(guidesRoot)
+    .filter((file) => file.endsWith(".md"))
+    .map((file) => [file, readFileSync(resolve(guidesRoot, file), "utf8")]),
+);
 
-    expect(documents.map((document) => document.title)).toEqual([
-      "README · ZAIP-AIOS",
-      "Getting started",
-      "Security with danger-full-access",
-    ]);
-    expect(documents[0]?.content).toContain("Git-native operating system");
-    expect(documents[1]?.content).toContain("Read `.agents/config/project.yaml`");
-    expect(documents[2]?.content).toContain("Trust model");
-    expect(documents.map((document) => document.content).join("\n")).not.toContain(
-      "Conteúdo em português",
-    );
+describe("dashboard localization", () => {
+  it("uses the complete canonical English README instead of a fixed summary", () => {
+    const documents = buildHelpDocuments("en-US", "# README PT", sources);
+    expect(documents[0]?.content).toBe(readFileSync(resolve(root, "README-ENG.md"), "utf8"));
+    expect(documents[0]?.content).toContain("### v3 autonomy presets");
   });
 
-  it("has English content for every guide exposed by the popup", () => {
-    const guideFiles = [
-      "01-primeiros-passos.md",
-      "02-requirements.md",
-      "03-tasks.md",
-      "04-specs.md",
-      "05-prds.md",
-      "06-execucao.md",
-      "07-revisao-e-validacao.md",
-      "08-contexto-e-tokens.md",
-      "09-agentes-e-squads.md",
-      "10-seguranca.md",
-      "11-observabilidade-e-custos.md",
-      "12-instalacao-e-upgrade.md",
-      "13-boas-praticas.md",
-      "14-troubleshooting.md",
-      "15-tools-e-codex.md",
-    ];
-    const sources = Object.fromEntries(
-      guideFiles.map((file) => [`../../../../zaip-aios/guides/${file}`, `# PT ${file}`]),
-    );
-
-    const documents = buildHelpDocuments("en-US", "# README PT", sources);
+  it.each([
+    "pt-BR",
+    "en-US",
+  ] as const)("preserves every actual guide and its current contract in %s", (locale) => {
+    const documents = buildHelpDocuments(locale, "# README PT", sources);
+    expect(Object.keys(sources)).toHaveLength(28);
+    expect(documents).toHaveLength(29);
+    for (const [file, source] of Object.entries(sources)) {
+      const document = documents.find((entry) => entry.id === file);
+      expect(document?.content.endsWith(source)).toBe(true);
+      if (locale === "en-US") {
+        expect(document?.content).toContain("Language: Portuguese (pt-BR)");
+        expect(document?.content).toContain("an English translation is not available");
+      } else expect(document?.content).toBe(source);
+    }
+  });
 
-    expect(documents).toHaveLength(guideFiles.length + 1);
-    expect(documents.slice(1).every((document) => !document.content.startsWith("# PT"))).toBe(true);
+  it("propagates a changed guide instead of masking it with a fixed translation", () => {
+    const id = "../../../../zaip-aios/guides/01-primeiros-passos.md";
+    const changed = "# Primeiros passos\n\nContrato alterado: preservar o diário da Task.";
+    const documents = buildHelpDocuments("en-US", "# README", { [id]: changed });
+    expect(documents[1]).toMatchObject({ id, title: "Primeiros passos" });
+    expect(documents[1]?.content.endsWith(changed)).toBe(true);
+    expect(documents[1]?.content).not.toContain(".agents/rules/zaip/core.md");
   });
 
   it("preserves the source documentation in Portuguese", () => {

package/templates/.agents/dashboard/apps/frontend/src/dashboard-localization.ts

@@ -1,3 +1,5 @@
+import englishReadme from "../../../../../README-ENG.md?raw";
+
 export type DashboardLocale = "pt-BR" | "en-US";
 
 export interface HelpDocument {
@@ -6,256 +8,6 @@ export interface HelpDocument {
   content: string;
 }
 
-const englishReadme = `# ZAIP-AIOS
-
-ZAIP-AIOS is a Git-native operating system for autonomous software engineering with Codex. It turns a request into structured, traceable work by defining requirements, preparing a plan, coordinating execution, running tests and reviews, and only considering a result complete when verifiable evidence exists.
-
-## From conversation to executable work
-
-Work can start with a **Task**, a **PRD** (Product Requirements Document), or a **SPEC**. A PRD describes the problem, expected outcome, product context, and acceptance criteria. A SPEC turns that intent into a technical scope, solution, acceptance criteria, Changes, and a DAG of executable Tasks.
-
-ZAIP-AIOS does not require a VPS, a competing runtime, or mandatory API model routing. Codex remains the execution host while ZAIP-AIOS adds method, operational memory, governance, traceability, and observability to the repository.
-
-## Six-stage method
-
-1. **Definition** — capture PRDs, Requirements, and acceptance criteria.
-2. **Planning** — prepare SPECs, Changes, dependencies, and rollback.
-3. **Ready to execute** — confirm that scoped work is actionable.
-4. **Execution** — implement Tasks and record Runs.
-5. **Verification** — run tests, review the diff, and collect evidence.
-6. **Completion** — close the lifecycle only after acceptance is satisfied.
-
-Small, independent frontend changes may use a task-first lite flow and begin directly in execution without definition or planning evidence.
-
-## Operational dashboard
-
-The dashboard provides three complementary views:
-
-- **Operations** follows PRDs, SPECs, Tasks, Changes, Executions, Runs, and conversations.
-- **Cost Monitor** aggregates time, tokens, models, providers, and estimated cost.
-- **Traceability** connects each delivered result to its requirements, changes, runs, tests, and evidence.
-
-## Engineering principles
-
-- Start from an observable outcome and explicit acceptance criteria.
-- Keep domain logic independent from infrastructure and vendors.
-- Prefer small, reversible, traceable changes.
-- Load only the context required for the active work.
-- Preserve unrelated changes in a dirty worktree.
-- Treat tests, evidence, observability, and rollback as part of delivery.
-- Never infer external authorization from technical capability.
-
-## Installation and development
-
-Use the repository setup command documented for the current release, then run the doctor and integrity checks. The framework source lives in this repository; generated public and consumer artifacts are validated for release parity.
-
-The main local quality gates cover type checking, focused tests, architecture boundaries, generated text, framework integrity, and release parity. Use focused checks while implementing and the applicable final gates before completion.
-
-## Repository structure
-
-- \`.agents/config/\` — project-owned configuration.
-- \`.agents/rules/\` — operational and architectural rules.
-- \`.agents/requirements/\` — durable Requirements and acceptance criteria.
-- \`.agents/skills/\` — reusable workflows.
-- \`.agents/records/\` — lifecycle records addressed by explicit ID.
-- \`.agents/records/lifecycle/\` — canonical lifecycle manifests, chunks, indexes, and summaries.
-- \`.agents/dashboard/\` — dashboard applications and modules.
-- \`.agents/runtime/\` — runtime and CLI distributable.
-
-Read runtime projections for discovery. Open lifecycle records only when you already have their ID.`;
-
-const englishGuides: Record<string, string> = {
-  "01-primeiros-passos.md": `# Getting started
-
-1. Read \`.agents/config/project.yaml\` and \`.agents/rules/zaip/core.md\`.
-2. Consult \`.agents/records/lifecycle/\` to discover the current state.
-3. Classify the work as a Task, SPEC, or PRD.
-4. Load only the applicable Rules, Requirements, and skills.
-5. Define verifiable acceptance before editing.
-6. Execute, test, and record evidence in the active lifecycle.
-
-Do not scan \`.agents/records/\`; open a record only when you have its ID.`,
-  "02-requirements.md": `# Requirements
-
-Use a Requirement for a durable, testable obligation.
-
-1. Describe the outcome and boundary, not the preferred implementation.
-2. Create observable acceptance criteria.
-3. Record risks, dependencies, and negative cases.
-4. Connect every criterion to a test or evidence.
-5. Version changes without erasing the previous intent.
-6. Promote only after consistency and traceability are validated.
-
-A good criterion answers unambiguously: did it pass or fail?`,
-  "03-tasks.md": `# Tasks
-
-Use a Task for a small, independent delivery with a clear result.
-
-1. State the objective, scope, and out-of-scope items.
-2. Link applicable Requirements.
-3. List likely files or components without freezing the solution.
-4. Define checks proportional to risk.
-5. Execute in the associated Run and attach evidence.
-6. Close only when acceptance is satisfied or a blocker is proven.`,
-  "04-specs.md": `# SPECs
-
-Use a SPEC when delivery requires multiple Tasks or dependency ordering.
-
-1. Turn the desired result into verifiable capabilities.
-2. Resolve the project stack from \`stack.id\` and \`stack.overrides\`.
-3. Record the stack profile, overrides, concise description, exact versions, and workspace-verifiable sources.
-4. Split delivery into small Tasks with their own acceptance.
-5. Model dependencies as a DAG and avoid artificial sequences.
-6. Identify critical paths, risks, and rollback.
-7. Map every Requirement to Tasks and evidence.
-8. Validate the SPEC before execution and block missing or inconsistent stack data.
-
-A SPEC plans delivery; it does not authorize external changes by itself.`,
-  "05-prds.md": `# PRDs
-
-Use a PRD for a product initiative with multiple capabilities or SPECs.
-
-1. Record the problem, audience, outcome, and metrics.
-2. Define scope, constraints, and non-goals.
-3. Keep the PRD independent of language, framework, database, infrastructure, and vendor.
-4. Specify functional and non-functional requirements.
-5. Convert capabilities into independent SPECs where the technical stack is resolved.
-6. Cover risks, rollout, observability, and rollback.
-7. Build the DAG and confirm that every acceptance criterion has planned evidence.`,
-  "06-execucao.md": `# Execution
-
-1. Confirm the lifecycle ID and governing acceptance criteria.
-2. Inspect the diff and preserve unrelated changes.
-3. Implement the smallest coherent increment.
-4. Run focused checks after each increment.
-5. Record consequential decisions, evidence, and deviations.
-6. Run final gates and document rollback.
-
-Do not mark work complete because effort was spent; complete it because the outcome is verifiable.`,
-  "07-revisao-e-validacao.md": `# Review and validation
-
-1. Review Requirements and acceptance criteria.
-2. Examine the diff, architecture boundaries, and error paths.
-3. Run focused tests, then all applicable gates.
-4. Verify security, compatibility, documentation, and rollback.
-5. Rank findings by impact and cite concrete evidence.
-6. Record the result without changing the implementation during a read-only review.`,
-  "08-contexto-e-tokens.md": `# Context and tokens
-
-1. Start with \`project.yaml\`, \`core.md\`, and runtime projections.
-2. Load only the triggered Rule, Requirement, or skill.
-3. Prefer indexes, summaries, and targeted search over full files.
-4. Open records only by a known lifecycle ID.
-5. Summarize stable facts and preserve literal text only when normative.
-6. Remove superseded results and non-actionable detail from context.
-
-For tools, read \`catalog.yaml\`, choose an ID, and open only its manifest.`,
-  "09-agentes-e-squads.md": `# Agents and squads
-
-1. Delegate only concrete, independent subtasks.
-2. Give each agent an objective, boundaries, inputs, and output format.
-3. Avoid two agents editing the same files.
-4. Centralize architecture decisions and integration in the responsible agent.
-5. Require evidence, not only completion claims.
-6. Use parallelism only when it shortens the critical path without increasing conflict.`,
-  "10-seguranca.md": `# Security with danger-full-access
-
-The security profile treats unrestricted filesystem access as a technical capability, never as blanket authorization. User intent, repository scope, lifecycle write scopes, and explicit approval remain the governing boundaries.
-
-## Trust model
-
-The user controls global opt-in and trusted projects. Repository instructions may narrow authority but cannot silently expand it. Missing or ambiguous authorization fails closed for destructive, external, credential-related, or irreversible operations.
-
-## Security layers
-
-1. **Global opt-in and trusted project** — unrestricted execution is enabled only by explicit user configuration in a trusted workspace.
-2. **No-prompt is not authorization** — suppressing approval prompts does not grant new scope.
-3. **Fail-closed hooks** — pre-tool controls reject operations that cannot be classified safely.
-4. **Filesystem boundary** — writes remain inside authorized workspace roots and lifecycle scopes.
-5. **Secrets protection** — credentials, tokens, environment files, and private keys are not exposed or committed.
-6. **Inline execution controls** — evasive shell composition and hidden payload execution are blocked.
-7. **Allowlisted egress** — external access is limited to required, trusted destinations.
-8. **Destructive operations** — recursive deletion, destructive Git commands, and irreversible mutations require explicit authority.
-9. **Codex forbidden rules** — known dangerous command patterns are denied before execution.
-10. **Bounded GitHub deployment** — setup never implies push, and deployment is limited to the requested repository and branch.
-11. **Apps, MCPs, and external tools** — integrations follow least privilege, read-only defaults, and explicit activation.
-12. **Lifecycle and traceability** — Tasks, Changes, Executions, Runs, write scopes, tests, and evidence make mutations auditable.
-13. **Autonomous runtime opt-in** — autonomous execution requires explicit project configuration and isolated worktrees.
-14. **Integrity and regression tests** — managed files, adapters, configuration, and security rules are validated continuously.
-
-## Residual limits
-
-No policy can eliminate risk from compromised dependencies, trusted binaries, operating-system vulnerabilities, or a user intentionally authorizing a dangerous operation. Least privilege, backups, reviewable diffs, isolated credentials, and reversible rollout remain necessary.
-
-## Safe operation
-
-- Inspect the target and resolved path before recursive file operations.
-- Keep credentials outside tracked files.
-- Prefer focused, reversible commands.
-- Review diffs before commit or deployment.
-- Run doctor, integrity, and security checks after configuration changes.
-- Stop when required authority or a safe rollback path is missing.
-
-## Rollout and rollback
-
-Roll out security changes in stages, validate on representative repositories, and preserve the previous known-good configuration. Rollback means restoring the prior managed policy, rebuilding adapters, rerunning integrity checks, and confirming that the workspace remains within its intended trust boundary.`,
-  "11-observabilidade-e-custos.md": `# Observability and costs
-
-1. Select the Run by ID.
-2. Check duration, tokens, cost, retries, and rework.
-3. Compare planned acceptance with produced evidence.
-4. Identify slow gates, excessive context, and repeated calls.
-5. Aggregate trends without exposing sensitive prompts or secrets.
-6. Turn recurring findings into a Rule, Requirement, or skill improvement.`,
-  "12-instalacao-e-upgrade.md": `# Installation and upgrade
-
-1. Check the current version and whether local changes are clean or intentionally preserved.
-2. Run doctor and integrity checks before changing anything.
-3. Run a dry-run of installation, migration, or upgrade.
-4. Review managed, public, and preserved files.
-5. Apply the change, validate adapters, and run gates.
-6. Test rollback and confirm the final version.
-
-\`framework.lock.yaml\` is relevant to this flow; do not load it during ordinary work.`,
-  "13-boas-praticas.md": `# Best practices
-
-- Start from the outcome and acceptance criteria, not the tool.
-- Keep the domain independent from infrastructure.
-- Make changes small, reversible, and traceable.
-- Validate early with deterministic, focused tests.
-- Prefer explicit configuration over hidden conventions.
-- Load context on demand and preserve the token budget.
-- Treat documentation, observability, and rollback as part of delivery.`,
-  "14-troubleshooting.md": `# Troubleshooting
-
-1. Reproduce the problem with the smallest possible command.
-2. Read the complete message and identify the first causal error.
-3. Run doctor, focused validators, and \`git diff --check\`.
-4. Check versions, paths, encoding, variables, and managed files.
-5. Compare against runtime projections without scanning records.
-6. Fix the cause, repeat the reproduction, and then run the full applicable gates.
-
-For installation or integrity problems, consult \`framework.lock.yaml\`.`,
-  "15-tools-e-codex.md": `# Tools and Codex setup
-
-1. Ask the agent to list or activate a tool; it uses the tool-setup skill.
-2. The skill reads only the applicable catalog and manifest.
-3. A trusted MCP is registered disabled and validated before activation.
-4. An API without a trusted MCP uses the API-to-MCP workflow to generate a secure adapter.
-5. Secrets are never pasted into chat; names belong in \`.agents/.env.example\` and values in ignored local storage.
-6. Configuration changes must be reversible and preserve existing preferences.
-
-Enable public, read-only, unauthenticated integrations by default, such as official documentation. Browser automation must be an explicit development-profile choice because it starts processes and expands the operational surface.
-
-## Local MCP generated from an API
-
-Model an \`adapter.yaml\` from official documentation, scaffold the local MCP, run its doctor, test read-only calls, generate a Codex preview, and apply only after review. The generated server uses STDIO, does not open a port, and blocks writes without explicit approval.
-
-## OpenAI documentation
-
-The default profile enables official OpenAI developer documentation without credentials and in read-only mode. Questions about OpenAI APIs, models, SDKs, Codex, or MCP should use the OpenAI docs skill and cite the consulted page.`,
-};
-
 export function buildHelpDocuments(
   locale: DashboardLocale,
   readme: string,
@@ -264,7 +16,13 @@ export function buildHelpDocuments(
   const guides = Object.entries(guideSources)
     .map(([path, source]) => {
       const fileName = path.split("/").at(-1) ?? path;
-      const content = locale === "en-US" ? (englishGuides[fileName] ?? source) : source;
+      // Guides currently have one canonical Portuguese source. Never substitute
+      // independently maintained summaries that can conceal changed contracts.
+      const content =
+        locale === "en-US"
+          ? "> Language: Portuguese (pt-BR). Current canonical guide; an English translation is not available.\n\n" +
+            source
+          : source;
       return { id: path, title: documentTitle(content, fileName), content };
     })
     .sort((a, b) => a.title.localeCompare(b.title, locale));

package/templates/.agents/dashboard/apps/frontend/src/dashboard-project-overview.ts

@@ -1,7 +1,12 @@
 export interface ProjectOverview {
   framework_version: string | null;
+  installation?: ProjectInstallationSummary;
+  installation_profile?: "full" | "dev-lite" | "lite" | "custom";
+  health?: { state: "healthy" | "degraded" | "unknown"; scope: "settings_runtime" };
+  dependencies?: ProjectInstallationDimension & { installed: number | null };
+  documentation?: ProjectInstallationDimension & { available: number | null };
   metrics: Array<{
-    id: "agents" | "squads" | "skills" | "rules" | "hooks" | "database";
+    id: "agents" | "squads" | "skills" | "rules" | "hooks";
     label: string;
     value: number | string;
   }>;
@@ -23,6 +28,34 @@ export interface ProjectOverview {
       | "sales_playbook";
     label: string;
     artifact: string;
-    available: boolean;
+    available: boolean | null;
   }>;
 }
+
+export type ProjectInstallationState =
+  | "complete"
+  | "incomplete"
+  | "unknown"
+  | "unavailable"
+  | "not_applicable";
+
+export interface ProjectInstallationDimension {
+  applicable: number | null;
+  missing: number | null;
+  unknown: number | null;
+  not_applicable: number | null;
+  percent: number | null;
+  state?: ProjectInstallationState;
+}
+
+/** New fields are optional while older dashboard runtimes are still supported. */
+export interface ProjectInstallationSummary {
+  /** @deprecated Legacy aggregate; it must never be interpreted as dependency health. */
+  completed?: number;
+  /** @deprecated Legacy aggregate; it must never be interpreted as dependency health. */
+  total?: number;
+  /** @deprecated Legacy aggregate; it must never be interpreted as dependency health. */
+  percent?: number;
+  /** @deprecated Legacy aggregate; it must never be interpreted as dependency health. */
+  state?: "complete" | "incomplete";
+}

package/templates/.agents/dashboard/apps/frontend/src/dashboard-retry.ts

@@ -0,0 +1,17 @@
+export function retryDashboardLoad(
+  failedArea: string | null,
+  selectedTraceTaskId: string | null,
+  operations: unknown,
+  loadCostSummary: () => Promise<unknown>,
+  openTrace: (id: string) => Promise<unknown>,
+  loadOperationsDetails: () => Promise<unknown>,
+  refresh: () => Promise<unknown>,
+  setError: (error: string | null) => void,
+): void {
+  setError(null);
+  if (failedArea === "costs") void loadCostSummary();
+  else if (failedArea === "traceability" && selectedTraceTaskId)
+    void openTrace(selectedTraceTaskId);
+  else if (failedArea === "operations" && operations !== null) void loadOperationsDetails();
+  else void refresh();
+}

package/templates/.agents/dashboard/apps/frontend/src/dashboard-setup-route.ts

@@ -0,0 +1,29 @@
+import { renderAppSetupRoute } from "./AppSetupRoutes.js";
+
+type SetupInput = Parameters<typeof renderAppSetupRoute>[0];
+
+export function createDashboardSetupRoute(
+  api: SetupInput["api"],
+  costLocale: SetupInput["costLocale"],
+  fxRate: SetupInput["fxRate"],
+  navigate: SetupInput["navigate"],
+  pathname: SetupInput["pathname"],
+  pricing: SetupInput["pricing"],
+  refresh: () => Promise<unknown>,
+  setFxRate: SetupInput["setFxRate"],
+  setPricing: SetupInput["setPricing"],
+) {
+  return renderAppSetupRoute({
+    api,
+    costLocale,
+    fxRate,
+    navigate,
+    pathname,
+    pricing,
+    refresh: async () => {
+      await refresh();
+    },
+    setFxRate,
+    setPricing,
+  });
+}

package/templates/.agents/dashboard/apps/frontend/src/dashboard-view-actions.test.ts

@@ -0,0 +1,51 @@
+import { afterEach, expect, it, vi } from "vitest";
+import { createDashboardViewSelector } from "./dashboard-view-actions.js";
+
+afterEach(() => vi.unstubAllGlobals());
+
+function fixture(controller: AbortController | null) {
+  vi.stubGlobal("window", { scrollTo: vi.fn() });
+  const input: Parameters<typeof createDashboardViewSelector>[0] = {
+    setDashboardView: vi.fn(),
+    costsLoadedRef: { current: false },
+    currency: "BRL",
+    costs: null,
+    loadCostSummary: vi.fn(async () => undefined),
+    costSummaryAbortRef: { current: controller },
+    traceTasks: [],
+    boardRequestVersionRef: { current: 0 },
+    loadMoreTraceTasks: vi.fn(async () => []),
+    setTraceTasks: vi.fn(),
+    setSelectedTraceTaskId: vi.fn(),
+    openTrace: vi.fn(async () => undefined),
+    setTrace: vi.fn(),
+    setTraceLoadingTaskId: vi.fn(),
+  };
+  return input;
+}
+
+it("joins the active summary when navigation and the automatic load coincide", async () => {
+  const controller = new AbortController();
+  const input = fixture(controller);
+  await createDashboardViewSelector(input)("cost-monitor");
+  expect(input.loadCostSummary).not.toHaveBeenCalled();
+  expect(controller.signal.aborted).toBe(false);
+  expect(input.setDashboardView).toHaveBeenCalledWith("cost-monitor");
+});
+
+it("permits a retry after failure cleanup and an explicitly aborted prior request", async () => {
+  const input = fixture(null);
+  await createDashboardViewSelector(input)("cost-monitor");
+  expect(input.loadCostSummary).toHaveBeenCalledTimes(1);
+  const controller = new AbortController();
+  controller.abort();
+  input.costSummaryAbortRef.current = controller;
+  await createDashboardViewSelector(input)("cost-monitor");
+  expect(input.loadCostSummary).toHaveBeenCalledTimes(2);
+});
+
+it("still aborts the request when leaving Cost Monitor", async () => {
+  const controller = new AbortController();
+  await createDashboardViewSelector(fixture(controller))("operations");
+  expect(controller.signal.aborted).toBe(true);
+});

package/templates/.agents/dashboard/apps/frontend/src/dashboard-view-actions.ts

@@ -0,0 +1,68 @@
+import { shouldLoadCostSummary } from "./AppRequestGuards.js";
+import type { DashboardView } from "./DashboardCapabilityNav.js";
+
+type TraceTask = {
+  id: string;
+  status: string;
+  finished_at: string | null;
+  updated_at: string;
+};
+
+type DashboardViewActions<T extends TraceTask> = {
+  setDashboardView: (view: DashboardView) => void;
+  costsLoadedRef: { current: boolean };
+  currency: "BRL" | "USD";
+  costs: { currency: string } | null;
+  loadCostSummary: () => Promise<unknown>;
+  costSummaryAbortRef: { current: AbortController | null };
+  traceTasks: T[];
+  boardRequestVersionRef: { current: number };
+  loadMoreTraceTasks: (append: boolean, includeCompleted: boolean) => Promise<T[]>;
+  setTraceTasks: (tasks: T[]) => void;
+  setSelectedTraceTaskId: (id: string) => void;
+  openTrace: (id: string) => Promise<unknown>;
+  setTrace: (value: null) => void;
+  setTraceLoadingTaskId: (id: null) => void;
+};
+
+export function createDashboardViewSelector<T extends TraceTask>(input: DashboardViewActions<T>) {
+  return async (nextView: DashboardView) => {
+    input.setDashboardView(nextView);
+    window.scrollTo({ left: 0, top: 0 });
+    if (nextView === "cost-monitor") {
+      if (
+        shouldLoadCostSummary({
+          costsLoaded: input.costsLoadedRef.current,
+          currency: input.currency,
+          snapshotCurrency: input.costs?.currency,
+        }) &&
+        (input.costSummaryAbortRef.current === null ||
+          input.costSummaryAbortRef.current.signal.aborted)
+      )
+        void input.loadCostSummary();
+    } else {
+      input.costSummaryAbortRef.current?.abort();
+    }
+    if (nextView === "traceability") {
+      let candidates = input.traceTasks;
+      if (candidates.length === 0) {
+        const requestVersion = input.boardRequestVersionRef.current;
+        candidates = await input.loadMoreTraceTasks(false, true);
+        if (requestVersion !== input.boardRequestVersionRef.current) return;
+        input.setTraceTasks(candidates);
+      }
+      const ordered = candidates.toSorted(
+        (a, b) =>
+          Date.parse(b.finished_at ?? b.updated_at) - Date.parse(a.finished_at ?? a.updated_at),
+      );
+      const latest = ordered.find((task) => task.status === "completed") ?? ordered[0];
+      if (latest) {
+        input.setSelectedTraceTaskId(latest.id);
+        void input.openTrace(latest.id);
+      }
+      return;
+    }
+    input.setTrace(null);
+    input.setTraceLoadingTaskId(null);
+  };
+}

package/templates/.agents/dashboard/apps/frontend/src/operations-period-render.test.ts

@@ -4,6 +4,7 @@ import { OperationsPage } from "@zaip-ai/dashboard-operations/react";
 import { createElement } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import { describe, expect, it, vi } from "vitest";
+import { readAppCompositionSource } from "./__tests__/app-composition-support.js";
 import { PeriodTransitionOverlay, PeriodTransitionShell } from "./App.js";
 
 const data = {
@@ -42,6 +43,41 @@ function renderPeriod(preset: "today" | "yesterday", loading = false) {
 }
 
 describe("App-owned Operations period render", () => {
+  it("renders factual All Time dates while a bounded selection ignores arriving coverage", () => {
+    const render = (preset: "all" | "this-month", firstDay: string) =>
+      renderToStaticMarkup(
+        createElement(OperationsPage, {
+          capabilityNavigation: createElement("span"),
+          data,
+          datePreset: preset,
+          dateRange: { start: "2026-09-01", end: "2026-09-10" },
+          loading: false,
+          currency: "BRL",
+          locale: "pt-BR",
+          onDateChange: vi.fn(),
+          onLocaleChange: vi.fn(),
+          onOpenDocument: vi.fn(),
+          onOpenTask: vi.fn(async () => false),
+          onPriorityChange: vi.fn(async () => undefined),
+          onRefresh: vi.fn(),
+          factualCostPeriods: {
+            day: [firstDay, "2026-09-10"].map((key) => ({
+              key,
+              estimated_usd: null,
+              estimated_brl: 0,
+              duration_ms: null,
+            })),
+          },
+        }),
+      );
+    expect(render("all", "2026-06-02")).toContain('value="2026-06-02"');
+    expect(render("all", "2026-07-04")).toContain('value="2026-07-04"');
+    const bounded = render("this-month", "2026-06-02");
+    expect(bounded).toContain('value="2026-09-01"');
+    expect(bounded).not.toContain('value="2026-06-02"');
+    expect(bounded).toContain('option value="this-month" selected=""');
+  });
+
   it("renders Today then Yesterday while loading omits duplicated period controls", () => {
     const today = renderPeriod("today");
     const yesterdayLoading = renderPeriod("yesterday", true);
@@ -95,8 +131,8 @@ describe("App-owned Operations period render", () => {
   });
 
   it("reserves the global gate for a period replacement, not secondary pages", () => {
-    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
-    expect(app).toContain("const globalLoadingPending =");
+    const app = readAppCompositionSource();
+    expect(app).toContain("globalLoadingPending:");
     expect(app).toContain("periodTransitionPending ||");
     expect(app).not.toContain("entityPage.loading ||");
     expect(app).not.toContain("Object.values(boardStates).some((state) => state.loading)");