@canhta/dsh-autopilot 0.1.0-alpha.1

package/AGENTS.md

@@ -0,0 +1,41 @@
+# Engineering instructions
+
+Read the relevant GitHub issue and [documentation map](docs/README.md) before work. Keep this plugin repository's rules separate from those of repositories Autopilot modifies. `CLAUDE.md` links to this file; edit this source only.
+
+## Implementation discipline
+
+- Continue work on the checked-out branch and deliver commits there. Create or switch to a feature branch, and open a pull request, only when the user explicitly requests that action.
+- Build the approved requirement; actively look for native capabilities that improve its reliability, usability or execution quality. Apply improvements within that behavior; propose material product changes on GitHub with evidence, benefit, cost and acceptance criteria. YAGNI limits speculative implementation, not discovery or proposals. Search the codebase first and reuse an existing implementation.
+- Autopilot is a DSH plugin. Before implementing a capability, inspect supported DSH services, plugins, presets and extension points; reuse or compose them. Implement only missing Autopilot behavior, not a replacement agent loop, Session store, credential system or Web shell. Verify suitability against current source/docs; surface a missing extension instead of silently rebuilding the harness.
+- Before adding code, check in order: standard library, native platform capability, then installed dependencies. Use the first suitable maintained option; write only the missing behavior.
+- Prefer the smallest readable implementation. Keep a one-line solution when it is clear; do not compress code at the cost of comprehension or add speculative abstractions.
+- Organize modules by responsibility and cohesion, not line-count targets. Keep a long file when it owns one clear role behind a deep interface; split when it mixes reasons to change, exposes internal detail, duplicates behavior or couples unrelated callers. Do not create mechanical fragments solely to satisfy a size threshold.
+- Let names, types and structure explain the code. Add brief comments only for non-obvious intent, constraints or failure behavior; do not narrate the code or repeat it in JSDoc. Preserve documentation required by an actual public interface or toolchain.
+- Deliver production-ready behavior: validate external inputs, propagate actionable failures, own resource cleanup, protect secrets and verify relevant behavior. Do not present stubs, happy-path demos or unverified integrations as finished features.
+- Maintain one authoritative implementation. Update affected callers and tests together; do not add parallel versions, compatibility shims or legacy modes. If a real external compatibility obligation or durable-data migration conflicts with this rule, raise it on the GitHub issue before changing or discarding data.
+- Fix a discovered bug in the current task when its cause is clear and the correction is small, safe and verifiable; include a regression test. For larger or independently scoped bugs, search for an existing GitHub issue, then create or update one with evidence, impact, reproduction and acceptance criteria. Link the current task and add a blocking dependency when necessary. Reporting a bug only in chat or leaving it untracked is insufficient; distinguish suspected from reproduced failures.
+- Keep tests risk-based and high-signal. Update affected tests and add the smallest regression, boundary or integration case that proves a real behavior, security or lifecycle contract; each test must identify the failure it prevents. Remove superseded fixtures with their implementation, prefer shared conformance coverage over duplicate vendor cases, and keep suites bounded and fast. Coverage percentage alone does not justify a test.
+
+## Integration and documentation
+
+Verify DSH interfaces against the pinned dependency and current upstream source; conceptual spec interfaces are not existing APIs. Keep vendor logic in provider plugins and use the shared Host policy for Web commands. Read the relevant stable specs through the documentation map.
+
+When implementing or reviewing Host services, Client UI, lifecycle, persistence, public APIs or tests, follow [plugin engineering standards](docs/engineering.md). They adapt DSH's practices to this external plugin; upstream monorepo conventions do not automatically become this repository's policy.
+
+Each rule has one public documentation owner. Keep reusable behavior in specs; record work progress, open questions, review findings and test results on GitHub. Never commit credentials, live ticket content, runtime worktrees or execution transcripts. Report only verification actually performed.
+
+Local upstream research lives in `docs/research/`. Agents may read and update it to verify DSH behavior, but it is intentionally excluded from Git and npm and public tracked documents must not link to it. Do not delete this directory merely because Git reports it as ignored. Before shipping a durable fact learned there, record the cited upstream version in the owning spec, ADR or GitHub issue so a clean checkout remains self-contained. If the local directory is absent, inspect the pinned dependency and current upstream source directly.
+
+## Agent skills
+
+### Issue tracker
+
+Development work and progress live in GitHub Issues for `canhta/dsh-autopilot`; see [tracker conventions](docs/agents/issue-tracker.md).
+
+### Triage labels
+
+Use the five configured triage roles; see [label mapping](docs/agents/triage-labels.md).
+
+### Domain docs
+
+Single-context: root `CONTEXT.md` and relevant accepted decisions in `docs/adr/`; see [domain reading rules](docs/agents/domain.md).

package/CONTEXT.md

@@ -0,0 +1,39 @@
+# Autopilot language
+
+Vocabulary for coordinating tracker-approved development through DSH.
+
+## Work and systems
+
+
+**Plugin repository**: The codebase that develops Autopilot itself.
+
+**Target repository**: The codebase modified by an Autopilot execution. Avoid using “repo” when either repository could be meant.
+
+**Project scope**: The one configured tracker project from which Autopilot admits work; team/workspace context depends on the tracker.
+
+**Tracker provider**: An integration that supplies issue context and applies execution reports to the issue system.
+
+**Code-host provider**: An integration that publishes pull requests and resolves their disposition.
+
+**Provider binding**: A selected provider implementation and configured connection identity, excluding secret values.
+
+**Agent Brief**: The designated tracker comment defining approved scope, constraints and acceptance criteria.
+
+## Execution
+
+
+**Run**: One admitted ticket execution, including its continuation history. Avoid “task” when referring specifically to this execution record rather than the tracker issue.
+
+**Attempt**: An execution interval within a run; resumption is not a new run.
+
+**Session**: DSH-owned execution history associated with a run.
+
+**Checkpoint**: Continuation information recorded after execution becomes quiescent, not a frozen operating-system process.
+
+**Managed worktree**: The Git working directory allocated to an Autopilot run.
+
+**Human blocker**: A question or condition requiring a human tracker decision before work continues.
+
+**Operational pause**: A resumable stop caused by scheduling, operator hold or spending policy; distinct from a human blocker.
+
+**Completed run**: A run whose PR publication has been confirmed; delivery and PR review may still be pending.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 canhta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+![Autopilot — Turn approved work into review-ready pull requests with DeepSeek Harness.](docs/assets/banner.png)
+
+# Autopilot
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-78dba9?style=flat-square)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/canhta/dsh-autopilot/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/canhta/dsh-autopilot/actions/workflows/ci.yml)
+[![Status: alpha](https://img.shields.io/badge/status-alpha-d8b46a?style=flat-square)](https://github.com/canhta/dsh-autopilot/releases)
+[![Built for DeepSeek Harness](https://img.shields.io/badge/built_for-DeepSeek_Harness-6fa8dc?style=flat-square)](https://github.com/deepseek-ai/deepseek-harness)
+
+Autopilot turns approved tracker work into bounded agent runs and review-ready pull requests inside [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH).
+
+## What problem it solves
+
+Running a coding agent is easy. Operating one continuously is harder: somebody still has to decide which ticket is ready, track reported token use, limit concurrency, recover interrupted work, publish the exact verified commit and tell the team what happened.
+
+Autopilot adds that operational layer to DSH. It keeps approval, review and merge with humans while automating the work between an approved ticket and a pull request.
+
+It does not replace DSH or vendor integrations. DSH owns the agent runtime, Sessions, credentials and Web shell. Tracker and code-host access reuses official MCP servers and their existing authentication; Autopilot adds only the scheduling, lifecycle and publication behavior that joins them together.
+
+## What it does
+
+- Admits only tickets carrying the configured ready marker and current human authorization.
+- Queues work under schedule and concurrency limits, reserving a configured allowance against provider-reported token use.
+- Runs the repository's own instructions in a managed Git worktree through DSH.
+- Pauses, resumes and cancels without discarding durable run history.
+- Recovers interrupted publication, notifications and retained worktrees after restart.
+- Revalidates the exact Git state before creating a pull request.
+- Shows queue, run details, worktrees, delivery status and settings in DSH Web.
+- Stops at pull-request creation; humans still own review, CI decisions and merge.
+
+The contributor test suite verifies the current alpha with controlled providers. Production provider promotion remains gated by [provider conformance](https://github.com/canhta/dsh-autopilot/issues/4). Jira, GitHub Issues and GitHub code hosting are the first adapters; Linear, Bitbucket and later providers use the same provider contracts and MCP-first authentication policy.
+
+The alpha budget fields reserve capacity and reconcile provider-reported usage after requests. They are not an exact cumulative pre-request hard cap; keep native execution disabled for metered production until [the DSH budget boundary](https://github.com/canhta/dsh-autopilot/issues/5) is completed.
+
+## How it works
+
+```mermaid
+flowchart LR
+    ticket["Approved ticket"] --> gate["Ready marker + authorization"]
+    gate --> queue["Schedule + capacity + budget"]
+    queue --> dsh["DSH agent in managed worktree"]
+    dsh --> verify["Checks + exact Git state"]
+    verify --> pr["Review-ready pull request"]
+    pr -.-> notify["Notification"]
+```
+
+If the agent needs a decision, Autopilot posts the blocker back to the tracker and waits for an explicit response. A paused run retains its Session and worktree for a checked resume. A cancelled queued or quiescent run stops cleanly while retaining the evidence needed to understand what happened.
+
+Provider failures are isolated from the durable run result. For example, a notification outage cannot undo a completed pull request, and a restart can retry an uncertain publication without creating a duplicate.
+
+## Install
+
+Requires an existing DSH installation.
+
+```sh
+dsh plugin --profile web add https://github.com/canhta/dsh-autopilot/releases/download/v0.1.0-alpha.1/canhta-dsh-autopilot-0.1.0-alpha.1.tgz
+dsh --profile web
+```
+
+Open the URL printed by DSH, then select **Autopilot** in the sidebar.
+
+<details>
+<summary>Don't have DSH installed?</summary>
+
+Install its CLI with npm, then run DSH Web once to finish the normal DSH setup:
+
+```sh
+npm install --global @deepseek-ai/dsh
+dsh web
+```
+
+See the [DSH repository](https://github.com/deepseek-ai/deepseek-harness) for its own installation and safety guidance. Autopilot does not manage or upgrade this installation.
+
+</details>
+
+## Configure
+
+Open **Settings → Autopilot** to set the tracker and code-host bindings, schedule, concurrency, budget, notifications and retention policy. Configure the ready marker and provider-specific resource mapping in that provider's linked Settings section.
+
+Fresh installs keep execution disabled. Before enabling it, select the DSH default Agent preset and model, then configure each provider's DSH Settings namespace and official MCP server in the same profile. Keep vendor OAuth, model keys and tokens in DSH Credentials; Autopilot does not create a second authentication flow.
+
+For a systemd-managed VPS installation and backup/restore procedure, see [One-VPS operation](docs/deployment.md).
+
+## Contribute
+
+Start with a [GitHub issue](https://github.com/canhta/dsh-autopilot/issues) so the problem and acceptance criteria are clear. Then run the repository checks before opening a focused pull request:
+
+```sh
+git clone https://github.com/canhta/dsh-autopilot.git
+cd dsh-autopilot
+pnpm install
+pnpm run check
+```
+
+The full contribution workflow, verification expectations and package checks are in [Contributing](docs/CONTRIBUTING.md).

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+- insert:
+    - id: autopilot
+      name: "@canhta/dsh-autopilot"
+    - id: autopilot-jira
+      name: "@canhta/dsh-autopilot/jira"
+    - id: autopilot-github-issues
+      name: "@canhta/dsh-autopilot/github-issues"
+    - id: autopilot-github-code-host
+      name: "@canhta/dsh-autopilot/github-code-host"
+    - id: autopilot-webhook-notification
+      name: "@canhta/dsh-autopilot/webhook-notification"
+    - id: autopilot-ntfy-notification
+      name: "@canhta/dsh-autopilot/ntfy-notification"

package/deploy/dsh-autopilot.service

@@ -0,0 +1,26 @@
+[Unit]
+Description=DSH Autopilot Host
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=dsh-autopilot
+Group=dsh-autopilot
+WorkingDirectory=/var/lib/dsh-autopilot/package
+Environment=DSH_HOME=/var/lib/dsh
+Environment=PATH=/usr/local/bin:/usr/bin:/bin
+ExecStart=/usr/bin/env dsh --profile autopilot --host 127.0.0.1 --port 14500 --no-open
+Restart=on-failure
+RestartSec=10s
+TimeoutStopSec=5min
+KillMode=control-group
+UMask=0077
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectHome=true
+ProtectSystem=strict
+ReadWritePaths=/var/lib/dsh /var/lib/dsh-autopilot /srv/autopilot-target
+
+[Install]
+WantedBy=multi-user.target

package/docs/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to dsh-autopilot
+
+Start with a [GitHub issue](https://github.com/canhta/dsh-autopilot/issues). Documentation corrections can go straight to a focused PR; for implementation or design changes, agree on scope and acceptance criteria before substantial work. Questions and proposals also belong in Issues.
+
+## Set up locally
+
+Follow the [checkout instructions](../README.md#contribute). To submit changes without repository write access, fork the repository on GitHub and clone your fork instead. Create a branch for your contribution:
+
+```sh
+git switch -c docs/clarify-onboarding
+```
+
+Choose a branch name describing your own change. Plugin work requires [Node.js](https://nodejs.org/) 24 or newer and [pnpm](https://pnpm.io/). Install dependencies after cloning:
+
+```sh
+pnpm install
+pnpm run hooks:install
+```
+
+No API credentials are needed for documentation or the local test suite. Provider behavior tests use controlled MCP responses and private in-memory credential boundaries; they do not contact vendor services.
+
+## Find the right context
+
+1. Read the issue body, comments and dependencies. [Tracker conventions](agents/issue-tracker.md) explain development labels and where work updates belong.
+2. Read [AGENTS.md](../AGENTS.md) for repository-wide contribution rules. These apply to human and agent-authored changes.
+3. Use the [documentation map](README.md) to select only the relevant stable specs. Read [engineering standards](engineering.md) when implementing or reviewing code.
+
+Do not copy the entire documentation set into an issue or agent prompt. Link the authoritative sections and state the task's scope and acceptance criteria.
+
+## Make and verify a change
+
+For documentation, update the existing owner of a fact instead of adding a second explanation. Check relative links and anchors, verify commands against the actual repository, and distinguish required behavior from implemented behavior. When changing an upstream API claim, cite the exact dependency or source version in the owning specification, ADR or GitHub issue.
+
+Check whitespace errors before submitting:
+
+```sh
+git diff --check
+```
+
+This checks whitespace only, not links, technical accuracy or plugin behavior. Review the rendered Markdown and verify affected references separately.
+
+For code, follow the engineering guide's [verification requirements](engineering.md#verification-by-changed-surface). Run the complete local bootstrap gate before submitting:
+
+```sh
+pnpm run check
+```
+
+Use `pnpm test -- tests/<name>.spec.ts` while iterating on one behavior. Package or export changes also require `mkdir -p .artifacts`, `pnpm pack --pack-destination .artifacts`, and `pnpm run verify:package`; the last command installs the tarball into a disposable DSH profile, verifies the effective layer, boots the built Host entry, and checks the exact resolver diagnostic for a missing Host entry. Report exactly what ran; do not substitute upstream DSH tests for this plugin's integration evidence. Live-provider tests require explicitly authorized resources and spending.
+
+Biome is the repository formatter and linter. Run `pnpm run format` to apply safe formatting and lint fixes. Lefthook runs Biome on staged JavaScript, TypeScript and JSON before commit, then runs the complete local gate before push.
+
+## Submit a pull request
+
+Push your branch to your fork and open a PR against `main`. Include:
+
+- The related issue and the behavior or documentation changed.
+- Verification performed, results and any untested conditions.
+- UI evidence when the change affects an implemented interface.
+
+Keep the PR focused. Put progress updates, review findings and test evidence in the issue or PR; keep committed docs about lasting behavior and usage. A documentation update alone is not evidence that a planned feature ships.

package/docs/README.md

@@ -0,0 +1,34 @@
+# Documentation map
+
+Read [scope](specs/scope.md) for product responsibilities and [CONTEXT](../CONTEXT.md) for terminology. New contributors should start with [Contributing](CONTRIBUTING.md).
+
+## Where information belongs
+
+| Information | Authoritative location |
+| --- | --- |
+| Agent operating rules | [AGENTS.md](../AGENTS.md); `CLAUDE.md` links to the same source |
+| Implementation and verification standards | [Engineering](engineering.md) |
+| Domain terms | [CONTEXT.md](../CONTEXT.md) |
+| Stable product and integration behavior | `specs/` |
+| Accepted architectural decisions | `adr/` |
+| Tasks, dependencies, progress and verification evidence | [GitHub Issues](https://github.com/canhta/dsh-autopilot/issues) |
+
+Specifications define required behavior and acceptance rules; they do not claim that a capability has passed its external acceptance gates. Record implementation status and test evidence on the relevant GitHub issue.
+
+## Read by task
+
+| Working on | Read |
+| --- | --- |
+| Product boundaries | [Scope](specs/scope.md) |
+| Host, Client, lifecycle, persistence or tests | [Engineering](engineering.md) |
+| Admission, human authorization, pause and recovery | [Lifecycle](specs/lifecycle.md) |
+| Provider composition and extension | [Providers](specs/providers.md) |
+| DSH execution, repository rules and delegation | [Execution](specs/execution.md) |
+| Cordis lifecycle, packaging and Host/Client integration | [Plugin design](specs/plugin.md) |
+| Tracker projections, PR handoff and delivery | [Integrations](specs/integrations.md) |
+| Configuration, scheduling, budget, persistence and cleanup | [Operations](specs/operations.md) |
+| VPS supervision, backup or restore | [Deployment](deployment.md) |
+| UI navigation, visual design and journeys | [Web UX](specs/web-ui.md) |
+| UI data, commands and states | [Components](specs/ui-components.md) |
+
+Repository-development conventions apply here only; they are not imposed on repositories that Autopilot operates on.

package/docs/agents/domain.md

@@ -0,0 +1,7 @@
+# Domain documentation
+
+This repository uses a single domain context. Before domain/design exploration, read root `CONTEXT.md` and the relevant accepted decisions in `docs/adr/`. If either is absent, proceed without creating placeholders. Domain modeling creates records when terms or architectural choices are actually resolved.
+
+CONTEXT is a glossary only. Use its terms consistently; it does not hold product scope, implementation plans or progress. ADRs capture accepted architectural decisions and their rationale, not pending questions or task status. Raise a conflict with an accepted ADR explicitly before changing that decision.
+
+Use `docs/README.md` to find stable specifications. Open choices and work progress belong in GitHub Issues as defined in `issue-tracker.md`; record an accepted architectural outcome in an ADR only when its enduring decision value warrants one.

package/docs/agents/issue-tracker.md

@@ -0,0 +1,21 @@
+# Development tracker: GitHub
+
+Use GitHub Issues in `canhta/dsh-autopilot` through `gh` for this repository's development work. Autopilot's runtime Jira/Linear providers are unrelated to this choice.
+
+## Authority
+
+Tasks, priorities, assignments, blocking dependencies, unresolved choices and implementation progress live only on GitHub. Task-specific scope and acceptance criteria belong in the issue body; progress, review findings and verification evidence belong in issue/PR comments. Link stable design requirements in docs instead of copying them into each update. Do not maintain task mirrors, progress checklists or open-decision registers in repository Markdown.
+
+## Operations
+
+Resolve the repository from the remote and use `--repo canhta/dsh-autopilot` when working elsewhere. Read the issue body, labels, comments and blocking dependencies before starting. Use `gh issue view`, `gh issue list`, `gh issue create`, `gh issue edit` and `gh issue comment` for the corresponding operations. Update or link existing issues rather than create duplicates. Close only when completion evidence meets the issue's criteria.
+
+Use native sub-issues for decomposition and native issue dependencies for blocking relationships when supported. Preserve the same facts in issue-body links if a GitHub feature is unavailable; never fall back to a local status mirror. Tracker configuration does not grant blanket authority to create, close or publish work outside the user's requested scope.
+
+## Skill requests
+
+“Publish to the issue tracker” means create/update a GitHub issue within the authorized task. “Fetch the relevant ticket” means read the GitHub issue and its comments. Task specs belong in issue bodies; stable product/interface specifications belong in `docs/specs/` and are linked from issues.
+
+## Pull requests as a triage surface
+
+PRs as a request surface: no.

package/docs/agents/triage-labels.md

@@ -0,0 +1,13 @@
+# Triage labels
+
+These roles apply to development issues in this repository, not Autopilot runtime labels.
+
+| Role | GitHub label | Meaning |
+| --- | --- | --- |
+| needs-triage | needs-triage | Maintainer evaluation required |
+| needs-info | needs-info | Waiting for clarification |
+| ready-for-agent | ready-for-agent | Self-contained work ready for an agent |
+| ready-for-human | ready-for-human | Requires human implementation |
+| wontfix | wontfix | Will not be actioned |
+
+Use this mapping whenever an engineering skill names a triage role. Check blocking dependencies separately; a label does not prove a task is unblocked.

package/docs/deployment.md

@@ -0,0 +1,138 @@
+# One-VPS operation
+
+This is the proposed initial deployment shape for the implemented Host/runtime slice: one systemd-managed DSH Web
+profile, one local SQLite runtime store, one target repository and managed worktree root, and operator access through an
+SSH local-forward. It deliberately does not configure the unfinished #8 GitHub/Jira publication and delivery providers.
+
+Validation is currently local and synthetic: the packaged Host entry boots in a disposable profile, the unit is checked
+with `systemd-analyze verify`, and a separate synthetic process is refused while the first Host owns the same store.
+No real VPS shutdown/restart or offline backup/restore drill has been performed. Those steps remain an explicit issue #9
+acceptance gate; this recipe must not be presented as production-recovery evidence until that drill is recorded.
+
+The commands below assume a dedicated `dsh-autopilot` system account and these roots:
+
+| Data | Path |
+| --- | --- |
+| DSH profile, Settings and Session data | `/var/lib/dsh` |
+| installed plugin checkout/artifact | `/var/lib/dsh-autopilot/package` |
+| Autopilot SQLite runtime store | `/var/lib/dsh-autopilot/runtime/state.sqlite` |
+| managed worktrees | `/var/lib/dsh-autopilot/worktrees` |
+| target repository, including the worktrees' common Git directory | `/srv/autopilot-target` |
+| offline backups | `/var/backups/dsh-autopilot` |
+
+Keep all of these on local durable storage. DSH's SQLite WAL mode is not selected for a network filesystem.
+
+## Install and supervise
+
+Install DSH, Node 24, pnpm and Git through the operator-controlled installation path. Copy the reviewed release artifact to
+`/var/lib/dsh-autopilot/package`, create the DSH `autopilot` profile from the Web defaults, and install the artifact:
+
+```sh
+sudo -u dsh-autopilot env DSH_HOME=/var/lib/dsh \
+  dsh --profile autopilot --from-default-profile web --dump-config >/dev/null
+sudo -u dsh-autopilot env DSH_HOME=/var/lib/dsh \
+  dsh plugin --profile autopilot add \
+  /var/lib/dsh-autopilot/package/canhta-dsh-autopilot-0.1.0-alpha.1.tgz
+```
+
+Record the installed DSH version and artifact checksum before promotion. Upgrade either only as a reviewed deployment
+change. Autopilot does not install, replace or upgrade the operator's DSH runtime.
+
+In the effective DSH profile, configure the SQLite storage row at
+`/var/lib/dsh-autopilot/runtime/state.sqlite`. Autopilot derives persistence and process ownership from that DSH storage
+composition. Its optional Host-only `runtimeStorePath` setting is only a fail-closed assertion of the same absolute path;
+it neither selects storage nor enables maintenance. Set `managedWorktreeRoot` to `/var/lib/dsh-autopilot/worktrees`,
+`targetRepository` to `/srv/autopilot-target`, and the approved target base branch. Select the DSH default Agent preset
+and model route for unattended work. Keep execution disabled until those native services and the remaining execution
+settings validate and the profile dump shows the intended effective values. The alpha budget fields reconcile
+provider-reported usage after requests; they are not an exact cumulative pre-request hard cap. Keep metered production
+execution disabled until the enforcement boundary tracked in [#5](https://github.com/canhta/dsh-autopilot/issues/5)
+is complete.
+
+Install [the supplied unit](../deploy/dsh-autopilot.service) as `/etc/systemd/system/dsh-autopilot.service`, then run:
+
+```sh
+sudo systemctl daemon-reload
+sudo systemctl enable --now dsh-autopilot.service
+sudo systemctl status dsh-autopilot.service
+sudo journalctl --unit dsh-autopilot.service --since today
+```
+
+The process stays on DSH's supported loopback Web binding. Reach it from an operator workstation with an authenticated,
+encrypted SSH tunnel, then open the loopback URL printed by DSH:
+
+```sh
+ssh -N -L 127.0.0.1:14500:127.0.0.1:14500 operator@vps.example
+```
+
+This is an administrative access path, not a public Web deployment. Do not copy a `0.0.0.0` example: the selected DSH
+Web cohort rejects it, and a generic reverse proxy does not make durable Settings safe on a remote hostname. A public
+TLS deployment remains unclaimed until the separate paired-access composition passes the plugin access acceptance suite.
+
+Keep provider credentials out of the unit, Settings snapshots, backup command line and shell environment. When live
+providers arrive, provision encrypted systemd credentials (or an equivalently private host credential mechanism), expose
+only their credential references to the DSH credential/provider configuration, and back up the encrypted source through
+the operator's secret-recovery system. Configure model credentials through the selected DSH provider; Autopilot neither
+reads nor stores them.
+
+## Shutdown and health
+
+`systemctl stop dsh-autopilot` gives the Host five minutes to fence admission, quiesce managed Agent/process ranges,
+flush Sessions, persist pause/recovery facts, close the stores and finally release the runtime-owner fence. systemd's
+control-group kill policy is a last resort after that bounded graceful shutdown; a forced kill leaves recovery work for
+the next start.
+
+Operational health has independent facts:
+
+- process liveness and whether this Host holds the configured runtime-store fence;
+- maintenance-store usability;
+- unfinished-run, cleanup-intent and registered publication/delivery recovery;
+- current code-host disposition availability;
+- admission permitted, intentionally paused, or blocked by recovery.
+
+A running process with recovery or persistence failure is not ready to dispatch. An intentionally disabled/draining
+scheduler is paused, not dead. On restart, the owner fence is acquired before run-state recovery. New dispatch remains
+blocked while an interrupted run or registered #8 recovery participant reports pending/failed work.
+
+## Consistent backup
+
+Use an offline backup. Stopping the service is the consistency boundary across SQLite, DSH Session files, Git's common
+directory and linked worktrees; copying them live at unrelated instants is not a supported backup.
+
+```sh
+sudo systemctl stop dsh-autopilot.service
+sudo test ! -e /var/lib/dsh-autopilot/runtime/state.sqlite.autopilot-owner
+sudo install -d -m 0700 /var/backups/dsh-autopilot
+sudo tar -C / -cpf /var/backups/dsh-autopilot/autopilot-YYYYMMDDTHHMMSSZ.tar \
+  var/lib/dsh \
+  var/lib/dsh-autopilot/runtime \
+  var/lib/dsh-autopilot/worktrees \
+  var/lib/dsh-autopilot/package \
+  srv/autopilot-target
+sudo systemctl start dsh-autopilot.service
+```
+
+Record the archive checksum, exact DSH version, plugin artifact checksum and effective profile dump beside the archive.
+Do not add the released `.autopilot-owner` directory to an archive; its presence means shutdown did not complete and the
+backup must not proceed. The target repository is required because retained worktrees point to its common Git directory.
+
+## Restore drill
+
+Test restore on a replacement VPS or an isolated filesystem namespace; never over a running Host. Install the same Node,
+pnpm and Git cohort, stop the service, verify the archive checksum, extract all five roots together, restore the dedicated
+account ownership/modes, and keep admission disabled for inspection:
+
+```sh
+sudo systemctl stop dsh-autopilot.service
+sudo tar -C / -xpf /var/backups/dsh-autopilot/autopilot-YYYYMMDDTHHMMSSZ.tar
+sudo chown -R dsh-autopilot:dsh-autopilot /var/lib/dsh /var/lib/dsh-autopilot /srv/autopilot-target
+sudo -u dsh-autopilot git -C /srv/autopilot-target worktree list --porcelain
+sudo systemctl start dsh-autopilot.service
+sudo systemctl status dsh-autopilot.service
+```
+
+Confirm the runtime owner is held, persistence is ready, every retained path is managed/missing/orphaned as expected,
+Sessions resolve, and recovery is complete before enabling admission. Missing paths and orphans require reconciliation;
+workspace association alone never authorizes deletion. Restore encrypted provider credentials through the separate
+private secret-recovery mechanism, then verify integrations. A pending cleanup intent is reconciled to either “path still
+present; preview again” or “path absent; removal completed before acknowledgement”; it is never blindly replayed.

package/docs/engineering.md

@@ -0,0 +1,43 @@
+# Plugin engineering standards
+
+These are rules for implementing this repository, not instructions imposed on target repositories. Product behavior stays in `specs/`; verify exact upstream APIs against the pinned DSH dependency and current public source before using them.
+
+## Host code and public APIs
+
+- Use strict TypeScript and ESM. Reuse owner-exported types; brand opaque ids crossing services. Handle closed discriminated unions exhaustively; merge-extensible registries need an explicit unknown-provider/event path.
+- Validate configuration, provider/model JSON, durable records and process/wire inputs where they enter. Trust required types inside the same typed process; avoid defensive fallback branches for impossible inputs. Normalize provider failures at the provider service, preserving independent facts such as timeout and process exit.
+- Give every public operation a current consumer and documented preconditions, effects, failures and cancellation behavior. Keep helpers private. Deployment-varying choices belong in validated configuration; protocol constants and security invariants are not user tunables.
+- Follow the selected Loader export form: a service-class default export or named function-plugin exports, not both. Declare required service injection; read genuinely optional services through `ctx.get`. Packaging and resource lifetimes follow [plugin integration](specs/plugin.md), not a second local convention.
+- One asynchronous operation has one lifecycle owner. Capture its run/Session identity before awaiting; keep that identity explicit at service, persistence, worker and authority boundaries. Cancellation requested, process exited and all descendants stopped are different observations.
+- Publish derived state and notifications after the durable operation commits. Observer failure cannot undo a committed operation or starve other observers; policy vetoes remain in the deciding operation, not an observer. Enforce authorization through the actual executor, including direct and alternate callers.
+- Bound complete retained/emitted values, including framing and metadata. Own temporary paths, output files and child lifetimes; use private unpredictable paths and the configured subprocess environment policy. Worktree removal follows [cleanup requirements](specs/operations.md#worktrees-and-cleanup), not generic recursive deletion.
+
+## Client code
+
+Compose in `apply` through DSH slots and injected services. Derive the framework's runtime, child-slot, store and inject prop types rather than restating them. Components receive data and callbacks; they do not receive `ctx`, whole services or custom service-access hooks.
+
+Keep Host-derived business data in its owning data object. Declared stores hold shared view state such as selection and drafts; local component state holds local interaction. Subscribe through framework-provided hooks; do not mirror external snapshots with manual subscriptions. Keep observable and unchanged snapshot identities stable. Command/query behavior belongs to [UI components](specs/ui-components.md).
+
+Use public static primitives, not another feature plugin's private exports. Route cross-feature UI through declared slots, not ReactNode-valued service props. Use CSS Modules and semantic DSH tokens; route product copy, accessibility names and formatters through typed locale dictionaries. Keep external ticket text and stable identifiers verbatim. Verify exact imports against the pinned DSH package; [visual requirements](specs/web-ui.md) own appearance and accessibility acceptance.
+
+## Verification by changed surface
+
+Plan the relevant tiers on the implementation issue before coding. Use real DSH services beneath controlled external/model/clock inputs. Keep source tests and packed-artifact tests explicit so stale build outputs cannot make a source test pass.
+
+| Changed surface | Required evidence |
+| --- | --- |
+| Policy, provider or durable operation | Behavior tests for success, denial, malformed external input, uncertain acknowledgement and recovery; relevant [provider conformance](specs/providers.md#future-providers-and-acceptance). |
+| Registration, async resource or composition | Loader-booted fixture through a supported profile; missing dependency, withdrawal, unload/remount and no surviving resources or duplicate registrations. Hand-built plugin mounting alone is insufficient. |
+| Persistence, pause or external side effect | Real storage/fixture Git state across actual restart; verify committed and uncommitted outcomes independently, not just a returned status. |
+| Model-visible input/output | Keyless assembled Session replay/expected-output evidence; inspect persisted events and actual workspace effects. Update intended expectations explicitly, never refresh them in CI. |
+| Client data or presentation | Data-layer tests plus realistic component fixtures; assembled DSH browser evidence for slot/loading, interaction or visible changes. Follow [visual acceptance](specs/web-ui.md#visual-acceptance). |
+| Distribution or public exports | Install the packed artifact outside the checkout; exercise built Host/Client and worker entries actually shipped. Declare assets/dependencies completely; do not rely on upstream source paths. |
+| Live-provider support | Explicitly authorized, bounded test resources and spending. Keyless/mocked success does not certify live support; skipped checks remain reported as skipped. |
+
+Tests own unique ports, directories and processes, clean up on failure, and synchronize on observed events rather than guessed sleeps. Include empty, exact-limit, multibyte and oversized-result cases when adding bounds. A regression test must fail when its guarded defect is reintroduced. Verify files, Git state and external receipts independently of model prose.
+
+Run the smallest checks covering the changed surface; broader CI supplies the supported platform matrix. Define this repository's runnable gates when build tooling exists, using maintained DSH test helpers where externally usable. Upstream command names and coverage percentages are not evidence that this repository has those gates. Report exact commands, skips and remaining gaps on GitHub.
+
+## Documentation and diagnostics
+
+Update affected public usage/error documentation with behavior. Explain non-obvious constraints and model/token/cache effects when a plugin contributes model-visible material; link shared definitions instead of repeating them. Add executable invariant checks only for independent observations that can diverge, not empty companions or assertions of registration metadata. [AGENTS.md](../AGENTS.md) owns prose discipline and discovered-bug handling.