# Pi Native Extension launch demo verification

This note verifies the Pi Native Extension launch docs and defines the sanitized demo script for mirrored Steering and risky bash Sanction flows.

## Scope

Fizzy #55 asks to verify Pi install/use docs and create or validate a mirrored Steering / risky bash demo. This document covers the launch-safe path for `pi-agent-tick`:

- install the extension into Pi
- enable optional Agent Tick phone/web mirroring
- run a mirrored Steering prompt with a recommended option
- run a risky bash command gate without exposing secrets or executing commands from Agent Tick
- validate package tests and pack metadata

Agent Tick remains the bounded approval/steering layer. Pi and the local shell remain the execution environment.

## Current docs/media status

- `README.md` documents install, Agent Tick config resolution, steering mirroring, risky bash approvals, lifecycle status updates, tool names, parameters, and controls.
- `media/ask-user-demo.gif` and `media/ask-user-demo.mp4` show the local Pi `ask_user` UI inherited from `pi-ask-user`.
- The media is useful for local UI layout, but it is not a full phone/web mirrored Agent Tick capture. Treat the live script below as the launch demo source until a new side-by-side recording is captured.

## Install verification path

```sh
agent-tick login
pi install npm:@self-deprecated/pi-agent-tick
```

Expected behavior:

- `agent_tick_ask_user` is the canonical tool.
- `ask_user` remains a compatibility alias.
- If Agent Tick config is missing, local Pi prompts still work.
- If Agent Tick config exists, prompts mirror to Agent Tick phone/web and the first local or remote answer wins.
- `PI_AGENT_TICK_DISABLED=1` disables mirroring without disabling local Pi prompts.

## Mirrored Steering demo script

Use a safe prompt with no secrets and a clear escape option:

```text
Ask Pi to use agent_tick_ask_user:
Question: Which launch task should I demo next?
Context: We are recording a Pi + Agent Tick demo with sanitized sample data. No secrets or customer data are included.
Options:
- Run the docs build (favorite, safest)
- Run the mobile typecheck (thorough)
- Stop the demo (deny / escape)
Choice mode: select-then-submit or click-to-submit
Option placement: inline-after-content
```

Expected behavior:

1. Pi opens the local prompt immediately.
2. Agent Tick creates a mirrored `steering` or `questionnaire` request depending on `choiceInteractionMode`.
3. The same choices appear on Agent Tick phone/web.
4. The first answer wins.
5. If local Pi wins, the remote request is abandoned.
6. If Agent Tick wins, Pi receives the mapped selection.
7. The agent proceeds only with the selected bounded option.

Evidence in tests:

- `src/agent-tick.test.ts` covers `buildSteeringRequest`, questionnaire/select-then-submit mapping, multi-select mapping, cancel mapping, and remote response mapping.
- `index.test.ts` covers canonical tool registration and local/remote race behavior.

## Risky bash Sanction demo script

Sanctions are opt-in. Before recording a risky-command demo, add a temporary project-local `.pi/agent-tick.json` with a deny rule such as:

```json
{
  "sanctions": {
    "enabled": true,
    "policy": "allow-by-default",
    "tools": {
      "bash": {
        "deny": {
          "vcs-push": {
            "commandRegex": "^(git|jj)$",
            "argsRegex": "\\bpush\\b",
            "riskClass": "vcs-push",
            "reason": "VCS push"
          }
        }
      }
    }
  }
}
```

Use a command that is clearly matched by the configured demo rule but safe to deny. Do not use real deploy, publish, production, or secret-bearing commands in a public recording.

Suggested prompt to Pi:

```text
For the demo, attempt this command only after Agent Tick approval:
jj git push --dry-run
```

Expected behavior:

1. The Pi `tool_call` hook analyzes the `bash` command units and matches the configured `vcs-push` deny rule.
2. Pi shows a local approval prompt.
3. If Agent Tick config exists and remote approval is enabled, the extension creates a mirrored `sanction` request titled `Approve Pi command?`.
4. The request body contains redacted matched command units and reasons.
5. The request `command` field follows `sanctions.approval.discloseCommand` (`safe-only` by default).
6. Approve allows Pi to continue the local command.
7. Deny, cancel, timeout, or no approval source blocks the tool call.
8. Agent Tick never executes the command; it only returns the decision.

Safer recording pattern:

- Use a project-local `.pi/agent-tick.json` and remove it after the demo.
- Use a finite sanction approval timeout such as `sanctions.approval.timeoutMs=120000`.
- Use a throwaway repo/branch or keep the local denial path for the public GIF/video.
- Show the phone/web request and choose **Deny** for the first take to prove blocking.
- Optionally show an **Approve** take with a harmless dry-run command.

Evidence in tests:

- `src/agent-tick.test.ts` covers default no-sanction behavior, allow-by-default deny rules, approve-by-default allow rules, disabled tools/rules, and deny-over-allow precedence.
- Tests cover composed/wrapped command bypass attempts including lists, pipelines, subshells, shell wrappers, command substitutions, `env`, `command`, `sudo`, `xargs`, and `find -exec`.
- Tests verify safe command disclosure omits secret-looking commands and can force redacted disclosure.
- Tests verify local approval can win, local/remote denial blocks execution, remote approval can allow execution, and no approval channel blocks approval-required commands.

## Status update demo note

When Agent Tick config exists and status config is enabled, lifecycle hooks send best-effort status updates according to `.pi/agent-tick.json` / global config. Defaults are intentionally quiet:

- `before_agent_start`: `working` with a short task summary
- `agent_end`: `waiting` with a minimal message
- `turn_end`: disabled unless configured as a heartbeat
- `session_shutdown`: disabled by default because process-exit delivery depends on Pi/Node awaiting shutdown handlers
- `blocked`: sent when a steering or sanction prompt is cancelled, denied, or times out and status is enabled

These are demo-supporting signals, not approval records. Do not rely on status updates as audit proof.

## Validation commands

Run before publishing demo copy or release notes:

```sh
bun test
npm run check
```

Expected at the time this document was added:

- `bun test` passes extension/unit coverage.
- `npm run check` runs `npm pack --dry-run` and confirms package contents include the extension entrypoint, source modules, skills, README, and license.

## Public demo boundaries

Do not include:

- production hosts or customer names
- real tokens, API keys, cookies, `.env` contents, or private keys
- full command output/logs
- real deploy/publish workflows
- raw agent prompts or private chat transcripts

Do include:

- sanitized repo/branch names
- bounded choices with an escape/deny option
- the local Pi prompt and mirrored Agent Tick phone/web request
- the fact that Pi/local shell executes or blocks the command, not Agent Tick
- a denial path so viewers understand fail-closed behavior

## Open follow-up

A new side-by-side phone/web recording should replace the inherited `ask_user` UI-only media when a real device capture is available. Until then, the live script above is the verified launch demo path.