opencode-codeops 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -2,8 +2,109 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 2.2.0 — 2026-10-10
+
+### Fixes
+
+- scripts: make the changelog content test survive the release fold
+- docs: address the Phase 4 review findings
+- tui: arm the clear guard before the identity gate
+- progress: return promises from the tool and progress handlers
+- progress: align schema typings with the host JsonSchema contract
+- tui: scope the status RPC call to the session location
+- tui: contain status transport failures in the strip
+- plan: keep migration admission checkbox-based
+- plan: count only id-prefixed execution tasks
+
+### Chores
+
+- repo: ignore the local project-scope install
+- progress: complete the final full verification
+- progress: pass the Phase 3 full verification
+- progress: pass the Phase 2 full verification
+- plan: final verification and go/no-go record
+- plan: phase 2 full verification
+- plan: phase 1 full verification
+- codeops: refresh the specialist check state
+- codeops: record the specialist check state
+
+### Documentation
+
+- roadmap: mark REQ-LIVE-TASK-PROGRESS done
+- document the live sidebar and update the changelog
+- exec-plan: add the fail-soft progress reporting protocol
+- plan: pass the live-task-progress preflight and resolve 29 findings
+- plan: add the live-task-progress plan set (gate passed)
+- plan: fix the phase 3 review nits and record the review
+- changelog: add the Unreleased entry for the foundation slices
+- plan: record phase 2 review evidence
+- agents: refresh the specialist coverage line
+- agents: add the specialist coverage line to managed project facts
+- changelog: add the 2.1.1 upgrade notes
+
+### Tests
+
+- progress: record the ST-23 remote-client acceptance
+- progress: record the ST-22 live smoke evidence
+- progress: add the exec-plan protocol and docs content tests
+- tui: add the sidebar view implementation tests
+- progress: add the sidebar live-view specification tests
+- progress: add the server wiring implementation tests
+- progress: add the server wiring specification tests
+- progress: add the core implementation tests
+- progress: add the live progress core specification tests
+- smoke: record the live TUI smoke evidence (v2.0.24)
+- tui: add foundation implementation tests
+- tui: add foundation spec tests (red phase)
+- plan: add parser counting implementation tests
+- plan: add the parser counting spec tests (red phase)
+
+### Features
+
+- tui: replace the status strip with the live progress view
+- progress: wire the live run state into the server plugin
+- progress: add the guarded progress tool registration
+- rpc: add the progress method, live events, and emit binding
+- progress: add the run-state runtime and honesty display
+- progress: add the live progress core contracts
+- tui: add the sidebar status strip and packaging
+- tui: register the codeops status RPC from the server plugin
+- tui: add the shared codeops status RPC helper
+- agents: add the agent-pipeline-reviewer specialist
+
+### CI
+
+- test on Node 24 instead of end-of-life Node 20
+
+## 2.1.1 — 2026-10-09
+
+### Upgrade Notes
+
+- Update and restart the OpenCode service to pick up the fix: until the 2.1.1
+  plugin is loaded, plugin unloads keep deleting the shared `$CODEOPS_TMPDIR`
+  directory of running sessions.
+
+### Fixes
+
+- plugin: stop deleting the shared scratch directory on unload
+
+### Tests
+
+- plugin: pin the scratch-directory lifecycle contract (red phase)
+
+### Documentation
+
+- changelog: add the 2.1.0 usage notes and complete the feature
+
 ## 2.1.0 — 2026-10-09
 
+### Usage
+
+- Run the `analyze-agents` skill on demand for a project-level specialist check; it records
+  `codeops/specialist-check.json`, and `analyze-project` reports the coverage line.
+- `exec-plan` records each ruling batch in `plans/<plan>/05-findings.md`, which feeds finding-area
+  recurrence in the check.
+
 ### Documentation
 
 - readme: list the analyze-agents skill and the on-demand detection flow

package/README.md

@@ -145,11 +145,22 @@ The plugin also warns (non-blocking) if any tool attempts to edit `codeops/.code
 
 Every session also gets a workspace-hygiene guard: the plugin exports `CODEOPS_TMPDIR`, a scratch
 directory under the OS temp directory that belongs to the running OpenCode plugin instance. Skills
-and agents put temporary files there and delete them when the run completes; the plugin removes the
-directory when it unloads and sweeps directories abandoned by interrupted runs at startup, so
-CodeOps does not accumulate scratch data. Because OpenCode 2 does not expose a session id to shell
-hooks, concurrent sessions served by one instance share this directory. The full protocol is in
-`_shared/workspace-hygiene.md`.
+and agents put temporary files there and delete them when the run completes; the plugin sweeps
+directories abandoned by interrupted runs at startup (older than seven days), so CodeOps does not
+accumulate scratch data. Because OpenCode 2 does not expose a session id to shell hooks, concurrent
+sessions served by one instance share this directory, and no session's scratch is deleted while
+others may still use it. The full protocol is in `_shared/workspace-hygiene.md`.
+
+## Live task progress in the sidebar
+
+While an `exec-plan` run is active, the sidebar shows the current run — plan, phase, task,
+activity (`starting`, `implementing`, `verifying`, `reviewing`, `delegating`, `blocked`,
+`waiting`, `done`), and the verified-task count — reported by the agent through the
+`codeops_progress` tool. The view is intentionally honest: it always shows an "as of" time; a
+run with no update for 10 minutes is marked "stale" instead of looking live; and nothing renders
+when no run is active, when the host lacks the plugin APIs, or when every call fails. The
+Markdown execution plan remains the single progress source of truth; the live view never gates
+execution.
 
 ## Agent model configuration
 

package/_shared/workspace-hygiene.md

@@ -51,7 +51,9 @@ keep scratch file names specific to the run to avoid collisions.
 
 ## Automatic safety net
 
-The CodeOps plugin exports `$CODEOPS_TMPDIR` for each runtime and removes that runtime's
-directory when the plugin unloads. At startup it also removes CodeOps temp directories older
-than seven days, so an interrupted run cannot leak storage forever. The safety net is a
-fallback, not a substitute: the run itself still performs the cleanup pass above.
+The CodeOps plugin exports `$CODEOPS_TMPDIR` for each runtime. At startup it removes CodeOps
+temp directories older than seven days, so an interrupted run cannot leak storage forever.
+The plugin never deletes a runtime's directory while sessions may still be running — several
+sessions can share one directory, so reclamation happens only through the age-based sweep.
+The safety net is a fallback, not a substitute: the run itself still performs the cleanup
+pass above.

package/bin/lib/codeops-progress.d.mts

@@ -0,0 +1,236 @@
+/**
+ * Type declarations for the live progress core.
+ *
+ * The module is plain JavaScript so `node --test` can exercise it directly;
+ * these declarations give the TypeScript plugin entries typed access.
+ */
+
+/** The eight activity states a run can report. */
+export type CodeOpsActivity =
+  | "starting"
+  | "implementing"
+  | "verifying"
+  | "reviewing"
+  | "delegating"
+  | "waiting"
+  | "blocked"
+  | "done"
+
+/** A progress report as sent by an agent through the tool. */
+export interface CodeOpsProgressReport {
+  readonly plan: string
+  readonly activity: CodeOpsActivity
+  readonly phase?: string
+  readonly task?: string
+  readonly detail?: string
+  readonly verified?: number
+  readonly total?: number
+}
+
+/**
+ * A report after normalization.
+ *
+ * Only fields present in the input appear; optional text fields may be `null`
+ * when the input carried a whitespace-only string.
+ */
+export interface NormalizedProgressReport {
+  readonly plan: string
+  readonly activity: CodeOpsActivity
+  readonly phase?: string | null
+  readonly task?: string | null
+  readonly detail?: string | null
+  readonly verified?: number
+  readonly total?: number
+}
+
+/** One complete run snapshot: the `progress` payload and `updated` event data. */
+export interface CodeOpsRunState {
+  readonly plan: string
+  readonly phase: string | null
+  readonly task: string | null
+  readonly detail: string | null
+  readonly activity: CodeOpsActivity
+  readonly verified: number
+  readonly total: number | null
+  readonly startedAt: number
+  readonly updatedAt: number
+  readonly sessionID: string
+}
+
+/** The cleared-event payload: the cleared run's identity and clear time. */
+export interface CodeOpsRunCleared {
+  readonly plan: string
+  readonly sessionID: string
+  readonly clearedAt: number
+}
+
+/** JSON-Schema shape of the progress tool's input. */
+export type CodeOpsProgressReportSchema = {
+  readonly type: "object"
+  readonly additionalProperties: false
+  readonly required: readonly ["plan", "activity"]
+  readonly properties: {
+    readonly plan: { readonly type: "string" }
+    readonly phase: { readonly type: "string" }
+    readonly task: { readonly type: "string" }
+    readonly activity: { readonly type: "string"; readonly enum: readonly CodeOpsActivity[] }
+    readonly detail: { readonly type: "string" }
+    readonly verified: { readonly type: "integer"; readonly minimum: 0 }
+    readonly total: { readonly type: "integer"; readonly minimum: 0 }
+  }
+}
+
+/** JSON-Schema shape of the progress tool's acknowledgement. */
+export type CodeOpsProgressOutputSchema = {
+  readonly type: "object"
+  readonly additionalProperties: false
+  readonly required: readonly ["ok"]
+  readonly properties: { readonly ok: { readonly type: "boolean" } }
+}
+
+/** JSON-Schema shape of a complete run snapshot. */
+export type CodeOpsRunStateSchema = {
+  readonly type: "object"
+  readonly additionalProperties: false
+  readonly required: readonly [
+    "plan",
+    "phase",
+    "task",
+    "activity",
+    "detail",
+    "verified",
+    "total",
+    "startedAt",
+    "updatedAt",
+    "sessionID",
+  ]
+  readonly properties: {
+    readonly plan: { readonly type: "string" }
+    readonly phase: { readonly type: readonly ["string", "null"] }
+    readonly task: { readonly type: readonly ["string", "null"] }
+    readonly detail: { readonly type: readonly ["string", "null"] }
+    readonly activity: { readonly type: "string"; readonly enum: readonly CodeOpsActivity[] }
+    readonly verified: { readonly type: "integer"; readonly minimum: 0 }
+    readonly total: { readonly type: readonly ["integer", "null"]; readonly minimum: 0 }
+    readonly startedAt: { readonly type: "integer"; readonly minimum: 0 }
+    readonly updatedAt: { readonly type: "integer"; readonly minimum: 0 }
+    readonly sessionID: { readonly type: "string" }
+  }
+}
+
+/** JSON-Schema shape of the cleared-event payload. */
+export type CodeOpsRunClearedSchema = {
+  readonly type: "object"
+  readonly additionalProperties: false
+  readonly required: readonly ["plan", "sessionID", "clearedAt"]
+  readonly properties: {
+    readonly plan: { readonly type: "string" }
+    readonly sessionID: { readonly type: "string" }
+    readonly clearedAt: { readonly type: "integer"; readonly minimum: 0 }
+  }
+}
+
+/** The name of the agent-callable tool that reports task progress. */
+export declare const CODE_OPS_TOOL_NAME: "codeops_progress"
+
+/** The description of the progress tool, shown in the host's tool list. */
+export declare const CODE_OPS_TOOL_DESCRIPTION: string
+
+/** Longest accepted free-text value; longer values are truncated. */
+export declare const CODE_OPS_STRING_CAP: 200
+
+/** Largest accepted `verified`/`total` count; larger values are clamped. */
+export declare const CODE_OPS_COUNT_MAX: 1000000
+
+/** Age in milliseconds at which a run is shown as stale (10 minutes). */
+export declare const CODE_OPS_STALE_MS: 600000
+
+/** The input schema of the progress tool. */
+export declare const ProgressReportSchema: CodeOpsProgressReportSchema
+
+/** The output schema of the progress tool. */
+export declare const ProgressOutputSchema: CodeOpsProgressOutputSchema
+
+/** The schema of one complete run snapshot. */
+export declare const RunStateSchema: CodeOpsRunStateSchema
+
+/** The schema of the cleared-event payload. */
+export declare const RunClearedSchema: CodeOpsRunClearedSchema
+
+/** Validate an unknown value as a progress report. */
+export declare function isCodeOpsProgressReport(value: unknown): value is CodeOpsProgressReport
+
+/** Validate an unknown value as a complete run snapshot. */
+export declare function isCodeOpsRunState(value: unknown): value is CodeOpsRunState
+
+/**
+ * Accept a validated snapshot from an `updated` event scoped to the viewer's
+ * directory; `null` when the event is foreign or its data is invalid.
+ */
+export declare function acceptRunUpdate(event: unknown, directory: string): CodeOpsRunState | null
+
+/**
+ * Accept a validated cleared payload from a `cleared` event scoped to the
+ * viewer's directory; `null` when the event is foreign or its data is invalid.
+ */
+export declare function acceptRunCleared(
+  event: unknown,
+  directory: string
+): CodeOpsRunCleared | null
+
+/** Normalize an unknown report; `null` means rejection. */
+export declare function normalizeProgressReport(value: unknown): NormalizedProgressReport | null
+
+/** Emit binding accepted by {@link CodeOpsProgressRuntime.bindEmit}. */
+export type CodeOpsEmit = (name: string, payload: unknown) => void | Promise<void>
+
+/** The in-memory run-state runtime shared by the tool handler and the RPC. */
+export interface CodeOpsProgressRuntime {
+  /** Normalize and apply a report; `null` means the report was rejected. */
+  report(input: unknown, sessionID: string, nowMs?: number): CodeOpsRunState | null
+  /** The current snapshot, or `null` when no run is active. */
+  snapshot(): CodeOpsRunState | null
+  /**
+   * Clear the active run when `sessionID` is the last reporter; returns the
+   * cleared identity, or `null` when a different session owns the run.
+   */
+  clearSession(sessionID: string): CodeOpsRunCleared | null
+  /** Bind the event emitter; a throwing or rejecting emitter is swallowed. */
+  bindEmit(emit: CodeOpsEmit): void
+}
+
+/** Create one in-memory run-state runtime. */
+export declare function createCodeOpsProgress(): CodeOpsProgressRuntime
+
+/**
+ * Pick the newer of two snapshots; an equal `updatedAt` lets `incoming` win,
+ * so the view converges on the latest delivery.
+ */
+export declare function mergeRunState(
+  current: CodeOpsRunState | null,
+  incoming: CodeOpsRunState
+): CodeOpsRunState
+
+/** Test whether a run has not been updated for ten minutes. */
+export declare function isRunStale(snapshot: Pick<CodeOpsRunState, "updatedAt">, nowMs: number): boolean
+
+/** The rendered sidebar text for a run snapshot. */
+export interface CodeOpsRunDisplay {
+  /** The three display lines (fewer segments when values are unknown). */
+  readonly lines: string[]
+  /** Whether the last update is ten minutes old or older. */
+  readonly stale: boolean
+}
+
+/** Render the visible sidebar lines for a run snapshot. */
+export declare function describeRun(snapshot: CodeOpsRunState, nowMs: number): CodeOpsRunDisplay
+
+/**
+ * Register the agent-callable progress tool on a plugin context,
+ * feature-detected and never-throwing; `false` when the host lacks the tool
+ * API or the registration failed.
+ */
+export declare function registerCodeOpsProgressTool(
+  ctx: unknown,
+  runtime: CodeOpsProgressRuntime
+): Promise<boolean>