@harzva/dsh-restart-autoresume

Readme

# dsh-restart-autoresume

`@harzva/dsh-restart-autoresume` adds a controlled **Restart & resume running tasks** flow to DeepSeek Harness (DSH). It records ordinary top-level sessions, flushes their durable state, delegates the actual restart to the existing `dsh-restart` Host service, and safely submits one auditable continuation turn per eligible intent after the new Host starts.

This public alpha targets DSH `0.1.1-rc.2`, Cordis `4.0.1`, and Node.js 22+. It is distributed through GitHub Releases and is not installed in a production profile by the release process.

## Screenshots

### Existing DSH restart service is available

![Restart actions backed by the existing DSH restart service](docs/assets/phase6-native-restart-panel.png)

### One ordinary top-level task is captured

![One running ordinary top-level task captured before restart](docs/assets/phase6-native-running-task.png)

### The original session continues after restart

![The continuation turn completes in the original durable session](docs/assets/phase6-native-autoresume-complete.png)

### Resume Ledger settles the intent

![The operator intent is durably completed after one attempt](docs/assets/phase6-native-ledger-settled.png)

The screenshots come from a disposable local Web profile. They contain no credentials or machine-private paths and are repository documentation assets, not runtime dependencies.

## What it provides

- one additive Host loader row and one Client sidebar Slot;
- **Restart & resume running tasks** and **Restart only** actions with explicit confirmation;
- existing `dsh-restart` Host-service capability checks that fail closed;
- Session flush before ledger commit and accepted restart acknowledgement before the delayed native restart request;
- a private, schema-versioned Resume Ledger with serialized atomic updates, corruption isolation, expiry, capacity cleanup, and `0600` files;
- startup recovery with stable intent/RPC provenance, leases, bounded concurrency, retry ceiling, and manual retry;
- live and cold Session evidence checks before dispatch and after durable persistence;
- automatic crash recovery only for registered, interrupted, ordinary top-level sessions;
- fiber-owned Agent listeners, startup work, timers, Remote service, Slot registration, styles, and cleanup.

User-stopped, completed, blocked, max-token, errored, and subagent sessions are excluded. A resumed turn is a new visible continuation request; it is not process-level checkpoint restoration.

## Deployment contract

This package deliberately does not implement another DSH restart mechanism. The target profile must already mount `dsh-restart@0.3.1` or another compatible provider of this small Host contract:

```js
{
  provider: 'dsh-restart',
  requestRestart: () => Promise<void>
}
```

`dsh-restart` remains the sole owner of closing and reopening DSH. This package owns only the durable recovery orchestration around that action. If `dshRestartRuntime` is absent or malformed, restart requests return `RESTART_RUNTIME_UNAVAILABLE` before candidates are captured or Ledger state is written. No launchd/systemd/macOS helper configuration is accepted by this package.

## Installation

Install only into a disposable or explicitly approved profile:

```sh
dsh plugin --profile web add https://github.com/Harzva/dsh-restart-autoresume/releases/download/v0.1.0-alpha.1/harzva-dsh-restart-autoresume-0.1.0-alpha.1.tgz --ignore-scripts
```

The compatible `dsh-restart@0.3.1` provider is a prerequisite and must be installed and mounted first. Do not substitute the unrelated public npm package currently using the unscoped `dsh-restart` name unless it explicitly implements the `dshRestartRuntime` contract above.

The bundle contributes exactly one row, `dsh-restart-autoresume`. Configure that row in the profile patch layer; an id-targeted patch replaces the whole `config`, so restate every non-default field you need:

```yaml
- id: dsh-restart-autoresume
  config:
    autoResumeCrash: true
    maxAttempts: 3
    claimTtlMs: 30000
    intentTtlMs: 86400000
    recoveryConcurrency: 1
    startupSettleMs: 1000
    restartDelayMs: 250
```

The `dsh-restart` bundle must be mounted in the same Host realm. Service lookup is live, so stopping or unloading the provider immediately disables the restart actions without affecting DSH startup or Ledger inspection.

## Disable and rollback

The single loader row is the immediate recovery boundary. Keep the package installed but disable all Host and Client behavior with:

```yaml
- id: dsh-restart-autoresume
  disabled: true
```

Restart the profile and confirm stock DSH starts without the sidebar action. To remove the package dependency as well:

```sh
dsh plugin --profile web remove @harzva/dsh-restart-autoresume
```

The Resume Ledger contains only safe routing/status metadata. Disabling or removing the loader does not modify DSH Session history.

## Safety semantics

- Operator restart snapshots only ordinary running roots, flushes each Session, atomically records one restart generation, acknowledges the request, and then calls the existing `dshRestartRuntime` through a Cordis-owned timer.
- Existing armed crash markers for the same sessions are atomically superseded by the operator generation, preventing duplicate recovery races.
- Crash recovery uses only valid plugin-owned intents and requires the durable Session boundary to be `interrupted`.
- Each intent uses `dsh-restart-autoresume:<intentId>` as stable RPC provenance. Durable inbox and user-message evidence is checked before any redispatch.
- The continuation prompt tells the Agent to inspect unknown external outcomes before retrying. The plugin does not promise exactly-once behavior for arbitrary tools or external systems.
- Automatic attempts are bounded. A terminal failed intent can be explicitly rearmed from the Client while retaining the same intent id and deduplication provenance.

## Development verification

```sh
pnpm install --ignore-scripts
pnpm check
pnpm run pack:dsh
pnpm run verify:dsh-offline
```

The final isolated validation includes real Web loading, Client Remote activation, a closed-loop restart through the existing `dsh-restart` Host service, durable continuation of one running ordinary top-level task, prior no-task/single-task/multi-task and `SIGKILL` recovery drills, tool-result-unknown boundaries, user-stop protection, retry ceiling/manual retry, disconnect/reconnect, responsive light/dark UI, and disable-only stock cold start. See [`docs/05-验收报告.md`](docs/05-验收报告.md) for the evidence matrix and known limits.

## Known limits

- The supported baseline is DSH `0.1.1-rc.2`; other DSH release candidates require a fresh contract and runtime validation.
- The first release never restores subagents directly. Their parent top-level Session may coordinate new subagents after recovery.
- DSH's atomic-write contract provides locked same-directory replacement but does not claim full directory-`fsync` durability against sudden power loss.
- An orphaned ledger lock is an operator remediation item after confirming that no writer is alive.
- The disposable Phase 6 process relaunch harness is test infrastructure used for crash/reconnect drills; it is not a production dependency or a second shipped restart implementation.