diff --git a/Directory.Packages.props b/Directory.Packages.props
index 2daf4c6..9747d33 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -46,6 +46,11 @@
+
+
+
diff --git a/README.md b/README.md
index 2e7aa0b..1195104 100644
--- a/README.md
+++ b/README.md
@@ -544,8 +544,10 @@ the Windows service APIs (`advapi32` / `ServiceController`) — never `sc.exe`.
**Linux and macOS**: the same commands work with the portable `executer-agent`
binary (`install` writes a systemd unit `executer-agent` or a launchd daemon
-`info.executer.agent`). Configuration lives in `/etc/executer/agent.json`
-instead of the registry, credentials under `/var/lib/executer` (mode 600).
+`info.executer.agent`, and symlinks the binary into `/usr/local/bin` so
+`executer-agent` is on `PATH`; `remove` deletes both). Configuration lives in
+`/etc/executer/agent.json` instead of the registry, credentials under
+`/var/lib/executer` (mode 600).
On startup the agent idempotently installs PowerShell 7 when missing (Homebrew
on macOS, the official install script on Linux) — scripts run via the embedded
PowerShell SDK either way, so this only matters for operator convenience.
diff --git a/src/Agent/Agent.csproj b/src/Agent/Agent.csproj
index 652a72c..5fa4593 100644
--- a/src/Agent/Agent.csproj
+++ b/src/Agent/Agent.csproj
@@ -35,7 +35,6 @@
-
@@ -43,10 +42,17 @@
+
+
+
+
+
diff --git a/src/Agent/Service/UnixServiceLifecycle.cs b/src/Agent/Service/UnixServiceLifecycle.cs
index 6be30e8..4dbe098 100644
--- a/src/Agent/Service/UnixServiceLifecycle.cs
+++ b/src/Agent/Service/UnixServiceLifecycle.cs
@@ -14,14 +14,80 @@ public static class UnixServiceLifecycle
private const string SystemdUnit = "executer-agent";
private const string LaunchdLabel = "info.executer.agent";
+ // On the default PATH on both linux and macOS, and writable (unlike /usr/bin
+ // on macOS under SIP). Mirrors the Windows installer's PATH entry so
+ // `executer-agent` / `which executer-agent` work from any shell.
+ private const string PathLink = "/usr/local/bin/executer-agent";
+
private static string ExePath =>
Environment.ProcessPath ?? throw new InvalidOperationException("Cannot determine the executable path.");
public static int Install()
- => OperatingSystem.IsMacOS() ? InstallLaunchd() : InstallSystemd();
+ {
+ var code = OperatingSystem.IsMacOS() ? InstallLaunchd() : InstallSystemd();
+ if (code == 0)
+ {
+ LinkOnPath();
+ }
+
+ return code;
+ }
public static int Remove()
- => OperatingSystem.IsMacOS() ? RemoveLaunchd() : RemoveSystemd();
+ {
+ UnlinkFromPath();
+ return OperatingSystem.IsMacOS() ? RemoveLaunchd() : RemoveSystemd();
+ }
+
+ ///
+ /// Symlink the agent onto PATH. Best-effort: a failure here (e.g. not root,
+ /// read-only /usr/local) never fails the install. Replaces only a prior
+ /// symlink of ours — never an unrelated real file at that path.
+ ///
+ private static void LinkOnPath()
+ {
+ try
+ {
+ Directory.CreateDirectory("/usr/local/bin");
+
+ var existing = new FileInfo(PathLink);
+ if (existing.Exists || existing.LinkTarget is not null)
+ {
+ if (existing.LinkTarget is null)
+ {
+ Console.Error.WriteLine($"warning: {PathLink} exists and is not a symlink; leaving it in place.");
+ return;
+ }
+
+ File.Delete(PathLink);
+ }
+
+ File.CreateSymbolicLink(PathLink, ExePath);
+ Console.WriteLine($"Linked {PathLink} -> {ExePath}");
+ }
+ catch (Exception ex)
+ {
+ Console.Error.WriteLine($"warning: could not add executer-agent to PATH ({ex.Message}).");
+ }
+ }
+
+ private static void UnlinkFromPath()
+ {
+ try
+ {
+ // Remove only a symlink that points at our install, so an unrelated
+ // /usr/local/bin/executer-agent is left untouched.
+ if (new FileInfo(PathLink).LinkTarget is { } target
+ && (target == ExePath || target.Contains("/executer/", StringComparison.Ordinal)))
+ {
+ File.Delete(PathLink);
+ }
+ }
+ catch (Exception ex)
+ {
+ Console.Error.WriteLine($"warning: could not remove executer-agent from PATH ({ex.Message}).");
+ }
+ }
public static int Start()
=> OperatingSystem.IsMacOS()
diff --git a/src/Agent/Storage/JobHistoryStore.cs b/src/Agent/Storage/JobHistoryStore.cs
index 796822d..8dbafb9 100644
--- a/src/Agent/Storage/JobHistoryStore.cs
+++ b/src/Agent/Storage/JobHistoryStore.cs
@@ -1,4 +1,5 @@
using Microsoft.Data.Sqlite;
+using Microsoft.Extensions.Logging;
using Shared.Infrastructure.Constants;
namespace Agent.Storage;
@@ -7,47 +8,77 @@ namespace Agent.Storage;
/// Durable local record of handled job ids so JetStream redelivery or agent
/// restart never executes the same script twice. Retains the most recent
/// completed entries (bounded) in a lightweight SQLite database.
+///
+/// If SQLite cannot initialize (e.g. the host lacks a usable system libsqlite3),
+/// the store falls back to an in-memory record so the agent still runs — job
+/// idempotency then holds within the process lifetime but not across restarts.
+/// The failure is logged once at startup rather than crashing the service.
///
public sealed class JobHistoryStore : IDisposable
{
- private readonly SqliteConnection connection;
+ private readonly SqliteConnection? connection;
private readonly Lock writeLock = new();
- public JobHistoryStore()
- : this(Path.Combine(Branding.AgentProgramDataDirectory, Branding.JobHistoryFileName))
+ // In-memory fallback (used only when connection is null). handledOrder keeps
+ // insertion order for bounded pruning; handledSet backs membership tests.
+ private readonly HashSet? handledSet;
+ private readonly Queue? handledOrder;
+ private readonly Dictionary? downloadCacheMem;
+
+ public JobHistoryStore(ILogger logger)
+ : this(Path.Combine(Branding.AgentProgramDataDirectory, Branding.JobHistoryFileName), logger)
{
}
- public JobHistoryStore(string databasePath)
+ public JobHistoryStore(string databasePath, ILogger? logger = null)
{
- var directory = Path.GetDirectoryName(databasePath);
- if (!string.IsNullOrEmpty(directory))
+ try
{
- Directory.CreateDirectory(directory);
+ var directory = Path.GetDirectoryName(databasePath);
+ if (!string.IsNullOrEmpty(directory))
+ {
+ Directory.CreateDirectory(directory);
+ }
+
+ var sqlite = new SqliteConnection($"Data Source={databasePath}");
+ sqlite.Open();
+
+ using var command = sqlite.CreateCommand();
+ command.CommandText = """
+ CREATE TABLE IF NOT EXISTS HandledJobs (
+ JobId TEXT PRIMARY KEY,
+ AcceptedUtc TEXT NOT NULL,
+ CompletedUtc TEXT NULL,
+ State TEXT NULL
+ );
+
+ CREATE TABLE IF NOT EXISTS DownloadCache (
+ DestinationPath TEXT PRIMARY KEY,
+ ObjectKey TEXT NULL,
+ ETag TEXT NULL,
+ Sha256 TEXT NULL,
+ SizeBytes INTEGER NULL,
+ DownloadedUtc TEXT NOT NULL
+ );
+ """;
+ command.ExecuteNonQuery();
+
+ connection = sqlite;
+ }
+ catch (Exception ex)
+ {
+ // Any storage failure — a missing/incompatible native SQLite, an
+ // unwritable path — must not take the agent down. Degrade to
+ // in-memory idempotency and carry on.
+ logger?.LogWarning(
+ ex,
+ "Local job store unavailable ({Path}); using in-memory idempotency (not persisted across restarts).",
+ databasePath);
+ connection = null;
+ handledSet = [];
+ handledOrder = new Queue();
+ downloadCacheMem = [];
}
-
- connection = new SqliteConnection($"Data Source={databasePath}");
- connection.Open();
-
- using var command = connection.CreateCommand();
- command.CommandText = """
- CREATE TABLE IF NOT EXISTS HandledJobs (
- JobId TEXT PRIMARY KEY,
- AcceptedUtc TEXT NOT NULL,
- CompletedUtc TEXT NULL,
- State TEXT NULL
- );
-
- CREATE TABLE IF NOT EXISTS DownloadCache (
- DestinationPath TEXT PRIMARY KEY,
- ObjectKey TEXT NULL,
- ETag TEXT NULL,
- Sha256 TEXT NULL,
- SizeBytes INTEGER NULL,
- DownloadedUtc TEXT NOT NULL
- );
- """;
- command.ExecuteNonQuery();
}
/// What the agent knows about a previously downloaded file.
@@ -55,6 +86,14 @@ public sealed class JobHistoryStore : IDisposable
public DownloadCacheEntry? GetDownloadCache(string destinationPath)
{
+ if (connection is null)
+ {
+ lock (writeLock)
+ {
+ return downloadCacheMem!.GetValueOrDefault(destinationPath);
+ }
+ }
+
using var command = connection.CreateCommand();
command.CommandText =
"SELECT ETag, Sha256, SizeBytes FROM DownloadCache WHERE DestinationPath = $path;";
@@ -76,6 +115,12 @@ public sealed class JobHistoryStore : IDisposable
{
lock (writeLock)
{
+ if (connection is null)
+ {
+ downloadCacheMem![destinationPath] = new DownloadCacheEntry(etag, sha256, sizeBytes);
+ return;
+ }
+
using var command = connection.CreateCommand();
command.CommandText = """
INSERT INTO DownloadCache (DestinationPath, ObjectKey, ETag, Sha256, SizeBytes, DownloadedUtc)
@@ -105,6 +150,22 @@ public sealed class JobHistoryStore : IDisposable
{
lock (writeLock)
{
+ if (connection is null)
+ {
+ if (!handledSet!.Add(jobId))
+ {
+ return false;
+ }
+
+ handledOrder!.Enqueue(jobId);
+ while (handledSet.Count > ProtocolDefaults.JobIdempotencyRetention && handledOrder.Count > 0)
+ {
+ handledSet.Remove(handledOrder.Dequeue());
+ }
+
+ return true;
+ }
+
using var command = connection.CreateCommand();
command.CommandText = "INSERT OR IGNORE INTO HandledJobs (JobId, AcceptedUtc) VALUES ($id, $utc);";
command.Parameters.AddWithValue("$id", jobId.ToString("D"));
@@ -117,6 +178,12 @@ public sealed class JobHistoryStore : IDisposable
{
lock (writeLock)
{
+ if (connection is null)
+ {
+ // Membership already recorded on accept; nothing else to track.
+ return;
+ }
+
using var command = connection.CreateCommand();
command.CommandText = "UPDATE HandledJobs SET CompletedUtc = $utc, State = $state WHERE JobId = $id;";
command.Parameters.AddWithValue("$utc", DateTimeOffset.UtcNow.ToString("O"));
@@ -130,6 +197,14 @@ public sealed class JobHistoryStore : IDisposable
public bool IsHandled(Guid jobId)
{
+ if (connection is null)
+ {
+ lock (writeLock)
+ {
+ return handledSet!.Contains(jobId);
+ }
+ }
+
using var command = connection.CreateCommand();
command.CommandText = "SELECT 1 FROM HandledJobs WHERE JobId = $id;";
command.Parameters.AddWithValue("$id", jobId.ToString("D"));
@@ -138,7 +213,7 @@ public sealed class JobHistoryStore : IDisposable
private void Prune()
{
- using var command = connection.CreateCommand();
+ using var command = connection!.CreateCommand();
command.CommandText = """
DELETE FROM HandledJobs WHERE JobId NOT IN (
SELECT JobId FROM HandledJobs ORDER BY AcceptedUtc DESC LIMIT $keep
@@ -148,5 +223,5 @@ public sealed class JobHistoryStore : IDisposable
command.ExecuteNonQuery();
}
- public void Dispose() => connection.Dispose();
+ public void Dispose() => connection?.Dispose();
}