@carbon-ni/pi-schedule 0.0.0-stage → 0.1.0

package/DEVELOPMENT.md

@@ -0,0 +1,91 @@
+# Development
+
+## One command per lifecycle stage
+
+Use Node.js 22.18+ (Nix provides 24), npm 10.9.9, Git, and Pi 1.5.x. Use
+`nix develop` if Node is unavailable. If your npm differs, use
+`npx --yes npm@10.9.9 ci` before installing hooks.
+
+| Stage             | Command                                | Enforcement                                                       |
+| ----------------- | -------------------------------------- | ----------------------------------------------------------------- |
+| Discover commands | `make help`                            | Copyable local commands                                           |
+| Install           | `make setup`                           | Locked dependencies, install scripts disabled, versioned hooks    |
+| Verify hooks      | `make hooks-check`                     | Checks hook path and executability                                |
+| During work       | `fzz --log-file .tmp/funzzy/tests.log` | Same normal gate on changes                                       |
+| Normal gate       | `make check`                           | Pre-commit, pre-push, watcher, CI                                 |
+| Format            | `make format` / `make format-write`    | Explicit manual/release check                                     |
+| Coverage          | `make coverage`                        | Explicit budgets: 85% lines/functions, 75% branches               |
+| Security          | `make security`                        | Native dependency audit; high severity blocks                     |
+| Real Pi smoke     | `node scripts/smoke.mjs`               | Explicit isolated RPC test with local deterministic HTTP provider |
+| Release           | `make release-check`                   | Normal gate + format, coverage, audit, package dry run            |
+
+Coverage preloads every production module so newly added, unimported code does
+not disappear from the report. Keep module evaluation free of external effects;
+start resources through explicit lifecycle adapters.
+
+The normal gate is lint, typecheck, and deterministic tests only. Success prints
+exactly `true`. Failure prints `false` first, then at most 40 diagnostic lines.
+Hooks strip Git redirect variables so scratch repositories cannot touch the
+submodule index. Commit subjects follow Conventional Commits.
+
+CI invokes the same normal gate on main pushes and pull requests. Pushing a stable
+`v<version>` tag runs the release gate, then publishes `@carbon-ni/pi-schedule` to
+npm through trusted publishing. Tag creation is manual. See [releasing](docs/RELEASING.md)
+for initial npm setup, copyable release commands, and failure recovery.
+
+Review the package dry run before publishing. Pi is a host peer dependency;
+TypeBox is also host-provided. Development versions and direct tooling are
+pinned; the lockfile pins their dependency graph.
+
+## Definition of done
+
+- Behavior and failure paths have deterministic tests; use fake time, not sleeps.
+- The watcher normal gate passes for the current revision.
+- Coverage and audit pass for the changed scope; uncovered risk is recorded.
+- Runtime changes pass the explicit Pi smoke test; this uses no real credentials
+  and no user session. Human TUI review remains a separate check.
+- Formatting passes and docs describe actual behavior and recovery.
+- Commit/push the submodule before updating its parent pointer. Never amend.
+- Update TASK-0007 on the separate planning board when its criteria are met.
+
+## Boundaries and configuration
+
+Domain state transitions do not import infrastructure, Pi, TypeBox, or Node
+modules. ESLint enforces inward imports for production domain files. Changes to
+that rule require both a passing baseline and a forbidden-import probe that
+fails lint. Tests import external test helpers; they are not production layers.
+
+There is one versioned watcher config and one lint/type/test gate. Runtime
+defaults are defined in source; Pi's agent-directory default is overridden only
+by Pi's standard `PI_CODING_AGENT_DIR`. Budget changes use the manual command;
+there is no competing environment or JSON budget policy.
+
+`skipLibCheck` skips inconsistent third-party declaration internals, including
+Pi's generated JSON model declarations under NodeNext. Our source, fixtures,
+and integration calls remain strictly typechecked.
+
+## Do not
+
+- Do not use shell sleeps for scheduling, run a hidden daemon, steer active work,
+  or silently execute missed/uncertain tasks.
+- Do not reconstruct terminal scheduler state from an active history branch.
+- Do not let model parameters set creator, session ownership, root, or budget.
+- Do not claim that a submitted prompt proves a successful check.
+- Do not force-add runtime state, credentials, logs, or coverage output.
+- Do not bypass a failing implementation hook. Fix it and use the same gate as CI.
+
+## Failure → recovery
+
+- Dependencies unavailable → `npm ci` (network is required for installation).
+- Hooks absent → `make setup && make hooks-check`.
+- Format failure → `make format-write && make format`.
+- Type/lint/test failure → `make check`; read bounded diagnostics and run the
+  relevant individual command from `make help`.
+- Watcher unavailable → `fzz run -- @agent-final`; it uses the same normal gate.
+- Missing Pi → install Pi 1.5.x, then `make try`.
+- Runtime/storage/lock failure → use [security recovery](docs/SECURITY.md), then
+  `/reload`. Never delete an active process's lock.
+- Audit failure → `npm audit`; review advisories and pin a targeted correction.
+  Do not use `npm audit fix --force`.
+- Coverage failure → `make coverage`; add behavioral cases, not config-string
+  assertions or a lower threshold.

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# pi-schedule
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Schedule one-off follow-ups in your [Pi](https://pi.dev) conversation. Ask Pi to
+check CI later, or set a deadline yourself. Results appear in the same chat.
+
+**Keep the Pi session open and the computer awake.** There is no background
+service, recurring schedule, or automatic retry.
+
+## Install
+
+Requires Pi 1.5.x, Node.js 22.18+, and a persistent TUI or RPC session.
+Storage relies on Unix file permissions and filesystem behavior; use macOS or Linux.
+Pi extensions run with your user permissions, not in a sandbox.
+
+```sh
+git clone https://github.com/carbon-ni/pi-schedule.git
+cd pi-schedule
+npm ci
+pi install "$PWD"
+```
+
+Start Pi, or run `/reload` in an existing session. If the repository is already
+at `~/.pi/agent/extensions/pi-schedule`, Pi discovers it without `pi install`.
+
+After the first npm release, install without cloning:
+
+```sh
+pi install npm:@carbon-ni/pi-schedule
+```
+
+## Schedule a follow-up
+
+Ask Pi with an exact target and a clear scope:
+
+> In 30 minutes, check CI for owner/repo#123 and report failures. Do not modify code.
+
+Pi confirms the task ID, due time with timezone, target, and cancellation command.
+It can schedule further checks needed for the current request, with a reason for
+each check. A status check does not authorize code changes, pushes, or merges.
+
+To schedule without a model call, use `/schedule`:
+
+```text
+/schedule in 30m Check CI for owner/repo#123 and report failures; do not modify code
+/schedule at 2026-11-09T14:30:00+01:00 Check deployment status for owner/repo
+/schedule list
+```
+
+Use an explicit timezone offset for `at`. Replace `S-<id>` below with the ID from
+the confirmation or task list:
+
+```text
+/schedule show S-<id>
+/schedule cancel S-<id>
+/schedule help
+```
+
+Tasks wait while Pi is busy, messages are queued, or extension UI is blocking.
+They remain cancellable until dispatch starts. **Dispatched means Pi started the
+turn, not that the check succeeded.** Read the conversation for findings or blockers.
+
+## Recover missed work
+
+Closing Pi stops execution. Reloading or resuming keeps future tasks, but missed
+tasks become overdue. Sleep or forward-clock gaps over two minutes also require
+review; missed work does not run automatically.
+
+Inspect the saved request, then explicitly run overdue work when Pi is idle:
+
+```text
+/schedule show S-<id>
+/schedule run S-<id>
+```
+
+If dispatch is uncertain, inspect the conversation and any external effects first.
+Then acknowledge it without replay:
+
+```text
+/schedule dismiss S-<id>
+```
+
+Create a fresh task only if another check is needed. For storage or lock errors,
+follow [security and recovery](docs/SECURITY.md) before using `/reload`.
+
+Each confirmation includes `pi --session-id <id>` to resume from the same project.
+Use it if a task was scheduled before the first chat message: Pi creates session
+files lazily, so the session may not appear in the picker yet.
+
+## Control follow-up limits
+
+Agent-created checks share a default budget of **three checks within two hours**.
+Follow-ups cannot reset that budget or silently recreate a cancelled chain. A new
+explicit user request starts a new authorization scope.
+
+Only you can change a chain's total run limit and expiry from now:
+
+```text
+/schedule budget S-<id> 5 3h
+```
+
+An expired chain needs a budget extension before it can run. Maximum explicit
+budget: 20 checks within 24 hours. Each session allows 20 pending or overdue tasks,
+8 KiB per saved instruction, and 1,000 history records.
+
+For agent integrations, `schedule_task` supports `create`, `list`, `show`, and
+`cancel`. Creation requires an instruction, exact target, reason, and either
+`delay_seconds` or timezone-qualified `run_at`.
+
+## Local state
+
+Tasks stay in `~/.pi/agent/schedule/`, or `<PI_CODING_AGENT_DIR>/schedule/` when
+Pi's agent directory is overridden. There is no separate scheduler configuration.
+
+State files use mode 600; directories and locks use mode 700. Each session has one
+exclusive owner. Forked sessions get separate stores. Rewinding history does not
+restore cancelled or dispatched tasks. Corrupt state is retained for recovery;
+a write failure stops scheduling until reload.
+
+## Development
+
+See [development](DEVELOPMENT.md) for setup, isolated loading, and checks;
+[releasing](docs/RELEASING.md) for npm setup and publishing;
+[architecture](docs/ARCHITECTURE.md) for implementation boundaries;
+[security and recovery](docs/SECURITY.md) for permissions and failure handling;
+and [design baseline](docs/PLAN.md) for the original requirements.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,59 @@
+# Architecture
+
+## Ownership
+
+```text
+src/index.ts                  Pi package entrypoint
+  └─ src/infra/extension.ts    Pi lifecycle, commands/tools, UI, timer wiring
+       ├─ src/cli/             Manual command parsing
+       ├─ src/lib/             Shared task presentation and output bounds
+       ├─ src/application/     Runtime orchestration and Store boundary
+       │    └─ src/domain/    Pure task/chain state transitions
+       └─ src/infra/          FileStore, lock ownership, state decoding
+            └─ domain types
+fixtures/                     Isolated smoke-test controls, never auto-loaded
+scripts/                      Gates, hooks, native-test discovery, RPC smoke
+docs/                         Design, architecture, security contracts
+```
+
+Tests are colocated with their subject. Add a shared helper to `src/lib` only
+when it has a real shared responsibility. Do not add workflow-engine or service
+layers for a one-session capability.
+
+## Dependency direction
+
+The domain owns tasks, chains, and transitions. It has no infrastructure imports.
+The application owns timing policy, trusted parent association, and the Store
+interface. Infrastructure implements that interface and validates JSON before
+passing state inward. The Pi adapter composes the runtime with the file store
+and translates host events, user commands, and tool calls. Presentation depends
+only on domain values. CLI parsing has no runtime dependencies.
+
+## Creation and delivery
+
+1. CLI parsing or the tool adapter provides a saved instruction and deadline.
+   The entrypoint assigns creator/session/project; the runtime assigns a trusted
+   chain root and parent.
+2. Pure transitions validate and produce a new snapshot. FileStore validates
+   schema and graph invariants, writes a private temporary file, fsyncs it,
+   atomically renames, then fsyncs the directory. Only then acknowledge creation.
+3. The timer asks the runtime to evaluate UTC deadlines. Host idle, queue, and
+   blocking-UI checks gate dispatch. Due tasks remain cancellable in our store.
+4. Persist uncertain dispatch intent before calling Pi. Only Pi's matching
+   `before_agent_start` event acknowledges the scheduled turn. An asynchronous
+   send failure leaves uncertainty instead of a false success or automatic retry.
+5. A scheduled turn binds descendants to its persisted chain. Only a new explicit
+   human-input run clears that association; an agent cannot omit its parent to
+   acquire a fresh budget.
+
+## Why not session entries?
+
+Pi histories can branch or fork, while cancellation and dispatch tombstones must
+not rewind. Session entries also do not provide exclusive cross-process ownership.
+The authoritative state is therefore one per-session sidecar plus an exclusive
+lock, not a branch projection or duplicated session ledger. Forks have different
+session IDs and do not inherit runnable work.
+
+Pi can delay writing a new session file until chat starts. Scheduler state is
+still durable; confirmations include `pi --session-id <id>` for explicit resume.
+No task runs in another conversation merely because the project path matches.

package/docs/PLAN.md

@@ -0,0 +1,84 @@
+# Scheduling design baseline
+
+> Original design for TASK-0007, captured 2026-11-08. This is not the task board.
+> README and DEVELOPMENT describe implemented behavior and verification; the
+> historical criteria below preserve the design intent, not live progress.
+
+## Problem
+
+Waiting for CI, deployments, or another external operation requires the user to remember to return and ask Pi to check again. Long-running shell sleeps hide this intent, occupy execution, and cannot provide reliable listing, cancellation, or recovery.
+
+## Decision
+
+Build `pi-schedule`, a Pi extension for one-off follow-ups in the original session. The user explicitly selected session-open execution as the MVP. This is a plan, not an active schedule.
+
+Example: “In 30 minutes check CI again.” Pi resolves the relevant repository and PR, records the action, and confirms its ID and exact local due time with timezone. At the due time it initiates a normal Pi turn in that session. Scheduling must not merely display a reminder.
+
+No daemon, cron, external service, spawned Pi process, recurring schedules, worktrees, or cross-session delivery in v1. No intray dependency: this runs inside the target session.
+
+## Reference
+
+[Codex scheduled tasks](https://developers.openai.com/codex/app/automations), accessed 2026-11-08, documents in-chat scheduling, standalone runs, reviewable results, and the requirement to keep the computer and app running for local projects. Borrow explicit action + schedule + destination + visible result, not its full automation platform. The current page is titled “Scheduled tasks | ChatGPT Learn”; product naming has changed.
+
+## User contract
+
+- Natural language is interpreted by the agent into structured tool input. The scheduler validates inputs deterministically; it does not use an LLM to decide whether work is due.
+- Both manual and agent-initiated scheduling are first-class. The user may schedule directly through a command or natural language. The agent may schedule a follow-up without asking each time when it is necessary to finish the current authorized task (e.g. CI is still running). This is not permission to invent unrelated monitoring or new work.
+- Agent-created tasks must visibly explain why a follow-up is needed, show their due time and target, and remain listable/cancellable. User cancellation stops that follow-up chain; the agent must not silently recreate it. Scheduling does not extend the original action permissions.
+- Bound agent follow-up chains with a root task ID, remaining run budget, and expiry shared by every descendant. Proposed default: at most three agent-initiated checks within two hours per root task; the user can explicitly change the budget. Each scheduled check consumes one run; reaching a limit reports the unresolved state and asks the user rather than resetting the budget. A pending-count cap alone is not sufficient.
+- Tools: `schedule_task` with create/list/cancel actions. Create takes an explicit instruction and exactly one of positive integer `delay_seconds` or timezone-qualified `run_at`. Return ID, due time, resolved scope, and execution limitation.
+- `/schedule in 30m <instruction>` and `/schedule at <ISO-8601-with-offset> <instruction>` create tasks directly without an LLM round trip. `/schedule help`, `/schedule list`, `/schedule cancel <id>`, and `/schedule run <id>` provide discovery, inspection, cancellation, and explicit overdue recovery. Natural-language cancellation uses the same application logic. Repeating run/cancel cannot dispatch twice.
+- Support “in 30 minutes” first. Absolute dates require an explicit offset; ask about ambiguous time or target rather than guess. Resolve relative duration against an injected clock at successful creation, not model request start.
+- Save a durable instruction: e.g. check CI for `owner/repo` PR 123 and report status/failures. Do not save only “check that again.” Resolve repo/PR identity before create; omit credentials and unnecessary transcript text.
+- Confirmation: “Scheduled S-123 for <date/time/timezone> (in 30 minutes): check CI for owner/repo#123. Runs only while this Pi session is open and computer is awake.”
+- Current permissions and instructions still apply at execution. “Check CI” does not authorize fixing code, pushing, merging, or cancelling workflow runs. Report blockers; never silently grant access.
+- Show pending count/next due time and visible task lifecycle records. Distinguish scheduled, due/waiting, dispatched, cancelled, overdue, and uncertain. Do not claim a check succeeded merely because a prompt was submitted.
+
+## Timing and lifecycle
+
+1. Persist creation before acknowledging it; timer is only a wake-up mechanism. Compare absolute UTC deadlines on every wake, with bounded periodic rechecks to handle clock changes and sleep.
+2. Dispatch only when the original session is idle, with no pre-existing queued user work. Recheck eligibility immediately before dispatch. Keep due work in the scheduler until then so cancellation remains meaningful; do not insert uncancellable messages behind an active turn.
+3. Order simultaneous due tasks by due time then stable ID. Run one at a time and recheck session/user queue state between runs. Use non-steering delivery defensively; verify actual Pi queue semantics in a spike before implementation.
+4. Define a two-minute lateness grace for ordinary event-loop delay. A task delayed beyond that without an observed continuous busy-session wait becomes overdue (e.g. sleep or large forward clock jump). Never run early after a backward clock change. Make this policy explicit in help.
+5. Clean up timers on every session shutdown, including reload/new/resume/fork. Restore pending tasks on reload/resume of the same session. If a restored deadline has passed, mark overdue and require `/schedule run <id>`; do not execute a surprise catch-up.
+6. Session replacement never redirects a task to the new conversation. Forks do not inherit runnable tasks; branch navigation does not resurrect dispatched or cancelled tasks. Verify session ID and history behavior against the installed Pi API.
+7. Mark dispatch intent durably before calling Pi. A crash between persistence and delivery is uncertain: show it and require explicit recovery, never automatically replay. Do not promise exactly-once external effects. Concurrent opens of the same session must fail closed for scheduling unless exclusive ownership is proven.
+8. Closing Pi stops execution. Starting another session does not run old tasks. Pending records remain available when the original session is resumed. The feature cannot wake a sleeping computer.
+
+## Design
+
+Keep changes under `pi/agent/extensions/pi-schedule/`, following nearby package conventions and current `@earendil-works/*` imports.
+
+Separate deterministic task validation/state transitions from Pi lifecycle and tool/command adapters. Inject clock, timer, persistence, and delivery at the boundary; avoid building a generic workflow framework.
+
+Proposed record: schema version, task ID, owning session ID, project path and resolved target, instruction, creator (`user` or `agent`), scheduling reason, root/parent task IDs, shared follow-up budget and expiry, created/due timestamps, state, lifecycle timestamps, and failure/uncertainty reason. Creator attribution must come from the command/tool entry point, not a model-supplied authority claim. Explicit user changes to autonomous budgets need a user-controlled command or equivalent verified input; the agent cannot grant itself a larger budget. Limit instruction length and pending count (proposed 8 KiB and 20 per session). Validate persisted records; malformed state disables affected tasks with a visible error rather than silently discarding them.
+
+First investigate whether session custom entries (`pi.appendEntry`) can provide authoritative lifecycle reconstruction across branches and exclusive ownership. They already persist extension data outside model context. Use them if guarantees hold; otherwise use a small private per-session store with atomic writes and an exclusive lock. Choose one source of truth, document retention/deletion and permissions, and do not create a second shadow ledger. Cancelled/dispatched tombstones must not vanish on branch rewind.
+
+Pi integration evidence: `pi.sendUserMessage` initiates a turn when idle and supports `deliverAs: "followUp"` while streaming. `session_start`/`session_shutdown` cover reload and session replacement. Existing `pi-auto` exercises queued messages; `pi-intray` handles cross-process messages but is unnecessary here. Exact API behavior and compatibility must be checked before implementation; no harness changes are proposed.
+
+## Delivery plan (test first)
+
+1. **Prove the boundary:** inspect current Pi docs/examples in full as needed; spike idle/queued-user semantics, session identity, forks, persistence replay, and duplicate session ownership. Finalize storage and delivery policy before coding the scheduler.
+2. **Implement deterministic core:** fake-clock tests first for validation, due ordering, cancellation, state transitions, overdue classification, and crash recovery. Add persistence adapter and ownership handling.
+3. **Wire Pi:** expose tools/commands, lifecycle cleanup, idle dispatch, and visible task state. Test adapters with fake Pi events; include integration checks for session replacement and reload.
+4. **Verify user flow:** short real-session timer checks CI in the same conversation; cancel prevents dispatch; active work is not interrupted; close/resume yields an overdue task without execution. Document help, prerequisites, recovery commands, storage, and limitations.
+
+## Acceptance criteria
+
+- [ ] Direct manual commands and natural-language requests create durable tasks through the same validated scheduling logic, with resolved target and exact due-time confirmation; no shell sleep or background process.
+- [ ] The agent can schedule a necessary follow-up to the current task without per-task approval, with visible reason and creator attribution; unrelated work remains outside scope.
+- [ ] Agent-created follow-ups share a bounded run budget and expiry across descendants. Cancellation, exhausted budget, and expiry prevent silent recreation; tests cover both allowed follow-ups and rejected scope/budget expansion.
+- [ ] An open, awake, idle session runs the specified check at/after due time and returns an ordinary reviewable response in the original conversation.
+- [ ] Busy-session work and queued user messages take priority; cancel remains effective until dispatch begins.
+- [ ] List/cancel/help/explicit-overdue-run work without relying on natural-language inference; invalid/past/ambiguous inputs have actionable errors.
+- [ ] Close, reload, resume, sleep, clock jumps, session replacement, forks, branch rewind, corrupted persistence, and duplicate ownership follow the stated policy.
+- [ ] Crash windows are reported as uncertain; no silent retry and no exactly-once claim.
+- [ ] Task text is treated as stored user-request data, not system authority; untrusted CI output cannot create further schedules or expand authorization.
+- [ ] Tests cover happy and failure paths with fake time and fake delivery; no wall-clock waits or live network dependencies in automated tests.
+- [ ] Localized coverage is measured for validation/state transitions and lifecycle adapters; record uncovered risk rather than use source-string tests as coverage.
+- [ ] Manual short-timer smoke check and focused regression checks pass; no full repository check is required for planning.
+
+## Future scope (not committed)
+
+General recurring schedules beyond bounded current-task follow-ups; standalone/background execution; results inbox; OS notifications. Each requires its own lifecycle and authorization design.

package/docs/RELEASING.md

@@ -0,0 +1,105 @@
+# Publish to npm
+
+Package: `@carbon-ni/pi-schedule`.
+Repository: `carbon-ni/pi-schedule`.
+
+Pushing a stable `v<version>` tag starts `.github/workflows/release.yml`.
+The workflow requires the tagged commit to be in `main` history and the tag to
+match `package.json`. It runs the release gate before publishing with npm trusted
+publishing (OIDC). No npm write token is stored in GitHub.
+
+Only stable releases are supported. Prerelease tags are rejected rather than
+published as `latest`.
+
+## One-time setup
+
+You need publish access to the `@carbon-ni` npm scope and admin access to the
+GitHub repository. The npm scope and GitHub owner do not need to have the same name.
+
+1. In GitHub, create an environment named `npm`. Add required reviewers if your
+   plan supports them, and restrict deployment tags to `v*`. Protect release tags
+   with a repository ruleset so only release maintainers can create them.
+2. If the npm package does not exist yet, perform the first publish locally as
+   shown below. Trusted publishing is configured in an existing package's settings.
+3. In the npm package settings, add a GitHub Actions trusted publisher:
+
+   | Field                | Value                      |
+   | -------------------- | -------------------------- |
+   | Organization or user | `carbon-ni`                |
+   | Repository           | `pi-schedule`              |
+   | Workflow filename    | `release.yml`              |
+   | Environment name     | `npm`                      |
+   | Allowed actions      | Allow direct `npm publish` |
+
+4. Complete an automated release within two days of creating the trusted
+   publisher. An unused configuration expires; delete and recreate it if needed.
+5. After the first automated publish succeeds, select npm publishing access
+   **Require two-factor authentication and disallow tokens**. No `NPM_TOKEN`
+   secret is needed.
+
+### First publish only
+
+Run from a clean, reviewed checkout of `main`, after the release-process changes
+have been pushed. Check scope access with your npm account; a registry 404 does
+not prove you have permission to publish.
+
+```sh
+npm ci
+make release-check
+node scripts/release.mjs "v$(node -p "require('./package.json').version")"
+npm login --registry=https://registry.npmjs.org/
+npm publish --ignore-scripts
+```
+
+The first publish uses interactive npm authentication and any required 2FA.
+It does not get GitHub Actions provenance. Later CI releases do.
+Do not push a tag for this already-published version: the workflow would attempt
+to publish it again. Configure the trusted publisher, then use the next patch
+version for the first automated release.
+
+## Release a new version
+
+Start with a clean `main` checkout. Keep npm 10.9.9 for local development.
+`npm version` changes both manifests and creates a new commit and tag; it does
+not publish. Replace `patch` with `minor` or `major` when appropriate.
+
+```sh
+git switch main
+git pull --ff-only
+npm ci
+make release-check
+npm version patch -m "chore(release): %s"
+node scripts/release.mjs "v$(node -p "require('./package.json').version")"
+git push origin main
+git push origin "v$(node -p "require('./package.json').version")"
+```
+
+Approve the `npm` environment deployment if review is enabled. The workflow uses
+npm 10.9.9 for verification and pinned npm 11.6.2 for OIDC publishing only.
+It publishes public TypeScript sources and docs, without tests or development
+tooling. There is no build step; Pi loads the TypeScript extension directly.
+
+Check the workflow and registry after publication:
+
+```sh
+gh run list --workflow release.yml --limit 5
+npm view @carbon-ni/pi-schedule version dist-tags --json
+pi install npm:@carbon-ni/pi-schedule
+```
+
+## Recover a failed release
+
+- **Verification failed:** fix the cause on `main` and create a new version.
+  Do not move or replace a published release tag.
+- **Authentication failed:** compare every trusted-publisher field above,
+  including the environment name and permission for direct publishing. Recreate
+  expired publisher configurations, then rerun the failed publish job with
+  `gh run rerun <run-id> --failed`.
+- **Publish result uncertain:** inspect the workflow and run
+  `npm view @carbon-ni/pi-schedule@<version> version`. If it exists, do not retry
+  publishing it. If it is absent and the cause is resolved, rerun the failed job.
+- **Version already exists:** npm versions are immutable. Use `npm version patch`
+  and follow the release steps again; never unpublish to make a retry succeed.
+
+See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) for
+provider requirements and troubleshooting.

package/docs/SECURITY.md

@@ -0,0 +1,77 @@
+# Security and recovery
+
+## Trust boundaries
+
+Pi extensions execute with user permissions. This scheduler is not a sandbox,
+and it does not prevent a malicious extension or another process running as the
+same user from modifying files or invoking commands.
+
+The tool schema accepts action, instruction, target, reason, deadline, and ID.
+It does not accept creator, project path, session identity, root/parent, or budget.
+The Pi adapter assigns those at trusted entrypoints. Agent-created roots remain
+associated with the current request across reloads; scheduled turns bind the
+actual dispatched parent, so omitting a model-supplied parent cannot reset limits.
+
+Checking CI does not grant permission to fix, push, merge, cancel jobs, or start
+unrelated monitoring. The scheduled prompt and tool guidelines preserve this
+boundary. Scope matching and scheduling reasons are not proof of user intent;
+semantic authorization still depends on the agent obeying current instructions.
+Untrusted CI output is data, not a new scheduling authorization.
+
+## Assets and controls
+
+- Saved instructions may contain private project details. State stays local;
+  do not include credentials or unnecessary transcript content.
+- Directory and lock modes are 700; snapshots are 600. Final directory/file
+  symlinks and non-private files are rejected. Parent paths belong to trusted Pi
+  configuration. Atomic writes do not follow a supplied state-file symlink.
+- A session has one exclusive owner. No automatic stale-lock deletion or replay.
+- JSON schema, task/chain relationships, session/project identity, text bounds,
+  history counts, and budgets are validated before restored state can run.
+- A write failure stops scheduling until reload. A crash after a write but
+  before delivery is uncertain; exactly-once external effects are not promised.
+- Task summaries escape control characters; tool output is bounded to 50 KiB
+  with a truncation notice. All active work appears before terminal history.
+- No credentials, telemetry, external scheduler, or additional third-party
+  service is used. The model handling a scheduled turn sees its saved request
+  under the user's existing Pi provider settings.
+
+## Lock and corruption recovery
+
+Start with the exact path printed in the runtime error. The lock contains
+`owner.json` with PID/token; the corresponding JSON snapshot is authoritative.
+
+1. Close the other Pi session normally; reload this one.
+2. After a crash, inspect `owner.json` and verify its PID no longer exists.
+   For example, `ps -p <pid> -o pid=,command=` (PID reuse is possible, so inspect
+   the process, not only whether a PID exists).
+3. Only after verifying no live owner, remove that lock's `owner.json` using
+   `rm -- <lock-path>/owner.json`, then `rmdir -- <lock-path>`, then `/reload`.
+   Do not remove a lock just to silence an error.
+4. For corrupt JSON, stop the owner and retain a private backup. Restore a known
+   good snapshot or explicitly discard the affected session's schedules. The
+   extension never overwrites corrupt data with an empty state automatically.
+
+Uncertain work: `/schedule show <id>`, inspect the conversation/external effects,
+then `/schedule dismiss <id>` without replay. If a new check is needed, create it
+explicitly after inspection.
+
+## Retention and deletion
+
+History and cancellation/dispatch tombstones remain for the session's lifetime
+(up to 1,000 records). No automatic pruning or transcript export occurs. Cancel
+pending work before closing the session. To delete saved instructions, close its
+owner and delete the corresponding JSON snapshot after checking its task/session
+IDs. Do not delete active snapshots or tombstones to reset agent limits.
+
+The Pi agent directory may be a symlink into a config repository. That repository
+must ignore its `schedule/` directory, just as it ignores session/auth data.
+This parent checkout explicitly ignores `pi/agent/schedule/`.
+
+## Supply chain
+
+Direct development dependencies are exact-pinned; npm's lockfile pins transitives.
+Install scripts are disabled. Host Pi and TypeBox are peer dependencies, not a
+second bundled runtime. `make security` audits the full installed graph.
+The minimatch 11.0.4 override addresses GHSA-g3hv-75wg-m249 in lint dependencies;
+remove it only when upstream constraints require patched versions.

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@carbon-ni/pi-schedule",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carbon-ni/pi-schedule.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "scheduler"
+  ],
+  "type": "module",
+  "description": "Session-scoped scheduled follow-ups for Pi",
+  "packageManager": "npm@10.9.9",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "README.md",
+    "DEVELOPMENT.md",
+    "docs"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=1.5.0 <2",
+    "typebox": "1.3.15"
+  },
+  "overrides": {
+    "minimatch": "11.0.4"
+  },
+  "scripts": {
+    "test": "node scripts/test.mjs",
+    "test:coverage": "node scripts/test.mjs --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --check .",
+    "format:write": "prettier --write .",
+    "check": "sh scripts/gate.sh"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.5.0",
+    "@eslint/js": "10.0.1",
+    "@types/node": "22.20.5",
+    "eslint": "10.8.1",
+    "globals": "17.11.0",
+    "prettier": "3.9.6",
+    "typebox": "1.3.15",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.67.0"
+  }
+}