@osolmaz/pi-workflows 0.6.1 → 0.8.0

package/docs/JOB_PROGRESS.md

@@ -0,0 +1,119 @@
+# Durable job progress
+
+`@osolmaz/pi-workflows/job-progress` lets a remote job publish progress that a Pi Workflows monitor can validate and measure. It uses the existing `pi-workflows.progress.v1` track contract and ETA estimator.
+
+## Report progress
+
+Create one reporter for one physical job. Inject the storage write so the package remains independent of a cloud provider.
+
+```ts
+import { createJobProgressReporter } from "@osolmaz/pi-workflows/job-progress";
+
+const reporter = createJobProgressReporter({
+  application: "example",
+  component: "batch-worker",
+  jobId: process.env.JOB_ID ?? "local",
+  sourceRevision: "abc123",
+  contractHash: "def456",
+  startedAt: new Date().toISOString(),
+  initialTracks: [
+    {
+      key: "overall",
+      data: {
+        schema: "pi-workflows.progress.v1",
+        status: "running",
+        phase: "starting",
+      },
+    },
+  ],
+  minimumIntervalMs: 30_000,
+  publishTimeoutMs: 15_000,
+  publish: async (snapshot, signal) => {
+    await bucket.writeText(progressPath, JSON.stringify(snapshot), { signal });
+  },
+});
+
+await reporter.report({
+  phase: "processing",
+  tracks: [
+    {
+      key: "records",
+      data: {
+        schema: "pi-workflows.progress.v1",
+        status: "running",
+        phase: "processing",
+        completed: 400,
+        total: 1_000,
+        unit: "records",
+      },
+    },
+  ],
+});
+```
+
+The first update, each phase change, and each terminal update publishes immediately. Other updates are coalesced until `minimumIntervalMs` has passed. Call `flush()` at a durable checkpoint or before exit when the current snapshot has not been published.
+
+On process restart, read and validate the existing snapshot and pass it as `previousSnapshot`. The reporter continues its sequence number and rejects an identity, deadline, or terminal-state mismatch.
+
+The reporter keeps the latest snapshot after a write failure. The application decides when to log and retry that failure. A timed-out storage write remains serialized until the underlying write settles, so an older write cannot overwrite a newer snapshot. Storage adapters must honor the abort signal and settle after cancellation. A progress failure must not replace receipt or checkpoint validation.
+
+## Finish a job
+
+A terminal update gets a finish timestamp and publishes immediately:
+
+```ts
+await reporter.report({
+  state: "completed",
+  phase: "complete",
+  tracks: [
+    {
+      key: "records",
+      data: {
+        schema: "pi-workflows.progress.v1",
+        status: "completed",
+        phase: "complete",
+        completed: 1_000,
+        total: 1_000,
+        unit: "records",
+      },
+    },
+  ],
+});
+```
+
+A terminal snapshot is not a receipt. Receipts, manifests, hashes, and durable application outputs remain authoritative.
+
+## Store and discover snapshots
+
+Write one mutable snapshot per physical job:
+
+```text
+<existing-bucket>/<application-prefix>/runs/<job-id>/progress.json
+```
+
+Add these immutable labels to the job or schedule:
+
+```text
+progress_schema=pi-workflows.job-progress.v1
+progress_bucket=<existing-bucket>
+progress_prefix=<application-prefix>/runs
+```
+
+A monitor reads the labels, forms `<progress_prefix>/<job-id>/progress.json`, validates the snapshot with `validateJobProgressSnapshot`, and publishes its tracks with stable keys. It should retain consecutive snapshots so Pi Workflows can estimate a conservative ETA from measured rates.
+
+## Estimate from snapshots
+
+```ts
+import { estimateJobProgress } from "@osolmaz/pi-workflows/job-progress";
+
+const result = estimateJobProgress(previousSnapshots);
+for (const estimate of result.estimates) {
+  console.log(estimate.key, estimate.remainingMedianMs);
+}
+```
+
+The estimator returns no measured ETA until a track has a known total and enough positive progress samples. A source-provided `sourceEstimatedFinishAt` remains available through the normal progress contract.
+
+## Data boundary
+
+Snapshots may contain identifiers, phases, counters, totals, timestamps, and cost totals. Do not put credentials, environment values, input records, model responses, logs, or private content in a snapshot. The strict validator rejects unknown fields and limits the encoded snapshot to 64 KiB.

package/docs/MONITOR.md

@@ -242,6 +242,11 @@ One monitor can track several processes. Each uses a stable progress key. A miss
 
 The progress estimator treats each key independently. A phase, unit, total, or counter reset in one track does not reset another track.
 
+Remote Jobs can publish the same tracks in a strict
+[`pi-workflows.job-progress.v1` snapshot](JOB_PROGRESS.md). A monitor discovers
+the snapshot from immutable Job labels, validates its identity, and submits its
+tracks without copying log-derived guesses into progress fields.
+
 ## Interval and lifetime
 
 The normal workflow engine remains finite. The built-in monitor therefore retains the 1,000-check safety ceiling and must not claim to be mathematically unbounded.

package/docs/plans/2026-08-17-bundled-skills-plan.md

@@ -0,0 +1,104 @@
+---
+title: Bundle Pi Workflows skills with the extension
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-17
+---
+
+# Bundle Pi Workflows skills with the extension
+
+Pi Workflows should be the single source of truth for instructions that teach an agent how to use its extension and built-in workflows. Installing the Pi package should discover those skills with the extension, while Pi's normal package filters let users disable either resource type or an individual skill.
+
+## Outcome
+
+The npm package will include two optional Pi skills:
+
+- `pi-workflows` explains when and how to use the `workflow` tool, control runs, complete step contracts, publish progress, and author workflow files.
+- `monitor` starts and operates the built-in monitor workflow with the established 30-minute default, inferred finish rule, status report on every check, and structured progress guidance.
+
+The existing monitor skill in `osolmaz/tools` will move here and be removed from that repository. OnurPi will expose the upstream extension and skills from one reviewed package version.
+
+## Scope
+
+- Add stable skill paths under `skills/`.
+- Declare both the extension and skills in the Pi package manifest.
+- Include the skill files in npm artifacts.
+- Document bundled resources and independent disable controls.
+- Add automated checks for manifest paths, skill metadata, package contents, and duplicate skill names.
+- Test discovery from a packed package with the real Pi runtime.
+- Release the compatible feature as `0.7.0`, following the repository's pre-1.0 minor-release convention.
+- Update the OnurPi pin and package resource forwarding.
+- Delete the Tools copy and sync local skill mirrors so no duplicate remains.
+
+## Non-goals
+
+- Do not add a new workflow node, workflow schema field, or Pi core API.
+- Do not load skills only while a workflow step is active.
+- Do not create a general workflow-to-skill attachment system.
+- Do not copy unrelated operating-policy skills such as `autoimplement` or `autoresearch-loop`.
+
+## Public contract
+
+The package uses Pi's documented package resource contract:
+
+- `pi.extensions` exposes the existing extension.
+- `pi.skills` exposes `skills/`.
+- Pi package filters and `pi config` can disable all skills, one skill, or the extension independently.
+
+The `workflow` tool description remains the small always-available call contract. The `pi-workflows` skill contains detailed guidance that Pi loads only when a matching task requires it. Workflow step messages remain compact and authoritative for `submit` and `update` attempt identifiers.
+
+## Contract impact
+
+- **Session state:** no new session entry or change to normal Pi session behavior.
+- **Other persistent data:** none.
+- **Pi internals:** none.
+- **Public Pi API:** package `pi.skills` discovery and existing package resource filters. The extension continues to use its current public APIs.
+
+## Implementation
+
+1. Add `skills/pi-workflows/SKILL.md` with concise tool and authoring guidance linked to the bundled reference docs.
+2. Move the current monitor skill to `skills/monitor/SKILL.md` and align repository-relative references with the package layout.
+3. Add `skills` to the npm package files and Pi manifest.
+4. Add tests that validate declared paths, required frontmatter, unique skill names, and packed files.
+5. Update README installation and configuration examples, including independent resource filtering.
+6. Pack the package and start the real Pi runtime from that artifact. Verify that `/skill:pi-workflows` and `/skill:monitor` are discovered with the extension, then verify that package filtering can hide the monitor skill without hiding the extension.
+7. Run all repository checks and Pi Reviewer, merge, release `0.7.0`, and verify npm contents.
+8. Pin `0.7.0` in OnurPi, forward the dependency's skills, and run OnurPi checks.
+9. Remove `agents/skills/monitor` from Tools, run the sync script, and verify that the installed skill now comes from the Pi Workflows package only.
+
+## Acceptance criteria
+
+- A direct Pi installation of `@osolmaz/pi-workflows` discovers the extension and both skills.
+- The OnurPi wrapper discovers the same two upstream skills.
+- Users can disable bundled skills or the extension with standard Pi package settings.
+- The model can use the `workflow` tool from the new skill without larger workflow step messages.
+- npm contains the two `SKILL.md` files and their referenced documentation.
+- Tools contains no monitor skill source or synced duplicate.
+- Local checks, real-Pi end-to-end tests, Pi Reviewer, and CI pass.
+
+## Verification
+
+Run in `pi-workflows`:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+npx -y @simpledoc/simpledoc check
+npm pack --dry-run
+```
+
+Run the packed-package Pi discovery smoke test documented by the implementation, then run in OnurPi:
+
+```bash
+npm run check
+npm run slophammer
+git diff --check
+```
+
+Run in Tools after deletion:
+
+```bash
+python3 agents/sync-skills.py
+npx -y @simpledoc/simpledoc check
+```

package/docs/plans/2026-08-17-durable-job-progress-plan.md

@@ -0,0 +1,176 @@
+# Durable job progress
+
+## Problem
+
+Long-running remote jobs can expose state only through logs and final receipts. A monitor can confirm that a job is running, but it cannot give a reliable progress value or remaining time when the job does not publish a completed count, a total, and source timestamps.
+
+xTap Pool and OurModels need the same durable progress contract. The contract must work with their existing Hugging Face Buckets, survive worker restarts, and use the ETA estimator that Pi Workflows already uses for `pi-workflows.progress.v1` tracks.
+
+## Requirements
+
+The implementation must:
+
+- add one storage-neutral job progress API to `@osolmaz/pi-workflows`
+- reuse `pi-workflows.progress.v1` for progress tracks
+- write one mutable snapshot for each physical job in the application's existing Bucket
+- let monitors discover the snapshot from immutable job labels
+- let Pi Workflows validate the snapshot and estimate remaining time from repeated samples
+- let xTap Pool report restore, review, recovery, and publication progress
+- let OurModels report discovery, processing, cache, and publication progress
+- keep receipts, content hashes, manifests, and databases authoritative
+- avoid secrets, post text, model output, and other private content in progress snapshots
+- preserve one physical enrichment job at a time during the xTap Pool change
+- leave the OurModels replacement schedule suspended until a paid run is separately approved
+
+## Non-goals
+
+This work does not add:
+
+- a new remote store
+- a metrics database
+- a second ETA protocol
+- a Pi core change
+- a service or daemon
+- a compatibility path for an older snapshot schema
+- automatic authority to retry, deploy, publish, or spend money
+
+## Public contract
+
+The npm package exports a new subpath:
+
+```ts
+import {
+  createJobProgressReporter,
+  estimateJobProgress,
+  validateJobProgressSnapshot,
+  type JobProgressSnapshot,
+} from "@osolmaz/pi-workflows/job-progress";
+```
+
+A snapshot has schema `pi-workflows.job-progress.v1` and contains:
+
+- stable application and component names
+- the physical job identifier
+- source and work-contract identifiers
+- a monotonic sequence number
+- job state and current phase
+- start, update, optional deadline, and optional finish timestamps
+- one or more keyed `pi-workflows.progress.v1` tracks
+- optional settled cost and active reservation facts
+
+The validator is strict. It rejects unknown fields, duplicate track keys, invalid timestamps, non-finite values, invalid progress tracks, and oversized snapshots.
+
+The reporter accepts an injected asynchronous `publish(snapshot)` callback. Pi Workflows does not import a Hugging Face client. The reporter:
+
+- keeps sequence numbers monotonic within the process
+- rejects regressions within one phase and epoch
+- coalesces frequent updates with a configurable minimum interval
+- flushes phase changes and terminal states immediately
+- bounds publication time with an abort deadline
+- preserves the most recent unsent snapshot after a transient publication failure
+- never includes arbitrary metadata or environment values
+
+A terminal snapshot is operational evidence only. The application's receipt and durable output validation still decide whether work succeeded.
+
+## Storage and discovery
+
+Each application writes snapshots to its existing Bucket.
+
+xTap Pool uses:
+
+```text
+osolmaz/xtap-pool-bucket/operations/enrichment/runs/<job-id>/progress.json
+```
+
+OurModels uses:
+
+```text
+osolmaz/ourmodels-data/<prefix>/operations/community-posts/runs/<job-id>/progress.json
+```
+
+Each schedule supplies these immutable labels:
+
+```text
+progress_schema=pi-workflows.job-progress.v1
+progress_bucket=<bucket>
+progress_prefix=<path-before-job-id>
+```
+
+A monitor reads the labels, appends the physical job identifier and `progress.json`, reads the snapshot with existing local Hugging Face authentication, validates it, and publishes each track under a stable workflow progress key. The monitor does not trust an ETA string from logs. It uses source finish time when the snapshot provides one, or the existing conservative estimator after enough measured samples.
+
+## xTap Pool tracks
+
+The enrichment worker reports these stable tracks when facts are measurable:
+
+| Key                | Unit       | Source                                             |
+| ------------------ | ---------- | -------------------------------------------------- |
+| `database-restore` | bytes      | downloaded database bytes and expected object size |
+| `registry-replay`  | events     | replayed registry events and discovered total      |
+| `registry-scan`    | candidates | durable scan cursor and fixed candidate total      |
+| `queue`            | records    | terminal records and durable queue total           |
+| `publication`      | bytes      | uploaded and verified database bytes               |
+| `overall`          | phases     | completed phases and fixed phase count             |
+
+Phase-only states remain valid when a total is not yet known. The worker must not invent totals.
+
+The existing three unresolved records must receive durable outcomes under the fixed full-response deadline or become exactly validated blocked records. The worker then publishes and verifies the index before its final receipt is accepted.
+
+## OurModels tracks
+
+The community-posts worker reports these stable tracks when facts are measurable:
+
+| Key               | Unit    | Source                                          |
+| ----------------- | ------- | ----------------------------------------------- |
+| `model-discovery` | models  | discovered and inspected model count            |
+| `community-posts` | models  | processed models and fixed discovered total     |
+| `cache`           | records | durable cached model results and expected total |
+| `publication`     | bytes   | uploaded and verified artifact bytes            |
+| `overall`         | phases  | completed phases and fixed phase count          |
+
+The worker continues to use its existing receipt and manifest rules. A progress write failure must not corrupt a useful checkpoint or published result.
+
+## Delivery sequence
+
+1. Add and release `@osolmaz/pi-workflows/job-progress` as version `0.8.0`.
+2. Add snapshot discovery guidance to the bundled monitor skill.
+3. Update xTap Pool to use `0.8.0`, add measured callbacks, and add schedule labels.
+4. Merge and deploy xTap Pool, then replace the old suspended schedule.
+5. End the old physical job only when the replacement source is ready and the one-job rule can be preserved.
+6. Start one instrumented xTap Pool recovery job under the existing restoration budget.
+7. Update OurModels to use `0.8.0`, add measured callbacks, and replace old schedules with one suspended instrumented schedule.
+8. Do not start a paid OurModels run until its measured cost range and ceiling receive the required approval.
+9. Start a Pi monitor that reads both progress surfaces and displays current progress and ETA.
+
+## Acceptance checks
+
+Pi Workflows must pass:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+```
+
+Tests must cover strict validation, unknown fields, duplicate keys, monotonic updates, phase resets, coalescing, transient publication failure, deadline abort, terminal flush, and ETA estimation from snapshots.
+
+xTap Pool must pass its repository checks, including mutation testing. A live recovery must show a valid snapshot in the existing index Bucket, and repeated monitor samples must produce a measured ETA when a track has a known total and positive progress.
+
+OurModels must pass:
+
+```bash
+npm run check
+npm run coverage
+npm run dry
+npm run mutate
+node scripts/test-bounds-engine.mjs
+node scripts/validate-model-data.mjs
+```
+
+Its replacement schedule must remain suspended with only the approved two secrets until a paid run is authorized.
+
+## Recovery
+
+If a progress publication fails, the worker keeps useful work and retries only the latest snapshot at the next bounded update. If the job ends before that succeeds, the receipt and durable outputs remain authoritative and the monitor marks progress stale.
+
+If a repeated deterministic worker defect appears, stop the affected job and schedule. Preserve all existing Bucket objects and return the exact failing phase, source revision, snapshot, receipt state, and last valid durable outputs.

package/docs/workflows.md

@@ -369,6 +369,16 @@ and resume later by running that wait again from the beginning.
 A monitor uses the session's single active workflow slot. It does not provide
 cron syntax, calendar scheduling, OS notifications, or a background service.
 
+### Durable remote Job progress
+
+Remote workers can publish the same progress tracks through
+`@osolmaz/pi-workflows/job-progress`. The storage-neutral reporter writes a
+strict, versioned snapshot through an application-supplied callback. A monitor
+can read consecutive snapshots from an existing remote store and use the normal
+progress estimator without treating logs as durable state. See
+[JOB_PROGRESS.md](JOB_PROGRESS.md) for the API, snapshot schema, restart rules,
+and discovery labels.
+
 ## The step contract
 
 Every `agent` prompt ends with a step contract block naming the workflow, the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osolmaz/pi-workflows",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"
@@ -20,6 +20,7 @@
   "files": [
     "dist",
     "src",
+    "skills",
     "examples",
     "docs",
     "README.md",
@@ -38,6 +39,10 @@
     "./controllers": {
       "types": "./dist/controllers/index.d.ts",
       "default": "./dist/controllers/index.js"
+    },
+    "./job-progress": {
+      "types": "./dist/job-progress/index.d.ts",
+      "default": "./dist/job-progress/index.js"
     }
   },
   "publishConfig": {
@@ -86,6 +91,9 @@
   "pi": {
     "extensions": [
       "./src/extension/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   }
 }

package/skills/monitor/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: monitor
+description: Use when the user asks to monitor, watch, track, or periodically check a running command, remote Job, CI run, deployment, publication, or other long-running objective. Starts the built-in Pi monitor workflow immediately in the current session and drives the objective autonomously, including routine recovery, until verified completion or a material blocker.
+compatibility: Requires Pi Workflows and the built-in monitor workflow.
+---
+
+# Monitor
+
+Use the built-in Pi `monitor` workflow as an autopilot for the requested objective. Monitoring is not passive status polling. The agent must maintain nominal operation, repair recoverable failures, resume durable work, and continue until the complete objective is verified or a material blocker makes safe continuation impossible.
+
+A monitor request authorizes routine operational actions that are necessary to preserve and finish the stated objective, subject to the conversation and repository approval boundaries. These actions can include restarting or resuming the same non-paid Job or process, repairing an exact operational configuration or storage-path error, retrying transient infrastructure failures, restoring a verified checkpoint, and replacing a failed physical attempt with the same immutable execution contract. Paid launches, resumes, retries, or replacements require the explicit approval described below. Monitoring does not authorize changing the objective, method, model, data source, production selection, or other consequential contract.
+
+## Prepare and start without delay
+
+As soon as the user invokes this skill:
+
+1. Read the current conversation, active plan, repository instructions, and applicable compute, runtime, credential, deployment, or publication skills.
+2. Preserve the exact objective, immutable execution contract, current identifiers, durable progress, cost already spent, approval ceilings, finish criteria, and known recovery rules in the workflow input. Write or update a durable plan or incident note first only when the work needs one for safe continuation.
+3. Make the workflow instructions faithful to what the user requested. Do not reduce an implementation or recovery objective to observation-only monitoring.
+4. Call `workflow` with `action: "start"` in the current Pi session without asking for another confirmation or waiting for a later turn.
+5. Let the first workflow check run immediately. Do not use Unified Exec sleeps, manual polling loops, a second scheduler, or a separate Pi session as a substitute.
+
+Do not finish the initiating turn before the workflow start call. If a safe contract cannot yet be written because a critical identifier or boundary is missing, gather it immediately when possible. Ask the user only when the missing decision is consequential and cannot be inferred safely.
+
+## Build the monitor contract
+
+Derive the workflow input from the full conversation:
+
+- `task`: State the complete objective, the exact current target and stable identifiers, authoritative status sources, durable progress and final-output surfaces, approved recovery actions, immutable boundaries, cost and credential rules, and required validation or downstream operations.
+- `everyMinutes`: Use the user's interval when present. Use `30` when the user gives no interval. The built-in workflow accepts intervals from 1 minute through 24 hours.
+- `stopWhen`: Infer verified completion from the full conversation. Describe completion of the complete objective, not only the end of one physical process. Also name material blockers that require human intervention.
+
+When the conversation gives no clear finish criterion, set `stopWhen` to `Stop only when the user explicitly asks to stop.` Do not use that fallback when a broader implementation, repair, publication, or deployment objective is clear from context.
+
+Do not invent a finite check count. Omit `maxChecks` unless the user explicitly requests one. The workflow host can apply its own safety upper bound. Disclose that bound if it appears.
+
+## Paid infrastructure authority
+
+A monitoring request does not grant spending approval or create a default spending ceiling. Before launching, resuming, retrying, or replacing paid work, load and follow the paid-compute, provider, Job-control, and runtime skills that apply. Present the required estimate and obtain explicit approval when those policies require it.
+
+After approval, preserve the exact method, hardware, concurrency, cumulative cost ceiling, and recovery assumptions in the monitor task. Continue only within that approved contract. Stop for a decision before new paid work when there is no applicable approval, when the ceiling would be exceeded, or when evidence invalidates an approved assumption.
+
+The monitor may use a credential only when the conversation or repository has already authorized that credential's source, destination, and purpose. It may reuse that authorization for retries and replacement attempts under the same objective. It must not discover unrelated credentials, broaden scopes, copy credentials to a new store, or print secret values.
+
+## Start the workflow
+
+Start the built-in workflow in the current session with this shape:
+
+```text
+workflow({
+  action: "start",
+  workflow: "monitor",
+  input: {
+    task: "<complete objective, contract, recovery authority, and verification task>",
+    everyMinutes: 30,
+    stopWhen: "<derived finish criterion or explicit-user-stop fallback>"
+  }
+})
+```
+
+Use the user-supplied interval instead of `30` when present. Add `maxChecks` only when the user explicitly supplies that limit. Do not send `reportWhen`; the current monitor reports every accepted check.
+
+Do not start a second monitor for the same objective while one is active. Update or replace the run only when the objective or contract changes. A replacement must preserve the previous accepted observation and durable recovery state.
+
+## Complete workflow checks
+
+Each workflow check arrives with an exact step contract. Apply only the operational authority recorded in `task`. The default monitor contract is recovery-capable autopilot within recorded approval boundaries, not authority to create new spending or change the objective.
+
+For each check:
+
+1. Query the target's authoritative status.
+2. Query durable progress and final-output surfaces. Run independent reads in parallel when useful.
+3. Compare the current values with the previous accepted observation.
+4. If operation is not nominal, preserve evidence, diagnose the issue, apply the smallest authorized repair, and verify that durable progress resumes. Fix issues and restart Jobs or processes when that is necessary to keep the same objective moving.
+5. Include a concise report for every accepted check. Report absolute totals and meaningful deltas when counters matter.
+6. Select `continue` or `stop` as required by the step contract.
+7. Call `workflow` with `action: "submit"` exactly once, using the supplied step and attempt IDs and the required output shape.
+
+The workflow sends each report as a Pi notification. Notifications do not start a new assistant turn. Do not add a separate assistant reply to a workflow notification.
+
+## Publish progress when measurable
+
+Progress is optional. Do not invent it for work that has no factual count, total, rate, or source estimate.
+
+When the target exposes measurable progress, include one or more tracks in the check output. Use a stable key for each independent process or workstream. Use `overall` for a real aggregate only; do not add unrelated tracks together.
+
+Each track uses `pi-workflows.progress.v1` and can include:
+
+- `status`: `pending`, `running`, `waiting`, `blocked`, `completed`, `failed`, `cancelled`, or `unknown`;
+- `label` and `phase` for short display text and estimation epochs;
+- `completed`, `total`, and `unit` for factual counts;
+- `sourceUpdatedAt` and `sourceEstimatedFinishAt` when the target provides its own fresh estimate.
+
+Submit observed facts. The workflow computes rates, confidence, remaining work, and measured ETA from durable samples. Do not guess a count, rate, or ETA. A changed phase, total, unit, or lower completed count starts a new estimation epoch.
+
+For several concurrent processes, publish one stable track per process. The Pi widget and viewers show them separately and keep each ETA independent.
+
+### Read durable job snapshots
+
+A remote job can advertise a `pi-workflows.job-progress.v1` snapshot with these immutable labels:
+
+- `progress_schema=pi-workflows.job-progress.v1`
+- `progress_bucket=<existing-bucket>`
+- `progress_prefix=<path-before-job-id>`
+
+When these labels exist, form `<progress_prefix>/<physical-job-id>/progress.json`, read it from the named existing store with an already authorized credential, and validate it with the installed `@osolmaz/pi-workflows/job-progress` API. Reject a snapshot whose job ID, source revision, or work-contract identity does not match the observed Job. Do not follow a path or credential named inside unvalidated data.
+
+Publish the snapshot tracks under stable keys. Preserve consecutive samples so the workflow can estimate ETA from measured progress. Treat a stale or missing snapshot as unavailable progress, not as proof that the Job stopped. Receipts, hashes, manifests, and final outputs remain the completion evidence.
+
+## Apply finish rules
+
+### Still active
+
+Continue. Keep reports short unless the state changed materially.
+
+### Completed
+
+Stop only after the inferred finish criterion is true. Verify required final artifacts, checksums, receipts, publication state, or downstream health before selecting `stop`.
+
+### Failed, stopped, or blocked
+
+Do not disarm the monitor for a superficial reason. One failed physical Job, command, CI run, deployment attempt, upload, or status read is not the end of the objective. Treat it as an operational event, preserve evidence and durable state, diagnose it, apply the smallest safe repair, restart or resume the same immutable contract, restore nominal operation, and keep monitoring.
+
+Examples of recoverable conditions include transient provider or network errors, platform eviction, rate limits, expired physical attempts, safe checkpoint reconciliation, exact path or configuration mistakes, bounded storage failures, and a stalled deployment that has a documented recovery action.
+
+Stop only for a material blocker, such as:
+
+- a deterministic shared code or data defect that makes further attempts unsafe;
+- an invalid, missing, or unverifiable checkpoint when useful state would be lost;
+- a required credential that has no prior source-and-destination authorization;
+- a changed model, method, source, hardware class, objective, or production decision;
+- a destructive or security-sensitive action outside the recorded authority;
+- a cost, time, or resource ceiling that cannot safely contain the remaining work;
+- evidence that the requested result cannot be made truthful or valid under the current contract.
+
+Never keep paid workers retrying a deterministic shared failure. Contain affected work, report the evidence and ETA impact, and stop for a decision.
+
+### Status unavailable
+
+Retry only a cheap, bounded status read. If the source remains unavailable, report the gap. Continue only when observation remains safe and the finish criterion is not met.
+
+## Check the right surfaces
+
+Depending on the target, inspect:
+
+- Process, Job, workflow, CI, or deployment status.
+- Durable receipts and counters.
+- Checkpoints or partial outputs.
+- Final manifests, databases, publications, or release artifacts.
+- Error state and the freshness of the last durable update.
+
+Logs and progress counters alone do not prove saved work or completion. Prefer durable artifacts and authoritative remote state.
+
+## Stop on user request
+
+When the user asks to stop, cancel the active monitor workflow with `workflow({ action: "cancel" })` and confirm that monitoring stopped. Do not wait for the next scheduled check.
+
+## Status format
+
+For an unchanged active target, prefer a compact report:
+
+```text
+Target remains running:
+- Progress: <absolute total> (<delta since last report>)
+- Cost or resource use: <total>
+- Durable output: <state>
+- Next check: <interval>
+```
+
+Explain anomalies, failures, or approval boundaries when they occur. Avoid repeating the full history at every check.