New 'alias' subcommand (+ POS_SUBCMDS row, menu option 6 'Manage
aliases'): create/update/list/remove bash aliases that run
'pos system bank run <name>', written into ~/.bashrc inside a managed
marker block (BASH_RC_FILE seam for tests, atomic tmp+mv rewrite).
- alias_valid_name enforces ^[a-zA-Z][a-zA-Z0-9_-]*$
- same-name create is an idempotent retarget; last alias removal cleans
the whole block; outer ~/.bashrc aliases preserved byte-identically
- outer-alias collision refused (file untouched), PATH-shadow non-blocking
warn, 'bank remove' drops aliases pointing at the removed command
- GNU sed '1,0p' edge case (block at line 1) fixed with guarded ranges;
regex-quote literalization avoided via glob case payload match
- t-bank.sh +49 checks (71 -> 120); docs: POS.md, howto/system.md,
tests/README.md, AGENT_TODO.md; make gen byte-idempotent
(also refreshes the pos-communication-telegram-listener filetable
line count so the previous commit's tree is gen-consistent)
- rename bin/pos-bank -> bin/pos-system-bank with # POS: system bank
header; CLI becomes 'pos system bank'; BANK_FILE storage seam and v2
escaped format unchanged
- delete bin/pos-system-alias; remove its POS.md/howto sections and the
system-alias INTERACTIVE_CMDS entry; pos ai alias untouched
- update bin/pos comment + usage example, completions (gen), docs,
tests/t-bank.sh CLI path, AGENT_TODO Done notes
bank.env is line-oriented (name|description|command) so commands with
real newlines spanned records: bank_load truncated the command to its
first line and the remaining script lines became bogus entries. The
bank_get+cut -f3 retrieval path also truncated at embedded tabs.
- lib/bank-lib.sh: v2 format escapes backslash->\\ and newline->\\n
in the command field, writes # BANK_VERSION: 2; bank_load decodes
with printf %b only for v2 files, so existing v1 files load raw
(backward compatible, verified against the real ts-google entry).
- bin/pos-bank: cmd_show/cmd_run/cmd_edit now read fields from the
BANK_* arrays via bank_find instead of bank_get+cut.
- tests/t-bank.sh: +13 checks (71 total) - multiline round-trip exact
bytes, literal backslash-n, v1 raw-backslash compat, v1+re-save
byte-identical, CLI show/run full script.
_pos_complete_categories offered only hyphenated categories plus a
hardcoded 'config', so 'pos <TAB>' never showed bank/tree. Category-less
tools are now discovered from the executable scan, and the words==3
dispatch routes no-hyphen tools to _pos_complete_tool so 'pos bank <TAB>'
offers list/add/show/run/edit/remove.
- bin/pos: _pos_category_list now emits category-less tools (pos-bank,
pos-config, pos-tree) as sorted menu entries with an empty subcommand
column, deduped against real categories (pos-ai). bank previously
never appeared in the bare 'pos' menu.
- bin/pos-bank: fixed invalid 'local name="" -a cli_params=()' at
cmd_run (line 150) — bash rejected '-a' after an assignment, crashing
every 'pos bank run' with 'local: -a: not a valid identifier'.
Split into 'local name=""' + 'local -a cli_params=()'.
- tests/t-bank.sh: added B12-B14 covering cmd_run (no-params,
missing-command, param substitution) — would have caught the crash.
- AGENT_TODO.md: bank feature moved to Done.
lib/bank-lib.sh was added for pos bank but never registered in install.sh's
phase-2 lib copy list, so it never reached /usr/local/bin and pos bank failed
after install. Also restored yt-lib.sh to POS_LIBS (pre-existing gap: uninstall
left it behind). Symmetry gate tests/t-uninstall-manifest.sh now passes.
The yt-lib.sh library was missing from the install script's library
list, causing pos-media-yt-subtitles (and other yt-* tools) to fail
with 'No such file or directory' when run from /usr/local/bin/.
This adds yt-lib.sh to the install list and updates documentation
to reflect the change.
Architect-approved (C): install.sh now skips+aborts (exit 0) when the
installed version equals the current git-derived version, with a --force
flag to re-install. Version scheme 0.0cN (N = git commit count) bumps by
construction on every commit.
- install_version(): derives 0.0c$count via git rev-list; empty when .git
absent (gate skipped); INSTALL_VERSION_OVERRIDE presence-check seam for
tests (empty override simulates no-git deterministically)
- Gate after arg parse, before phases; numeric comparison (strip 0.0c, -eq);
messages: 'Already installed (X). Use --force to re-install.' and
'(dry-run) Would skip install: already at version X', both exit 0
- flag_set installed_version after 'Bootstrap complete' banner (not in
dry-run, even under --force, never on phase failure)
- Docs: SCRIPTS.md flag table + gate description, AGENT_Context line count
248->301 + flags + flow diagram, README --force row, tests/README row,
AGENT_TODO Done entry
Verified: new tests/t-install-version.sh 21 checks (9 contracted cases,
real install.sh + hermetic env seams); suite 20 files / 461 checks /
0 fail / 0 skip; make gen byte-idempotent; make check OK; make lint
0 FAIL, 0 WARN; bash -n clean; git diff --check clean; Reviewer
APPROVE_WITH_NOTES with 3 mutation disproofs (8/21, 9/21, 4/21 fail)
User report: smb-client/nfs-client mountpoint step could only auto-suggest
candidates, or create a fresh dir behind a hidden 'n=new' key — no way to
type an arbitrary existing path as the mountpoint, so the manual option
was effectively invisible (candidates from /media etc. always populated
the picker, hiding the typing path entirely). Designer framing: capability
gap + discoverability gap; backend already handled arbitrary paths (CLI
cmd_mount + ensure_mountpoint), only the interactive menu blocked it.
Change (identical in bin/pos-share-smb-client and bin/pos-share-nfs-client):
- pick_mountpoint hint 'n=new' -> 't=type'; key arm n -> t
- ask_new_mountpoint generalized to ask_mountpoint: an existing
directory is now used AS-IS (no create, no confirm); a non-existent
path keeps the 'Create mountpoint?' confirm + sudo mkdir flow; existing
non-directory rejected ('has a file there'); shape checks and system-path
refusal unchanged; stream contract (display->stderr, path->stdout) kept
- menu_ask_mountpoint empty-candidate fall-through now routes through the
same ask_mountpoint validator (single source of truth)
Docs: DOC/howto/share.md NFS+SMB mountpoint sections updated from n=new to
t=type and describe existing-path-without-create behavior.
Scoped to the two client files + howto doc; persistence/automount units,
unmount/remove flows, cmd_* CLIs, share_folder_candidates, and
lib/menu-lib.sh untouched.
Verified: 9-scenario smoke matrix x2 files (~19 assertions each: existing
dir as-is, new-dir confirm+create, decline, relative/trailing-slash/system/
empty rejections, non-dir reject, mkdir-fail), make gen idempotent, make
check OK, make lint 0 FAIL/0 WARN, make test 17 files / 299 checks green,
bash -n clean, git diff --check clean. Designer ACCEPT framing+spec;
Reviewer ACCEPT after doc fix.
User hit 'API error 402: ... You requested up to 131072 tokens, but can
only afford 4511' on the assist alias: no provider ever sent max_tokens,
so OpenRouter's credit pre-check billed the routed model's full
worst-case output; user also asked to bound session history to the last
5 requests/responses.
Architect decisions:
- AI_MAX_TOKENS (num, default 2048): sent as max_tokens on OpenRouter
and generationConfig.maxOutputTokens on Gemini — a real per-request
cost ceiling. llamacpp unchanged (local/free, no pre-check).
- AI_SESSION_TURNS (num, default 40 kept back-compat; messages, 2 per
exchange — 10 = last 5 conversations): resolved lazily in session_push
because config loads after the hardcoded line-25 default.
- Both registered in the bin/pos-ai POS_CONFIG @General section, so they
appear in 'pos config ai' with num: validation.
Reviewer hardening (CHANGES_REQUIRED -> fixed): unguarded env input could
reach jq tonumber (0/-5/010/abc all savable via config-ui's ^-?[0-9]+$)
and abort the CLI; both providers and session_push now guard with
^[1-9][0-9]*$ and fall back to the default.
Verified: fake-curl shim smoke (16 provider-body + 12 session-window
checks incl. the 010-regression proof), make gen idempotent, make check
OK, make lint 0 FAIL/0 WARN, make test 17 files / 299 checks / 0 fail
(~49s), bash -n clean, git diff --check clean. Reviewer ACCEPT (twice).
Tester regression round (permanent provider-body + session-pruning
coverage) intentionally not run this cycle — user's call; remains a
documented follow-up.
User report after the llamacpp app install: 'installed llama.cpp unknown',
valid flags rejected (randomly per run), 'Model not found' for the HF
downloader's own layout, and a systemd user-bus failure over SSH. Detective
(real b10822 binary, FACT) found four independent causes:
- version: llama-server --version prints to STDERR; detect_llama_version's
2>/dev/null swallowed it -> always 'unknown'. Now captures 2>&1 + accepts
semver/build tokens (incl. build 1.2.3 edge)
- validation: printf|grep -q under pipefail -> SIGPIPE rc=141 race randomly
rejected flags present in the 59 KB --help. Now pipe-less grep (no race);
20x determinism regression test
- model resolution: resolve_model accepted files only, but the HF downloader
creates <models>/<repo>/file.gguf dirs. Now expands a dir with exactly one
*.gguf (never silently picks; multi-gguf lists + errs)
- port: llama.cpp default 8080 vs tool/adapter 8088; validation reliability
means --port is now always pinned in the unit
- user bus: headless/SSH sessions lack XDG_RUNTIME_DIR -> ensure_user_bus in
lib/common.sh pre-flights all three systemctl --user tools with remediation
text; pos ai server --no-unit direct-run escape hatch (pidfile) for boxes
with no bus
- find_llamacpp narrowed to llama-server/llama-server-cuda (bare 'server'
fallback hazard); installer post-install sanity (version+help execute,
symlink targets resolve)
Architect decisions DQ1-DQ6 recorded. Tester: 4 new regression files
(version-from-stderr, 25x flag-validation determinism, model dir expansion,
bus pre-flight + E2E) + 3 fixture updates; suite 16 files / 269 checks.
Verified: make gen idempotent; make check OK; make lint 0 FAIL, 0 WARN;
make test 269/269 (~49s); bash -n clean; git diff --check clean.
The HF tree API returns entries shaped {oid,path,size,type} with no
rfilename field, so every downstream .rfilename read was null: the
--gguf filter crashed with 'jq: endswith() requires string inputs' and
single-file/all-files/meta modes silently built 'null' URLs. hf_repo_files
now normalizes tree entries to the {rfilename,size} shape the fallback
already emits (object-guarded; error-object bodies degrade to [] instead
of jq 5). The --gguf filter is type-guarded and empty results get
mode-aware messages. Verified: 12/12 fixture harness, live API 13->10
gguf, tiny real download OK, gates green. User confirmed the real
--gguf command now downloads [1/10].
LLAMACPP_* keys lived under a generic General group. Added a conditional
'@[AI_PROVIDER=llamacpp] llamacpp' caption (mirrors OpenRouter), so the
provider gets its own section; General now only holds AI_SYSTEM_PROMPT
plus the HF keys that arrive from pos-ai-hf. AI_PROVIDER description and
usage text mention llamacpp.
Also: inactive config groups no longer dim the key name — keys stay bold
so an inactive provider block is not one uniform grey wall; only values
and descriptions dim, and the caption still carries the inactive reason.
Service manager (start/stop/status/models/logs) with systemd user
service generation, GPU auto-detection, model selection from pos ai hf
downloads. Provider adapter integrates with pos ai ask as --provider
llamacpp. Config extends existing ai scope with LLAMACPP_* keys.
87 test cases / 0 failed. make gen/check/lint 0 FAIL / 0 WARN.
Bash-native tool using curl/jq to download AI models from HF Hub.
Subcommands: download (single file/repo/gguf filter), search, list, remove.
Auth via HF_TOKEN in ai.env, resume support, disk space pre-flight,
rate limit handling, .hf-meta metadata tracking.
46 test cases / 0 failed. make gen/check/lint 0 FAIL / 0 WARN.
New tool that classifies URLs by domain and delegates to pos media mp3
(audio) or pos media mp4 (video). Listener gains URL detection step
between prefix map and AI bridge — bare URLs auto-download.
Domain rules: music.youtube.com/soundcloud/bandcamp → mp3,
youtube/vimeo/twitch → mp4 --best, unknown → configurable default.
28 test cases / 70 assertions / 0 failed.
make gen && make check green, make lint 0 FAIL / 0 WARN.
Generalizes the Telegram listener with a configurable text-prefix map
(telegram_prefixes.env): any non-command message '<word> <text>' runs
the mapped command with <text> appended as ONE quoted argument — e.g.
opencode=opencode turns 'opencode check cpu' into opencode "check cpu".
Routing order per message: text-prefix map → built-in Gemini ai bridge →
/command map → Unknown command. A mapped word shadows the Gemini bridge.
The prefix verb is reworked: bare = list map + bridge word; 'prefix
<word> <cmd...>' = map; 'prefix <word>' = show; 'prefix -r <word>' = remove.
The Gemini trigger word itself is now set via 'pos config telegram'
(TELEGRAM_AI_PREFIX).
Also extracted run_and_reply() to share the /command-map (60s) and
prefix (120s) execution semantics; fixed a latent set -e abort on
invalid templates in prefix_map_set's check_syntax call.
Verified: 27/27 routing-harness assertions, full CLI verb suite,
dispatch smoke, pos config telegram render, bash -n, make gen && make check,
make lint 0 FAIL / 0 WARN, shellcheck -S style (0 new findings).
menu_ask_value used line-oriented read -rp: a multiline Ctrl+V paste
flooded the tty queue, read consumed only the first line, and the rest
executed as commands later (or were eaten by a later prompt).
- lib/menu-lib.sh: new menu_read_value() raw-mode bracketed-paste
reader (stty -icanon -echo -isig, \e[?2004h/l, literal newlines inside
[200~..[201~, Enter submits outside paste, edit keys, cancel on
Ctrl-D-empty/Ctrl-C/Z/\, terminal restored via trap). Bytes via
dd|od|tr chunks, not bash read: read self-interrupts on ETX from a
tty even with ISIG disabled.
- bin/pos-ai-alias: prompt encode/decode (backslash, newline) with
load/save wiring; newline-safe truncate; edit wizard Enter keeps the
full original prompt (no more silent >80-char truncation).
Verified via pty harnesses: multiline + single-line paste captured
verbatim with nothing executed, Ctrl-D/Ctrl-C cancel cleanly, full
create/list/show/edit E2E, round-trips byte-exact. Gates: make gen &&
make check, make lint 0 FAIL 0 WARN.
Add an optional5th 'trusted' field to aliases
(name|provider|session|prompt|trusted). Trusted aliases pass --trust to
pos ai, which makes _prompt_run_command auto-execute the agent's detected
commands without the Y/n confirmation (command still printed for audit).
- bin/pos-ai: new --trust global flag; _prompt_run_command takes trusted
arg and skips the prompt when set; POS_FLAGS + usage updated
- bin/pos-ai-alias: _ALIAS_TRUSTED array, 5-field env format (backward
compat: missing field defaults to untrusted), Trust column in table,
trust row in show, trust step (5/5) in create wizard with security
warning, trust toggle (4/4) with diff tag in edit wizard, wrapper
scripts get --trust when alias is trusted
- completions/pos.bash + gen docs updated
Gates: make gen && make check && make lint = 0 FAIL, 0 WARN
read -e -i only handles single-line text. Multi-line commands (docker
install etc) broke it. Now flattens newlines to spaces before pre-filling
the readline buffer. User sees a single editable line.
- _inject_command tries: xclip/wl-copy (clipboard) -> xdotool (typing) -> tmux -> history
- Clipboard is primary: user pastes with Ctrl+Shift+V
- preinstall.sh: add xdotool and xclip to PACKAGES
- e: xdotool type (X11/Wayland) -> tmux send-keys -> history fallback
- Command appears on active terminal line for editing before Enter
- Y/Enter: execute, n: add to history
- _extract_commands() parses bash/sh/shell fenced code blocks
- _prompt_run_command() prompts [Y/n] via /dev/tty after AI response
- Y/Enter: execute via run helper (respects DRY_RUN)
- n: command added to history (press up-arrow to recall, edit, run)
- Integrated in both cmd_ask() and cmd_chat()
- Skipped when output is piped/redirected
New bin/pos-docker-stack: docker ps output grouped by Docker Compose
project (stack). Each stack is a sorted section (name, status, ports);
containers without a compose project land in a Standalone group at the
end. Running only by default, -a|--all includes stopped/exited. Status
colored on a terminal; summary line 'Stacks: N containers: N
standalone: N'; exit 0 when empty.
Data via docker ps --format with \x1f delimiters (project label
com.docker.compose.project from compose v2); parsed with awk -F'\x1f'
+ IFS=$'\x1f' read — tab/pipe delimiters are IFS whitespace or appear
in values (DEV.md:213). Dash padding via sed, not tr (multi-byte).
Deps guard (docker) before --help; no stdin.
Docs: POS.md docker row + detail, howto/docker.md table + section,
bin/pos usage EXAMPLES, AGENT_Context Common Tasks row. Verified:
stub suite 23/23, live daemon runs, dispatch, make gen && make check,
make lint 0 FAIL / 0 WARN.
Your Name