ironsilk 0.9.1__tar.gz

ironsilk-0.9.1/.gitignore

@@ -0,0 +1,2 @@
+# build-time staging only — populated by `make prepare-data`, removed by `make clean-data`
+hermes_navigator/data/

ironsilk-0.9.1/Makefile

@@ -0,0 +1,66 @@
+.PHONY: install install-dev test build wheel sdist upload upload-test test-release bump clean prepare-data clean-data
+
+PKG_DATA = hermes_navigator/data
+
+# ---------------------------------------------------------------------------
+# dev
+# ---------------------------------------------------------------------------
+
+install:
+	pip install -e .
+
+install-dev:
+	pip install -e ".[dev,controller,daemon,telegram]"
+
+test:
+	pytest -v
+
+# ---------------------------------------------------------------------------
+# data assembly (temporary staging into package dir before build)
+# ---------------------------------------------------------------------------
+
+prepare-data:
+	mkdir -p $(PKG_DATA)
+	cp examples/config.yml      $(PKG_DATA)/config.yml
+	cp examples/domains.yml     $(PKG_DATA)/domains.yml
+	cp skills/navigator.skill.yml $(PKG_DATA)/skill.yml
+
+clean-data:
+	rm -rf $(PKG_DATA)
+
+# ---------------------------------------------------------------------------
+# build
+# ---------------------------------------------------------------------------
+
+build: clean prepare-data
+	python -m build
+	$(MAKE) clean-data
+
+wheel: prepare-data
+	python -m build --wheel
+	$(MAKE) clean-data
+
+sdist: prepare-data
+	python -m build --sdist
+	$(MAKE) clean-data
+
+upload: build
+	twine upload dist/*
+
+upload-test: build
+	twine upload --repository testpypi dist/*
+
+test-release: bump clean build
+	twine upload --repository testpypi dist/*
+
+bump:
+	python bump.py $(TYPE)
+
+# ---------------------------------------------------------------------------
+# clean
+# ---------------------------------------------------------------------------
+
+clean: clean-data
+	rm -rf build/ dist/ *.egg-info hermes_navigator.egg-info __pycache__ .pytest_cache .hatch
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete

ironsilk-0.9.1/OPERATOR-NOTE.md

@@ -0,0 +1,184 @@
+# IronSilk Operator Slices
+<!-- Ref: jgwill/Miadi#300 -->
+
+## Slice 1: tmux Terminal Awareness
+
+This slice proves that Hermes Navigator can know enough about a tmux session
+before attaching to it.
+
+Proof path:
+
+```bash
+hnavig operator terminals
+hnavig operator peek 7 --lines 80
+hnavig operator attach 7
+```
+
+`operator terminals` lists live tmux sessions and panes with attach commands.
+`operator peek` captures recent scrollback without changing focus. `operator
+attach` prints the exact attach, switch, and pane-select commands.
+
+Running the attach is intentionally guarded:
+
+```bash
+hnavig mode controller
+hnavig operator attach 7 --run
+```
+
+`--run` requires `ACTIVE_CONTROLLER` mode and an interactive local TTY. The safe
+default is command printing only.
+
+## Slice 2: Persisted Terminal Registry
+
+This slice records terminal awareness as append-only JSONL, not SQLite, before
+any resume automation exists.
+
+Proof path:
+
+```bash
+hnavig operator registry save
+hnavig operator registry last-known
+hnavig operator registry drift
+```
+
+`registry save` appends one timestamped observation snapshot. `registry
+last-known` reads the newest saved snapshot. `registry drift` compares current
+tmux state with that snapshot.
+
+The registry separates observed tmux fields from inferred Navigator fields.
+Observed fields include session id, pane id, cwd, command, pid, and attach
+state. Inferred fields include universe confidence and generated attach/switch
+commands. Every snapshot includes provenance and `recorded_at`.
+
+## Slice 3: Operator Checkpoint
+
+This slice answers: what is going on, and where can I safely enter?
+
+Proof path:
+
+```bash
+hnavig operator checkpoint
+hnavig operator checkpoint --target 7 --peek-lines 20
+hnavig operator checkpoint --format json
+```
+
+`checkpoint` is read-only. It combines current terminals, last-known registry
+metadata, drift summary, stale/last-seen hints, and safe attach/switch/select
+commands. It only captures scrollback when `--target` is explicit.
+
+## Slice 4: Checkpoint Handoff Artifacts
+
+This slice serializes the same checkpoint report into portable handoff files.
+
+Proof path:
+
+```bash
+hnavig operator checkpoint --write
+hnavig operator checkpoint --target 7 --peek-lines 20 --write
+```
+
+`--write` saves Markdown and JSON under
+`HNAVIG_HOME/operator/checkpoints/<timestamp>-operator-checkpoint.*`. The
+artifacts include provenance, the source command, and the no-attach/no-resume
+safety note. It does not create a new storage schema or mutate terminals.
+
+## Slice 5: Steer Proposal
+
+This slice creates a human-reviewable follow-up message for one target without
+sending it.
+
+Proof path:
+
+```bash
+hnavig operator steer-proposal 7 --message "continue from here"
+hnavig operator steer-proposal 7 --message-file prompt.md --write
+hnavig operator steer-proposal 7 --message "continue" --peek-lines 40
+```
+
+`steer-proposal` is read-only. It resolves the explicit target, optionally
+includes a peek excerpt, records the proposed message, and prints manual
+`tmux send-keys` suggestions clearly marked as suggestions only. It never calls
+`tmux send-keys`.
+
+## Slice 6: Agent Install Smoke
+
+This slice verifies that a fresh agent can install the published package and use
+the existing operator workflow without source-checkout assumptions.
+
+Proof path:
+
+```bash
+python -m venv /tmp/hnavig-agent-smoke-venv
+source /tmp/hnavig-agent-smoke-venv/bin/activate
+pip install -U hermes-navigator
+hnavig --help
+hnavig operator --help
+
+HNAVIG_HOME=/tmp/hnavig-agent-smoke hnavig operator terminals --format json
+HNAVIG_HOME=/tmp/hnavig-agent-smoke hnavig operator checkpoint --format json
+HNAVIG_HOME=/tmp/hnavig-agent-smoke hnavig operator checkpoint --write
+HNAVIG_HOME=/tmp/hnavig-agent-smoke hnavig operator steer-proposal 0 --message "Please summarize your current state and wait for human confirmation." --write
+```
+
+Use the visible `terminal_id` from `operator terminals` in place of `0` when the
+local tmux target differs. This smoke remains read-only: no attach, no send, no
+resume automation.
+
+## Slice 7: Guarded Send / Apply
+
+This slice closes the raw-`tmux send-keys` gap with an explicit, guarded
+mutation primitive for reviewed steer.
+
+Proof path:
+
+```bash
+hnavig operator send 7 --message "continue from the last verified checkpoint"
+hnavig operator send 7 --proposal-file /path/to/steer-proposal.json
+hnavig mode controller
+hnavig operator send 7 --proposal-file /path/to/steer-proposal.json --run
+```
+
+`operator send` requires an explicit target and exactly one reviewed message
+source: `--message`, `--message-file`, or `--proposal-file`. The default is a
+dry-run plan that prints the exact `tmux send-keys -l` and `tmux send-keys -t
+... C-m` commands without executing them. Actual mutation remains guarded by
+`ACTIVE_CONTROLLER` mode plus an interactive local TTY. It also requires a
+currently resolved tmux target before execution. It does not attach, resume, or
+choose a target automatically.
+
+## Slice 8: v0.7.0 Release Gate
+
+This slice gives a fresh Hermes-Agent operator one command to verify the CLI
+base before starting workspace registry work.
+
+Proof path:
+
+```bash
+hnavig doctor --release-target 0.7.0
+hnavig doctor --release-target 0.7.0 --strict
+hnavig doctor --release-target 0.7.0 --require-daemon --strict
+```
+
+`doctor` checks package version, state/config shape, tmux availability, daemon
+ping/context readiness, user service hints, and the operator/session command
+surfaces required for the 0.7.0 base. Missing daemon/service/context state is
+reported clearly; `--require-daemon` promotes daemon absence to a failed check.
+
+## Slice 9: Tmux-Backed Named Sessions
+
+This slice makes the named session vocabulary concrete without introducing a
+new runtime substrate before the Hermes-Agent boundary is stable.
+
+Proof path:
+
+```bash
+hnavig session new ava-260512 --cwd /usr/local/src/ironsilk
+hnavig session attach ava-260512
+hnavig mode controller
+hnavig session new ava-260512 --cwd /usr/local/src/ironsilk --run
+hnavig session attach ava-260512 --run
+```
+
+`session new` and `session attach` are dry-run by default. They print exact tmux
+commands and record executed sessions in the existing session store. Execution
+requires `ACTIVE_CONTROLLER` mode and an interactive local terminal.