@amistio/cli 0.1.31 → 0.1.33

package/README.md

@@ -17,6 +17,8 @@ Runner Update installs the official `@amistio/cli` package and then refreshes th
 
 Current runners advertise the work kinds they can claim. Older runners that do not send this capability can continue legacy brain generation, implementation, and plan revision work, but they will skip source-aware assistant, impact-preview, semantic brain consolidation, project-context refresh, issue-diagnosis, app-evaluation, security-posture, Test-quality, implementation-Test-gate, and implementation-verification work until updated.
 
+Tool session reuse is bounded. One-shot tool sessions close after successful completion, failed runs are blocked, active sessions are treated as already in use, and reusable sessions idle for more than six hours are closed before the next claim selects context. This keeps follow-up work from inheriting stale local AI context while preserving recent reusable sessions for related work.
+
 Repository brain auto-sync is disabled until the repository link option is enabled in the app. After pairing, run `amistio sync watch` from the paired checkout to push recognized external brain Markdown/MDX files and explicit HTML artifacts under `docs/html/<area>/`, including local ADRs, plans, prompts, workflows, memory, context, architecture, and feature docs, to the app for review. Markdown is the default generation format; HTML appears only when a runner or user explicitly generated an HTML artifact. `amistio run --watch` also runs the same cycle between work polls when the option is enabled. The CLI skips templates, unsupported paths, oversized files, unchanged managed docs, and conflicts instead of silently overwriting web state.
 
 Repository autopilot is disabled until the repository link option is enabled in the app. When enabled, Amistio can attach an audited low-risk autopilot authorization to eligible runner work, including generated brain approval, impact preview, issue diagnosis, security posture scan, app evaluation cleanup, low-risk implementation handoff, requeue, and implementation verification. The Runner panel shows and updates safe work scopes, allowed candidate types, max risk, optional runner binding, daily/concurrent/failure budgets, expiry/review/cooldown windows, and pause state. The CLI shows authorization id, candidate id/type, outcome, policy version, and work kind in `amistio work list`, claim logs, runner prompts, and milestone activity. Autopilot does not widen local runner permissions: pairing, supported work kinds, runner identity, Git worktree isolation, redaction, local-tool permission controls, and unsafe/review-required/blocked/paused/budget stops still apply.
@@ -36,6 +38,7 @@ amistio run --watch --tool opencode --provider anthropic --model-id claude-opus-
 amistio run --watch --max-concurrent-work 2 --tool opencode
 amistio run --watch --background --tool opencode
 amistio runner status
+amistio runner smoke-session-lifecycle
 ```
 
 Provider-backed model preferences use sanitized catalog fields: `--provider`, `--model-id`, optional `--model-variant`, and `--reasoning-effort` (`auto`, `low`, `medium`, `high`, or `xhigh`). Opencode catalog metadata is synthesized by Amistio or derived from readable local OpenCode JSON config until opencode exposes a native catalog. Provider credentials, API keys, and local secret paths stay in the local tool configuration; they are not stored in Amistio preferences or runner heartbeats.
@@ -46,6 +49,8 @@ When `--tool codex` uses the Codex SDK, intermediate progress can be quiet until
 
 `amistio runner status` reports local background runner state, latest heartbeat, and bounded resource usage when available. Resource usage is latest-sample runner process memory/CPU plus safe aggregate system memory/load signals; it does not include source files, environment variables, command lines, process lists, credentials, or arbitrary local paths.
 
+`amistio runner smoke-session-lifecycle` runs a local no-claim smoke for the runner tool-session lifecycle. It does not contact the API, claim production work, inspect source, or mutate local runner state; it verifies that completed one-shot sessions close, active sessions are treated as in use, stale sessions are not selected for reuse, and fresh related reusable sessions can still continue.
+
 The runner advertises its supported work kinds in heartbeats. Current runners can claim read-only `projectContextRefresh` jobs from the workspace Context panel and create due runner-driven refreshes when no fresh approved map exists. Context refreshes inspect the paired checkout locally without modifying files and submit only bounded summaries, slices, entities, relations, safe citations, confidence, freshness, and repo-relative paths. If a submitted context refresh contains unsafe evidence, unsafe paths, or a map too large to store safely, Amistio marks the refresh failed with a safe reason instead of storing the rejected raw result. Approved maps are reused as context packs for source-aware assistant and impact-preview work. Current runners can also claim read-only issue diagnosis jobs from the web Issues panel, generate root-cause analysis and a proposed fix, and submit that result without modifying source. They can claim manual read-only `appEvaluationScan` jobs from the workspace Evaluate panel and create at most one due hourly evaluation during normal watch/background polling when app evaluation is enabled for the repository link. Evaluation results contain bounded summaries, safe evidence, suggested actions, lifecycle proposals, and repo-relative paths only. Current runners can also claim manual read-only `securityPostureScan` jobs from the workspace Security panel and create due daily posture checks during normal watch/background polling. Security scan results contain bounded summaries, standard references, safe evidence, and repo-relative paths only. Current runners can claim manual read-only `testQualityScan` jobs from the workspace Test panel and create one due daily Test scan per repository when Test quality is enabled. Test scans run only existing lint, typecheck, test, coverage, build, or verify commands and submit bounded command summaries, coverage summaries, safe findings, blocked reasons, warnings, and repo-relative paths. Missing tests, missing coverage, low coverage, failing checks, flaky tests, and test gaps create reviewable plan-backed findings in the app. Current runners also claim `implementationTestGate` jobs before implementation completion, PR handoff, or runner-managed push; a passing gate is required unless the web Test panel records an audited override. Blocked implementation Test gates submit structured Test findings, such as `blockedEnvironment`, with safe evidence, a suggested action, and a verification plan. Current runners can claim read-only `implementationVerification` jobs from Tasks to prove whether completed implementation work actually landed; verification submits bounded acceptance-criteria evidence, checks, gaps, outcome, and recommendation without mutating source. Source, secrets, environment variables, command lines, process lists, credentials, provider sessions, and arbitrary local paths stay local. Implementation or cleanup is queued separately only after the user approves an issue analysis, app evaluation finding, security remediation plan, or Test quality plan in the app.
 
 Approved implementation work uses Git as the handoff boundary. During worktree preflight, the runner locally copies eligible ignored root dotenv files such as `.env.local` or `.env.test.local` from the paired checkout into the implementation worktree when the target is missing and ignored, so local tests can use the same machine configuration. Dotenv values, variable names, file contents, and local paths are not uploaded to Amistio, and copied dotenv files stay ignored so PR handoff does not commit them. After the local tool completes successfully, the runner materializes approved Markdown, MDX, and HTML project-brain artifacts for the same work scope into the isolated worktree before final Git status. It then commits all source and artifact changes, fetches and rebases from the linked remote's default branch, pushes an `amistio/work/...` branch, opens or reuses a pull request with the locally authenticated `gh` CLI, reports only safe PR and artifact-inclusion metadata to Amistio, and removes the local worktree after the PR URL is durable. Artifact-only materialization changes still create or reuse a PR; no-change completion requires no source changes and no approved artifact changes. Prepare the runner machine with Git commit identity, fetch/push permission to the linked remote, and `gh auth status`. If artifact materialization, commit, fetch/rebase, push, or PR creation fails, the work item is blocked and the branch/worktree stay on disk for manual recovery; source files and patches are not uploaded to Amistio.

package/dist/index.js

@@ -4740,8 +4740,32 @@ function runProcess(command, args, timeoutMs) {
   });
 }
 
+// src/tool-session-lifecycle.ts
+var TOOL_SESSION_MAX_IDLE_MS = 6 * 60 * 60 * 1e3;
+function completedToolSessionStatus(session) {
+  return session.resumabilityScope === "none" ? "closed" : "open";
+}
+function completedToolSessionClosedReason(session) {
+  if (session.resumabilityScope !== "none") {
+    return void 0;
+  }
+  return "Completed one-shot tool run; this session is not reusable.";
+}
+function staleToolSessionClosedReason(session, now = /* @__PURE__ */ new Date()) {
+  if (session.status !== "open") {
+    return void 0;
+  }
+  const lastActivityMs = Date.parse(session.lastActivityAt);
+  if (!Number.isFinite(lastActivityMs)) {
+    return "Session has an invalid last activity timestamp; closing to prevent stale context reuse.";
+  }
+  if (lastActivityMs + TOOL_SESSION_MAX_IDLE_MS >= now.getTime()) {
+    return void 0;
+  }
+  return "Session idle window expired; closing to prevent stale context reuse.";
+}
+
 // src/session-policy.ts
-var maxIdleMs = 24 * 60 * 60 * 1e3;
 var maxTotalMs = 7 * 24 * 60 * 60 * 1e3;
 var maxMessageCount = 80;
 var maxEstimatedTokens = 12e4;
@@ -4825,10 +4849,10 @@ function sessionIneligibleReason(session, input, now) {
   if (input.workItem.executionWorktreeKey && session.executionWorktreeKey !== input.workItem.executionWorktreeKey) {
     return "worktree scope mismatch";
   }
-  if (session.status === "closed" || session.status === "archived" || session.status === "blocked" || session.status === "unavailable") {
+  if (session.status === "closed" || session.status === "archived" || session.status === "blocked" || session.status === "unavailable" || session.status === "active") {
     return `session is ${session.status}`;
   }
-  if (Date.parse(session.lastActivityAt) + maxIdleMs < now.getTime()) {
+  if (Date.parse(session.lastActivityAt) + TOOL_SESSION_MAX_IDLE_MS < now.getTime()) {
     return "session is idle past the reuse window";
   }
   if (Date.parse(session.createdAt) + maxTotalMs < now.getTime()) {
@@ -4873,6 +4897,134 @@ function tokens(value) {
   return value.toLowerCase().split(/[^a-z0-9]+/).filter((token) => token.length >= 4);
 }
 
+// src/runner-activation-smoke.ts
+function runRunnerActivationSmoke(now = /* @__PURE__ */ new Date()) {
+  const reusableSession = createSmokeSession({ now, status: "open", lastActivityAt: new Date(now.getTime() - 60 * 60 * 1e3).toISOString() });
+  const activeSession = createSmokeSession({ now, status: "active", lastActivityAt: new Date(now.getTime() - 60 * 60 * 1e3).toISOString() });
+  const staleOpenSession = createSmokeSession({ now, status: "open", lastActivityAt: new Date(now.getTime() - 7 * 60 * 60 * 1e3).toISOString() });
+  const workItem = createSmokeWorkItem(now);
+  const oneShotStatus = completedToolSessionStatus({ resumabilityScope: "none" });
+  const oneShotClosedReason = completedToolSessionClosedReason({ resumabilityScope: "none" });
+  const reusableStatus = completedToolSessionStatus({ resumabilityScope: "localMachine" });
+  const activeSelection = selectToolSession({
+    policy: "auto",
+    workItem,
+    sessions: [activeSession],
+    toolName: "opencode",
+    runnerId: "runner_smoke",
+    repositoryLinkId: "repo_smoke",
+    machineId: "machine_smoke",
+    supportsSessionReuse: true,
+    now
+  });
+  const staleSelection = selectToolSession({
+    policy: "auto",
+    workItem,
+    sessions: [staleOpenSession],
+    toolName: "opencode",
+    runnerId: "runner_smoke",
+    repositoryLinkId: "repo_smoke",
+    machineId: "machine_smoke",
+    supportsSessionReuse: true,
+    now
+  });
+  const reusableSelection = selectToolSession({
+    policy: "auto",
+    workItem,
+    sessions: [reusableSession],
+    toolName: "opencode",
+    runnerId: "runner_smoke",
+    repositoryLinkId: "repo_smoke",
+    machineId: "machine_smoke",
+    supportsSessionReuse: true,
+    now
+  });
+  const staleClosedReason = staleToolSessionClosedReason(staleOpenSession, now);
+  const checks = [
+    {
+      name: "completed-one-shot-closes",
+      passed: oneShotStatus === "closed" && Boolean(oneShotClosedReason),
+      detail: `completed one-shot status=${oneShotStatus}`
+    },
+    {
+      name: "completed-reusable-stays-open",
+      passed: reusableStatus === "open",
+      detail: `completed reusable status=${reusableStatus}`
+    },
+    {
+      name: "active-session-not-reused",
+      passed: activeSelection.decision === "created",
+      detail: `active selection decision=${activeSelection.decision}`
+    },
+    {
+      name: "stale-session-not-reused",
+      passed: staleSelection.decision === "created" && Boolean(staleClosedReason),
+      detail: `stale selection decision=${staleSelection.decision}`
+    },
+    {
+      name: "fresh-reusable-session-reused",
+      passed: reusableSelection.decision === "continued",
+      detail: `fresh reusable selection decision=${reusableSelection.decision}`
+    }
+  ];
+  return {
+    checkedAt: now.toISOString(),
+    passed: checks.every((check) => check.passed),
+    checks
+  };
+}
+function createSmokeWorkItem(now) {
+  const timestamp = now.toISOString();
+  return {
+    id: "work_smoke",
+    type: "workItem",
+    schemaVersion: 1,
+    accountId: "acct_smoke",
+    projectId: "proj_smoke",
+    workItemId: "work_smoke",
+    workKind: "implementation",
+    status: "running",
+    title: "Implement runner session smoke",
+    requestedBy: "user_smoke",
+    requestedByUserId: "user_smoke",
+    attempt: 1,
+    idempotencyKey: "smoke_session_lifecycle",
+    sessionGroupKey: "session_smoke",
+    lastStatusAt: timestamp,
+    createdAt: timestamp,
+    updatedAt: timestamp
+  };
+}
+function createSmokeSession({ now, status, lastActivityAt }) {
+  const timestamp = now.toISOString();
+  return {
+    id: `tool_session_smoke_${status}`,
+    type: "toolSession",
+    schemaVersion: 1,
+    accountId: "acct_smoke",
+    projectId: "proj_smoke",
+    toolSessionId: `tool_session_smoke_${status}`,
+    repositoryLinkId: "repo_smoke",
+    tool: "opencode",
+    provider: "opencode",
+    resumabilityScope: "localMachine",
+    title: "Implement runner session smoke",
+    summary: "Smoke test session",
+    tags: ["runner", "session", "smoke"],
+    relatedDocumentIds: [],
+    status,
+    runnerId: "runner_smoke",
+    machineId: "machine_smoke",
+    lastWorkItemId: "work_previous",
+    lastActivityAt,
+    messageCount: 1,
+    reusePolicy: "auto",
+    sessionGroupKey: "session_smoke",
+    createdAt: timestamp,
+    updatedAt: timestamp
+  };
+}
+
 // src/sync.ts
 import { execFile as execFile3 } from "node:child_process";
 import { createHash as createHash5 } from "node:crypto";
@@ -6035,6 +6187,7 @@ function createAppEvaluationScanPrompt(workItem, context) {
     "- Treat active proposed, approved, ready, or in-progress plans/prompts with accepted controlling ADRs, features, or work artifacts as active backlog. Do not classify them as cleanup material solely because they are older, unexecuted, or not yet fully implemented; use keepActive when they still describe valid pending or approved work.",
     "- Treat intentionally in-progress feature tracks as still-active work when their controlling plan/feature has unchecked requirements or explicit follow-up gaps. For example, a completed first implementation prompt does not make the broader feature stale if PLAN/FEAT evidence says remaining lifecycle work is still open; return proposedLifecycleAction keepActive with evidence instead of cleanup.",
     "- Treat prompt frontmatter status Ready as an active execution backlog state by default, not as stale review debt. Only flag a Ready prompt for metadata correction when its controlling plan, feature, prompt index, or verification evidence unambiguously proves the prompt has already completed or been superseded.",
+    "- Treat implemented umbrella plans that explicitly label unchecked checklist items as deferred follow-ups, future candidates, roadmap backlog, or split-out hardening phases as valid deferred backlog. Do not mark the umbrella incomplete or stale solely because those deferred items remain unchecked; use keepActive or no cleanup, and recommend a fresh focused plan only when a concrete deferred slice has current evidence and approval.",
     "- When lifecycle metadata disagrees across indexes, frontmatter, feature specs, ADRs, and implementation evidence, cite the conflict and propose a metadata correction or verification step instead of archival/removal.",
     "- Check missing memory or workflow updates when repeated lessons or operational rules are visible.",
     "- Check release readiness, UX, accessibility, performance, reliability, and security-posture follow-through at a summary level.",
@@ -8472,6 +8625,20 @@ runner.command("status").description("Show background runner status for the pair
     console.log(`  Resource usage: ${formatRunnerResourceUsage(heartbeat?.resourceUsage)}`);
   }
 });
+runner.command("smoke-session-lifecycle").description("Run a local no-claim smoke for runner tool-session lifecycle behavior").option("--json", "Print the smoke report as JSON").action((options) => {
+  const report = runRunnerActivationSmoke();
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(`Runner session lifecycle smoke: ${report.passed ? "passed" : "failed"}`);
+    for (const check of report.checks) {
+      console.log(`  ${check.passed ? "ok" : "fail"} ${check.name}: ${check.detail}`);
+    }
+  }
+  if (!report.passed) {
+    process.exitCode = 1;
+  }
+});
 runner.command("stop").description("Stop a background runner for the paired repository").option("--api-url <url>", apiUrlOptionDescription, defaultApiUrl()).option("--root <path>", "Repository root", defaultRoot).option("--runner-id <runnerId>", "Runner ID to stop when multiple background runners exist").action(async (options) => {
   const context = await loadPairedApiContext(options.root, options.apiUrl);
   if (!context) {
@@ -11026,6 +11193,8 @@ async function prepareToolSession({
   workItem
 }) {
   const { toolSessions } = await apiClient.listToolSessions(projectId);
+  const now = /* @__PURE__ */ new Date();
+  await closeStaleToolSessionsBestEffort(apiClient, projectId, toolSessions, now);
   const selection = selectToolSession({
     policy: sessionPolicy,
     workItem,
@@ -11034,7 +11203,8 @@ async function prepareToolSession({
     runnerId,
     repositoryLinkId,
     machineId,
-    supportsSessionReuse
+    supportsSessionReuse,
+    now
   });
   if (selection.decision === "skipped") {
     return selection;
@@ -11076,6 +11246,18 @@ async function prepareToolSession({
   });
   return { ...selection, toolSession };
 }
+async function closeStaleToolSessionsBestEffort(apiClient, projectId, toolSessions, now) {
+  const staleSessions = toolSessions.map((session) => ({ session, reason: staleToolSessionClosedReason(session, now) })).filter((item) => Boolean(item.reason));
+  if (!staleSessions.length) {
+    return;
+  }
+  const settlements = await Promise.allSettled(staleSessions.map(({ session, reason }) => apiClient.updateToolSession(projectId, session.toolSessionId, {
+    status: "closed",
+    closedReason: reason,
+    summary: session.summary ?? reason
+  })));
+  logRejectedSettlements("close stale tool sessions", settlements);
+}
 async function finalizeToolSession({
   apiClient,
   costUsd,
@@ -11093,8 +11275,10 @@ async function finalizeToolSession({
     return void 0;
   }
   const summary = summarizeToolOutput(stdout) ?? session.summary;
+  const nextStatus = status === "completed" ? completedToolSessionStatus(session) : "blocked";
+  const closedReason = status === "completed" ? completedToolSessionClosedReason(session) : "Last run failed or returned a non-zero exit code.";
   const { toolSession } = await apiClient.updateToolSession(projectId, session.toolSessionId, {
-    status: status === "completed" ? "open" : "blocked",
+    status: nextStatus,
     runnerId,
     lastWorkItemId: workItemId,
     messageCount: (session.messageCount ?? 0) + (messageCount ?? 1),
@@ -11102,7 +11286,7 @@ async function finalizeToolSession({
     ...tokensIn !== void 0 ? { estimatedInputTokens: (session.estimatedInputTokens ?? 0) + tokensIn } : {},
     ...tokensOut !== void 0 ? { estimatedOutputTokens: (session.estimatedOutputTokens ?? 0) + tokensOut } : {},
     ...costUsd !== void 0 ? { costUsd: (session.costUsd ?? 0) + costUsd } : {},
-    ...status === "failed" ? { closedReason: "Last run failed or returned a non-zero exit code." } : {}
+    ...closedReason ? { closedReason } : {}
   });
   return toolSession;
 }