# Tick for DeepSeek Harness

[English](README.md) | [Simplified Chinese](README.zh-CN.md)

[![CI](https://github.com/Lightmaze/dsh-tick-loop/actions/workflows/ci.yml/badge.svg)](https://github.com/Lightmaze/dsh-tick-loop/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/Lightmaze/dsh-tick-loop?include_prereleases&label=release)](https://github.com/Lightmaze/dsh-tick-loop/releases)
[![License: MIT](https://img.shields.io/badge/license-MIT-7c3aed.svg)](LICENSE)

> **Give an agent another step — without giving it another task.**

`/tick` is a bounded, auditable time-step primitive for DeepSeek Harness. It
lets an already-settled session continue into one more ordinary model turn,
then another, without inventing a new goal or steering the active turn.

```text
natural conversation  -> settled
/tick 3               -> control plane only; the model never sees the command
  tick #1             -> ordinary user-role follow-up -> completed
  tick #2             -> ordinary user-role follow-up -> completed
  tick #3             -> ordinary user-role follow-up -> completed
                         stop; no fourth prompt is manufactured
```

This is not an autonomous-agent framework. It is one small primitive that
makes “another step of model time” explicit, observable, and experimentally
controllable.

## Three-minute start

Requirements: Node.js 24 and DeepSeek Harness `0.1.0-rc.6`.

Install the tagged source bundle into a DSH profile:

```bash
dsh plugin --profile web add "github:Lightmaze/dsh-tick-loop#v0.2.0-alpha.3"
dsh web
```

The bundle deliberately disables DSH Goal/Ralph continuation and automatic
compaction in that profile so they cannot become hidden continuation sources.
Use a disposable profile or review [`cordis.patch.yml`](cordis.patch.yml) before
installing into a profile you already rely on.

In a new session, establish what `tick` means in the natural conversation:

> A tick asks for nothing; it is simply a basic time step in which thought can
> continue. Therefore, do real thinking rather than merely performing the
> appearance of thought.

After that turn settles, run:

```text
/tick 3
```

Useful controls:

```text
/tick                                  Default count and literal-tick policy
/tick 12                               Exactly 12 additional time steps
/tick policies                         List configured policies
/tick 12 --policy reflective-en        Use a named, frozen time-step text
/tick 12 --policy reflective-en --resume
                                       Cross one latest interrupted boundary
/tick status                           Inspect the current bounded run
/tick stop                             Stop before the next enqueue
```

Run the provider-free protocol demonstration locally:

```bash
npm run demo
```

It exercises the command, terminal gate, three sequential enqueues, audit
records, and hard stop. It does not fabricate model output or call a provider.

## Two ways to use a time step

### Literal tick

The built-in `literal-tick` policy sends exactly:

```text
tick
```

This is the smallest intervention. Its meaning comes from the session's normal
context, not from a hidden persona or goal prompt.

### Named policy

For controlled prompt-comparison experiments, configure explicit time-step
texts and select one per run. Ready-to-copy overlays are included in
[`examples/reflective.en.yml`](examples/reflective.en.yml) and
[`examples/reflective.zh-CN.yml`](examples/reflective.zh-CN.yml).

The selected policy is frozen when the run starts. Audit records store its ID,
UTF-8 byte length, and SHA-256 digest, but not another copy of the prompt text.

## What the plugin guarantees

| Property | Contract |
| --- | --- |
| Explicit start | Ordinary conversation never starts a loop. Only `/tick` does. |
| Natural context first | A settled, natural user turn must already exist. |
| One turn at a time | The next time step is queued only after the previous terminal is `completed`. |
| Hard bound | A run accepts 1–256 additional steps and never manufactures step `N+1`. |
| Control/context separation | `/tick ...` stays in the command plane; only the selected time-step text reaches the model. |
| Provenance | Plugin steps are counted by source metadata, not by matching the visible word `tick`. |
| Fail closed | Error, unknown terminal, inconsistent history, disposal, or state drift stops or waits; there is no silent fallback. |
| Auditability | JSONL records capture arming, scheduling, enqueue, terminal, stop, and completion decisions. |

`--resume` is intentionally narrow: it may start a new bounded run across one
latest durable `interrupted` terminal. It does not resurrect an exact in-memory
timer, count an interrupted turn as completed, or replay a tool effect whose
outcome is unknown.

The complete state machine and audit schema are in
[`docs/PROTOCOL.md`](docs/PROTOCOL.md).

## Tick is not a scheduler or a goal loop

- A scheduler asks **when** a prompt should run.
- A goal loop asks **what outcome** should keep being pursued.
- Tick asks neither. It grants an already-contextualized session one bounded
  next turn after settlement.

That distinction is the project. If another mechanism supplies purpose,
background recurrence, retry, compaction, or hidden continuation, it should be
named and measured separately.

## Evidence boundary

This repository proves source-level and provider-free Harness behavior. The
real DSH command-registry gate verifies that `/tick` is registered as a slash
command and that only the generated time-step message reaches the follow-up
seam.

It does **not** prove hidden continuous thinking, autonomous life,
consciousness, useful self-direction, or that more ticks improve a task. A
model-visible time step is still an input. Its effects are empirical and may
depend on the model, context, tools, task, and policy.

Use the preregistration and comparison guidance in
[`docs/EXPERIMENTS.md`](docs/EXPERIMENTS.md) before making claims from a run.

## Development

```bash
node --test
node scripts/protocol-demo.mjs --check
node scripts/release-gate.mjs
DSH_INSTALL_ROOT=/path/to/dsh npm run test:dsh-registry
npm pack --dry-run
```

The test suite uses Node.js built-ins and makes no provider calls. CI runs on
Windows and Linux. DSH compatibility is exact-version pinned because upstream
is still a release candidate.

## Project map

- [`docs/PROTOCOL.md`](docs/PROTOCOL.md) — command grammar, state machine,
  audit records, and recovery boundary.
- [`docs/EXPERIMENTS.md`](docs/EXPERIMENTS.md) — controlled comparisons and
  honest interpretation.
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — changes, tests, and observation reports.
- [`SECURITY.md`](SECURITY.md) — private disclosure and trace hygiene.
- [`CHANGELOG.md`](CHANGELOG.md) — release history.

Bug reports and reproducible observations are welcome. Please use the issue
templates and remove provider credentials, private prompts, and workspace data
before attaching traces.

## License

MIT