GitPulse is a local-first, zero-telemetry developer desktop application. Repository and task state stay in local stores. Git remotes, GitHub operations, optional tool installation and configured agent providers can use the network.
Product stack. DevCouncil is components and modules. Manvi wraps them. GitPulse uses Manvi for policy, workbench, and agent hosting, and selected DevCouncil modules for code intelligence. Take or update only the modules this app needs.
flowchart TD
subgraph Boundary["Security & Isolation Boundary"]
direction TB
Webview["Tauri Webview<br/>(Strict CSP: default-src 'self')"]
IPCBoundary["Tauri IPC Seam<br/>(331 Registered cmd_* Handlers)"]
LocalEngine["Rust Core Engine<br/>(Validated paths, git sandbox & policy gates)"]
Webview -->|Typed IPC Only| IPCBoundary
IPCBoundary --> LocalEngine
end
subgraph SidecarIsolation["Local Sidecar & Module Boundaries"]
direction TB
ManviSidecar["Manvi Sidecar (manvi serve)<br/>(Stdio NDJSON, 5-verdict safety ladder)"]
DevMapGate["DevMap Engine<br/>(Local .devmap/ in $GIT_COMMON_DIR/info/exclude)"]
end
subgraph ExternalSurfaces["External Surface Isolation"]
direction TB
LocalGH["Local gh CLI<br/>(Uses existing OS keychain)"]
LocalFB["Local firebase CLI<br/>(Uses existing local login)"]
LocalAI["Local LLM Server<br/>(Loopback 127.0.0.1 / localhost Only)"]
PTY["User Shell / Explicit Agent PTYs<br/>(Separate OS process trees)"]
end
LocalEngine <-->|Stdio Only| ManviSidecar
LocalEngine <-->|Local Store & Socket| DevMapGate
LocalEngine --> LocalGH
LocalEngine --> LocalFB
LocalEngine --> LocalAI
LocalEngine --> PTY
- GitPulse has no centralized backend or analytics tracking.
- Network-capable features run through user actions or explicitly enabled settings,
including scheduled release checks, automatic task suggestions, and the
default-on GitHub alert scan (Dependabot and code scanning via the local
ghCLI when a repository opens). A failed GitHub check does not toast. - Firebase App Hosting listings are user-action only, never automatic, because
they can enable an API on your Google Cloud project. See Local
firebaseCredential Safety below. - The webview does not load external CDN scripts, styles, or telemetry trackers.
- Opening a checkout first requires an explicit Trust and Open decision. Path inspection does not run Git; canceled or failed approval does not start watchers, status hydration, dependency scans, or code indexing. A tab whose open was refused for trust is marked as needing trust and is left out of live indexing, DevCouncil initialization, documentation refresh, metrics and status polling, so a refusal stays one state instead of a stream of failing calls. A workspace registry sync still writes the registry and reports such tabs as skipped for being untrusted.
- Trust permits the repository's Git hooks, helpers, and project tools to run with the user's account permissions, including code in submodules. It is an execution decision, not an OS sandbox or a claim that the project is safe.
- GitPulse stores remembered grants in its application configuration directory, outside repository policy and task files. A grant binds the repository — the common Git directory, by canonical path and filesystem identity — together with the checkout that was approved. Replacing either, or redirecting a gitfile at a different repository, requires fresh approval.
- Identity is compared in a way that survives a reboot. On Unix it is the canonical path, the inode and the birth time; on Windows, the file identity. The device number is deliberately not compared, because macOS reassigns it at mount and a reboot renumbers it, which used to revoke every approval. The birth time still tells a replacement from the original when an inode is recycled. The trade-off is stated plainly: a same-user attacker who mounts a crafted volume over the exact approved path could match an approval, but that user can already edit the owner-only trust store, and nothing widens which repositories are trusted.
- Grant records are named by an FNV-1a hash of the path, which a Rust release
cannot change (the earlier
DefaultHashernames could). Lookup still reads the old names, and a bounded startup pass (at most 4,096 directory entries) renames what it finds, skipping symlinks, fifos, corrupt and oversized files. A damaged record under the stable name fails closed rather than falling back to an older one. - One approval covers the repository, so a linked worktree is not a second decision. Every working tree shares one configuration, one hook directory and one object database, and that shared surface is the whole of what the decision is about; approving per checkout would ask the same question again for no additional authority. The approval dialog names that scope before it is granted.
- A checkout is covered only when the approved Git directory itself vouches for
it: the repository is held inside it as a real
.gitdirectory, or its private Git directory is a registered entry under that common directory'sworktrees/whosegitdirnames this checkout back. A directory that merely points a gitfile or a symlink at a trusted common directory is making a claim, not presenting evidence, and is refused — forging what is read instead requires write access to the approved repository's own Git directory, where acore.fsmonitorwould already run. - Shared Git-directory discovery stays filesystem-only, and removing a worktree still admits the target in its own right because Git scans it internally. A target in the approved repository is answered by that same grant; a target in a repository nobody approved is refused before Git starts.
- Revocation reaches the whole repository, including approvals recorded separately for its other working trees, so it is never partial. If the checkout has already been deleted it can no longer name its repository, so revocation falls back to the checkout's own path, which is all that remains to identify.
- Approvals stored before the repository became the unit are still honoured and are not widened by the change: each authorizes only the checkout it named, read from its own filename namespace so it cannot be replayed as a repository-wide one. Widening a decision taken under narrower terms is a decision to re-take, not to reinterpret, so the first approval granted after upgrading is the one that covers the family.
- That re-taking is offered rather than waited for. Trust is reported as a scope — none, this checkout, or the repository — not as a yes/no, because a single bit cannot distinguish a complete approval from a partial one, and a caller reading one reports "already trusted" for a repository whose every worktree is refused. Where a pre-repository approval leaves siblings unreadable, the worktrees panel says so and offers to extend it, and the refusal a linked worktree returns names the older scheme instead of telling someone to grant an approval they already granted. Extending is still the human's decision and still goes through the same dialog; nothing is widened by reading it.
- Native Git, background analysis, DevMap, PTY startup, and MCP reads enforce trust. MCP cannot grant it. A refusal is an explicit error or unavailable result, never a successful empty scan.
- Global tool probes run from a neutral filesystem root. Local source-tool installation requires approval for the checkout used to build the tool.
- Approval binds a directory, not a path. Because the operating system resolves a working-directory path again when a child starts, GitPulse pins the approved directory and starts the child on that pinned directory, so renaming a path component and leaving a link in its place cannot divert a Git or tool process into a checkout that was never approved. Where the whole path is already beyond other users' reach — every component owned by this user or root, and not writable by group or other unless it is sticky — the pin is redundant and is skipped, which keeps the common case on the fast process-launch path.
- On that pinned path the repository a child belongs to is read back through the pinned directory itself rather than by walking the path a second time, and the approval must name that same repository. A rename that briefly substitutes a directory and puts it back can otherwise leave the two descriptions disagreeing, with the child anchored to one checkout while the approval was granted for another.
- A terminal is the one child that cannot be re-anchored after it starts, so it is refused outright when a directory holding some component of the checkout's path is writable by other users. That refusal names the directory to change and is deliberately distinct from a trust refusal: approving the repository again cannot resolve it.
- Use the repository tab's Revoke repository trust action to close the tab and block subsequent operations for that repository and every worktree of it. Already-started terminals and agent tasks retain the authority they were given; stop them separately when needed.
- Filesystems that cannot supply a stable creation identity are refused with an explanation. Trust decisions are local to this installation and are not portable project metadata.
- Ordinary editor and documentation saves replace file entries atomically under pinned, symlink-free parent directories. Saving one hard link does not truncate the inode shared by its other names.
- Saves enforce the existing 8 MiB file budget. Nested paths, empty files, internal symlinks, and executable permissions remain supported; external symlinks and special files are refused.
- macOS metadata copying, Linux ownership and extended-attribute copying, and Windows replacement preserve supported file metadata. If preservation fails, the save fails rather than silently dropping that metadata. Linux saves clear set-id and file-capability privileges as ordinary content writes do; metadata work is bounded to 512 attributes and 1 MiB of values.
- Concurrent changes can make a save fail. If a change races publication, the error identifies retained recovery content for review. This is not an OS sandbox against another process already running with the user's rights.
- GitPulse never requests, reads, stores, or transmits your GitHub personal access tokens or passwords.
- All GitHub operations (PR inspection, workflow dispatch, Dependabot and code scanning queries) delegate exclusively to your locally installed and authenticated
ghCLI.
- The same rule holds for Firebase: GitPulse never requests, reads, stores or
transmits your Google credentials. App Hosting reads delegate to your locally
installed and authenticated
firebaseCLI, which owns the login. - Detecting that a repository uses Firebase is a local file read (
.firebaserc,firebase.json) and reaches no network. Those paths are resolved through the repository sandbox, so a symlinked.firebaserccannot be used to read a file outside the checkout — including the CLI's own credential store. - Listing backends or rollouts can enable an API on your Google Cloud
project. The Firebase CLI runs
ensureApiEnabledbefore those listings and turns the App Hosting API on when it is off. App Hosting publishes no read-only OAuth scope, so this is not avoidable by asking differently. GitPulse therefore treats those listings as mutations: they never run on their own, only from an explicit action, the panel states the side effect before the button, and the exact command line is judged by the policy gate before any process starts. Every invocation passes--json, which the CLI treats as implying non-interactive, so a prompt fails loudly instead of enabling something quietly. - A listing that could not run is reported as a reason, never as a backend with no deployments.
- What the CLI can do is asked, not assumed.
apphosting:rollouts:listis registered upstream only behind theinternaltestingexperiment, which is off by default, and an unregistered subcommand exits non-zero having written nothing to either stream. GitPulse therefore probes the installed CLI — by listing a command group, which needs no login, no project and no network — and offers the rollout action only when the subcommand is really there. A capability that could not be probed is reported as unknown rather than as absent: the two have different remedies. - Only three
firebasesubcommands can ever be spawned, each built by a single argv builder that includes the program name, so the line the policy gate judges is the line that runs. A contract test reads the module and fails on any subcommand literal outside that allow-list, on any flag the subcommand does not declare, and on--token, which would place a credential on a command line that other local processes can read.
apphosting:rollouts:createis the only command in this module that changes what the user's production traffic serves. It is not reversible from GitPulse — App Hosting publishes no rollback verb, so undoing a rollout means creating another against an earlier commit — and it is not idempotent: upstream allocates a new rollout id per call, so running it twice deploys twice.- It is therefore behind two steps, not one. The commit must be a full 40-character SHA (an abbreviation is an ambiguous target for something that reaches production, and is refused with the reason), and the panel spells out the exact project, backend and commit — plus the fact that GitPulse cannot undo it — before the deploying button exists at all. Changing any part of that target disarms the confirmation, so the values sent are always the values reviewed.
- The gate runs before the process. A refused verdict returns an error and nothing is spawned; a contract test asserts that ordering directly, because this command's argv is built in the Firebase module rather than spelled out in the handler and is therefore exempt from the literal-argv comparison.
--forceis never passed. Upstream prompts only when neither a branch nor a commit was named, and GitPulse always names a commit, so nothing here suppresses a confirmation the user would otherwise have seen.- A rollout that started is never reported as failed. If the CLI exits zero without confirming the result, the panel says the rollout started but could not be confirmed, and warns against a blind retry — because a false failure is what turns one deployment into two.
- Built-in local AI completions (commit messages, explanations and branch names)
and local model probes restrict their transport to loopback addresses
(
127.0.0.1,localhost,[::1]); remote base URLs are rejected on that path. - Commit messages are classified in the app from the staged patch. When no loopback model is selected, a supported Mac may ask Apple Intelligence only for the subject, and only from that classified brief — the patch itself is not sent. If that model is unavailable or its subject fails those checks, the message is the one the app already wrote. Explanations, branch names, and remediation plans still require a loopback model.
- Task enhancement and agent execution use the separately configured profile Manvi provider or agent CLI. Their network and filesystem access follow that provider and the selected run settings. The local-completion transport restriction does not establish containment for an explicitly launched agent.
- When
~/.anthropic-accountsis present (Manvi'santhropic-accountregistry), GitPulse launchesmanvi serveviaanthropic-account exec --no-fallback --repo $HOME -- manvi(src-tauri/src/harness/anthropic_account.rs). GitPulse never reads or stores that Anthropic API key; if the registry exists but cannot be read, GitPulse fails closed rather than falling back to a saved in-app key that may belong to another organisation. Manvi's promise to withholdANTHROPIC_API_KEYfrom its child processes is verified before spawn and at the handshake.
- The embedded interactive terminal (
src-tauri/src/terminal/) runs user shell processes directly viaportable-pty. - Local AI suggestions and the policy sidecar do not read/write ordinary shell sessions. Explicit Claude, Manvi, Codex and task launches create dedicated PTY sessions; the launched process receives that session's input.
- Terminal handoffs remain user-controlled. Managed runs (Codex and Claude Code) use the separate Manvi configuration/decision protocol. A worktree is not an OS sandbox, and native launch validation alone does not prove the provider's effective policy. See Tasks and workspaces for the verification limits.
- Model-assisted remediation actions (
cmd_manvi_run_action) are restricted to a strict command allowlist and require explicit user confirmation. - On Unix (
#[cfg(unix)]), the PTYs live in a separate process,gitpulse-ptyd, reached over a unix socket that only the same user can connect to (0700directory,0600socket, peer uid checked on every connection). Repository validation, trust andrequire_unsubstitutable_dirrun in that process, where the fork happens; a session-only trust grant never reaches it. Settings → Agents → Keep managed agent runs running when GitPulse quits (keep_terminals_running, on by default) governs whether managed agent runs also live in a detachedmanvi serve --listenprocess across app restarts. What this widens and why it grants a same-user process nothing it did not already have is documented in the signed-off security-impact statement in Terminal host.
- Opening a repository fetches Dependabot and code scanning alerts through the
locally authenticated
ghCLI. This is on by default under Settings → Analysis. GitPulse still does not read or store GitHub tokens. - Only critical and high findings raise a warning. A check that could not run
(missing
gh, not a GitHub remote, API error) is listed in Health and recorded in diagnostics, never presented as an all-clear. - Scan local on the Health panel does not call GitHub. The Check GitHub alerts button remains a manual refresh.
workbench/ci_watch.rspolls GitHub Actions through the same locally authenticatedghloader the Remote panel uses, for repositories that have a live or just-finished agent attempt branch (gitpulse/<task>-<id>). It asks only repositories the user has trusted; an untrusted repository is reported as untrusted and is never asked, and a trust store that cannot be read is its own state, not "untrusted" and not aghfault. It makes at most two asks per five-second sweep and forty per ten minutes, backs a failing repository off to ten minutes, and keeps its queues bounded. The run table that says which branches to watch is re-read every thirty seconds, not on every sweep.- A finish is attributed through the repository the checkout's git remote
names (a local git read, no
ghcall, made only for a trusted checkout and at most once per idle period), and is recorded only for a repository that is trusted at that moment. It is attributed to an attempt only by the attempt branch GitHub says the run ran on; a signal never names a branch the run was not on, and CI on the commit an attempt started from (the base branch's own run) is nobody's result. A repository with no GitHub remote cannot be watched, which is reported as its own state and is not a fault. The shared baseline also folds in the Remote panel's own listings, so a finish can exist for a repository this watcher never asked; it is not recorded unless the trust gate admits it. - It records a result with
signals.record, a store method that is host-only: the renderer is refused it (host_only), so no page can write a "your branch passed CI" notice that GitHub never sent. A signal is a fact the store was told; it never changes a task, a run or a proposal. Its log block on a failed task names the workflow, the run URL, the head commit and the conclusion, and never the run's output. ghmissing or signed out, a capped listing and an unreadable trust store are reported (Diagnostics lists the first; the Remote panel showstruncated), never presented as "no CI". A run already finished when first seen is history, not news.- Security impact: no new network endpoint, credential, process or permission.
The watcher widens nothing that can run; it adds one reader of
ghoutput inside the existing trust gate and one writer of a notice-only store method.
- Send to agent puts a CI result, or a person's note, back into the agent
that pushed the branch. It is never automatic: the panel shows the exact
text and the route a send would take (live session, resume, managed
follow-up, or unavailable with the reason), and sends only on an explicit
confirm of that route. The host re-decides the route at confirm time and
refuses (
route_changed, nothing sent) if it is no longer the one shown. Text from the producer (a workflow or branch name, a run URL) has control and bidirectional characters made visible before it is composed, and the message is held to 8 KiB, plain text with line breaks and tabs only. - A live Claude session is reached through a filesystem mailbox, not a
socket:
<config dir>/agent-mailbox/<session uuid>/. Directories are0700, files0600, every open isO_NOFOLLOW, the mailbox root and each session directory are refused if they are symlinks (the ancestors above the GitPulse config directory are the user's own and are not checked), and an object not owned by the current user or wider than its mode is refused and never read. Writes are temp-file plusrename-without-replace; a claim is a second atomic rename, so a message is delivered once even though the plugin's hook and the--settingscopy both run. Per session: 8 pending messages, 2 waiting hooks; 64 sessions and 16 waiting hooks overall; pending messages expire after 2 hours, claimed ones after 10 minutes. The session cap and the waiter caps count every Claude session in any GitPulse terminal (GITPULSE_SESSION_IDis set on plain terminals too), not only task attempts, so many plainclaudetabs can fill them, after which a send answersmailbox_full. - The newest hooks on a session take precedence: a later stop's two hooks displace an earlier stop's at their next 250 ms look (they exit 0), so a session is listening from its latest stop and not deaf from its first stop's timeout. A hook that claims a message but cannot write it to stderr still exits 2 with the message lost; it is logged, and the message is reported as claimed ("picked up"), never as read.
- Delivery is a second
Stophook entry,gitpulse-hook deliver, registered withasyncRewake: trueand a 1800 s timeout (Claude Code hooks reference, https://code.claude.com/docs/en/hooks.md: anasyncRewakehook runs in the background and wakes the session on exit 2, showing stderr as a system reminder). It waits at most 1740 s with a bounded 250 ms poll, claims one message, writes it to stderr and exits 2. Every other outcome (timeout, unknown session, full caps, an untrusted mailbox, any I/O error) exits 0. Only a session GitPulse launched has a mailbox: the hook acts only whenGITPULSE_SESSION_IDis set and the payload'ssession_idis a canonical UUID, and an unknown session creates nothing on disk. Every stop waits,stop_hook_activeor not: the turn anasyncRewakewake starts is itself a stop-hook continuation (inferred from the Claude Code 2.1.317 binary, where the wake is queued withstopHookActive: true; no real turn was run), so a hook that declined to wait there would leave a just-woken session with no waiter until the person types. This is not a self-sustaining loop: a waiter wakes Claude only on a message a person confirmed, and the waiter caps and Claude Code's own cap on consecutive continuations bound it. - A queued message is not read: the panel says queued, picked up, or
delivered, and never that the agent read or acted on it. A managed follow-up
goes through Manvi's
work.runs.managed.continue; a Manvi that does not advertise it is reported as "this Manvi version cannot take follow-ups", and a run not prepared for follow-ups as that, neither as a run failure. "Nothing was sent" is said only for the refusal codes Manvi documents as writing nothing (E_TURN_IN_FLIGHT,E_CONTINUE_RATE,E_CONTINUE_LIMIT,E_RUN_ENDED,E_DEPENDENCY,E_BAD_REQUEST,E_CONTINUE_UNSUPPORTED). An outcome that may have been written is its own state withsent: null:pending(E_CONTINUE_PENDING; Confirm stays armed and asks again with the same request id, which returns the first answer and never sends twice),unresolved(E_CONTINUE_UNRESOLVED, or an answeredunresolvedstate; never resent) andunconfirmed(anE_code this build does not know). The note editor warns that a different note is a new message sent in addition. When no hook is waiting on a live session the preview says only that, and that GitPulse cannot see why. - Security impact: a same-uid process could always type into an agent's
terminal, so the mailbox widens nothing a local user could not already do; it
adds one new way for text to reach an agent's context, and that text is only
what a person previewed and confirmed. No new network endpoint, credential,
socket or Tauri command (the host method is
runs.send_to_agenton the existing workbench seam). The hook adds a background process per idle GitPulse-launched Claude session, bounded by the waiter caps and the timeout. Expired entries are removed by the deposit and claim paths themselves, not by a daemon.
- Health's local dependency scan runs whichever audit CLIs are already on
PATH, and each is invoked so that it reads dependency metadata instead of
running the checkout: npm with
ignore-scripts, Composer with--no-plugins --no-scriptsso the project's ownvendor/plugins are not activated, pip-audit with--no-deps --disable-pip, cargo-audit through its subcommand binary so an[alias]in the checkout's Cargo configuration cannot shadow it, and govulncheck withGOTOOLCHAIN=localso a module's owntoolchainline cannot choose which Go toolchain is downloaded and run. Supply-chain health parsers (cargo denySARIF andcargo crevJSONL) similarly parse static artifact outputs without executing unverified code. - A scan that cannot complete is reported as a failed check, never as a clean result. These are bounded read-only invocations, not a sandbox: each scanner still parses repository-supplied files with the user's account permissions.
- Insights → Health integrates the Kingfisher secrets scanner to discover exposed API keys, access tokens, and credentials in repository files.
- Kingfisher runs with
--redactand--no-validate, a scrubbed environment (PATH,HOME,NO_COLORonly), and a fixed argv that never loads a repository config. Findings cross IPC as rule ID and name, repo-relative path, line, confidence, Git location, and a per-scan ordinal grouping rows that hold the same value. Secret values, matched strings, context lines, Kingfisher fingerprints and redaction hashes are dropped in the backend and never cached or persisted. - Scanner standard output is unlogged in diagnostics to eliminate accidental secret disclosure in application logs or bug reports.
- Fail-closed reporting: scans that time out, error, abort, or truncate are reported as unverified / not clean, never as an all-clear. Kingfisher exits 0 when it cannot read a file, so completeness is taken from its audit record; a scan it marks partial, or one that carries no audit, is never shown as clean.
- Dead-branch cleanup identifies merged, stale, or squashed branches using
git merge-treeto verify merge status safely. - Before executing any deletion, GitPulse generates explicit git commands
(
git branch -d/-D,git push --delete) and requires user authorization. A refusal halts the entire batch before any branch is removed. - Durable tip backups: prior to any branch deletion, a restorable tip backup is written to disk and recorded in the event ledger, allowing recovery via the Restore action.
.gitpulse/hooks.tomlsupportspost_create,pre_merge, andpost_mergelifecycle commands.- Lifecycle commands run with the user's permissions and are strictly gated on explicit repository trust. Untrusted checkouts unconditionally refuse to execute lifecycle hooks.
- Hooks are bounded: each command has a 15-minute wall-clock deadline, keeps at most 1 MiB of its output, and has its whole process tree killed at the deadline, so a hung hook cannot hang worktree creation. The deadline limits duration, not authority: a trusted hook still runs with the user's rights.
- A hook that fails, times out or is refused is reported, never discarded: the
Worktrees panel says the worktree exists but was not set up, a teardown says
its
post_mergecleanup did not run, and an agent's worktree whosepost_createfailed is removed and the agent is not started. - Merge & teardown asks the policy gate about every git command it runs, as it runs it: the merge of the worktree's own branch, the squash commit, the forced worktree removal and the branch deletion. It refuses when the main checkout is not on the target branch, and a squash whose commit fails stops before the worktree or branch is touched.
- What changed. The plugin's
gitpulse-hookbecomes a git writer:worktree-createrunsgit worktree add, andworktree-removerunsgit worktree removeandgit branch -d, from the agent's session. It also runs the repository's approvedpost_createhooks there. - Every write is judged and recorded. Each of those git commands (and the
removal and branch delete that undo a worktree whose
post_createfailed) goes to the command gate first, throughharness::judge_command, which writes the ledger row before it answers. A rule that fires refuses the operation. Reads (status,rev-list,check-ignore,ls-files) are not gated, as in the app. - Removal discards confirmed work. Claude Code asks the user before it
removes a worktree that holds uncommitted or untracked files or commits no
other branch or remote holds, and never sends the hook
discard_changes. So the hook forces such a removal (git worktree remove --force, thengit branch -D) and names what it discarded. A check that cannot run keeps the worktree. - Hook consent is unchanged.
post_createcommands run only when the exact hooks file was approved in the Worktrees panel; an unapproved or changed file runs nothing, and the hook says so on stderr. - Untrusted repositories (owner decision): GitPulse runs nothing in them;
procguardadmits no child process whose working directory is in an untrusted repository. The binary exits 75 untouched, and the plugin's launcher runs the plaingit worktree addClaude Code would have run, with no hooks, caches or.worktreeinclude. Removal there takes the same road, with the same checks done in the launcher; it keeps the branch, so no commit is lost. - No path to a worktree that is not ready. A git failure, a policy
refusal or the 540 s deadline all exit non-zero with nothing on stdout. A
post_createfailure keeps the worktree, as the Worktrees panel does; it is recorded in the worktree's git directory and the session's start-up brief warns the agent, because Claude Code does not show a successful hook's stderr. A GitPulse failure before any write exits 75 so plain git can still make the worktree. .worktreeincludecan copy secrets. It copies the files the repository's owner listed and ignored, which in practice means.env,.env.local, private keys (*.pem,*.key) and cloud credential files. This is accepted because the copy stays on the same machine, under the same user and on the same volume, with the source's permission bits; the copy is ignored in the new worktree too (checked with that worktree's own rules), so it is no easier to commit than the original; nothing is copied without a.worktreeincludenaming it; and an agent in the worktree could already read the original through the main checkout. Links are never followed on either side, existing files are never overwritten, and what is copied is logged by path, never by content.
- Cross-repository pointer validation: Zero-copy DevMap pointers (
base_store_ref.json) are accepted only whenresolve_git_common_dirproves the linked worktree andanchor_repo_rootshare the exact canonical Git common directory and contain no..traversal components (codeintel/worktree_overlay.rs,codeintel/store.rs). Crafted pointers targeting unrelated repositories or arbitrary SQLite databases fail closed. - Managed lane directory reservation:
.gitpulse/worktrees/is reserved for GitPulse-managed task-attempt lanes; manual UI, CLI, and MCP worktree creation inside that directory is refused (refuse_gitpulse_lane_target). - Bounded, lock-serialized agent coordination bus:
<git-common-dir>/gitpulse/lanes/serializes reads and writes underflock(2)on.bus.lock, rejects absolute paths,..traversal segments, and NUL bytes (sanitize_claim_paths), and enforces hard caps on active lanes (64), claimed paths/symbols per lane (128), retained messages (256), message body bytes (16 KiB), andgitpulse_worktree_radarwire size (64 KiB, reportingtruncated: truewhen cut). - MCP write & Git mutation gates: Read tools (
readOnlyHint: true, includinggitpulse_worktree_inboxandgitpulse_worktree_radar) never mutate Git or task state. Mutatinggitpulse_worktree_*tools require explicit repository trust (repository_trust::require), canonical path containment within the repository's worktree family, and Manvi policy-harness checks (harness::guard_command) on Git mutations. - Sound
gitpulse-rustcartifact reuse:gitpulse-rustcbounds@<rspfile>expansion (8 MiB, depth 4), never caches-C incrementalorbuild_script_buildinvocations, re-verifies every.dfile dependency and# env-dep:variable on Stage 2 hits, and strips comments and string literals before applying the compile-timeinclude*!(concat!(env!("OUT_DIR"), ...))exemption so runtimeOUT_DIRpaths cannot leak across worktrees.
- The signal guard protects GitPulse,
gitpulse-ptyd, and child agent sessions from accidental mass-termination by external tools (e.g.pkill,killall,pgrep,pidof). - Linux Tool Modeling: On Linux, the signal guard directly models
procps pkill/pgrep,psmisc killall, andsysvinit pidof(ft-06723bb7,d9954240,1ba087a0).- Matches process names against both
commandargv[0]'s basename (union with macOS reading). - Inspects real, effective, and saved UIDs from
/proc/<pid>/statusand applies exactkill(2)permission checks. - Correctly counts ancestors for
procps pkill. - Non-effect classes (multiple patterns,
-h/-V,killall -l, signal 0) pass silently without signaling. - Any unmodelled
psmisc killalloption escalates to an explicit user confirmation prompt rather than permitting unverified termination.
- Matches process names against both
- Background-class processes (such as background Git commands and watcher index builders) enter Darwin's background QoS scheduling band (
PRIO_DARWIN_PROCESS) in the child process beforeexecvia apre_exechook (procguard::spawn_background,ft-b597add5). - This eliminates the race window in post-spawn parent demotion where rapidly execing binaries (
sh -c,gitwrappers) created new tasks before demotion arrived. - If a background child fails to enter the band (such as under sandbox policies that deny
system-sched), the spawn fails explicitly with a tagged errno ("could not enter the background band: ") rather than silently running at normal priority.
- Agent hook notifications (
gitpulse-hook) communicate over a private, non-blocking Unix domain socket with strict deadlines (300 ms forSessionEnd, 1.5 s for other events). - If a reply deadline expires or the bridge closes without responding, the hook appends a durable drop record (
{"v":1,"at":<unix_ms>,"event":...,"session":...}) to<socket>.dropsbeside the socket (ft-6d8ff969,ft-878db72b). - Records are tightened to
0600best-effort through the file handle (fchmod), never as a blocking precondition. - Single-owner rotation renames
.dropsto.prevwhen exceeding 32 KiB, halting appending at 64 KiB. - The reader uses
.prev'sctimeas an immutable rotation clock to allow lower-bound warning notes in Settings to expire after 7 days. - When Unix domain sockets are unavailable (such as on Windows),
notifyreportsunsupportedonce per invocation and exits 0 cleanly.
- Release Bundle Verification:
release.ymlandscripts/check-release-assets.mjsdownload installer packages by asset ID and inspect archive contents across platforms (fat arm64 + x86_64 Mach-O in macOS archives, ELF in Debian packages, and PE binaries extracted via 7z in Windows MSIs/NSIS installers) to ensure every declared[[bin]]fromCargo.tomlexists. - Workflow Pipeline Safety:
check-workflows.mjsenforces theno-pipe-to-shellrule, rejecting any workflow that pipes downloaded scripts directly into a shell. Actionlint installation is pinned by SHA-256 release tarball checksums.
- Command runners propagate errors as strongly typed
CommandErrorinstances directly to the command edge across Tauri IPC (2bac9304). - This eliminates the legacy thread-local error store (
take_last_error), preventing ambient error state from leaking across concurrent command invocations or worker threads.
- Automatic application release checks are off by default; GitPulse does not automatically install application updates.
- When explicitly enabled under Settings → Updates, GitPulse compares public release tags once a day via
git ls-remoteagainst the upstream repository. - No user tokens, repository paths, or hardware telemetry are ever sent.
- Release checks only notify with a link to GitHub releases. Optional-tool setup is a separate, explicitly requested install/update workflow.
The webview operates under a strict CSP configured in src-tauri/tauri.conf.json:
default-src 'self'connect-src 'self' ipc: http://ipc.localhostimg-src 'self' data: blob: https:— pictures, and only pictures, may load from any https origin, so a README's badges show. Fetching one reveals the viewer's IP address and the time to that host, the same as opening the README on a forge; rendered<img>elements carryreferrerpolicy="no-referrer", and plain-http pictures are not fetched. No directive other thanimg-srcadmits anhttps:source or a wildcard (scripts/dev-port.test.tsholds the CSP to exactly this).script-src 'self'— remote scripts, inline scripts andevalare disallowed.style-src 'self' 'unsafe-inline'— stylesheets load only from the app itself; inline styles are allowed. This is the only directive that permits inline content, and it still admits no remote stylesheet.font-src 'self' data:,base-uri 'none'andobject-src 'none'— no remote fonts, no<base>rewriting of relative URLs, and no plugin embeds.- The development policy (
devCsp) adds only the local Vite server'shttpandwsorigins on loopback; release builds never carry them.
Rendered repository Markdown is untrusted content in the app's own document.
MarkDev's renderer escapes raw HTML and refuses active URL schemes; GitPulse
then namespaces every rendered id, replaces any picture that would resolve
against the app's own origin, and handles every link itself — the webview
never follows one (src/lib/files/markdownLinks.ts, guarded by
harness/markdown.html). Markdown parsing uses pulldown-cmark 0.13.5 (RUSTSEC-2026-0414)
to prevent exponential event duplication attacks from malformed wikilinks ([[a|]])
under ENABLE_WIKILINKS. Pictures beside a note are read only from inside its
repository, through the same containment check as cmd_get_file_blob.
A Browser session in the terminal dock (macOS) shows a local dev server's page
in a native webview laid over the tab (src-tauri/src/browser). That brings
web content into the process that holds git and the terminals, so the webview
is built to have no way back in:
- No IPC bridge. It is built with wry directly, not as a Tauri webview.
Tauri gives every webview it manages the invoke script, the
ipcmessage handler and theipc://scheme, and its capability check matches the window as well as the webview, so a Tauri child of the main window would inherit every command grant; in a dev builddevUrl(localhost:5173) is also treated as the app's own origin. The browser webview gets no IPC handler, no custom scheme and no injected script.src-tauri/tests/browser_pane_isolation.rschecks, against Tauri's own webview in the same window as a control, that a page on thedevUrlorigin and on another origin finds no__TAURI_INTERNALS__, nowindow.ipc, noipchandler, and cannotfetch("ipc://…"); giving the pane an IPC handler turns it red. - Loopback only. Only
http/httpstolocalhost,127.0.0.0/8or::1(andabout:blank) load. The rule is applied to every frame's navigations, so a remote iframe is refused too, and a refusal is shown in the session. Subresource requests (fetch, images) are not navigations and are not filtered. - Its own storage. Each session uses a non-persistent data store, so a page on the app's own dev origin cannot read GitPulse's localStorage or cookies, and nothing is written to disk.
- At most 8 sessions, and every session is closed when the main page
reloads (both tested). New-window requests are denied and no download
handler is installed, so wry cancels downloads; both are configuration
(
browser/pane.rs), not yet exercised by a test. - Page text is data. The URL and title a page reports are capped in the backend, and the title goes through the tab-title sanitizer.
- Agents can open, not drive.
gitpulse_browser_openlets an agent ask the running app to open a session. It refuses an untrusted repository and a non-loopback URL, and reaches the app only through the single-instance mailbox, which accepts this user's processes alone (peer uid checked) and validates the request again (absolute repository, loopback URL). The app comes to the front to show it. There is no tool to read the page, run script in it, navigate it elsewhere or close it; that wider control (board card M2) is not approved.
Once the page has keyboard focus it receives keystrokes, as any browser does; nothing typed there reaches GitPulse.
If you discover a security vulnerability in GitPulse, please report it via GitHub Security Advisories rather than filing a public issue:
We take security issues seriously and will respond promptly to investigate and patch confirmed vulnerabilities.
The September 2026 GTK migration replaced the old glib 0.18.5 dependency
with glib 0.22.9; the previous unresolved RUSTSEC-2024-0429 note no longer
matches the lockfile. The maintained GTK consumer patches and their validation
are documented in Dependency Health.
On 2026-09-12, the pinned revision ac84b24 passed cargo audit --deny warnings
for 550 Rust dependencies and npm audit for 175 npm dependencies, with no
reported advisories. These are dated advisory-database checks, not exhaustive
source or runtime security verification. Re-run both checks for a release.
GitPulse writes to GitHub in one new way: a commit status (devcouncil/verify) and an
optional pull-request comment carrying a task's verification verdict, through the user's
own gh login (owner-approved option A). The boundaries are enforced in
src-tauri/src/workbench/verify_status.rs and pinned by its tests. It is off per
repository until the person opts in (verify_status in tools.json; an unreadable block
is off). It runs only from the desktop commands cmd_verify_status_post and
cmd_verify_status_save; no MCP tool calls it. success needs a settled passed record
for the commit it names and a clean worktree at that commit; anything not established posts
error, and a verdict that cannot be tied to the commit posts nothing. The content is a
fixed vocabulary, counts and criterion numbers: no command output, environment, diff hunks
or free text. The request is gh api; GitPulse never reads, stores or logs the token.